Generated: July 9, 2004, 14:28:36 | Copyright © 2004 , Kurt Nørmark | ![]() |
SchemeDoc is a tool for documentation of Scheme Libraries. SchemeDoc extracts documentation from Scheme source files. SchemeDoc is integrated with the LAML manual document style, which supports more general authoring of library manuals.
A LAML Manual is an XML document in Scheme, which is defined and constrained by an XML DTD. This XML DTD is documented below.
It is also possible to extract a partial manual (element names, content model, and attribute descriptions) from an XML DTD. Finally, it is possible to merge the manual contributions from an XML DTD with ordinary manual entries.
The manual you are reading now is created from the Manal XML DTD, augmented with form and attribute descriptions.
See also the SchemeDoc home page, the SchemeDoc and the LAML Manual facility tutorial, tutorial examples, and additional SchemeDoc examples.
The raw SchemeDoc tool, which extracts documentation from two, three and four semicolon comments, is documented separately. Only users with special, lower-level interests are supposed to read this documentation.
This manual also touches on the internal manual format, which is written to an auxiliary file with the extension manlsp.
1. SchemeDoc tags in Scheme source files | 4. Manual extraction forms | 7. Auxiliary file with internal manual format |
2. Top level form | 5. Manual pages | |
3. Front matters forms | 6. Manual sections |
attribute-description | A description of a single XML attribute |
attribute-descriptions | The container of a number of attribute-description clauses |
comment | An internal comment about the enclosing manual-page |
description | The descriptions of the entity. |
example | An example of the call of a function or procedure, and some hints of the outcome |
example-form | Describes an example of a head - or signature - of the entity |
external-reference | A link to a web resource external to this manual |
form | Describes the head - or signature - of the entity |
internal-references | A link to other manual pages or manual sections in this manual |
manual | The top level manual form. |
manual-abstract | The abstract of the manual |
manual-affiliation | The affiliation of the manual author. |
manual-author | The author(s) of a manual |
manual-from-scheme-file | Extract a manual via SchemeDoc from a Scheme source file |
manual-from-xml-dtd | Extract a partial manual from an XML Document Type Defintion (DTD) |
manual-front-matters | Holds a number of overall manual properties. |
manual-page | The description of an entity such as a function, variable, or XML element in terms of a number of different constituents. |
manual-section | A manual section |
manual-title | The title of the manual |
merged-manual-from-xml-dtd | Extract a partial manual from an XML Document Type Defintion (DTD) and merge it with the manual-page and manual-section forms of this manual. |
misc | A miscellaneous remark about the documented entity |
name-ref | A name of another manual-page or manual-section |
parameter | The description of a named parameter |
parameters | A container for the descriptions of individual parameters |
postcondition | This condition must be true if/when the function or procedure terminates |
precondition | This condition must be true in order to call a function or procedure |
returns | The description of the returned value of a function |
section-body | A overall description of the manual pages in this section |
section-title | The title of this manual section |
1 SchemeDoc tags in Scheme source files | |||
In this section we explain the SchemeDoc tagging language, which can be used within Scheme comments in Scheme source files. The remaining sections of the current page documents the properties of the XML-in-LAML language for (SchemeDoc) library manuals. In order to have documentation extracted from a Scheme source file, the documentation is organized in comments with one, two, three, or four initial semicolons. Recall that semicolons are the Lisp lexical comment symbols: The rest of a line with a semicolon is a comment. All one comment semicolon comments are ignored by this facility. N semicolon comments, N higher than one, are called SchemeDoc comments. Two semicolon comments are used as comments of define forms. You can either place the comment before the define form or after the name/signature of the define form. See below. Three semicolon comments are used for text sections between documented forms. The first sentence (separated with '.' and a space) is used as the title of the section. Four semicolon comments are used as the introduction to a documentation document. There should, as such, only be one four semicolon comment in a Scheme file. The four semicolon comment is usally the first part of Scheme source file. It is possible to use HTML markup within SchemeDoc comments. We recommend that this is only used scarcely. Function definitions of the form (define f (lambda (par) ...)) should be documented with a two semicolon comment before the form, whereas (define (f par) ...) can be documented with two semicolon comments before the form or just after (f par). If you have two semicolon comments both before and within the define form they are concatenated. In comments at level two there may be additional internal tagging at the end of the comment. Here is an example: ;; Return the fifth element of a list ;; .form (fifth x) ;; .parameter x is a list (define fifth (make-selector-function 5)) The general format of a SchemDoc comment with internal tagging is: .key description The rules concerning internal tags in SchemeDoc comments are the following:
The following internal tags are supported for manual entries (in two semicolon comments): .title Some title .form (form-name par1 par2) .pre-condition Some precondition .post-condition Some postcondition .description Some Description .parameter par-name parameter description .example some example .reference "category" "anchor" "url" .internal-references "category" "ref1" "ref2" ... .misc Miscelaneous information .comment Internal comment .returns Return value description Notice that '$' serves as an escape character in the description part of every n semicolon comment, n >= 2. Internal references support categorized cross references within the current manual page. A reference is a categoried reference from an anchor to an arbitrary url (external resource). The first sentence of a three semicolon section comment is taken as the title of the section. The remaining part of the three semicolon comment serves as the body of the section. The flollowing internal tag is supported in a manual section (three semicolor comments): .section-id id In a manual section, a .section-id tag makes it possible to define the id of a section. This id is used as an anchor name in the generated HTML document. In addition, section ids ala SECTION1, SECTION2, etc are added as HTML anchor names of the sections. The use of explicit section names, via .section-id, is encouraged. Remember to place the .section-id after the text, which describes the section. The following internal tags are supported in manual abstracts (four semicolon comments): .title Manual title .author Manual author .affiliation Author affiliation Internal representation remark: The SchemeDoc tool parses the comments and returns a list like ( (description "Return the fifth element of a list") (form "(fifth x)") (param "x is a list") ) | |||
2 Top level form | |||
Here starts the documentation of SchemeDoc and the LAML manual document style. We start with the top level form. | |||
manual | |||
Description | The top level manual form. Contains all other forms as direct or indirect constituents. There are basically four different types of manuals, all of which are covered by examples below. The first represents a 'hand written', non-extracted manual. The second is a manual with information extracted from a Scheme source file. The third is a manual extracted directly from an XML DTD. The fourth is an augmented XML DTD manual (in which we merge DTD information with information in manual-section and manual-page clauses). | ||
XML content model | ( manual-front-matters , ( ( manual-page | manual-section ) * | manual-from-scheme-file | manual-from-xml-dtd | ( ( manual-page | manual-section ) * , merged-manual-from-xml-dtd ) ) ) | ||
Example | (manual (manual-front-matters ...) (manual-section ...) (manual-page ...) (merged-manual-from-xml-dtd 'src "dtd-file-path") ) | ||
Example | (manual (manual-front-matters ...) (manual-from-xml-dtd 'src "dtd-file-path") ) | ||
Example | (manual (manual-front-matters ...) (manual-from-scheme-file 'src "file-path") ) | ||
Example | (manual (manual-front-matters ...) (manual-section ...) (manual-page ...) ) | ||
3 Front matters forms | |||
In this section we describe the front matters form of a manual. The use of CSS stylesheets are controlled by attributes of manual-front-matters. CSS clauses can be located in a stylesheets subdirectory of the LAML manual source directory. These are called manual source stylesheets. The manual software directory also contains a stylesheets directory. These are called built in stylesheets. The effective stylesheet is aggregated by four parts: The built in manual prestylesheet, the manual source prestylesheet, the built in manual stylesheet, and the manual source stylesheet (in this order). Please consult the Manual CSS guide for further information about the use of CSS in LAML manuals. | |||
manual-front-matters | |||
Description | Holds a number of overall manual properties. In case the manual abstract is omitted it may be supplied from a four semicolon comment extracted by SchemeDoc. | ||
XML content model | ( manual-title ? , manual-author ? , manual-affiliation ? , manual-abstract ? ) | ||
XML attributes Required: * Default values: red | laml-resource | ( true | false ) | Is this manual part of LAML, or is it external to LAML. Controls top banner of manual page. Does also control the placement of the CSS stylesheet file. |
default-attribute-explanation | CDATA | The default attribute explanation in case no other explanation is available | |
manual-destination-directory | CDATA | The destination directory of the manual. Defaults to the LAML startup directory. | |
css-prestylesheet | CDATA | The name of the first part of the CSS stylesheet, usually for font sizes and other sizes. Use either compact or normal. | |
css-stylesheet | CDATA | The name of the last part of the CSS stylesheet, for additional styling. Use either original or fancy. | |
css-stylesheet-copying | ( true | false ) | Is the CSS stylesheet copied to the destination directory | |
make-dtd-manual-template | ( true | false ) | Controls the generation of a LAML manual template file for attribute descriptions and form descriptions. Does only apply for manuals of type 'merged-manual-from-xml-dtd' and 'manual-from-xml-dtd'. | |
See also | enclosing element | manual | |
manual-title | |||
Description | The title of the manual | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-front-matters | |
Note | Relation to SchemeDoc: This form corresponds to the .title tag in 4-semicolon comment in a Scheme source file. | ||
manual-author | |||
Description | The author(s) of a manual | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-front-matters | |
Note | Relation to SchemeDoc: This form corresponds to the .author tag in 4-semicolon comment in a Scheme source file. | ||
manual-affiliation | |||
Description | The affiliation of the manual author. May be a number of separate strings in sequence. | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-front-matters | |
Note | Relation to SchemeDoc: This form corresponds to the .affiliation tag in 4-semicolon comment in a Scheme source file. | ||
manual-abstract | |||
Description | The abstract of the manual | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-front-matters | |
Note | Relation to SchemeDoc: This form corresponds initial text of a 4-semicolon comment in a Scheme source file. | ||
4 Manual extraction forms | |||
Different forms with which to extract manual information from other sources. | |||
manual-from-scheme-file | |||
Description | Extract a manual via SchemeDoc from a Scheme source file | ||
XML content model | EMPTY | ||
XML attributes Required: * Default values: red | src * | CDATA | An absolute path to the Scheme source file, or a path relative to the LAML startup directory |
See also | enclosing element | manual | |
manual-from-xml-dtd | |||
Description | Extract a partial manual from an XML Document Type Defintion (DTD) | ||
XML content model | EMPTY | ||
XML attributes Required: * Default values: red | src * | CDATA | An absolute path to the DTD, or a path relative to the LAML startup directory |
See also | enclosing element | manual | |
merged-manual-from-xml-dtd | |||
Description | Extract a partial manual from an XML Document Type Defintion (DTD) and merge it with the manual-page and manual-section forms of this manual. The manual-page forms typically contribute with description and attribute-descriptions forms. | ||
XML content model | EMPTY | ||
XML attributes Required: * Default values: red | src * | CDATA | An absolute path to the DTD, or a path relative to the LAML startup directory |
See also | enclosing element | manual | |
5 Manual pages | |||
A manual page describes the properties of a a single function, variable, or XML element. | |||
manual-page | |||
Description | The description of an entity such as a function, variable, or XML element in terms of a number of different constituents. | ||
XML content model | ( form | description | example-form | precondition | postcondition | parameters | example | external-reference | internal-references | comment | misc | returns | attribute-descriptions ) * | ||
XML attributes Required: * Default values: red | name * | CDATA | The name of the entity |
See also | enclosing element | manual | |
description | |||
Description | The descriptions of the entity. The first sentence of the description goes into the alphabetically sorted table in front of the manual. | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to the initial text of a 2-semicolon comment in a Scheme source file. | ||
form | |||
Description | Describes the head - or signature - of the entity | ||
XML content model | (#PCDATA) | ||
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a .form tag in a 2-semicolon comment in a Scheme source file. | ||
example-form | |||
Description | Describes an example of a head - or signature - of the entity | ||
XML content model | (#PCDATA) | ||
See also | enclosing element | manual-page | |
precondition | |||
Description | This condition must be true in order to call a function or procedure | ||
XML content model | (#PCDATA) | ||
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a .pre-condition tag in a 2-semicolon comment in a Scheme source file. | ||
postcondition | |||
Description | This condition must be true if/when the function or procedure terminates | ||
XML content model | (#PCDATA) | ||
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a .post-condition tag in a 2-semicolon comment in a Scheme source file. | ||
parameters | |||
Description | A container for the descriptions of individual parameters | ||
XML content model | ( parameter * ) | ||
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a number of .parameter tags in a 2-semicolon comment in a Scheme source file. | ||
parameter | |||
Description | The description of a named parameter | ||
XML content model | (#PCDATA | div | span )* | ||
XML attributes Required: * Default values: red | name * | CDATA | The name of a parameter |
See also | enclosing element | parameters | |
Note | Relation to SchemeDoc: This form corresponds to a .parameter tag in a 2-semicolon comment in a Scheme source file. | ||
example | |||
Description | An example of the call of a function or procedure, and some hints of the outcome | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-page | |
external-reference | |||
Description | A link to a web resource external to this manual | ||
XML content model | (#PCDATA | div | span )* | ||
XML attributes Required: * Default values: red | href | CDATA ( #REQURIED ) | The URL of the external resource |
category | CDATA ( #REQURIED ) | The role of this external reference - a single word or a very short phrase | |
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a .reference tag in a 2-semicolon comment in a Scheme source file. | ||
internal-references | |||
Description | A link to other manual pages or manual sections in this manual | ||
XML content model | ( name-ref * ) | ||
XML attributes Required: * Default values: red | category | CDATA ( #REQURIED ) | The role of this internal reference - a single word or a very short phrase |
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a .internal-references tag in a 2-semicolon comment in a Scheme source file. | ||
name-ref | |||
Description | A name of another manual-page or manual-section | ||
XML content model | (#PCDATA) | ||
See also | enclosing element | internal-references | |
comment | |||
Description | An internal comment about the enclosing manual-page | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a .comment tag in a 2-semicolon comment in a Scheme source file. | ||
misc | |||
Description | A miscellaneous remark about the documented entity | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a .misc tag in a 2-semicolon comment in a Scheme source file. | ||
returns | |||
Description | The description of the returned value of a function | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-page | |
Note | Relation to SchemeDoc: This form corresponds to a .returns tag in a 2-semicolon comment in a Scheme source file. | ||
attribute-descriptions | |||
Description | The container of a number of attribute-description clauses | ||
XML content model | ( attribute-description * ) | ||
See also | enclosing element | manual-page | |
attribute-description | |||
Description | A description of a single XML attribute | ||
XML content model | (#PCDATA | div | span )* | ||
XML attributes Required: * Default values: red | name * | CDATA | The name of the attribute |
See also | enclosing element | attribute-descriptions | |
6 Manual sections | |||
A manual section is a grouping of a number of related manual-pages | |||
manual-section | |||
Description | A manual section | ||
XML content model | ( section-title , section-body ? ) | ||
XML attributes Required: * Default values: red | id * | CDATA | A unique id of a manual section. Used for section cross references and references to manual sections from manual pages |
See also | enclosing element | manual | |
Note | Relation to SchemeDoc: The id attribute corresponds to the internal .section-id tag of a 3-semicolon comment in a Scheme programs. | ||
section-title | |||
Description | The title of this manual section | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-section | |
Note | Relation to SchemeDoc: This form corresponds to the first sentence of 3-semicolon comment in a Scheme source file. | ||
section-body | |||
Description | A overall description of the manual pages in this section | ||
XML content model | (#PCDATA | div | span )* | ||
See also | enclosing element | manual-section | |
Note | Relation to SchemeDoc: This form corresponds to all but the first sentence of the initial text of 3-semicolon comment in a Scheme source file. | ||
7 Auxiliary file with internal manual format | |||
In this section we briefly document the internal documentation format, which is written to a file with the extension 'manlsp'. Just before a SchemeDoc manual is presented, the tool makes an internal file with extension 'manlsp', in which it writes a Lisp list. In this list, all the manual information is represented. The list is a list of association lists. The best way to lear about the auxiliary file, and the format of the internal representation, is to look at the LAML SchemeDoc and Manuals examples. The third column of the example index gives access to the manlsp files. | |||