Changes between Initial Version and Version 1 of CCLDocOverview

10/13/14 22:56:18 (2 years ago)



  • CCLDocOverview

    v1 v1  
     3= CCLDoc Documentation system = 
     4== Overview == #overview 
     5CCLDoc is a system for creating lisp documentation.  It uses s-expressions to represent document 
     6structure, markup, cross references, and contents.  It has a small number of basic operators, supports 
     7macros for syntax extensions, and supports a simple syntax for embedding expressions in strings for 
     8added convenience. 
     10All the symbols referenced in this section without an explicit package prefix are external 
     11in the `:CCLDOC` package. 
     13A CCLDoc document definition is processed by the [#f_load-document LOAD-DOCUMENT] function to produce 
     14a [#c_document DOCUMENT] object.  This object can then be processed to create other formats. 
     15Currently three output formats are supported: [#f_output-docbook OUTPUT-DOCBOOK] generates 
     16[ docbook] output, [#f_output-tracwiki OUTPUT-TRACWIKI] generates [ Trac Wiki] 
     17output, and [#f_output-ccldoc OUTPUT-CCLDOC] generates CCLDoc source output. 
     19By having a small number of relatively high-level operators, CCLDoc allows the creation of 
     20consistently formatted documents even when written by many different people over extended 
     21periods of time.  Additionally, the simple document model enables longevity by making it easy to 
     22upgrade and change the back-end tools used to implement the final formatting, without having 
     23to convert the document source 
     26== Source Syntax == #source-syntax 
     27A CCLDoc document is represented by an s-expression with the usual semantics: when the 
     28s-expression is a `CONS`, the `CAR` of each form is a CCLDoc operator and the 
     29`CDR` contains the arguments. The s-expression can also be a string in which case it 
     30has additional internal structure as described in [#string-syntax String Syntax]. Finally, for 
     31convenience, an uninterned symbol is treated the same as a string, providing an alternate 
     32syntax (namely `#:| ... |`) for entering text with many double-quotes. 
     34CCLDoc operators are symbols.  Their input package is ignored and they are converted to keywords 
     35during processing (so they can be entered with or without an initial colon, as you prefer).  There 
     36is a set of predefined operators, documented here.  You can define additional operators using 
     37[#m_def-expander DEF-EXPANDER]. 
     39=== Basic Operators === #basic-operators 
     43<tt><font size="+1"><b>(:include-file filename &amp;key in-package external-format)     </b></font><i>[ccldoc operator]</i></tt> 
     46The file //`filename`// should consist of any number of lisp forms followed by 
     47CCLDoc forms.  The lisp forms are processed as if by `LOAD` until the first CCLDoc form 
     48is encountered, after which all the remaining forms must be CCLDoc forms.  The CCLDoc forms are 
     49included in the document replacing the `include-file` form itself. 
     51The //`in-package`// parameter can be used to specify the package used to load the file, 
     52and is entirely equivalent to placing an `in-package` form at the start of the included file. 
     53//`external-format`// specifies the character encoding of the file 
     60<tt><font size="+1"><b>(:defsection title &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     63A named, referenceable, block of text.  A `defsection` can occur at top-level, in which 
     64case it defines the document;  or it can occur directly within another `defsection`, in which 
     65case it defines a subsection; and finally it can occur directly within the body of a 
     66[#cd_definition :DEFINITION].  Sections can be referred to using the title, and, if necessary to disambiguate, 
     67the name of the containing section or definition -- see [#cd_ref :REF]. 
     74<tt><font size="+1"><b>(:index-section title)     </b></font><i>[ccldoc operator]</i></tt> 
     77Placed at the top-level of the document to specify the title and location of the index 
     84<tt><font size="+1"><b>(:glossary-section title &amp;rest glossentries)     </b></font><i>[ccldoc operator]</i></tt> 
     87Placed at the top-level of the document to specify the title and location of the glossary. 
     88It may contain [#cd_glossentry :GLOSSENTRY] definitions, although note that [#cd_glossentry :GLOSSENTRY] definitions 
     89can actually occur anywhere in the document and will be placed in the glossary and sorted automatically 
     96<tt><font size="+1"><b>(:block title &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     99Defines a block of text set off (indented) from the main text.  The //`title`// can 
     100be `NIL` to create an anonymous block.  Note however that even when titled, a block 
     101cannot be referred to by name from elsewhere in a document. 
     108<tt><font size="+1"><b>(:code-block &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     111A block suitable for listing of code.  A fixed width font will be used to display the content, 
     112and whitespace and linebreaks will be shown verbatim.  Note however that markup //is// 
     113allowed within code blocks. 
     120<tt><font size="+1"><b>(:table title head-row &amp;rest rows)     </b></font><i>[ccldoc operator]</i></tt> 
     123Defines a table. Tables have a sequence of [#cd_row :ROW] clauses, the first of which will 
     124be formatted specially as the head row.  Tables can be referred to using the //`title`//, 
     125and if necessary to disambiguate, the name of the containing section -- see [#cd_ref :REF]. 
     132<tt><font size="+1"><b>(:glossentry term &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     135A glossary definition.  //`term`// is the term being defined, and the remaining 
     136clauses are the explanation of the text.  A `glossentry` can appear anywhere in the 
     137source document, but it doesn't get displayed where it appears - all the `glossentry` 
     138forms get collected into the [#cd_glossary-section :GLOSSARY-SECTION].  Glossary entries can be referred 
     139to from elsewhere in the document using the //`term`// -- see [#cd_ref :REF]. 
     146<tt><font size="+1"><b>(:definition (type name) signature summary &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     149A definition block - unit of reference documentation describing a single global lisp name. 
     151//`type`// is a symbol specifing the type of the definition, establishing a namespace 
     152in which //`name`// is interpreted.  (As usual, the input package of the //`type`// symbol is 
     153ignored and the symbol is converted to a keyword during processing).  The //`name`// can 
     154be any lisp object.  Definitions can be referred to from elsewhere in the document using their 
     155//`type`// and //`name`// -- see [#cd_ref :REF]. //`name`//s of the same 
     156//`type`// are compared using `EQUALP`. 
     158//`signature`// is the syntactic synopsis of the definition. 
     160 **Note** 
     162 Someday I'd like the signature to be a lisp expression that will be automatically converted 
     163 to text with consistent markup for parameters and values, but that is not implemented right now. 
     164 For now it might be best for document consistency to simply avoid markup in the signature 
     168//`summary`// is a concise one line summary of the functionality being defined. 
     170The //`subforms`// provide a more detailed description. 
     172The following //`type`// values are supported by default.  Additional types can be defined via 
     173[#m_def-definition-type DEF-DEFINITION-TYPE]. 
     175 `:ccldoc`[[BR]] 
     176 `:hemlock-command`[[BR]] 
     177 `:hemlock-variable`[[BR]] 
     178 `:toplevel-command`[[BR]] 
     179 `:package`[[BR]] 
     180 `:reader-macro`[[BR]] 
     181 `:variable`[[BR]] 
     182 `:method`[[BR]] 
     183 `:lap-macro`[[BR]] 
     184 `:generic-function`[[BR]] 
     185 `:macro`[[BR]] 
     186 `:function`[[BR]] 
     187 `:condition`[[BR]] 
     188 `:class`[[BR]] 
     189 `:type`[[BR]] 
     199<tt><font size="+1"><b>(:row &amp;rest items)     </b></font><i>[ccldoc operator]</i></tt> 
     202For use within [#cd_table :TABLE] only, defines a single row in the table as a sequence of [#cd_item :ITEM] 
     210<tt><font size="+1"><b>(:listing type &amp;rest items)     </b></font><i>[ccldoc operator]</i></tt> 
     213A listing of items specified by the //`items`// forms.  //`type`// determines how the list 
     214will be formatted.  //`type`// names are symbols whose input package is ignored and converted to 
     215keyword during processing.  The following //`type`// values are supported: 
     218 `:bullet`:: A list in which item is marked with a character such as a bullet 
     222 `:number`:: A list in which each item is marked with a sequentially incremented label 
     226 `:definition`:: A list in which each item consists of a term and an associated description. 
     227   See [#cd_item :ITEM] for the  syntax of definition list items 
     231 `:column`:: A simple undecorated column, typically of single words or phrases 
     241<tt><font size="+1"><b>(:para &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     244A paragraph. 
     251<tt><font size="+1"><b>(:item &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     254A single item in a [#cd_listing :LISTING] or [#cd_row :ROW] expression.  It cannot be used in any other context. 
     255In `:definition` [#cd_listing :LISTING] items (only), the term and the description should be separated by 
     256`:=>`, for example: 
     258`(item "An " (emphasis "important") " item" => "An item which is very important")` 
     260As usual, the input package of `=>` is ignored, so it can be entered with or without the colon. 
     267<tt><font size="+1"><b>(:index &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     270Request an index entry.  The //`subforms`// are displayed in place, but in addition, the phrase is 
     271added to the document index with a link to this point. 
     278<tt><font size="+1"><b>(:clause &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     281Much like the lisp `PROGN` operator,  makes a single expressions from a sequence of them. 
     288<tt><font size="+1"><b>(:link url &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     291Makes the text specified by //`subforms`// into a link to the url //`url`//.  If no //`subforms`// 
     292is specified, the //`url`// becomes the text. 
     299<tt><font size="+1"><b>(:quote string)     </b></font><i>[ccldoc operator]</i></tt> 
     302Specifies that //`string`// is to be used literally, without being interpreted as described in [#string-syntax String Syntax]. 
     309<tt><font size="+1"><b>(:markup type &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     312Requests that markup as specified by //`type`// should be applied to //`subforms`//.  The //`type`// is named 
     313by a symbol whose input package is ignored and converted to keyword during processing.  The following types are 
     317 `:emphasis`:: Emphasized text, usually rendered in in italics or boldface 
     321 `:code`:: Literal lisp code, usually rendered in fixed width font 
     325 `:param`:: Parameter name 
     329 `:sample`:: Content that should be replaced by a value 
     333 `:system`:: Operating system construct, for example a shell command or environment variable 
     338The difference between `:param` and `:sample` is subtle and perhaps not worth the trouble... But the intent is 
     339that `:param` be used for a name of the eventual value, whereas `:sample` be used for an example of such a value. 
     340For instance: `"(compile-file " (:param "filename") ")"#` vs `"(compile-file " (:sample "/name/of/file") ")"`. 
     347<tt><font size="+1"><b>(:ref target &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     350Makes the text specified by //`subforms`// into a link to another part of the document as indicated by //`target`//.  If 
     351no //`subforms`// are specified, default text is generated based on the target.  In addition, if the specified target is 
     352a glossary entry or a definition, this reference to it will be listed in the index. 
     354The //`target`// name can take one of the following forms: 
     357 `:document`:: Targets the document itself.  You can't actually link to the document itself, so this is only useful 
     358   as the parent-target of a section target 
     362 `(:definition type name)`:: Targets a [#cd_definition :DEFINITION] block.  //`type`// and //`name`// are 
     363   as described in [#cd_definition :DEFINITION].  In addition, //`type`// may be `:*` (or any interned symbol 
     364   whose pname is "*"), indicating any type. 
     368 `(:glossentry term)`:: Targets a [#cd_glossentry :GLOSSENTRY] block defining the given //`term`//. 
     372 `(:section title [:in parent-target ...])`:: Targets a [#cd_defsection :DEFSECTION] block whose title 
     373   is //`title`//. Optionally a sequence of immediate parents of the section can be named as well, for example 
     374   `(:section "Description" :in "Names and Definitions")` might be used in a document containing different 
     375   subsections named `"Description"`.  A fully-qualified unambiguous name of a section might look like 
     376   `(:section "Description" :in "Names and Definitions" :in "Usage" :in :document)`. 
     378   The reversed sequence of parent titles can also be included in one string, separated by `"::"`, with 
     379   the toplevel document indicated by `"."`.  So the equivalent to above would be 
     380   `(:section "Names and Definitions::Description")` for the first 
     381   example, or `(:section ".::Usage::Names and Definitions::Descriptions")` for the second. 
     385 `(:table title [:in parent-target ...])`:: Targets a [#cd_table :TABLE].  Syntax is the same as 
     386   for `:section`. 
     390 `:index` or `(:section :index)`:: Targets the index section 
     394 `:glossary` or `(:section :glossary)`:: Targets the glossary section 
     398 `(:chapter title)`:: Equivalent to `(:section title :in :document)` 
     404If the document doesn't actual contain a block named by //`target`//, no link will be produced, but the clause 
     405will still be displayed and, in case of a glossary entry or definition, the reference will be listed in the index. 
     410=== Convenience Operators === #convenience-operators 
     411The following operators define more convenient ways of accessing the same functionality 
     412as the basic operators described in [#basic-operators Basic Operators]. 
     417<tt><font size="+1"><b>(:document title &amp;rest sections)     </b></font><i>[ccldoc operator]</i></tt> 
     420Equivalent to `(`[#cd_section :SECTION]` title . sections)` 
     427<tt><font size="+1"><b>(:chapter title &amp;rest sections)     </b></font><i>[ccldoc operator]</i></tt> 
     430Depending on context, this either defines or references a chapter.  When used at top-level of a 
     431document, it is equivalent to `(`[#cd_defsection :DEFSECTION]` title . sections)`. In other contexts, 
     432only one argument is allowed, and it is equivalent to `(`[#cd_ref :REF]` (:chapter title))` 
     439<tt><font size="+1"><b>(:section title &amp;rest parent-spec)     </b></font><i>[ccldoc operator]</i></tt> 
     442Equivalent to  `(`[#cd_ref :REF]` (:section title . parent-specs))`. 
     449<tt><font size="+1"><b>(:variable symbol)     </b></font><i>[ccldoc operator]</i></tt> 
     452Equivalent to `(`[#cd_ref :REF]` (:definition :variable symbol))` 
     459<tt><font size="+1"><b>(:function fspec)     </b></font><i>[ccldoc operator]</i></tt> 
     462Equivalent to `(`[#cd_ref :REF]` (:definition :function fspec))` 
     469<tt><font size="+1"><b>(:macro symbol)     </b></font><i>[ccldoc operator]</i></tt> 
     472Equivalent to `(`[#cd_ref :REF]` (:definition :macro symbol))` 
     479<tt><font size="+1"><b>(:class symbol)     </b></font><i>[ccldoc operator]</i></tt> 
     482Equivalent to `(`[#cd_ref :REF]` (:definition :class symbol))` 
     489<tt><font size="+1"><b>(:type tspec)     </b></font><i>[ccldoc operator]</i></tt> 
     492Equivalent to `(`[#cd_ref :REF]` (:definition :type tspec))` 
     499<tt><font size="+1"><b>(:refdef type name)     </b></font><i>[ccldoc operator]</i></tt> 
     502Equivalent to `(`[#cd_ref :REF]` (:definition type name))` 
     509<tt><font size="+1"><b>(:term string)     </b></font><i>[ccldoc operator]</i></tt> 
     512Equivalent to `(`[#cd_ref :REF]` (:glossentry string))` 
     519<tt><font size="+1"><b>(:emphasis &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     522Equivalent to `(`[#cd_markup :MARKUP]` :emphasis . subforms)` 
     529<tt><font size="+1"><b>(:system &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     532Equivalent to `(`[#cd_markup :MARKUP]` :system . subforms)` 
     539<tt><font size="+1"><b>(:sample &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     542Equivalent to `(`[#cd_markup :MARKUP]` :sample . subforms)` 
     549<tt><font size="+1"><b>(:param &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     552Equivalent to `(`[#cd_markup :MARKUP]` :param . subforms)` 
     559<tt><font size="+1"><b>(:code &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt> 
     562Equivalent to `(`[#cd_markup :MARKUP]` :code . subforms)` 
     569<tt><font size="+1"><b>(:lbrace)     </b></font><i>[ccldoc operator]</i></tt> 
     572Equivalent to `(:quote "{")` 
     579<tt><font size="+1"><b>(:rbrace)     </b></font><i>[ccldoc operator]</i></tt> 
     582Equivalent to `(:quote "}")` 
     587=== String Syntax === #string-syntax 
     588Strings are the terminal clauses in CCLDoc expressions and define the text to be output. 
     590For convenience, strings support a syntax for embedding other clauses, in the form `{operand arguments}`. 
     591The parsing of the arguments is up to the operand, but in general consists of some operand-specific number 
     592of lisp expressions, with the rest of the arguments forming the body.  The processing of the embedded syntax 
     593can be avoided by using the [#cd_quote :QUOTE] operator. 
     595In order to support the embedded syntax, #!\{ and #!\} cannot be entered directly in an unquoted string clause. 
     596Use {lbrace} and {rbrace} instead. 
     598Blank lines (i.e. lines consisting only of whitespace characters) in string clauses are treated as paragraph breaks. 
     602== API Documentation == #api-documentation 
     606<tt><font size="+1"><b>(load-document filename &amp;key external-format) =&gt; document     </b></font><i>[Function]</i></tt> 
     609Load a CCLDoc source file and return a [#c_document DOCUMENT] object.  The file //`filename`// should 
     610consist of any number of lisp forms followed by a single CCLDoc form which should be (or expand into) 
     611a [#cd_defsection :DEFSECTION] expression.  The lisp preceding forms are processed as if by `LOAD`. 
     618<tt><font size="+1"><b>(output-docbook doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt> 
     621Takes a [#c_document DOCUMENT] object //`doc`// and creates a file in //`filename`// containing [ docbook] 
     629<tt><font size="+1"><b>(output-tracwiki doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt> 
     632Takes a [#c_document DOCUMENT] object //`doc`// and creates a file in //`filename`// containing [ Trac Wiki] 
     640<tt><font size="+1"><b>(output-ccldoc doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt> 
     643Takes a [#c_document DOCUMENT] object //`doc`// and creates a file //`filename`// containing CCLDoc 
     644source code, in effect disassembling the document.  Note that this output is mainly useful for 
     645debugging, since all the macros will have been expanded. 
     652<tt><font size="+1"><b>(def-expander name arglist [:parser-types parser-types] &amp;body body)     </b></font><i>[Macro]</i></tt> 
     655Define a CCLDoc macro.  The syntax of //`arglist`// and //`body`// is the same as for `DEFMACRO`. 
     656When the CCLDoc processor encounters a form whose `CAR` is an interned symbol with the same pname as //`name`//, 
     657the //`body`// of the expander will be invoked with the form destructured against //`arglist`//, and the returned 
     658form will be used instead. 
     660The //`parser-types`// option can be used to specify the parsing if //`name`// is used with the embedded string syntax. 
     661It should be an (unquoted) list of some number of `:lisp` symbols followed by at most one `:text` symbol. 
     662The string parser will read as many arguments as there are instances of `:lisp` using the lisp `READ` function, 
     663and then the rest of the string will be parsed as CCLDoc forms.  For example: 
     667      (def-expander :REFDEF (type name) 
     668        :parser-types (:lisp :lisp) 
     669        `(ref (definition ,type ,name))) 
     670      }}} 
     671allows the embedded syntax `{refdef type name}`, where `type` and `name` will be parsed 
     672using the lisp `READ`.  This example: 
     676      (def-expander my-markup (type &rest subforms) 
     677        :parser-types (:lisp :text) 
     678        `(markup ,type ,@subforms)) 
     679      }}} 
     680allows the embedded syntax `{markup type Arbitrary text ...}`, where `type` will 
     681be parsed using the lisp `READ`, and the rest of the form will be processed by CCLDoc and passed in as the 
     682//`subforms`// parameter to the expander. 
     689<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> 
     692Adds a new type that can be used to classify name of a [#cd_definition :DEFINITION]. 
     694//`type`// is a symbol naming the type being defined (as usual, the input package of the //`type`// symbol is 
     695ignored and the symbol is converted to a keyword during processing) 
     697//`parent-type`// is, optionally, an existing type from which the new type descends.  This is used to inherit 
     698some properties, and to help in matching references to their targets (so for example we know that a reference 
     699to `(:definition :function trace)` is applicable to `(:definition :macro trace)`, because the type 
     700`:macro` descends from `:function`. 
     702//`type-name`// the user-visible name of this type, as a string.  If not specified, it defaults to the 
     703capitalized version of the //`type`//. 
     705//`id-prefix`// is a prefix to use in generating external id's for definitions of this type. If not 
     706specified, it inherits from //`parent-type`//, ultimately defaulting to `"x_"`. 
     708//`function`// is a function of one argument which will be used to canonicalize names of this type.  The returned 
     709values will be compared using `EQUALP` to determine whether the refer to the same object. If not 
     710specified, it inherits from //`parent-type`//, ultimately defaulting to `#'identity`. 
     715== DOCUMENT Object Model == #document-object-model 
     716This section describes the structure of the [#c_document DOCUMENT] object.  You only need to read this 
     717section if you want to implement a new output format or write a document analysis tool. 
     719A CCLDoc document is a tree of [#t_clause CLAUSE] objects, rooted with a [#c_document DOCUMENT] object. 
     725<tt><font size="+1"><b>clause     </b></font><i>[Type]</i></tt> 
     728The type `clause` is a union of three types: 
     731 `STRING`:: a string represents text to be output to the document 
     735 `CLAUSE-OBJECT`:: an instance of the [#c_clause-object CLAUSE-OBJECT] class as described below 
     739 `CONS`:: a list of `STRING` or `CLAUSE-OBJECT` objects (no nested lists), representing a sequence of text 
     746=== Abstract Classes === #abstract-classes 
     750<tt><font size="+1"><b>clause-object ()     </b></font><i>[Class]</i></tt> 
     753The base class of CCLDoc objects.  The following functions are applicable to all `clause-object` instances: 
     755 [#f_clause-parent CLAUSE-PARENT][[BR]] 
     756 [#f_clause-document CLAUSE-DOCUMENT][[BR]] 
     757 [#f_section-level SECTION-LEVEL][[BR]] 
     758 [#f_clause-text CLAUSE-TEXT][[BR]] 
     766<tt><font size="+1"><b>named-clause (clause-object)     </b></font><i>[Class]</i></tt> 
     769The class of objects which can be linked to from other objects.  The following functions 
     770are applicable to `named-clause` instances: 
     772 [#f_clause-name CLAUSE-NAME][[BR]] 
     773 [#f_clause-external-id CLAUSE-EXTERNAL-ID][[BR]] 
     781<tt><font size="+1"><b>clause-with-title (clause-object)     </b></font><i>[Class]</i></tt> 
     784A mixin class that adds support for the [#f_clause-title CLAUSE-TITLE] property 
     791<tt><font size="+1"><b>clause-with-term (clause-object)     </b></font><i>[Class]</i></tt> 
     794A mixin class that adds support for the [#f_clause-term CLAUSE-TERM] property 
     801<tt><font size="+1"><b>clause-with-body (clause-object)     </b></font><i>[Class]</i></tt> 
     804A mixin class that adds support for the [#f_clause-body CLAUSE-BODY] property 
     811<tt><font size="+1"><b>clause-with-items (clause-object)     </b></font><i>[Class]</i></tt> 
     814A mixin class that adds support for the [#f_clause-items CLAUSE-ITEMS] property 
     819=== Concrete Classes === #concrete-classes 
     823<tt><font size="+1"><b>document (section)     </b></font><i>[Class]</i></tt> 
     826Class of the top-level document 
     833<tt><font size="+1"><b>index-section (section)     </b></font><i>[Class]</i></tt> 
     836Class of the index section.  The index section has no body, since it's assumed that the backend will 
     837take care of producing the section.  It contains the desired section title, and its position in the 
     838document indicates where the index chapter should go. 
     845<tt><font size="+1"><b>glossary-section (section)     </b></font><i>[Class]</i></tt> 
     848Class of the glossary section.  The body of the glossary section consists of [#c_glossentry GLOSSENTRY] 
     849objects, sorted according to the term they define 
     856<tt><font size="+1"><b>section (named-clause clause-with-title clause-with-body)     </b></font><i>[Class]</i></tt> 
     859Class of document sections 
     866<tt><font size="+1"><b>glossentry (named-clause clause-with-term clause-with-body)     </b></font><i>[Class]</i></tt> 
     869Class of glossary entries. 
     876<tt><font size="+1"><b>code-block (clause-with-body)     </b></font><i>[Class]</i></tt> 
     879Class of a block to be displayed as code with verbatim line breaks and spacing 
     886<tt><font size="+1"><b>block (clause-with-title clause-with-body)     </b></font><i>[Class]</i></tt> 
     889Class of a block, with an optional title, to be rendered offset from the main text. 
     896<tt><font size="+1"><b>para (clause-with-body)     </b></font><i>[Class]</i></tt> 
     899Class of a paragraph 
     906<tt><font size="+1"><b>docerror (clause-object)     </b></font><i>[Class]</i></tt> 
     909Class of an error message generated during processing of the document source.  The text of the error 
     910message is returned by [#f_clause-text CLAUSE-TEXT] 
     917<tt><font size="+1"><b>link (clause-with-body)     </b></font><i>[Class]</i></tt> 
     920Class of a link to a url target which is returned [#f_link-url LINK-URL].  The body of the clause is the 
     921text to be displayed.  It is guaranteed non-empty (CCLDoc fills in a default if the user 
     922didn't provide it). 
     929<tt><font size="+1"><b>table (named-clause clause-with-title clause-with-items)     </b></font><i>[Class]</i></tt> 
     932Class of a table.  The items of a `table` are a vector of [#c_row ROW] objects for the table 
     939<tt><font size="+1"><b>row (clause-with-items)     </b></font><i>[Class]</i></tt> 
     942Class of a table row.  `row` objects occur only in the [#f_clause-items CLAUSE-ITEMS] vector 
     943of a [#c_table TABLE] object.  The items of a `row` are a vector of [#c_item ITEM] objects for the columns in the row 
     950<tt><font size="+1"><b>listing (clause-with-items)     </b></font><i>[Class]</i></tt> 
     953Class of a listing.  The listing type is returned by [#f_listing-type LISTING-TYPE].  See [#cd_listing :LISTING] for the 
     954list of possible types. 
     956The items of a listing are a vector a [#c_item ITEM] objects, except for `:definition` listing type, 
     957where the items are [#c_term-item TERM-ITEM] objects. 
     964<tt><font size="+1"><b>indexed-clause (clause-with-body)     </b></font><i>[Class]</i></tt> 
     967Class of text to be both entered in document and added to index 
     974<tt><font size="+1"><b>markup (clause-with-body)     </b></font><i>[Class]</i></tt> 
     977Class of text to have markup applied.  The markup type is returned by [#f_markup-type MARKUP-TYPE].  See [#cd_markup :MARKUP] for 
     978the list of possible types 
     985<tt><font size="+1"><b>item (clause-with-body)     </b></font><i>[Class]</i></tt> 
     988Class of text which occurs as an item in a table [#c_row ROW] or a [#c_listing LISTING] 
     995<tt><font size="+1"><b>item (clause-with-term clause-with-body)     </b></font><i>[Class]</i></tt> 
     998Class of text which occurs only in [#c_listing LISTING] objects of type `:definition` 
     1005<tt><font size="+1"><b>xref (indexed-clause)     </b></font><i>[Class]</i></tt> 
     1008Class of a link to another object in the document.  The function [#f_xref-target XREF-TARGET] returns the 
     1009object that is the target of the reference.  The clause body is what the user specified as the text of the 
     1010link.  It may be `NIL` if the user didn't specify any text, in which case the function 
     1011[#f_xref-default-body XREF-DEFAULT-BODY] will return default text computed by CCLDoc. 
     1018<tt><font size="+1"><b>definition (named-clause clause-with-body)     </b></font><i>[Class]</i></tt> 
     1021Class of a definition.  The clause body is the full description of the definition.  The function 
     1022[#f_definition-signature DEFINITION-SIGNATURE] returns the signature of the definition and [#f_definition-summary DEFINITION-SUMMARY] 
     1023returns the summary.  [#f_definition-display-name DEFINITION-DISPLAY-NAME] returns a user-visible version of the definition name. 
     1028=== Accessor Functions === #accessor-functions 
     1032<tt><font size="+1"><b>(clause-text clause) =&gt; string     </b></font><i>[Function]</i></tt> 
     1035Returns the text of the //`clause`// with all markup removed. 
     1042<tt><font size="+1"><b>(section-level clause-object) =&gt; integer     </b></font><i>[Function]</i></tt> 
     1045Returns the level of the section containing //`clause-object`//.  The document is level 0 
     1052<tt><font size="+1"><b>(clause-document clause-object) =&gt; document     </b></font><i>[Function]</i></tt> 
     1055Returns the document containing the //`clause-object`// 
     1062<tt><font size="+1"><b>(clause-parent clause-object) =&gt; clause-object-or-nil     </b></font><i>[Function]</i></tt> 
     1065Returns the clause containing //`clause-object`//, or `NIL` if //`clause-object`// is the document 
     1072<tt><font size="+1"><b>(clause-name named-clause) =&gt; name     </b></font><i>[Function]</i></tt> 
     1075Returns the name of the //`named-clause`//.  The name is a lisp object uniquely identifying the clause 
     1076when compared with `EQUALP`. When //`named-clause`// is a [#c_glossentry GLOSSENTRY], the name is  
     1077a string, the text of the term being defined by the entry.  When //`named-clause`// is a [#c_section SECTION], 
     1078the name is a `CONS` whose `CAR` is the title of the section and whose `CDR` is the 
     1079clause-name of the section's parent clause.  When //`named-clause`// is a [#c_definition DEFINITION], 
     1080the name is a [#c_dspec DSPEC] as described in [#definition-names Definition names]. 
     1087<tt><font size="+1"><b>(clause-external-id named-clause) =&gt; string     </b></font><i>[Function]</i></tt> 
     1090Returns a string uniquely identifying the //`named-clause`//.  The string starts with 
     1091a letter and contains only letters, numbers, underscores, dashes, and periods 
     1098<tt><font size="+1"><b>(clause-title clause-with-title) =&gt; string-or-nil     </b></font><i>[Function]</i></tt> 
     1101Returns the clause title.  When //`clause-with-title`// is a [#c_named-clause NAMED-CLAUSE], the title 
     1102is required and hence the value will not be `nil`.  When //`clause-with-title`// is a [#c_block BLOCK], 
     1103the title may be `nil`. 
     1110<tt><font size="+1"><b>(clause-term clause-with-term) =&gt; clause-or-nil     </b></font><i>[Function]</i></tt> 
     1113Returns the term clause 
     1120<tt><font size="+1"><b>(clause-body clause-with-body) =&gt; clause-or-nil     </b></font><i>[Function]</i></tt> 
     1123Returns the body clause 
     1130<tt><font size="+1"><b>(clause-items clause-with-items) =&gt; vector     </b></font><i>[Function]</i></tt> 
     1133Returns a vector.  When //`clause-with-items`// is a [#c_table TABLE], the returned vector is a 
     1134vector of [#c_row ROW] objects.  When //`clause-with-items`// is a [#c_row ROW], or it is 
     1135a [#c_listing LISTING] of type other than `:definition`, then the vector is a vector of [#c_item ITEM] 
     1136objects.  When //`clause-with-items`// is a [#c_listing LISTING] of type `:definition`, the 
     1137vector is a vector of [#c_term-item TERM-ITEM] objects. 
     1144<tt><font size="+1"><b>(markup-type markup) =&gt; markup-type     </b></font><i>[Function]</i></tt> 
     1147Returns the markup type.  See [#cd_markup :MARKUP] operator for the list of possible types 
     1154<tt><font size="+1"><b>(listing-type listing) =&gt; listing-type     </b></font><i>[Function]</i></tt> 
     1157Returns the listing type.  See [#cd_listing :LISTING] operator for the list of possible types 
     1164<tt><font size="+1"><b>(definition-display-name definition) =&gt; clause     </b></font><i>[Function]</i></tt> 
     1167Returns a user-visible version of the definition name. 
     1174<tt><font size="+1"><b>(definition-summary definition) =&gt; clause     </b></font><i>[Function]</i></tt> 
     1177Returns the definition summary 
     1184<tt><font size="+1"><b>(definition-signature definition) =&gt; clause     </b></font><i>[Function]</i></tt> 
     1187Returns the definition signature 
     1194<tt><font size="+1"><b>(link-url link) =&gt; string     </b></font><i>[Function]</i></tt> 
     1197Returns the url that is the target of this link 
     1204<tt><font size="+1"><b>(xref-target xref) =&gt; named-object     </b></font><i>[Function]</i></tt> 
     1207Returns the target of the reference 
     1214<tt><font size="+1"><b>(xref-default-body link) =&gt; clause     </b></font><i>[Function]</i></tt> 
     1217Returns the default body for the reference that can be used when the user didn't specify one 
     1222=== Definition Names === #definition-names 
     1226<tt><font size="+1"><b>dspec ()     </b></font><i>[Class]</i></tt> 
     1229The type of the value returned by [#f_clause-name CLAUSE-NAME] for [#c_definition DEFINITION] objects. Encodes the name and type of 
     1230the definition 
     1237<tt><font size="+1"><b>(dspec-type dspec) =&gt; definition-type     </b></font><i>[Function]</i></tt> 
     1240The type of the definition named by //`dspec`//.  See [#cd_definition :DEFINITION] for 
     1241a discussion of definition types 
     1248<tt><font size="+1"><b>(dspec-name dspec) =&gt; definition-name     </b></font><i>[Function]</i></tt> 
     1251The name of the definition named by //`dspec`//.  See [#cd_definition :DEFINITION] for 
     1252a discussion of definition names 
     1259<tt><font size="+1"><b>(dspec-type-name dspec) =&gt; string     </b></font><i>[Function]</i></tt> 
     1262A user-visible version of the definition type