Literate Programming in Ada, AdaDoc, AdaBrowse

Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts]

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.

-- 
Nick Roberts

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Wes Groleau]

Were the original "tangle" "web" and "weave" open source?

I think they were in Pascal.  Should be easy to convert to
Ada and modify some of the details in the process.

-- 
Wes Groleau
   "Ideas are more powerful than guns,
    We would not let our enemies have guns;
    why should we let them have ideas?"
                                -- Jozef Stalin

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Pascal Obry]

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

> Comments welcome.

I'm just worried that the original source code instrumented with "--  "
(unindented), "--+ " and "--- " plus the ${} macros would not be really easy
to read. Do you have small example of an instrumented code ?

Pascal.

-- 

--|------------------------------------------------------
--| Pascal Obry                           Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--|              http://www.obry.org
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver wwwkeys.pgp.net --recv-key C1082595

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts]

Wes Groleau wrote:
> Were the original "tangle" "web" and "weave" open source?
> 
> I think they were in Pascal.  Should be easy to convert to
> Ada and modify some of the details in the process.

Well, yes, but that doesn't address the problem I mentioned, that have to 
run the tangle program evry time between changing the source code (even 
slightly) and recompiling and running.

Since (as I understand it) tangling involves reading and interpreting /all/ 
the web files of the project, and regenerating /all/ the source code files 
(obviously, there may be hundreds), it just isn't a practical proposition 
for software development.

-- 
Nick Roberts

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[stephane richard]

"Nick Roberts" <nick.roberts@acm.org> wrote in message 
news:2sr234F1oog3tU1@uni-berlin.de...
>
> Well, yes, but that doesn't address the problem I mentioned, that have to 
> run the tangle program evry time between changing the source code (even 
> slightly) and recompiling and running.
>
> Since (as I understand it) tangling involves reading and interpreting 
> /all/ the web files of the project, and regenerating /all/ the source code 
> files (obviously, there may be hundreds), it just isn't a practical 
> proposition for software development.
>
> -- 
> Nick Roberts

Have you looked at AIDE ? http://stephane.rochebrune.org/aide/aide.html

it uses textinfo. I don't know how integrated to the rest it is....but I 
think there's a lot of things to facilitate the process...that combined with 
Emacs macros might help...I'd have a quick read :-).

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts]

Pascal Obry wrote:

> I'm just worried that the original source code instrumented with "--  "
> (unindented), "--+ " and "--- " plus the ${} macros would not be really easy
> to read. Do you have small example of an instrumented code ?

This is my idea of what the beginning of a package specification might look
like after being reformatted. I've not shown the expansion of "gmgpl.txt"
but I'm sure you can imagine the usual message.

~~~

-----------------------------------------------------------------------------------------------
-- {Titian.Color} package specification

-- Copyright (C) 2004 Nicholas James Roberts (South Croydon, Surrey, UK).

--+gmgpl.txt


-----------------------------------------------------------------------------------------------
-- =####= Color =####=

-- Titian uses a color system which accomodates the fact that many computer display systems can
-- only show a limited number of different colors at a time, whilst others can show an
-- unlimited number. For the former kind of display systems, the set of colors which can be
-- displayed is generally called a 'palette'. The latter display systems are often described
-- as 'true color' systems; the Titian term for them is that they have *'direct color'.

-- Titian ensures that the programmer has the choice of using direct color values or colors
-- selected from a palette, for all drawing operations. The former option will be slightly
-- more efficient for direct color contexts, and may be more convenient regardless of the
-- context. The latter option will be more efficient for contexts which do not have direct
-- color (but will be reasonably efficient for contexts that do). For maximum efficiency with
-- all possible contexts, the programmer could program two different algorithms for contexts
-- with and without direct color.

-- The basic color definitions are collected in this package ({Titian.Color}). Other
-- color-related packages are {Titian.Color.CMYK} and {Titian.Color.HSL}. The
-- color-related graphics context primitive operations are declared in the package
-- {Titian.Raster_IO}.

-- The term *'palette' is used for any set of distinct colors, as well as for the particular
-- set of colors associated with a graphics context.

-- Dealing with color in a way which will be suitable for the widest range of devices presents
-- bit of a challenge: different devices have widely varying ways of supporting color (e.g.
-- from those which have no colors at all, to video adapters which support a plethora of
-- different modes, each with its own combination of bit-planes, palette sizes, and so on). I
-- think there is a necessity to support the sophisticated color options many devices provide
-- - it would surely be a shame not to allow programs to take full advantage of them - but not
-- to the extent that overly complicates life for the poor beleaguered application programmer.
-- Furthermore, the facilities provided by the proposed binding for color manipulation must be
-- reasonably efficient. To this end, I have devised a system which hopefully allows
-- programmers the best of both worlds.

-- I hope the term direct color (defined just above) will be considered reasonably neutral.

-- I need help with the color systems. Also, I am completely in the dark as to the ins and
-- outs of color correction: I would appreciate help in this area.


-----------------------------------------------------------------------------------------------
with ???;


-----------------------------------------------------------------------------------------------
package Titian.Color is

   pragma Pure;


-----------------------------------------------------------------------------------------------
-- =###= The {Color_Error} Exception =###=

-- There is one color-related exception, {Color_Error}.

   Color_Error: exception;

-- The {Color_Error} exception is raised if:

-- * an attempt to engage a color in a palette fails (normally because the palette doesn't
-- have enough free slots);

-- * an attempt is made to use a color selector for an invalid slot (one which is neither
-- fixed nor has been engaged);

-- * an attempt is made to release fixed colors;

-- * a color conversion cannot be effected, either because the calculation would be too
-- difficult (or slow), or because the destination type cannot hold a color value
-- corresponding (closely enough) to the color being converted.


-----------------------------------------------------------------------------------------------
-- =###= Basic Color Descriptor =###=

-- The type {Basic_Color} holds color values in the familiar Red-Green-Blue, or *'RGB', system
-- of color representation, with the addition of an *'alpha value', which can be used to
-- control the extent to which the background of an image is allowed to show through. The RGB
-- system with alpha values can be termed the *'RGBA' color system.

   type Light_Level is delta 1.0/2**32 range 0.0 .. 1.0; -- implementation defined delta
   type Alpha_Level is delta 1.0/2**32 range 0.0 .. 1.0; -- implementation defined delta

   for Light_Level'Size use 32; -- implementation defined
   for Alpha_Level'Size use 32; -- implementation defined

   type Basic_Color is
      record
         Red, Green, Blue: Light_Level;
         Alpha: Alpha_Level := 1.0;
      end record;

   for Basic_Color'Size use 32*4; -- implementation defined

