Generated: Monday, November 14, 2011, 09:14:40 Copyright © 2011 , Kurt NÝrmark The local LAML software home page

Reference Manual of LAML SchemeDoc

Kurt NÝrmark Department of Computer Science Aalborg University Denmark

SchemeDoc is a tool for documentation of Scheme libraries. It can also be used for documentation of Scheme libraries which are derived from XML DTDs.

SchemeDoc can extract documentation from documentation comments of Scheme source files. The extracted documentation can be presented as CSS styled XHTML pages. SchemeDoc extracts documentation comments at the top level of a Scheme program, and at one level below the top-level.

Some CSS information is available, including a visual gallery of the different built in CSS stylesheets.

SchemeDoc can also extract information from a parsed XML DTD, and merge this information with explicitly authored information. In addition, SchemeDoc can be used manually, without any kind of extraction. All possibilities are made available via the XML language, which is described below.

The manual, you are reading now, is itself created from the Manual XML DTD, augmented with element and attribute descriptions.

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

The SchemeDoc Index Facility makes it possible to construct a frame-based browser on top a number of SchemeDoc Manuals.

The SchemeDoc extraction tool, which extracts documentation from distinguished 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.

The LAML and SchemeDoc distributions come with indexed versions of the R4RS and R5RS Scheme Reports in the directories r4rs and r5rs of the distribution.

Table of Contents:
1. Documentation Comments 4. Top level form 7. Manual pages
2. Internal SchemeDoc tags 5. Front matters forms 8. Manual sections
3. Custom tags 6. Manual extraction forms 9. The auxiliary manlsp file
A. Mirror Information Appendix

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
examples Zero, one or more concrete examples
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-element-order The presentation ordering of tags in a SchemeDoc manual.
manual-from-scheme-file Extract a manual via SchemeDoc from a Scheme source file
manual-from-scheme-files Extract a manual via SchemeDoc from one or more Scheme source files (say n source files).
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
scheme-source-linking-manual The description of other manuals, which is used in case that the attribute scheme-source-linking is true.
schemedoc-custom-tag-presentation
section-body A overall description of the manual pages in this section
section-title The title of this manual section
supported-manual-page-elements A list of tag names (symbols) supported by SchemeDoc.


1 Documentation Comments

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

Multi-semicolon style: (example)
  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.

Documentation-mark style: (example)
  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



2 Internal SchemeDoc tags

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.



3 Custom tags

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.


