From ankh.iia.org!uunet!MathWorks.Com!news2.near.net!bloom-beacon.mit.edu!senator-bedfellow.mit.edu!faqserv Sun Aug 28 10:24:46 1994
Path: ankh.iia.org!uunet!MathWorks.Com!news2.near.net!bloom-beacon.mit.edu!senator-bedfellow.mit.edu!faqserv
From: thompson@sun1.coe.ttu.edu
Newsgroups: comp.programming.literate,comp.answers,news.answers
Subject: comp.programming.literate FAQ
Supersedes: <literate-programming-faq_776749825@rtfm.mit.edu>
Followup-To: comp.programming.literate
Date: 28 Aug 1994 13:40:17 GMT
Organization: Texas Tech University, Lubbock, Texas, USA
Lines: 1543
Approved: news-answers-request@MIT.Edu
Distribution: world
Expires: 26 Sep 1994 13:39:58 GMT
Message-ID: <literate-programming-faq_778081198@rtfm.mit.edu>
Reply-To: thompson@sun1.coe.ttu.edu
NNTP-Posting-Host: bloom-picayune.mit.edu
Summary: Literate Programming FAQ--general introduction to the concepts
         of literate programming and the tools available to write
         literate programs.
X-Last-Updated: 1994/08/23
Originator: faqserv@bloom-picayune.MIT.EDU
Xref: ankh.iia.org comp.programming.literate:546 comp.answers:3359 news.answers:10115

Archive-name: literate-programming-faq
Last-modified: 1994/08/23
Version: 1.1.10


Welcome to the Literate Programming Frequently Asked Questions List
-------------------------------------------------------------------

This version was created Tuesday, August 23, 1994, and should considered
stale after 90 days.  Information contained in this document is the best
available at preparation.  The original file was dated October 15, 1993
(just for historical purposes).

Disclaimer: "This FAQ is presented with no warranties or guarantees of
ANY KIND including correctness or fitness for any particular purpose.
The author of this document has attempted to verify correctness of the
data contained herein; however, slip-ups can and do happen.  If you use
this data, you do so at your own risk."

Copyright 1993, 1994 David B. Thompson.  All rights reserved worldwide.
Permission is granted to copy this document for free distribution so
long as it remains intact and unmodified.  For other arrangements,
contact the author/maintainer via email: thompson@sun1.coe.ttu.edu.

What's New?
-----------

+ Add Fold2Web entry.
+ Correct noweb.el entry.  (Thanks Dominique!)
+ Update nuweb.el entry.
+ Update SchemeWEB entry.
+ Update WWW and literate programming entry.
+ Update c2cweb entry.


= ======================================================================

* Introduction or "What's this all about?"
------------------------------------------

This document is for new and experienced users of literate programming
tools.  The purpose is to explain the concept of literate programming and
to provide a resource for locating files of interest to literate
programmers and those interested in literate programming.

The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list
is maintained by Dave Thompson, who can be reached at:

    thompson@sun1.coe.ttu.edu     * Preferred mailing address for FAQ
                                    related comments/questions.
    wqdbt@ttacs1.ttu.edu          * Forwarded to my pc.

