| 1 | [[PageOutline]] |
| 2 | |
| 3 | = CCLDoc Documentation system = |
| 4 | == Overview == #overview |
| 5 | CCLDoc is a system for creating lisp documentation. It uses s-expressions to represent document |
| 6 | structure, markup, cross references, and contents. It has a small number of basic operators, supports |
| 7 | macros for syntax extensions, and supports a simple syntax for embedding expressions in strings for |
| 8 | added convenience. |
| 9 | |
| 10 | All the symbols referenced in this section without an explicit package prefix are external |
| 11 | in the `:CCLDOC` package. |
| 12 | |
| 13 | A CCLDoc document definition is processed by the [#f_load-document LOAD-DOCUMENT] function to produce |
| 14 | a [#c_document DOCUMENT] object. This object can then be processed to create other formats. |
| 15 | Currently 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] |
| 17 | output, and [#f_output-ccldoc OUTPUT-CCLDOC] generates CCLDoc source output. |
| 18 | |
| 19 | By having a small number of relatively high-level operators, CCLDoc allows the creation of |
| 20 | consistently formatted documents even when written by many different people over extended |
| 21 | periods of time. Additionally, the simple document model enables longevity by making it easy to |
| 22 | upgrade and change the back-end tools used to implement the final formatting, without having |
| 23 | to convert the document source |
| 24 | |
| 25 | |
| 26 | == Source Syntax == #source-syntax |
| 27 | A CCLDoc document is represented by an s-expression with the usual semantics: when the |
| 28 | s-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 |
| 30 | has additional internal structure as described in [#string-syntax String Syntax]. Finally, for |
| 31 | convenience, an uninterned symbol is treated the same as a string, providing an alternate |
| 32 | syntax (namely `#:| ... |`) for entering text with many double-quotes. |
| 33 | |
| 34 | CCLDoc operators are symbols. Their input package is ignored and they are converted to keywords |
| 35 | during processing (so they can be entered with or without an initial colon, as you prefer). There |
| 36 | is 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 &key in-package external-format) </b></font><i>[ccldoc operator]</i></tt> |
| 44 | }}} |
| 45 | |
| 46 | The file //`filename`// should consist of any number of lisp forms followed by |
| 47 | CCLDoc forms. The lisp forms are processed as if by `LOAD` until the first CCLDoc form |
| 48 | is encountered, after which all the remaining forms must be CCLDoc forms. The CCLDoc forms are |
| 49 | included in the document replacing the `include-file` form itself. |
| 50 | |
| 51 | The //`in-package`// parameter can be used to specify the package used to load the file, |
| 52 | and 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 61 | }}} |
| 62 | |
| 63 | A named, referenceable, block of text. A `defsection` can occur at top-level, in which |
| 64 | case it defines the document; or it can occur directly within another `defsection`, in which |
| 65 | case 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, |
| 67 | the 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 | |
| 77 | Placed 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 &rest glossentries) </b></font><i>[ccldoc operator]</i></tt> |
| 85 | }}} |
| 86 | |
| 87 | Placed at the top-level of the document to specify the title and location of the glossary. |
| 88 | It may contain [#cd_glossentry :GLOSSENTRY] definitions, although note that [#cd_glossentry :GLOSSENTRY] definitions |
| 89 | can 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 97 | }}} |
| 98 | |
| 99 | Defines a block of text set off (indented) from the main text. The //`title`// can |
| 100 | be `NIL` to create an anonymous block. Note however that even when titled, a block |
| 101 | cannot 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 109 | }}} |
| 110 | |
| 111 | A block suitable for listing of code. A fixed width font will be used to display the content, |
| 112 | and whitespace and linebreaks will be shown verbatim. Note however that markup //is// |
| 113 | allowed within code blocks. |
| 114 | |
| 115 | |
| 116 | |
| 117 | [=#cd_table] |
| 118 | {{{ |
| 119 | #!html |
| 120 | <tt><font size="+1"><b>(:table title head-row &rest rows) </b></font><i>[ccldoc operator]</i></tt> |
| 121 | }}} |
| 122 | |
| 123 | Defines a table. Tables have a sequence of [#cd_row :ROW] clauses, the first of which will |
| 124 | be formatted specially as the head row. Tables can be referred to using the //`title`//, |
| 125 | and 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 133 | }}} |
| 134 | |
| 135 | A glossary definition. //`term`// is the term being defined, and the remaining |
| 136 | clauses are the explanation of the text. A `glossentry` can appear anywhere in the |
| 137 | source document, but it doesn't get displayed where it appears - all the `glossentry` |
| 138 | forms get collected into the [#cd_glossary-section :GLOSSARY-SECTION]. Glossary entries can be referred |
| 139 | to 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 147 | }}} |
| 148 | |
| 149 | A 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 |
| 152 | in which //`name`// is interpreted. (As usual, the input package of the //`type`// symbol is |
| 153 | ignored and the symbol is converted to a keyword during processing). The //`name`// can |
| 154 | be 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 | |
| 170 | The //`subforms`// provide a more detailed description. |
| 171 | |
| 172 | The 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 &rest items) </b></font><i>[ccldoc operator]</i></tt> |
| 200 | }}} |
| 201 | |
| 202 | For use within [#cd_table :TABLE] only, defines a single row in the table as a sequence of [#cd_item :ITEM] |
| 203 | expresssions |
| 204 | |
| 205 | |
| 206 | |
| 207 | [=#cd_listing] |
| 208 | {{{ |
| 209 | #!html |
| 210 | <tt><font size="+1"><b>(:listing type &rest items) </b></font><i>[ccldoc operator]</i></tt> |
| 211 | }}} |
| 212 | |
| 213 | A listing of items specified by the //`items`// forms. //`type`// determines how the list |
| 214 | will be formatted. //`type`// names are symbols whose input package is ignored and converted to |
| 215 | keyword 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 242 | }}} |
| 243 | |
| 244 | A paragraph. |
| 245 | |
| 246 | |
| 247 | |
| 248 | [=#cd_item] |
| 249 | {{{ |
| 250 | #!html |
| 251 | <tt><font size="+1"><b>(:item &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 252 | }}} |
| 253 | |
| 254 | A single item in a [#cd_listing :LISTING] or [#cd_row :ROW] expression. It cannot be used in any other context. |
| 255 | In `: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 | |
| 260 | As 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 268 | }}} |
| 269 | |
| 270 | Request an index entry. The //`subforms`// are displayed in place, but in addition, the phrase is |
| 271 | added 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 279 | }}} |
| 280 | |
| 281 | Much 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 289 | }}} |
| 290 | |
| 291 | Makes the text specified by //`subforms`// into a link to the url //`url`//. If no //`subforms`// |
| 292 | is 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 | |
| 302 | Specifies 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 310 | }}} |
| 311 | |
| 312 | Requests that markup as specified by //`type`// should be applied to //`subforms`//. The //`type`// is named |
| 313 | by a symbol whose input package is ignored and converted to keyword during processing. The following types are |
| 314 | supported: |
| 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 | |
| 338 | The difference between `:param` and `:sample` is subtle and perhaps not worth the trouble... But the intent is |
| 339 | that `:param` be used for a name of the eventual value, whereas `:sample` be used for an example of such a value. |
| 340 | For 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 &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 348 | }}} |
| 349 | |
| 350 | Makes the text specified by //`subforms`// into a link to another part of the document as indicated by //`target`//. If |
| 351 | no //`subforms`// are specified, default text is generated based on the target. In addition, if the specified target is |
| 352 | a glossary entry or a definition, this reference to it will be listed in the index. |
| 353 | |
| 354 | The //`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 | |
| 404 | If the document doesn't actual contain a block named by //`target`//, no link will be produced, but the clause |
| 405 | will 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 |
| 411 | The following operators define more convenient ways of accessing the same functionality |
| 412 | as the basic operators described in [#basic-operators Basic Operators]. |
| 413 | |
| 414 | [=#cd_document] |
| 415 | {{{ |
| 416 | #!html |
| 417 | <tt><font size="+1"><b>(:document title &rest sections) </b></font><i>[ccldoc operator]</i></tt> |
| 418 | }}} |
| 419 | |
| 420 | Equivalent to `(`[#cd_section :SECTION]` title . sections)` |
| 421 | |
| 422 | |
| 423 | |
| 424 | [=#cd_chapter] |
| 425 | {{{ |
| 426 | #!html |
| 427 | <tt><font size="+1"><b>(:chapter title &rest sections) </b></font><i>[ccldoc operator]</i></tt> |
| 428 | }}} |
| 429 | |
| 430 | Depending on context, this either defines or references a chapter. When used at top-level of a |
| 431 | document, it is equivalent to `(`[#cd_defsection :DEFSECTION]` title . sections)`. In other contexts, |
| 432 | only 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 &rest parent-spec) </b></font><i>[ccldoc operator]</i></tt> |
| 440 | }}} |
| 441 | |
| 442 | Equivalent 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 | |
| 452 | Equivalent 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 | |
| 462 | Equivalent 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 | |
| 472 | Equivalent 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 | |
| 482 | Equivalent 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 | |
| 492 | Equivalent 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 | |
| 502 | Equivalent 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 | |
| 512 | Equivalent to `(`[#cd_ref :REF]` (:glossentry string))` |
| 513 | |
| 514 | |
| 515 | |
| 516 | [=#cd_emphasis] |
| 517 | {{{ |
| 518 | #!html |
| 519 | <tt><font size="+1"><b>(:emphasis &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 520 | }}} |
| 521 | |
| 522 | Equivalent to `(`[#cd_markup :MARKUP]` :emphasis . subforms)` |
| 523 | |
| 524 | |
| 525 | |
| 526 | [=#cd_system] |
| 527 | {{{ |
| 528 | #!html |
| 529 | <tt><font size="+1"><b>(:system &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 530 | }}} |
| 531 | |
| 532 | Equivalent to `(`[#cd_markup :MARKUP]` :system . subforms)` |
| 533 | |
| 534 | |
| 535 | |
| 536 | [=#cd_sample] |
| 537 | {{{ |
| 538 | #!html |
| 539 | <tt><font size="+1"><b>(:sample &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 540 | }}} |
| 541 | |
| 542 | Equivalent to `(`[#cd_markup :MARKUP]` :sample . subforms)` |
| 543 | |
| 544 | |
| 545 | |
| 546 | [=#cd_param] |
| 547 | {{{ |
| 548 | #!html |
| 549 | <tt><font size="+1"><b>(:param &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 550 | }}} |
| 551 | |
| 552 | Equivalent to `(`[#cd_markup :MARKUP]` :param . subforms)` |
| 553 | |
| 554 | |
| 555 | |
| 556 | [=#cd_code] |
| 557 | {{{ |
| 558 | #!html |
| 559 | <tt><font size="+1"><b>(:code &rest subforms) </b></font><i>[ccldoc operator]</i></tt> |
| 560 | }}} |
| 561 | |
| 562 | Equivalent 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 | |
| 572 | Equivalent 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 | |
| 582 | Equivalent to `(:quote "}")` |
| 583 | |
| 584 | |
| 585 | |
| 586 | |
| 587 | === String Syntax === #string-syntax |
| 588 | Strings are the terminal clauses in CCLDoc expressions and define the text to be output. |
| 589 | |
| 590 | For convenience, strings support a syntax for embedding other clauses, in the form `{operand arguments}`. |
| 591 | The parsing of the arguments is up to the operand, but in general consists of some operand-specific number |
| 592 | of lisp expressions, with the rest of the arguments forming the body. The processing of the embedded syntax |
| 593 | can be avoided by using the [#cd_quote :QUOTE] operator. |
| 594 | |
| 595 | In order to support the embedded syntax, #!\{ and #!\} cannot be entered directly in an unquoted string clause. |
| 596 | Use {lbrace} and {rbrace} instead. |
| 597 | |
| 598 | Blank 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 &key external-format) => document </b></font><i>[Function]</i></tt> |
| 607 | }}} |
| 608 | |
| 609 | Load a CCLDoc source file and return a [#c_document DOCUMENT] object. The file //`filename`// should |
| 610 | consist of any number of lisp forms followed by a single CCLDoc form which should be (or expand into) |
| 611 | a [#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 &key external-format if-exists) </b></font><i>[Function]</i></tt> |
| 619 | }}} |
| 620 | |
| 621 | Takes a [#c_document DOCUMENT] object //`doc`// and creates a file in //`filename`// containing [http://docbook.org docbook] |
| 622 | source. |
| 623 | |
| 624 | |
| 625 | |
| 626 | [=#f_output-tracwiki] |
| 627 | {{{ |
| 628 | #!html |
| 629 | <tt><font size="+1"><b>(output-tracwiki doc filename &key external-format if-exists) </b></font><i>[Function]</i></tt> |
| 630 | }}} |
| 631 | |
| 632 | Takes a [#c_document DOCUMENT] object //`doc`// and creates a file in //`filename`// containing [http://trac.edgewall.org/wiki Trac Wiki] |
| 633 | source. |
| 634 | |
| 635 | |
| 636 | |
| 637 | [=#f_output-ccldoc] |
| 638 | {{{ |
| 639 | #!html |
| 640 | <tt><font size="+1"><b>(output-ccldoc doc filename &key external-format if-exists) </b></font><i>[Function]</i></tt> |
| 641 | }}} |
| 642 | |
| 643 | Takes a [#c_document DOCUMENT] object //`doc`// and creates a file //`filename`// containing CCLDoc |
| 644 | source code, in effect disassembling the document. Note that this output is mainly useful for |
| 645 | debugging, 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] &body body) </b></font><i>[Macro]</i></tt> |
| 653 | }}} |
| 654 | |
| 655 | Define a CCLDoc macro. The syntax of //`arglist`// and //`body`// is the same as for `DEFMACRO`. |
| 656 | When the CCLDoc processor encounters a form whose `CAR` is an interned symbol with the same pname as //`name`//, |
| 657 | the //`body`// of the expander will be invoked with the form destructured against //`arglist`//, and the returned |
| 658 | form will be used instead. |
| 659 | |
| 660 | The //`parser-types`// option can be used to specify the parsing if //`name`// is used with the embedded string syntax. |
| 661 | It should be an (unquoted) list of some number of `:lisp` symbols followed by at most one `:text` symbol. |
| 662 | The string parser will read as many arguments as there are instances of `:lisp` using the lisp `READ` function, |
| 663 | and 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 | }}} |
| 671 | allows the embedded syntax `{refdef type name}`, where `type` and `name` will be parsed |
| 672 | using 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 | }}} |
| 680 | allows the embedded syntax `{markup type Arbitrary text ...}`, where `type` will |
| 681 | be 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 (&optional parent-type) &key type-name id-prefix function) </b></font><i>[Macro]</i></tt> |
| 690 | }}} |
| 691 | |
| 692 | Adds 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 |
| 695 | ignored 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 |
| 698 | some properties, and to help in matching references to their targets (so for example we know that a reference |
| 699 | to `(: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 |
| 703 | capitalized 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 |
| 706 | specified, 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 |
| 709 | values will be compared using `EQUALP` to determine whether the refer to the same object. If not |
| 710 | specified, it inherits from //`parent-type`//, ultimately defaulting to `#'identity`. |
| 711 | |
| 712 | |
| 713 | |
| 714 | |
| 715 | == DOCUMENT Object Model == #document-object-model |
| 716 | This section describes the structure of the [#c_document DOCUMENT] object. You only need to read this |
| 717 | section if you want to implement a new output format or write a document analysis tool. |
| 718 | |
| 719 | A 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 | |
| 728 | The 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 | |
| 753 | The 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 | |
| 769 | The class of objects which can be linked to from other objects. The following functions |
| 770 | are 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 | |
| 784 | A 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 | |
| 794 | A 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 | |
| 804 | A 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 | |
| 814 | A 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 | |
| 826 | Class 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 | |
| 836 | Class of the index section. The index section has no body, since it's assumed that the backend will |
| 837 | take care of producing the section. It contains the desired section title, and its position in the |
| 838 | document 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 | |
| 848 | Class of the glossary section. The body of the glossary section consists of [#c_glossentry GLOSSENTRY] |
| 849 | objects, 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 | |
| 859 | Class 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 | |
| 869 | Class 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 | |
| 879 | Class 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 | |
| 889 | Class 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 | |
| 899 | Class 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 | |
| 909 | Class of an error message generated during processing of the document source. The text of the error |
| 910 | message 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 | |
| 920 | Class of a link to a url target which is returned [#f_link-url LINK-URL]. The body of the clause is the |
| 921 | text to be displayed. It is guaranteed non-empty (CCLDoc fills in a default if the user |
| 922 | didn'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 | |
| 932 | Class 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 | |
| 942 | Class of a table row. `row` objects occur only in the [#f_clause-items CLAUSE-ITEMS] vector |
| 943 | of a [#c_table TABLE] object. The items of a `row` are a vector of [#c_item ITEM] objects for the columns in the row |
| 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 | |
| 953 | Class of a listing. The listing type is returned by [#f_listing-type LISTING-TYPE]. See [#cd_listing :LISTING] for the |
| 954 | list of possible types. |
| 955 | |
| 956 | The items of a listing are a vector a [#c_item ITEM] objects, except for `:definition` listing type, |
| 957 | where 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 | |
| 967 | Class 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 | |
| 977 | Class of text to have markup applied. The markup type is returned by [#f_markup-type MARKUP-TYPE]. See [#cd_markup :MARKUP] for |
| 978 | the 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 | |
| 988 | Class 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 | |
| 998 | Class 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 | |
| 1008 | Class of a link to another object in the document. The function [#f_xref-target XREF-TARGET] returns the |
| 1009 | object that is the target of the reference. The clause body is what the user specified as the text of the |
| 1010 | link. 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 | |
| 1021 | Class 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] |
| 1023 | returns 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) => string </b></font><i>[Function]</i></tt> |
| 1033 | }}} |
| 1034 | |
| 1035 | Returns 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) => integer </b></font><i>[Function]</i></tt> |
| 1043 | }}} |
| 1044 | |
| 1045 | Returns 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) => document </b></font><i>[Function]</i></tt> |
| 1053 | }}} |
| 1054 | |
| 1055 | Returns 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) => clause-object-or-nil </b></font><i>[Function]</i></tt> |
| 1063 | }}} |
| 1064 | |
| 1065 | Returns 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) => name </b></font><i>[Function]</i></tt> |
| 1073 | }}} |
| 1074 | |
| 1075 | Returns the name of the //`named-clause`//. The name is a lisp object uniquely identifying the clause |
| 1076 | when compared with `EQUALP`. When //`named-clause`// is a [#c_glossentry GLOSSENTRY], the name is |
| 1077 | a string, the text of the term being defined by the entry. When //`named-clause`// is a [#c_section SECTION], |
| 1078 | the name is a `CONS` whose `CAR` is the title of the section and whose `CDR` is the |
| 1079 | clause-name of the section's parent clause. When //`named-clause`// is a [#c_definition DEFINITION], |
| 1080 | the 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) => string </b></font><i>[Function]</i></tt> |
| 1088 | }}} |
| 1089 | |
| 1090 | Returns a string uniquely identifying the //`named-clause`//. The string starts with |
| 1091 | a 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) => string-or-nil </b></font><i>[Function]</i></tt> |
| 1099 | }}} |
| 1100 | |
| 1101 | Returns the clause title. When //`clause-with-title`// is a [#c_named-clause NAMED-CLAUSE], the title |
| 1102 | is required and hence the value will not be `nil`. When //`clause-with-title`// is a [#c_block BLOCK], |
| 1103 | the 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) => clause-or-nil </b></font><i>[Function]</i></tt> |
| 1111 | }}} |
| 1112 | |
| 1113 | Returns the term clause |
| 1114 | |
| 1115 | |
| 1116 | |
| 1117 | [=#f_clause-body] |
| 1118 | {{{ |
| 1119 | #!html |
| 1120 | <tt><font size="+1"><b>(clause-body clause-with-body) => clause-or-nil </b></font><i>[Function]</i></tt> |
| 1121 | }}} |
| 1122 | |
| 1123 | Returns the body clause |
| 1124 | |
| 1125 | |
| 1126 | |
| 1127 | [=#f_clause-items] |
| 1128 | {{{ |
| 1129 | #!html |
| 1130 | <tt><font size="+1"><b>(clause-items clause-with-items) => vector </b></font><i>[Function]</i></tt> |
| 1131 | }}} |
| 1132 | |
| 1133 | Returns a vector. When //`clause-with-items`// is a [#c_table TABLE], the returned vector is a |
| 1134 | vector of [#c_row ROW] objects. When //`clause-with-items`// is a [#c_row ROW], or it is |
| 1135 | a [#c_listing LISTING] of type other than `:definition`, then the vector is a vector of [#c_item ITEM] |
| 1136 | objects. When //`clause-with-items`// is a [#c_listing LISTING] of type `:definition`, the |
| 1137 | vector 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) => markup-type </b></font><i>[Function]</i></tt> |
| 1145 | }}} |
| 1146 | |
| 1147 | Returns 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) => listing-type </b></font><i>[Function]</i></tt> |
| 1155 | }}} |
| 1156 | |
| 1157 | Returns 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) => clause </b></font><i>[Function]</i></tt> |
| 1165 | }}} |
| 1166 | |
| 1167 | Returns 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) => clause </b></font><i>[Function]</i></tt> |
| 1175 | }}} |
| 1176 | |
| 1177 | Returns the definition summary |
| 1178 | |
| 1179 | |
| 1180 | |
| 1181 | [=#f_definition-signature] |
| 1182 | {{{ |
| 1183 | #!html |
| 1184 | <tt><font size="+1"><b>(definition-signature definition) => clause </b></font><i>[Function]</i></tt> |
| 1185 | }}} |
| 1186 | |
| 1187 | Returns the definition signature |
| 1188 | |
| 1189 | |
| 1190 | |
| 1191 | [=#f_link-url] |
| 1192 | {{{ |
| 1193 | #!html |
| 1194 | <tt><font size="+1"><b>(link-url link) => string </b></font><i>[Function]</i></tt> |
| 1195 | }}} |
| 1196 | |
| 1197 | Returns 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) => named-object </b></font><i>[Function]</i></tt> |
| 1205 | }}} |
| 1206 | |
| 1207 | Returns 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) => clause </b></font><i>[Function]</i></tt> |
| 1215 | }}} |
| 1216 | |
| 1217 | Returns 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 | |
| 1229 | The type of the value returned by [#f_clause-name CLAUSE-NAME] for [#c_definition DEFINITION] objects. Encodes the name and type of |
| 1230 | the definition |
| 1231 | |
| 1232 | |
| 1233 | |
| 1234 | [=#f_dspec-type] |
| 1235 | {{{ |
| 1236 | #!html |
| 1237 | <tt><font size="+1"><b>(dspec-type dspec) => definition-type </b></font><i>[Function]</i></tt> |
| 1238 | }}} |
| 1239 | |
| 1240 | The type of the definition named by //`dspec`//. See [#cd_definition :DEFINITION] for |
| 1241 | a discussion of definition types |
| 1242 | |
| 1243 | |
| 1244 | |
| 1245 | [=#f_dspec-name] |
| 1246 | {{{ |
| 1247 | #!html |
| 1248 | <tt><font size="+1"><b>(dspec-name dspec) => definition-name </b></font><i>[Function]</i></tt> |
| 1249 | }}} |
| 1250 | |
| 1251 | The name of the definition named by //`dspec`//. See [#cd_definition :DEFINITION] for |
| 1252 | a 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) => string </b></font><i>[Function]</i></tt> |
| 1260 | }}} |
| 1261 | |
| 1262 | A user-visible version of the definition type |
| 1263 | |
| 1264 | |
| 1265 | |
| 1266 | |
| 1267 | |