Kurt Nørmark ©
Department of Computer Science
Aalborg University
Denmark

Abstract Index References Contents

Theses slides are intended for the IPCC/SIGDOC 2000 conference in Boston, Massachusetts. The conference took place September 24-27, 2000.

Plan of the SIGDOC talk Slide Note Contents Index References

On this page we outline the plan of the SIGDOC talk, which includes selected pages from this collection of material

Background Briefly about literate programming Characteristics of Elucidative Programming An example of an elucidative Java program Model and concepts The elucidative tools Tool philosophy and tool integration Perspectives and concluding remarks

In order to be concrete we briefly present an example of a literate program and the source from which it is generated

References A literate Life Program in Pascal - NuWeb - in Danish An example of the literate program source program (section 5) - in Danish

Literate Programming and the WEB System Slide Note Contents Index References

Here we will briefly describe an important background and inspiration, namely Knuth's ideas of literate programming.

Knuth invented literate programming in order to explain and publish his programs in articles and books

Characteristics of literate programming: A program is structured according to its explanation The distance between the documentation and the program is small Physical proximity The pieces of program 'live in' the documentation The opposite approach of conventional program commenting

Literate programming is typically supported by tools in the WEB-family

Problems with WEB-like literate programming Slide Note Contents Index References

Elucidative programming is meant to be an alternative to WEB-like literate programming. Therefore it is natural to identify a number of problems with classical literate programming which we attempt to remedy in our variation of literate programming.

The Program is embedded in the documentation Only few programmers want to split their programs in fragments and to organize these as parts of the documentation Language mixing The mix of three languages in a single document is not attractive Documentation language, programming language, WEB interconnection language Reading and comprehension problems in the WEB-source files Extra level in error handling Error handling is more complicated because the errors need to be mirrored in the WEB source program Reasonable solutions exist Paper orientation Most existing tools are oriented towards printed paper presentation of the literate program

Despite these problems the original ideas and tools remain to be very interesting and attractive for skilled and motivated users

To elucidate is

"to make clear or plain, especially by explanation"

"to throw light on something complex"

Elucidative Programming Slide Note Contents Index References

At this place we introduce elucidative programming. We here describe a number of key properties of the documentation approach.

Elucidative programming is meant to remedy some of the identified problems with literate programming

Elucidative programming highlights: User interface Present the program and the documentation side-by-side in an Internet browser Leave the program "in peace" Does not impose any requirement on the organization of the program in files or directories Address existing abstractions from the documentation Does not rely on separately named program fragments Supported by the development environment Requires specialized editor functionality We will return to all of these items later in the presentation

An example of an elucidative program Slide Note Contents Index References

In order to be concrete we will here give an example of an elucidative program. This program is akin to the program which is discussed in the SIGDOC paper

The example illustrates the development of a small program that converts a large integer, representing the number of seconds elapsed since January 1, 1970 to a conventional date and time structure

References The Time Conversion example (Java - Only in Netscape) The Time Conversion example (Scheme) An everyday example: The annotator tool (Scheme)

Strong and weak points Slide Note Contents Index References

We see both strong and weak points in the elucidative approach

Strong points The possibility to explain transverse themes, such as design patterns The use of navigational proximity instead of physical proximity Weak points Difficult to maintain an elucidative program Reading in a browser - writing in the development environment

The elucidative programming model Slide Note Contents Index References

This page describes a number of important concepts behind the elucidative programming model.

Entities Named abstractions on the program side Sections and subsections on the documentation side A naming scheme that allows us to address the program entities from the documentation Relations A doc-prog relation which connects explanations with program entities. A prog-prog relation which connects applied and defined name occurrences A doc-doc relation which connects explanations across the hierarchical documentation structure Source markers Represent positions in a program which we want to address in the explanations Documentation bundle An aggregation of programs, documentation texts, and additional properties (e.g., processing options)

The source format of the documentation Slide Note Contents Index References

When the programmer works with a literate program the source format of the documentation is of particular interest. This format is important because it constitute the words and lines actually written by the programmer. In addition, the programmer will spend much time reading parts of the documentation in this format. Therefore the properties of the format matters. This page is related to the Scheme elucidator only.

An XML markup language is used for the overall structure, the relations, and the source markers HTML is used for additional markup purposes

Reference An excerpt of the time conversion documentation source

Tool Overview Slide Note Contents Index References

There are three important tools in an elucidative programming environment. Of these, a standard Internet browser counts for one. The others are the editor used for programming and documentation, and the tool which produces the underlying browser format.