Comment and constructive criticism is welcome.  Direct flames to
/dev/null (or > nul if you're a msdos user! ;-)  If you find an error,
please report it.  I'm particularly interested in establishing the
locations of generally available literate programming tools.  If you are
the author of such a tool and wish to have it included in this list,
please send email.

Please note this is a work-in-progress.  It is *not* complete, and
probably will not be complete for some months.  Nevertheless, the
information contained herein may be useful to some.  Use it as it is
intended.

- ----------------------------------------------------------------------

- Typography
------------

Major sections of the FAQ are divided by double lines (====).  Minor
sections and other divisions are separated by single lines (----).
Major topics use a "* " as a leader.  Minor topics use a "- " as a
leader.  This should simplify searching for topics.


= ======================================================================

Table of Contents:
------------------

* Introduction, or "What's this all about?"
    - Typography
* How do I get the FAQ?
    - Literate Programming FAQ
    - FWEB FAQ
* Is there a newsgroup?  (The comp.programming.literate newsgroup)
* What internet nodes are of interest to literate programmers?
* What is literate programming?
* How do I begin literate programming?
* What literate programming tools are available and where are they?
    - APLWEB
    - AWEB
    - CLiP
    - CWEB
    - FunnelWeb
    - FWEB
    - IMPACT
    - lit2x
    - Literate Programmer's Workshop (LPW)
    - MapleWEB
    - MWEB (Schrod/Detig)
    - MWEB (Sewell)
    - noweb
    - nuweb
    - ProTeX
    - RWEB
    - SchemeWEB
    - Spidery WEB
    - WEB
    - WinWordWEB
* Are there other tools I should know about?
    - C2LaTeX
    - c2cweb
    - c2man
    - cnoweb
    - Fold2web
    - FunnelWeb mode
    - noweb.el
    - nuweb.el
    - TIE
    - Web mode
* What other resources are available?
    - World Wide Web
    - TeX Resources
    - Virtual Coursework
* Are there any code examples?
    - Examples included with developer's tools
    - Cameron Smith's KR-CWEB
    - Stanford GraphBase
* Bibliographies.
* How to anonymously ftp.
* Acknowledgements.
* End notes.


= ======================================================================

* How do I get the FAQ?
-----------------------

- Literate Programming FAQ
--------------------------

You have many ways to get a current copy of this FAQ.  One is to use
anonymous ftp (if you don't know how, see a later section in this FAQ)
to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites
or the Literate Programming Archive and retrieve a copy of the file.
Open an ftp connection to one of the CTAN sites and retrieve the file:

    help/LitProg-FAQ

(For more information on CTAN and the literate programming archive, see
the section below entitled "Internet Nodes of Interest to Literate
Programmers.")

An alternative is to use the fileserver at Sam Houston State University
(SHSU).  Send a message to FILESERV@SHSU.EDU and include in your
message:

    SENDME LITPROG.FAQ

The file server will forward a copy of the file to you via email.


- ----------------------------------------------------------------------

- FWEB FAQ
----------

Marcus Speh <marcus@x4u.desy.de> maintains the FWEB FAQ.  The current
version number is 1.29.  It can be retrieved in the same way as this
FAQ; either by anonymous ftp or through the SHSU file server.  On the
SHSU server, the file name is FAQ.FWEB.  Invoke your ftp software, open
a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory
FAQ, and transfer the file FAQ.FWEB.

Alternatively, send a message to the file server, FILESERV@SHSU.EDU, and
include the following text in a one line message:

    SENDME FAQ.FWEB

The file server will send the current version of the file via email.

The FWEB FAQ exists in various formats, including HyperText (see other
resources below). In Europe, the complete distribution can also be
obtained from ftp.desy.de [131.169.10.115] in directory
/pub/faq/web/fweb/.  It is also available from the literate programming
archive (LPA) in the directory LPA/Documentation/faq/fweb (see the
references to LPA below for more information).

Also, Marcus Speh is looking for someone willing to take over the FWEB
FAQ.  The text of his email message follows...
  "Please add to the FWEB FAQ the note that I am looking for someone
  to take the maintenance of the FAQ over - I am ready to assist in
  any way whatsoever, including tons of mail, notes for
  v1.29->v1.30, Texinfo sources, a WWW server and Hypertextification
  etc."
If you're interested, send mail to marcus@x4u2.desy.de and express your
willingness to serve.

= ======================================================================

* Is there a newsgroup?
-----------------------

One of the most important resources is the literate programming
newsgroup, comp.programming.literate.  You can read this newsgroup using
your standard reader.  Altenatively, the newsgroup is gated to a mailing
list hosted by George Greenwade and Sam Houston State University.  You
can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU, and
include in the message one line of text:

    SUBSCRIBE LITPROG  "your name in quotes"

The list is unmoderated; messages sent to litprog@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.programming.literate.

Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory litprog.


= ======================================================================

* What internet nodes are of interest to literate programmers?
--------------------------------------------------------------

The principal nodes of interest to literate programmers are the Literate
Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX
Archive Network).

The Literate Programming Archive (LPA) is:

  Node:       ftp.th-darmstadt.de [130.83.55.75]
  Directory:  programming/literate-programming
  Notes:      Fastest response during off-U.S. [yep] business hours.

The CTAN sites are:

ftp host             IP            CTAN root    Institution and Sponsor
-------------------------------------------------------------------------
ftp.tex.ac.uk   134.151.79.32     pub/archive  Aston Univ./UK TeX U.G.
ftp.dante.de    129.206.100.192   soft/tex     DANTE e.V.
ftp.shsu.edu    192.92.115.10     tex-archive  Sam Houston State Univ.

Other nodes and directories of interest include:

  Node:       niord.shsu.edu [192.92.115.8]
  Directory:  various (do some snooping!)
  Notes:      Has a gopher server.

  Node:       ftp.desy.de [131.169.10.115]
  Directory:  pub/web. Various documents, samples, and the FWEB FAQ.
  Notes:      Has a www server, http://info.desy.de:80/


= ======================================================================

* What is Literate Programming?
-------------------------------

Literate programming is the combination of documentation and source
together in a fashion suited for reading by human beings.  In fact,
literate programs should be enjoyable reading, even inviting!  (Sorry
Bob, I couldn't resist!)  In general, literate programs combine source
and documentation in a single file.  Literate programming tools then
parse the file to produce either readable documentation or compilable
source.  The WEB style of literate programming was created by D.E. Knuth
during the development of his TeX typsetting software.

All the original work revolves around a particular literate programming
tool called WEB.  Knuth says:

     The philosophy behind WEB is that an experienced system
     programmer, who wants to provide the best possible
     documentation of his or her software products, needs two
     things simultaneously: a language like TeX for formatting,
     and a language like C for programming.  Neither type of
     language can provide the best documentation by itself; but
     when both are appropriately combined, we obtain a system
     that is much more useful than either language separately.

     The structure of a software program may be thought of as a
     web that is made up of many interconnected pieces.  To
     document such a program we want to explain each individual
     part of the web and how it relates to its neighbours. The
     typographic tools provided by TeX give us an opportunity to
     explain the local structure of each part by making that
     structure visible, and the programming tools provided by
     languages such as C or Fortran make it possible for us to
     specify the algorithms formally and unambigously. By
     combining the two, we can develop a style of programming
     that maximizes our ability to perceive the structure of a
     complex piece of software, and at the same time the
     documented programs can be mechanically translated into a
     working software system that matches the documentation.


Another author (Eric W. van Ammers) wrote me a short article treating
his opinions on literate programming.  The text follows:


First observation on LP

    About 90% of the disussion on this list is about problems with
applying some WEB-family member to a particular programming language or
a special documentation situation. This is ridiculous, I think. Let me
explain shortly why...

Lemma 1:
    I have proposed for many years that programming has nothing to do
with programming langauges, i.e. a good programmer makes good programs
in any language (given some time to learn the syntax) and a bad
programmer will never make a good program, no matter the language he
uses (today many people share this view, fortunately).

Lemma 2:
    Literate Programming has (in a certain way not yet completely understood)
to do with essential aspects of programming.

Conclusion 1:
    A LP-tool should be independent of programming language.

Lemma 3:
    It seems likely that the so called BOOK FORMAT PARADIGM [ref. 1] plays an
important role in making literate programs work.

Lemma 4:
    There are very many documentation systems currently being used to produce
documents in the BOOK FORMAT.

Conclusion 2:
    A LP-tool should be independent of the documentation system that the
program author whishes to use.

My remark some time ago that we should discuss the generic properties of
an LP-tool was based on the above observation.


References:

[1] Paul W. Oman and Curtus Cook. Typographical style is more than cosmetic.
    CACM 33, 5, 506-520 (May 1990)


Second observation on LP

    The idea of a literate program as a text book should be extendend
even further. I would like to see a literate program as an (in)formal
argument of the correctness of the program.
    Thus a literate program should be like a textbook on mathematicics.
A mathematical textbook explains a theory in terms of lemma and
theorems. But the proofs are never formal in the sense that they are
obtaind by symbol manipulation of a proof checker. Rather the proofs are
by so called "informal rigour", i.e. by very precise and unambiguous
sentences in a natural language.

Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				              E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			            voice:	+31 (0)8370 83356/84154
The Netherlands				              fax:	  +31 (0)8370 84731


= ======================================================================

* How do I begin literate programming?
--------------------------------------

A recommended book is D.E. Knuth's collection of articles (1992)
"Literate Programming," Center for the Study of Language and
Information, Stanford University, ISBN 0-937073-80-6 (pbk).  This book
gives insight into Knuth's thoughts as he developed the web system of
literate programming (and TeX for typesetting).  It does not document
methods for literate programming.

A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate
Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk).
This book focuses on using Knuth's web system.

Some talk exists in the newsgroup/mailing list for a Usenet University
course in literate programming.  I'm sure discussion of this topic will
be welcomed.  If you are interested, please participate.


= ======================================================================

* What literate programming tools are available and where are they?
-------------------------------------------------------------------

A significant number of tools for literate programming are available.
Most have been ported from their original systems, so support multiple
computer platforms.  If you are the developer of such a tool, and would
like to make the software freely available, please send me email and
I'll reply with a form (like those below) for you to fill in.  (Or
short-circuit the process and kludge a form from below. :-)


- ----------------------------------------------------------------------

- APLWEB
--------

Developer:      Christoph von Basum <CvB@erasmus.hrz.uni-bielefeld.de>
Version:        Unknown
Hardware:       MSDOS
Languages:      IBM APL2 and STSC APL
Formatter:      Plain TeX
Availability:   Anonymous ftp from:
                  LPA:/apl
                  watserv1.uwaterloo.ca:/languages/apl/aplweb
Readme:         Unknown

Description:    None available.

Support:        Unknown

Note: The status of this particular package is unknown.


- ----------------------------------------------------------------------

- AWEB
------

Developer:      Unknown
Version:        Unknown
Hardware:       Unknown
Languages:      Ada
Formatter:      Unknown
Availability:   Anonymous ftp from:
                  LPA:/ada/web
Readme:         Unknown

Description:    None available

Support:        Not supported.


- ----------------------------------------------------------------------

- CLiP
------

Developer:      E.W. van Ammers and M.R. Kramer
Version:        Unknown
Hardware:       Vax/VMS, Unix, and MS-DOS
Languages:      Any programming language.
Formatter:      Any formatter (TeX, LaTeX, Troff, Runoff, etc) or any
                wordprocessor including WYSIWYG systems (Word Perfect,
                Win Word, Ami Pro, Word, etc.)
Availability:   Anonymous ftp from:
                  sun01.info.wau.nl:/CLIP/ms_dos    MS-DOS version
                  sun01.info.wau.nl:/CLIP/vax_vms   VAX/VMS version
                  CTAN:/web/clip
                  LPA:/machines/ms-dos
                  LPA:/machines/vax
Readme:         With bundle above

Description:

  CLiP does not use explicite commands to perform the extraction
  process. Rather it recognizes pseudostatemens written as comments in
  the programming language in question. CLiP distinguishes
  pseudostatments from ordinary comments because the former comply with
  a a particular style. This style can be adjusted to suit virtually any
  programming language. The CLiP approach to LP makes the system
  extremely versatile. It is independent of programming language and
  text processing environment. We designed CLiP to be compatible with
  hypertext systems as well but we have not yet experimented with this
  form of documentation.

  Features:
  + CLiP imposes virtually no limitations on the text-processing system
    used to produce the documentation. If the text-processor supports
    these items you can
    + structure the documentation according to your own taste.
    + include drawings, pictures, tables etc.
    + disclose your documentatio my means of X-ref tables, Indexes,
      Table of contents, Table of tables, Table of figures, etc.
    + typeset the documented code.
  + Extracts any number of modules from a maximum of 64 source files.
  + No pretty-printing. Code from the source files is copied "as is" to
    the module.
  + Appearance of code segments in the documentation matches those of
    the modules to ease the identification of code segements.
  + Supports partially specified data types.
  + Comprehensive user manual (preliminary version) and technical
    description.
  - No automatic generation of a X-ref table for program identifiers.

Support:        Bugs, problems and assistance by e-mail:
                  ammers@rcl.wau.nl


- ----------------------------------------------------------------------

- CWEB
------

Developer:      Silvio Levy and D.E. Knuth
Version:        3.0
Hardware:       Unix systems (dos and amiga ports available)
Languages:      C and C++
Formatter:      Plain TeX and LaTeX.
Availability:   Anonymous ftp from:
                  labrea.stanford.edu:/pub/cweb
                  LPA:/c.c++
                  CTAN:/web/c_cpp/cweb
                  DOS version in CTAN:/web/c_cpp/cwb30p8c
                  DOS version in LPA:/machines/ms-dos
                  Amiga version CTAN:/web/c_cpp/AmigaCWEB
                  Mac port of CTANGLE in LPA:/machines/mac
                  LaTeX support in LPA:/c.c++
Readme:         Bundled with above
Description:    No description provided.
Support:        Bugs to levy@math.berkeley.edu

Note:  A fork of CWEB 3.x was developed by Marc van Leeuwen
<M.van.Leeuwen@cwi.nl> which implements several changes to CWEB.  It is
available for anonymous ftp from ftp.cwi.nl:pub/cweb.  The principle
changes are:
  - Scans include files for typedef definitions
  - Grammar and formatting rules are well separated, allowing for
    run-time selection of a rule set (via command line option)
  - New manual.


- ----------------------------------------------------------------------

- FunnelWeb
-----------

Developer:      Ross N. Williams: ross@guest.adelaide.edu.au
Version:        Unknown
Hardware:       MSDOS, Mac, VMS, Sun.  Other ports reported.
Languages:      No restrictions.
Formatter:      Plain TeX for printing.  Otherwise, no restrictions.
Availability:   Anonymous ftp from:
                  CTAN:/web/funnelweb
                  LPA:/independent
                  ftp.adelaide.edu.au:/pub/funnelweb
Readme:         With bundle above.

Description:

  FunnelWeb is a production-quality literate-programming tool that
  emphasises simplicity and reliability. Everything about FunnelWeb,
  from the simplicity of its language to the comprehensive tutorial in
  the user's manual, has been designed to make this as simple, as
  practical, and as usable a tool as possible.

  Features:
     + Provides a simple macro preprocessor facility.
     + Can produce typeset documentation.
     + Runs on Sun, VMS VAX, Macintosh, PC, and others.
     + Portable C source code distributed under GNU licence.
     + Comprehensive user's manual including tutorial.
     + Programming-language independent.
     + Can generate multiple output files.
     + Allows complete control over the output text.
     + Regression test suite with over 200 tests.
     + Fully worked example (in /pub/funnelweb/examples).
     - Requires TeX to produce typeset documentation.
     - Typesets program code using TT font only.

Support:  No formal support available.  Mailing list maintained with
          about 50 subscribers.  Informal assistance available from
          mailing list.


- ----------------------------------------------------------------------

- FWEB
------

Developer:      John A. Krommes <krommes@princeton.edu>
Version:        1.30a (1.40 for the experienced, patient, and brave)
Hardware:       Unix, VMS, and DOS platforms (anything with ANSI C)
Languages:      C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a
          		  language-independent mode.
Formatter:      Plain TeX and LaTeX.
Availability:   Anonymous ftp from:
                  ftp.pppl.gov:/pub/fweb
                  CTAN:/web/fweb
                  LPA:/fweb
                  DOS version in LPA:/machines/ms-dos
Readme:         In bundle with above.

Description:

  It also has a well-developed user's manual and its own FAQ (see
  above).  Beginning with 1.40, documentation is maintained in gnu
  texinfo format.  It runs on most platforms: VMS, PC, UNIX, and pretty
  much anything that the GNU C compiler (GCC) is supported for.

  Features:

   + Processes multiple languages during a single run (so one can mix C
     and Fortran, for example).
   + Language-independent mode (v1.40).
   + Ability to turn off pretty-printing (v1.40).
   + Built-in Ratfor translator.
   + Built-in macro preprocessor (closely follows ANSI C, with
     extensions).
   + A style file that allows the user to adjust many parameters and
     behavior patterns of FWEB.
   + Various operator-overloading features that provide additional
     pretty-printing capabilities to languages such as C++ and
     Fortran-90.
   + Numerous miscellaneous features and command-line options.

