Generated: December 12, 2003, 17:53:53 | Copyright © 2003 , Kurt Nørmark | ![]() |
The LAML SchemeDoc tool is part of the LAML software package, which is free software available from the LAML home page. The current page is created by SchemeDoc.
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, which implements Schemedoc. As such, Schemedoc has simply been used on itself.
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.
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 How to use comments for documentation purposes. | |||
In order to have documentation extracted, 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. 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 text section. (The text your are reading now - in a browser- is written in a three semicolon comment). Four semicolon comments are used as the introduction to a documentation document. There should, as such, only by one four semicolon comment in a Scheme file. Please notice that 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. It is possible to use HTML formatting within a schemedoc comment. 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 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 manual producing tool may decide to parse additional parts of the strings (the cadr parts of the lists shown above).
The general format of an internal Schemdoc tag is: The rules concerning internal tags in Schemedoc comments are the following:
.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 descriptionNotice 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). We see that all manual clauses of the LAML manual document styles are supported except parameters (plural) and cross-references. These two are made automatically from a number of parameter clauses (singular), and a number of reference and internal-references clauses (not necessarily adjecent). The following internal tags are supported in manual abstracts (four semicolon comments): .title Manual title .author Manual author .affiliation Author affiliationRecall that 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. 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. | |||
2 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 ''. | ||
3 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 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 | |
4 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 | ||
5 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! | |
6 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. | ||
7 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 | |