Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Stephen Leake <stephen_leake@acm.org>]

Nick Roberts <nick.roberts@acm.org> writes:

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

That is certainly important.

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

I use Texinfo or LaTeX, for things that are too complex for Ada
comments.

> <snip description of Literate programming>

I agree, LP is not a good choice.

However, I think the motivation behind LP is still valid. That is,
"find a way to keep documentation up to date". The LP approach to that
is to integrate the documentation source with the code source. But I
think the reason that works is developers can easily edit
documentation and code source _within the same editor_. That suggests
a different approach; different files and syntax for documentation
source, but an Integrated Development Environment that can handle both
with ease. Emacs and GPS and others are such an IDE for Ada, Texinfo,
and LaTeX.

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

This is what AdaBrowse does. Since it is based on comments in the Ada
code, I don't think it solves the problem of how to document "things
that are too complex for Ada comments". It can produce nice summaries
of packages and type heirarchies, which is also a good thing; it helps
people learn how the code works, and/or how to use the code.

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

I think it is more important to focus on the information presented,
and less on the mechanism to do that.

There are some design decisions that simply can't be documented nicely
in Ada comments. For a simple example, the design rule that all
constructors should be declared in nested packages. You don't want to
repeat that in every package, and you don't want to designate one
package as the "prime document package". For a more complex example,
the documentation of how signals are handled in Gtk needs its own
separate document.

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

Emacs Ada mode does this. So does GPS. I consider this a minimum
requirement for any IDE. (In my opinion, PFE is _not_ a good IDE).

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

Why would this be useful? If you want it, use --#include; at least it
will be recognized.

> * 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;

What, exactly, does this mean? The line number before or after all (or
some?) substitutions are made? See the C preprocessor for possible
answers to this question.

> * "FILE", which is replaced by the full pathname of the source file;
> 
> * "DATE", which is replaced by the current date and time.

Why would these be useful? These are configuration management issues,
not design documentation issues.

"Current" when the file is loaded into the IDE? when the file is
processed by this tool? When the file was last written to disk? None
of these are very meaningful.

> I also propose writing another quite simple Ada program which will
> generate an HTML rendition of an Ada source file. 

AdaBrowse does this. If you think it needs more features, please add
them. Leverage other people's work, don't re-invent it.

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

Exactly _why_ would these be handy? You are proposing a lot of work,
with very little justification.

I want documentation to be fully searchable. I find it hard to search
a collection of html pages, but you could argue that's a browser
function. For example, Texinfo is searchable only because the Emacs
Info browser supports it. Any Open Source format that is fully
searchable via an Open Source browser is fine with me. 

Hmm. I really do prefer the browser to be integrated with the IDE
(Emacs in my case). I believe the bleeding edge Emacs can display
rendered HTML, even on Windows. But I still want full searching.

> 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); 

Why is this a problem? In my opinion, you run AdaBrowse only when you
do a release of a project (that's what I do for SAL). The generated
documentation is for people who need to learn the package, not for the
package developer; the Ada code and comments should be good enough for
them.

> a compiler which supports ASIS must be available. 

Well, the only Open Source Ada compiler is GNAT, and ASIS is available
for it. So this is a moot point (for a fully Open Source project).

> It does seem almost like using a sledgehammer to crack a nut.

ASIS is a way to access the Ada parser in the compiler front end. Any
tool that parses Ada code should use the compiler front end; otherwise
it's duplicating work. Not to mention probably wrong.

Learning to use ASIS well does take time. Perhaps for "a simple
comment parser", you don't need to parse the Ada code. But I don't
think the results of "a simple comment parser" would be worth having.

Learning to add to AdaBrowse should be simpler than learning to use
ASIS from scratch (I have not looked at the AdaBrowse sources). I
suggest you give it a try.

-- 
-- Stephe