Common Lisp Package: CLOD

* Description CLOD is a tool for creating documentation for Common Lisp programs. CLOD examines a loaded package and writes information about all the symbols defined within that package, to a file. The output file is in /Org/ format. Org is a simple but powerful 'wiki-like' markup language that is understood by *Org-mode*, a powerful outliner, personal wiki and organiser that runs as a major mode within the /Emacs/ text editor. Org-mode can export org-format files to numerous other formats, including HTML, LaTeX, PDF, DocBook, and plain text. More information: - Emacs :: [[http://www.gnu.org/software/emacs]] (if you program CL, you won't need to be told what Emacs is) - Org mode :: [[http://orgmode.org/]] * Why use CLOD? - You can use org markup within docstrings (easy for humans to read) to create subsections, bulleted lists, hyperlinks within the document or to external URLs, etc. - Easy export to multiple file formats: text, HTML, DocBook, LaTeX -> PDF... - You can edit the output within Emacs, which is already the IDE of most Commn Lisp programmers. - If GraphViz is installed, automatically create a diagram illustrating the package's class hierarchy -- see http://www.graphviz.org/ - Org markup has many cool tricks. Some examples of useful things you can put in docstrings: - Include an entire file and format as plain text: : #+INCLUDE: "filename" quote - Include an entire file with common lisp syntax highlighting : #+INCLUDE: "filename.lisp" src lisp - Timestamps and datestamps: : {{{ modification-time(%r) }}} {{{modification-time(%r)}}} : {{{ date(%Y-%m-%d) }}} {{{date(%Y-%m-%d)}}} - Define text macros, use with ={{{macro(arg1,arg2)}}}= : #+MACRO: foo Replacement text $1 $2 - Embed any LaTeX code directly (no special markup needed) - Embed any HTML code (special markup needed) - Automatic syntax highlighting of source code examples in exported documents, eg: ;;; (defun hello (a &key b) ;;; (print "Hello, world!")) - Because CLOD works by introspection rather than parsing files, it copes effortlessly with unusual toplevel forms. Documentation generators that parse files usually won't be able to tell that your toplevel macro `=(defclass-easy ...)=' (or whatever) actually expands to a class definition. - For the same reason, CLOD avoids the problems with dependencies that can trouble other documentation generators (i.e. difficulties generating correct documentation unless you manually move things around in the source so that the doc generator finds things in the `right' order). - Easily change the global appearance of the document by specifying a cascading style sheet (/note: only affects HTML export from Org mode/) * Dependencies - ASDF: [[http://common-lisp.net/project/asdf/]] - Closer-MOP: [[http://common-lisp.net/project/closer/]] - Iterate: [[http://common-lisp.net/project/iterate/]] - CL-PPCRE: [[http://weitz.de/cl-ppcre/]] * How to use 1. Install CLOD somewhere ASDF can find it. 2. Load CLOD with =(asdf:oos 'asdf:load-op :clod)= 3. Load the package or packages for which you wish to produce documentation, eg: =(asdf:oos 'asdf:load-op :mypkg)= 4. Run =(clod:document-package :mypkg nil)= and you will see the documentation as a string, returned by [[document-package]]. 5. Run =(clod:document-package :mypkg "filename.org")= and the same documentation will be written to 'filename.org'. 6. Load filename.org into Emacs. Export to HTML with =M-x org-export=, or press C-c C-e to be presented with a menu of export options. * Writing the documentation All documentation produced by CLOD is obtained by /introspection/, i.e. by the running CL process examining itself. If a symbol has an associated docstring, it will be used by CLOD to produce the documentation for that symbol. Within documentation strings, you can use org mode markup. This is a simple, human-readable markup language similar to the type of markup used for wiki editing and forum posting. See the Org [[http://orgmode.org/manual/Markup.html][manual]] for more information. Also see the docstrings in the CLOD source code, which use org markup. Some special points to note: - Outline headings are used to structure org documents. These headings begin with one or more asterisks at the start of the line. Thus, if you want a large docstring to be divided into subsections, the heading for each subsection should be a line that starts with one or more asterisks (*), then a space, then the title of the heading. - These headings will automatically be correctly 'indented' for their location in the structure of the final document. The whole document is one outline, and any given docstring will usually be appearing 2 or 3 levels deep within that outline. However, CLOD finds all heading lines within docstrings and increases the number of asterisks appropriately. - An extra blank line is also automatically inserted after headings within docstrings, allowing you to save screen space in the docstring itself. - By default, many docstrings are inserted within a subsection titled 'Description'. However, if you don't want this to happen, but rather want the docstring to define its own heading names, make sure that the very first thing in the docstring is a heading (straight after the opening quote). (Note for mmm-mode users (see below): if the docstring starts with '###' to signal that it is in fact a docstring, CLOD will skip the hashes before looking to see if the string starts with a heading.) So ="###* Arguments ..."= will work in that case. - Some symbol names used by common lisp can conflict with the markup used by org mode. For example, =*global-variable*=: asterisks are interpreted by org mode as signifying bold text. CLOD catches these in headings and auto-generated documentation, but not within doc strings, where you will need to surround the offending symbol with =equals signs=. - *Hyperlinks* are created using : [[double square brackets]] Any text surrounded by these brackets will link to the same text (case insensitive) surrounded by =<<double angle brackets>>=. CLOD uses this to define hyperlinks for all symbols in the package. Every symbol MYSYMBOL has: 1. A hyperlink =<<function MYSYMBOL>>= if MYSYMBOL is a function, =<<variable MYSYMBOL>>= if it is a global variable, etc. 2. A hyperlink =<<MYSYMBOL>>= which will either link to MYSYMBOL's documentation, or to a 'disambiguation section' if the same symbol has multiple meanings (eg there is both a function and a variable called MYSYMBOL). - Org mode has the ability to use Emacs' font-lock mode to produce source code snippets that are correctly syntax highlighted for any major mode. To use this normally requires surrounding the code with =#+BEGIN_SRC ... #+END_SRC=. CLOD provides a shortcut: Any lines within docstrings that begin with three semicolons =;;;= are assumed to be example lisp source code. The first 3 semicolons are removed and the rest of the line is syntax highlighted. * Combining org mode and common lisp mode in a single Emacs buffer You can use org mode markup within docstrings, but you can't see the effects of the markup until you export the documentation to org using CLOD. You also don't get access to org's support for automatic formatting of bulleted lists as you write, or the fantastic support for writing tables, or hyperlinks that you can click with the mouse, or .... What if you could use all the goodness of Org, while editing docstrings in your lisp source code? You can. This section explains how. 1. Download and install nXhtml, an emacs package that contains code allowing multiple major modes to be active in a single buffer. http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl 2. Add the code in `mmm-clod.el' to your .emacs file. Make sure you change the mmm-mode directory to the directory where you installed mmm-mode. 3. Restart emacs. Load a lisp source file. All documentation strings should appear with a coloured background, and when you move the cursor inside them, you will see 'Lisp[Org]' on the modeline. 4. If not everything is highlighting correctly, or if you write a new docstring and org does not activate within it, press control-` to 'refresh' mmm-mode. Not everything works: expanding and collapsing headings fails, and clicking the mouse elsewhere within the doc string often causes problems. But overall the two modes work together surprisingly well. MMM-mode recognises the following things as doc strings: 1. Any string that emacs fontifies using 'font-lock-doc-face'. (in other words, font-lock mode must be active.) 2. Any string inside the form '=(:documentation STRING)='. 3. Finally, any string whose first three characters are '###'. Since lines beginning with a hash are interpreted as comments by org mode, these characters will disappear when you export your document to HTML or other formats. * Example docstring Here is the docstring for [[document-package]]. It illustrates the use of headings, bulleted lists, definition lists, =code=, *bold* and /italic/ markup, hyperlinks to other definitions, and syntax highlighting of lisp source code examples. : "* Arguments : - PKG :: A package name or package object. : - FILE/STREAM :: A string (filename), stream object, or =NIL=. : - AUTO-LINKS :: Boolean. : - LINES-BETWEEN-SECTIONS :: Boolean. : - BRIEF-METHODS :: Boolean. : - STYLE-SHEET :: A string. : - TITLE :: A string. : - AUTHOR :: A string. : - EMAIL :: A string. : * Returns : A string, or nil. : * Description : Produce documentation for the package =PKG=. : : The documentation's destination depends on the value of =FILE/STREAM=: : - =STRING=: documentation is written to the file named by the string. : - =STREAM=: documentation is written to the already existing stream. : - =NIL=: documentation is written to a string, which is then returned by : this function. : : Explanation of optional arguments: : - =TITLE=, =AUTHOR= and =EMAIL= specify the document title, the name of : the author, and the email address of the author. : - If =AUTO-LINKS= is non-nil, *all* occurrences of symbol names within the : text of docstrings will be interpreted as hyperlinks, regardless of : whether they are marked up as hyperlinks. : - If LINES-BETWEEN-SECTIONS is nil, do not output a horizontal line before : each new section of documentation. : - If BRIEF-METHODS is nil, document individual methods with their own : sections, just like functions and generic functions. Most people put : 'method' documentation in the docstrings of their generic functions, but : if you set docstrings for individual methods then set this to nil. : - =STYLE-SHEET= specifies the name of a /Cascading Style Sheet/ (.CSS) file : which will be used as the style for the document if you export it : to HTML from org mode." : : * Example : ;;; (clod:document-package :mypkg "mypkg-doc.org" : ;;; :style-sheet "swiss.css" :title "My Package" : ;;; :author "F. B. Quux" :email "quux@gmail.com") : : * See also : - [[document-packages]]

README:

FUNCTION

Public

DOCUMENT-PACKAGE (PKG FILE/STREAM &KEY (AUTO-LINKS NIL) (LINES-BETWEEN-SECTIONS T) (BRIEF-METHODS T) (INTERNAL-SYMBOLS? T) (CLASS-DIAGRAM NIL) (STYLE-SHEET NIL) (TITLE NIL) (AUTHOR *DOCUMENT-AUTHOR*) (EMAIL *DOCUMENT-EMAIL*))

* Arguments - PKG :: A package name or package object. - FILE/STREAM :: A string (filename), stream object, or =NIL=. - AUTO-LINKS :: Boolean. - LINES-BETWEEN-SECTIONS :: Boolean. - BRIEF-METHODS :: Boolean. - INTERNAL-SYMBOLS :: Boolean. - CLASS-DIAGRAM :: Boolean. - STYLE-SHEET :: A string. - TITLE :: A string. - AUTHOR :: A string. - EMAIL :: A string. * Returns A string, or nil. * Description Produce documentation for the package =PKG=. The documentation's destination depends on the value of =FILE/STREAM=: - =STRING=: documentation is written to the file named by the string. - =STREAM=: documentation is written to the already existing stream. - =NIL=: documentation is written to a string, which is then returned by this function. Explanation of optional arguments: - =TITLE=, =AUTHOR= and =EMAIL= specify the document title, the name of the author, and the email address of the author. - =STYLE-SHEET= specifies the name of a Cascading Style Sheet (.CSS) file which will be used as the style for the document if you export it to HTML from org mode. - If =AUTO-LINKS= is non-nil, *all* occurrences of symbol names within the text of docstrings will be interpreted as hyperlinks, regardless of whether they are marked up as hyperlinks. - If =LINES-BETWEEN-SECTIONS= is nil, do not output a horizontal line before each new section of documentation. - If =BRIEF-METHODS= is nil, document individual methods with their own sections, just like functions and generic functions. Most people put 'method' documentation in the docstrings of their generic functions, but if you set docstrings for individual methods then set this to nil. - If =INTERNAL-SYMBOLS?= is non-nil, document both internal and external (exported) symbols. If nil, only document external symbols. - If =CLASS-DIAGRAM= is non-nil, create a section after the toplevel package description, containing a description of the package hierarchy in the form of a GraphViz 'dot' diagram (see http://www.graphviz.org/). * Example ;;; (clod:document-package :mypkg "mypkg-doc.org" ;;; :style-sheet "swiss.css" :title "My Package" ;;; :author "F. B. Quux" :email "quux@gmail.com") * See also - [[document-packages]]

DOCUMENT-PACKAGES (PACKAGES FILE/STREAM &KEY (AUTO-LINKS NIL) (LINES-BETWEEN-SECTIONS T) (BRIEF-METHODS T) (INTERNAL-SYMBOLS? T) (CLASS-DIAGRAM NIL) (STYLE-SHEET NIL) (TITLE *DOCUMENT-TITLE*) (AUTHOR *DOCUMENT-AUTHOR*) (EMAIL *DOCUMENT-EMAIL*))

* Arguments - PACKAGES :: A list of package objects, or symbols naming packages. - FILE/STREAM :: A string (filename), stream object, or =NIL=. Other arguments are the same as for [[document-package]]. * Returns A string, or nil. * Description Produces documentation for all the packages in =PACKAGES=, within a single file. See [[document-package]] for more details.

Private

ACCESSIBLE-SYMBOLS (SYMS ACCESS PKG)

* Arguments - SYMS :: A list of symbols. - ACCESS :: One of the keywords =:INTERNAL= or =:EXTERNAL=. - PKG :: A package object. * Returns A list of symbols. * Description Given a list of symbols, SYMS, returns the subset of SYMS whose accessibility in PKG matches ACCESS.

AMPERSAND-SYMBOL? (SYM)

Does the symbol SYM begin with an ampersand, such as &ANY, &REST and so on?

DECLARED-SPECIAL-P (SYMBOL)

Returns true if SYMBOL is declared special.

DOCUMENT-PACKAGE-CONTENTS (PKG &OPTIONAL (ACCESSIBILITIES *ACCESSIBILITIES*))

* Arguments - PKG :: A package name or package object. - ACCESSIBILITIES :: A list containing zero or more of the symbols =:external= or =:internal=. * Return Value Ignored. * Description Writes documentation for all symbols contained within the package =PKG=. Does not write documentation for the actual package object.

ENTITY->STRING (ENTITY)

* Arguments - ENTITY :: An [[=entity=]]. * Returns A string. * Description Given an entity, returns a string that can be used to describe that entity type in human-readable form, in headings, etc.

ENTITY->TAG (ENTITY)

* Arguments - ENTITY :: An [[=entity=]]. * Returns A string. * Description Given an entity, returns a string that can be used as a *tag* denoting that entity type in org mode. See [[http://orgmode.org/manual/Tags.html]] for information on tags.

FUNCTION-LAMBDA-LIST (FUNC)

* Arguments - FUNC :: A function object, macro object, generic function object, or a symbol bound to a function or macro. * Returns Two values: - The lambda list of the function name or function object, FUNC; or nil if the function takes no arguments or the lambda list cannot be retrieved. - A boolean value -- T if a lambda list (even an empty one) was found, NIL otherwise. * Description Returns the lambda list associated with the definition of the function or macro =FUNC=. For example, the lambda list for the common lisp function =FIND= is the list: : (ITEM SEQUENCE &KEY :FROM-END :TEST :TEST-NOT :START :END :KEY)

FUNCTION-NAME (FN)

* Arguments - FN :: A function, generic function or macro object. * Returns The name of a function or macro, or nil. * Description Returns the official 'name' bound to the function, macro, or generic function object FN. Returns =NIL= if no name can be found or if the function is anonymous (=lambda=).

HTML-SAFE-STRING (STR)

* Arguments - STR :: A string. * Returns A string. * Description Given a string which is intended as a link target, return a copy in which we remove or alter any unsafe characters that will stop the link working properly when the document is exported to HTML. * See Also - [[*unsafe-html-chars*]]

LIST->STRING-WITH-COMMAS (LS)

* Arguments - LS :: A list of values. * Returns A string. * Description Given a list of arbitrary values, returns a string consisting of the printed representations of those values, separated by commas and spaces. * Example ;;; (list->string-with-commas '(a b 123)) ;;; ;;; => "A, B, 123"

LIST-ALL-DIRECT-SLOTS (CLASSES)

* Arguments - CLASSES :: A list of class objects. * Return Value A list of SLOT-DEFINITION instances. * Description Return a list of all the direct SLOT-DEFINITION instances defined for all the classes in CLASSES.

LIST-ALL-INDIRECT-SLOTS (CLASSES)

* Arguments - CLASSES :: A list of class objects. * Return Value A list of SLOT-DEFINITION instances. * Description Return a list of all the indirect SLOT-DEFINITION instances defined for all the classes in CLASSES.

LIST-ALL-SLOT-ACCESSORS (CLASSES)

* Arguments - CLASSES :: A list of class objects. * Return Value A list of generic functions. * Description Return a list of all the reader and writer generic functions associated with all the slots of the classes in CLASSES.

MAKE-SPECIALISED-LAMBDA-LIST (TERMS SPECS)

* Arguments - TERMS :: Unspecialised version of the lambda list (a list of symbols). - SPECS :: List of class names on which a particular method is specialised. * Returns A list. * Description Given an unspecialised lambda list and a list of specialisers, reconstruct the specialised lambda list and return it.

MAKE-TARGET (SYM &OPTIONAL ENTITY)

Returns a string that will be interpreted by org as a destination for hyperlinks to =SYM=.

MAP-LIST (FUNCTION LIST)

Map over proper and not proper lists.

ORG-SAFE-SYMBOL (SYM)

* Arguments - SYM :: A symbol. * Return Value A string. * Description Given the symbol SYM, return a string that represents SYM in a form that is human-readable and where org will not be confused by any characters that might represent markup instructions.

SIMPLE-TYPE? (SYM)

* Arguments - SYM :: A symbol. * Return Value Boolean. * Description Returns =T= if =SYM= names a non-class type, such as can be defined by [[deftype]].

STR+ (&REST STRINGS)

* Arguments - STRINGS :: One or more strings. * Returns A string. * Description Returns the concatenation of all supplied strings. Shorthand for =(concatenate 'string . STRINGS)=.

STRING-STARTS-WITH? (STR START)

* Arguments - STR :: A string. - START :: A smaller string. * Returns Boolean. * Description Predicate. Does the string =STR= start with the string =START=?

SYMBOL-ACCESSIBILITY (SYM &OPTIONAL (PKG *PACKAGE*))

* Arguments - SYM :: A symbol. - PKG :: A package. * Returns One of =:inherited, :internal, :external= or =nil=. * Description Returns a symbol describing how the symbol =SYM= is accessible within the package =PKG=. If =SYM= is exported by =PKG= then the function returns =:external=, and so on.

TYPE->STRING (TYP)

Returns a simple string representation of the type specifier =TYP=.

USES-FOR-SYMBOL (SYM)

* Arguments - SYM :: A symbol. * Return Value A list of [[=entity=]] values. * Description Given a symbol =SYM=, return a list of entity values, describing the different meanings/bindings of =SYM= within its home package.

WORD-WRAP (TEXT &KEY (WIDTH 80) RESPECT-NEWLINES RESPECT-HYPHENS EXCLUDE-START-CHAR EXCLUDE-END-CHAR)

* Arguments - TEXT :: A string. - WIDTH :: An integer. The maximum length of lines once TEXT is wrapped. Default is 80. - RESPECT-NEWLINES :: Boolean. Should newline characters within the string be treated as unbreakable? (=NIL=) - RESPECT-HYPHENS :: Boolean. Should we refrain from breaking hyphenated words? (=NIL=) - EXCLUDE-START-CHAR :: A character, or nil. - EXCLUDE-END-CHAR :: A character, or nil. * Return Value A list of strings. * Description Given a string =TEXT=, breaks the string into a series of smaller strings, none of which is longer than =WIDTH=. Returns the list of strings. If =EXCLUDE-START-CHAR= and =EXCLUDE-END-CHAR= are supplied, those characters will be treated as demarcating sections of the string whose length is to be ignored (treated as zero).

WRAP-AND-WRITE (FMT &REST ARGS)

Wraps the result of =(FORMAT NIL FMT . ARGS)=, then writes the resulting paragraph to output.

WRAP-AND-WRITE-CODE (FMT &REST ARGS)

Wraps the result of =(FORMAT NIL FMT . ARGS)=, then writes the resulting paragraph with 'literal' or 'source code block' markup.

WRITE-BULLET-POINT (FMT &REST ARGS)

Writes a the result of =(FORMAT NIL FMT . ARGS)= as a point within an active bulleted list.

WRITE-CHAPTER (SYMLIST ENTITY TITLE)

* Arguments - SYMLIST :: A list of symbols. - ENTITY :: An [[=entity=]]. - TITLE :: A string. * Return Value Ignored. * Description Writes the section of the document which describes all entities of type =ENTITY=. =SYMLIST= should be a list of all the symbols that name such entities.

WRITE-CLASS-HIERARCHY (CLASSES)

* Arguments - CLASSES :: A list of CLASS objects. * Returns Ignored. * Description Writes the inheritance tree of CLASSES as a GraphViz diagram, using the DOT language. External parent classes are also included. See http://www.graphviz.org/ for details of the GraphViz language.

WRITE-DISAMBIGUATION (SYM USES)

Writes a section providing disambiguating links for the symbol SYM, which is bound in multiple namespaces.

WRITE-DOCSTRING (STR &KEY (LEVELS *HEADING-LEVEL*) (DEFAULT Not documented.))

* Arguments - STR :: A docstring. - LEVELS :: How many levels deep in the outline is this docstring? - DEFAULT :: A string. Default text, used if =STR= is =NIL=. * Return Value Ignored. * Description Writes the docstring STR to the document. Before doing this, processes the docstring to: - Demote headings - Make all hyperlinks safe for org mode and HTML export - Convert lines beginning with ';;;' to syntax-highlighting markup.

WRITE-DOCSTRING-SECTION (TITLE DOCSTR)

Writes the documentation string DOCSTR within its own subsection.

WRITE-HEADING (TITLE)

Writes a section heading entitled =TITLE=.

WRITE-INDEX (PKG &OPTIONAL (ACCESSIBILITIES (LIST INTERNAL EXTERNAL)))

Writes a section containing an alphabetical index of all the symbols in the package PKG.

WRITE-LAMBDA-LIST-SECTION (SYM)

Writes a section describing the lambda list of the function or macro SYM.

WRITE-LIST-AS-PARAGRAPH (LS)

LS is a list of items. Writes all the items in LS to output as a single wrapped paragraph. Individual items are separated by commas.

WRITE-OUT (FMT &REST ARGS)

Writes the result of =(FORMAT NIL FMT . ARGS)= to output.

WRITE-PREAMBLE

* Arguments None. * Return Value Ignored. * Description Writes some org instructions, intended to be placed at the start of the document. These specify the document's author, title, and set some export options.

Undocumented

DOCPKG (&REST PACKAGES)

ENSURE-GENERIC-FUNCTION (FUN-NAME &REST ALL-KEYS &KEY ENVIRONMENT DEFINITION-SOURCE &ALLOW-OTHER-KEYS)

FIND-PKG (PKG)

FIND-SYM (SYM &OPTIONAL (PKG (PACKAGE-NAME *PACKAGE*)))

REPLACE-STRINGS-WITH-SYMBOLS (TREE)

WRITE-COLOPHON

WRITE-LINES (&REST LINES)

MACRO

Private

DO-OWN-SYMBOLS ((VAR PKG) &BODY BODY)

* Arguments - VAR :: symbol naming a variable that will be bound to each symbol in turn. - PKG :: a package. * Description Iterate through all the non-imported symbols in the package =PKG=. =BODY= is executed once for each such symbol, with =VAR= bound to each symbol in turn.

WRITE-INDENTED ((INDENT) &BODY BODY)

* Arguments - INDENT :: An integer. * Return Value Ignored. * Description All text that is written within the body of the form will be indented a further =INDENT= spaces from the left margin.

WRITING-BULLETED-LIST (&BODY BODY)

All output within the body of a form is assumed to be within a bulleted list.

WRITING-SECTION ((TITLE) &BODY BODY)

Wraps all output within the body of the form in its own section.

WRITING-SECTION-FOR-SYMBOL ((ENTITY SYM) &BODY BODY)

Wraps all output within the body of the form in its own section. The title of the section describes the entity of type =ENTITY= that is bound to the symbol =SYM=.

Undocumented

DEFGENERIC (&WHOLE FORM NAME (&REST ARGS) &BODY OPTIONS)

DEFMETHOD (&WHOLE FORM NAME &BODY BODY &ENVIRONMENT ENV)

GENERIC-FUNCTION

Private

DOCUMENT (SYM DOCTYPE)

* Arguments - SYM :: a symbol. - DOCTYPE :: an [[=entity=]]. * Returns: Ignored. * Description Writes a section documenting the [[=entity=]] named =SYM= which is of entity type =DOCTYPE=.

VARIABLE

Private

*ACCESSIBILITIES*

List of one or both of the keywords =:EXTERNAL= and =:INTERNAL=. Only symbols whose accessibility matches one of the keywords in the list will be documented.

*ALPHABET*

List of uppercase letters (characters) from A to Z.

*AMBIGUITIES*

Hash table created during package documentation. Stores all symbols which have multiple 'meanings' within the package.

*BRIEF-METHODS*

If true, most documentation for methods is assumed to be found in the docstring for their generic function. A generic function's methods are therefore described in a very brief format (bulleted list). If false, each method receives its own section, just like other functions.

*CLASS-DIAGRAM*

If true, creates a section describing the package class hierarchy as a 'dot' diagram, which can be fed to the GraphViz program (if installed) to create a visual representation of the hierarchy.

*CLASS-DIAGRAM-COUNTER*

Counter that is incremented by one each time a class diagram is created. Used to construct the name of the class diagram PNG file that is produced by `dot'.

*CLOD-VERSION-STRING*

String containing CLOD's version number.

*DOCUMENT-AUTHOR*

The author of the document. A string.

*DOCUMENT-EMAIL*

The email address of the document's author. A string.

*DOCUMENT-STYLE-SHEET*

Filename of the Cascading Style Sheet (.css) file to use if the document produced by CLOD is exported to HTML.

*DOCUMENT-TITLE*

The title of the document. A string.

*HEADING-CHAR*

Character used at the beginning of lines to signify headings and subheadings. Should not be changed.

*HEADING-LEVEL*

Number of levels 'deep' within the outline. Used when creating headings for sections and subsections.

*HYPERSPEC-ROOT*

URL or directory where the Hyperspec is found. Not currently implemented.

*LEFT-MARGIN*

Width of the current 'left margin', in spaces.

*LINE-WIDTH*

Width to which paragraphs are wrapped, in characters.

*LINES-BETWEEN-SECTIONS*

If true, sections of the document will be separated by horizontal lines.

*OUT*

Global variable that is bound to the output stream used by CLOD while writing documentation.

*UNSAFE-HTML-CHARS*

List of characters which are unsafe within HTML links and anchors, and which need to be converted to a safe representation. See also: [[html-safe-string]].

CLASS

Private

ANIMAL

dummy class, created to illustrate CLOD's ability to produce class diagrams using GraphViz.

BIRD

dummy class, created to illustrate CLOD's ability to produce class diagrams using GraphViz.

CAT

dummy class, created to illustrate CLOD's ability to produce class diagrams using GraphViz.

DOG

dummy class, created to illustrate CLOD's ability to produce class diagrams using GraphViz.

HAWK

dummy class, created to illustrate CLOD's ability to produce class diagrams using GraphViz.

MAMMAL

dummy class, created to illustrate CLOD's ability to produce class diagrams using GraphViz.

Undocumented

STANDARD-CLASS

STANDARD-GENERIC-FUNCTION

STANDARD-METHOD