lotus

previous page: 14.2. Ramsey (Other Opinions about Literate Programming)
  
page up: Literate Programming FAQ
  
next page: 14.3. My (Dave Thompson's) Experience (Other Opinions about LiterateProgramming)

3. typeset documentation, especially diagrams and mathematics




Description

This article is from the Literate Programming FAQ, by David B. Thompson thompson@shelob.ce.ttu.edu with numerous contributions by others.

3. typeset documentation, especially diagrams and mathematics


Flexible order of elaboration means being able to divide your source
program into chunks and write the chunks in any order, independent of
the order required by the compiler. In principle, you can choose the
order best suited to explaining what you are doing. More subtly, this
discipline encourages the author of a literate program to take the
time to consider each fragment of the program in its proper sphere,
e.g., not to rush past the error checking to get to the ``good
parts.'' In its time and season, each part of the program is a good
part. (This is the party line; your mileage may vary.)

I find the reordering most useful for encapsulating tasks like input
validation, error checking, and printing output fit for humans --- all
tasks that tend to obscure ``real work'' when left inline. Reordering
is less important when using languages like Modula-3, which has
exceptions and permits declarations in any order, than when using
languages like C, which has no exceptions and requires declaration
before use.

Automatic support for browsing means getting a table of contents,
index, and cross-reference of your program. Cross-reference might be
printed, so that you could consult an index to look up the definition
of an identifier `foo'. With good tools, you might get a printed
mini-index on every page if you wanted. Or if you can use a hypertext
technology, cross-reference might be as simple as clicking on an
identifier to reach its definition.

Indexing is typically done automatically or `semi-automatically', the
latter meaning that identifier definitions are marked by hand.
Diligently done semi-automatic indexes seem to be best, because the
author can mark only the identifiers he or she considers important,
but automatic indexing can be almost as good and requires no work.
Some tools allow a mix of the two strategies.

Some people have applied literate-programming tools to large batches
of legacy code just to get the table of contents, index, and cross-
reference.

I don't use diagrams and mathematics very often, but I wouldn't want
to have to live without them. I have worked on one or two projects
where the ability to use mathematical formulae to document the program
was indispensible. I also wouldn't like to explain some of my
concurrent programs without diagrams. Actually I write almost all of
my literate programs using only sections headers, lists, and the
occasional table.

>Wouldn't it be easier to do one's literate programming using
>a wysiwyg word processor (e.g. Word for Windows) and
>indicate what is source code by putting it in a different
>font?

The data formats used in wysiwyg products are proprietary, and they
tend to be documented badly if at all. They are subject to change at
the whim of the manufacturer. (I'll go out on a limb and say there are
no significant wysiwyg tools in the public domain. I hope the Andrew
people will forgive me.) These conditions make it nearly impossible to
write tools, especially tools that provide automatic indexing and
cross-reference support. The CLiP people have a partial solution that
works for tools that can export text --- they plant tags and
delimiters throughout the document that enable the reordering
transformation (``tangling'').

People use TeX, roff, and HTML because free implementations of these
tools are widely available on a variety of platforms. TeX and HTML
are well documented, and TeX and roff are stable. TeX is the most
portable. I think I have just answered the FAQ ``how come all these
tools use TeX, anyway?'' :-)

Norman Ramsey

 

Continue to:













TOP
previous page: 14.2. Ramsey (Other Opinions about Literate Programming)
  
page up: Literate Programming FAQ
  
next page: 14.3. My (Dave Thompson's) Experience (Other Opinions about LiterateProgramming)