Subj : Re: Doc/noDoc? (was: CV, work-history, 91C, CompSci?, Applet? ...)
To   : comp.programming,comp.software-eng
From : blmblm
Date : Thu Sep 15 2005 11:21 am

In article <REM-2005sep14-001@Yahoo.Com>,
Robert Maas, see http://tinyurl.com/uh3t <rem642b@Yahoo.Com> wrote:
>> From: Chris Hills <c...@phaedsys.org>
>> There is a system called Literate Programming where the
>> documentation and the source are the same thing. ...
>> It never caught on. Started out using Pascal and TeX

[ snip ]

>Given that TeX is rather inscrutable, since it's based not on the
>nested structure of math expressions and the semantic meaning of the
>atoms, but rather on the manual shifts to superscript and subscript
>that would be present in a linearized sequence of typewriter actions
>and the particular font used to represent each atom, how can TeX by
>itself (without compiling it to printable format) be acceptable
>documentation?
>
>Now if comments in the source file contained directives which were
>compiled to produce separate documentation, as is the case with
>JavaDoc, that would be something entirely different.

A Google search for Knuth and "literate programming" turns up some
information and examples.

Apparently the idea is to store both program source code and
documentation in "master source" form (which mixes TeX commands
and source code) and then extract from it both documentation and
compilable code.

So it's not exactly like Java's Javadoc system, but it's sort of
along the same lines.  (Sort of -- with the Java system, the "master
source" is compilable source code, which apparently is not the case
with Knuth's system.)

Sounds interesting.  I wonder if it could still catch on if someone
developed a GUI front end for it.  Judging by the example I skimmed,
few people now would be able to write the "master source" (lots of
TeX) without some help, but maybe .... ?  Idle speculation, mostly.

(As for whether TeX expresses semantic structure -- it can be used
as you describe, or one can define macros that are more meaningful
for the task being done.  LaTeX is an example of such a set of 
macros (or maybe "sets of macros" is more apt).)

[ snip ]

-- 
| B. L. Massingill
| ObDisclaimer:  I don't speak for my employers; they return the favor.

.