Generated: July 2, 2004, 09:28:18

Copyright ©2004, Kurt Nørmark

Reference manual of the Scheme Elucidator

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

Source file: styles/elucidator/elucidator.scm
LAML Version 24.00 (December, 2003, development)

This is the documentation of the original Scheme Elucidator, which now is obsolete. Please consult the Reference Manual of the Scheme Elucidator 2. The Scheme Elucidator is a program development tool which produces internal documentation of a Scheme program. The Scheme Elucidator is part of the LAML software package, and it is available from the LAML home page. Internal documentation is seen as a contrast to interface documentation, which can be made by means of SchemeDoc. The produced documentation consist of a number of HTML files, to be shown in an Internet browser. The sources of the produced documentation is a number of scheme program files, a documentation file in a simple text format, and an LAML setup file. The the root of the resulting HTML files is located in the same directory as the documentation and the setup file. The documentation is produced when the LAML file is processed. Taken together these files form a so-called documentation bundle. An elucidator is a kind of a literate programming tool, which connects the documentation and the program by means of links instead of physically embedding the program fragments in the documentation. To emphasize this difference, we talk about elucidative programming instead of literate programming. The Scheme elucidator produces web documentation. There is also editor support of producing the documentation. Currently we support elucidative Scheme programming via the Emacs text editor. Below we will also summarize the editor commands which we use in Emacs for elucidative programming. There exists (incomplete) internal documentation of the Scheme Elucidator (on the www.cs.aau.dk site) in terms of an elucidative program. There is also a brief user guide, which describes how to navigate the Elucidator in a WWW browser. Please also take a look of the examples, in particular the example called 'Small Meta Demo', which in simple way illustrates all the different facilities in the Scheme elucidator. The LAML tutorial is written as a set of elucidative programs, and as such it also makes up a good example. If you are a new user of the Elucidator start reading the section 'Practical Introduction' below the table.

Table of Contents:

1. Practical Introduction 4. Lisp level documentation functions 7. The program files 2. Forms in the setup file 5. The textual documentation file 8. An example of a complete documentation file 3. Secondary setup 6. The setup file 9. Elucidator editor support using Emacs

Alphabetic index:

