>> Theoretically, COBOL was intended to be self documenting. The
>> choice of
>> reserved words and the variable naming convention were
>> intended to make
>> comments unnecessary (not to imply that it worked).

> It did work, but only at the level it was intended to work for:
> individual statements and expressions. But understanding a single
> statement is only a small problem: understanding what a whole section
> does is more difficult, and understanding why it does that is even
> harder. A program can only approach being self-documenting when the
> language has abstractions for the higher levels, and allows these levels
> to be named appropriately.

> Wouter van Ooijen

This problem has been addressed by the method called "structured
documentation" or "literate programming" introduced by Prof. Donald
Knuth of Stanford. His original method, called WEB, was meant for
Pascal and was followed by CWEB for C. Additional versions followed
for other languages, with a generic version called Funnelweb which is
available free on the Internet.
The idea is to combine the executable code and the documentation in
the same source file. Processing this file with one program extracts the
executable source, ready to be compiled or assembled. Using a
different program formats the documentation for printing in TeX so
that a "pretty printed" output file can be produced.
The novel idea here is that the executable code is not presented in one
monolithic listing but rather as short blocks, each of which has
paragraphs of explanatory material accompanying it. The code extraction
program treats these blocks as text macros (in the word processor sense)
and puts them together to make the input to the compiler. The documenation
preparation program adds formatting information to the entire file so that
the blocks are numbered and cross referenced, the code sections are printed
with keywords in bold face, variables names in italic, comments uniformly
indicated, etc. Once you have read a CWEB formatted documentation file, you
may find it difficult to go back to looking at the old style listings.
For a discussion of literate programming , see the discussion at

www.ross.net/funnelweb

You can also download Funnelweb there. The various software for implementing
literate programming is specific to the language being documented, so a generic
program like Funnelweb which can handle all languages is especially useful, especially
since it is the only system I know of which can handle PIC assembly code. Funnelweb
even produces HTML output (as well as TeX)  for the documentation, so you don't need
a TeX system to print the output.

John Power

--
http://www.piclist.com hint: PICList Posts must start with ONE topic:
[PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads