(((title . "Reference Manual of LAML SchemeDoc") (author . "Kurt N\370rmark") (affiliation . "Department of Computer Science Aalborg University Denmark") (abstract . "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.\n SchemeDoc extracts documentation comments at the top\n 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.\n In addition, SchemeDoc can be used manually, without any kind of extraction. All possibilities are made available via the\n 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,\n 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.") (scheme-source-file . not-provided) (laml-resource . "true") (documentation-commenting-style . not-provided) (default-attribute-explanation . not-provided) (source-destination-delta . not-provided) (css-prestylesheet . "normal") (css-stylesheet . "fancy") (css-stylesheet-copying . not-provided) (make-dtd-manual-template . "false") (keep-syntactical-comment-file . not-provided) (manual-destination-name . not-provided) (mirror-names-defined . not-provided) (mirror-name-prefix . not-provided) (attribute-sorting . "as-in-dtd") (scheme-source-linking . not-provided)) ((section-id "doc-comments") (kind "manual-section") (section-title "Documentation Comments") (section-body "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) 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. A documentation comment is a comment block with two or more semicolons. The comment extraction facility 'eats' and eliminates a possible single white space following the ';'. Remaining white spaces are preserved. All one comment semicolon comments are ignored by the SchemeDoc tool. 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. 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. 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) 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. The number of semicolons used for a documentation comment is not significant. 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. The documentation comment character is a distinguished character, which per default is '!'. 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. The comment extraction facility 'eats' and eliminates a possible single white space following the '!' or ';'. Remaining white spaces are preserved. 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. 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. 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. nbsp Caveat: During the extraction of comments from Scheme programs, the Scheme source program is preprocessed. The preprocessor transforms all lexical comments to syntactical constituents: \n ; This is a comment =>\n\n (comment!!! 1 \"This is a comment\")\n 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: \n '(x .\n y ; A dotted pair)\n Which is transformed to \n '(x .\n y (comment 1 \"A dotted pair\"))\n 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")) ((section-id "internal-tagging") (kind "manual-section") (section-title "Internal SchemeDoc tags") (section-body "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: \n ;; Return the fifth element of a list\n ;; .form (fifth x)\n ;; .parameter x is a list\n (define fifth (make-selector-function 5)) The following is equivalent (using internal tags before the function description): \n ;; .form (fifth x)\n ;; .parameter x is a list\n ;; Return the fifth element of a list\n (define fifth (make-selector-function 5)) The general format of a SchemeDoc comment with internal tagging is: \n .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: 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). The only characters allowed between the semicolons and .key are blank space characters (space, tab). 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. 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. 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. 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): \n .form (form-name par1 par2)\n .pre-condition Some precondition\n .post-condition Some postcondition\n .parameter par-name description\n .attribute attr-name implied/required description\n .example some example\n .reference \"category\" \"anchor\" \"url\"\n .internal-references \"category\" \"ref1\" \"ref2\" ...\n .misc Miscelaneous information\n .comment Internal comment\n .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 \n ;; ... on so on Instead, you should escape the first '.': \n ;; $... 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): \n .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: \n .title Manual title\n .author Manual author\n .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): \n .laml-resource false ; true or false\n .css-prestylesheet compact ; small, small-compact, compact, normal, or large\n .css-stylesheet original ; original, orginal-bordered, fancy, argentina, brazil, dark-green\n .css-stylesheet-copying true ; true or false\n .scheme-source-linking true ; true or false\n .source-destination-delta man/ ; a relative directory path from the source to the destination\n .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: \n ;;;; .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 \n (\n (description \"Return the fifth element of a list\")\n (form \"(fifth x)\")\n (param \"x is a list\")\n ) 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.")) ((section-id "custom-tags") (kind "manual-section") (section-title "Custom tags") (section-body "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: \n .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.")) ((kind "manual-page") (title "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 (example "(define supported-manual-page-elements '(title library kind form description pre-condition post-condition parameters example cross-references misc comment returns\n xml-in-laml-example-form attributes content-model level xml-in-laml-attributes side-effects throws my-own-tag))")) (misc "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)") (cross-references)) ((kind "manual-page") (title "manual-element-order") (form "manual-element-order") (description "The presentation ordering of tags in a SchemeDoc manual. A list of symbols.") (examples (example "(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 \n pre-condition parameters xml-in-laml-attributes returns side-effects post-condition throws example cross-references misc comment))")) (misc "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)") (cross-references)) ((kind "manual-page") (title "schemedoc-custom-tag-presentation") (form "(schemedoc-custom-tag-presentation kind)") (parameters (parameter "kind" "The tag name (a symbol)")) (returns "A string which presents kind") (misc "Use a cond with an else clause that returns (as-string kind)") (cross-references)) ((section-id "top-forms") (kind "manual-section") (section-title "Top level form") (section-body "Here starts the documentation of SchemeDoc and the LAML manual document style. We start with the top level form.")) ((kind "manual-page") (title "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). ") (attribute-descriptions) (examples (example "(manual \n (manual-front-matters ...)\n (manual-section ...)\n (manual-page ...) \n)") (example "(manual \n (manual-front-matters ...)\n (manual-from-scheme-file 'src \"file-path\")\n)") (example "(manual \n (manual-front-matters ...)\n (manual-from-xml-dtd 'src \"dtd-file-path\")\n)") (example "(manual \n (manual-front-matters ...)\n (manual-section ...)\n (manual-page ...)\n (merged-manual-from-xml-dtd 'src \"dtd-file-path\")\n)")) (cross-references) (kind "manual-page") (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)))") (attributes)) ((section-id "front-stuff") (kind "manual-section") (section-title "Front matters forms") (section-body "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.")) ((kind "manual-page") (title "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.") (attribute-descriptions (attribute-description "laml-resource" "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.") (attribute-description "default-attribute-explanation" "The default attribute explanation in case no other explanation is available") (attribute-description "css-prestylesheet" "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.") (attribute-description "css-stylesheet" "The name of the last part of the CSS stylesheet, for additional styling. A name without file extension. See visual gallery for possibilities.") (attribute-description "css-stylesheet-copying" "Is the CSS stylesheet copied to the destination directory") (attribute-description "make-dtd-manual-template" "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'.") (attribute-description "documentation-commenting-style" "Controls which documentation commenting style to use for extraction of documentation from Scheme soruce file comments. See the section about documentation comments.") (attribute-description "keep-syntactical-comment-file" "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.") (attribute-description "source-destination-delta" "The relative file path from the manual source directory to the HTML target directory. You are responsible for creating the directory/directories.") (attribute-description "manual-destination-name" "The proper name of the manual destination file (the HTML file and others). Defaults to the proper name of the LAML source file. ") (attribute-description "mirror-names-defined" "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. ") (attribute-description "mirror-name-prefix" "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-description "attribute-sorting" "Only for XML DTD documentation: The ordering of attributes in the XML DTD manual. Either as-in-dtd or by-attribute-name.") (attribute-description "scheme-source-linking" "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.") (attribute-description "scheme-report-version" "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.") (attribute-description "rnrs-url" "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.") (attribute-description "example-repository" "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.") (attribute-description "element-cross-reference-url-fn" "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.") (attribute-description "element-cross-reference-anchor-text" "A fixed text that serves as anchor text for URLs generated by the function named by the element-cross-reference-url-fn attribute.") (attribute-description "verbosity-level" "How much information is given by SchemeDoc during processing. 0: Minimal information 1: One output line for each item processed. Defaults to 0.") (attribute-description "xml-protected-descriptions" "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.")) (cross-references) (kind "manual-page") (content-model "(manual-title?,manual-author?,manual-affiliation?,manual-abstract?,scheme-source-linking-manual*)") (attributes (attribute "laml-resource" ("true" "false") "false") (attribute "verbosity-level" "CDATA" "0") (attribute "documentation-commenting-style" ("multi-semicolon" "documentation-mark") "multi-semicolon") (attribute "default-attribute-explanation" "CDATA" "#IMPLIED") (attribute "source-destination-delta" "CDATA" "#IMPLIED") (attribute "css-prestylesheet" "CDATA" "#IMPLIED") (attribute "css-stylesheet" "CDATA" "#IMPLIED") (attribute "css-stylesheet-copying" ("true" "false") "true") (attribute "make-dtd-manual-template" ("true" "false") "false") (attribute "keep-syntactical-comment-file" ("true" "false") "false") (attribute "manual-destination-name" "CDATA" "#IMPLIED") (attribute "mirror-names-defined" ("true" "false") "true") (attribute "mirror-name-prefix" "CDATA" "") (attribute "attribute-sorting" ("as-in-dtd" "by-attribute-name") "as-in-dtd") (attribute "scheme-source-linking" ("true" "false") "false") (attribute "scheme-report-version" ("r4rs" "r5rs" "none") "r5rs") (attribute "rnrs-url" "CDATA" "#IMPLIED") (attribute "xml-protected-descriptions" ("true" "false") "true") (attribute "example-repository" "CDATA" "#IMPLIED") (attribute "element-cross-reference-url-fn" "CDATA" "#IMPLIED") (attribute "element-cross-reference-anchor-text" "CDATA" "#IMPLIED")) (cross-references (internal-references "enclosing element" "manual"))) ((kind "manual-page") (title "manual-title") (description "The title of the manual") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to the .title tag in 4-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-front-matters"))) ((kind "manual-page") (title "manual-author") (description "The author(s) of a manual") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to the .author tag in 4-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-front-matters"))) ((kind "manual-page") (title "manual-affiliation") (description "The affiliation of the manual author. May be a number of separate strings in sequence.") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to the .affiliation tag in 4-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-front-matters"))) ((kind "manual-page") (title "manual-abstract") (description "The abstract of the manual") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to the initial text of a 4-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-front-matters"))) ((kind "manual-page") (title "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.") (attribute-descriptions (attribute-description "key" "A unique short name which identifies this manual. You can chose the name.") (attribute-description "file-path" "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.) ") (attribute-description "url" "Not used anymore.")) (cross-references (reference "similar elucidator form" "manual-source" "../../elucidator-2/man/elucidator.html#manual-source")) (kind "manual-page") (content-model "(#PCDATA)") (attributes (attribute "key" "CDATA" "#REQUIRED") (attribute "file-path" "CDATA" "#REQUIRED") (attribute "url" "CDATA" "#IMPLIED")) (cross-references (internal-references "enclosing element" "manual-front-matters"))) ((section-id "man-types") (kind "manual-section") (section-title "Manual extraction forms") (section-body "Different forms with which to extract manual information from other sources.")) ((kind "manual-page") (title "manual-from-scheme-file") (description "Extract a manual via SchemeDoc from a Scheme source file") (attribute-descriptions (attribute-description "src" "An absolute path to the Scheme source file, or a path relative to the LAML startup directory")) (cross-references) (kind "manual-page") (content-model "EMPTY") (attributes (attribute "src" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing elements" "manual" "manual-from-scheme-files"))) ((kind "manual-page") (title "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.") (cross-references) (kind "manual-page") (content-model "(manual-from-scheme-file+)") (attributes) (cross-references (internal-references "enclosing element" "manual"))) ((kind "manual-page") (title "manual-from-xml-dtd") (description "Extract a partial manual from an XML Document Type Defintion (DTD)") (attribute-descriptions (attribute-description "src" "An absolute path to the DTD, or a path relative to the LAML startup directory")) (cross-references) (kind "manual-page") (content-model "EMPTY") (attributes (attribute "src" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing element" "manual"))) ((kind "manual-page") (title "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.") (attribute-descriptions (attribute-description "src" "An absolute path to the DTD, or a path relative to the LAML startup directory")) (cross-references) (kind "manual-page") (content-model "EMPTY") (attributes (attribute "src" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing element" "manual"))) ((section-id "manual-page-forms") (kind "manual-section") (section-title "Manual pages") (section-body "A manual page describes the properties of a a single function, variable, or XML element.")) ((kind "manual-page") (title "manual-page") (description "The description of an entity such as a function, variable, or XML element in terms of a number of different constituents.") (attribute-descriptions (attribute-description "name" "The name of the entity")) (cross-references) (kind "manual-page") (content-model "(form | description | example-form | precondition | postcondition | parameters | examples | external-reference | internal-references | comment | misc | returns | attribute-descriptions)*") (attributes (attribute "name" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing element" "manual"))) ((kind "manual-page") (title "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!") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to the initial text of a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "form") (description "Describes the head - or signature - of the entity") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to a .form tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA)") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "example-form") (description "Describes an example of a head - or signature - of the entity") (attribute-descriptions) (cross-references) (kind "manual-page") (content-model "(#PCDATA)") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "precondition") (description "This condition must be true in order to call a function or procedure") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to a .pre-condition tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA)") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "postcondition") (description "This condition must be true if/when the function or procedure terminates") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to a .post-condition tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA)") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "parameters") (description "A container for the descriptions of individual parameters") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to a number of .parameter tags in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(parameter*)") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "parameter") (description "The description of a named parameter") (attribute-descriptions (attribute-description "name" "The name of a parameter")) (misc "Relation to SchemeDoc: This form corresponds to a .parameter tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes (attribute "name" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing element" "parameters"))) ((kind "manual-page") (title "examples") (description "Zero, one or more concrete examples") (attribute-descriptions) (cross-references) (kind "manual-page") (content-model "(example*)") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "example") (description "An example of the call of a function or procedure, and some hints of the outcome") (attribute-descriptions) (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "examples"))) ((kind "manual-page") (title "external-reference") (description "A link to a web resource external to this manual") (attribute-descriptions (attribute-description "href" "The URL of the external resource") (attribute-description "category" "The role of this external reference - a single word or a very short phrase")) (misc "Relation to SchemeDoc: This form corresponds to a .reference tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes (attribute "href" "CDATA" "#REQUIRED") (attribute "category" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "internal-references") (description "A link to other manual pages or manual sections in this manual") (attribute-descriptions (attribute-description "category" "The role of this internal reference - a single word or a very short phrase")) (misc "Relation to SchemeDoc: This form corresponds to a .internal-references tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(name-ref*)") (attributes (attribute "category" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "name-ref") (description "A name of another manual-page or manual-section") (attribute-descriptions) (cross-references) (kind "manual-page") (content-model "(#PCDATA)") (attributes) (cross-references (internal-references "enclosing element" "internal-references"))) ((kind "manual-page") (title "comment") (description "An internal comment about the enclosing manual-page") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to a .comment tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "misc") (description "A miscellaneous remark about the documented entity") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to a .misc tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "returns") (description "The description of the returned value of a function") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to a .returns tag in a 2-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "attribute-descriptions") (description "The container of a number of attribute-description clauses") (attribute-descriptions) (cross-references) (kind "manual-page") (content-model "(attribute-description*)") (attributes) (cross-references (internal-references "enclosing element" "manual-page"))) ((kind "manual-page") (title "attribute-description") (description "A description of a single XML attribute") (attribute-descriptions (attribute-description "name" "The name of the attribute")) (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes (attribute "name" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing element" "attribute-descriptions"))) ((section-id "manual-section-forms") (kind "manual-section") (section-title "Manual sections") (section-body "A manual section is a grouping of a number of related manual-pages")) ((kind "manual-page") (title "manual-section") (description "A manual section") (attribute-descriptions (attribute-description "id" "A unique id of a manual section. Used for section cross references and references to manual sections from manual pages")) (misc "Relation to SchemeDoc: The id attribute corresponds to the internal .section-id tag of a 3-semicolon comment in a Scheme programs.") (cross-references) (kind "manual-page") (content-model "(section-title,section-body?)") (attributes (attribute "id" "CDATA" "#REQUIRED")) (cross-references (internal-references "enclosing element" "manual"))) ((kind "manual-page") (title "section-title") (description "The title of this manual section") (attribute-descriptions) (misc "Relation to SchemeDoc: This form corresponds to the first sentence of 3-semicolon comment in a Scheme source file.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-section"))) ((kind "manual-page") (title "section-body") (description "A overall description of the manual pages in this section") (attribute-descriptions) (misc "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.") (cross-references) (kind "manual-page") (content-model "(#PCDATA |div | span)*") (attributes) (cross-references (internal-references "enclosing element" "manual-section"))) ((section-id "aux") (kind "manual-section") (section-title "The auxiliary manlsp file") (section-body "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.")))