~~~

I think my idea for macro substitution (${...}) is not so clever, and
could be dropped. Maybe =###= could be used to delimit titles. Possibly
--- at the beginning of a line could be expanded to a line across. There
would have to be special logic to avoid trying to word-wrap lines
across! The lone * represents a bullet (for a list item). The form
*'foo' is intended to enter the word foo into a cross-index.

Obviously this is only a tiny example.

The syntax of the macros (if I keep them), would perhaps need to be
$LINE{...} where the ... is replaced by the correct value. The idea
behind the macros was so that you could write something like:

   if Error_Detected then
      Put_Line (Current_Error, "Error in $LINE{} $FILE{}");
   else
      ...

If the Put_Line happened to be on line 234 of the file "wibble.adb", then
the above would be expanded to:

   if Error_Detected then
      Put_Line (Current_Error, "Error in $LINE{234} $FILE{wibble.adb}");
   else
      ...

I'm not quite sure if this would be worth it.

-- 
Nick Roberts

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Lionel Draghi]

Hello Nick,

NaturalDocs may be interresting for you. It partially comply with your 
description. You can build documentation with sources, text files, 
pictures, etc. The structure of the document is in a text file.
The main point is that you don't need more or less akward comment 
conventions or tags, and that it works on illegal Ada sources.

Take a look on those page, there is a slightly modified example from the 
Ada Quality and Style, and the corresponding html page:
http://lionel.draghi.free.fr/Natural_Docs_Test/autolayout.ads
http://lionel.draghi.free.fr/Natural_Docs_Test/doc/autolayout-ads.html

Pages like http://lionel.draghi.free.fr/Natural_Docs_Test/doc/ are 
generated from simple text files.

On a project not yet public, I have a documentation build from sources, 
some text files, and UML diagrams exported from dia in svg format.

It's far from beeing perfect, the result is far from beeing pretty, but 
it's so easy to use, and with almost no constraint on sources.

-- 
Lionel Draghi

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Björn Persson]

Nick Roberts wrote:

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

The requirement that these comments must be unindented could become a 
problem. GPS auto-indents comments as well as code, and I would think 
there are other editors that do the same. Programmers would have to 
fight this auto-indentation every time they edited these comments.

 > * simple formatting of the text in unindented comments (e.g. embolden
 > !never!, italicise /always/, <code>-tag text between {} braces, etc.);

These should of course be kept as compatible with other tools as 
possible. *Asterisks* are commonly used for emphasis. I read Usenet with 
Mozilla, and it shows this kind of notation as *bold*, /italic/ and 
_underlined_. Adabrowse turns "@code@" into "<CODE>code</CODE>".

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Björn Persson]

Nick Roberts wrote:

> The syntax of the macros (if I keep them), would perhaps need to be
> $LINE{...} where the ... is replaced by the correct value. The idea
> behind the macros was so that you could write something like:
> 
>   if Error_Detected then
>      Put_Line (Current_Error, "Error in $LINE{} $FILE{}");
>   else
>      ...

I think this would be done better with functions:

    if Error_Detected then
       Put_Line (Current_Error, "Error on line " & ECLAT.Line_Number &
                                " in " & ECLAT.File_Name & '.');
    else
       ...

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Wes Groleau]

Nick Roberts wrote:
> Since (as I understand it) tangling involves reading and interpreting 
> /all/ the web files of the project, and regenerating /all/ the source 
> code files (obviously, there may be hundreds), it just isn't a practical 
> proposition for software development.

Would it not be possible with GNAT to tweak something
so that gnatmake looks at changes in 'web' files instead
of changes in .ad{s,b} files, and does the conversion
(one file at a time) automagically before compiling?

-- 
Wes Groleau

    If you put garbage in a computer nothing comes out but garbage.
    But this garbage, having passed through a very expensive machine,
    is somehow ennobled and none dare criticize it.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Wes Groleau]

Nick Roberts wrote:
> -- =###= The {Color_Error} Exception =###=
> 
> -- There is one color-related exception, {Color_Error}.
> 
>   Color_Error: exception;

What does the first line tell you that the third does not?
If the answer is nothing, then why can't the tool get the
info from line three?

In my opinion, well-written Ada code can be it's own documentation.
Sure, readers will want to skip over some code and/or some comments
(different readers will skip different parts) but I see no point
in having the same info two or more times in two or more formats
even if some tool splits it up for human consumption.

I certainly see no point in omitting the comments from the code
and instead burying them in pages of bureaucratic boilerplate
in some 500-page specification.

A corollary of Murphy's law is that duplicate information
eventually becomes different information.  Putting both
in the same file may slow down the process, but it will
not prevent it.

-- 
Wes Groleau

People would have more leisure time if it weren't
for all the leisure-time activities that use it up.
                        -- Peg Bracken

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Wes Groleau]

Björn Persson wrote:

> Nick Roberts wrote:
>  > * simple formatting of the text in unindented comments (e.g. embolden
>  > !never!, italicise /always/, <code>-tag text between {} braces, etc.);
> 
> These should of course be kept as compatible with other tools as 
> possible. *Asterisks* are commonly used for emphasis. I read Usenet with 
> Mozilla, and it shows this kind of notation as *bold*, /italic/ and 
> _underlined_. Adabrowse turns "@code@" into "<CODE>code</CODE>".

Why not use XML ?  Shouldn't be too hard to put together
an XML-processor that can do the split-up for you.  In fact,
if the XML is designed well, it would not be hard to use CSS
to output different things, different formats, and/or different
parts according to whether viewing (hearing) with a web browser,
a screen reader, or some other @media (device/destination).

-- 
Wes Groleau
   "Two things are infinite, the universe and human stupidity.
    But I'm not so sure about the universe."
                                -- Albert Einstein

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Björn Persson]

Wes Groleau wrote:

> Why not use XML ?  Shouldn't be too hard to put together
> an XML-processor that can do the split-up for you.  In fact,
> if the XML is designed well, it would not be hard to use CSS
> to output different things, different formats, and/or different
> parts according to whether viewing (hearing) with a web browser,
> a screen reader, or some other @media (device/destination).

If you mean including XML tags in the comments in the source code, yes 
it allows a lot of nice formatting in the generated documents, but it 
tends to make the source files harder to read. The trick is to find a 
balance that produces nice documents and doesn't make the comments hard 
to read for the programmer who works with the source code.

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Steve]

Just to share another hairbrained scheme regarding documentation.

