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

Reference Manual of the SchemeDoc extraction tool

Kurt Nørmark © normark@cs.auc.dk Department of Computer Science Aalborg University Denmark

Source file: tools/schemedoc/schemedoc.scm
LAML Version 24.00 (July 9 2004, beta 5, full)

This is the LAML SchemeDoc tool which extracts interface documentation of a Scheme source program. This tool, as documented here, is only about the extraction. Others parts of the software, the LAML manual facility take care of presenting the extracted documentation. From version 22 of LAML we recommend that you use the extraction facility through the LAML manual facility. See also the SchemeDoc home page.

Interface documentation is found in two, three or four semicolon Lisp comments. A number of internal tags in the comments make it possible to express a variety of interface properties in a structured way. The main procedure of the tool is extract-documentation-from-scheme-file. Two additional functions used for internal purposes are also documented.

If you read this via the documentation and manual facility, this text is extracted from the Scheme source file and presented as a LAML manual. As such, Schemedoc has simply been used on its own source file.

We recommend that you consult "SchemeDoc and Manual pages" for a tutorial introduction to SchemeDoc.

Besides SchemeDoc, the LAML software package has a tool for internal documentation of Scheme programs. This tool is called the Scheme Elucidator.

The interfaces of all the LAML libraries, tools, and document styles have been documented by use of SchemeDoc.

Table of Contents:
1. SchemeDoc parameters. 3. The first internal function. 5. Internal tagging support in schemedoc comments.
2. The main SchemeDoc function. 4. The second internal function. 6. Variables holding extracted information.

Alphabetic index:
allowed-duplicates-elements allowed-duplicates-elements A list of internal tag names (symbol) for which we allow multiple occurences.
delete-comment-file? delete-comment-file? A boolean variable which tells whether to delete the temporary (by this tool) generated source file, in which comments are syntactical Lisp forms.
escape-character escape-character The escape character, which can be used to 'protect' an initial dot in a Scheme comment.
extract-documentation-from-scheme-file (extract-documentation-from-scheme-file scheme-file) This function is the main function.
extract-internal-tagging (extract-internal-tagging comment-string) Parse the comment string, in order to extract internal tagging.
extract-relevant-documentation (extract-relevant-documentation file-name) Extract a manual style list of documentation from file-name and return it.
extracted-manual-abstract extracted-manual-abstract Variable holding the extracted manual abstract.
extracted-manual-affiliation extracted-manual-affiliation Variable holding the extracted manual affiliation.
extracted-manual-author extracted-manual-author Variable holding the extracted manual author.
extracted-manual-title extracted-manual-title Variable holding the extracted manual title.
internal-tagging-char internal-tagging-char The character which designates the start of an internal tag i SchemeDoc (on the start of a line).
lexical-to-syntactical-comments! (lexical-to-syntactical-comments! scheme-input-file scheme-output-file) Given the source file, scheme-input-file, make another file scheme-output-file, in which the lexical comments are turned into syntactic comments in terms of comment forms.
temp-output-file temp-output-file The name of the file where the function lexical-to-syntactical-comments! places it's output

1 SchemeDoc parameters.
This section contains a few SchemeDoc constants, which affect SchemeDoc's processing of a Scheme source file.

delete-comment-file?
Form delete-comment-file?
Description A boolean variable which tells whether to delete the temporary (by this tool) generated source file, in which comments are syntactical Lisp forms. The name of the source file is determined by the variable temp-output-file. By default, the value is #t.

internal-tagging-char
Form internal-tagging-char
Description The character which designates the start of an internal tag i SchemeDoc (on the start of a line). The preset value is the character '.'

escape-character
Form escape-character
Description The escape character, which can be used to 'protect' an initial dot in a Scheme comment. More concrete, we use the escaping character '' for escaping of initial '.' in comment text. Other characters can also be escaped, such as '' itself. The preset value is the character ''.

2 The main SchemeDoc function.
The main SchemeDoc function is extract-documentation-from-scheme-file.

extract-documentation-from-scheme-file
Form (extract-documentation-from-scheme-file scheme-file)
Description This function is the main function. As such, this function IS the schemedoc extraction tool. The function takes as input a name of a scheme file (full path, file extension inclusive). The function returns a list structures suitable for the manual style to display via the function make-manual. Notice that the procedure make-manual is not called by this function. In addition, the procedure extract-documentation-from-scheme-file assigns values to the variables extracted-manual-abstract extracted-manual-title, extracted-manual-author, and extracted-manual-affiliation.
Returns A list of association lists.
See also assigned variables extracted-manual-abstract extracted-manual-title extracted-manual-author extracted-manual-affiliation

3 The first internal function.
The function in this section makes lexical Lisp style comments to syntactical comments. We document it because it may be useful in its own right.

lexical-to-syntactical-comments!
Form (lexical-to-syntactical-comments! scheme-input-file scheme-output-file)
Description Given the source file, scheme-input-file, make another file scheme-output-file, in which the lexical comments are turned into syntactic comments in terms of comment forms. The first parameter of a comment form is the number of semicolons in the lexical comment. The second parameter is the comment text itself. Several consequtive lines of (equally leveled comments) are organized in one comment form.

temp-output-file
Form temp-output-file
Description The name of the file where the function lexical-to-syntactical-comments! places it's output

4 The second internal function.
The function in this section extracts relevant level n, n > 2, comments for documentation purposes

extract-relevant-documentation
Form (extract-relevant-documentation file-name)
Description Extract a manual style list of documentation from file-name and return it. It is assumed that file-name contains syntactical (comment ...) comments, as produced by the procedure lexical-to-syntactical-comments!
See also relevant procedure lexical-to-syntactical-comments!

5 Internal tagging support in schemedoc comments.

extract-internal-tagging
Form (extract-internal-tagging comment-string)
Description Parse the comment string, in order to extract internal tagging. If no internal tagging is found return ((description "comment-string")). If at least one internal tag is found return an a-list of the form ((tag-1-symbol va1-1-string) (tag-2-symbol va1-2-string) ...). The string part before the first tag is returned as (description "string part before first tag") in the list.

allowed-duplicates-elements
Form allowed-duplicates-elements
Description A list of internal tag names (symbol) for which we allow multiple occurences. parameter, reference, and internal-reference tags are treated specially, and are always allowed to be duplicated.

6 Variables holding extracted information.
The variables in this section are assigned to the abstract, title, author and affiliation, as extracted by extract-documentation-from-scheme-file from the initial four semicolon comment of the Scheme source file.

extracted-manual-abstract
Form extracted-manual-abstract
Description Variable holding the extracted manual abstract.
See also extracting procedure extract-documentation-from-scheme-file

extracted-manual-title
Form extracted-manual-title
Description Variable holding the extracted manual title.
See also extracting procedure extract-documentation-from-scheme-file

extracted-manual-author
Form extracted-manual-author
Description Variable holding the extracted manual author.
See also extracting procedure extract-documentation-from-scheme-file

extracted-manual-affiliation
Form extracted-manual-affiliation
Description Variable holding the extracted manual affiliation.
See also extracting procedure extract-documentation-from-scheme-file


Generated: July 9, 2004, 14:32:46
Generated by LAML SchemeDoc .