Changes between Initial Version and Version 1 of CCLDocOverview


Ignore:
Timestamp:
Oct 13, 2014, 10:56:18 PM (5 years ago)
Author:
rme
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CCLDocOverview

    v1 v1  
     1[[PageOutline]]
     2
     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.
     9
     10All the symbols referenced in this section without an explicit package prefix are external
     11in the `:CCLDOC` package.
     12
     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[http://docbook.org docbook] output, [#f_output-tracwiki OUTPUT-TRACWIKI] generates [http://trac.edgewall.org/wiki Trac Wiki]
     17output, and [#f_output-ccldoc OUTPUT-CCLDOC] generates CCLDoc source output.
     18
     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
     24
     25
     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.
     33
     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].
     38
     39=== Basic Operators === #basic-operators
     40[=#cd_include-file]
     41{{{
     42#!html
     43<tt><font size="+1"><b>(:include-file filename &amp;key in-package external-format)     </b></font><i>[ccldoc operator]</i></tt>
     44}}}
     45
     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.
     50
     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
     54
     55
     56
     57[=#cd_defsection]
     58{{{
     59#!html
     60<tt><font size="+1"><b>(:defsection title &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     61}}}
     62
     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].
     68
     69
     70
     71[=#cd_index-section]
     72{{{
     73#!html
     74<tt><font size="+1"><b>(:index-section title)     </b></font><i>[ccldoc operator]</i></tt>
     75}}}
     76
     77Placed at the top-level of the document to specify the title and location of the index
     78
     79
     80
     81[=#cd_glossary-section]
     82{{{
     83#!html
     84<tt><font size="+1"><b>(:glossary-section title &amp;rest glossentries)     </b></font><i>[ccldoc operator]</i></tt>
     85}}}
     86
     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
     90
     91
     92
     93[=#cd_block]
     94{{{
     95#!html
     96<tt><font size="+1"><b>(:block title &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     97}}}
     98
     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.
     102
     103
     104
     105[=#cd_code-block]
     106{{{
     107#!html
     108<tt><font size="+1"><b>(:code-block &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     109}}}
     110
     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.
     114
     115
     116
     117[=#cd_table]
     118{{{
     119#!html
     120<tt><font size="+1"><b>(:table title head-row &amp;rest rows)     </b></font><i>[ccldoc operator]</i></tt>
     121}}}
     122
     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].
     126
     127
     128
     129[=#cd_glossentry]
     130{{{
     131#!html
     132<tt><font size="+1"><b>(:glossentry term &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     133}}}
     134
     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].
     140
     141
     142
     143[=#cd_definition]
     144{{{
     145#!html
     146<tt><font size="+1"><b>(:definition (type name) signature summary &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     147}}}
     148
     149A definition block - unit of reference documentation describing a single global lisp name.
     150
     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`.
     157
     158//`signature`// is the syntactic synopsis of the definition.
     159
     160 **Note**
     161 
     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
     165 
     166 
     167
     168//`summary`// is a concise one line summary of the functionality being defined.
     169
     170The //`subforms`// provide a more detailed description.
     171
     172The following //`type`// values are supported by default.  Additional types can be defined via
     173[#m_def-definition-type DEF-DEFINITION-TYPE].
     174
     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]]
     190
     191
     192
     193
     194
     195
     196[=#cd_row]
     197{{{
     198#!html
     199<tt><font size="+1"><b>(:row &amp;rest items)     </b></font><i>[ccldoc operator]</i></tt>
     200}}}
     201
     202For use within [#cd_table :TABLE] only, defines a single row in the table as a sequence of [#cd_item :ITEM]
     203expresssions
     204
     205
     206
     207[=#cd_listing]
     208{{{
     209#!html
     210<tt><font size="+1"><b>(:listing type &amp;rest items)     </b></font><i>[ccldoc operator]</i></tt>
     211}}}
     212
     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:
     216
     217 
     218 `:bullet`:: A list in which item is marked with a character such as a bullet
     219   
     220   
     221 
     222 `:number`:: A list in which each item is marked with a sequentially incremented label
     223   
     224   
     225 
     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
     228   
     229   
     230 
     231 `:column`:: A simple undecorated column, typically of single words or phrases
     232   
     233   
     234
     235
     236
     237
     238[=#cd_para]
     239{{{
     240#!html
     241<tt><font size="+1"><b>(:para &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     242}}}
     243
     244A paragraph.
     245
     246
     247
     248[=#cd_item]
     249{{{
     250#!html
     251<tt><font size="+1"><b>(:item &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     252}}}
     253
     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:
     257
     258`(item "An " (emphasis "important") " item" => "An item which is very important")`
     259
     260As usual, the input package of `=>` is ignored, so it can be entered with or without the colon.
     261
     262
     263
     264[=#cd_index]
     265{{{
     266#!html
     267<tt><font size="+1"><b>(:index &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     268}}}
     269
     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.
     272
     273
     274
     275[=#cd_clause]
     276{{{
     277#!html
     278<tt><font size="+1"><b>(:clause &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     279}}}
     280
     281Much like the lisp `PROGN` operator,  makes a single expressions from a sequence of them.
     282
     283
     284
     285[=#cd_link]
     286{{{
     287#!html
     288<tt><font size="+1"><b>(:link url &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     289}}}
     290
     291Makes the text specified by //`subforms`// into a link to the url //`url`//.  If no //`subforms`//
     292is specified, the //`url`// becomes the text.
     293
     294
     295
     296[=#cd_quote]
     297{{{
     298#!html
     299<tt><font size="+1"><b>(:quote string)     </b></font><i>[ccldoc operator]</i></tt>
     300}}}
     301
     302Specifies that //`string`// is to be used literally, without being interpreted as described in [#string-syntax String Syntax].
     303
     304
     305
     306[=#cd_markup]
     307{{{
     308#!html
     309<tt><font size="+1"><b>(:markup type &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     310}}}
     311
     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
     314supported:
     315
     316 
     317 `:emphasis`:: Emphasized text, usually rendered in in italics or boldface
     318   
     319   
     320 
     321 `:code`:: Literal lisp code, usually rendered in fixed width font
     322   
     323   
     324 
     325 `:param`:: Parameter name
     326   
     327   
     328 
     329 `:sample`:: Content that should be replaced by a value
     330   
     331   
     332 
     333 `:system`:: Operating system construct, for example a shell command or environment variable
     334   
     335   
     336
     337
     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") ")"`.
     341
     342
     343
     344[=#cd_ref]
     345{{{
     346#!html
     347<tt><font size="+1"><b>(:ref target &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     348}}}
     349
     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.
     353
     354The //`target`// name can take one of the following forms:
     355
     356 
     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
     359   
     360   
     361 
     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.
     365   
     366   
     367 
     368 `(:glossentry term)`:: Targets a [#cd_glossentry :GLOSSENTRY] block defining the given //`term`//.
     369   
     370   
     371 
     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)`.
     377   
     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.
     382   
     383   
     384 
     385 `(:table title [:in parent-target ...])`:: Targets a [#cd_table :TABLE].  Syntax is the same as
     386   for `:section`.
     387   
     388   
     389 
     390 `:index` or `(:section :index)`:: Targets the index section
     391   
     392   
     393 
     394 `:glossary` or `(:section :glossary)`:: Targets the glossary section
     395   
     396   
     397 
     398 `(:chapter title)`:: Equivalent to `(:section title :in :document)`
     399   
     400   
     401
     402
     403
     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.
     406
     407
     408
     409
     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].
     413
     414[=#cd_document]
     415{{{
     416#!html
     417<tt><font size="+1"><b>(:document title &amp;rest sections)     </b></font><i>[ccldoc operator]</i></tt>
     418}}}
     419
     420Equivalent to `(`[#cd_section :SECTION]` title . sections)`
     421
     422
     423
     424[=#cd_chapter]
     425{{{
     426#!html
     427<tt><font size="+1"><b>(:chapter title &amp;rest sections)     </b></font><i>[ccldoc operator]</i></tt>
     428}}}
     429
     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))`
     433
     434
     435
     436[=#cd_section]
     437{{{
     438#!html
     439<tt><font size="+1"><b>(:section title &amp;rest parent-spec)     </b></font><i>[ccldoc operator]</i></tt>
     440}}}
     441
     442Equivalent to  `(`[#cd_ref :REF]` (:section title . parent-specs))`.
     443
     444
     445
     446[=#cd_variable]
     447{{{
     448#!html
     449<tt><font size="+1"><b>(:variable symbol)     </b></font><i>[ccldoc operator]</i></tt>
     450}}}
     451
     452Equivalent to `(`[#cd_ref :REF]` (:definition :variable symbol))`
     453
     454
     455
     456[=#cd_function]
     457{{{
     458#!html
     459<tt><font size="+1"><b>(:function fspec)     </b></font><i>[ccldoc operator]</i></tt>
     460}}}
     461
     462Equivalent to `(`[#cd_ref :REF]` (:definition :function fspec))`
     463
     464
     465
     466[=#cd_macro]
     467{{{
     468#!html
     469<tt><font size="+1"><b>(:macro symbol)     </b></font><i>[ccldoc operator]</i></tt>
     470}}}
     471
     472Equivalent to `(`[#cd_ref :REF]` (:definition :macro symbol))`
     473
     474
     475
     476[=#cd_class]
     477{{{
     478#!html
     479<tt><font size="+1"><b>(:class symbol)     </b></font><i>[ccldoc operator]</i></tt>
     480}}}
     481
     482Equivalent to `(`[#cd_ref :REF]` (:definition :class symbol))`
     483
     484
     485
     486[=#cd_type]
     487{{{
     488#!html
     489<tt><font size="+1"><b>(:type tspec)     </b></font><i>[ccldoc operator]</i></tt>
     490}}}
     491
     492Equivalent to `(`[#cd_ref :REF]` (:definition :type tspec))`
     493
     494
     495
     496[=#cd_refdef]
     497{{{
     498#!html
     499<tt><font size="+1"><b>(:refdef type name)     </b></font><i>[ccldoc operator]</i></tt>
     500}}}
     501
     502Equivalent to `(`[#cd_ref :REF]` (:definition type name))`
     503
     504
     505
     506[=#cd_term]
     507{{{
     508#!html
     509<tt><font size="+1"><b>(:term string)     </b></font><i>[ccldoc operator]</i></tt>
     510}}}
     511
     512Equivalent to `(`[#cd_ref :REF]` (:glossentry string))`
     513
     514
     515
     516[=#cd_emphasis]
     517{{{
     518#!html
     519<tt><font size="+1"><b>(:emphasis &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     520}}}
     521
     522Equivalent to `(`[#cd_markup :MARKUP]` :emphasis . subforms)`
     523
     524
     525
     526[=#cd_system]
     527{{{
     528#!html
     529<tt><font size="+1"><b>(:system &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     530}}}
     531
     532Equivalent to `(`[#cd_markup :MARKUP]` :system . subforms)`
     533
     534
     535
     536[=#cd_sample]
     537{{{
     538#!html
     539<tt><font size="+1"><b>(:sample &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     540}}}
     541
     542Equivalent to `(`[#cd_markup :MARKUP]` :sample . subforms)`
     543
     544
     545
     546[=#cd_param]
     547{{{
     548#!html
     549<tt><font size="+1"><b>(:param &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     550}}}
     551
     552Equivalent to `(`[#cd_markup :MARKUP]` :param . subforms)`
     553
     554
     555
     556[=#cd_code]
     557{{{
     558#!html
     559<tt><font size="+1"><b>(:code &amp;rest subforms)     </b></font><i>[ccldoc operator]</i></tt>
     560}}}
     561
     562Equivalent to `(`[#cd_markup :MARKUP]` :code . subforms)`
     563
     564
     565
     566[=#cd_lbrace]
     567{{{
     568#!html
     569<tt><font size="+1"><b>(:lbrace)     </b></font><i>[ccldoc operator]</i></tt>
     570}}}
     571
     572Equivalent to `(:quote "{")`
     573
     574
     575
     576[=#cd_rbrace]
     577{{{
     578#!html
     579<tt><font size="+1"><b>(:rbrace)     </b></font><i>[ccldoc operator]</i></tt>
     580}}}
     581
     582Equivalent to `(:quote "}")`
     583
     584
     585
     586
     587=== String Syntax === #string-syntax
     588Strings are the terminal clauses in CCLDoc expressions and define the text to be output.
     589
     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.
     594
     595In order to support the embedded syntax, #!\{ and #!\} cannot be entered directly in an unquoted string clause.
     596Use {lbrace} and {rbrace} instead.
     597
     598Blank lines (i.e. lines consisting only of whitespace characters) in string clauses are treated as paragraph breaks.
     599
     600
     601
     602== API Documentation == #api-documentation
     603[=#f_load-document]
     604{{{
     605#!html
     606<tt><font size="+1"><b>(load-document filename &amp;key external-format) =&gt; document     </b></font><i>[Function]</i></tt>
     607}}}
     608
     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`.
     612
     613
     614
     615[=#f_output-docbook]
     616{{{
     617#!html
     618<tt><font size="+1"><b>(output-docbook doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt>
     619}}}
     620
     621Takes a [#c_document DOCUMENT] object //`doc`// and creates a file in //`filename`// containing [http://docbook.org docbook]
     622source.
     623
     624
     625
     626[=#f_output-tracwiki]
     627{{{
     628#!html
     629<tt><font size="+1"><b>(output-tracwiki doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt>
     630}}}
     631
     632Takes a [#c_document DOCUMENT] object //`doc`// and creates a file in //`filename`// containing [http://trac.edgewall.org/wiki Trac Wiki]
     633source.
     634
     635
     636
     637[=#f_output-ccldoc]
     638{{{
     639#!html
     640<tt><font size="+1"><b>(output-ccldoc doc filename &amp;key external-format if-exists)     </b></font><i>[Function]</i></tt>
     641}}}
     642
     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.
     646
     647
     648
     649[=#m_def-expander]
     650{{{
     651#!html
     652<tt><font size="+1"><b>(def-expander name arglist [:parser-types parser-types] &amp;body body)     </b></font><i>[Macro]</i></tt>
     653}}}
     654
     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.
     659
     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:
     664
     665
     666{{{
     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:
     673
     674
     675{{{
     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.
     683
     684
     685
     686[=#m_def-definition-type]
     687{{{
     688#!html
     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>
     690}}}
     691
     692Adds a new type that can be used to classify name of a [#cd_definition :DEFINITION].
     693
     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)
     696
     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`.
     701
     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`//.
     704
     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_"`.
     707
     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`.
     711
     712
     713
     714
     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.
     718
     719A CCLDoc document is a tree of [#t_clause CLAUSE] objects, rooted with a [#c_document DOCUMENT] object.
     720
     721
     722[=#t_clause]
     723{{{
     724#!html
     725<tt><font size="+1"><b>clause     </b></font><i>[Type]</i></tt>
     726}}}
     727
     728The type `clause` is a union of three types:
     729
     730 
     731 `STRING`:: a string represents text to be output to the document
     732   
     733   
     734 
     735 `CLAUSE-OBJECT`:: an instance of the [#c_clause-object CLAUSE-OBJECT] class as described below
     736   
     737   
     738 
     739 `CONS`:: a list of `STRING` or `CLAUSE-OBJECT` objects (no nested lists), representing a sequence of text
     740   
     741   
     742
     743
     744
     745
     746=== Abstract Classes === #abstract-classes
     747[=#c_clause-object]
     748{{{
     749#!html
     750<tt><font size="+1"><b>clause-object ()     </b></font><i>[Class]</i></tt>
     751}}}
     752
     753The base class of CCLDoc objects.  The following functions are applicable to all `clause-object` instances:
     754
     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]]
     759
     760
     761
     762
     763[=#c_named-clause]
     764{{{
     765#!html
     766<tt><font size="+1"><b>named-clause (clause-object)     </b></font><i>[Class]</i></tt>
     767}}}
     768
     769The class of objects which can be linked to from other objects.  The following functions
     770are applicable to `named-clause` instances:
     771
     772 [#f_clause-name CLAUSE-NAME][[BR]]
     773 [#f_clause-external-id CLAUSE-EXTERNAL-ID][[BR]]
     774
     775
     776
     777
     778[=#c_clause-with-title]
     779{{{
     780#!html
     781<tt><font size="+1"><b>clause-with-title (clause-object)     </b></font><i>[Class]</i></tt>
     782}}}
     783
     784A mixin class that adds support for the [#f_clause-title CLAUSE-TITLE] property
     785
     786
     787
     788[=#c_clause-with-term]
     789{{{
     790#!html
     791<tt><font size="+1"><b>clause-with-term (clause-object)     </b></font><i>[Class]</i></tt>
     792}}}
     793
     794A mixin class that adds support for the [#f_clause-term CLAUSE-TERM] property
     795
     796
     797
     798[=#c_clause-with-body]
     799{{{
     800#!html
     801<tt><font size="+1"><b>clause-with-body (clause-object)     </b></font><i>[Class]</i></tt>
     802}}}
     803
     804A mixin class that adds support for the [#f_clause-body CLAUSE-BODY] property
     805
     806
     807
     808[=#c_clause-with-items]
     809{{{
     810#!html
     811<tt><font size="+1"><b>clause-with-items (clause-object)     </b></font><i>[Class]</i></tt>
     812}}}
     813
     814A mixin class that adds support for the [#f_clause-items CLAUSE-ITEMS] property
     815
     816
     817
     818
     819=== Concrete Classes === #concrete-classes
     820[=#c_document]
     821{{{
     822#!html
     823<tt><font size="+1"><b>document (section)     </b></font><i>[Class]</i></tt>
     824}}}
     825
     826Class of the top-level document
     827
     828
     829
     830[=#c_index-section]
     831{{{
     832#!html
     833<tt><font size="+1"><b>index-section (section)     </b></font><i>[Class]</i></tt>
     834}}}
     835
     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.
     839
     840
     841
     842[=#c_glossary-section]
     843{{{
     844#!html
     845<tt><font size="+1"><b>glossary-section (section)     </b></font><i>[Class]</i></tt>
     846}}}
     847
     848Class of the glossary section.  The body of the glossary section consists of [#c_glossentry GLOSSENTRY]
     849objects, sorted according to the term they define
     850
     851
     852
     853[=#c_section]
     854{{{
     855#!html
     856<tt><font size="+1"><b>section (named-clause clause-with-title clause-with-body)     </b></font><i>[Class]</i></tt>
     857}}}
     858
     859Class of document sections
     860
     861
     862
     863[=#c_glossentry]
     864{{{
     865#!html
     866<tt><font size="+1"><b>glossentry (named-clause clause-with-term clause-with-body)     </b></font><i>[Class]</i></tt>
     867}}}
     868
     869Class of glossary entries.
     870
     871
     872
     873[=#c_code-block]
     874{{{
     875#!html
     876<tt><font size="+1"><b>code-block (clause-with-body)     </b></font><i>[Class]</i></tt>
     877}}}
     878
     879Class of a block to be displayed as code with verbatim line breaks and spacing
     880
     881
     882
     883[=#c_block]
     884{{{
     885#!html
     886<tt><font size="+1"><b>block (clause-with-title clause-with-body)     </b></font><i>[Class]</i></tt>
     887}}}
     888
     889Class of a block, with an optional title, to be rendered offset from the main text.
     890
     891
     892
     893[=#c_para]
     894{{{
     895#!html
     896<tt><font size="+1"><b>para (clause-with-body)     </b></font><i>[Class]</i></tt>
     897}}}
     898
     899Class of a paragraph
     900
     901
     902
     903[=#c_docerror]
     904{{{
     905#!html
     906<tt><font size="+1"><b>docerror (clause-object)     </b></font><i>[Class]</i></tt>
     907}}}
     908
     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]
     911
     912
     913
     914[=#c_link]
     915{{{
     916#!html
     917<tt><font size="+1"><b>link (clause-with-body)     </b></font><i>[Class]</i></tt>
     918}}}
     919
     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).
     923
     924
     925
     926[=#c_table]
     927{{{
     928#!html
     929<tt><font size="+1"><b>table (named-clause clause-with-title clause-with-items)     </b></font><i>[Class]</i></tt>
     930}}}
     931
     932Class of a table.  The items of a `table` are a vector of [#c_row ROW] objects for the table
     933
     934
     935
     936[=#c_row]
     937{{{
     938#!html
     939<tt><font size="+1"><b>row (clause-with-items)     </b></font><i>[Class]</i></tt>
     940}}}
     941
     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
     944
     945
     946
     947[=#c_listing]
     948{{{
     949#!html
     950<tt><font size="+1"><b>listing (clause-with-items)     </b></font><i>[Class]</i></tt>
     951}}}
     952
     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.
     955
     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.
     958
     959
     960
     961[=#c_indexed-clause]
     962{{{
     963#!html
     964<tt><font size="+1"><b>indexed-clause (clause-with-body)     </b></font><i>[Class]</i></tt>
     965}}}
     966
     967Class of text to be both entered in document and added to index
     968
     969
     970
     971[=#c_markup]
     972{{{
     973#!html
     974<tt><font size="+1"><b>markup (clause-with-body)     </b></font><i>[Class]</i></tt>
     975}}}
     976
     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
     979
     980
     981
     982[=#c_item]
     983{{{
     984#!html
     985<tt><font size="+1"><b>item (clause-with-body)     </b></font><i>[Class]</i></tt>
     986}}}
     987
     988Class of text which occurs as an item in a table [#c_row ROW] or a [#c_listing LISTING]
     989
     990
     991
     992[=#c_term-item]
     993{{{
     994#!html
     995<tt><font size="+1"><b>item (clause-with-term clause-with-body)     </b></font><i>[Class]</i></tt>
     996}}}
     997
     998Class of text which occurs only in [#c_listing LISTING] objects of type `:definition`
     999
     1000
     1001
     1002[=#c_xref]
     1003{{{
     1004#!html
     1005<tt><font size="+1"><b>xref (indexed-clause)     </b></font><i>[Class]</i></tt>
     1006}}}
     1007
     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.
     1012
     1013
     1014
     1015[=#c_definition]
     1016{{{
     1017#!html
     1018<tt><font size="+1"><b>definition (named-clause clause-with-body)     </b></font><i>[Class]</i></tt>
     1019}}}
     1020
     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.
     1024
     1025
     1026
     1027
     1028=== Accessor Functions === #accessor-functions
     1029[=#f_clause-text]
     1030{{{
     1031#!html
     1032<tt><font size="+1"><b>(clause-text clause) =&gt; string     </b></font><i>[Function]</i></tt>
     1033}}}
     1034
     1035Returns the text of the //`clause`// with all markup removed.
     1036
     1037
     1038
     1039[=#f_section-level]
     1040{{{
     1041#!html
     1042<tt><font size="+1"><b>(section-level clause-object) =&gt; integer     </b></font><i>[Function]</i></tt>
     1043}}}
     1044
     1045Returns the level of the section containing //`clause-object`//.  The document is level 0
     1046
     1047
     1048
     1049[=#f_clause-document]
     1050{{{
     1051#!html
     1052<tt><font size="+1"><b>(clause-document clause-object) =&gt; document     </b></font><i>[Function]</i></tt>
     1053}}}
     1054
     1055Returns the document containing the //`clause-object`//
     1056
     1057
     1058
     1059[=#f_clause-parent]
     1060{{{
     1061#!html
     1062<tt><font size="+1"><b>(clause-parent clause-object) =&gt; clause-object-or-nil     </b></font><i>[Function]</i></tt>
     1063}}}
     1064
     1065Returns the clause containing //`clause-object`//, or `NIL` if //`clause-object`// is the document
     1066
     1067
     1068
     1069[=#f_clause-name]
     1070{{{
     1071#!html
     1072<tt><font size="+1"><b>(clause-name named-clause) =&gt; name     </b></font><i>[Function]</i></tt>
     1073}}}
     1074
     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].
     1081
     1082
     1083
     1084[=#f_clause-external-id]
     1085{{{
     1086#!html
     1087<tt><font size="+1"><b>(clause-external-id named-clause) =&gt; string     </b></font><i>[Function]</i></tt>
     1088}}}
     1089
     1090Returns a string uniquely identifying the //`named-clause`//.  The string starts with
     1091a letter and contains only letters, numbers, underscores, dashes, and periods
     1092
     1093
     1094
     1095[=#f_clause-title]
     1096{{{
     1097#!html
     1098<tt><font size="+1"><b>(clause-title clause-with-title) =&gt; string-or-nil     </b></font><i>[Function]</i></tt>
     1099}}}
     1100
     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`.
     1104
     1105
     1106
     1107[=#f_clause-term]
     1108{{{
     1109#!html
     1110<tt><font size="+1"><b>(clause-term clause-with-term) =&gt; clause-or-nil     </b></font><i>[Function]</i></tt>
     1111}}}
     1112
     1113Returns the term clause
     1114
     1115
     1116
     1117[=#f_clause-body]
     1118{{{
     1119#!html
     1120<tt><font size="+1"><b>(clause-body clause-with-body) =&gt; clause-or-nil     </b></font><i>[Function]</i></tt>
     1121}}}
     1122
     1123Returns the body clause
     1124
     1125
     1126
     1127[=#f_clause-items]
     1128{{{
     1129#!html
     1130<tt><font size="+1"><b>(clause-items clause-with-items) =&gt; vector     </b></font><i>[Function]</i></tt>
     1131}}}
     1132
     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.
     1138
     1139
     1140
     1141[=#f_markup-type]
     1142{{{
     1143#!html
     1144<tt><font size="+1"><b>(markup-type markup) =&gt; markup-type     </b></font><i>[Function]</i></tt>
     1145}}}
     1146
     1147Returns the markup type.  See [#cd_markup :MARKUP] operator for the list of possible types
     1148
     1149
     1150
     1151[=#f_listing-type]
     1152{{{
     1153#!html
     1154<tt><font size="+1"><b>(listing-type listing) =&gt; listing-type     </b></font><i>[Function]</i></tt>
     1155}}}
     1156
     1157Returns the listing type.  See [#cd_listing :LISTING] operator for the list of possible types
     1158
     1159
     1160
     1161[=#f_definition-display-name]
     1162{{{
     1163#!html
     1164<tt><font size="+1"><b>(definition-display-name definition) =&gt; clause     </b></font><i>[Function]</i></tt>
     1165}}}
     1166
     1167Returns a user-visible version of the definition name.
     1168
     1169
     1170
     1171[=#f_definition-summary]
     1172{{{
     1173#!html
     1174<tt><font size="+1"><b>(definition-summary definition) =&gt; clause     </b></font><i>[Function]</i></tt>
     1175}}}
     1176
     1177Returns the definition summary
     1178
     1179
     1180
     1181[=#f_definition-signature]
     1182{{{
     1183#!html
     1184<tt><font size="+1"><b>(definition-signature definition) =&gt; clause     </b></font><i>[Function]</i></tt>
     1185}}}
     1186
     1187Returns the definition signature
     1188
     1189
     1190
     1191[=#f_link-url]
     1192{{{
     1193#!html
     1194<tt><font size="+1"><b>(link-url link) =&gt; string     </b></font><i>[Function]</i></tt>
     1195}}}
     1196
     1197Returns the url that is the target of this link
     1198
     1199
     1200
     1201[=#f_xref-target]
     1202{{{
     1203#!html
     1204<tt><font size="+1"><b>(xref-target xref) =&gt; named-object     </b></font><i>[Function]</i></tt>
     1205}}}
     1206
     1207Returns the target of the reference
     1208
     1209
     1210
     1211[=#f_xref-default-body]
     1212{{{
     1213#!html
     1214<tt><font size="+1"><b>(xref-default-body link) =&gt; clause     </b></font><i>[Function]</i></tt>
     1215}}}
     1216
     1217Returns the default body for the reference that can be used when the user didn't specify one
     1218
     1219
     1220
     1221
     1222=== Definition Names === #definition-names
     1223[=#c_dspec]
     1224{{{
     1225#!html
     1226<tt><font size="+1"><b>dspec ()     </b></font><i>[Class]</i></tt>
     1227}}}
     1228
     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
     1231
     1232
     1233
     1234[=#f_dspec-type]
     1235{{{
     1236#!html
     1237<tt><font size="+1"><b>(dspec-type dspec) =&gt; definition-type     </b></font><i>[Function]</i></tt>
     1238}}}
     1239
     1240The type of the definition named by //`dspec`//.  See [#cd_definition :DEFINITION] for
     1241a discussion of definition types
     1242
     1243
     1244
     1245[=#f_dspec-name]
     1246{{{
     1247#!html
     1248<tt><font size="+1"><b>(dspec-name dspec) =&gt; definition-name     </b></font><i>[Function]</i></tt>
     1249}}}
     1250
     1251The name of the definition named by //`dspec`//.  See [#cd_definition :DEFINITION] for
     1252a discussion of definition names
     1253
     1254
     1255
     1256[=#f_dspec-type-name]
     1257{{{
     1258#!html
     1259<tt><font size="+1"><b>(dspec-type-name dspec) =&gt; string     </b></font><i>[Function]</i></tt>
     1260}}}
     1261
     1262A user-visible version of the definition type
     1263
     1264
     1265
     1266
     1267