Support:        Bug reports and suggestions to krommes@princeton.edu


- ----------------------------------------------------------------------

- IMPACT
--------

Developer:      Timothy Larkin, from Levy/Knuth CWEB 3.1
Version:        1.0
Hardware:       Macintosh; requires AppleEvents.
Languages:      C, C++
Formatter:      TeX
Availability:   CTAN archives
Readme:         A short readme file is included in the SEA archive.

Description:

  IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as
  a foreground program, tangling files selected from the Mac File
  Picker. Or it can operate in the background, tangling files in
  response to odoc events sent by other applications, such as editors.

Support:

  I welcome any reports of bugs. The product will be updated as new
  versions of the CWEB appear. Other features may be added as users
  suggest them.


- ----------------------------------------------------------------------

- lit2x
-------

Developer:      Unknown
Version:        Unknown
Hardware:       Unknown
Languages:      Unknown
Formatter:      Unknown
Availability:   Anonymous ftp from:
                  LPA:/independent
Readme:         Unknown
Description:    None available
Support:        Unknown


- ----------------------------------------------------------------------

- Literate Programmer's Workshop (LPW)
--------------------------------------

Developer:      Norbert Lindenberg
Version:        1.1
Hardware:       Apple Macintosh
Languages:      C++, Object Pascal & others
Formatter:      self-contained WYSIWYG system
Availability:   Anonymous ftp from:
                  LPA:/machines/mac
                  CTAN:/web/lpw
                  ftp.apple.com:/pub/literate.prog
Readme:         With bundle above.  Also comes with 38-page manual.

Description:

  The Literate Programming Workshop is an environment for the integrated
  development of program source text and documentation in combined
  documents. It consists of a WYSIWYG word processor based on a style
  sheet approach, a mechanism to extract parts of the text in a
  document, and a project management system that handles multi-document
  projects. The system is designed to be used in conjunction with the
  Macintosh Programmer's Workshop: it prepares raw source text for the
  MPW compilers, accepts MPW error messages, and shows them in the
  context of the original documents. Automatic indexing and hypertext
  features allow for easy access to both source text and documentation.

  LPW is shareware.

Support:        Bugs, problems, and questions to lpw@aol.com.


- ----------------------------------------------------------------------

- MapleWEB
----------

Developer:      Unknown
Version:        Unknown
Hardware:       Unknown
Languages:      Maple
Formatter:      Unknown
Availability:   Anonymous ftp from:
                  LPA:/maple
Readme:         Unknown
Description:    None
Support:        Unknown


- ----------------------------------------------------------------------

- MWEB (Schrod/Detig)
---------------------

Developer:      Joachim Schrod
Version:        Unknown
Hardware:       Unknown
Languages:      Modula-2
Formatter:      Unknown
Availability:   Anonymous ftp from:
                  LPA:/modula-2
Readme:         Unknown
Description:    None
Support:        Not supported.


- ----------------------------------------------------------------------

- MWEB (Sewell)
---------------

Developer:      Sewell
Version:        Unknown
Hardware:       Unknown
Languages:      Modula-2
Formatter:      Unknown
Availability:   Anonymous ftp from:
                  LPA:/modula-2
Readme:         Unknown
Description:    None
Support:        Not supported.


- ----------------------------------------------------------------------

- noweb
-------

Developer:      Norman Ramsey <norman@bellcore.com>
Version:        2.6
Hardware:       Unix and DOS platforms.
Languages:      All programming languages.
Formatter:      Plain TeX, LaTeX, and HTML (Mosaic) formatters.
Availability:   Anonymous ftp from:
                  CTAN:/web/noweb
                  LPA:/independent
                  DOS version also in LPA:/machines/ms-dos
                    also bart.kean.edu:/pub/leew
                  Last recourse, use bellcore.com:/pub/norman
