Generated: August 27, 2003, 22:48:37Copyright ©2003, 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 21.00 (August 27, 2003, PP edition)

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 stuff5. Other manual facilities9. Support of a master index.
2. Top level functions6. Anchor names in a manual page10. XML-in-LAML support.
3. Clauses of a manual page7. Programmatic support of manual generation.
4. Clauses of a manual section8. Index functions.

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
clean-manual-page(clean-manual-page page)Filter a manual page such that only known elements are processed.
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.
end-remarkend-remarkA possible end remark added as the last line of the documentation in small font.
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.
make-manual(make-manual . par-list)This function makes the manual from collected information.
make-master-index(make-master-index all-entries . dir)Write a master index to the file manual-name.html.
manual-from-parsed-dtd(manual-from-parsed-dtd dtd-list-structure)Return a manual list, as extracted from a parsed dtd.
manual-index(manual-index manual style)Return a manual index.
manual-index-order-leq?(manual-index-order-leq? x y)The predicate ordering the manual entries for index sorting
manual-index-width-listmanual-index-width-listThe widths of the colums of the manual index.
manual-masterindex(manual-masterindex augmented-manual style)Return the master index given an augmented manual.
manual-page(manual-page id . elements)Defines a manual entry.
manual-page?(manual-page? elements)Given an entry (or page).
manual-section(manual-section . elements)Define a manual section with title and body (plain text)
manual-section(manual-section . element)Defines a new section of a manual.
manual-section?(manual-section? elements)Given an entry (or page).
manual-table-of-contents(manual-table-of-contents manual style)Old
master-manual-index-width-listmaster-manual-index-width-listThe column widths of the master index.
merge-manual-pages(merge-manual-pages man-list-1 man-list-2)Merge the manual page lists man-list-1 and man-list-2.
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
read-and-augment-lsp-file(read-and-augment-lsp-file name . dir)Return the saved name.lsp manual info.
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.
write-lisp-form-manual(write-lisp-form-manual manual-page-list . dir)Writes a manual structure (list of entries) to a file.
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.


 

7.   PROGRAMMATIC SUPPORT OF MANUAL GENERATION.
The functions in the following are selected functions from the style manual.scm, which are useful when manuals are made from other programs. This part of the manual has been extracted automatically from the Scheme source file of the style.


manual-page?


Form
(manual-page? elements)

Description
Given an entry (or page). Is it a manual page (as opposed to a manual section)


manual-section?


Form
(manual-section? elements)

Description
Given an entry (or page). Is it a manual section (as opposed to a manual page)


manual-section


Form
(manual-section . elements)

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


make-manual


Form
(make-manual . par-list)

Description
This function makes the manual from collected information. In this sense, this is the function which makes things happen. If no first parameter is given, the manual is made from the collected information, which is present in the variable manual-page-list. If a parameter is given, the manual is made from this list of entries. A second parameter it gives the absolute destination-directory. A possible third parameter is the name of the source file. (This parameter is used for informational purposes only). This functions reverses the order of entries. Take a look at one of the lsp files with manual information in order to find out about the list structures of a manual-list. A HTML file is written containing the formatted manual. The HTML file is written to a particular destination-dirctory (if this information is provided as the second parameter), else to the current directory.


clean-manual-page


Form
(clean-manual-page page)

Description
Filter a manual page such that only known elements are processed.


end-remark


Form
end-remark

Description
A possible end remark added as the last line of the documentation in small font. Default is the empty string.


 

8.   INDEX FUNCTIONS.
The functions supporing the generation of a manual index.


manual-index-width-list


Form
manual-index-width-list

Description
The widths of the colums of the manual index. A list of three integers


manual-index


Form
(manual-index manual style)

Description
Return a manual index. Style should be the symbol header-manual-style


manual-index-order-leq?


Form
(manual-index-order-leq? x y)

Description
The predicate ordering the manual entries for index sorting


write-lisp-form-manual


Form
(write-lisp-form-manual manual-page-list . dir)

Description
Writes a manual structure (list of entries) to a file. The filename is manual-name.lsp. If the optional parameter dir is given write the lsp file in this directory. Else write it in the current directory. If provided, dir ends in a slash. The lsp file is useful for programmatic access to the entire body of manual information.


 

9.   SUPPORT OF A MASTER INDEX.
A collection of indexes from several manual pages is called a master index. A master index is made manually from a separate LAML file which reads the saved .lsp files. The master index must be in the same directory as all the contributions.


read-and-augment-lsp-file


Form
(read-and-augment-lsp-file name . dir)

Description
Return the saved name.lsp manual info. Augment each entry with the library name and path information. In that way we know for each manual entry where it comes from. The second parameter is optional. If provided it gives the directory from which to read the lsp files. The directory information is relative to the-library directory. If it is not provided, read from the current directory.


master-manual-index-width-list


Form
master-manual-index-width-list

Description
The column widths of the master index. A list of 4 integers.


manual-masterindex


Form
(manual-masterindex augmented-manual style)

Description
Return the master index given an augmented manual. The augmentation is information about the library of each entry.


make-master-index


Form
(make-master-index all-entries . dir)

Description
Write a master index to the file manual-name.html. The second parameter is optional. If provided it gives the directory of the resulting file. If not, write in the current directory. A master index is a normal index, but in addition it contains a libray column Normally the parameters all-entries are made by mapping read-and-augment-lsp-file over the saved lsp files with manual information. Next these lists are append accumulated.


manual-table-of-contents


Form
(manual-table-of-contents manual style)

Description
Old


 

10.   XML-IN-LAML SUPPORT.
Extraction of manual stuff from a parsed dtd and merging of manual pages.


manual-from-parsed-dtd


Form
(manual-from-parsed-dtd dtd-list-structure)

Description
Return a manual list, as extracted from a parsed dtd.

Parameters
dtd-list-structurethe Lisp structure, as generated by the LAML DTD parser.


merge-manual-pages


Form
(merge-manual-pages man-list-1 man-list-2)

Description
Merge the manual page lists man-list-1 and man-list-2. Appart from title, the fields in the two manual lists should be disjoint. The first one controls the ordering of the resulting list. Entries of man-list-2 which do not have a counterpart in man-list-1 are not included in the result.


Generated: August 27, 2003, 22:48:37