Generated: Monday, November 14, 2011, 09:19:23Copyright ©2011, Kurt NørmarkThe local LAML software home page

Reference manual of the LAML manual facility

Kurt Nørmark ©    normark@cs.auc.dk    Department of Computer Science    Aalborg University    Denmark    

Source file: styles/manual/manual.scm
LAML Version 38.0 (November 14, 2011, full)

This is the reference manual of the LAML manual facility. Via a specialized set of LAML manual markup it is possible to produce reference manual pages, which can be shown in an Internet browser. This manual is produced my means of the manual facility, and it is thus kind of a meta application of the facility.

You should also consult the LAML tutorial on SchemeDoc and the Manualdocument style.

Table of Contents:
1. Preamble stuff3. Clauses of a manual page5. Other manual facilities
2. Top level functions4. Clauses of a manual section6. Anchor names in a manual page

Alphabetic index:
attribute-description(attribute-description name description)Defines and explains a single attribute of an XML-in-LAML function
attribute-descriptions(attribute-description . attribute-description-list)Defines and explains the attributes of an XML-in-LAML function
comment(comment internal-comment)Defines an internal comment.
cross-references(cross-references . ref-list)Defines a list of cross reference items.
description(description description-string)Describes the meaning of of a function.
example(example ex)Gives an example of the described function
form(form form-list)Shows the calling form of a manual entry
internal-ref(internal-ref name)Returns a link to another place in the current manual document
internal-references(internal-references cat . ref-list)Make a list of references to other places in this manual.
laml-manual-stufflaml-manual-stuffA boolean variable which controls if the generated manual is considered a laml manual.
manual-page(manual-page id . elements)Defines a manual entry.
manual-section(manual-section . element)Defines a new section of a manual.
manual-section(manual-section . elements)Define a manual section with title and body (plain text)
misc(misc m)Describes miscelaneous information about this function
parameter(parameter name description)Defines the name and the meaning of a single parameter
parameters(parameters . parameter-list)Defines the parameters of a function
pre-condition(pre-condition condition-string)Defines the precondition of a manual entry
reference(reference cat anchor url)Makes a single reference to an Internet item
returns(returns return-description)Explains the returned value of a function
section-body(section-body body)Defines the body of a manual section
section-title(section-title title)Defines the title of a section
set-home-url(set-home-url url)Define the home url to be referred to from the manual page, if any.
set-manual-abstract(set-manual-abstract abstract)Defines a manual abstract text
set-manual-author(set-manual-author . author-affiliation-list)Defines the author and affiliation information of this manual
set-manual-master-index(set-manual-master-index url)Define the url of the master index.
set-manual-name(set-manual-name name)Defines the name of this manual.
set-manual-title(set-manual-title title)Defines the manual title
title(title title-string)Sets the title of a manual entry.
xml-in-laml-example-form(xml-in-laml-example-form form-list)Shows a typical example of a calling form of an XML-in-LAML element.

 

1.   PREAMBLE STUFF
The preamble stuff consist of forms which must occur first in a manual


set-manual-title


Form
(set-manual-title title)

Description
Defines the manual title

Preconditions
Must occur before any manual-section or manual-page form

Parameters
titlethe title of the manual (a string)


set-manual-author


Form
(set-manual-author . author-affiliation-list)

Description
Defines the author and affiliation information of this manual

Preconditions
Must occur before any manual-section or manual-page form

Parameters
author-affiliation-lista list of strings, the first of which should be the author name. The rest can be address and affiliation information. The author name are embedded into a copyright notice


set-manual-abstract


Form
(set-manual-abstract abstract)

Description
Defines a manual abstract text

Preconditions
Must occur before any manual-section or manual-page form

Parameters
abstracta string, the abstract text


set-manual-name


Form
(set-manual-name name)

Description
Defines the name of this manual. The result of the processing is written til name .html. It is not necessary to use this form in implemetations, which can take the name from the Emacs buffer name

Preconditions
Must occur before any manual-section or manual-page form

Parameters
namea name without path or extension information


set-home-url


Form
(set-home-url url)

Description
Define the home url to be referred to from the manual page, if any. Not in effect any more.

Preconditions
Must occur before any manual-section or manual-page form

Parameters
urlthe internet address of the home page


set-manual-master-index


Form
(set-manual-master-index url)

Description
Define the url of the master index. The master index is a possibility in case several manual pages exist in the same directory, for instance for a system of libraries. The index must be generated manually, although there are functions for this purpose (see a separate section of this manual). If you do not want to refer to a master index, do not use this form, or pass #f as parameter.

Preconditions
Must occur before any manual-section or manual-page form

Parameters
urlthe internet address of the index page (a string)- or #f


laml-manual-stuff


Form
laml-manual-stuff

Description
A boolean variable which controls if the generated manual is considered a laml manual. For most users, this variable should be false.


 

2.   TOP LEVEL FUNCTIONS
The important top level functions are manual-page and manual-section. These are the most important functions from a manual writer's perspective.


manual-page


Form
(manual-page id . elements)

Description
Defines a manual entry.

Parameters
idA symbol identifying the manual page
elementsZero, one or more title, form, pre-condition, description, parameters, example, or misc elements


manual-section


Form
(manual-section . element)

