Re: Literate Programming in Ada, AdaDoc, AdaBrowse

["Steve" <nospam_steved94@comcast.net>]

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