Copyright © 2011 , Kurt Nørmark | ![]() |
This is the manual of the Scheme Elucidator 2. The Scheme Elucidator 2 is major new release of the original Scheme Elucidator. The Scheme Elucidator 2 uses an XML in LAML setup file, and it supports an XML in LAML documentation format. The original documentation format, based on a simple, special-purpose markup language, is still supported.
From LAML version 26, the Scheme Elucidator 2 also supports multiple versions of a source file. This represents another significant change of the tool.
Most important, this manual documents the Elucidator 2 XML-in-LAML language. In addition, we give a practical introduction to the Scheme Elucidator. We also provide documentation of the original textual documentation format, and a description of support for Elucidative Programming in Emacs.
You are invited to look at the examples, which comes with the Elucidator 2 and LAML. The LAML Tutorial is another example of documentation produced with the Scheme Elucidator 2. The paper Scheme Program Documentation Tools and the accompanying examples are also relevant.
For information about Elucidative Programming consult the Elucidative Programming Home Page.
The source program of the Scheme Elucidator is available as an Elucidative Program. At this point in time, the documentation has not been updated from the original Elucidator to the Elucidator 2. Notice, in this context, that this particular elucidative program illustrates the new version facility of the tool.
begin-documentation | An empty element that marks the beginning of the documentation |
color-entry | A color entry controls the coloring of a group of source programs. |
color-scheme | The color scheme controls the background coloring of the HTML source programs of the elucidator. |
doc-abstract | The documentation abstract as it appears in the documentation-intro form. |
doc-affiliation | The affiliation of the author as it appears in the documentation-intro form. |
doc-author | The author of the documentation as it appears in the documentation-intro form. |
doc-email | The email of the author as it appears in the documentation-intro form. |
doc-ref | A documentation cross reference. |
doc-title | The title of the documentation as it appears in the documentation-intro form. |
documentation-entry | A documentation entry is a sectional unit at the level below documentation sections. |
documentation-from | This clause addresses a separate documentation file authored in the special purpose textual documentation format. |
documentation-intro | This clause holds title, author, affiliation, email, and abstract information about the current elucidative program. |
documentation-section | A documentation section is a sectional unit at the level above documentation entries. |
elucidator | This is the absolute top-level form of the Scheme Elucidator. |
elucidator-front-matters | The elucidator front matters describe the program source files of the documentation bundle and the set of overall elucidator attributes. |
end-documentation | An empty element that marks the end of the documentation. |
entry-body | The body of a documentation-entry form |
entry-title | The title of a documentation-entry form |
manual-source | The description of SchemeDoc interface documentation, to which we generate links from the current elucidative program. |
new-rgb-color | The description of an RGB color. |
predefined-color | A name of a predefined color. |
program-source | The description of a single Scheme program source file to be included in the elucidative program. |
section-body | The body of a documentation-section clause. |
section-title | The title of a documentation-section clause. |
source-files | Scheme source files and/or Scheme interface documentation of the current documentation bundle. |
source-marker | A reference to a source marker. |
strong-prog-ref | A strong program reference from the documentation to a program entity. |
typographic-prog-ref | A typographic emphasis of a program name. |
version-group | A version group which enumerates a number of program sources. |
weak-prog-ref | A weak program reference from the documentation to a program entity. |
![]() ![]() ![]() 1 Practical introduction | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
When you have installed LAML on your computer you also have a full installation of the Scheme elucidator, including Emacs support of Elucidative Programming. The Emacs command M-x make-elucidator helps you establish a new elucidator. Follow the directives given from this command. From Emacs type use the command M-x elucidator-help to get brief help on the Elucidator editor commands. For more complete information see the section Emacs Support in this manual. The command M-x elucidate on an elucidator buffer activates the Elucidator from Emacs. The Elucidator is the tool which produces the web pages which presents the documentation bundle as set of HTML files. The main file is found in html/index.html. In addition, if the setup file is called f.laml, the main file is available as f.html in the source directory. Please notice the Tools > Scheme Elucidator menu in Emacs. When you read the Elucidator web pages you can navigate to the Help page via one of the 'Question Mark Icons' to get help on the possibilities offered by the Elucidator tool. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() ![]() ![]() 2 Commenting convensions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The source programs that are processed by the Scheme Elucidator will have to obey certain convension with respect the placement of comments. The reason is that comments are turned into syntactical constituents during the processing of the Scheme source programs. The rules are the following:
As we develop the Elucidator in the future, we will work in the direction minimizing the restrictions from above. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() ![]() ![]() 3 Top-level forms | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The top-level elucidator forms are described in this section. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | This is the absolute top-level form of the Scheme Elucidator. The use of this form is optional in the sense that the direct subforms, as they appear in the XML content model, can be elevated to top-level forms. The use of multiple top-level forms is convenient in cases where large volumes of documentation is present. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( elucidator-front-matters , begin-documentation , ( ( documentation-intro , ( documentation-section | documentation-entry ) * ) | documentation-from ) , end-documentation ) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
elucidator-front-matters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The elucidator front matters describe the program source files of the documentation bundle and the set of overall elucidator attributes. The color scheme used for the program sources is also defined in the elucidator front matters. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( color-scheme ? , source-files ) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | laml-resource | ( true | false ) | Is this elucidative program part of the LAML distribution, or located within the LAML directories. Possible values: true or false. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
table-of-contents | ( detailed | shallow ) | The default table of contents type. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
shallow-table-of-contents-columns | CDATA ( 3 ) | The number of columns in a shallow table of contents. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
detailed-table-of-contents-columns | CDATA ( 2 ) | The number of columns in a detailed table of contents. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
source-marker-presentation | ( image | text | colored-text ) | Controls the rendering of source markers in the documentation. Use of image causes presentation of small graphical color circles. Use of text causes textual presentation of the source markers. Use of colored-text also causes textual presentation of the source markers, with coloring of the text. image is recommended. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
source-marker-char | CDATA ( @ ) | The source marker character. A string of length 1. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
source-markers-in-program | ( show-all | show-documented | ignore ) | How and when to show source markers in the source program.
Source markers not shown are presented in raw form, such as @a. show-all: Show all source markers, including those not used in the actual documentation. show-documented: Show only source markers that are used in the actual documentation. ignore: Do not show source markers. The links from possible source markers in the documentation to the marked places in the program persist. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
browser-pixel-width | CDATA ( 1100 ) | The pixel width of the browser which shows an elucidative program. This number is used for some layout purposes which requires knowledge of available horizontal width. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
control-frame-pixel-height | CDATA ( 130 ) | The pixel height of the control frame. The control frame is the upper left frame of an elucidator. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
home-url | CDATA | An optional home URL of the elucidator. Can for instance be used for a link to a root page of several related elucidators. If relative, it is relative to the HTML target directory. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
next-url | CDATA | An optional link to the next elucidator in a sequence. Relative to the HTML directory of the current elucidator. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
previous-url | CDATA | An optional link to the previous elucidator in a sequence. Relative to the HTML directory of the current elucidator. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
scheme-report-version | ( r4rs | r5rs | none ) | Controls which version of the Scheme Report to use for this elucidative program. Use r4rs or r5rs to select the fourth or fifth Revised Report for linking from syntax/procedure names to appropriate places in the Scheme Report. Use none, in case you do not want to link to a Scheme Report. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
rnrs-url | CDATA | A link to a directory with an RnRS (R4RS/R5RS) Scheme Report. The attribute scheme-report-version controls the selection of Scheme Report. You should either use the default value (by not specifying this attribute) which gives you a link to an appropriate directory at the www.cs.aau.dk site. You can also use a link to the appropriate r4rs or r5rs directory in your local LAML directory (depending on the value of the attribute scheme-report-version). Either an absolute URL or a URL relative to the HTML directory of the current elucidator. If laml-resource is true, the value of this attribute is disregarded, and the rnrs-url always points at the r4rs/r5rs directory in your LAML distribution. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cross-reference-index | ( per-letter | aggregated | none ) | The kind of cross reference index used for the current elucidator. The cross reference index shows the abstractions in which a given name is used. The value per-letter breaks the index in one page per letter in the alphabet. The value aggregated joins all entries in a single page. The value none suppresses the cross reference index. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
defined-name-index | ( per-letter | aggregated | none ) | The kind of defined name index used for the current elucidator. The defined name index enumerates all names defined in one of the source programs in the current elucidator. The value per-letter breaks the index in one page per letter in the alphabet. The value aggregated joins all entries in a single page. The value none suppresses the defined name index. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
duplicated-name-index | ( true | false ) | Duplicated names are defined at two or more different locations in the source files of the documentation bundle. This boolean attribute controls the generation of an index of duplicated names. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
initial-program-frame | ( blank | first-source-file ) | Controls the initial contents of the elucidator program frame. The value blank shows an introductory text in the program frame. The value first-source-file shows the first mentioned source program the source-files clause of the elucidator front matters. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
large-font-source-file | ( true | false ) | Controls the generation of large font HTML source files. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
small-font-source-file | ( true | false ) | Controls the generation of small font HTML source files. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
default-source-file-font-size | ( small | large ) | Gives the default font size of the HTML source files. Links from the documentation and indexes point at these versions of the source files. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
program-menu | ( inline-table | separate-frame | none ) | Controls the generation of the program menu of the elucidator. The program menu is either located in the control frame or in a separte frame in the upper right corner. None is not yet supported. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
manual-frame-from-program | ( documentation-frame | program-frame | other ) | Controls which frame to use for presentation of SchemeDoc manuals links from the program. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
manual-frame-from-documentation | ( documentation-frame | program-frame | other ) | Controls which frame to use for presentation of SchemeDoc manuals links from the documentation. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-escape-char | CDATA | Defines the documentation escape character. The default value is "\" . Textual documentation only. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
program-link-prefix-char | CDATA | Defines the program link prefix character. The default value is "{" . Textual documentation only | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
program-link-suffix-char | CDATA | Defines the program link suffix character. The default value is "}" . Textual documentation only | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-link-prefix-char | CDATA | Defines the documentation prefix character. The default value is "[" . Textual documentation only | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-link-suffix-char | CDATA | Defines the documentation suffix character. The default value is "]" . Textual documentation only | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
strong-link-char | CDATA | The defines the strong link character. The default value is "*" . Textual documentation only | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
weak-link-char | CDATA | Defines the weak link character. The default value is "+" . Textual documentation only | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
none-link-char | CDATA | Defines the 'non-link' character. The default value is "-" . Textual documentation only | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
default-program-link | ( weak | strong | none ) | Defines the default program link type. Textual documentation only | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
author-mode | ( true | false ) | Controls a few aspects of the rendering of the documentation. Intended to help the author of an Elucidative program. Not well-developed in the current version. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
processing-mode | ( silent | verbose ) | Controls the amount of information printed while processing a documentation bundle. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
warn-if-no-doc-source-marker | ( true | false ) | If true, a warning is issued if we encounter a source marker in a program source file for which there is no counter part in the documentation. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
warn-if-multiple-doc-source-markers | ( true | false ) | If true, a warning is issued if we encounter a source marker in a program source file for which there a two or more counter parts in the documentation. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
source-destination-delta | CDATA ( html/ ) | A relative file path that controls the location of the HTML directory of the elucidator. The file path is relative to the source directory that holds the LAML setup/documentation file. Must be terminated by a forward slash: '/'. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
css-documentation-stylesheet | CDATA ( documentation ) | The proper name of the CSS stylesheet for the documentation. The CSS stylesheet is located in the stylesheets directory of styles/xml-in-laml/elucidator/. There may also be a stylesheets directory of the directory, which holds the LAML source file of the elucidative program. Defaults to "documentation". The stylesheet that comes with the elucidator is appended to the stylesheet given by the author of the current elucidative program. If a stylesheet file does not exist, it is considered as being empty. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
css-program-stylesheet | CDATA ( program ) | The proper name of the CSS stylesheet for Scheme source programs. The CSS stylesheet is located in the stylesheets directory of styles/xml-in-laml/elucidator/. There may also be a stylesheets directory of the directory, which holds the LAML source file of the elucidative program. Defaults to "program". The stylesheet that comes with the elucidator is appended to the stylesheet given by the author of the current elucidative program. If a stylesheet file does not exist, it is considered as being empty. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
render-doc-comments | ( true | false ) | Controls the rendering of documentation comments in source programs. If false, SchemeDoc documentation comments (normally two-semicolon comments) are not rendered. The value false is used by SchemeDoc in its rendering of source programs by means of the Scheme Elucidator. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Note | Notice that the attributes that control the various special characters for textual documentation, ...-char , have not yet been tested carefully. You may expect minor problems if you use them. We almost exclusively use LAML style documentation for our purposes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-from | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | This clause addresses a separate documentation file authored in the special purpose textual documentation format. This clause is used instead of documentation-intro, documentation-section, and documentation-entry clauses. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | src * | CDATA | The file path of the textual documentation file. Can either be an absolute file path or a file path relative to the directory that holds the LAML setup file. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-intro | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | This clause holds title, author, affiliation, email, and abstract information about the current elucidative program. Used in case the documentation is given on XML-in-LAML form in documentation-section and documentation-entry clauses. Cannot be used together with a document-from clause. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( doc-title , doc-author , doc-affiliation , doc-email , doc-abstract ) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
begin-documentation | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | An empty element that marks the beginning of the documentation | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-section | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A documentation section is a sectional unit at the level above documentation entries. Conceptually (but the physically) a documentation section holds a number of documentation entries. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( section-title , section-body ) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | id * | CDATA | A unique id of the section. Used for cross reference purposes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
program-version | CDATA | A program version number to enforce for all strong-prog-ref and weak-prog-ref clauses in this documentation entry. Use of this attribute assumes, that the entry only documents program aspects from a single source file. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-entry | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A documentation entry is a sectional unit at the level below documentation sections. You can think of a documentation-entry as a subsection. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( entry-title , entry-body ) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | id * | CDATA | A unique name (id) of the entry. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
program-version | CDATA | A program version number to enforce for all strong-prog-ref and weak-prog-ref clauses in this documentation entry. Use of this attribute assumes, that the entry only documents program aspects from a single source file. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
end-documentation | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | An empty element that marks the end of the documentation. Internally, this clause initiates the majority of the processing of the Scheme Elucidator. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() ![]() ![]() 4 Front matters subforms | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
In this section we describe the possible subforms of the elucidator front matters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
color-scheme | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The color scheme controls the background coloring of the HTML source programs of the elucidator. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( color-entry ) * | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator-front-matters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
color-entry | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A color entry controls the coloring of a group of source programs. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( new-rgb-color | predefined-color ) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | group * | CDATA | The name of the group of source programs. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | color-scheme | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
new-rgb-color | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The description of an RGB color. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | red * | CDATA | The amount of red. A decimal number between 0 and 255. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
green * | CDATA | The amount of green. A decimal number between 0 and 255. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
blue * | CDATA | The amount of blue. A decimal number between 0 and 255. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | color-entry | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
predefined-color | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A name of a predefined color. One of documentation-background-color, program-background-color-1, ... program-background-color-10. Or one of the LAML color constants. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | color-entry | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
source-files | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | Scheme source files and/or Scheme interface documentation of the current documentation bundle. Scheme interface documentation is produced by LAML SchemeDoc. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( program-source | version-group | manual-source ) * | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator-front-matters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
program-source | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The description of a single Scheme program source file to be included in the elucidative program. If textual content is provide, it becomes a more user friendly (longer) name of the source program than the key attribute. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | key | CDATA | A nick name of the source file. Intended for convenient referencing purposes in program reference forms. If a key attribute is given in a surrounding version-group element, you should not given any key attribute her. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
file-path * | CDATA | The file path of the source program. Relative to the directory that holds the LAML setup file of the current elucidator. Can also be an absolute file path. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
language | CDATA | The programming language being used. Optional. Always Scheme in the current version. Intended for future generalizations. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
group | CDATA | The group to which the source file belongs. Groups are defined in color entries of a color scheme. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
process | ( true | false ) | Controls the processing of the source file. If true, process the file. If false, do not process the file. In this case, we rely on saved information from the latest processing of the source file. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing elements | source-files version-group | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
manual-source | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The description of SchemeDoc interface documentation, to which we generate links from the current elucidative program. By including an entry to a SchemeDoc manual page, the elucidator can generate links to the SchemeDoc documentation entries, both from the documentation and from source programs. If textual content is provided, it becomes a more user friendly (longer) name of the manual than the key attribute. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 can be with or without manlsp extension. (SchemeDoc generates files with manlsp extension together with an HTML file.) The given file is relative to the directory that holds the elucidator LAML setup file. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
url | CDATA | Not used anymore. Do not give any url attribute. The URL of the manual is now derived automatically from the file-path and from internal manual information in the manlsp file. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | source-files | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
version-group | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A version group which enumerates a number of program sources. The oldest program version is given as the first program-source in the version-group. The last program-source in the version group is the newest one (the version most up-to-date). The initial version number is 1 (one). Thus, if there are three program sources in the version group, the newest is of version 3, and the oldest is of version 1. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | ( program-source ) + | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | key * | CDATA | The source key shared between all versions of program sources in the version group. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
group | CDATA | The group to which all program sources in this version group belongs. Groups are defined in color entries of a color scheme. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | source-files | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() ![]() ![]() 5 Documentation subforms | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
In this section we describe the possible subforms of documentation intro, documentation sections, and documentation entries. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
doc-title | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The title of the documentation as it appears in the documentation-intro form. Only used with XML-in-LAML documentation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-intro | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
doc-author | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The author of the documentation as it appears in the documentation-intro form. Only used with XML-in-LAML documentation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-intro | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
doc-affiliation | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The affiliation of the author as it appears in the documentation-intro form. Only used with XML-in-LAML documentation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-intro | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
doc-email | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The email of the author as it appears in the documentation-intro form. Only used with XML-in-LAML documentation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-intro | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
doc-abstract | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The documentation abstract as it appears in the documentation-intro form. Only used with XML-in-LAML documentation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA | a | abbr | acronym | address | applet | b | basefont | bdo | big | blockquote | br | button | center | cite | code | del | dfn | dir | div | dl | em | fieldset | font | form | h1 | h2 | h3 | h4 | h5 | h6 | hr | i | iframe | img | input | ins | isindex | kbd | label | map | menu | noframes | noscript | object | ol | p | pre | q | s | samp | script | select | small | span | strike | strong | sub | sup | table | textarea | tt | u | ul | var )* | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-intro | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
section-title | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The title of a documentation-section clause. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-section | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
section-body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The body of a documentation-section clause. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA | a | abbr | acronym | address | applet | b | basefont | bdo | big | blockquote | br | button | center | cite | code | del | dfn | dir | div | dl | em | fieldset | font | form | h1 | h2 | h3 | h4 | h5 | h6 | hr | i | iframe | img | input | ins | isindex | kbd | label | map | menu | noframes | noscript | object | ol | p | pre | q | s | samp | script | select | small | span | strike | strong | sub | sup | table | textarea | tt | u | ul | var )* | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | body-style | ( normal | grey | small | grey-small ) | - | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-section | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
entry-title | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The title of a documentation-entry form | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-entry | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
entry-body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | The body of a documentation-entry form | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA | a | abbr | acronym | address | applet | b | basefont | bdo | big | blockquote | br | button | center | cite | code | del | dfn | dir | div | dl | em | fieldset | font | form | h1 | h2 | h3 | h4 | h5 | h6 | hr | i | iframe | img | input | ins | isindex | kbd | label | map | menu | noframes | noscript | object | ol | p | pre | q | s | samp | script | select | small | span | strike | strong | sub | sup | table | textarea | tt | u | ul | var )* | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | body-style | ( normal | grey | small ) | - | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-entry | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() ![]() ![]() 6 Reference forms | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
In this section the forms used for reference purposes are documented. These forms are used in documentation sections and entries, and only with XML-in-LAML documentation. The forms in this section are not used when documentation-from is applied. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
strong-prog-ref | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A strong program reference from the documentation to a program entity. The strong reference is rendered as an anchored link from the documentation. A strong program reference is intended to be given in a documentation context where the referred program name is explained . The target is either a definition in one of the program sources, or an entry in one of the manual sources. If the textual content is non-empty it is used as the source anchor name of the link, as located in the documentation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | file | CDATA | The name of a source file or manual file. This corresponds to the key attributes of program-source and manual-source elements. This attribute is optional. In case no file name is given, all program sources and manual sources are searched for a unique definition that matches the name attribute (the next attribute). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
vers | CDATA | A particular version number of the file. Source files in a version group are implicitly numberede from 1 to n, in the order they are given within the version group. Number 1 is the oldest version. Defaults to the highest possible version number (the newest version). If this attribute appears the file attribute must also appear. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
name | CDATA | The name of a definition, either in a source file or a manual file. This attribute is also optional. In cases where the name attribute is omitted, a reference to the overall source file or manual is generated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
file-part | CDATA | A part name (section name) of file. Used only to address a section id in a SchemeDoc manual. In these cases the file and file-part attributes are given. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
weak-prog-ref | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A weak program reference from the documentation to a program entity. The weak reference is rendered as an anchored link from the documentation. A weak program reference is intended to be given in a documentation context where the referred program name is only mentioned , but not explained. The target is either a definition in one of the program sources, or an entry in one of the manual sources. If the textual content is non-empty it is used as the source anchor name of the link, as located in the documentation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | (#PCDATA) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | file | CDATA | The name of a source file or manual file. This corresponds to the key attributes of program-source and manual-source elements. This attribute is optional. In case no file name is given, all program sources and manual sources are searched for a unique definition that matches the name attribute (the next attribute). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
vers | CDATA | A particular version number of the file. Source files in a version group are implicitly numberede from 1 to n, in the order they are given within the version group. Number 1 is the oldest version. Defaults to the highest possible version number (the newest version). If this attribute appears the file attribute must also appear. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
name | CDATA | The name of a definition, either in a source file or a manual file. This attribute is also optional. In cases where the name attribute is omitted, a reference to the overall source file or manual is generated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
file-part | CDATA | A part name (section name) of file. Used only to address a section id in a SchemeDoc manual. In these cases the file and file-part attributes are given. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
typographic-prog-ref | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A typographic emphasis of a program name. No linking is involved. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | name * | CDATA | The name to be emphasized. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
doc-ref | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A documentation cross reference. The reference is rendered as an anchored link from one place in the documentation to another. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | name * | CDATA | The name of an entry or an id of a section which becomes the target of the link. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
source-marker | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | A reference to a source marker. The source marker denotes an explicit location in some definition in a source program. The source marker is implicitly associated with the nearest preceding strong program reference. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | name * | CDATA | The name of the source marker. A string of length one, being one of the letters a, b, c, d, e, f, g, h, i, j, k, l, m, n, or o. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() ![]() ![]() 7 The textual documentation format | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The textual documentation format, as introduced in the original Elucidator, is still supported in this version of the tool. The textual format is inserted into the documentation by means of the element documentation-from. If the textual documentation form is used, the elements defined in the previous sections are not used. First we describe the documentation intro (corresponding to the function documentation-intro ): .TITLE title .AUTHOR author .EMAIL email .AFFILIATION affiliation .ABSTRACT abstract .END After the documentation intro comes a number of documentation sections: (corresponding to the function documentation-section ): .SECTION id .TITLE title .BODY body-text .END Finally, in between sections we have documentation entries (corresponding to the function documentation-entry ) .ENTRY id .TITLE title .BODY body-text .END The templates shown above corresponds exactly to the insertions done by the Emacs lisp template functions, which are described in the last part of this manual. Inside the body text of sections and entries you can make links to program fragments, or more precisely, to the definitions in a Scheme program.
If {f} is used without a leading +, *, or -, the value of the variable default-program-link determines the default kind of linking from documentation to program. Possible values of default-program-link is one of the symbols weak , strong , or none . If {f} , {+f} , {*f} , or {file:f} does not refer to a program name in the documentation bundle, as defined by the program-source clauses, we attempt to link to a manual entry, as defined by the manual-source clauses. It is possible to mark a particular place in program by means of a source marker. A source marker in a program must be at a comment place, and it is denoted by @x , where x is a letter in the interval [a..o]. @a corresponds to ( source-marker 'name "a") A source marker in a program, such as @a , must be followed by blank space (a space, CR, etc). Source markers can also be used in the documentation, in which they link to the detailed program place via the closest, preceding strong documentation/program link. Make sure that you do not use the same source marker to refer to places in different definitions within a single section or entry in the documentation. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() ![]() ![]() 8 Emacs support | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Using Emacs (GNU Emacs on either windows or unix) there exists a substantial support of elucidative programming. The main idea is to keep track of all the files in a bundle. We support a splitted frame in Emacs, with documentation in the top-most window, and a program in the bottom window in an Emacs frame. We will now describe the Emacs editor commands which support elucidative programming. These are defined in the Emacs lisp file 'elucidator.el' which resides in the same directory as the 'elucidator.scm' program (which implements the Elucidator tool). The keybindings given below correspond to the hygienic keybindings. If you use the original LAML keybindings you should, in general disregard the initial C-c.
In addition, we support a number of insert functions which allows template insertion. These functions are all defined as part of LAML emacs lisp template facility. The template insertions commands are:
Any command described above is activated by M-x command (i.e., Esc X command) or via the keyboard bindings described above. A Emacs menu of Elucidator commands is available under Tools > Scheme Elucidator. In addition, the generic LAML Emacs commands are useful when you write LAML style documentation in this tool. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Mirror name: | elucidator2 |
Automatic loading of common XML-in-LAML library? | No |
List of action elements | (elucidator-front-matters begin-documentation documentation-intro documentation-section documentation-entry documentation-from end-documentation) |
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-first |