Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Stephen Leake <stephen_leake@acm.org>]

"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