The Scheme Elucidator 2 Reference Manual

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.

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.

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.