alphabetic-cross-reference-index? alphabetic-cross-reference-index? A boolean variale controlling whether to split the cross reference index in alphabetic files. alphabetic-defined-name-index? alphabetic-defined-name-index? A boolean variale controlling whether to split the defined name index in alphabetic files. begin-documentation (begin-documentation) Starts the section of the documentation in which documentation-entry and documentation-section forms may appear. body (body b) Defines the body of a documentation-entry. browser-pixel-width browser-pixel-width A variable defining the width of the browser in pixels control-frame-pixel-height control-frame-pixel-height The pixel height of the (top level) control frame copy-image-files? copy-image-files? A variable which controls whether to copy image icons from the software directory to the source (documentation) directory. d-link-prefix-char d-link-prefix-char A variable defining the documentation link prefix character. d-link-suffix-char d-link-suffix-char A variable defining the documentation link prefix character. default-program-font-size default-program-font-size Set the default font size of the programs presented in this elucidator. default-program-link default-program-link A variable that determines the default kind of linking from documentation to program. default-table-of-content default-table-of-content Set the default table of contents of this elucidator. documentation-entry (documentation-entry . elements) Define the elements of a documentation entry. documentation-from (documentation-from documentation-file) Parses and extracts documentation from a separate, textual format which we define in a subsequent section of this manual. documentation-intro (documentation-intro title author email affiliation abstract) Define the documentation introduction in terms of a title, author, email, affiliation, and abstract documentation-section (documentation-section . elements) Define the elements of a documentation section. elucidator-color-scheme elucidator-color-scheme An association list that maps group strings to colors. elucidator-home-url elucidator-home-url Define the home URL of the elucidator. elucidator-marker-char elucidator-marker-char A char valued variable which defines the character used as source marker char. elucidator-verbose-mode elucidator-verbose-mode A variable controling the amount of output written while eludicating a documentation bundle. end-documentation (end-documentation) Ends the section of the documentation which contains documentation-entry and documentation-section forms end-file-empty-lines end-file-empty-lines The number of empty lines in the bottom of an html file, Allow navigation to bottom stuf. file-location (file-location path) Sets the file location of a program source to be path group (group group-name) Defines the group to which a source file belongs. id (id id-symbol) Defines the identification of a documentation-entry or documentation-section intro (intro i) Defines the introductory text of a documentation-entry. key (key key-val) Sets the key to key-val. language (language lang) Defines the programming language used in a program source link-definitions-to-cross-reference-index? link-definitions-to-cross-reference-index? A boolean variable which controls whether to link from program definitions to the corresponding entry in the cross reference index. make-all-indexes (make-all-indexes) Ask for generation of both duplicate name index, cross reference index, and defining name index make-large-source-files? make-large-source-files? A boolean variable which controls the generation of a source file with large fonts. make-no-indexes (make-no-indexes) Ask for generation of no indexes manual-frame-from-documentation manual-frame-from-documentation A variable that determines the name of the browser frame used when we address manual entries from the documentation. manual-frame-from-program manual-frame-from-program A variable that determines the name of the browser frame used when we address manual entries from the program. manual-source (manual-source . elements) Declare a LAML manual file to be part of the documentation. maximum-processing (maximum-processing) Ask for maximum processing of the documentation bundle. minimum-processing (minimum-processing) Ask for minimum processing of the documentation bundle. p-link-prefix-char p-link-prefix-char A variable defining the program link prefix character. p-link-suffix-char p-link-suffix-char A variable defining the program link suffix character. present-hidden-ids? present-hidden-ids? Controls whether to present the identification of sections and entries, hidden using the background color. process-only (process-only . source-keys) Controls which of the sources files to process. program-source (program-source . elements) Define a program source file to be part of this documentation bundle. rs4r-url-prefix rs4r-url-prefix Define the URL prefix to the LAML distribution directory that contains the 'Scheme knowledge'. set-documentation-name (set-documentation-name name) Define the name of the documentation. set-source-directory (set-source-directory dir) Defines the source directory to be dir. source-marker-kind source-marker-kind A variable which deterimens the 'style' of source markers on the documentation page. title (title t) Defines the title of a documentation-entry or documentation-section url-location (url-location path) Sets the url address of a manual-source to be path

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 fresh elucidator. Follow the direction given from this command. From Emacs type C-e ? 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 (or C-e C-o) on an elucidator buffer activates the Elucidator from Emacs. The Elucidator is the tool which produces the WWW pages which presents the documentation bundle in an Internet browser. 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.

When you read the Elucidator WWW pages navigate to the Help page via one of the 'Question Mark Icons' to get help on the possibilities offered by the Elucidator tool.

2.   FORMS IN THE SETUP FILE
The setup file must be a file with laml file extension. This is the file which connects all the files in a documentation bundle. In this section we will describe the important and primary functions and forms, which may be found in the setup file. In the next section we document a number of less important forms. We start with the most important setup forms

3.   SECONDARY SETUP
In this section we document a number of less important setup possibilities.

4.   LISP LEVEL DOCUMENTATION FUNCTIONS
The functions in this section document the Lisp level documentation-entry and documentation-section functions. Normally, these functions are not used. Instead we rely on the simple, textual (and non-Lisp) format of documentation found in a separate file. However, it is perfectly possible to avoid the separate documentation file, and to use the two functions below (and their constituent forms). In fact, the format of the separate, textual documentation file is parsed and transformed to calls of documentation-entry and documentation-section

5.   THE TEXTUAL DOCUMENTATION FILE
Here we describe the format of the textual and separate documentation format. The textual format is inserted into the documentation by means of the function documentation-from . If the textual documentation form is used, the functions defined in the previous sections are typically not used. However, it is perfectly possible to use the textual format (and documentation-from) side by side with documentation-entry and documentation-section forms . Such a mixed style may be attractive for people who want to take advantage of LAML expressions instead of HTML expressions, which can be used in the textual documentation format.

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. Here we just mention f without explaining it.
• Using {*f} creates a strong link at a place, where f is explained.
• Using {-f} creates a typographical emphasis of f, but no linking
• 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 [d] creates a link to another documentation section or entry; d is the id if the section/entry.

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

