Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Andre <avsaway@hotmail.com>]

Nick Roberts wrote:
> 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.
> 

I think you need to keep it simple (as many of the replies also state)
Here a sample of how I write down my comment in the source code.

    --  .Operation: Put a date-time in a string
    --  .Preconditions:
    --   .in: FTime, the date-time
    --  .Semantics:
    --   Format the date-time in yyyy-mm-dd hh:mm:ss.mmm
    --  .Postconditions:
    --   .return: a string with the date-time
    function Date_As_Str
       (SysTime : SYSTEMTIME)
       return String;

I have written a small program which takes the main ada source file as 
input and browses all 'with's to parse all source files. Each source 
file gets its onw HTML file with documentation.

I use '--  .<keyword>:' to detect if it is valid documentation.

Of course this can be extended with additional stuff to format the 
documentation, add images, hyperlinks and ....

When I finish a (re)design or want an update of my documentation, I just 
run my own program to create the HTML pages.
I also create a Microsoft help project with all the HTML files. Then I 
can create a Compiled Help file, which I can print to paper or to PDF 
using PDF Creator.