Download Elucidative Programming

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 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
Elucidative Programming
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
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
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
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 Java Elucidator
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
 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 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
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
 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