What I would like to see is a fancy programming editor that allows you to
include text, graphics, spreadsheets, etc., in comments.

A way to do this is to maintain the source code as text with special markers
referencing the comments, and maintain the comments in a separate file or
database.  The approach has the advantage that the compiler doesn't have to
deal with the comments and the source may be viewed without the comments
using a different editor.  It has the disadvantage that a special editor is
required to edit the code along with the comments, and since the code and
comments are in separate files, there is always potential of losing the
comment files.  The editor could be made to output the source with comments
in a standard format: html, pdf, etc.

I'm one of those guys that likes to draw a lot of diagrams describing code.
It is often hard to assemble comments in code that do the diagram justice.

Steve
(The Duck)

"Nick Roberts" <nick.roberts@acm.org> wrote in message
news:2sqmccF1oit5sU1@uni-berlin.de...
> 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.
[snip]
> Comments welcome.
>
> -- 
> Nick Roberts

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[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

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Oliver Kellogg]

Bj�rn Persson wrote:

>>   if Error_Detected then
>>      Put_Line (Current_Error, "Error in $LINE{} $FILE{}");
>>   else
>>      ...
> 
> I think this would be done better with functions:
> 
>     if Error_Detected then
>        Put_Line (Current_Error, "Error on line " & ECLAT.Line_Number &
>                                 " in " & ECLAT.File_Name & '.');
>     else
>        ...
> 

Minor quibble: This notation blurs the distinction between parse time
and run time evaluation, is that intentional?

Oliver M. Kellogg

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Andre]

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.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Björn Persson]

Oliver Kellogg wrote:

> Björn Persson wrote:
> 
>>    if Error_Detected then
>>       Put_Line (Current_Error, "Error on line " & ECLAT.Line_Number &
>>                                " in " & ECLAT.File_Name & '.');
>>    else
>>       ...
> 
> Minor quibble: This notation blurs the distinction between parse time
> and run time evaluation, is that intentional?

Yeah, well, is it harmful? I would expect a good compiler to perform as 
much evaluation as possible at compile time.

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Pascal Obry]

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

> This is my idea of what the beginning of a package specification might look
> like after being reformatted. I've not shown the expansion of "gmgpl.txt"
> but I'm sure you can imagine the usual message.

Thanks for the simple example. I indeed do not like the unindented comments
in the spec but I have nothing to propose at the moment... we'll see...

Pascal.

-- 

--|------------------------------------------------------
--| Pascal Obry                           Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--|              http://www.obry.org
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver wwwkeys.pgp.net --recv-key C1082595

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Marius Amado Alves]

I appreciate the requirement for some kind of master system containing 
both documentation and program elements.

The original Knuthian literate programming idea was not special comments 
in the source code but the other way around, source code fragments 
embedded in the text, which text being a piece of technical literature 
describing the system under construction.

It's not just a difference of perspective.

Documentation and source code are two very different things, and one 
should not step on the feet of the other.

Overloading the source code with documentation elements ruins the source 
code.

Lately I've been putting all comments, if any, in the bottom of the 
source code file.

And of course one should always write code in a way that it reduces the 
need for comments.

When some unit needs extensive commentary, the place for that is in a 
separate file.

The link between documentation and source code items is based on the 
names of the source code entities.

This model is sufficient even for hypertext generation.

The rest is pretty printing :-)

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Wes Groleau]

Björn Persson wrote:

> If you mean including XML tags in the comments in the source code, yes 
> it allows a lot of nice formatting in the generated documents, but it 
> tends to make the source files harder to read. The trick is to find a 

No. I mean using XML and CSS as the basis for the
original poster's desire for a way to easily extract
compilable code and/or human-readable documentation
FROM the web file.


-- 
Wes Groleau
-----------
Daily Hoax: http://www.snopes2.com/cgi-bin/random/random.asp

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Wes Groleau]

Steve wrote:

> Just to share another hairbrained scheme regarding documentation.
> 
> What I would like to see is a fancy programming editor that allows you to
> include text, graphics, spreadsheets, etc., in comments.
> 
> A way to do this is to maintain the source code as text with special markers
> referencing the comments, and maintain the comments in a separate file or
> database.  The approach has the advantage that the compiler doesn't have to
> deal with the comments and the source may be viewed without the comments
> using a different editor.  It has the disadvantage that a special editor is
> required to edit the code along with the comments, and since the code and
> comments are in separate files, there is always potential of losing the
> comment files.  The editor could be made to output the source with comments
> in a standard format: html, pdf, etc.

Already available:

fancy editor    = WYSIWYG HTML or XML editor
viewer          = web browser
special markers = XML tags

This can be done in the style I earlier proposed,
where the code is extracted from the file for compiling.
But it can also be done where the HTML/XML appears ONLY
in the code comments.  In the latter, however, it may be
difficult to make right margins (indents) look right.

-- 
Wes Groleau

A pessimist says the glass is half empty.

An optimist says the glass is half full.

An engineer says somebody made the glass
        twice as big as it needed to be.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Steve]

"Wes Groleau" <groleau+news@freeshell.org> wrote in message
news:VdOdnQV68tGu3_TcRVn-rQ@gbronline.com...
> Steve wrote:
>
> > Just to share another hairbrained scheme regarding documentation.
> >
> > What I would like to see is a fancy programming editor that allows you
to
> > include text, graphics, spreadsheets, etc., in comments.
> >
> > A way to do this is to maintain the source code as text with special
markers
> > referencing the comments, and maintain the comments in a separate file
or
> > database.  The approach has the advantage that the compiler doesn't have
to
> > deal with the comments and the source may be viewed without the comments
> > using a different editor.  It has the disadvantage that a special editor
is
> > required to edit the code along with the comments, and since the code
and
> > comments are in separate files, there is always potential of losing the
> > comment files.  The editor could be made to output the source with
comments
> > in a standard format: html, pdf, etc.
>
> Already available:
>

Great!
Where can I find it?
I'm running on Windows 2000.

Steve
(The Duck)

> fancy editor    = WYSIWYG HTML or XML editor
> viewer          = web browser
> special markers = XML tags
>
> This can be done in the style I earlier proposed,
> where the code is extracted from the file for compiling.
> But it can also be done where the HTML/XML appears ONLY
> in the code comments.  In the latter, however, it may be
> difficult to make right margins (indents) look right.
>
> -- 
> Wes Groleau
>
> A pessimist says the glass is half empty.
>
> An optimist says the glass is half full.
>
> An engineer says somebody made the glass
>         twice as big as it needed to be.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Stephen Leake]

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

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Stephen Leake]