Readme:         With bundle above.

Description:

  noweb is designed to meet the needs of literate programmers while
  remaining as simple as possible.  Its primary advantages are
  simplicity, extensibility, and language-independence.  noweb uses 5
  control sequences to WEB's 27.  noweb now supports indexing and
  identifier cross-reference, including hypertext ``hot links''
  courtesy of Mosaic.  The simple noweb manual is only 2 pages;
  documenting the full power of noweave and notangle requires another 3
  pages.  noweb works ``out of the box'' with any programming language,
  and its formatter-dependent part is a 60-line nawk program. The
  primary sacrifice relative to WEB is the loss of prettyprinting.

Support:        email to the author


- ----------------------------------------------------------------------

- nuweb
-------

Developer:      Preston Briggs: preston@cs.rice.edu
Version:        0.87
Hardware:       Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga.
Languages:      Any programming language or combination of programming
                languages.
Formatter:      Latex
Availability:   Anonymous ftp from:
                  Unix: CTAN:/web/nuweb
                  DOS:  CTAN:/web/nuweb-pc
                  LPA:/independent
                  Amiga: CTAN:/web/nuweb/nuweb_ami
                  Amiga: wuarchive.wustl.edu/pub/aminet
Readme:         Send mail to preston@cs.rice.edu

Description:

  A single program that takes a web file written in a combination of
  latex and any programming language(s) and produces a latex file that
  can be pretty printed and a set of files containing code for
  compilation/interpretation by the appropriate language processors.

  Strengths include speed, simplicity, multiple languages, nice indices
  and cross-references, latex.  Doesn't require any special macros or
  macro files.

  Drawbacks: latex-dependent, no code pretty printing, harder to make
  indices than cweb.

  More good stuff: nice support for make, doesn't reformat source files,
  so they're easy to debug.  Lots of control without too much effort.
  That is, it doesn't do too much!

  Future directions... Very little change planned, except perhaps
  refinements in the indexing software.

Support:        Hack it yourself or send e-mail to preston@cs.rice.edu


- ----------------------------------------------------------------------

- ProTeX
--------

Developer:      Eitan Gurari <gurari@cis.ohio-state.edu>
Version:        1.1  (AlProTeX 1.2)
Hardware:       Any platform with TeX (ProTeX is written in TeX)
Languages:      Any language
Formatter:      TeX and LaTeX
Availability:   Anonymous ftp from:
                  ftp.cis.ohio-state.edu : pub/tex/osu/gurari/
                  LPA:/independent
Readme:         Unknown
Description:    There is a book published on using ProTeX,
                @Book{Gurari:TLD94,
                  author =       "Eitan M. Gurari",
                  title =        "{\TeX} and {\LaTeX}: Drawing and
                                  Literate Programming",
                  publisher =    pub-MH,
                  year =         "1994",
                  address =      pub-MH:adr,
                  bibdate =      "Wed Sep 29 17:55:14 1993",
                  acknowledgement = ack-nhfb,
                }

Support:        gurari@cis.ohio-state.edu


- ----------------------------------------------------------------------

- RWEB
------

Developer:      Unknown
Version:        Unknown
Hardware:       Unknown
Languages:      Unknown
Formatter:      Unknown
Availability:   Anonymous ftp from:
                  LPA:/reduce
Readme:         Unknown
Description:    Web generator in AWK.
Support:        Unknown


- ----------------------------------------------------------------------

- SchemeWEB
-----------

Developer:      John D. Ramsdell
Version:        2.1
Hardware:       Unix and DOS platforms
Languages:      Any dialect of Lisp.
Formatter:      LaTeX.
Availability:   The Unix version is in the Scheme Repository and it is
                available via anonymous ftp from:
                  cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh
                  LPA:/lisp
                  CTAN:/tex-archive/web/schemeweb
                The DOS version is part of the PCS/Geneva Scheme system
                which is available via anonymous ftp from:
                  cui.unige.ch:/pub/pcs
                  LPA:/machines/ms-dos
Readme:         In bundle with above.

Description:

  SchemeWEB is a Unix filter that allows you to generate both Lisp and
  LaTeX code from one source file.  The generated LaTeX code formats
  Lisp programs in typewriter font obeying the spacing in the source
  file. Comments can include arbitrary LaTeX commands.  SchemeWEB was
  originally developed for the Scheme dialect of Lisp, but it can easily
  be used with most other dialects.

Support:        Bug reports to ramsdell@mitre.org.


- ----------------------------------------------------------------------

- SpideryWEB
------------

Developer:      Norman Ramsey <norman@bellcore.com>
Version:        Unknown
Hardware:       Unix and DOS platforms
Languages:      Most Algol-like languages, including C, Ada, Pascal,
                Awk, and many others.
Formatter:      Plain TeX and latex for text formatters.
Availability:   Anonymous ftp from:
                CTAN
                LPA:/spiderweb
Readme:         In distribution.

Description:

  A system for building language-dependent WEBs. Spider is frozen; no
  further development is planned.

Support:        Bug reports to spider-bugs@oracorp.com.


- ----------------------------------------------------------------------

- WEB
-----

Developer:      Donald Knuth
Version:        Unknown
Hardware:       Unknown
Languages:      Pascal
Formatter:      TeX (of course! ;-)
Availability:   Anonymous ftp from:
                  LPA:/pascal
Readme:         Unknown

Description:

This is the original software that started it all.  The original TeX
processor was written in WEB.

Support:        None known.


- ----------------------------------------------------------------------

- WinWordWEB
------------

Developer:      Lee Wittenberg <leew@pilot.njin.net>
Version:        Unknown
Hardware:       Needs Microsoft Word for Windows, v.2.x, and, of course,
                MS-Windows 3.x.
Languages:      Any programming language.
Formatter:      Word for Windows 2.x for text formatting and file
                maintenance.
Availability:   Anonymous ftp from:
                  bart.kean.edu:pub/leew
                  LPA:/machines/ms-dos
                World-Wide Web (WWW)
