The ability to approve posts to this moderated group has been restored,
by migrating the moderating software to a new host. Thank you to charter
moderator Dr Norman Ramsey, and to the Big8 board, for helping make this
possible.
MODERATOR INFO: comp.programming.literate
Article submission address:
cpl@newjersey.metaed.comModeration team contact:
cpl-board@newjersey.metaed.comTechnical team contact:
cpl-admin@newjersey.metaed.comCHARTER: comp.programming.literate
A forum for the discussion of literate programming.
(1) To share ideas, questions, experiences, and knowledge about the
reading and writing of literate programs or more generally the
presentation of code for human readers (e.g., prettyprinting).
(2) To discuss the merits of the currently existing literate-
programming and related tools.
(3) To discuss the design of new literate-programming and related
tools.
Moderation Policies:
Any posting that bears a plausible relationship to literate programming
is welcome. For example, discussion may include techniques for
prettyprinting code or other techniques for documenting design or code.
Advertising of tools or services related to literate programming (e.g.,
offers to review programs for pay) is considered acceptable. Other
advertising is unacceptable.
Moderation will primarily be automatic, by robo-moderator. Submissions
from regular contributors will be accepted immediately, without human
intervention. The human moderators will examine other submissions; any
submission that conforms to the newsgroup charter will be accepted, and
the person making the submission will be added to the list of regular
contributors (whose posts are automatically accepted). In the unlikely
event that a regular contributor sends a number of off-topic posts, that
person will be notified by a moderator and removed from the list of
regular contributors. The exact number of such posts required to trigger
this action is left to the good judgement of the moderators. The
moderators will continue to accept on-topic posts from such persons; no
person is ever to be prohibited from posting articles deemed acceptable
under this charter.
Background:
The rest of this section presents some background information to help
people identify what topics are related to literate programming.
In an article published in _The Computer Journal_ 27 (1984), 97-111,
Donald E. Knuth proposed a "literate" programming style:
I believe that the time is ripe for significantly better
documentation of programs, and that we can best achieve this by
considering programs to be works of literature. Hence, my title:
"Literate Programming."
Let us change our traditional attitude to the construction of
programs: Instead of imagining that our main task is to instruct a
*computer* what to do, let us concentrate rather on explaining to
*human beings* what we want a computer to do.
The practitioner of literate programming can be regarded as an
essayist, whose main concern is with exposition and excellence of
style. Such an author, with thesaurus in hand, chooses the names of
variables carefully and explains what each variable means. He or she
strives for a program that is comprehensible because its concepts
have been introduced in an order that is best for human
understanding, using a mixture of formal and informal methods that
reinforce each other.
There is reasonable (but not unanimous) consensus that a literate-
programming system can be characterized by the following properties:
- The compilable program and the publishable documentation should be
generated *automatically* from a *single* source.
- The program can be presented in the order that is best for human
understanding, regardless of any requirements of the programming
language.
- The program should be automatically indexed and cross-referenced.
- The program may be formatted or prettyprinted in a way that makes
it especially readable.
Existing literate-programming systems support a wide range of
programming languages and documentation systems. Specialized tools have
been written for Ada, Awk, C, C++, Fortran, Modula-2, Modula-3, Pascal
and Scheme, and there are language-independent tools exist that support
almost any programming language (including Perl, sh, and make).
Documentation systems supported include HTML, TeX, Troff, and Word for
Windows.
…