Changes between Initial Version and Version 1 of CCLDocOverview


Ignore:
Timestamp:
10/13/14 22:56:18 (2 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