Elucidative Programming

Kurt Nørmark

Aalborg University

Denmark

SIGDOC September 2000

Plan for this talk 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

Literate programming

Characteristics of literate programming:

Detachment of program explanation structure from program structure

The proximity between program fragments and their explanations

The pieces of program 'live in' the documentation

The opposite approach of conventional program commenting

Problems with 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 mixingThe 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 handlingError handling is more complicated because the errors need to be mirrored in the WEB source program

Reasonable solutions exist

Paper orientationMost existing tools are oriented towards printed paper presentation of the literate program

Elucidative 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

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

The meaning of the word

To elucidate is

– "to make clear or plain, especially by explanation"

– "to throw light on something complex"

Strong and weak points Strong points

The possibility to explain transverse themes, such as design patterns

The use of navigational proximity instead of physical proximity

Weak point

Difficult to maintain an elucidative program

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 edoc source format<section label="year"> <title>Year</title> To calculate which year a given UT time occur in the <slink role="describes" href="@calcYear(long)">calcYear(long)</slink> method uses successive counting.<br/><br/> It starts out with the <slink role="describes" href="@BASE_YEAR">base year</slink> and <slink role="mentions"

href="@calcYear(long)@e:b"> succesivly adds</slink> the number of seconds for the year in the loop

until it ends up with <slink role="mentions" href="@calcYear(long)@e:a">less

seconds</slink> than the next year contains.<br/><br/>

The length of a given year is returned by the method <slink role="describes" href="@yearLength(long)">yearLength(long)</slink>, which check if the year is a <dlink role="mentions"

href="/Time.edoc@leapyear">leap year</dlink> and returns the correct amount of seconds.</section>

Tool overview 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 browser which is used for presentation of the elucidative program

The Editor tool

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

We have augmented Emacs with elucidative facilities

The elucidator tool

• 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 elucidator is the tool that processes a documentation bundle in order to produce an elucidative program

The Java Elucidator

Observations about the Java elucidator:

The naming scheme used to address program units from the documentation is rather complex

Much more elaborate 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 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

The design of the Java Elucidator

Tool integration

• 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

Tool Philosophy

• Possible tool organizations:

Provide a brand new tool with an embedded editing environment for elucidative programming

Like Sametinger's Dogma System

Introduce a separate 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

A broader perspective on the use of an elucidator

• Documents with 'an elucidative potential':

Diaries and logs

Written code reviews and code walk throughs

Program tutorials

Design documents

Maintenance documentation

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

Status and conclusions 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