Changes between Initial Version and Version 1 of CCLDocOverview

Timestamp:

Oct 13, 2014, 10:56:18 PM (7 years ago)

Author:

rme

Comment:

--

CCLDocOverview

@@ +1 @@
+[[PageOutline]]
+
+= CCLDoc Documentation system =
+== Overview == #overview
+CCLDoc is a system for creating lisp documentation.  It uses s-expressions to represent document
+structure, markup, cross references, and contents.  It has a small number of basic operators, supports
+macros for syntax extensions, and supports a simple syntax for embedding expressions in strings for
+added convenience.
+
+All the symbols referenced in this section without an explicit package prefix are external
+in the `:CCLDOC` package.
+
+A CCLDoc document definition is processed by the [#f_load-document LOAD-DOCUMENT] function to produce
+a [#c_document DOCUMENT] object.  This object can then be processed to create other formats.
+Currently three output formats are supported: [#f_output-docbook OUTPUT-DOCBOOK] generates
+[http://docbook.org docbook] output, [#f_output-tracwiki OUTPUT-TRACWIKI] generates [http://trac.edgewall.org/wiki Trac Wiki]
+output, and [#f_output-ccldoc OUTPUT-CCLDOC] generates CCLDoc source output.
+
+By having a small number of relatively high-level operators, CCLDoc allows the creation of
+consistently formatted documents even when written by many different people over extended
+periods of time.  Additionally, the simple document model enables longevity by making it easy to
+upgrade and change the back-end tools used to implement the final formatting, without having
+to convert the document source
+
+
+== Source Syntax == #source-syntax
+A CCLDoc document is represented by an s-expression with the usual semantics: when the
+s-expression is a `CONS`, the `CAR` of each form is a CCLDoc operator and the
+`CDR` contains the arguments. The s-expression can also be a string in which case it
+has additional internal structure as described in [#string-syntax String Syntax]. Finally, for
+convenience, an uninterned symbol is treated the same as a string, providing an alternate
+syntax (namely `#:| ... |`) for entering text with many double-quotes.
+
+CCLDoc operators are symbols.  Their input package is ignored and they are converted to keywords
+during processing (so they can be entered with or without an initial colon, as you prefer).  There
+is a set of predefined operators, documented here.  You can define additional operators using
+[#m_def-expander DEF-EXPANDER].
+
+=== Basic Operators === #basic-operators
+[=#cd_include-file] 
+{{{
+#!html
+<tt><font size="+1"><b>(:include-file filename &amp;key in-package external-format)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+The file //`filename`// should consist of any number of lisp forms followed by
+CCLDoc forms.  The lisp forms are processed as if by `LOAD` until the first CCLDoc form
+is encountered, after which all the remaining forms must be CCLDoc forms.  The CCLDoc forms are
+included in the document replacing the `include-file` form itself.
+
+The //`in-package`// parameter can be used to specify the package used to load the file,
+and is entirely equivalent to placing an `in-package` form at the start of the included file.
+//`external-format`// specifies the character encoding of the file
+
+
+
+[=#cd_defsection] 
+{{{
+#!html
+<tt><font size="+1"><b>(:defsection title &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+A named, referenceable, block of text.  A `defsection` can occur at top-level, in which
+case it defines the document;  or it can occur directly within another `defsection`, in which
+case it defines a subsection; and finally it can occur directly within the body of a
+[#cd_definition :DEFINITION].  Sections can be referred to using the title, and, if necessary to disambiguate,
+the name of the containing section or definition -- see [#cd_ref :REF].
+
+
+
+[=#cd_index-section] 
+{{{
+#!html
+<tt><font size="+1"><b>(:index-section title)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Placed at the top-level of the document to specify the title and location of the index
+
+
+
+[=#cd_glossary-section] 
+{{{
+#!html
+<tt><font size="+1"><b>(:glossary-section title &amp;rest glossentries)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Placed at the top-level of the document to specify the title and location of the glossary.
+It may contain [#cd_glossentry :GLOSSENTRY] definitions, although note that [#cd_glossentry :GLOSSENTRY] definitions
+can actually occur anywhere in the document and will be placed in the glossary and sorted automatically
+
+
+
+[=#cd_block] 
+{{{
+#!html
+<tt><font size="+1"><b>(:block title &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Defines a block of text set off (indented) from the main text.  The //`title`// can
+be `NIL` to create an anonymous block.  Note however that even when titled, a block
+cannot be referred to by name from elsewhere in a document.
+
+
+
+[=#cd_code-block] 
+{{{
+#!html
+<tt><font size="+1"><b>(:code-block &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+A block suitable for listing of code.  A fixed width font will be used to display the content,
+and whitespace and linebreaks will be shown verbatim.  Note however that markup //is//
+allowed within code blocks.
+
+
+
+[=#cd_table] 
+{{{
+#!html
+<tt><font size="+1"><b>(:table title head-row &amp;rest rows)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Defines a table. Tables have a sequence of [#cd_row :ROW] clauses, the first of which will
+be formatted specially as the head row.  Tables can be referred to using the //`title`//,
+and if necessary to disambiguate, the name of the containing section -- see [#cd_ref :REF].
+
+
+
+[=#cd_glossentry] 
+{{{
+#!html
+<tt><font size="+1"><b>(:glossentry term &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+A glossary definition.  //`term`// is the term being defined, and the remaining
+clauses are the explanation of the text.  A `glossentry` can appear anywhere in the
+source document, but it doesn't get displayed where it appears - all the `glossentry`
+forms get collected into the [#cd_glossary-section :GLOSSARY-SECTION].  Glossary entries can be referred
+to from elsewhere in the document using the //`term`// -- see [#cd_ref :REF].
+
+
+
+[=#cd_definition] 
+{{{
+#!html
+<tt><font size="+1"><b>(:definition (type name) signature summary &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+A definition block - unit of reference documentation describing a single global lisp name.
+
+//`type`// is a symbol specifing the type of the definition, establishing a namespace
+in which //`name`// is interpreted.  (As usual, the input package of the //`type`// symbol is
+ignored and the symbol is converted to a keyword during processing).  The //`name`// can
+be any lisp object.  Definitions can be referred to from elsewhere in the document using their
+//`type`// and //`name`// -- see [#cd_ref :REF]. //`name`//s of the same
+//`type`// are compared using `EQUALP`.
+
+//`signature`// is the syntactic synopsis of the definition.
+
+ **Note**
+ 
+ Someday I'd like the signature to be a lisp expression that will be automatically converted
+ to text with consistent markup for parameters and values, but that is not implemented right now.
+ For now it might be best for document consistency to simply avoid markup in the signature
+ 
+ 
+
+//`summary`// is a concise one line summary of the functionality being defined.
+
+The //`subforms`// provide a more detailed description.
+
+The following //`type`// values are supported by default.  Additional types can be defined via
+[#m_def-definition-type DEF-DEFINITION-TYPE].
+
+ `:ccldoc`[[BR]]
+ `:hemlock-command`[[BR]]
+ `:hemlock-variable`[[BR]]
+ `:toplevel-command`[[BR]]
+ `:package`[[BR]]
+ `:reader-macro`[[BR]]
+ `:variable`[[BR]]
+ `:method`[[BR]]
+ `:lap-macro`[[BR]]
+ `:generic-function`[[BR]]
+ `:macro`[[BR]]
+ `:function`[[BR]]
+ `:condition`[[BR]]
+ `:class`[[BR]]
+ `:type`[[BR]]
+
+
+
+
+
+
+[=#cd_row] 
+{{{
+#!html
+<tt><font size="+1"><b>(:row &amp;rest items)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+For use within [#cd_table :TABLE] only, defines a single row in the table as a sequence of [#cd_item :ITEM]
+expresssions
+
+
+
+[=#cd_listing] 
+{{{
+#!html
+<tt><font size="+1"><b>(:listing type &amp;rest items)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+A listing of items specified by the //`items`// forms.  //`type`// determines how the list
+will be formatted.  //`type`// names are symbols whose input package is ignored and converted to
+keyword during processing.  The following //`type`// values are supported:
+
+ 
+ `:bullet`:: A list in which item is marked with a character such as a bullet
+   
+   
+ 
+ `:number`:: A list in which each item is marked with a sequentially incremented label
+   
+   
+ 
+ `:definition`:: A list in which each item consists of a term and an associated description.
+   See [#cd_item :ITEM] for the  syntax of definition list items
+   
+   
+ 
+ `:column`:: A simple undecorated column, typically of single words or phrases
+   
+   
+
+
+
+
+[=#cd_para] 
+{{{
+#!html
+<tt><font size="+1"><b>(:para &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+A paragraph.
+
+
+
+[=#cd_item] 
+{{{
+#!html
+<tt><font size="+1"><b>(:item &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+A single item in a [#cd_listing :LISTING] or [#cd_row :ROW] expression.  It cannot be used in any other context.
+In `:definition` [#cd_listing :LISTING] items (only), the term and the description should be separated by
+`:=>`, for example:
+
+`(item "An " (emphasis "important") " item" => "An item which is very important")`
+
+As usual, the input package of `=>` is ignored, so it can be entered with or without the colon.
+
+
+
+[=#cd_index] 
+{{{
+#!html
+<tt><font size="+1"><b>(:index &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Request an index entry.  The //`subforms`// are displayed in place, but in addition, the phrase is
+added to the document index with a link to this point.
+
+
+
+[=#cd_clause] 
+{{{
+#!html
+<tt><font size="+1"><b>(:clause &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Much like the lisp `PROGN` operator,  makes a single expressions from a sequence of them.
+
+
+
+[=#cd_link] 
+{{{
+#!html
+<tt><font size="+1"><b>(:link url &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Makes the text specified by //`subforms`// into a link to the url //`url`//.  If no //`subforms`//
+is specified, the //`url`// becomes the text.
+
+
+
+[=#cd_quote] 
+{{{
+#!html
+<tt><font size="+1"><b>(:quote string)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Specifies that //`string`// is to be used literally, without being interpreted as described in [#string-syntax String Syntax].
+
+
+
+[=#cd_markup] 
+{{{
+#!html
+<tt><font size="+1"><b>(:markup type &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Requests that markup as specified by //`type`// should be applied to //`subforms`//.  The //`type`// is named
+by a symbol whose input package is ignored and converted to keyword during processing.  The following types are
+supported:
+
+ 
+ `:emphasis`:: Emphasized text, usually rendered in in italics or boldface
+   
+   
+ 
+ `:code`:: Literal lisp code, usually rendered in fixed width font
+   
+   
+ 
+ `:param`:: Parameter name
+   
+   
+ 
+ `:sample`:: Content that should be replaced by a value
+   
+   
+ 
+ `:system`:: Operating system construct, for example a shell command or environment variable
+   
+   
+
+
+The difference between `:param` and `:sample` is subtle and perhaps not worth the trouble... But the intent is
+that `:param` be used for a name of the eventual value, whereas `:sample` be used for an example of such a value.
+For instance: `"(compile-file " (:param "filename") ")"#` vs `"(compile-file " (:sample "/name/of/file") ")"`.
+
+
+
+[=#cd_ref] 
+{{{
+#!html
+<tt><font size="+1"><b>(:ref target &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Makes the text specified by //`subforms`// into a link to another part of the document as indicated by //`target`//.  If
+no //`subforms`// are specified, default text is generated based on the target.  In addition, if the specified target is
+a glossary entry or a definition, this reference to it will be listed in the index.
+
+The //`target`// name can take one of the following forms:
+
+ 
+ `:document`:: Targets the document itself.  You can't actually link to the document itself, so this is only useful
+   as the parent-target of a section target
+   
+   
+ 
+ `(:definition type name)`:: Targets a [#cd_definition :DEFINITION] block.  //`type`// and //`name`// are
+   as described in [#cd_definition :DEFINITION].  In addition, //`type`// may be `:*` (or any interned symbol
+   whose pname is "*"), indicating any type.
+   
+   
+ 
+ `(:glossentry term)`:: Targets a [#cd_glossentry :GLOSSENTRY] block defining the given //`term`//.
+   
+   
+ 
+ `(:section title [:in parent-target ...])`:: Targets a [#cd_defsection :DEFSECTION] block whose title
+   is //`title`//. Optionally a sequence of immediate parents of the section can be named as well, for example
+   `(:section "Description" :in "Names and Definitions")` might be used in a document containing different
+   subsections named `"Description"`.  A fully-qualified unambiguous name of a section might look like
+   `(:section "Description" :in "Names and Definitions" :in "Usage" :in :document)`.
+   
+   The reversed sequence of parent titles can also be included in one string, separated by `"::"`, with
+   the toplevel document indicated by `"."`.  So the equivalent to above would be
+   `(:section "Names and Definitions::Description")` for the first
+   example, or `(:section ".::Usage::Names and Definitions::Descriptions")` for the second.
+   
+   
+ 
+ `(:table title [:in parent-target ...])`:: Targets a [#cd_table :TABLE].  Syntax is the same as
+   for `:section`.
+   
+   
+ 
+ `:index` or `(:section :index)`:: Targets the index section
+   
+   
+ 
+ `:glossary` or `(:section :glossary)`:: Targets the glossary section
+   
+   
+ 
+ `(:chapter title)`:: Equivalent to `(:section title :in :document)`
+   
+   
+
+
+
+If the document doesn't actual contain a block named by //`target`//, no link will be produced, but the clause
+will still be displayed and, in case of a glossary entry or definition, the reference will be listed in the index.
+
+
+
+
+=== Convenience Operators === #convenience-operators
+The following operators define more convenient ways of accessing the same functionality
+as the basic operators described in [#basic-operators Basic Operators].
+
+[=#cd_document] 
+{{{
+#!html
+<tt><font size="+1"><b>(:document title &amp;rest sections)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_section :SECTION]` title . sections)`
+
+
+
+[=#cd_chapter] 
+{{{
+#!html
+<tt><font size="+1"><b>(:chapter title &amp;rest sections)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Depending on context, this either defines or references a chapter.  When used at top-level of a
+document, it is equivalent to `(`[#cd_defsection :DEFSECTION]` title . sections)`. In other contexts,
+only one argument is allowed, and it is equivalent to `(`[#cd_ref :REF]` (:chapter title))`
+
+
+
+[=#cd_section] 
+{{{
+#!html
+<tt><font size="+1"><b>(:section title &amp;rest parent-spec)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to  `(`[#cd_ref :REF]` (:section title . parent-specs))`.
+
+
+
+[=#cd_variable] 
+{{{
+#!html
+<tt><font size="+1"><b>(:variable symbol)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_ref :REF]` (:definition :variable symbol))`
+
+
+
+[=#cd_function] 
+{{{
+#!html
+<tt><font size="+1"><b>(:function fspec)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_ref :REF]` (:definition :function fspec))`
+
+
+
+[=#cd_macro] 
+{{{
+#!html
+<tt><font size="+1"><b>(:macro symbol)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_ref :REF]` (:definition :macro symbol))`
+
+
+
+[=#cd_class] 
+{{{
+#!html
+<tt><font size="+1"><b>(:class symbol)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_ref :REF]` (:definition :class symbol))`
+
+
+
+[=#cd_type] 
+{{{
+#!html
+<tt><font size="+1"><b>(:type tspec)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_ref :REF]` (:definition :type tspec))`
+
+
+
+[=#cd_refdef] 
+{{{
+#!html
+<tt><font size="+1"><b>(:refdef type name)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_ref :REF]` (:definition type name))`
+
+
+
+[=#cd_term] 
+{{{
+#!html
+<tt><font size="+1"><b>(:term string)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_ref :REF]` (:glossentry string))`
+
+
+
+[=#cd_emphasis] 
+{{{
+#!html
+<tt><font size="+1"><b>(:emphasis &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_markup :MARKUP]` :emphasis . subforms)`
+
+
+
+[=#cd_system] 
+{{{
+#!html
+<tt><font size="+1"><b>(:system &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_markup :MARKUP]` :system . subforms)`
+
+
+
+[=#cd_sample] 
+{{{
+#!html
+<tt><font size="+1"><b>(:sample &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_markup :MARKUP]` :sample . subforms)`
+
+
+
+[=#cd_param] 
+{{{
+#!html
+<tt><font size="+1"><b>(:param &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_markup :MARKUP]` :param . subforms)`
+
+
+
+[=#cd_code] 
+{{{
+#!html
+<tt><font size="+1"><b>(:code &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(`[#cd_markup :MARKUP]` :code . subforms)`
+
+
+
+[=#cd_lbrace] 
+{{{
+#!html
+<tt><font size="+1"><b>(:lbrace)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(:quote "{")`
+
+
+
+[=#cd_rbrace] 
+{{{
+#!html
+<tt><font size="+1"><b>(:rbrace)     </b></font><i>[ccldoc operator]</i></tt>
+}}}
+
+Equivalent to `(:quote "}")`
+
+
+
+
+=== String Syntax === #string-syntax
+Strings are the terminal clauses in CCLDoc expressions and define the text to be output.
+
+For convenience, strings support a syntax for embedding other clauses, in the form `{operand arguments}`.
+The parsing of the arguments is up to the operand, but in general consists of some operand-specific number
+of lisp expressions, with the rest of the arguments forming the body.  The processing of the embedded syntax
+can be avoided by using the [#cd_quote :QUOTE] operator.
+
+In order to support the embedded syntax, #!\{ and #!\} cannot be entered directly in an unquoted string clause.
+Use {lbrace} and {rbrace} instead.
+
+Blank lines (i.e. lines consisting only of whitespace characters) in string clauses are treated as paragraph breaks.
+
+
+
+== API Documentation == #api-documentation
+[=#f_load-document] 
+{{{
+#!html
+<tt><font size="+1"><b>(load-document filename &amp;key external-format) =&gt; document     </b></font><i>[Function]</i></tt>
+}}}
+
+Load a CCLDoc source file and return a [#c_document DOCUMENT] object.  The file //`filename`// should
+consist of any number of lisp forms followed by a single CCLDoc form which should be (or expand into)
+a [#cd_defsection :DEFSECTION] expression.  The lisp preceding forms are processed as if by `LOAD`.
+
+
+
+[=#f_output-docbook] 
+{{{
+#!html
+<tt><font size="+1"><b>(output-docbook doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt>
+}}}
+
+Takes a [#c_document DOCUMENT] object //`doc`// and creates a file in //`filename`// containing [http://docbook.org docbook]
+source.
+
+
+
+[=#f_output-tracwiki] 
+{{{
+#!html
+<tt><font size="+1"><b>(output-tracwiki doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt>
+}}}
+
+Takes a [#c_document DOCUMENT] object //`doc`// and creates a file in //`filename`// containing [http://trac.edgewall.org/wiki Trac Wiki]
+source.
+
+
+
+[=#f_output-ccldoc] 
+{{{
+#!html
+<tt><font size="+1"><b>(output-ccldoc doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt>
+}}}
+
+Takes a [#c_document DOCUMENT] object //`doc`// and creates a file //`filename`// containing CCLDoc
+source code, in effect disassembling the document.  Note that this output is mainly useful for
+debugging, since all the macros will have been expanded.
+
+
+
+[=#m_def-expander] 
+{{{
+#!html
+<tt><font size="+1"><b>(def-expander name arglist [:parser-types parser-types] &amp;body body)     </b></font><i>[Macro]</i></tt>
+}}}
+
+Define a CCLDoc macro.  The syntax of //`arglist`// and //`body`// is the same as for `DEFMACRO`.
+When the CCLDoc processor encounters a form whose `CAR` is an interned symbol with the same pname as //`name`//,
+the //`body`// of the expander will be invoked with the form destructured against //`arglist`//, and the returned
+form will be used instead.
+
+The //`parser-types`// option can be used to specify the parsing if //`name`// is used with the embedded string syntax.
+It should be an (unquoted) list of some number of `:lisp` symbols followed by at most one `:text` symbol.
+The string parser will read as many arguments as there are instances of `:lisp` using the lisp `READ` function,
+and then the rest of the string will be parsed as CCLDoc forms.  For example:
+
+
+{{{
+      (def-expander :REFDEF (type name)
+        :parser-types (:lisp :lisp)
+        `(ref (definition ,type ,name)))
+      }}}
+allows the embedded syntax `{refdef type name}`, where `type` and `name` will be parsed
+using the lisp `READ`.  This example:
+
+
+{{{
+      (def-expander my-markup (type &rest subforms)
+        :parser-types (:lisp :text)
+        `(markup ,type ,@subforms))
+      }}}
+allows the embedded syntax `{markup type Arbitrary text ...}`, where `type` will
+be parsed using the lisp `READ`, and the rest of the form will be processed by CCLDoc and passed in as the
+//`subforms`// parameter to the expander.
+
+
+
+[=#m_def-definition-type] 
+{{{
+#!html
+<tt><font size="+1"><b>(def-definition-type type (&amp;optional parent-type) &amp;key type-name id-prefix function)     </b></font><i>[Macro]</i></tt>
+}}}
+
+Adds a new type that can be used to classify name of a [#cd_definition :DEFINITION].
+
+//`type`// is a symbol naming the type being defined (as usual, the input package of the //`type`// symbol is
+ignored and the symbol is converted to a keyword during processing)
+
+//`parent-type`// is, optionally, an existing type from which the new type descends.  This is used to inherit
+some properties, and to help in matching references to their targets (so for example we know that a reference
+to `(:definition :function trace)` is applicable to `(:definition :macro trace)`, because the type
+`:macro` descends from `:function`.
+
+//`type-name`// the user-visible name of this type, as a string.  If not specified, it defaults to the
+capitalized version of the //`type`//.
+
+//`id-prefix`// is a prefix to use in generating external id's for definitions of this type. If not
+specified, it inherits from //`parent-type`//, ultimately defaulting to `"x_"`.
+
+//`function`// is a function of one argument which will be used to canonicalize names of this type.  The returned
+values will be compared using `EQUALP` to determine whether the refer to the same object. If not
+specified, it inherits from //`parent-type`//, ultimately defaulting to `#'identity`.
+
+
+
+
+== DOCUMENT Object Model == #document-object-model
+This section describes the structure of the [#c_document DOCUMENT] object.  You only need to read this
+section if you want to implement a new output format or write a document analysis tool.
+
+A CCLDoc document is a tree of [#t_clause CLAUSE] objects, rooted with a [#c_document DOCUMENT] object.
+
+
+[=#t_clause] 
+{{{
+#!html
+<tt><font size="+1"><b>clause     </b></font><i>[Type]</i></tt>
+}}}
+
+The type `clause` is a union of three types:
+
+ 
+ `STRING`:: a string represents text to be output to the document
+   
+   
+ 
+ `CLAUSE-OBJECT`:: an instance of the [#c_clause-object CLAUSE-OBJECT] class as described below
+   
+   
+ 
+ `CONS`:: a list of `STRING` or `CLAUSE-OBJECT` objects (no nested lists), representing a sequence of text
+   
+   
+
+
+
+
+=== Abstract Classes === #abstract-classes
+[=#c_clause-object] 
+{{{
+#!html
+<tt><font size="+1"><b>clause-object ()     </b></font><i>[Class]</i></tt>
+}}}
+
+The base class of CCLDoc objects.  The following functions are applicable to all `clause-object` instances:
+
+ [#f_clause-parent CLAUSE-PARENT][[BR]]
+ [#f_clause-document CLAUSE-DOCUMENT][[BR]]
+ [#f_section-level SECTION-LEVEL][[BR]]
+ [#f_clause-text CLAUSE-TEXT][[BR]]
+
+
+
+
+[=#c_named-clause] 
+{{{
+#!html
+<tt><font size="+1"><b>named-clause (clause-object)     </b></font><i>[Class]</i></tt>
+}}}
+
+The class of objects which can be linked to from other objects.  The following functions
+are applicable to `named-clause` instances:
+
+ [#f_clause-name CLAUSE-NAME][[BR]]
+ [#f_clause-external-id CLAUSE-EXTERNAL-ID][[BR]]
+
+
+
+
+[=#c_clause-with-title] 
+{{{
+#!html
+<tt><font size="+1"><b>clause-with-title (clause-object)     </b></font><i>[Class]</i></tt>
+}}}
+
+A mixin class that adds support for the [#f_clause-title CLAUSE-TITLE] property
+
+
+
+[=#c_clause-with-term] 
+{{{
+#!html
+<tt><font size="+1"><b>clause-with-term (clause-object)     </b></font><i>[Class]</i></tt>
+}}}
+
+A mixin class that adds support for the [#f_clause-term CLAUSE-TERM] property
+
+
+
+[=#c_clause-with-body] 
+{{{
+#!html
+<tt><font size="+1"><b>clause-with-body (clause-object)     </b></font><i>[Class]</i></tt>
+}}}
+
+A mixin class that adds support for the [#f_clause-body CLAUSE-BODY] property
+
+
+
+[=#c_clause-with-items] 
+{{{
+#!html
+<tt><font size="+1"><b>clause-with-items (clause-object)     </b></font><i>[Class]</i></tt>
+}}}
+
+A mixin class that adds support for the [#f_clause-items CLAUSE-ITEMS] property
+
+
+
+
+=== Concrete Classes === #concrete-classes
+[=#c_document] 
+{{{
+#!html
+<tt><font size="+1"><b>document (section)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of the top-level document
+
+
+
+[=#c_index-section] 
+{{{
+#!html
+<tt><font size="+1"><b>index-section (section)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of the index section.  The index section has no body, since it's assumed that the backend will
+take care of producing the section.  It contains the desired section title, and its position in the
+document indicates where the index chapter should go.
+
+
+
+[=#c_glossary-section] 
+{{{
+#!html
+<tt><font size="+1"><b>glossary-section (section)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of the glossary section.  The body of the glossary section consists of [#c_glossentry GLOSSENTRY]
+objects, sorted according to the term they define
+
+
+
+[=#c_section] 
+{{{
+#!html
+<tt><font size="+1"><b>section (named-clause clause-with-title clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of document sections
+
+
+
+[=#c_glossentry] 
+{{{
+#!html
+<tt><font size="+1"><b>glossentry (named-clause clause-with-term clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of glossary entries.
+
+
+
+[=#c_code-block] 
+{{{
+#!html
+<tt><font size="+1"><b>code-block (clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a block to be displayed as code with verbatim line breaks and spacing
+
+
+
+[=#c_block] 
+{{{
+#!html
+<tt><font size="+1"><b>block (clause-with-title clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a block, with an optional title, to be rendered offset from the main text.
+
+
+
+[=#c_para] 
+{{{
+#!html
+<tt><font size="+1"><b>para (clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a paragraph
+
+
+
+[=#c_docerror] 
+{{{
+#!html
+<tt><font size="+1"><b>docerror (clause-object)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of an error message generated during processing of the document source.  The text of the error
+message is returned by [#f_clause-text CLAUSE-TEXT]
+
+
+
+[=#c_link] 
+{{{
+#!html
+<tt><font size="+1"><b>link (clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a link to a url target which is returned [#f_link-url LINK-URL].  The body of the clause is the
+text to be displayed.  It is guaranteed non-empty (CCLDoc fills in a default if the user
+didn't provide it).
+
+
+
+[=#c_table] 
+{{{
+#!html
+<tt><font size="+1"><b>table (named-clause clause-with-title clause-with-items)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a table.  The items of a `table` are a vector of [#c_row ROW] objects for the table
+
+
+
+[=#c_row] 
+{{{
+#!html
+<tt><font size="+1"><b>row (clause-with-items)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a table row.  `row` objects occur only in the [#f_clause-items CLAUSE-ITEMS] vector
+of a [#c_table TABLE] object.  The items of a `row` are a vector of [#c_item ITEM] objects for the columns in the row
+
+
+
+[=#c_listing] 
+{{{
+#!html
+<tt><font size="+1"><b>listing (clause-with-items)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a listing.  The listing type is returned by [#f_listing-type LISTING-TYPE].  See [#cd_listing :LISTING] for the
+list of possible types.
+
+The items of a listing are a vector a [#c_item ITEM] objects, except for `:definition` listing type,
+where the items are [#c_term-item TERM-ITEM] objects.
+
+
+
+[=#c_indexed-clause] 
+{{{
+#!html
+<tt><font size="+1"><b>indexed-clause (clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of text to be both entered in document and added to index
+
+
+
+[=#c_markup] 
+{{{
+#!html
+<tt><font size="+1"><b>markup (clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of text to have markup applied.  The markup type is returned by [#f_markup-type MARKUP-TYPE].  See [#cd_markup :MARKUP] for
+the list of possible types
+
+
+
+[=#c_item] 
+{{{
+#!html
+<tt><font size="+1"><b>item (clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of text which occurs as an item in a table [#c_row ROW] or a [#c_listing LISTING]
+
+
+
+[=#c_term-item] 
+{{{
+#!html
+<tt><font size="+1"><b>item (clause-with-term clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of text which occurs only in [#c_listing LISTING] objects of type `:definition`
+
+
+
+[=#c_xref] 
+{{{
+#!html
+<tt><font size="+1"><b>xref (indexed-clause)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a link to another object in the document.  The function [#f_xref-target XREF-TARGET] returns the
+object that is the target of the reference.  The clause body is what the user specified as the text of the
+link.  It may be `NIL` if the user didn't specify any text, in which case the function
+[#f_xref-default-body XREF-DEFAULT-BODY] will return default text computed by CCLDoc.
+
+
+
+[=#c_definition] 
+{{{
+#!html
+<tt><font size="+1"><b>definition (named-clause clause-with-body)     </b></font><i>[Class]</i></tt>
+}}}
+
+Class of a definition.  The clause body is the full description of the definition.  The function
+[#f_definition-signature DEFINITION-SIGNATURE] returns the signature of the definition and [#f_definition-summary DEFINITION-SUMMARY]
+returns the summary.  [#f_definition-display-name DEFINITION-DISPLAY-NAME] returns a user-visible version of the definition name.
+
+
+
+
+=== Accessor Functions === #accessor-functions
+[=#f_clause-text] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-text clause) =&gt; string     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the text of the //`clause`// with all markup removed.
+
+
+
+[=#f_section-level] 
+{{{
+#!html
+<tt><font size="+1"><b>(section-level clause-object) =&gt; integer     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the level of the section containing //`clause-object`//.  The document is level 0
+
+
+
+[=#f_clause-document] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-document clause-object) =&gt; document     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the document containing the //`clause-object`//
+
+
+
+[=#f_clause-parent] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-parent clause-object) =&gt; clause-object-or-nil     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the clause containing //`clause-object`//, or `NIL` if //`clause-object`// is the document
+
+
+
+[=#f_clause-name] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-name named-clause) =&gt; name     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the name of the //`named-clause`//.  The name is a lisp object uniquely identifying the clause
+when compared with `EQUALP`. When //`named-clause`// is a [#c_glossentry GLOSSENTRY], the name is 
+a string, the text of the term being defined by the entry.  When //`named-clause`// is a [#c_section SECTION],
+the name is a `CONS` whose `CAR` is the title of the section and whose `CDR` is the
+clause-name of the section's parent clause.  When //`named-clause`// is a [#c_definition DEFINITION],
+the name is a [#c_dspec DSPEC] as described in [#definition-names Definition names].
+
+
+
+[=#f_clause-external-id] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-external-id named-clause) =&gt; string     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns a string uniquely identifying the //`named-clause`//.  The string starts with
+a letter and contains only letters, numbers, underscores, dashes, and periods
+
+
+
+[=#f_clause-title] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-title clause-with-title) =&gt; string-or-nil     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the clause title.  When //`clause-with-title`// is a [#c_named-clause NAMED-CLAUSE], the title
+is required and hence the value will not be `nil`.  When //`clause-with-title`// is a [#c_block BLOCK],
+the title may be `nil`.
+
+
+
+[=#f_clause-term] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-term clause-with-term) =&gt; clause-or-nil     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the term clause
+
+
+
+[=#f_clause-body] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-body clause-with-body) =&gt; clause-or-nil     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the body clause
+
+
+
+[=#f_clause-items] 
+{{{
+#!html
+<tt><font size="+1"><b>(clause-items clause-with-items) =&gt; vector     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns a vector.  When //`clause-with-items`// is a [#c_table TABLE], the returned vector is a
+vector of [#c_row ROW] objects.  When //`clause-with-items`// is a [#c_row ROW], or it is
+a [#c_listing LISTING] of type other than `:definition`, then the vector is a vector of [#c_item ITEM]
+objects.  When //`clause-with-items`// is a [#c_listing LISTING] of type `:definition`, the
+vector is a vector of [#c_term-item TERM-ITEM] objects.
+
+
+
+[=#f_markup-type] 
+{{{
+#!html
+<tt><font size="+1"><b>(markup-type markup) =&gt; markup-type     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the markup type.  See [#cd_markup :MARKUP] operator for the list of possible types
+
+
+
+[=#f_listing-type] 
+{{{
+#!html
+<tt><font size="+1"><b>(listing-type listing) =&gt; listing-type     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the listing type.  See [#cd_listing :LISTING] operator for the list of possible types
+
+
+
+[=#f_definition-display-name] 
+{{{
+#!html
+<tt><font size="+1"><b>(definition-display-name definition) =&gt; clause     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns a user-visible version of the definition name.
+
+
+
+[=#f_definition-summary] 
+{{{
+#!html
+<tt><font size="+1"><b>(definition-summary definition) =&gt; clause     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the definition summary
+
+
+
+[=#f_definition-signature] 
+{{{
+#!html
+<tt><font size="+1"><b>(definition-signature definition) =&gt; clause     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the definition signature
+
+
+
+[=#f_link-url] 
+{{{
+#!html
+<tt><font size="+1"><b>(link-url link) =&gt; string     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the url that is the target of this link
+
+
+
+[=#f_xref-target] 
+{{{
+#!html
+<tt><font size="+1"><b>(xref-target xref) =&gt; named-object     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the target of the reference
+
+
+
+[=#f_xref-default-body] 
+{{{
+#!html
+<tt><font size="+1"><b>(xref-default-body link) =&gt; clause     </b></font><i>[Function]</i></tt>
+}}}
+
+Returns the default body for the reference that can be used when the user didn't specify one
+
+
+
+
+=== Definition Names === #definition-names
+[=#c_dspec] 
+{{{
+#!html
+<tt><font size="+1"><b>dspec ()     </b></font><i>[Class]</i></tt>
+}}}
+
+The type of the value returned by [#f_clause-name CLAUSE-NAME] for [#c_definition DEFINITION] objects. Encodes the name and type of
+the definition
+
+
+
+[=#f_dspec-type] 
+{{{
+#!html
+<tt><font size="+1"><b>(dspec-type dspec) =&gt; definition-type     </b></font><i>[Function]</i></tt>
+}}}
+
+The type of the definition named by //`dspec`//.  See [#cd_definition :DEFINITION] for
+a discussion of definition types
+
+
+
+[=#f_dspec-name] 
+{{{
+#!html
+<tt><font size="+1"><b>(dspec-name dspec) =&gt; definition-name     </b></font><i>[Function]</i></tt>
+}}}
+
+The name of the definition named by //`dspec`//.  See [#cd_definition :DEFINITION] for
+a discussion of definition names
+
+
+
+[=#f_dspec-type-name] 
+{{{
+#!html
+<tt><font size="+1"><b>(dspec-type-name dspec) =&gt; string     </b></font><i>[Function]</i></tt>
+}}}
+
+A user-visible version of the definition type
+
+
+
+
+