The Elucidator Help Page

The pages shown in this browser is the result of 'elucidating' a number of programs and a documentation file. The main purpose is to present internal program documentation side by side with a number of source programs. The leftmost window shows the documentation, and the rightmost window one of the programs. The topmost window is a menu and index window, from which a number of aspects can be controlled.

Elucidative programming is variant of literate programming , as coined by Knuth in the early eighties. In most literate programming tools (called WEB tools), fragments of programs are defined inside the program documentation. In literate programming, a tool (called tangle) can extract and assemble the program fragments according to the rules of the programming language. Another tool (called weave) formats the documentation, generates indexes, and presents all of it in a nice-looking paper format.

The main characteristics of elucidative programming in relation to literate programming are:

  1. The program source files are not affected at all.
    It is not necessary to split the programs into fragments, and to organize these in the context of the program explanations. An existing program source file can be handled.
  2. The program and the documentation are shown side by side.
    We do not go for an embedded presentation of the program inside its documentation. Rather, we provide for mutual navigation between program and documentation in a two-frame layout
  3. The program units which we document, are whole abstractions.
    Things get simpler when we can settle on documentation of named abstractions instead of arbitrary program fragments (sometimes called 'chunks' or 'scraps')
  4. We support on-line presentation in a browser.
    Literate programming tools were primary oriented towards presentation of the weaved results on a static paper medium.
  5. The elucidator tool use specific knowledge about the programming language.
    The language knowledge is used to identify the names in the program. Applied names are related to their definitions, and the program is decorated with colors and extensive linking. Currently we support the programming language Scheme. We wish to support elucidative programming in other languages in the future.
  6. Program and documentation indexes are available.
    A tables of contents, an index of the program definitions, and a cross reference index is available
  7. The creation of the format, from which the elucidated information is generated, is supported by a special set of editor commands.
    In that way it is realistic to handle the practical aspect of documenting a program while it is written

A documentation bundle consist of a single documentation file, a number of program files, and a setup file. The documentation file is described in very simple, textual format, which allows the use of HTML tags for formatting. As mentioned above, there are no special requirements to the program files. The setup files is a Scheme file, which describes the the constituents of the documentation bundle together with a number of processing parameters. Running the setup file through a Scheme processor generates the HTML pages shown in this browser.

The icons in the menu and index frame (at the top) are now described:

IconExplanation
Reset the elucidator to vertical layout (the default layout). All frames are reverted to the 'start position'.
Reset the elucidator to a horizontal layout. This is an alternative layout in which the documentation and a selected program are shown under each other, in full width
Presents an index of all defined names in the menu and index frame, just below the icons at the top of the window. The index is pr. default broken into fragments according to starting letter of the defined name.
Presents a cross reference index in the menu and index frame. A cross reference index relates all applied names to the definition, in which they occur. The index is pr. default broken into fragments according to starting letter of the applied name.
Present an index of all named defined more than once in the documentation bundle. This is useful information in a Lisp program
Present an overall table of contents for the documentation in the menu and index frame. This table of contents only covers the top-level section, but no subsections.
Present a table of contents for the documentation in the menu and index frame. This table of contents convers both top-level sections and subsections (also called entries).
Present an Elucidator help page in the documentation frame to the left
Present an Elucidator help page in the program frame to the right

The icons in the rightmost group allows navigation to each of the program files in a documentation bundle.

From the documentation frame (to the left) it is possible to adjust the program window, such that a given piece of program is shown. Similarly, from the program frame (to the right), the yellow left arrows can be used to find the section in the documentation, which explains the particular program unit. The light yellow arrows refer to a documentation section which mentions the definition (as opposed to explaining it). We talk about strong and weak relations between the documentation and the program resp. Besides these means of navigation it is possible to navigate inside the documentation frame, and inside the program frames.

Inside the program and inside documentation sections you may find small color bullets like . These are called source markers. The source markers are used to point out a particular place in a piece of program, which is discussed in a documentation section. You can click on a source marker in the documentation in order to navigate to the corresponding source marker in the program. Also navigation in the opposite direction is supported from most source markers. The popup text, which appears in most browsers when the cursor rests on a source marker, gives useful additional information about the source marker. Notice that a source marker in the documentation is associated with the closest preceding strong documentation-program relation.

The source programs are, by default, shown using a fairly small font size. The small square symbols can be used to toggle the program frames to use larger font. Notice that the small square symbol is only shown in certain configurations (when the variable make-large-source-files? is true)

The icon is an anchor of a link from a definition to an entry in the cross reference index. This link is very convenient because it allows us to follow call chains via the cross reference index: Go from a definition of N to the cross reference entry N. Find via that entry a function F which calls N; Go the cross reference entry of F, and find a function G which calls F, etc.

The elucidator is written in Scheme, using the LAML software packages.

You can use the browser's back button to establish the original contents of this frame, or you can activate the reset elucidator icon in the top left corner to return to the standard layout.

Kurt NÝrmark
Aalborg University
normark@cs.auc.dk
http://www.cs.auc.dk/~normark/