Literate Programming in Ada, AdaDoc, AdaBrowse

From: Nick Roberts (nick.roberts_at_acm.org)
Date: 10/09/04 

Date: Sat, 09 Oct 2004 18:44:43 +0100

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

Relevant Pages

  • Re: Literate Programming in Ada, AdaDoc, AdaBrowse
    ... > documentation accompanying open source Ada projects. ... for things that are too complex for Ada ... > (particularly the package specifications), ...
    (comp.lang.ada)
  • Re: Ada OS
    ... Location of the main documentation and links ... the "c2ada" the program should be used on itself. ... C code to a standard Ada 95 code. ... SourceForce that is hurting SourceForce as well as the OSI. ...
    (comp.lang.ada)
  • Re: Ada OS
    ... after 3+ months you should have the complete "c2ada" working. ... Location of the main documentation and links ... should be in the download area as an archived version. ... C code to a standard Ada 95 code. ...
    (comp.lang.ada)
  • Re: strings and multidimensional arrays
    ... from Ada 83, I would have expected it to be documented as such. ... presence of aliased is all the documentation needed for that. ... Quality is scientific reality. ... -- from Zen and the Art of Motorcycle ...
    (comp.lang.ada)
  • Re: Access procedure to pointer
    ... don't see what other form of documentation would be much better. ... any decent Ada IDE will provide hyperlinks ... that's simply not necessary; .ads files serve the same ... even if ada source code is far easier to read ...
    (comp.lang.ada)