"Steve" <nospam_steved94@comcast.net> writes:

> Just to share another hairbrained scheme regarding documentation.
> 
> What I would like to see is a fancy programming editor that allows you to
> include text, graphics, spreadsheets, etc., in comments.

I would find that hard to read. This is what hyperlinks are for; put
the URL in the code, an have your IDE bring up the referenced document
at a keystroke (or mouseclick if you insist :). Works quite well for me.

> A way to do this is to maintain the source code as text with special
> markers 

IE, URLs.

> referencing the comments, and maintain the comments in a separate
> file or database. 

Whatever format your IDE supports. In my case, that's whatever format
Windows supports, since it's easy for Emacs to start an external tool
to show any Windows format known to the Windows registry.

> The approach has the advantage that the compiler doesn't have to
> deal with the comments 

Yes

> and the source may be viewed without the comments using a different
> editor. 

Yes.

> It has the disadvantage that a special editor is required to edit
> the code along with the comments, and since the code and comments
> are in separate files, there is always potential of losing the
> comment files. The editor could be made to output the source with
> comments in a standard format: html, pdf, etc.

Nothing special here, just URLs and MS Windows. I assume there is
something similar for X Windows; I haven't tried.

> I'm one of those guys that likes to draw a lot of diagrams
> describing code. 

Good.

> It is often hard to assemble comments in code that do the diagram
> justice.

Try URLs.

-- 
-- Stephe

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Stephen Leake]

Andre <avsaway@hotmail.com> writes:

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

This is an absolutly perfect example of why the documentation
generator needs to parse the full Ada code. What is the name of the
parameter? The document says "FTime", the code says "SysTime". 

I don't trust _anyone_ to maintain comments like this. That's what
tools are for!

-- 
-- Stephe

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Stephen Leake]

Björn Persson <spam-away@nowhere.nil> writes:

> Oliver Kellogg wrote:
> 
> > Björn Persson wrote:
> >
> >>    if Error_Detected then
> >>       Put_Line (Current_Error, "Error on line " & ECLAT.Line_Number &
> >>                                " in " & ECLAT.File_Name & '.');
> >>    else
> >>       ...
> > Minor quibble: This notation blurs the distinction between parse time
> > and run time evaluation, is that intentional?
> 
> Yeah, well, is it harmful? I would expect a good compiler to perform
> as much evaluation as possible at compile time.

If the purpose of $LINE is to give you debugging information, then use
the debugger instead.

If it's to give you a stack dump from deployed applications, so the
developer can debug it separately, then use GNAT.Tracebacks.Symbolic
instead.

Focus on what the feature will actually be used for.

-- 
-- Stephe

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Simon Wright]

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

> Wes Groleau wrote:
> > Were the original "tangle" "web" and "weave" open source?
> > I think they were in Pascal.  Should be easy to convert to
> > Ada and modify some of the details in the process.

The way the Pascal code was compiled to produce TeX was using a
special Pascal-to-C converter! I don't see any point in reworking that
part of it.

> Well, yes, but that doesn't address the problem I mentioned, that
> have to run the tangle program evry time between changing the source
> code (even slightly) and recompiling and running.
> 
> Since (as I understand it) tangling involves reading and
> interpreting /all/ the web files of the project, and regenerating
> /all/ the source code files (obviously, there may be hundreds), it
> just isn't a practical proposition for software development.

I believe I have a counter-proof by existence; my current project uses
a code generator that re-generates all the "framework" files every
time (from Rational Rose UML models); the logic is written in separate
bodies.

The reason it works is the -m (minimal recompilation) switch to
gnatmake, which checks whether a file whose timestamp has changed has
changed semantically as well. Clearly this involves reading the file,
so you need to do a full rebuild after lots of changes -- but in most
cases it does quite well. I doubt you would have the whole project in
one mammoth source file, you'd probably organize by chapters (for
example).

The time I did literate programming I used nuweb. I forget whether it
could produce HTML, the native output was LaTeX; with pdfTeX (not sure
of the capitalisation there!) you got very nice results.

Another tool, which I never used, was noweb.

-- 
Simon Wright                               100% Ada, no bugs.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Andre]

Stephen Leake wrote:
> Andre <avsaway@hotmail.com> writes:
> 
> 
>>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;
> 
> 
> This is an absolutly perfect example of why the documentation
> generator needs to parse the full Ada code. What is the name of the
> parameter? The document says "FTime", the code says "SysTime". 
> 
> I don't trust _anyone_ to maintain comments like this. That's what
> tools are for!
> 

This happens when code, including its comments, is copied.

But Stephen how do you want the couple the description with its 
parameter in an automatic way? This example is probably unneccessary 
comment, the name is self explaning, but that is not always the case.

By number (in this sample 1) goes also wrong when a parameter is added.

The only thing which could be done is check the given comment with the 
actual function prototype and generate errors.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Ole-Hjalmar Kristensen]

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

    NR> Wes Groleau wrote:
    >> Were the original "tangle" "web" and "weave" open source?
    >> I think they were in Pascal.  Should be easy to convert to

    >> Ada and modify some of the details in the process.

    NR> Well, yes, but that doesn't address the problem I mentioned, that have
    NR> to run the  tangle program evry time between  changing the source code
    NR> (even slightly) and recompiling and running.


    NR> Since (as I understand  it) tangling involves reading and interpreting
    NR> /all/ the web files of  the project, and regenerating /all/ the source
    NR> code  files  (obviously, there  may  be  hundreds),  it just  isn't  a
    NR> practical proposition for software development.


    NR> -- 
    NR> Nick Roberts

Make will automate the tangling, so it can work, but in my experience
the main problem is that you compile generated source code, and your
development environment is probably set up to let you edit and fix
errors in those files, not in the original "web" document.  So I think
your solution is better. It is essentially the same idea as javadoc
and numerous C++ documentation tools. Somewhere I stumbled over a
system which could be tailored to different programming languages, but
I have forgotten where....

-- 
   C++: The power, elegance and simplicity of a hand grenade.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts]

Nick Roberts wrote:

> Time for the latest hairbrained scheme from your uncle Nicky.
> ...

Thanks to everyone for your replies.

I still feel that AdaDoc, AdaBrowse, and other suggested solutions don't
quite do what I personally want. Maybe it's a bit 'horses for courses'.

Anyway, I think I'm going to experiment with a program that, in effect,
regenerates the web files from the source files. Except that I'll use
normal Texinfo files for the 'web' files (with the addition of a few
special macros).

