/[cldoc]/cldoc/src/package.lisp
ViewVC logotype

Contents of /cldoc/src/package.lisp

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.6 - (show annotations)
Mon Jan 9 22:32:12 2006 UTC (8 years, 3 months ago) by ihatchondo
Branch: MAIN
CVS Tags: HEAD
Changes since 1.5: +1 -1 lines
removed non ascii space char.
1 ;;; -*- Mode: Lisp; Syntax: Common-Lisp; Package: CLUDG; -*-
2 ;;; $Id: package.lisp,v 1.6 2006/01/09 22:32:12 ihatchondo Exp $
3 ;;; ---------------------------------------------------------------------------
4 ;;; Title: Common Lisp Universal Documentation Generator package definition
5 ;;; Created: 2005 10 23 12:30
6 ;;; Author: Iban Hatchondo <hatchond@yahoo.fr>
7 ;;; ---------------------------------------------------------------------------
8 ;;; (c) copyright 2005 by Iban Hatchondo
9
10 ;;; The authors grant you the rights to distribute
11 ;;; and use this software as governed by the terms
12 ;;; of the Lisp Lesser GNU Public License
13 ;;; (http://opensource.franz.com/preamble.html),
14 ;;; known as the LLGPL.
15
16 (common-lisp:in-package :common-lisp-user)
17
18 (defpackage "CLDOC"
19 ;; form minion (on of the #lisp irc bot):
20 ;; CLUDG: Crisp Lacunose Unkirk Dactyliomancy Geneticist
21 ;; was the original name.
22 (:nicknames cludg)
23 (:use common-lisp)
24 (:export
25 #:*constructor-control-string* #:*predicate-control-string*
26 #:*printer-control-string*
27 #:*class-inheritence* #:*condition-inheritence*
28 #:*struct-inheritence* #:*slot-reader-control-string*
29 #:*slot-writer-control-string* #:*slot-accessor-control-string*
30 #:+html-doctype+ #:+default-charset+ #:+default-link-delimiters+
31 #:+default-section-prefix+ #:+default-code-prefix+ #:+default-section-names+
32 #:define-descriptor-handler
33 #:find-descriptor-handler
34 #:register-output-type
35 #:find-output-type
36 #:grok-new-lines
37 #:define-string-purger
38 #:define-lambda-list-purger
39 ;; functions, class & protocol.
40 #:driver
41 #:html
42 #:text
43 #:extract-documentation
44 #:dformat
45 #:dformat-documentation
46 ;; cache system.
47 #:meta-descriptor
48 #:meta-descriptor-href #:meta-descriptor-desc #:meta-descriptor-file
49 #:clear-cache #:cache-descriptor #:initialise-cache
50 #:lookup-meta-descriptor #:lookup-meta-descriptor-anchor
51 #:lookup-meta-descriptor-href #:cache-meta-descriptors
52 ;; documentation string parsing utilities
53 #:doctree
54 #:doctree-tree
55 #:bulleted-list
56 #:last-list-item
57 #:add-to-bulleted-list-item
58 #:add-to-bulleted-list
59 #:handle-string
60 #:add-to-paragraph
61 #:paragraph-handle-line
62 #:add-to-code-block
63 #:create-doctree-from-string
64 #:starts-with
65 #:start-para-p
66 #:with-tree-loop)
67 (:documentation "Common Lisp Universal Documentation Generator.
68
69 CLDOC reads lisp source files and generates documentation using the
70 selected output driver. Because it is performing some symbol package
71 resolution it needs packages definition to be, at least loaded.
72 A simple way to satisfy this condition is to load, such as require would,
73 the systems to be documented before starting documentation extraction.
74
75 It currently has an HTML driver that generates XHTML 1.0 Strict.
76 This HTML driver has some simple DWIM (Do What I Mean) capabilities
77 using the doctree string parser facilities:
78 - Recognize both indent and empty-line paragraph breaks.
79 - Recognizes bulleted lists (the list grammar can be specified).
80 - Recognizes code segments: by default each lines are prefixed with ';;; '.
81 - Recognizes links: two kinds of hyper link are possible both using the
82 same grammar:
83 [opening-char(defun|defclass|defgeneric|...) symbol-name closing-char] |
84 [opening-char(http://|ftp://)address closing-char].
85 opening-char and closing char can be customized, see the :link-delimiters
86 option of {defclass cldoc:doctree} .
87
88 ;;; (defun foo ()
89 ;;; \"-- URL's: {http://common-lisp.net/cldoc}
90 ;;; -- Common Lisp symbols: {defgeneric cldoc:extract-documentation}\"
91 ;;; (values))
92
93 will produce:
94 -- URL's: {http://common-lisp.net/cldoc}
95 -- Common Lisp symbols: {defgeneric cldoc:extract-documentation}
96
97 Unlike Albert, {http://albert.sourceforge.net} , it does not allow
98 programmers to insert comments at the source code level which are
99 incorporated into the generated documentation.
100 Its goal was not to produce a LispDoc ala JavaDoc but to create a simple
101 and easy way to take advantage of the Lisp documentation string. So instead
102 of copying and pasting it in some commentary section with extra special
103 documentation tool markup stuff, the idea was to find a elegant way of
104 parsing the doc string.
105
106 To get started for documentation extraction see the extract-documentation
107 generic function.
108
109 If you want your particular macro top-level form to be parsed, then use the
110 define-descriptor-handler macro. A basic use case of this macro would be:
111 ;;; ;; Extracted from doc-cludg.lisp
112 ;;; (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
113 ;;; \"string purger\"
114 ;;; (setf (car form) 'cldoc::define-string-purger)
115 ;;; (values nil :restart (list (let ((*print-case* :upcase))
116 ;;; (macroexpand-1 form)))))
117
118 In the above example the created handler will call macroexpand-1 on the
119 form and return the macro expansion for it to parsed. Instead if this one
120 could also have tried to handle by itself the DEFINE-STRING-PURGER because
121 it returns a DEFUN form. This would have give:
122 ;;; (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
123 ;;; \"string purger\"
124 ;;; (setf (car form) 'cldoc::define-string-purger)
125 ;;; (let* ((*print-case* :upcase)
126 ;;; (macroexp (macroexpand-1 form))
127 ;;; (handler (car (find-descriptor-handler (car macroexp)))))
128 ;;; (when handler
129 ;;; (funcall handler form))))
130
131 But in general a macro expansion result in more than one DEFUN form, and
132 thus, the multiple value return (nil :restart macro-expansion) provides
133 a more generic way to handle most cases.
134 Another option would have been be to create a new symbol-description
135 subclass for this form and to implement the form parsing in the handler.
136
137 Here is the code that has been used to generate CLDOC HTML documentation:
138 ;;; (in-package :cldoc)
139 ;;;
140 ;;; ;; Special cldoc handler
141 ;;;
142 ;;; (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
143 ;;; \"string purger\"
144 ;;; (setf (car form) 'cldoc::define-string-purger)
145 ;;; (values nil :restart (list (let ((*print-case* :upcase))
146 ;;; (macroexpand-1 form)))))
147 ;;;
148 ;;; (cldoc::define-descriptor-handler DEFINE-LAMBDA-LIST-PURGER (form)
149 ;;; \"lambda purger\"
150 ;;; (setf (car form) 'cldoc::define-lambda-list-purger)
151 ;;; (values nil :restart (list (let ((*print-case* :upcase))
152 ;;; (macroexpand-1 form)))))
153 ;;;
154 ;;; ;; Extract doc.
155 ;;;
156 ;;; (cldoc:extract-documentation 'cldoc:html \"docu\"
157 ;;; (asdf:find-system :cldoc)
158 ;;; :table-of-contents-title
159 ;;; \"Common Lisp Universal Documentation Generator\")
160
161 This project has been mainly inspired by user-manual from Mark Kantrowitz,
162 the CSS file Gilbert Baumann made for McCLIM documentation and of course
163 by the JavaDoc tool from Sun."))

  ViewVC Help
Powered by ViewVC 1.1.5