Post on 05-Jan-2016
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