In the source files, each fragment will start with a comment that
contains its title between two special symbols. The symbols will be a
pair of =####= for a top-level fragment, a pair of =###= for the next
level down, and so on. Within the Texinfo files, I'll use the @lpfrag
macro, followed the fragment's name, to insert the actual text of a
fragment (with sub-fragments reduced to references).

This way, source files can be amended and recompiled without making
something else invalid, and the Texinfo files (having been processed
by my program) can be processed in the normal way to produce HTML or
other formats.

A source file will look like this:

~~~

=####= Overall program =####=
   =###= Mix the ingredients =###=
   ... mix
   =###= Bake them in oven =###=
      =##= Open oven door =##=
      ... open
      =##= Put things in oven =##=
      ... put in

~~~

The original Texinfo file might look like this:

~~~

Opening the oven door is easy, all you have to do is...

@lpfrag Open oven door

Mixing ingredients is tricky if you don't use the ...

@lpfrag Mix the ingredients

Putting things into the oven requires gloves ...

@lpfrag Put things in oven

Baking things in an oven takes steps, first ...

@lpfrag Bake them in oven

Making a cake ...

@lpfrag Overall program

~~~

Which would be expanded into (something like) the following:

~~~

Opening the oven door is easy, all you have to do is...

@verbatim Open oven door
... open
@end verbatim

Mixing ingredients is tricky if you don't use the ...

@verbatim Mix the ingredients
... mix
@end verbatim

Putting things into the oven requires gloves ...

@verbatim Put things in oven
... put in
@end verbatim

Baking things in an oven takes steps, first ...

@verbatim Bake them in oven
@lpref Open oven door
@lpref Put things in oven
@end verbatim

Making a cake ...

@verbatim Overall program
@lpref Mix the ingredients
@lpref Bake them in oven
@end verbatim

~~~

Anyway, I'll experiment with this a bit. To be honest, I suspect it
would be easier to write my processing program in a langauge such as
Python or Perl. Any recommendations? (Gawk?)

I do think that the documentation produced by this technique would
be supplemented, perhaps very usefully, by the output of AdaDoc or
AdaBrowse.

-- 
Nick Roberts

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Björn Persson]

Hey Nick, do you like Frank Sinatra?

You're writing your own operating system, your own compiler, your own 
windowing system, and now your own documentation system.

"I did it myyy waaay."

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Björn Persson]

Stephane Riviere wrote:

> just put your text before the
> procedure, function, etc...to comment...

Does AdaDoc require that the description be before the declaration, or 
can it be after too? I find it more natural to put it after, like this:

    function Synonym
      (Reference : Parameter_Name)
       return Parameter_Definition_Handle;
    --  Returns a definition which states that the parameter is
    --  an alternative name for another parameter.

    function Antonym
      (Reference   : Parameter_Name;
       Description : EAstring := Null_EAstring)
       return Parameter_Definition_Handle;
    --  Returns a definition which states that the parameter is
    --  the opposite of another parameter. It can only be used
    --  on boolean parameters.

    Illegal_Antonym : exception;
    --  A parameter is defined as an antonym of a parameter that
    --  can't have antonyms. (Only boolean parameters can have
    --  antonyms.)

This tells you first of all what is being declared (function, type, 
variable ...) and what its name is. Then it's explained what it does, 
and if parameter names are mentioned in the description, then they have 
been declared before they're referenced, just like in the code.

In my opinion, writing the description before the declaration breaks the 
text flow in about the same way as top-posting does.

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Missing features in NaturalAdaBrowseDoc...

[Lionel Draghi]

Something that I would find useful for a tool like AdaBrowse, is the 
ability to provide indexes on specific entries in the comments.

For example, let's say I put a "Portability issues" in somes headers.
When porting my soft, I find akward an error prone to "grep" this field. 
I would appreciate to have an index in the generated pages that provide 
me with a fast acces to all those entry.

Another cool feature would be to defines special fields that contains a 
list of references. For exemple requirements or bug Id, like in:

-- Requirements: req_234, req_456, req_007, req_098,
--               req_937

And then to have the cross reference generated between each req and 
sources where it is referenced.

I am pretty sure that a lot of project develop this kind of had hoc tools.

-- 
Lionel

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Lionel Draghi]

Stephen Leake wrote:
> Andre <avsaway@hotmail.com> writes:
> 
> 
>>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;
> 
> 
> This is an absolutly perfect example of why the documentation
> generator needs to parse the full Ada code. 
This is just an absolutly perfect example of why the comments should not 
repeat what is already in the code :-)

On the other hand, if you have to comment about a special parameter 
semantics, parsing the whole Ada code won't help catching a discrepancy.

-- 
Lionel

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Björn Persson]

Lionel Draghi wrote:

> Stephen Leake wrote:
> 
>> Andre <avsaway@hotmail.com> writes:
>>
>>> 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;
>>
>> This is an absolutly perfect example of why the documentation
>> generator needs to parse the full Ada code. 
> 
> This is just an absolutly perfect example of why the comments should not 
> repeat what is already in the code :-)
> 
> On the other hand, if you have to comment about a special parameter 
> semantics, parsing the whole Ada code won't help catching a discrepancy.

But at least it causes both "FTime" and "SysTime" to be carried over to 
the document, making the discrepancy visible. If only "FTime" appeared 
in the document, anyone trying to use the document would get strange 
compilation errors, and only when in desperation they resorted to 
reading the code would the reason be revealed.

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Missing features in NaturalAdaBrowseDoc...

[tmoran]

>Something that I would find useful for a tool like AdaBrowse, is the
>ability to provide indexes on specific entries in the comments.
  The program that scans pages on web sites and indexes them for
www.adaic.com can trivialy scan a set of docs in the form of html files.
Then Randy's search tool (see Search Ada sites at www.adaic.com) could do
your searches.  (The doc tool that makes Claw's searchable Windows Help
files preceded the html search project.)

>And then to have the cross reference generated between each req and
>sources where it is referenced.
  The searcher's database, of course, is basically a list of "where
referenced" for search terms, and could be dumped as such.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Georg Bauhaus]

Simon Wright <simon@pushface.org> wrote:
: Nick Roberts <nick.roberts@acm.org> writes:
: 
:> Wes Groleau wrote:
:> > Were the original "tangle" "web" and "weave" open source?
:> > I think they were in Pascal.  Should be easy to convert to
:> > Ada and modify some of the details in the process.
: 
: The way the Pascal code was compiled to produce TeX was using a
: special Pascal-to-C converter!