6.   THE SETUP FILE
Here follows an example of a complete setup file. The example is taken from the from the LAML example directory:

; The elucidator laml setup file ; Change the capital names ; Load the styles file, hereby defining style function (load (string-append laml-dir "laml.scm")) (laml-style "xml-in-laml/elucidator/elucidator") ; Set the directory in which this file resides. ; The directory ends in a '/' (set-source-directory (startup-directory)) ; Set the name of this file, without extension (set-documentation-name "meta-demo") ; Set the level of processing. With commenting, process all source files. ; (process-only) ; (make-no-indexes) (make-all-indexes) (define make-large-source-files? #t) ; (define toc-columns-detail 1) ; (define present-hidden-ids? #t) ; (define underline-program-links #f) ; (define underline-documentation-links #f) ; (define show-sectional-comment-name #f) ; The RELATIVE (back) path to the r4rs directory, which is located in the root of the LAML distribution. (define rs4r-url-prefix "../../../../r4rs/") ; Do you want an menu like selection of programs? (define separate-program-menu? #t) (define elucidator-color-scheme (make-color-scheme "meta" program-background-color-1 "other" program-background-color-2 )) (define (laml-source-file f) (string-append software-base-directory f)) ; Define the sourcefiles in this documentation bundle (program-source (key "meta-demo") (file-location (laml-source-file "examples/elucidator/meta-demo/meta-demo.scm")) (language "scheme") (group "meta") ) (program-source (key "other-source") (file-location (laml-source-file "examples/elucidator/meta-demo/other-source.scm")) (language "scheme") (group "other") ) ; Define the documentation body, here in terms of a documentation-from clause (begin-documentation) (documentation-from "meta-demo.txt") ; the name of the file can be changed (end-documentation)

7.   THE PROGRAM FILES
The program files are normal Scheme files. There are only a few things to observe:

• There should be no comments in between let, let*, lecrec and the name bindings.
• There should be no comments in between define and the name (or form) being defined

In addition the rules about the use of source marker in the scheme program should be observed:

• Source markers are found in Scheme comments. A source marker is implicitly related to the enclosing, top-level definition.
• A source marker is of the form @x, where x is a single character in the interval ['a'..'o'].
• A source marker in a program comment must be followed by a blank character (space, CR, or a similar character).
• A comment which is started with ::sectional-comment-id:: (a name in double colon) names the subsequent Scheme form(s). Such a comment is called a sectional comment.

8.   AN EXAMPLE OF A COMPLETE DOCUMENTATION FILE
In this section we show an example of complete documentation file. The example is taken from the meta demo example in the elucidator example directory.

.TITLE A simple meta demonstration of the Scheme Elucidator .AUTHOR Kurt Nørmark .EMAIL normark@cs.aau.dk .AFFILIATION Department of Computer Science, Aalborg University, Denmark .ABSTRACT This elucidative program demonstrates the facilities of the Scheme Elucidator. The program fragments are just simple and well known functions without any coherence or real value. .END ----------------------------------------------------------------------------- .SECTION first-section .TITLE A section .BODY This is section one. Here we can give overview of the subsequent subsections, which we happen to call entries. .END ----------------------------------------------------------------------------- .ENTRY first-entry .TITLE An introductory entry .BODY Here in the first subsection we can introduce the matters. Typically we do not make very many references to program pieces from the first section. A documentation bundle is the set of Scheme files, the textual documentation file, and the LAML setup file. <p> We have made the documentation bundle by means of the emacs command M-x make-elucidator. This command creates the documentation file, the first program file, and the setup file. It also creates the necessary and underlying file and directory structures. When we execute this editor command we are asked to process the LAML file, and to activate another emacs command setup-elucidator. We just do that. .END -------------------------------------------------------------------------------- .ENTRY second-entry .TITLE The next entry .BODY I made this entry via the Emacs command M-x insert-documentation-entry. <p> In this entry we can start discussing the Scheme program. Just to have something on the program side, we have made the well-known {-fak} function in meta-demo. So we make a reference to it. If we have lost the editor context we can always say C-e C-r (or M-x elucidator-reset-elucidator) to establish the characteristic split view editor panes with documentation in the top window and program in the bottom window.<p> Now let us discuss {*meta-demo$fak}. The reference just inserted is conveniently made by selecting the fak header in the Scheme file and entering C-e C-p (elucidator-program-ref). It turns out that this makes a full qualified reference (file and name). The reason is that the editor - at this point in time - does not known any thing about {-fak}. If the documentation bundle had been processed (abstracted) we would have this knowledge. We may change this policy in the future.<p> We now process the documentation bundle by C-e C-o (or M-x elucidator-elucidate). .END -------------------------------------------------------------------------------- .ENTRY third-entry .TITLE The next steps .BODY We now program additional functions in both {meta-demo$} and in {other-source$}. This - by the way - illustrates links to whole program files.<p> The functions in meta-demo are {*list-prefix} and its helping function {+list-prefix-1}. Notice first the strong reference (red) and the weak reference (blue). We may also just make typographic emphasis, like {-list-prefix-1} (C-e C-w). <p> The functions in {+other-source$} are {*other-source$pair-up} and its helping function {+other-source$pair-up-1}.<p> At the bottom of {*other-source$} we see a definitions of {+other-source$key-list} and {+other-source$val-list}. Following these definitions we see {+other-source$aref-assignment}, which in a rather informal way denotes a section of the program via use of a so-called <em>sectional comment</em> in {+other-source$}. .END -------------------------------------------------------------------------------- .ENTRY details .TITLE Discussing details .BODY Let us demonstrate the use of source markers in {*fak}. At @a we test if the parameter is zero. If it is we return the base value 1 (@b). If not we return n times (fak (- n 1)) (@c); This illustrates the recursion in {+fak}. .END -------------------------------------------------------------------------------- .ENTRY the-end .TITLE The End .BODY This ends our simple demonstration of the Scheme elucidator. .END

9.   ELUCIDATOR EDITOR SUPPORT USING EMACS
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, and to help author a documentation bundle in a a safe and convenient way. We support a splitted frame, 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 defines the Elucidator tool).

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, the textual documentation is assumed to in file f.txt. Both files are brought up in editor buffers.
refresh-elucidator	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-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-e g C-e C-h	A generic navigation command which can be used inside the textual documentation format. If used inside curly bracket navigate to a program unit. If used in brackets navigate to another documentation unit. If used on a defined name 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-e C-b	Reverse the effect of the previous goto
prog-ref	C-e C-p	Insert a program reference (in curly brackets) in the documentation. Uses completion for entering of a program identification
doc-ref	C-e C-d	Insert a documentation reference (in brackets) in the documentation. Uses completion for entering of a documentation identification
surround-prog-ref	C-e C-q	Surround an identifier with curly brackets in order to make a relation from a place in the documentation to a program unit. This function is an alternative to prog-ref, in situations where there is an existing program unit name in the documentation
show-setup	C-e C-u	Show the setup LAML file
show-program	C-e p	Show a program. You are prompted for one of the programs in the documentation bundle
elucidate	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-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-intro	none	Insert a documentation intro using the textual format
insert-documentation-section	C-e C-x	Insert a documentation section using the textual format
insert-documentation-entry	C-e C-c	Insert a documentation entry using the textual format
insert-lispstyle-documentation-section	none	Insert a documentation section using the LAML format
insert-lispstyle-documentation-entry	none	Insert a documentation entry using the LAML format

Any command described above is activated by M-x command (i.e., Esc X command) or via the keyboard bindings. Notice that the prefix of the elucidator keyboard bindings is C-e. Usually C-e runs the command end-of-line. This commands has been moved to C-e C-e when the elucidator is loaded into Emacs.