Readme:         WORDWEB.DOC in the downloadable package describes the
                system.

Description:

  WinWordWEB is a set of a Word for Windows macros (plus a paragraph
  style) that provide a crude literate programming environment.  The
  ``look and feel'' of the system is based on Norman Ramsey's noweb, but
  can easily be modified to suit individual tastes.

Support:

  None.  WinWordWEB was written as a prototype to see if a WYSIWYG
  literate programming system was possible.  It is intended as a jumping
  off point for future work by others. However, the system is
  surprisingly usable as it stands, and the author is interested in
  hearing from users (satisfied and dissatisfied).

  Anyone interested in actively supporting (and improving) the product
  should contact the author via email.


= ======================================================================

* Are there other tools I should know about?
--------------------------------------------

First of all, I'll list some not-quite-literate-programming tools.
Some may consider these to be pretty-printers.  Others may call them
literate programming tools.  In any event, they don't seem to be quite
in the same category as the tools listed above, so I'll include them
here.

- C2LaTeX
---------

Developer:      John D. Ramsdell
Version:        Unknown
Hardware:       Unix
Languages:      C
Formatter:      LaTeX but it's easy to change the formatter.
Availability:   Anonymous ftp from
                  omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex.
Readme:         Absent.  Documentation is in the C source for c2latex.

Description:

  C2latex provides simple support for literate programming in C.  Given
  a C source file in which the comments have been written in LaTeX,
  c2latex converts the C source file into a LaTeX source file.  It can
  be used to produce typeset listings of C programs and/or documentation
  associated with the program.

  C2latex produces LaTeX source by implementing a small number of rules.
  A C comment that starts at the beginning of a line is copied
  unmodified into the LaTeX source file.  Otherwise, non-blank lines are
  surrounded by a pair of formatting commands (\begin{flushleft} and
  \end{flushleft}), and the lines are separated by \\*. Each non-blank
  line is formatted using LaTeX's \verb command, except comments within
  the line are formatted in an \mbox.

Support:        Send bug reports to ramsdell@mitre.org.


- ----------------------------------------------------------------------

- c2cweb
--------

Developer:      Werner Lemberg
Version:        1.4
Hardware:       DOS, OS/2, Unix (gcc) - CWEB source included
Languages:      C, C++
Formatter:      TeX
Availability:   Anonymous ftp from
                  CTAN:/web/c_cpp/c2cweb
Readme:         In distribution.

Description:

  c2cweb will transform plain C or C++ code into a CWEB file to get a
  pretty formatted output. A modified CWEAVE (which transforms the CWEB
  file into a TeX file, see below) is included also.


Support:        Werner Lemberg <a7621gac@awiuni11.bitnet>




- ----------------------------------------------------------------------

- c2man
-------

Developer:      Graham Stoney
Version:        2.0 patchlevel 26
Hardware:       Unix, MSDOS, OS/2.
Languages:      C
Formatter:      nroff -man, texinfo (requires yacc/byacc/bison,
                  lex/flex, and nroff/groff/texinfo/LaTeX).
Availability:   Anonymous ftp from
                  ftp.wustl.edu:
                    /usenet/comp.sources.reviewed/volume03/c2man*
                  ftp.informatik.uni-stuttgart.de:
                    /pub/archive/comp.sources/reviewed/c2man*
Readme:         See distribution.

Description:

  The primary philosophy here is to use the programming language as far
  as possible to express the programmer's intentions, and to use
  comments only when the programming language is not sufficiently
  expressive. A comment can then become part of the language grammar
  which is recognised by a "documentation compiler". This tool parses a
  superset of the programming language and can automatically generate
  documentation in human-readable form by associating the programmer's
  comments with the objects in the code by their context.

Support:        Actively supported; mailing list available: send
                "subscribe c2man <Your Name>" (in the message body) to
                listserv@research.canon.oz.au.


- ----------------------------------------------------------------------

- cnoweb
--------

Developer:      Jim Fox
Version:        1.4 (January 4, 1991)
Hardware:       Anything with C and TeX.
Languages:      C
Formatter:      Plain TeX.
Availability:   Anonymous ftp from:
                  CTAN
                  LPA:/c.c++
Readme:         Unknown, cnoweb.tex contains documentation.

Description:

  cnoweb is as it's name describes: write C, not web.  No tangling or
  weaving is implemented.  Documentation (between standard /* */
  delimiteres) is written in TeX.  cnoweb provides typesetting of
  documentation, an table of contents of routines, and pretty-printing
  of C source.

Support:        None known.


- ----------------------------------------------------------------------

- Fold2Web
----------

Developer:      Bernhard Lang <lang@tu-harburg.d400.de>
Version:        V0.8
Hardware:       MSDOS
Languages:      All (must allow comment lines)
Formatter:      LaTeX
Availability:   Anonymous ftp from: 
                  kirk.ti1.tu-harburg.de (134.28.41.50)
                    /pub/fold2web/readme
                    /pub/fold2web/fold2web.zip
Readme:         In distribution

Description:

  The idea behind the Fold2Web tool is the following: A programmer can
  write his program source with a folding editor and later map the
  folded source files automatically to WEB-files. The generated WEB-files
  can then be modified by inserting required documentations.
  
  The advantage by starting program developement with original sources is
  to get short design cycles during the compile/debug steps. By using a
  folding editor the global structuring information can be already
  captured in folds during this developement phase. Fold information is
  typically stored in comment lines and thus will not affect the
  efficiency of the compile/debug design cycle.
  
  Some folding editors and a folding mode for the emacs are available
  (e.g. see our FUE folding editor for MSDOS machines which is a modified
  micro emacs. Pick it at kirk in directory /pub/fold2web).
  
  After reaching a stable version of a program source its time to convert
  the source file to a WEB-file and do the program documentation.
  Fold2Web is written to convert folded source text of any programming
  language to nuweb files. The folded structure is kept by mapping folds
  to scraps. Fold markers which differ between languages due to different 
  ways of specifying comments can be configured for each language.
  
  Good results can also achived when given but poor documented program
  sources have to be modified. Such sources can be folded using a folding
  editor to extract the global structures. This offers a global view to
  the program structures and help to understand its functionality.
  Furthermore the program code is not affected, only comment lines are
  inserted. Once folded the program source can be automatically
  translated to a WEB document using the above tool.

