steve%brl-bmd@sri-unix.UUCP (03/01/84)
From: Stephen Wolff <steve@brl-bmd>
Artificially intelligent it's not, and not even fancy; but there are
folks hereabouts that use the UNIX tools SCCS (or RCS) to do documentation
of various sorts. Although intended for managing the writing, evolving and
maintaining of large software packages, they can't tell C from Fortran from
straight English text and they will quite cheerfully maintain for you the
update/revision tree in any case.
I should imagine with a bit if thought you could link your code AND
documentation modules and manage 'em both simultaneously and equitably.rpw3@fortune.UUCP (03/09/84)
#R:sri-arpa:-1722400:fortune:21500009:000:1999
fortune!rpw3 Mar 8 17:21:00 1984
Versions of DEC-10 RUNOFF later than about 1977 had a feature called
the "select" character set, which was a hook to the commenting
conventions of your favorite programming lanuages so that RUNOFF input
could be buried in comments in the code. RUNOFF knew enough to look at
the extension of the source file and set the "select" set from that to
the normal defaults. Typically, <comment-char><"+"> turned stuff on,
and <comment-char><"-"> turned it off.
By using the equivalent of "-ms" displays (.DS/.DE) (which I have
forgotten the RUNOFF version of), you could actually include slected
pieces of the code in the document.
It really helped if the language had a "comment through end of line"
character, though you can make do (as in "C") by using some other
character at the front of each line of a multi-line comment.
An example in "C", written as if nroff knew about this feature and
had been told that the "select" char was "*":
/*+
*.SH
*Critical Algorithms
*.LP
*The Right_One macro requires two's-complement arithmetic,
*as it uses the property of the rightmost "one" remaining
*invariant under negation:
*.DS B
* Right_One(X) = (-X) AND (NOT X)
*.DE
*where "-X" is negation (unary minus) and "AND" and "NOT"
*are full-word bit-wise logical operators.
*-
*/
#define Right_One(x) ((-(x))&(~(x)))
This turned out to be very useful in keeping the documentation up-to-date
with the code. In addition, RUNOFF had a /VARIANT:xyz option that allowed
you to have ".IF xyz", etc., in your document, so that one file could
contain the "man" page (.HLP file), the documentation (.DOC), and the
program logic manual (.PLM). You specified the variant you wanted when
you ran it off. RUNOFF itself was the classic example: the source contained
all of the end-user documentation (a bit extreme, I admit!).
Rob Warnock
UUCP: {sri-unix,amd70,hpda,harpo,ihnp4,allegra}!fortune!rpw3
DDD: (415)595-8444
USPS: Fortune Systems Corp, 101 Twin Dolphin Drive, Redwood City, CA 94065