The tex.web sources speak of a Pascal compiler
"that was available to the author in 1982."
(Yes, there are systems that compile WEB (Pascal) to C.)
This seems to have been an intention:
"a conscious effort has been made here to avoid using several idiosyncratic
features of standard \PASCAL\ itself, so that most of the code can be
translated mechanically into other high-level languages."

: I don't see any point in reworking that
: part of it.

There is an Ada 83 WEB version.

ftp://ftp.ctan.org/tex-archive/web/ada/aweb/aweb.pro

Re: Missing features in NaturalAdaBrowseDoc...

[Marc A. Criley]

"Lionel Draghi" <Lionel.nospam.Draghi@Ada-France.org> wrote:
> Something that I would find useful for a tool like AdaBrowse, is the
> ability to provide indexes on specific entries in the comments.

Pass this suggestion on to AdaBrowse's maintainer, Thomas Wolfe; he may be
willing to add it.

Marc A. Criley
McKae Technologies
www.mckae.com

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts]

Bj�rn Persson wrote:

> Hey Nick, do you like Frank Sinatra?
> 
> You're writing your own operating system, your own compiler, your own 
> windowing system, and now your own documentation system.
> 
> "I did it myyy waaay."

Hehe. Yes!

However, AdaOS is not a revolutionary design. Its design is based mainly
on current OS orthodoxy. The ECLAT compiler is a new compiler, but the
language (Ada) isn't. The windowing system (Titian) is in abeyance at the
moment; I may never devlop it. And I'm not really writing a whole new
documentation system (although I did think of doing so at one point); I'm
only thinking of writing a fairly simple tool (and otherwise using the
Texinfo system). So I'm doing /some/ of it my way.

(Oh, and actually I'm not a great fan of Frank Sinatra :-)

-- 
Nick Roberts

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Stephane Riviere]

>Does AdaDoc require that the description be before the declaration, or 
>can it be after too? I find it more natural to put it after, like this:

I fully agree with you, but today, you should do this way (put
comments before the declaration). 

Note I'm just the author of the Texinfo module. 

AdaDoc has been written by Julien Burdy and Vincent ... (sorry, I
remember only his surname).

>In my opinion, writing the description before the declaration breaks the 
>text flow in about the same way as top-posting does.

Again, you're right. I think it could be changed. Help needed. 

Anyway the AIDE documentation toolset proposed is already very
powerfull and save huge amount of stupid work while vastly increase
tech. doc. accuracy...

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

Re: Missing features in NaturalAdaBrowseDoc...

[Stephane Riviere]

Hi Lionel & all,

>Something that I would find useful for a tool like AdaBrowse, is the 
>ability to provide indexes on specific entries in the comments.

Although I've not tested it, using the Texinfo mode of AdaDoc, it
should be be very easy to do that, just including a texinfo tag index
inside an Ada comment.

Any texinfo tag may be inserted this way. I feel this is a powerfull
way to customize the AdaDocTexinfo mode...

No need to reinvent the wheel. No special tags to learn. Just the
standard Ada comment "--" and (only if needed) Texinfo tags (in order
to beautify docs or, like your need, to customize output).

With - to my taste - the benefit of a very professional printing
output :)

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

Re: Missing features in NaturalAdaBrowseDoc...

[Lionel Draghi]

Lionel Draghi wrote:
...
> My idea here was to indicate to the tool that some of those entries are 
> list. For example:
> -- 
> -- Requirements: req_100, req_200, req_300
> -- 
> 
> And then, having the tool generating a cross-reference between each item 
> in the various "Requirements" line and the sources
> 
> The index would be named "Requirements", and would contain:
> req_100 : hyperlink_to_file_1, hyperlink_to_file_6
> req_200 : hyperlink_to_file_1
> req_300 : hyperlink_to_file_1, hyperlink_to_file_7
> etc.

Another exemple (It was on my web page, I forgot it):

Let’s imagine there is a “Status:” field on each package (maybe 
automatically inserted by the configuration management system).  This 
status could be Not_Tested, Tested, Reviewed, or whatever.  It would be 
interesting to have a cross reference between Status and Packages, so 
that one can check quickly which packages are still Not_Tested.

-- 
Lionel

Re: Missing features in NaturalAdaBrowseDoc...

[Lionel Draghi]

Marc A. Criley wrote:
...
> Pass this suggestion on to AdaBrowse's maintainer, Thomas Wolfe; he may be
> willing to add it.
Maybe, but I feel guilty not doing it myself, I would feel more asking 
for it :-)

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Pylinius]

Nick Roberts wrote:
> Bj�rn Persson wrote:
> 
>> Hey Nick, do you like Frank Sinatra?
>>
>> You're writing your own operating system, your own compiler, your own 
>> windowing system, and now your own documentation system.
>>
>> "I did it myyy waaay."
> 
> 
> Hehe. Yes!
> 
> However, AdaOS is not a revolutionary design. Its design is based mainly
> on current OS orthodoxy. The ECLAT compiler is a new compiler, but the
> language (Ada) isn't. The windowing system (Titian) is in abeyance at the
> moment; I may never devlop it. And I'm not really writing a whole new
> documentation system (although I did think of doing so at one point); I'm
> only thinking of writing a fairly simple tool (and otherwise using the
> Texinfo system). So I'm doing /some/ of it my way.
> 
> (Oh, and actually I'm not a great fan of Frank Sinatra :-)
> 

This is performance art people. The guy has no intent on doing any of 
this stuff.

E. Buzz Miller: Now, the first one here is called Venus of Irbino, and 
it was painted in 1538 by a guy in Venice. And, this is for real, his 
name is spelled T-I-T-I-A-N. Titian! Honest to God!

http://snltranscripts.jt.org/77/77hmiller.phtml

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts]

Pylinius wrote:

> ...
> This is performance art people. The guy has no intent on doing any of 
> this stuff.

I am available for weddings and Bar Mitzvahs.

-- 
Nick Roberts


:-)

Re: Missing features in NaturalAdaBrowseDoc...

[Stephane Riviere]

>Considering your own documentation, I know that I can trust you for the 
>professional output.

Thanks, but to be honest, all the hard stuff is done by Texinfo.

>(yes, I am lazzy).

And you're right : this is why we love Ada, isn't it ? ;)

I've took a look to NaturalDocs last year, but I can't remember why
I've not selected it... 

>As far as I understand it, this doesn't prevent a beautiful output to be 
>generated.

What are the NaturalDoc  outputs formats ?

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

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Pascal Obry]

Bj�rn Persson <spam-away@nowhere.nil> writes:

> Hey Nick, do you like Frank Sinatra?
> 
> You're writing your own operating system, your own compiler, your own
> windowing system, and now your own documentation system.