Support:   email to lang@tu-harburg.d400.de


- ----------------------------------------------------------------------

- Funnelweb Mode
----------------

Developer:      Daniel Simmons <simmdan@kenya.isu.edu>
Version:        Unknown
Availability:   Litprog archives (was in email)
                Anonymous ftp from:
                  ftp.imada.ou.dk

Description:

The other day I did a quick hack to nuweb.el as included with the nuweb
distribution so as to make a funnelweb-mode.el.  I've only used it
briefly, and I'm sure that it can be improved quite a bit.  I've been
thinking about adding support for folding on sections, a pull-down menu
to select macro definitions (like the recent functions posted to
gnu.emacs.sources for a C function definition pull-down menu) and some
kind of tags support for funnelweb.

Support:        Unknown


- ----------------------------------------------------------------------

- noweb.el
----------

Developer:      Bruce Stephens <bruce@liverpool.ac.uk>
Version:        Unknown.
Availability:   LitProg archives (in an email message).

Description:

This is a very simple mode I just hacked up.  There's a lot wrong with
it, but I thought others may be interested, even as it stands.  It
*requires* text properties, and assumes those used in GNU Emacs 19.22;
it'll quite likely work with Lucid Emacs, but I haven't tried it.

I use it with auctex8.1 and cc-mode 3.229, both of which are loaded
separately (I think my emacs is dumped with them, in fact).

The idea is to have one mode (which calls itself c-mode, but actually
has LaTeX-mode keybindings) generally (this means that the code is
hilighted nicely), and have the code chunks use a different keymap.


Support:        Email to bruce@liverpool.ac.uk


- ----------------------------------------------------------------------

- nuweb.el
----------

Developer:      Dominique de Waleffe <ddw@sunbim.be>
Version:        1.99
Availability:   Anonymous ftp from:
                  LPA
                  CTAN

Description:

  Provides a major mode extending Auctex for editing nuweb files. Main
  features (in 2.0):
   	- Edit scrap bodies in a separate buffer in a different mode
      (selected using emacs defaults for files, specific indication
      -*-mode-*-, or a buffer-local variable)
	  - Extends Auctex commands so that nuweb is called before LaTeX,
	  - Easy navigation on scrap definition and use points.
	  - Now creates an imenu (C-M-mouse1) with user index entries, macro
      definition positions and file definition positions.

Support:        Email to ddw@sunbim.be

- ----------------------------------------------------------------------

- TIE
-----

Developer:      Unknown
Version:        Unknown
Hardware:       Unknown
Availability:   Anonymous ftp from:
                  LPA:/Tools
Readme:         Unknown

Description:

This software merges change files.

Support:        Unknown


- ----------------------------------------------------------------------

- Web mode
----------

Developer:        Bart Childs <bart@cs.tamu.edu>
Version:          Unknown
Tools supported:  web, fweb, cweb, funnelweb
Availability:     Anonymous ftp from
                    ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode
                    thrain.anu.edu.au:pub/web/EMACS.web-mode

Description:

This version works with versions 18 and 19 of Emacs to be best of my
knowledge.  I have cleaned up a number of documentation items ...
In the same directory is wm_refcard.tex which is an edited version of
the famous one to include some web-mode commands.

The files limbo* are related to its use and notice that half them
have an uppercase L in them for LaTeX.  The setup is based upon the
fact that we (I am not alone here) primarily use FWEB for C and Fortran
programming.

We are using version 1.40 of FWEB although John Krommes warns that it
is not mature and the manual is not yet updated.  The info files are!
We are using LaTeX almost exclusively.  That will likely change and we
will revert to version 1.30 if the final form of 1.40 cannot return
to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6
type section numbers.


Support:        Unknown



= ======================================================================

* What other resources are available?
-------------------------------------

- World Wide Web
----------------

An untapped resource (by me anyway ;-) is the World Wide Web.  Marcus
Speh has expended considerable effort in this regard.  If you're
connected to WWW, then access:

  http://info.desy.de:80/user/projects/LitProg.html

If you aren't connected to WWW, telnet to info.cern.ch and explore.
You can reach Marcus' literate programming pages by typing:

  go http://info.desy.de:80/user/projects/LitProg.html

Help for people who have only Email and neither WWW nor telnet, can be
obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message,
  SEND <http_address>,
for example,
  SEND http://info.desy.de:80/user/projects/LitProg.html
to retrieve the LitProg library page.   A help file can be retrieved by
sending a message to the list server above with the text
  HELP
in the body of the message.  Instructions will be returned by email. For
literate programming documents, you can try anonymous ftp to ftp.desy.de
[131.169.10.115] and get the file:
  /pub/userWWW/projects/Announce/LitProg.txt


- ----------------------------------------------------------------------

- TeX Resources
---------------

Another resource of interest to literate programmers is the info-tex
mailing list.  If you're using (La)TeX as your typsetting system and
have access to internet, then you should investigate this mailing list.
Mail list service is available through the SHSU list-server.  To
subscribe, send a message to LISTSERV@SHSU.EDU, and include in the
message one line of text:

    SUBSCRIBE INFO-TEX "your name in quotes"

The list is unmoderated; messages sent to info-tex@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.text.tex.

Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory info-tex.

Another reason the TeX resources should be important is that so many of
the literate programming tools rely on either plain TeX or LaTeX as
their text formatter.  (La)TeX software systems exist for most computing
platforms.  These systems can be found on CTAN and other major archive
sites.  Use archie to find them or simply ftp to one of the CTAN
sites and browse.


- ----------------------------------------------------------------------

- Virtual Coursework
--------------------

