The elucidative programming home page and the DOPU page are the primary places to find information about elucidative programming.
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:
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:
| Icon | Explanation |
| 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 or in the case that variable
default-program-font-size is set to large)
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/