Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts <nick.roberts@acm.org>]

Time for the latest hairbrained scheme from your uncle Nicky.

I've been struggling with the question of how best to do the documentation 
accompanying open source Ada projects. It is especially important that the 
maintenance (as well as user) documentation is present, usable, and itself 
continuously maintainable, for this kind of project.

I've tinkered with DocBook, Texinfo, and other systems (even trying to 
invent one of my own). I've attempted to add 'literate programming' 
functionality to these systems.

Literate programming is a fancy way of documenting source code. The basic 
idea is that you break up the source code into fragments, and intersperse 
appropriate documentation with the fragments. The fragments can be 
reordered, and referentially contain other fragments (to form a hierarchy). 
This technique is capable of producing superbly documentated source code, 
since you can introduce concepts in the order which best fits explication, 
and show just the source code that needs to be described as you go along.

However, LP has problems. The classic mechanism requires that orignal 
program and document source text be intermixed in a single or set of 
physical text files, called 'web' files (nothing to do with the WWW). A 
'tangle' tool must be run to generate the actual source code files (which 
can be submitted to the compiler). This adds a new step, potentially a big 
and slow one, to the program development cycle. An alternate approach has 
been the idea of a mechanism to update the web files from changes made 
directly in the source code files, but this technique does not seem to have 
got very far.

Up to now, I've been opposed to the idea of putting the main (maintenance) 
documentation directly into the Ada source files (particularly the package 
specifications), on the grounds that this prevents the use of existing 
document preparation systems.

However, I'm now coming around to the idea. My latest hairbrained scheme is 
to write a program that will do a little bit of work reformatting comments 
in an Ada source file. I'm fairly sure it's not an original idea, but I 
cannot actually find references (on the WWW) to such a tool. Can emacs Ada 
Mode do something like this? My favourite editor is PFE (for Windows). It 
has a limited macro capability, but it's too limited for something like this.

Besides which, different people have differrent editors and document 
preparation systems (as a matter of availability or choice), and so an open 
source project ideally needs to be as agnostic on these things as possible.

So I propose to write a simple Ada program that will perform the following 
transformations on an Ada source file:

* If a line begins with "-- " (not indented), it and any immediately 
following non-blank lines are word-filled. Before word-filling, any "-- " 
at the beginning of a line is removed. After word-filling, every output 
line is prefixed by "-- ". Words are simply delimited by whitespace 
(there's no hyphenation or other fancy stuff).

* If a line begins with "--+", the remainder of the line is taken to be a 
pathname of a text file, whose contents are read. All following lines up to 
(but not including) a line beginning with "---" are deleted. The lines read 
from the text file are inserted, after having macro substitutions performed 
(as described next).

* Any occurrance of "${" followed by a name-string and then "}" is replaced 
by another string according to the name-string, iff the name-string is 
recognised.

Recognised name-strings are:

* "LINE", which is replaced by the current line number in the source file;

* "FILE", which is replaced by the full pathname of the source file;

* "DATE", which is replaced by the current date and time.

I also propose writing another quite simple Ada program which will generate 
an HTML rendition of an Ada source file. Features that could be 
incrementally added to this program could be:

* colour-code the Ada source text (highlighting reserved words, literals, 
etc.);

* simple formatting of the text in unindented comments (e.g. embolden 
!never!, italicise /always/, <code>-tag text between {} braces, etc.);

* index the identifiers, including identifiers within braces within 
unindented comments.

Also being able to generate an Texinfo rendition might be very handy, as 
well as XML (DocBook), TeX, or other formats.

These ideas lead us to the existing AdaDoc and AdaBrowse projects, both 
hosted on SourceForge. These seem to be very relevant to what I'm trying to 
achieve. However: development on AdaDoc seems to have stopped (since 2002); 
AdaBrowse relies on ASIS.

AdaDoc is written substantially in French (by Frenchmen). I don't 
personally have any objection to developing software in French, but it 
might seem less than ideal to some people. (Does it?) Is AdaDoc a dead project?

There are two reasons why I have an objection to the use of ASIS: AdaBrowse 
cannot be used on a source file which cannot be compiled (e.g. because it 
is still in an early state of development, or it has an unresolved error in 
it); a compiler which supports ASIS must be available. It does seem almost 
like using a sledgehammer to crack a nut.

Comments welcome.

-- 
Nick Roberts