Generated: July 9, 2004, 14:28:36 Copyright © 2004 , Kurt Nørmark The local LAML software home page

Reference Manual of SchemeDoc and the LAML Manual Facilities

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

LAML Version 24.00 (July 9 2004, beta 5, full)

SchemeDoc is a tool for documentation of Scheme Libraries. SchemeDoc extracts documentation from Scheme source files. SchemeDoc is integrated with the LAML manual document style, which supports more general authoring of library manuals.

A LAML Manual is an XML document in Scheme, which is defined and constrained by an XML DTD. This XML DTD is documented below.

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.

The manual you are reading now is created from the Manal XML DTD, augmented with form and attribute descriptions.

See also the SchemeDoc home page, the SchemeDoc and the LAML Manual facility tutorial, tutorial examples, and additional SchemeDoc examples.

The raw SchemeDoc tool, which extracts documentation from two, three and four semicolon comments, is documented separately. Only users with special, lower-level interests are supposed to read this documentation.

This manual also touches on the internal manual format, which is written to an auxiliary file with the extension manlsp.

Table of Contents:
1. SchemeDoc tags in Scheme source files 4. Manual extraction forms 7. Auxiliary file with internal manual format
2. Top level form 5. Manual pages
3. Front matters forms 6. Manual sections

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 SchemeDoc tags in Scheme source files

In this section we explain the SchemeDoc tagging language, which can be used within Scheme comments in Scheme source files. The remaining sections of the current page documents the properties of the XML-in-LAML language for (SchemeDoc) library manuals.

In order to have documentation extracted from a Scheme source file, the documentation is organized in comments with one, two, three, or four initial semicolons. Recall that semicolons are the Lisp lexical comment symbols: The rest of a line with a semicolon is a comment.

All one comment semicolon comments are ignored by this facility. N semicolon comments, N higher than one, are called SchemeDoc comments.

Two semicolon comments are used as comments of define forms. You can either place the comment before the define form or after the name/signature of the define form. See below.

Three semicolon comments are used for text sections between documented forms. The first sentence (separated with '.' and a space) is used as the title of the section.

Four semicolon comments are used as the introduction to a documentation document. There should, as such, only be one four semicolon comment in a Scheme file. The four semicolon comment is usally the first part of Scheme source file.

It is possible to use HTML markup within SchemeDoc comments. We recommend that this is only used scarcely.

Function definitions of the form

  (define f (lambda (par) ...))

should be documented with a two semicolon comment before the form, whereas

  (define (f par) ...)

can be documented with two semicolon comments before the form or just after (f par). If you have two semicolon comments both before and within the define form they are concatenated.

In comments at level two there may be additional internal tagging at the end of the comment. Here is an example:

  ;; Return the fifth element of a list
  ;; .form (fifth x)
  ;; .parameter x is a list
  (define fifth (make-selector-function 5))

The general format of a SchemDoc comment with internal tagging is:

  .key description

The rules concerning internal tags in SchemeDoc comments are the following:

  1. Each tag starts with a dot '.' and runs to the end of the line.
  2. The only characters allowed between the semicolons and .key are blank space characters (space, tab).
  3. Internal tags must be at the end of a comment. No descriptions (besides other internal tags) must be found after them.
  4. If a '.' character is needed as the first character on a comment line, it must be escaped with a '$' char. Following the usual escaping principles, an '$' can escape itself. Escaping is active in the part of a 2, 3, and 4 semicolon comment before the internal tagging starts.
  5. key can be an arbitry symbol without spaces. The manual style, however, only recognizes title, form, pre-condition, post-condition, description, parameter, reference, internal-references, misc, and comment.
  6. The descriptions in .title, .pre-condition, .post-condition, .example, .comment, .return and .misc is arbitrary free text (without newlines).
  7. There cannot be an internal tag on the first comment line. In other words, the first line must be some pure text description.
  8. Of parsing purposes, string quotes must be used around categories, anchors, refs and urls in .reference and .internal-references.

The following internal tags are supported for manual entries (in two semicolon comments):

   .title Some title
   .form (form-name par1 par2)
   .pre-condition Some precondition
   .post-condition Some postcondition
   .description Some Description
   .parameter par-name parameter description
   .example some example
   .reference "category" "anchor" "url"
   .internal-references "category" "ref1" "ref2" ...
   .misc Miscelaneous information
   .comment Internal comment
   .returns Return value description

Notice that '$' serves as an escape character in the description part of every n semicolon comment, n >= 2.

Internal references support categorized cross references within the current manual page. A reference is a categoried reference from an anchor to an arbitrary url (external resource).

The first sentence of a three semicolon section comment is taken as the title of the section. The remaining part of the three semicolon comment serves as the body of the section. The flollowing internal tag is supported in a manual section (three semicolor comments):

   .section-id id

In a manual section, a .section-id tag makes it possible to define the id of a section. This id is used as an anchor name in the generated HTML document. In addition, section ids ala SECTION1, SECTION2, etc are added as HTML anchor names of the sections. The use of explicit section names, via .section-id, is encouraged. Remember to place the .section-id after the text, which describes the section.

The following internal tags are supported in manual abstracts (four semicolon comments):

   .title Manual title
   .author Manual author
   .affiliation Author affiliation

Internal representation remark: The SchemeDoc tool parses the comments and returns a list like

  (
   (description "Return the fifth element of a list")
   (form "(fifth x)")
   (param "x is a list")
  )

2 Top level form
Here starts the documentation of SchemeDoc and the LAML manual document style. We start with the top level form.

manual
Description The top level manual form. Contains all other forms as direct or indirect constituents. There are basically four different types of manuals, all of which are covered by examples below. The first represents a 'hand written', non-extracted manual. The second is a manual with information extracted from a Scheme source file. The third is a manual extracted directly from an XML DTD. The fourth is an augmented XML DTD manual (in which we merge DTD information with information in manual-section and manual-page clauses).
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 ) ) )
Example
(manual 
  (manual-front-matters ...)
  (manual-section ...)
  (manual-page ...)
  (merged-manual-from-xml-dtd 'src "dtd-file-path")
)
Example
(manual 
  (manual-front-matters ...)
  (manual-from-xml-dtd 'src "dtd-file-path")
)
Example
(manual 
  (manual-front-matters ...)
  (manual-from-scheme-file 'src "file-path")
)
Example
(manual 
  (manual-front-matters ...)
  (manual-section ...)
  (manual-page ...) 
)

3 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.

4 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 relative 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 relative to the LAML startup directory
See also enclosing element manual

5 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

6 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.

7 Auxiliary file with internal manual format

In this section we briefly document the internal documentation format, which is written to a file with the extension 'manlsp'.

Just before a SchemeDoc manual is presented, the tool makes an internal file with extension 'manlsp', in which it writes a Lisp list. In this list, all the manual information is represented. The list is a list of association lists. The best way to lear about the auxiliary file, and the format of the internal representation, is to look at the LAML SchemeDoc and Manuals examples. The third column of the example index gives access to the manlsp files.



Generated: July 9, 2004, 14:28:39
Generated by LAML SchemeDoc .