Generated: April 2, 2002, 11:01:44Copyright ©2002, 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 17.00 (April 2, 2002) 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.

Table of Contents:
1. Preamble stuff4. Clauses of a manual section7. Programmatic support of manual generation.
2. Top level functions5. Other manual facilities8. Index functions.
3. Clauses of a manual page6. Anchor names in a manual page9. Support of a master index.

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

 

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


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)


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


Generated: April 2, 2002, 11:01:44