Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[stephane@_delete_this_rochebrune.org (Stephane Riviere)]

Hi Nick & all,

There is an alternative to your needs which has the merit to exist and
does not need an ASIS compiler : AdaDoc with its new Texinfo module
(not yet include in official AdaDoc release but available from me).

AdaDoc is french made but full english doc exist. It is known to work
reliably with any Ada compiler under Win or Linux.

AdaDoc can output HTML, TeX and now Texinfo !

Texinfo is (to my taste) a very important document format because you
can output to standart HTML, INFO, PS, PDF, TXT, and, believe or not,
even it is out of my scope of interest, win HLP format, plus some
unfamiliar ones. Texinfo has also a very simple, well designed, format
(much much simpler than TeX). 

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

By the way, PFE is a very good editor, I used it for years. Too bad
its author dropped it.

Under AIDE (for Windows but AIDE use ONLY free cross-platform tools),
I've a complete documentation tools suite.

Inputs :

Emacs/Glide (Texinfo aware) for texts
DIA and Gimp for diagrams and figures
Dia2code for UML diagrams and Ada gen code
AdaDoc (with new texinfo module, it's the corner stone of the whole)
for automatic specs inclusion in texinfo document...

output :

HTML, PS and PDF (with graphics)
INFO and TXT (no graphics)

FYI, AdaDoc is not dead. It is a very interesting project because it
does not need ASIS. It uses AFLEX and AYACC and XMLAda (XML is the
intermediate common format) . I've recompile the whole without any
problem with AIDE (under Windows) with the makelinux bash file ;)

The resulting docs are very impressive : beautiful output with almost
no manual work at all !

To "beautify" the output, as my texinfo module for AdaDoc accepts
additional texinfo tags inside Ada comments, I use to include @i{}
tags to format some words in italic :

example : 

-- @i{Description} : Put a text on the console at given coordinates
with specified colors attributes followed by a new line.
-- @i{Row} : Row coordinate.
-- @i{Col} : Column coordinate.
-- @i{Fore} : Foreground color.
-- @i{Back} : Background color.
Procedure Put_Lc(Row  : Line := 1;
                 Col  : Column :=1;
                 Text : String;
                 Fore : in Color_Type := Gray;
                 Back : in Color_Type := Black);

But this is only to beautify : you do not need any special character
in your source to use AdaDoc : just put your text before the
procedure, function, etc...to comment...

In this case, the parameters are of course extracted and ordered in
tables, with types and initializations...

You can also use TeX inside a Texinfo


I can sent to you some ADS with PDF results (even the TOC is
automatically generated, and so on for the PDFhierarchical bookmarks),
with the modified AdaDoc sources with samples. 

With this documentation tool suite, I can now create multi format and
consistent (allways up to date, no sync problems)  :

user docs,
technical docs,
reference manual,

Regards,

-- 
Stephane Riviere
Oleron Island - France
http://stephane.rochebrune.org
OpenPgp Key <5fd6a1e6> available on the web site above