Description
Defines a new section of a manual. The only forms allowed within a manual section are manual-title and manual-body

Parameters
elementsa list of manual-title and manual-body forms


 

3.   CLAUSES OF A MANUAL PAGE
Here we describe the kernel of the manual page facility: the clauses that may appear within a manual-page form


title


Form
(title title-string)

Description
Sets the title of a manual entry. The title defines an anchor name, which can be used for cross reference purposes via internal-references

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
title-stringThe title, which normally is the first element of the calling form. Of type string


form


Form
(form form-list)

Description
Shows the calling form of a manual entry

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
form-lista proper or improper list of symbols


xml-in-laml-example-form


Form
(xml-in-laml-example-form form-list)

Description
Shows a typical example of a calling form of an XML-in-LAML element.

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
form-lista proper or improper list of symbols and strings

See also
Similar functionform    

Note
Replaces a form constituent. Should never be used together with a form constituent.


pre-condition


Form
(pre-condition condition-string)

Description
Defines the precondition of a manual entry

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
condition-stringa string describing the precondition


description


Form
(description description-string)

Description
Describes the meaning of of a function. The first sentence goes into the overview table of the generated manual page. (A sentence is ended with a point and a space character)

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
description-stringA string describing the meaning


parameters


Form
(parameters . parameter-list)

Description
Defines the parameters of a function

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
parameter-lista list of parameter forms


parameter


Form
(parameter name description)

Description
Defines the name and the meaning of a single parameter

Preconditions
Is only meaningful as a constituent of parameters

Parameters
namethe name of a parameter (a string)
descriptionthe description of a parameter (a string)


attribute-descriptions


Form
(attribute-description . attribute-description-list)

Description
Defines and explains the attributes of an XML-in-LAML function

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
attribute-description-lista list of attribute-description clauses

See also
Constituent formattribute-description    

Note
Attribute descriptions are typically used together with automatic extraction of documention from parsed XML dtds.


attribute-description


Form
(attribute-description name description)

Description
Defines and explains a single attribute of an XML-in-LAML function

Preconditions
Is only meaningful as a constituent of an attribute-descriptions clause

Parameters
namethe name of an XML-in-LAML attribute
descriptionthe description of an XML-in-LAML attribute

See also
Enclosing formattribute-descriptions    


returns


Form
(returns return-description)

Description
Explains the returned value of a function

Parameters
return-descriptionThe explanation of the returned value (a string)


example


Form
(example ex)

Description
Gives an example of the described function

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
exthe example


cross-references


Form
(cross-references . ref-list)

Description
Defines a list of cross reference items. Each item must be a reference form

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
ref-listThe list of reference items


reference


Form
(reference cat anchor url)

Description
Makes a single reference to an Internet item

Preconditions
Must be found in a cross-references context

Parameters
catA string describing the kind and category of the reference
anchorThe anchor text of the URL
urlThe uniform resource locator of this reference


internal-references


Form
(internal-references cat . ref-list)

Description
Make a list of references to other places in this manual. All references are categorized as the first parameter describes

Preconditions
Must be found in a cross-references context

Parameters
catthe category of these references
ref-lista list of internal references to other places in this manual. The type is list of string. Each string refers to an anchor name (without #), which is defined for this manual. Each title of a manual-page gives rise to an anchor name


misc


Form
(misc m)

Description
Describes miscelaneous information about this function

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
mthe miscelanous information


comment


Form
(comment internal-comment)

Description
Defines an internal comment. An internal comment typically reflects the status of the software, a thing to remember in the documentaiton, or another problem which should be alleviated

Preconditions
Is only meaningful as a constituent of a manual page

Parameters
internal-commentthe text of the comment


 

4.   CLAUSES OF A MANUAL SECTION
Here follows the two possible clauses of a manual section


section-title


Form
(section-title title)

Description
Defines the title of a section

Preconditions
Must occur before any manual-section or manual-section form

Parameters
titlethe title string


section-body


Form
(section-body body)

Description
Defines the body of a manual section

Preconditions
Must occur before any manual-section or manual-section form

Parameters
bodythe text of a section body (a string)


 

5.   OTHER MANUAL FACILITIES
Here follows some miscellaneous manual facilities


internal-ref


Form
(internal-ref name)

Description
Returns a link to another place in the current manual document

Preconditions
Must occur 'within' a string of one of the manual clauses

Parameters
namethe anchor name, such as a title of another manual entry (a string, without path and #)


 

6.   ANCHOR NAMES IN A MANUAL PAGE
It is useful to be able to refer to particular places and entries on a manual page. Therefore each manual page (each entry) has assigned an anchor name corresponding to the title of the page. Thus, if we document the function f, there will be an anchor name called 'f'.

The sections of a manual are named via section numbers. Unfortunately, we do yet support sections with naming ids. Threfore the use the naming 'SECTION1', 'SECTION2', etc.

Finally, the top position, the position of the manual, the position before the table of contents, and the position before the manual index table are named with anchors. These are 'MANUAL-TOP', 'MANUAL-TOP', and 'MANUAL-INDEX' respectively.


manual-section


Form
(manual-section . elements)

Description
Define a manual section with title and body (plain text)


Generated: Monday, November 14, 2011, 09:19:23