I suspect Nick is an Highlander ;)

Pascal.

-- 

--|------------------------------------------------------
--| Pascal Obry                           Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--|              http://www.obry.org
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver wwwkeys.pgp.net --recv-key C1082595

Re: Missing features in NaturalAdaBrowseDoc...

[Lionel Draghi]

Stephane Riviere wrote:
...
> What are the NaturalDoc  outputs formats ?
I don't know, I just use html.

-- 
Lionel

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Marius Amado Alves]

Jacob, you apparently missed my post on this thread. You just had to 
reply to it with "I fully agree" :-)

Re: Missing features in NaturalAdaBrowseDoc...

[Stephane Riviere]

>> What are the NaturalDoc  outputs formats ?
>I don't know, I just use html.

After a quick tour on the natural docs website : HTML only. 

That's why I've rejected it, I guess. WeI also need _real_ printing
output for _real_ paper manuals...

However, The NaturalDocs main ideas are excellents.

Note it is very easy to create HTML output module but far more
difficult to create good PS or PDF output module (mainly due to the
physical page size restrictions).

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

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Steve]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2191 bytes --]

"Jacob Sparre Andersen" <sparre@nbi.dk> wrote in message
news:rlsfz4jdjuj.fsf@jacob.crs4.it...
> Steve wrote:
>
> > What I would like to see is a fancy programming editor that allows
> > you to include text, graphics, spreadsheets, etc., in comments.
>
> Why in the comments?
>
Because it makes the writing the tool simple, and minimizes on the amount of
garbage in the source code.

For example, the code might look something like

  ... some code...
end List_Finder;

-- M0410151846

procedure Optimize_Memory_Block( spender : Dirt_Cheap ) is
begin
   ... some more code ...


The editing tool would not show the number, just the comment.  The only time
you would see the number is if you were editing with some other tool (such
as a plain text editor).

Steve
(The Duck)

> But yes.  I have recently missed the possibility of having nice
> integrated mathematical analysis and source code implementing the
> result.
>
> > A way to do this is to maintain the source code as text with special
> > markers referencing the comments, and maintain the comments in a
> > separate file or database.
>
> Why not simply do it by keeping the linking completely separate from
> the source code, just using file names and completely specified Ada
> identifiers?  That will keep the source code nice, clean and readable
> for those who don't use the/a integration tool, and still allow exact
> cross linking between source code and non-source code objects.
>
> For production of documentation, <your preferred type-setting system>
> together with a method for referencing and extracting specific
> sections of Ada source code might do the job.
>
> For integrated editing in multiple formats, something more advanced is
> required, but please don't put non-plain text (including XML, texinfo,
> etc. marker) comments in source code I am going to read.  I actually
> prefer that there is only information that the compiler checks in the
> source code [1].
>
> Greetings,
>
> Jacob
>
> [1] Which makes comments parsed by a SPARK tool acceptable (if I get
>     one ;-)
> -- 
> �I'm perfectly happy with my current delusional system.�
>                                            -- Mirabel Tanner

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Jacob Sparre Andersen]

Steve wrote:
> Jacob Sparre Andersen wrote:
> > Steve wrote:

> > > What I would like to see is a fancy programming editor that
> > > allows you to include text, graphics, spreadsheets, etc., in
> > > comments.
> >
> > Why in the comments?
> >
> Because it makes the writing the tool simple, and minimizes on the
> amount of garbage in the source code.

I would rather say that it increases the amount of garbage in the
source code.

> For example, the code might look something like
[...]
> -- M0410151846

So you don't want to include other data formats in the code, but just
to link to them.  Why not just use the identifiers already available
in the source code for the links, instead of adding new ones?  (I
don't think I'm the first to suggest this)

Jacob
-- 
�Saving keystrokes is the job of the text editor, not the
 programming language.�                    -- Preben Randhol

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Steve]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 901 bytes --]

"Jacob Sparre Andersen" <sparre@nbi.dk> wrote in message
news:plsm8esaxn.fsf@sparre.crs4.it...
[snip]
>
> So you don't want to include other data formats in the code, but just
> to link to them.  Why not just use the identifiers already available
> in the source code for the links, instead of adding new ones?  (I
> don't think I'm the first to suggest this)
>

Unique markers are simpler, and independent of the code.  That is if you
change the code, the comment stays the same.

I also suggest that when you're using the editor that processes the comment
markers, that you don't see the markers, you just see the comments.  The
only time you would see these encoded markers is if you were looking at the
file with a different editor.

Steve
(The Duck)

> Jacob
> -- 
> �Saving keystrokes is the job of the text editor, not the
>  programming language.�                    -- Preben Randhol

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Bernhard Mulder]

> Anyway, I'll experiment with this a bit. To be honest, I suspect it
> would be easier to write my processing program in a langauge such as
> Python or Perl. Any recommendations? (Gawk?)

Since you already mentioned Python: you might be interested in Leo,
leo.sourceforge.net.

Leo is written in Python. It is and outliner and literal programming tool.

At the moment is does not support Ada directly, though that should
not be hard to add.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Jacob Sparre Andersen]

Marius Amado Alves wrote:

> I appreciate the requirement for some kind of master system
> containing both documentation and program elements.
> 
> The original Knuthian literate programming idea was not special
> comments in the source code but the other way around, source code
> fragments embedded in the text, which text being a piece of
> technical literature describing the system under construction.

Nice idea, but hard on the compiler, if you develop like I do (plenty
of compiles just to check the state of things and what's next on the
to-do list).

> It's not just a difference of perspective.
> 
> Documentation and source code are two very different things, and one
> should not step on the feet of the other.

Agreed.

> Overloading the source code with documentation elements ruins the
> source code.
> 
> Lately I've been putting all comments, if any, in the bottom of the
> source code file.

Why at the bottom and not at the top?

> And of course one should always write code in a way that it reduces
> the need for comments.

Aye!

> When some unit needs extensive commentary, the place for that is in
> a separate file.

Yes.  But I still think that putting a few words about the purpose of
a file in its beginning is a good practice.

> The link between documentation and source code items is based on the
> names of the source code entities.

Aye!

Jacob (who feels like he might as well have an AOL address ;-)
-- 
"Three can keep a secret if two of them are dead."

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Marius Amado Alves]

>>Lately I've been putting all comments, if any, in the bottom of the
                                ^^^^^^^^
                                 notes
>>source code file.
> 
> Why at the bottom and not at the top?

