/[cldoc]/cldoc/README
ViewVC logotype

Contents of /cldoc/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (show annotations)
Sun Jan 8 17:19:31 2006 UTC (8 years, 3 months ago) by ihatchondo
Branch: MAIN
Changes since 1.1: +2 -3 lines
Link support added.
1 Common Lisp Universal Documentation Generator.
2
3 CLDOC reads lisp source files and generates documentation using the
4 selected output driver. Because it is performing some symbol package
5 resolution it needs packages definition to be, at least loaded.
6 A simple way to satisfy this condition is to load, such as require
7 would, the systems to be documented before starting documentation
8 extraction.
9
10 It currently has an HTML driver that generates XHTML 1.0 Strict.
11 This HTML driver has some simple DWIM (Do What I Mean) capabilities
12 using the doctree string parser facilities:
13 - Recognize both indent and empty-line paragraph breaks.
14 - Recognizes bulleted lists (the list grammar can be specified).
15 - Recognizes code segments: by default each lines are prefixed with
16 ';;; '.
17 - Recognizes links: for standard URL's and symbol referencing.
18 (see the :link-delimiters option of the doctree class).
19
20 Unlike Albert (http://albert.sourceforge.net/) it does not allow
21 programmers to insert comments at the source code level which are
22 incorporated into the generated documentation.
23 Its goal was not to produce a LispDoc ala JavaDoc but to create a
24 simple and easy way to take advantage of the Lisp documentation
25 string. So instead of copying and pasting it in some commentary
26 section with extra special documentation tool markup stuff, the idea
27 was to find a elegant way of parsing the doc string.
28 To get started for documentation extraction see the
29 extract-documentation generic function.
30
31 If you want your particular macro top-level form to be parsed, then
32 use the define-descriptor-handler macro. A basic use case of this
33 macro would be:
34 ;; Extracted from doc-cludg.lisp
35 (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
36 "string purger"
37 (setf (car form) 'cldoc::define-string-purger)
38 (values nil :restart (list (let ((*print-case* :upcase))
39 (macroexpand-1 form)))))
40
41 In the above example the created handler will call macroexpand-1 on
42 the form and return the macro expansion for it to parsed. Instead if
43 this one could also have tried to handle by itself the
44 DEFINE-STRING-PURGER because it returns a DEFUN form. This would
45 have give:
46 (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
47 "string purger"
48 (setf (car form) 'cldoc::define-string-purger)
49 (let* ((*print-case* :upcase)
50 (macroexp (macroexpand-1 form))
51 (handler (car (find-descriptor-handler (car macroexp)))))
52 (when handler
53 (funcall handler form))))
54
55 But in general a macro expansion result in more than one DEFUN form,
56 and thus, the multiple value return (nil :restart macro-expansion)
57 provides a more generic way to handle most cases. Another option
58 would have been be to create a new symbol-description subclass for
59 this form and to implement the form parsing in the handler. Here is
60 the code that has been used to generate CLUDG HTML documentation:
61
62 ;;;; doc-cludg.lisp
63 (in-package :cldoc)
64
65 ;; Special cldoc handler
66
67 (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
68 "string purger"
69 (setf (car form) 'cldoc::define-string-purger)
70 (values nil :restart (list (let ((*print-case* :upcase))
71 (macroexpand-1 form)))))
72
73 (cldoc::define-descriptor-handler DEFINE-LAMBDA-LIST-PURGER (form)
74 "lambda purger"
75 (setf (car form) 'cldoc::define-lambda-list-purger)
76 (values nil :restart (list (let ((*print-case* :upcase))
77 (macroexpand-1 form)))))
78
79 ;; Extract doc.
80
81 (cldoc:extract-documentation 'cldoc:html \"docu\"
82 '("package.lisp"
83 "cludg.lisp"
84 "cache-system.lisp"
85 "string-parser.lisp"
86 "html.lisp")
87 :table-of-contents-title
88 "Common Lisp Universal Documentation Generator")
89
90 ;;;; End of doc-cludg.lisp
91
92 This project has been mainly inspired by user-manual from Mark
93 Kantrowitz, the CSS file Gilbert Baumann made for McCLIM
94 documentation and of course by the JavaDoc tool from Sun.
95

  ViewVC Help
Powered by ViewVC 1.1.5