Generated: December 12, 2003, 17:53:37 Copyright © 2003 , Kurt Nørmark The local LAML software home page

Reference manual of LAML Manuals and SchemeDoc

Kurt Nørmark © Department of Computer Science Aalborg University Denmark

LAML Version 23.00 (December 12, 2003, full)

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.

Table of Contents:
1. Top level form 3. Manual extraction forms 5. Manual sections
2. Front matters forms 4. Manual pages

Alphabetic index:
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.


Generated: December 12, 2003, 17:53:39
Generated by LAML SchemeDoc .