1. Elucidative Programming Kurt Nørmark Aalborg University Denmark SIGDOC September 2000

2. 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

3. 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

4. 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

5. 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

6. The meaning of the word To elucidate is – "to make clear or plain, especially by explanation" – "to throw light on something complex"

8. 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

9. 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)

10. The edoc source format Year To calculate which year a given UT time occur in the <slink role="describes" href="@calcYear(long)">calcYear(long) method uses successive counting. It starts out with the <slink role="describes" href="@BASE_YEAR">base year and succesivly adds the number of seconds for the year in the loop until it ends up with less seconds than the next year contains. The length of a given year is returned by the method <slink role="describes" href="@yearLength(long)">yearLength(long), which check if the year is a leap year and returns the correct amount of seconds.

11. 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

12. 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

13. 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

14. 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

15. The design of the Java Elucidator

16. 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

17. 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

18. 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

19. 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