| Copyright © 2011 , Kurt Nørmark | |
Interface documentation is found in two, three or four semicolon Lisp comments. This is called multi semicolon comment style. From version 25 of LAML we also support documentation mark commenting style, in which interface comments are marked with a distinguished character, per default '!'. 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.
| 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. |
| documentation-comment-character | documentation-comment-character | The documentation comment character, as used for the documentation mark commenting style of SchemeDoc. |
| 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 of the SchemeDoc extractor. |
| 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-css-prestylesheet | extracted-css-prestylesheet | Variable holding the extracted value of css-prestylesheet. |
| extracted-css-stylesheet | extracted-css-stylesheet | Variable holding the extracted value of css-stylesheet. |
| extracted-css-stylesheet-copying | extracted-css-stylesheet-copying | Variable holding the extracted value of css-stylesheet-copying. |
| extracted-laml-resource | extracted-laml-resource | Variable holding the extracted value of laml-resource. |
| 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. |
| extracted-scheme-source-linking | extracted-scheme-source-linking | Variable holding the extracted value of scheme-source-linking. |
| extracted-source-destination-delta | extracted-source-destination-delta | Variable holding the extracted value of source-destination-delta. |
| 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. |
| line-continuation-char | line-continuation-char | The character that can be used in the final position of a documentation comment line to indicate that the comment line is continued at the next (similar) comment line. |
| scheme-documentation-commenting-style | scheme-documentation-commenting-style | The Scheme commening style which determines the identification of documentation comments. |
| 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. | |||
| scheme-documentation-commenting-style | |||
| Form | scheme-documentation-commenting-style | ||
| Description | The Scheme commening style which determines the identification of documentation comments. Either multi-semicolon or documentation-mark (symbols). | ||
| 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 ''. | ||
| line-continuation-char | |||
| Form | line-continuation-char | ||
| Description | The character that can be used in the final position of a documentation comment line to indicate that the comment line is continued at the next (similar) comment line. | ||
| documentation-comment-character | |||
| Form | documentation-comment-character | ||
| Description | The documentation comment character, as used for the documentation mark commenting style of SchemeDoc. | ||
 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 of the SchemeDoc extractor. As such, this function IS the LAML SchemeDoc extraction tool. The function takes as input a name of a scheme file (full path, file extension inclusive). The function returns a list structure suitable for SchemeDoc to display. The list is delivered in reverse order compared with the ordering of the extracted information from the source file. Thus, you should reverse the result of this function before you pass it to the function make-manual of SchemeDoc. In addition, this procedure assigns values to a number of global variables. See below for details about these variables. | ||
| Parameters | scheme-file | The full path to the Scheme source file (including initial path and source file extension). | |
| Returns | A list of association lists (in reverse order compared to the content of the source file). | ||
| 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 parts in lines, which are not initiated with the designated internal tagging char, are returned as (description "..."). | ||
| 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 introductory comment of the Scheme source file. Additional variables may be assigned as well, see below. This tool does not make any use of the extracted values. They are provided for other tools via the global variables documented below. | |||
| 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 | |
| extracted-laml-resource | |||
| Form | extracted-laml-resource | ||
| Description | Variable holding the extracted value of laml-resource. The extracted value is only used if the similar manual-front-matters attribute is not provided. | ||
| See also | extracting procedure | extract-documentation-from-scheme-file | |
| extracted-css-prestylesheet | |||
| Form | extracted-css-prestylesheet | ||
| Description | Variable holding the extracted value of css-prestylesheet. The extracted value is only used if the similar manual-front-matters attribute is not provided. | ||
| See also | extracting procedure | extract-documentation-from-scheme-file | |
| extracted-css-stylesheet | |||
| Form | extracted-css-stylesheet | ||
| Description | Variable holding the extracted value of css-stylesheet. The extracted value is only used if the similar manual-front-matters attribute is not provided. | ||
| See also | extracting procedure | extract-documentation-from-scheme-file | |
| extracted-css-stylesheet-copying | |||
| Form | extracted-css-stylesheet-copying | ||
| Description | Variable holding the extracted value of css-stylesheet-copying. The extracted value is only used if the similar manual-front-matters attribute is not provided. | ||
| See also | extracting procedure | extract-documentation-from-scheme-file | |
| extracted-source-destination-delta | |||
| Form | extracted-source-destination-delta | ||
| Description | Variable holding the extracted value of source-destination-delta. The extracted value is only used if the similar manual-front-matters attribute is not provided. | ||
| See also | extracting procedure | extract-documentation-from-scheme-file | |
| extracted-scheme-source-linking | |||
| Form | extracted-scheme-source-linking | ||
| Description | Variable holding the extracted value of scheme-source-linking. The extracted value is only used if the similar manual-front-matters attribute is not provided. | ||
| See also | extracting procedure | extract-documentation-from-scheme-file | |