Generated: Monday, November 14, 2011, 09:15:05 Copyright © 2011 , Kurt NÝrmark The local LAML software home page

The Scheme Elucidator 2 Reference Manual

Kurt NÝrmark normark@cs.aau.dk Department of Computer Science Aalborg University Denmark

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.

Table of Contents:
1. Practical introduction 4. Front matters subforms 7. The textual documentation format
2. Commenting convensions 5. Documentation subforms 8. Emacs support
3. Top-level forms 6. Reference forms
A. Mirror Information Appendix

Alphabetic index:
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:

  • define forms: Comments are not allowed in between '(' and define, between define and the defined name, or within the signature of a function definition.
  • let forms: Comments are not in between '(' and let between let and the namebindings. However, within the name binding lists, comments are allowed at every position.
  • lambda forms: Comments are not allowed within the list of formal parameters.
  • syntax-rules forms: Comments are only allowed within the patterns and the templates. At all other possitions, comments are prohibited.

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.

  • Using the notation {+f} a weak link to the definition of f is created. This corresponds to (weak-prog-ref 'name "f"). Here we just mention f without explaining it.

  • Using {*f} creates a strong link at a place, where f is explained. This corresponds to (strong-prog-ref 'name "f").

  • Using {-f} creates a typographical emphasis of f , but no linking This corresponds to (typographic-prog-ref 'name "f").

  • In all three cases above we can qualify f with a file name. The general format of program reference is

        {modifier-char file $ name} 
    where modifier is a single key '*', '+', or '-'. File is a key name which refers to a file, as defined in a program-source form. name is the name of a definition in a Scheme file.

  • The notation {file$}, which is a special case of the item from above, creates a link a program file. File is a key name which refers to a file, as defined in a program-source form.

  • The notation [d] creates a link to another documentation section or entry; d is the id if the section/entry. This corresponds to (doc-ref 'name "f").

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.

Command Key binding Effect
make-elucidator none Make the directory structure of a new elucidator and establish a setup file based on information retrieved via prompting. Also make a template of the documentation file. As the first thing you should call elucidate on the setup buffer. This will cause the rest of the files to be created, including the necessary gif icons. Finally you should use setup-elucidator to make all the elucidator editor buffers, and to prepare for the programming and documentation process.
setup-elucidator none Set up the elucidator on an existing laml setup file, which must be an laml file. If f.laml is selected, a textual documentation is assumed to in file f.txt. If LAML style documentation is used, the documentation file is identical with the LAML setup file.
refresh-elucidator C-c C-e r Refresh the program knowledge established by the LAML processing part of the elucidator. This affect the cross referencing capabilities of the editor part, and it (re)defines the source files on which the elucidator works. The information is taken from the internal directory.
reset-elucidator C-c C-e C-r Reestablish a situation where the documentation and program is shown in a two window configuration, the documentation above the program
goto C-c C-e g
C-c C-e C-h
A generic navigation command which can be used inside the textual documentation format or the LAML documentation format. If used on a defined name in a Scheme source program (in the head of a Scheme define form) go to the place this definition is documented. If used on an applied name go to the definition of the name.
back C-c C-e C-b Reverse the effect of the previous goto
prog-ref C-c C-e C-p Insert a program reference (in curly brackets) in the documentation. Can be used from a program buffer or from within the documentation. If necessary, use completion for entering of a program identification
doc-ref C-c C-e C-d Insert a documentation reference in the documentation. Uses completion for entering of a documentation identification
show-setup C-c C-e C-u Show the setup LAML file. If laml documentation is used, this is the same file as the documentation file.
show-program C-c C-e p Show a program. You are prompted for one of the programs in the documentation bundle
elucidate C-c C-e C-o Run the elucidator on the setup file of the current documentation bundle. This command can be activated from an arbitrary buffer in the documentation bundle
save-elucidator-buffers none Saves all the buffers in the documentation bundle
quit-elucidator none Save elucidator buffers and kill them all. Reset the state of elucidator.
elucidator-help C-c C-e ? Shows brief elucidator help information in Emacs

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:

Command Key binding Effect
insert-documentation-section C-c C-e C-x Insert a documentation section using the textual format
insert-documentation-entry C-c C-e C-c Insert a documentation entry using the textual format

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 Information Appendix.
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


Generated: Monday, November 14, 2011, 09:15:06
Generated by LAML SchemeDoc using LAML Version 38.0 (November 14, 2011, full)