Generated: July 9, 2004, 14:28:25 | Copyright © 2004 , 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.
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.
1. Practical introduction | 4. Documentation subforms | 7. Emacs support |
2. Top-level forms | 5. Reference forms | |
3. Front matters subforms | 6. The textual documentation format |
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. |
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 direction 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 'Elucidator editor support using Emacs' 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 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 | 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. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
r4rs-url | CDATA | A link to a directory with an R4RS 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.auc.dk site. You can also use a link to the r4rs directory in your local LAML directory. Either an absolute URL or a URL relative to the HTML directory of the current elucidator. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 is not yet supported. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 is not yet supported. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
program-link-prefix-char | CDATA | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
program-link-suffix-char | CDATA | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-link-prefix-char | CDATA | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation-link-suffix-char | CDATA | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
strong-link-char | CDATA | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
weak-link-char | CDATA | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
none-link-char | CDATA | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
default-program-link | ( weak | strong | none ) | Still experimental | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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: '/'. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | elucidator | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
3 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 | 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | key * | CDATA | A nick name of the source file. Intended for convenient referencing purposes in program reference forms. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 element | source-files | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML content model | EMPTY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
XML attributes Required: * Default values: red | key * | CDATA | - | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
file-path * | CDATA | An absolute or 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.) Non-absolute file paths are relative to the directory that holds the elucidator LAML setup file. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
url * | CDATA | An absolute or relative URL to the manual HTML file, as generated by SchemeDoc. Typically, but not necessarily, this URL addresses a neighbor file of the file addressed by the file-path. A non-absolute URL is relative to the HTML directory of the current elucidator. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | source-files | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
4 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 )* | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 )* | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also | enclosing element | documentation-entry | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
5 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 | An optional key name of a source file. The key of a source file is given in a program-source form or in a manual-source form. In case no key name is given the program sources and manual sources are searched for a unique definition that matches the name attribute. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
name | CDATA | The name of a definition, either in a source file or a manual file. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
file-part | CDATA | A part name (section name) of file. Used only to address a section id in a SchemeDoc manual. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | An optional key name of a source file. The key of a source file is given in a program-source form or manual-source form. In case no key name is given the program sources and manual sources are searched for a unique definition that matches the name attribute. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
name | CDATA | The name of a definition, either in a source file or a manual file. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
file-part | CDATA | A part name (section name) of file. Used only to address a section id in a SchemeDoc manual. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
6 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. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
7 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. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||