Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts <nick.roberts@acm.org>]

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