Reference Manual of LAML SchemeDoc

The SchemeDoc extracter supports two different documentation commenting styles: multi-semicolon style and documentation-mark style. You can control which one to use via the documentation-commenting-style attribute of manual-front-matters.

The multi-semicolon style corresponds to the LAML commenting style, as used in all LAML software until 2004 (at least). The documentation-mark style is inspirred from similar SchemeDoc systems, in which a documentation mark (a single character) distinguishes ordinary comments and documentation comments. This is probably a more flexible approach, which is less likely to conflict with other commenting and coding styles.

Here follows the detailed rules of both styles. (It may be useful first to consult the examples):

1. A comment block is a consequtive sequence of comment lines, which are initiated with the same number of semicolons, and which are not separated by empty lines or non-comment lines.

2. A documentation comment is a comment block with two or more semicolons.

3. The comment extraction facility 'eats' and eliminates a possible single white space following the ';'. Remaining white spaces are preserved.

4. All one comment semicolon comments are ignored by the SchemeDoc tool.

5. Two semicolon comments - definition 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.

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

7. Four semicolon comments - documentation abstract comments - are used as the introduction to SchemeDoc documentation. 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.

1. A comment block is a consequtive sequence of comment lines, which are not separated by empty, blank or non-comment lines. The number of semicolons may vary from one comment line to another within a comment block.

2. The number of semicolons used for a documentation comment is not significant.

3. A documentation comment is a comment block which is identified by one or more documentation comment characters on the first line of a comment block. The documentation comment characters must appear after the semicolon(s), only separated by spaces or tabs.

4. The documentation comment character is a distinguished character, which per default is '!'.

5. The documentation comment character is only recognized in the first line of a comment block (and next to a semicolon). Documentation comment characters located other places within a comment count as normal characters.

6. The comment extraction facility 'eats' and eliminates a possible single white space following the '!' or ';'. Remaining white spaces are preserved.

7. Comments marked with a single documentation comment character - definition 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.

8. Comments marked with two documentation comment characters - section comments - are used for text sections between documented forms. The first sentence (separated with '.' and a space) is taken as the title of the section.

9. Comments marked with three documentation comment character - documentation abstract comments - are used as the introduction to a documentation document. There should, as such, only be one documentation abstraction comment in a Scheme file. The documentation abstraction comment is usally the first part of Scheme source file.

Caveat: During the extraction of comments from Scheme programs, the Scheme source program is preprocessed. The preprocessor transforms all lexical comments to syntactical constituents:

  ; This is a comment   =>

  (comment!!! 1 "This is a comment")

The result of the preprocessing can be seen in a temporary file if the front-matters attribute keep-syntactical-comment-file is true. The temporary file is located in the LAML temporary file directory, which per default is the temp directory branch of your laml directory.

In a few contexts, the comment!!! forms causes severe problems for the subsequent reading of the program. Here is an example:

  '(x .
    y ; A dotted pair)

Which is transformed to

  '(x .
    y (comment 1 "A dotted pair"))

The Scheme reader will be upset if it encounters this form. Therefore you should care a little about the actual placement of comments in Scheme source programs that are going to be processed by LAML SchemeDoc

In this section we explain the SchemeDoc tagging language, which can be used within documentation comments in Scheme source files.

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 definition comment before the form, whereas

  (define (f par) ...)

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

In definition comments there may be additional internal tagging. 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 following is equivalent (using internal tags before the function description):

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

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

  .key description

The dot-initiated internal tags may occur anywhere in the comment, as long as the rules listed belowed are obeyed. The comment lines, which a not dot-initiated, are concatenated and considered as the description of the definition.

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

1. Each tag starts with a dot '.' and runs to the end of the line. Long lines can, however be continued on the next comment line by placing a line continuation character '\' (back slash character) at the end of the line. Line continuation characters at other positions are treated as normal characters. Newline characters are kept in line-continued tags. (This matters, for instance, if you use an HTML pre tag for formatting purposes).

2. The only characters allowed between the semicolons and .key are blank space characters (space, tab).

3. If a '.' character is needed as the first character on a comment line (as part of the description of the definition) 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.

4. key can be an arbitry symbol without spaces. The manual style, however, only recognizes form, pre-condition, post-condition, parameter, reference, internal-references, misc, example, returns, and comment. However, see the section about custom-tags below.

5. The descriptions in .pre-condition, .post-condition, .example, .comment, .returns and .misc is arbitrary free text (without newlines). The description in .form is supposed to be a parenthesized calling form. The description in .parameter, .reference, and .internal-references are more structured, see below.

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

   .form (form-name par1 par2)
   .pre-condition Some precondition
   .post-condition Some postcondition
   .parameter par-name description
   .attribute attr-name implied/required 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. As a practical example, the following comment is illegal

   ;; ... on so on

