Re: Literate Programming in Ada, AdaDoc, AdaBrowse

From: Andre (avsaway_at_hotmail.com)
Date: 10/10/04 

Date: Sun, 10 Oct 2004 11:34:15 +0200

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.

Relevant Pages

  • Literate Programming in Ada, AdaDoc, AdaBrowse
    ... I've been struggling with the question of how best to do the documentation ... accompanying open source Ada projects. ... Literate programming is a fancy way of documenting source code. ... These ideas lead us to the existing AdaDoc and AdaBrowse projects, ...
    (comp.lang.ada)
  • Re: TeX and friends
    ... There is a core of a Unix OS in the foundations, ... which does of course mean that it's easy to write a nice integrated GUI ... but what about when you can't write any documentation at all ... the source code is ...
    (uk.people.support.depression)
  • Re: Doc-O-Matic 3.7 released - Source Documentation System
    ... > Doc-O-Matic 3.7 is the latest version of our Source Code Documentation ... > PDF, HTML Help, Help 2 and Windows Help. ... > Markus Spoettl, ...
    (microsoft.public.dotnet.languages.vb)
  • Re: PIC/Linux
    ... and some documentation, shell scripts, etc., but nothing that needs to be made. ... and got a complaint that it couldn't find simulavr. ... I decided it would be helpful to look at the source code for the ... cpio --extract to extract the contents of the cpio file. ...
    (sci.electronics.misc)
  • Ann: source code sharing wiki codewiki.wikispaces.com
    ... I have set up a wiki for source code which is available for anyone to ... allow anyone to make updates to the code and documentation ... This is the true essence of a wiki. ... making changes. ...
    (comp.programming)