Our elucidative programming environment contains the following tools: An elucidator which converts programs and documentation to HTML pages An editor which is used for both programming and documentation purposes A internet browser which is used for presentation of the elucidative program

The elucidator plays the role of the literate programming weave tool In elucidative programming there is no need for a tangle tool

The editor tool Slide Note Contents Index References

The editor tool for the elucidator plays a major practical role. It is important that the programmer can continue working in his favorite environment. We will assume that our programmers use Emacs. Therefore we chose be augment the Emacs text editor with elucidator support.

It is of major importance to provide for easy and flexible editor support of elucidative programming We have augmented Emacs with elucidative facilities

Design objectives: The editor applies a split-screen layout in the same way as the browser The editor's support of the programming language is available in non-changed form The creation of the doc-prog and doc-doc relations is nursed in particular The major navigation possibilities - as supported by the browser - are also present in the editor Emacs keeps the documentation bundle together by a special marking of the buffers involved

The elucidator tool Slide Note Contents Index References

The elucidator tool produces the HTML pages to be shown in a browser. In addition, the elucidator tool makes a number of data structures used by the editor to gain knowledge about the documentation bundle.

The elucidator is the tool that processes a documentation bundle in order to produce an elucidative program

Tasks of an elucidator Abstraction Parses the documentation and the program Extracts knowledge about program and documentation entities Synthesis Generates the HTML pages with links that represent the three kinds of relations between entities

The synthesis part of the processing may be carried out by the WWW server on a dynamic basis

The Java Elucidator Slide Note Contents Index References

The Java Elucidator has been developed by five master students The first version is similar to the Scheme elucidator at the conceptual level The second version supports a more structured documentation approach

Observations about the Java elucidator: The naming scheme used to address program units from the documentation is rather complex It involves a lot of details to make a doc-prog link Relies on an abstraction process which populates a relational database with program and documentation information The synthesis task is done dynamically by the WWW server It is also possible to generate a static set of HTML pages

The Design of the Java Elucidator Slide Note Contents Index References

On this page we will illustrate the overall design of the Java Elucidator.

Figure. The design of the Java Elucidator

Tool Integration Slide Note Contents Index References

Tool integration is a key issue when two or more program development tools are used together. On this page we discuss integration issues of the tools in an elucidative programming environment.

The current integration of the editor and the elucidator is simple and rather primitive

Cooperation between the elucidator and the editor The elucidator abstracts information from the documentation bundle which the editor can read on demand The editor is always a step behind with respect to knowledge about the current documentation bundle The elucidator can be activated very smoothly from the editor

Mutual activation of the browser from the editor - and vise versa - would be a major practical improvement

Tool philosophy Slide Note Contents Index References

Here we will discuss possible and different tool organizations. We call it 'tool philosophy'. Our point is not to force the programmer into a specialized environment for authoring of program documentation. We go for documentation enabling of existing environments. In our experience, programmers are rather conservative, and most of them want to continue working in their favorite environments. There must be major advantages in a new environment in order for the programmers to shift.

Possible tool organizations: Provide a brand new tool with an embedded editing environment for elucidative programming Like Sametinger's Dogma System Introduce a separate processing tool and augment an existing editor with knowledge about elucidative programming Typically a Unix and Emacs solution Include elucidative aspects into current integrated programming environments Long term goal - requires industrial collaboration

Programmers do not want to be forced into a new and specialized editing environment

A broader perspective on the use of an elucidator Slide Note Contents Index References

Here we will list a number of potential areas which we expect can be supported by the elucidator.

Most documents that need to address program units or program details will be able to benefit from the ideas of elucidative programming

Documents with 'an elucidative potential': Diaries and logs Written code reviews and code walk throughs Program tutorials Design documents Maintenance documentation

Status and Conclusions Slide Note Contents Index References

We conclude this presentation with some brief accounts on the status of our work.

Contributions: A renewal of the tool ideas for literate programming A serious attempt to present programs and their internal understanding on the Internet Status A prototype of an elucidative Scheme environment exists Two different versions of elucidative Java prototype environments exists Version 1 supports a single essay node with explanations Version 2 supports a much richer structuring of the explanations

In the fall we will get both educational and industrial experience with version 2 of the Java environment

Elucidative Programming
Course home     Author home     About producing this web     Previous lecture (top)     Next lecture (top)     Previous lecture (bund)     Next lecture (bund)     
Generated: October 8, 2000, 14:04:51