When you open a file for reference you want to look at the *significant* 
code, and usually at the start of it. A long comment at the top totally 
gets in the way. Compare:

   http://www.liacc.up.pt/~maa/files/g-io_aux.ads
   http://www.liacc.up.pt/~maa/files/g-io_aux-edited.ads

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Björn Persson]

Marius Amado Alves wrote:

> Compare:
> 
>   http://www.liacc.up.pt/~maa/files/g-io_aux.ads
>   http://www.liacc.up.pt/~maa/files/g-io_aux-edited.ads

The license block is too long, but otherwise I like the original version 
a lot better.

If there's anything special I need to be aware of about a particular 
function, then I want it to be noted in the most obvious place. I don't 
want to scroll down to check if perchance there might be a note about 
this function at the bottom of the file.

You also removed some important information: Where does the 
parameterless Get_Line read from? Which line does it get? Does it always 
return the whole line, from line break to line break, or could it be 
just part of the line in some cases? If so, which part and in which 
cases? We can assume that the second Get_Line reads from the file we 
pass to it, but does it otherwise work the same as the first Get_Line or 
are there any differences? The original file answers all of those questions.

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Jacob Sparre Andersen]

Marius Amado Alves wrote:

> When you open a file for reference you want to look at the
> *significant* code, and usually at the start of it. A long comment
> at the top totally gets in the way. Compare:
> 
>    http://www.liacc.up.pt/~maa/files/g-io_aux.ads
>    http://www.liacc.up.pt/~maa/files/g-io_aux-edited.ads

Unfair example.  Wasting space on copyright notices in every damned
text file is a horrible idea.  If you remove the copyright notice from
the beginning of the original version of the file, the first 10 lines
(well, actually the first five), show you useful information about the
overall idea with the file.

Jacob
-- 
"[...] *transfer* a bit of salary from the person who writes
 a bug to the person that finds a bug..." -- Keith Ray

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Marius Amado Alves]

> If there's anything special I need to be aware of about a particular 
> function, then I want it to be noted in the most obvious place. I don't 
> want to scroll down to check if perchance there might be a note about 
> this function at the bottom of the file.

Agreed. In this example there is nothing really special, but there are 
cases e.g. the infamous warning "the programmer is responsible for 
freeing this object". In those cases a *small* warning should be placed 
near the entities.

> You also removed some important information: Where does the 
> parameterless Get_Line read from? Which line does it get? Does it always 
> return the whole line, from line break to line break, or could it be 
> just part of the line in some cases? If so, which part and in which 
> cases? We can assume that the second Get_Line reads from the file we 
> pass to it, but does it otherwise work the same as the first Get_Line or 
> are there any differences? The original file answers all of those 
> questions.

All obvious answers, and so should be separate, if present at all.

1.  http://www.liacc.up.pt/~maa/files/g-io_aux.ads
2.  http://www.liacc.up.pt/~maa/files/g-io_aux-edited.ads
3.  http://www.liacc.up.pt/~maa/files/g-io_aux-notes.html

Note these are just fabricated outputs of an idealized master system for 
organizing source code with documentation. One viewable item can 
actually be the overloaded-with-comments source code file 1 which the 
tool keeps syncronized with 2 and 3. Then all views would be available 
for all tastes. (Hey, I just described a big part of my PhH hypothesis, 
Adaptive Hypertext :-)

The main (sub)thesis here was that the information required to make the 
necessary connections is there in the position of the notes in 1 and in 
the names of the formal entities. No visible special markers necessary.

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts]

Bernhard Mulder wrote:
>> Anyway, I'll experiment with this a bit. To be honest, I suspect it
>> would be easier to write my processing program in a langauge such as
>> Python or Perl. Any recommendations? (Gawk?)
> 
> Since you already mentioned Python: you might be interested in Leo,
> leo.sourceforge.net.
> 
> Leo is written in Python. It is and outliner and literal programming tool.
> 
> At the moment is does not support Ada directly, though that should
> not be hard to add.

Interesting you should mention Leo. I've already downloaded it to my
Windows XP machine, and tried to run it, without success.

I installed it using the downloaded installer (accepting all the
defaults). But when I try to run it (by clicking on the desktop shortcut)
it doesn't come up (it seems to run for a couple of seconds and then shut
down without ever showing a window). I already have Python 2.3.4
installed. Any suggestions welcome.

Anyway, undaunted, I'm having a go at writing my 'reverse tangle'
program in Ada, mainly as an exercise.

-- 
Nick Roberts

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Bernhard Mulder]

Nick Roberts wrote:
> Interesting you should mention Leo. I've already downloaded it to my
> Windows XP machine, and tried to run it, without success.
> 
> I installed it using the downloaded installer (accepting all the
> defaults). But when I try to run it (by clicking on the desktop shortcut)
> it doesn't come up (it seems to run for a couple of seconds and then shut
> down without ever showing a window). I already have Python 2.3.4
> installed. Any suggestions welcome.
> 
> Anyway, undaunted, I'm having a go at writing my 'reverse tangle'
> program in Ada, mainly as an exercise.
> 
The next thing I would recommend is to run Leo from a DOS window:
Open Dos, go to the src subdirectory of Leo and run leo.py.

If Leo comes up, fine.

Otherwise you should have a traceback which should give further clues.

Maybe you should send the follow-up to the discussion forums of Leo,
since this has nothing to do with Ada.

We can report back once you added support for Ada in Leo :-).

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Peter Hermann]

Bernhard Mulder <bwm@acm.org> wrote:
> Open Dos, go to the src subdirectory of Leo and run leo.py.

the dependency on python or dos is disturbing

-- 
--Peter Hermann(49)0711-685-3611 fax3758 ica2ph@csv.ica.uni-stuttgart.de
--Pfaffenwaldring 27 Raum 114, D-70569 Stuttgart Uni Computeranwendungen
--http://www.csv.ica.uni-stuttgart.de/homes/ph/
--Team Ada: "C'mon people let the world begin" (Paul McCartney)

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts]

Bernhard Mulder wrote:

> The next thing I would recommend is to run Leo from a DOS window:
> Open Dos, go to the src subdirectory of Leo and run leo.py.

Done it, and solved the problem! Thanks. I've left a message with a few
details in the Leo help forum.

> We can report back once you added support for Ada in Leo :-).

Hehe :-) I'll see.

-- 
Many thanks,
Nick Roberts

Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Bernhard Mulder]

I just checked in basic support for Ada.

> > We can report back once you added support for Ada in Leo :-).
> 
> Hehe :-) I'll see.
> 
> -- 
> Many thanks,
> Nick Roberts