supported-manual-page-elements
Form supported-manual-page-elements
Description A list of tag names (symbols) supported by SchemeDoc. Add the name of custom tags to this list
Examples (define supported-manual-page-elements '(title library kind form description pre-condition post-condition parameters example cross-references misc comment returns xml-in-laml-example-form attributes content-model level xml-in-laml-attributes side-effects throws my-own-tag))
Note The default value, which reflects the supported tags, is (title library kind form description pre-condition post-condition parameters example cross-references misc comment returns xml-in-laml-example-form attributes content-model level xml-in-laml-attributes)

manual-element-order
Form manual-element-order
Description The presentation ordering of tags in a SchemeDoc manual. A list of symbols.
Examples (define manual-element-order '(section-id section-title section-body title library kind form my-own-tag xml-in-laml-example-form description content-model attributes pre-condition parameters xml-in-laml-attributes returns side-effects post-condition throws example cross-references misc comment))
Note The default value, which reflects the ordering among the supported tags, is (section-id section-title section-body title library kind form xml-in-laml-example-form description content-model attributes pre-condition parameters xml-in-laml-attributes returns post-condition example cross-references misc comment)

schemedoc-custom-tag-presentation
Form (schemedoc-custom-tag-presentation kind)
Parameters kind The tag name (a symbol)
Returns A string which presents kind
Note Use a cond with an else clause that returns (as-string kind)


4 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-files | manual-from-scheme-file | manual-from-xml-dtd | ( ( manual-page | manual-section ) * , merged-manual-from-xml-dtd ) ) )
Examples (manual (manual-front-matters ...) (manual-section ...) (manual-page ...) )
(manual (manual-front-matters ...) (manual-from-scheme-file 'src "file-path") )
(manual (manual-front-matters ...) (manual-from-xml-dtd 'src "dtd-file-path") )
(manual (manual-front-matters ...) (manual-section ...) (manual-page ...) (merged-manual-from-xml-dtd 'src "dtd-file-path") )


5 Front matters forms

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.


manual-front-matters
Description Holds a number of overall manual properties. In case the manual abstract is omitted it may be supplied from a documentation abstract comment extracted by SchemeDoc.
XML content model ( manual-title ? , manual-author ? , manual-affiliation ? , manual-abstract ? , scheme-source-linking-manual * )
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.
verbosity-level CDATA           ( 0 ) How much information is given by SchemeDoc during processing. 0: Minimal information 1: One output line for each item processed. Defaults to 0.
documentation-commenting-style ( multi-semicolon | documentation-mark ) Controls which documentation commenting style to use for extraction of documentation from Scheme soruce file comments. See the section about documentation comments.
default-attribute-explanation CDATA The default attribute explanation in case no other explanation is available
source-destination-delta CDATA The relative file path from the manual source directory to the HTML target directory. You are responsible for creating the directory/directories.
css-prestylesheet CDATA The name of the first part of the CSS stylesheet, usually for font sizes and other sizes. A name without file extension. Use either small, small-compact, compact, normal or large.
css-stylesheet CDATA The name of the last part of the CSS stylesheet, for additional styling. A name without file extension. See visual gallery for possibilities.
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'.
keep-syntactical-comment-file ( true | false ) In the first phase of Scheme comment processing, the lexical comment are translated to syntactical comments. A temporary file named "schemesource.tmp" is generated. If the value of this attribute is "true", do not delete this file. It is not possible to set this attribute from the initial abstract comment in a Scheme source file.
manual-destination-name CDATA The proper name of the manual destination file (the HTML file and others). Defaults to the proper name of the LAML source file.
mirror-names-defined ( true | false ) Only for XML DTD documentation: Does this mirror define named functions. If not, the mirror functions can only be accessed via the language map. The default value is true.
mirror-name-prefix CDATA           ( ) Only for XML DTD documentation: The string prepended to each name of a mirror function. The default value is the empty string (meaning that no strings are prepended).
attribute-sorting ( as-in-dtd | by-attribute-name ) Only for XML DTD documentation: The ordering of attributes in the XML DTD manual. Either as-in-dtd or by-attribute-name.
scheme-source-linking ( true | false ) Only for documentation extracted from a Scheme source program: Controls the generation of a Scheme source program HTML file - made with the Scheme Elucidator 2 tool. Also controls the linking in between the interface documentation and the Scheme HTML source.
scheme-report-version ( r4rs | r5rs | none ) Only for documentation extracted from a Scheme source program and only relevant if scheme-source-linking it true: Controls which version of the Scheme Report to use in Scheme Source programs.
rnrs-url CDATA Only for documentation extracted from a Scheme source program and only relevant if scheme-source-linking it true: An absolute URL to the directory with your preferred version of the Scheme Report. Ends in a forward slash. You can use this attribute to point to your local R4RS or R5RS document within your local LAML system. Must be in accord with the value of scheme-report-version. Defaults to the appropriate URL at www.cs.aau.dk.
xml-protected-descriptions ( true | false ) Do not use this attribute. If true, the contents of description elements of manual-pages become 'html protected'. XML and HTML stuff appear verbatim if this attribute is true. Please notice that the default value is true.
example-repository CDATA A relative file path from the the SchemeDoc document to a testcases file in a Schemeunit test directory. By supplying this relative file path, selected unit testcases are used as examples in the documentation. The selection is based on the final testcase field (use-as-example or do-not-use-as-example). Overall, this facility represents an integration with SchemeDoc and the Interactive SchemeUnit test facility.
element-cross-reference-url-fn CDATA The name of a Scheme function. It maps element names (strings) to (absolute) URLs. The function is called on all elments (element names) to systematically produce cross references to external resource. This can, for instance, be used to link XML elements to an appropriate places in W3C documentation.
element-cross-reference-anchor-text CDATA A fixed text that serves as anchor text for URLs generated by the function named by the element-cross-reference-url-fn attribute.
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 to the initial text of a 4-semicolon comment in a Scheme source file.

scheme-source-linking-manual
Description The description of other manuals, which is used in case that the attribute scheme-source-linking is true. The information in this clause is used by the Scheme Elucidator only. By including an entry to a SchemeDoc manual page, the Scheme Elucidator can generate links to the SchemeDoc documentation manuals from the Scheme source programs. If textual content is provided of this element it becomes a more user friendly (longer) name of the manual than the key attribute. Corresponds to the Scheme Elucidator manual-source element.
XML content model (#PCDATA)
XML attributes
Required: *
Default values: red
key * CDATA A unique short name which identifies this manual. You can chose the name.
file-path * CDATA A relative path to a manual file, as generated by SchemeDoc. The path is relative to the directory that holds the LAML manual script file. The path can be with or without manlsp extension. (SchemeDoc generates files with manlsp extension together with an HTML file.)
url CDATA Not used anymore.
See also enclosing element manual-front-matters
See also similar elucidator form manual-source


6 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 elements manual manual-from-scheme-files

manual-from-scheme-files
Description Extract a manual via SchemeDoc from one or more Scheme source files (say n source files). Works as if source file number 2, 3, ... n are textually included into the first one by simple concatenation.
XML content model ( manual-from-scheme-file + )
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


7 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 | examples | 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. It is recommeded to use pure textual descriptions without any kind markup!
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.

examples
Description Zero, one or more concrete examples
XML content model ( example * )
See also enclosing element manual-page

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 examples

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 The URL of the external resource
category * CDATA 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 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


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


9 The auxiliary manlsp file

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.



Mirror Information Appendix.
Mirror name: schemedoc2
Automatic loading of common XML-in-LAML library? No
List of action elements (manual)
Generation of named mirror functions: Yes
Mirror name prefix: None
Transliteration of CDATA? Yes
List of elements for which transliteration does not apply: '()
List of elements for which all white spacing is preserved: '()
Name of HTML character transformation table: html-char-transformation-table
Are default DTD attributes passed explicitly? No
Are attributes only allowed to be text strings? Yes
Is extended textual contents allowed? No
Is white space represented by this mirror? Yes
How are duplicated XML attributes handled: 'keep-all


Generated: Monday, November 14, 2011, 09:14:40
Generated by LAML SchemeDoc using LAML Version 38.0 (November 14, 2011, full)