The Elucidative Programming Home PageMay 2014: Most links on this pages have been updated to accommodate a recent reorganization of our web server. Recent developments (December 2004): The Scheme Elucidator 2 is a major revision of the original Scheme Elucidator.
The Scheme Elucidator 2 is based on an XML-in-LAML format for setup and for the textual documentation.
(The original textual documentation language is still supported). Most recently, we have added version support
to the Scheme Elucidator 2. With this, the Scheme Elucidator can handle multiple versions of the same source file.
Our primary focus will be to document the evolution of a program, instead just the most recent version. The large example
referred above involves more than one version of the Scheme Elucidator. However, start with this small demo. Elucidative programming is a variant of literate programming, as coined by Knuth in the early eighties. In most current 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: - The program source files are not affected at all.It is not necessary (nor possible) to split the programs into fragments,
and to organize these in the context of the program explanations.
An existing program source file can be documented.
- 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.
- 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.
- We support on-line presentation in a browser.Literate programming tools were primary oriented towards presentation of the weaved results on paper.
Elucidative programming tools produce HTML pages instead which can be presented in an Internet browser.
- 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 and Java.
We plan to support elucidative programming in other languages in the future.
- Program and documentation indexes are available.A tables of contents, an index of the program definitions, and a cross reference index are available.
- The creation of the format, from which the elucidated information is generated,
is supported by a special set of editor commands in Emacs.The editor commands support the same kinds of navigations as the browser.
Several other editing operations are also very helpful.
Using these commands, 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 a 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 LAML Scheme file (see below), which describes 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 following resources on elucidative programming are available: - Papers (oldest first)
- Requirements for an Elucidative Programming Environment
(pdf, zipped postscript file, slides )
Presented at the International Workshop on Program Comprehension - IWPC'2000
June 2000, Limerick, Ireland. - An Elucidative Programming Environment for Scheme
(pdf, postscript file, slides )
Presented at Nordic Workshop on Programming Environment Research -NWPER'2000
May 2000, Lillehammer, Norway. - Elucidative Programming in Java
(pdf, postscript file, slides )
Presented at the eighteenth annual international conference on Computer documentation - IPCC/SIGDOC, September 2000 in Boston, USA. - Elucidative Programming
(pdf )
A later version of "An Elucidative Programming Environment for Scheme" with less Scheme details and
a balanced treatment of Scheme and Java.
Nordic Journal of Computing volume 7, number 2, page 87-105, Summer 2000. - Introducing Elucidative Programming in Student Projects
Coauthored with Thomas Vestdam (pdf, examples). Currently not published. - Aspects of Internal Program Documentation - An Elucidative Perspective
Coauthored with Thomas Vestdam (pdf).
June 2002. Presented at the 10th International Workshop on Program Comprehension - IWCP'2002. - Scheme Program Documentation Tools (pdf)
Published in the Proceedings of the Fifth SIGPLAN ACM Workshop on Scheme and Functional Programming.
This paper covers both the LAML SchemeDoc tool and the Scheme Elucidator 2 tool. - Maintaining Program Understanding - issues, tools, and future directions
Coauthored with Thomas Vestdam (pdf).
August 2004. Presented at the 11th Nordic Workshop on Programming and Software Development Tools and Techniques - NWPER'2004.
A revised version of this paper will also appear in Nordic Journal of Computing. - Towards Documentation of Program Evolution (pdf)
Coauthored with Thomas Vestdam. In Proceedings of the 21st International Conference on Software Maintenance, September 2005.
- Slides
- Examples of elucidative programs in Scheme
The Scheme Elucidator is part of the LAML software package. If you download this package you also get the Scheme Elucidator. The Elucidator Installation page contains a brief installation guide
An elucidator exists for Java. The Java Elucidator was origianlly developed by
Max Rydahl Andersen and Claus Nyhus Christensen and Vathanan Kumar and Søren Staun-Pedersen and Kristian Lykkegaard Sørensen.
Until recently, Thomas Vestdam was the maintainer of the Java Elucidator.
The Java eludicator follows the same principles as the Scheme elucidator, but
is technically more advanced than the Scheme elucidator. Kurt Nørmark
Aalborg University
normark@cs.aau.dk
http://people.cs.aau.dk/~normark/ |