/[cldoc]/cldoc/README
ViewVC logotype

Contents of /cldoc/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations)
Fri Nov 18 14:52:17 2005 UTC (8 years, 5 months ago) by ihatchondo
Branch: MAIN
Branch point for: CLDOC
Initial revision
1 ihatchondo 1.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    
18     should be added to the DWIM:
19     - links. how ?
20    
21     Unlike Albert (http://albert.sourceforge.net/) it does not allow
22     programmers to insert comments at the source code level which are
23     incorporated into the generated documentation.
24     Its goal was not to produce a LispDoc ala JavaDoc but to create a
25     simple and easy way to take advantage of the Lisp documentation
26     string. So instead of copying and pasting it in some commentary
27     section with extra special documentation tool markup stuff, the idea
28     was to find a elegant way of parsing the doc string.
29     To get started for documentation extraction see the
30     extract-documentation generic function.
31    
32     If you want your particular macro top-level form to be parsed, then
33     use the define-descriptor-handler macro. A basic use case of this
34     macro would be:
35     ;; Extracted from doc-cludg.lisp
36     (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
37     "string purger"
38     (setf (car form) 'cldoc::define-string-purger)
39     (values nil :restart (list (let ((*print-case* :upcase))
40     (macroexpand-1 form)))))
41    
42     In the above example the created handler will call macroexpand-1 on
43     the form and return the macro expansion for it to parsed. Instead if
44     this one could also have tried to handle by itself the
45     DEFINE-STRING-PURGER because it returns a DEFUN form. This would
46     have give:
47     (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
48     "string purger"
49     (setf (car form) 'cldoc::define-string-purger)
50     (let* ((*print-case* :upcase)
51     (macroexp (macroexpand-1 form))
52     (handler (car (find-descriptor-handler (car macroexp)))))
53     (when handler
54     (funcall handler form))))
55    
56     But in general a macro expansion result in more than one DEFUN form,
57     and thus, the multiple value return (nil :restart macro-expansion)
58     provides a more generic way to handle most cases. Another option
59     would have been be to create a new symbol-description subclass for
60     this form and to implement the form parsing in the handler. Here is
61     the code that has been used to generate CLUDG HTML documentation:
62    
63     ;;;; doc-cludg.lisp
64     (in-package :cldoc)
65    
66     ;; Special cldoc handler
67    
68     (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
69     "string purger"
70     (setf (car form) 'cldoc::define-string-purger)
71     (values nil :restart (list (let ((*print-case* :upcase))
72     (macroexpand-1 form)))))
73    
74     (cldoc::define-descriptor-handler DEFINE-LAMBDA-LIST-PURGER (form)
75     "lambda purger"
76     (setf (car form) 'cldoc::define-lambda-list-purger)
77     (values nil :restart (list (let ((*print-case* :upcase))
78     (macroexpand-1 form)))))
79    
80     ;; Extract doc.
81    
82     (cldoc:extract-documentation 'cldoc:html \"docu\"
83     '("package.lisp"
84     "cludg.lisp"
85     "cache-system.lisp"
86     "string-parser.lisp"
87     "html.lisp")
88     :table-of-contents-title
89     "Common Lisp Universal Documentation Generator")
90    
91     ;;;; End of doc-cludg.lisp
92    
93     This project has been mainly inspired by user-manual from Mark
94     Kantrowitz, the CSS file Gilbert Baumann made for McCLIM
95     documentation and of course by the JavaDoc tool from Sun.
96    

  ViewVC Help
Powered by ViewVC 1.1.5