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

["Nick Roberts" <nickroberts@adaos.worldonline.co.uk>]

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

This is best explained by an example. Suppose the (new) standard defined a
line in source code, which contained just two lexemes, the first === and the
second an identifier, as being a (say) 'mode switch'. If the identifier is
ADA (ignoring case), the following text lines are parsed as Ada source code,
up to the next mode switch or the end of the file. If the identifier is
anything else, the following text lines are ignored, up to the next mode
switch or the end of the file.

A file could then contain e.g.


[begin snippet]


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


[end snippet]


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

For the unfamiliar, the essence of 'literate programming' (invented by the
heroic Prof. Don Knuth) is to combine software documentation, in its own
suitable markup language (e.g. TeX or DocBook), with the source code itself,
in the same source file. This simply means you can neatly update both source
code and documentation at the same place, in the same file, at the same
time.

In the above example, with DocBook combined with Ada, the file would be
pre-processed ('weaved') to produce pure DocBook, which would then be
processed to be rendered on the screen (e.g. in a web browser) or formatted
and printed. This pre-processing could be obviated by making the mode
switches something like "<programlisting proglang="Ada"><![CDATA[" and
"]]></programlisting>".

It would be advantageous for the switches to be defined by the standard, so
that all Ada compilers would recognize them.

It would be a splendid opportunity to add a great buzzword to Ada: we could
say it was a "literate programming language". Gotta help with advocacy!

--
Best,
Nick Roberts