Marcus Speh plans an introductory course on Literate Programming on the
Internet, part of the first semester of "Global Network Academy" [GNA],
a non-profit corporation incorporated in the state of Texas, affilated
with the Usenet University project. The texts/sample programs for this
class will be made available via the World-Wide Web. A special room on GNA
Virtual Campus will be staffed by a consultant in one to two hour
shifts.  Students with questions can telnet to the virtual campus and
ask questions of the staff there.  If you are interested in
registering for the course either as a student or as a consultant,
please contact marcus@x4u.desy.de. You will receive a standard reply
message; no further action will be taken until June 94.  Interested
parties can check the hypertext notes for the completed C++ Course done in
a similar fashion, at URL http://info.desy.de:80/pub/uu-gna/html/cc/index.html

[Editor's note: Because of workload, Marcus requests that email
inquiries be limited to a statement of interest for either a student or
consultant position until June 1994.]


= ======================================================================

* Are there any code examples?
------------------------------

Examples of web programs are included with the FWEB, CWEB, and noweb
distributions.  nuweb is written in itself.

Cameron Smith converted the K&R calculator program into a literate
program.   It can be retrieved by anonymous ftp from:
  niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as
    krcwsamp.zip
  or from
    LPA/Documentation

Ross Williams has released a funnelweb example.  You can retrieve this
file from node ftp.adelaide.edu.au [129.127.40.3] as
  /pub/funnelweb/examples/except.*
This file should be on CTAN as well.

Lee Wittenberg has posted a few litprog examples.  They are available
via anonymous ftp from:
  bart.kean.edu:/pub/leew/samples.LP

The Stanford GraphBase is a large collection of programs by Don Knuth for
doing all kinds of computations and games with graphs; it is written in
(Levy/Knuth) CWEB. More details in the distribution.  It is available
via anonymous ftp from:
  labrea.stanford.edu:/pub/sgb


= ======================================================================

* Bibliographies
----------------

Nelson Beebe has collected an extensive bibliography treating literate
programming.  His work is available for anonymous ftp from
ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files:
    litprog.bib
    litprog.ltx
    litprog.twx.
Although I have not verified this, LPA is an alternate source for these
files.  Note that they are updated frequently (Nelson says several times
each week), so be sure to get a fresh copy before extensive use.
Joachim Schrod indicates that these files may be updated daily and can
be retrieved via anonymous ftp at LPA/documentation.


= ======================================================================

* How to anonymously ftp
------------------------

Pretty much everything mentioned here is available by anonymous FTP.
FAQ lists cross-posted to news.answers and rec.answers can be gotten
from rtfm.mit.edu [18.181.0.24], under /pub/usenet/news.answers or under
/pub/usenet/more.specific.group.name

"anonymous FTP" is just a way for files to be stored where anyone
can retrieve them over the Net.    For example, to retrieve the
latest version of the literate programming FAQ, do the following:

> ftp rtfm.mit.edu              /* connect to the site; message follows */
> anonymous                     /* type this when it asks for your name */
> <your email address>          /* type your address as the password    */
> cd /pub/usenet                /* go to the directory you want to be   */
> cd comp.programming.literate  /* one level down (no slash).           */
> dir                           /* look at what's there                 */
> get literate-progamming-faq   /* get the file; case-sensitive         */
> quit                          /* stop this mysterious thing           */

If your FTP program complains that it doesn't know where the site you
want to use is, type the numerical address instead of the sitename:

> ftp 18.181.0.24               /* connect with numerical address */

If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu
with the single word "help" in the body of the message.

Getting binary files (executables, or any compressed files) is only
slightly more difficult.   You need to set binary mode inside FTP before
you transfer the file.

> binary            /* set binary transfer mode  */
> ascii             /* set back to text transfer mode */

FAQs and spoiler lists are generally ascii files; everything else is
generally binary files.

Some common extensions on binary files in archive sites are:

  .Z           Compressed; extract with uncompress
  .tar.Z       Compressed 'tape archive'; uncompress then untar or tar -xvf
  .gz or .z    Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu)
  .sit         (Mac) StufIt archive
  .zip         Extract with Zip or Unzip
  .zoo         Yet another archive/compress program
  .lhe         (Amiga) ?
  .lzh         Lha archive program.
  .arj         (PC) Arj archive program.
  .exe         (PC) Sometimes self-extracting archives-just execute them.
  .uue or .UUE Transfer as text file; use uudecode to convert to binary
  .hqx         (Mac) BinHex format; transfer in text mode

Generic help can be found in the FAQs of comp.binaries.<your_system_type>
for how to transfer, extract, and virus-check binary files.  (At
rtfm.mit.edu)

If you can't FTP from your site, use one of the following ftp-by-mail
servers:

  ftpmail@decwrl.dec.com
  ftpmail@src.doc.ic.ac.uk
  ftpmail@cs.uow.edu.au
  ftpmail@grasp.insa-lyon.fr

For complete instructions, send a message reading "help" to the server.

If you don't know exactly what you're looking for, or exactly where it
is, there are programs and servers that can help you.  For more info,
send e-mail to mail-server@rtfm.mit.with with the body of the
message reading send usenet/news.answers/finding-sources


Thanks to Aliza R. Panitz (the "buglady") for this text.  I copied it
verbatim from her post on faq-maintainers with only minor modifications.


= ======================================================================

* Acknowledgements
------------------

This document would not have happened without the help of many people.
Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim
Schrod, Piet van Oostrum, and Ross N. Williams.  A special thanks to
Aliza R. Panitz for the text describing how to execute an anonymous ftp
for files of interest.

Any omissions from these acknowledgements should be considered an act of
stupidity on my part.  Of course, the authors of literate programming
tools mentioned above all play a vital role in the vitality of literate
programming. Furthermore, participants in the comp.programming.literate
newsgroup (and associated mailing list) all contributed in various
fashions.  Thank all of you.


= ======================================================================

* End notes
-----------

This document will continue to evolve.  I'm planning on adding entries
for additional literate programming tools and will expand the sections
on examples as more examples become available. Tools I will include are
WEB (the original pascal version) for starters. Others will be added as
I find and document them.  Omission of a particular tool should not be
considered a snub in any sense--simply an error or oversight on my part.

= End of File ==========================================================