Instead, you should escape the first '.':

   ;; $... on so on

A .parameter considers the name following .parameter as the parameter name and the remaining part of the line as the parameter description.

An .attribute clause is used for documentation of XML-in-LAML ad hoc abstractions. The name following .attribute is the attribute name. The next word must be either 'requried' or 'implied'. The rest of the line is the attribute description.

A .reference is a categoried external reference from an anchor to an arbitrary url.

An .internal-references support categorized cross references within the current manual.

The first sentence of a 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 following internal tag is supported in a manual section (three semicolon comments):

   .section-id id

The .section-id may occur anywhere in the section comment. 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.

The following internal tags are supported in manual abstract comments:

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

These internal tags may occur anywhere in the documentation abstract comment. In addition, the following SchemeDoc processing options may occur in manual abstract comment (here shown with concrete values):

   .laml-resource                 false                        ; true or false
   .css-prestylesheet             compact                      ; small, small-compact, compact, normal, or large
   .css-stylesheet                original                     ; original, orginal-bordered, fancy, argentina, brazil, dark-green
   .css-stylesheet-copying        true                         ; true or false
   .scheme-source-linking         true                         ; true or false
   .source-destination-delta      man/                         ; a relative directory path from the source to the destination
   .schemedoc-dependencies        "man/general" "man/color"    ; a list of absolute or relative file paths to SchemeDoc files used by Emacs

The value of source-destination-delta may be empty, with the meaning that the destination and the source directories are identical. If you provide a non-empty value of source-destination-delta, you must create the directory/directories yourself.

The processing options correspond roughly to the attributes of the manual-front-matters element.

In case you provide both internal tags in the manual abstract comment and similar attributes in the manual-front-matters form in a SchemeDoc LAML script, the attributes in the SchemeDoc LAML scripts overrides those in the source program manual abstract comment.

The internal tag .schemedoc-dependencies is only used by Emacs. By use of this tag, you can give a list of SchemeDoc resources, which Emacs will be aware of. Besides this list, Emacs will add an additional default list of useful SchemeDoc resources. The Emacs command display-schemedoc-information (bound to C-c C-h f ) can be applied in the same way as the native Emacs help command describe-function. Here follows an example of the use of .schemedoc-dependencies:

  ;;;; .schemedoc-dependencies "../man/laml" "man/general" "man/color" "man/time" "compatibility/man/mzscheme-compat"

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")
  )

The description field is the (concatenated) parts of the comment, which is not recognized as internal tag lines. See examples of such lists in the files with extension manlsp, which are generated by SchemeDoc.

SchemeDoc allows you to put in your own custom tags in documentation comments. These are given side by side with the standard internal SchemeDoc tags, described in the previous section. In this section we document how this is done, and how you control the presentation of custom tags in the resulting SchemeDoc manual pages.

The format is the following:

   .my-tag some information about my tag

Notice that "some information about my tag" is collected as a string. No additional structure is possible.

You must tell SchemeDoc a little about a custom tag t

• Announce that t is legal, and that it should be taken into account.
• Tell where t should be presented relative to the other tags (standard as well as custom tags).
• Tell how the tag name of t is going to be presented in the HTML documentation (optional).

If you want to use custom tags you should use SchemeDoc via a LAML script.

The following Scheme definitions controls the use of custom tags. You can redefine the variables supported-manual-page-elements, manual-element-order and redefine the function schemedoc-custom-tag-presentation just after SchemeDoc has been loaded in a LAML script. You can also use the variables to eliminate cirtain entries in a manual page, or to re-order the entries in a manual page. Example: sdoc file and html file from the SchemeDoc homepage at cs.aau.dk.

In this section we describe the front matters form of a SchemeDoc manual. The use of CSS stylesheets are controlled by two attributes of manual-front-matters. CSS clauses can be located in a stylesheets subdirectory of the LAML manual source directory. Such stylesheets are called manual source stylesheets. The manual software directory also contains a stylesheets directory. These are called built in stylesheets. The effective stylesheet, as applied by the generated SchemeDoc HTML page, 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.

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. The manlsp file is located side by side with the laml script that produces the manual.

The first element in the list of a manlsp file contains overall information about the manual: title, author, affiliation, abstract etc. It also contains 'raw values' of manual-front-matters attributes.

The cdr of the manlsp list contains an entry for each documented abstraction. The cdr of the manlsp file is a list of association lists. Each association lists contains information about a single documented abstraction.

A good way to learn about the auxiliary manlsp 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.