Getting started CLDOC reads lisp source files and generates documentation using the selected output driver. Because it is performing some symbol package resolution it needs packages definition to be, at least loaded. A simple way to satisfy this condition is to load, such as require would, the systems to be documented before starting documentation extraction.

To get started with documentation extraction see the extract-documentation generic function:

 (cldoc:extract-documentation 'cludg:html "docu" 
    (asdf:find-system :cldoc)
    "Common Lisp Universal Documentation Generator")

If you want your particular macro top-level form to be parsed, then use the define-descriptor-handler macro. A basic use case of this macro would be:

 ;; Extracted from doc-cludg.lisp
 (cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)
   "string purger"
   (setf (car form) 'cldoc::define-string-purger)
   (values nil :restart (list (let ((*print-case* :upcase))
                                (macroexpand-1 form)))))

It currently has an HTML driver that generates XHTML 1.0 Strict. This HTML driver has some simple DWIM (Do What I Mean) capabilities using the doctree string parser facilities:

  • Recognize both indent and empty-line paragraph breaks.
  • Recognizes bulleted lists (the list grammar can be specified).
  • Recognizes code segments: by default each lines are prefixed with ';;; '.
  • Recognizes links: for standard URL's and symbol referencing. (see the :link-delimiters option of the doctree class).

Install We will assume that if you have gotten this far, it means that you have either extracted a tar file with everything in it, or checked out the files from some CVS repository.

  1. Start Lisp either from the shell or from Emacs
  2. (load "cldoc.asd")
    This command will load the system definition file containing system definitions for ASDF.
  3. (asdf:operate 'asdf:load-op :cldoc) This command will compile and load the source files in the right order.
  4. See cldoc:extract-documentation generic function documentation in the doc/html directory.
bottom corner