Re: Literate Programming [was: A case where ...]

[Stephen Leake <stephen.a.leake.1@gsfc.nasa.gov>]

"Nick Roberts" <nickroberts@adaos.worldonline.co.uk> writes:

> What I think just be might be a worthwhile feature to add to a future
> revision would be some kind of line-oriented Ada 'on/off switch'.
> <snip>
> A file could then contain e.g.
> 
> === docbook
> 
> <para>The next function returns the opposite direction
> to the one given as its parameter.</para>
> 
> === ada
> 
>    function Opposite (Way: in Direction) return Direction;
> 
> === docbook
> 
> <para>The next function ...
> 
> This would mean that normal text files could be used to contain mixed
> content, including Ada source code, and yet any standard Ada compiler could
> directly compile such files. 

It is tempting to put documentation in the code files, and it works
well when the system has only a few code files. But when you have 100
files, most of them small child subprograms, where do you look for the
documentation that describes the whole system?

I prefer to keep documentation in a separate file, but in the same
directory as the code (or at least the same directory tree), and build
it from the same makefile (I use LaTeX for documents).

> This would be a huge advantage over having to pre-process ('tangle')
> the files before compiling them, which tends to render the automatic
> 'make' tools supplied with Ada systems useless.

Preprocessors do not render Ada make tools useless. The preprocessor
just requires it's own 'make' step, which is easy to handle with a
generic make (such as gnu make). The generic makefile does two things;
check that all the preprocessed files are up-to-date, and then invoke
the Ada make to check that the object files are up-to-date. I've used
this technique with GNAT and ObjectAda.

One thing preprocessors do screw up is the interface between an editor
and the compiled information, used for cross-referencing code. For
example, Emacs Ada mode + GNAT normally allows a single keystroke to
bring up the source code for any definition. However, if the GNAT
preprocessor is used, that keystroke brings up the preprocessor
_output_ file, but we want the preprocessor _input_ file. In this
particular case, the GNAT compiler and preprocessor already provide
the necessary information; the Emacs Ada mode does not properly use
it (one of these days I'll fix it :).

-- 
-- Stephe