Generated: December 12, 2003, 17:53:37 | Copyright © 2003 , Kurt Nørmark | ![]() |
The purpose of a LAML Manual is to document the programmatic interface of a Scheme program, typically a library.
A LAML Manual is an XML document in Scheme, which is defined and constrained by an XML DTD.
Using the LAML Manual facility it is possible to write a manual in an XML-in-LAML language. It is also possible to extract the manual from a Scheme source file via SchemeDoc. As such, the LAML manual serves as an interface to SchemeDoc. It is recommended to use the LAML manual facility rather than using SchemeDoc directly. Please consult the section How to use comments for documentation purposes for information about SchemeDoc commenting conventions. See also the separate SchemeDoc home page.
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.
This manual facility replaces the older LAML manual facility, which we now consider as obsolete.
The manual you are reading now is created from the Manal XML DTD, augmented with form and attribute descriptions.
See also the tutorial on SchemeDoc and the LAML Manual facility.
1. Top level form | 3. Manual extraction forms | 5. Manual sections |
2. Front matters forms | 4. Manual pages |
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 Top level form | |||
manual | |||
Description | The top level manual form. Contains all other forms as direct or indirect constituents. | ||
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 ) ) ) | ||
2 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. | ||
3 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 path 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 path to the LAML startup directory |
See also | enclosing element | manual | |
4 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 | |
5 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. | ||