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.
______________________________________________________________________
Table of Contents:
1. Welcome
1.1. Disclaimer
1.2. Copyright
1.3. What's New?
2. Introduction or
3. How do I get the FAQ?
3.1. Literate Programming FAQ
3.2. FWEB FAQ
4. Is there a newsgroup?
5. What internet nodes are of interest to literate programmers?
6. What is Literate Programming?
7. How do I begin literate programming?
8. What literate programming tools are available?
8.1. APLWEB
8.2. AWEB
8.3. CLiP
8.4. CWEB
8.5. CWEBx3.0
8.6. mCWEB
8.7. FunnelWeb
8.8. FunnelWeb 3.0AC
8.9. FWEB
8.10. IMPACT
8.11. lit2x
8.12. Literate Programmer's Workshop (LPW)
8.13. MapleWEB
8.14. MWEB (Schrod/Detig)
8.15. MWEB (Sewell)
8.16. noweb
8.17. nuweb
8.18. ProTeX
8.19. RWEB
8.20. SchemeWEB
8.21. SpideryWEB
8.22. WEB
8.23. WinWordWEB
9. Are there other tools I should know about?
9.1. C2LaTeX
9.2. c2cweb
9.3. c2man
9.4. cnoweb
9.5. Fold2Web
9.6. Funnelweb Mode
9.7. noweb.el
9.8. nuweb.el
9.9. TIE
9.10. Web mode
10. What other resources are available?
10.1. World Wide Web
10.2. TeX Resources
11. Are there any code examples?
12. Bibliographies
13. How to anonymously ftp
14. Acknowledgements
15. End notes
______________________________________________________________________
1. Welcome
Information contained in this document is the best available at
preparation. The original file was dated October 15, 1993 (just for
historical purposes).
1.1. Disclaimer
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.''
1.2. Copyright
Copyright 1993-1997 by 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@shelob.ce.ttu.edu>
1.3. What's New?
o My email address has changed (once again).
o Newsgroup is moderated.
o Updated fweb entry.
o Updated noweb entry.
o Added mCWEB entry.
o Updated c2cweb entry.
o Updated nuweb.el entry.
o Updated cLiP entry.
o Updated Lee W's examples (from bart).
o Last, but not least, new formatting of the FAQ. Many thanks go to
Andrew Johnson <ajohnson@gpu.srv.ualberta.ca> for helping make this
happen.
2. 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 <thompson@shelob.ce.ttu.edu>
Comments and constructive criticisms are 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 never be complete. Nevertheless, the information
contained herein may be useful to some. Use it as it is intended.
3. How do I get the FAQ?
3.1. 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''.)
3.2. FWEB FAQ
David Coker <coker@astro.sunyit.edu> maintains the FWEB FAQ. The
current version number is 1.30a. It can be retrieved in the same way
as this FAQ.
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 in the directory LPA/Documentation/faq/fweb (see
the references to LPA below for more information).
4. Is there a newsgroup?
One of the most important resources is the literate programming
newsgroup, comp.programming.literate. Because of the amount of
spamming and unrelated the posts, the newsgroup is now moderated.
Posts to the newsgroup are now routed through litprog-
mod@cs.virginia.edu. If your news reader does not post through this
address, then you will be unable to post messages to the newgroup.
You can read this newsgroup using your standard reader.
5. 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.
Participating hosts in the Comprehensive TeX Archive Network are:
ftp.dante.de (Deutschland)
-- anonymous ftp /tex-archive (/pub/tex /pub/archive)
-- gopher on node sun.dante.de
-- e-mail via ftpmail@dante.de
-- Administrator: <ftpmaint@dante.de>
ftp.tex.ac.uk (England)
-- anonymous ftp /tex-archive (/pub/tex /pub/archive)
-- gopher on node gopher.tex.ac.uk
-- NFS mountable from nfs.tex.ac.uk:/public/ctan/tex-archive
-- World Wide Web access on www.tex.ac.uk
-- Administrator: <ctan-uk@tex.ac.uk>
The site ftp.shsu.edu used to be the American CTAN site. Apparently,
that site has fallen into disrepair and should not be considered a
primary source for either TeX related or literate programming related
material. For the record, the address is:
ftp.shsu.edu (Texas, USA)
-- anonymous ftp and gopher /tex-archive (/pub/tex /pub/archive)
-- NFS mountable from ftp.SHSU.edu:/pub/ftp/tex-archive
-- e-mail via ftpmail@ftp.SHSU.edu
-- World Wide Web access on www.SHSU.edu
-- Administrator: <CTAN-Mgr@SHSU.edu>
A list of CTAN archive sites and their mirrors can be found on:
ftp.dante.de:/tex-archive/CTAN.sites
I presume that the other CTAN sites mirror this file, but have not
checked. As of my last check (September 1994), it contains:
"In order to reduce network load, it is recommended that you use the
Comprehensive TeX Archive Network (CTAN) host which is located in the
closest network proximity to your site."
Known partial mirrors of the CTAN reside on (alphabetically):
dongpo.math.ncu.edu.tw (Taiwan) /tex-archive
ftp.adfa.oz.au (Australia) /pub/tex/ctan
ftp.muni.cz (The Czech Republic) /pub/tex/CTAN
ftp.cs.ruu.nl (The Netherlands) /pub/tex-archive
ftp.uu.net (Virginia, USA) /pub/text-processing/TeX
nic.switch.ch (Switzerland) /mirror/tex
Known mirrors of the CTAN reside on (alphabetically):
ftp.center.osaka-u.ac.jp (Japan) /CTAN
ftp.ccu.edu.tw (Taiwan) /pub/tex
ftp.cs.rmit.edu.au (Australia) /tex-archive
ftp.duke.edu (North Carolina, USA) /tex-archive
ftp.germany.eu.net (Deutschland) /pub/packages/TeX
ftp.gwdg.de (Deutschland) /pub/dante
ftp.jussieu.fr (France) /pub4/TeX/CTAN
ftp.loria.fr (France) /pub/unix/tex/ctan
ftp.mpi-sb.mpg.de (Deutschland) /pub4/tex/mirror/ftp.dante.de
ftp.uni-bielefeld.de (Deutschland) /pub/tex
ftp.uni-stuttgart.de (Deutschland) /tex-archive (/pub/tex)
ftpserver.nus.sg (Singapore) /pub/zi/TeX
src.doc.ic.ac.uk (England) /packages/tex/uk-tex
sunsite.unc.edu (North Carolina, USA) /pub/packages/TeX
wuarchive.wustl.edu (Missouri, USA) /packages/TeX
Other nodes and directories of interest include:
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/
6. 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 pro-
grammer, who wants to provide the best possible documenta-
tion 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 docu-
ment such a program we want to explain each individual part
of the web and how it relates to its neighbours. The typo-
graphic 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 combin-
ing the two, we can develop a style of programming that max-
imizes our ability to perceive the structure of a complex
piece of software, and at the same time the documented pro-
grams 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
Another author (Norman Ramsey) wrote me and asked that his opinions be
included in the FAQ. What follows are Norman's comments verbatim.
I see it's time for the ``how is literate programming dif-
ferent from verbose commenting'' question. Perhaps David
Thompson will get this into the FAQ. Alert! What follows
are my opinions. In no way do I claim to speak for the
(fractious) literate-programming community.
How is literate programming different from verbose
commenting?
There are three distinguishing characteristics. In order of
importance, they are:
o flexible order of elaboration
o automatic support for browsing
o 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
7. 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.
8. What literate programming tools are available?
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. :-)
8.1. 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.
8.2. 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.
8.3. CLiP
Developer: E.W. van Ammers and M.R. Kramer
Versions: 2.0 and 2.4b (DOS only)
Platform: Vax/VMS, Unix, DOS
Languages: Any programming language
Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, HTML, etc)
or any wordprocessor including WYSIWYG systems
(Word Perfect, WinWord, Ami Pro, Word Pro, etc.)
Availability: Anonymous ftp from:
sun01.info.wau.nl:/CLIP/ms_dos DOS
sun01.info.wau.nl:/CLIP/ms_dos_24b DOS (v. 2.4b)
sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS
sun01.info.wau.nl:/CLIP/unix Unix
CTAN:/web/clip
LPA:/machines/ms-dos
LPA:/machines/vax
Readme: With bundle above
Description:
CLiP does not use explicit commands to perform the extraction
process. Rather it recognizes pseudostatements written as comments in
the programming language in question. CLiP distinguishes
pseudostatements from ordinary comments because the former comply with
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. Some hypertext examples are at
ftp://sun01.info.wau.nl/clip/html/queens.htm
ftp://sun01.info.wau.nl/clip/html/pal1.htm
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 documentation 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 segments.
+ 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 to
Eric.vanAmmers@user.info.wau.nl
8.4. 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
8.5. CWEBx3.0
Developer: Marc van Leeuwen
Version: Unknown
Hardware: Any system using ASCII code
Languages: ANSI C
Formatter: Plain TeX
Availability: Anonymous ftp from:
ftp.cwi.nl/pub/cweb
Readme: Bundled with above
Brief description:
A modified implementation of CWEB, with some extensions.
Provides a mode for full compatibility with Levy/Knuth CWEB.
The most significant extras are:
- Typedef declarations affect formatting througout source file
- Include files are scanned for typedef definitions
- Flexible selection of layout style
- Possibility to refer to sections using symbolic labels
- CTANGLE detects unbalanced braces and parentheses
- CWEAVE can be made to report syntax errors more easily
- Some additional mechanisms to avoid formatting problems
- New and modular set of grammar rules, based on ANSI C syntax
- Possibility to suppress #line directives
- A new manual
Support:
bugs and remarks to M.van.Leeuwen@cwi.nl
8.6. mCWEB
Developer: Markus Oellinger
Version: 1.0
Hardware: Unix
Languages: C/C++
Formatter: plainTeX
Availability: anonymous ftp from
ist.tu-graz.ac.at:/pub/utils/litprog/mcweb/mcweb.tgz
Readme: at same location
Description:
This is mCWEB 1.0, a descendant of the CWEB system of structured
documentation by Donald E. Knuth and Silvio Levy. It adds some
features that are indispensable when working in a team. mCWEB
regards a project of a book consisting of several chapter files.
By means of import and export commands, it automatically manages
all relationships between the chapters of a book and to other
books.
Interface documentation is now also part of mCWEB. It is
extracted into a second TeX file. This makes it possible to
define well known interfaces between the individual parts of a
project that will be implemented by different persons.
In addition, mCWEB parses C header files to find out about all
the datatypes defined there.
mCWEB comes with a full completely rewritten user manual and is
compatible with CWEB.
Support: Institute of Software Technology
moell@ist.tu-graz.ac.at
8.7. 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.
8.8. FunnelWeb 3.0AC
Developer: Enhanced by A.B.Coates (coates@physics.uq.edu.au)
from FunnelWeb v3.0 by Ross N. Williams
(ross@guest.adelaide.edu.au)
Version: 3.0AC
Hardware: MSDOS, Mac, VMS, Sun, OSF/1, Linux, Sys.V, OS/2.
Languages: No restrictions.
Formatter: Tex, LaTeX, or HTML.
Availability: Anonymous ftp from
ftp.physics.uq.oz.au:/pub/funnelwebAC30.tar.gz
Readme: With bundle above; for FunnelWeb manual see WWW page
http://www.physics.uq.oz.au:8001/people/coates/funnelweb.html
Description:
FunnelWeb 3.0AC is an enhanced version of FunnelWeb (see the entry
for FunnelWeb). FunnelWeb is designed to be typesetter independent,
though FunnelWeb v3.0 only supports (La)TeX as the typesetter.
FunnelWeb 3.0AC also supports HTML, and creates appropriate
hypertext links within the document among the code sections.
FunnelWeb 3.0AC also supports automatic and manual insertion of line
directives, so that compiler errors can be flagged back to the
original FunnelWeb source file. FunnelWeb 3.0AC is completely
compatible with FunnelWeb v3.0 sources (with one minor exception;
see the file README.ABC which comes with the FunnelWeb 3.0AC
distribution).
Support: Supported by A.B.Coates (coates@physics.uq.edu.au), subject
to the time constraints imposed by his thesis.
8.9. FWEB
Developer: John A. Krommes <krommes@princeton.edu>
Version: 1.53 (1.60-beta 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: LaTeX. Plain TeX may work, but is no longer supported.
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
8.10. 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.
8.11. lit2x
Developer: Unknown
Version: Unknown
Hardware: Unknown
Languages: Unknown
Formatter: Unknown
Availability: Anonymous ftp from:
LPA:/independent
Readme: Unknown
Description: None available
Support: Unknown
8.12. 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.
8.13. MapleWEB
Developer: Unknown
Version: Unknown
Hardware: Unknown
Languages: Maple
Formatter: Unknown
Availability: Anonymous ftp from:
LPA:/maple
Readme: Unknown
Description: None
Support: Unknown
8.14. 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.
8.15. 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.
8.16. noweb
Developer: Norman Ramsey <nr@cs.virginia.edu>
Version: 2.8
Hardware: Unix and DOS platforms (DOS binaries available for v2.7).
Languages: All programming languages, singly or in combination.
Automatic indexing for C, Icon, Pascal, Standard ML, TeX, Yacc
Formatter: Plain TeX, LaTeX, and HTML formatters.
Will convert LaTeX to HTML automatically.
Availability: Anonymous ftp from:
CTAN:/web/noweb
LPA:/independent
Last recourse, use ftp.cs.virginia.edu:pub/nr
Readme: With bundle above, or see the noweb home page:
http://www.cs.virginia.edu/~nr/noweb
Those without ftp access can consult ``Literate Programming
Simplified,'' IEEE Software, September 1994, pp97-105.
Description:
noweb is designed to meet the needs of literate programmers while
retaining the simplest possible input format. Its primary
advantages are simplicity, extensibility, and language-independence.
noweb uses 5 control sequences to WEB's 27. The noweb manual is
only 3 pages; an additional page explains how to customize its LaTeX
output. noweb works ``out of the box'' with any programming
language, and supports TeX, latex, and HTML back ends. A back end
to support full hypertext or indexing takes about 250 lines; a
simpler one can be written in 40 lines of awk. The primary
sacrifice relative to WEB is that code is not prettyprinted.
noweb supports indexing and identifier cross-reference, including
hypertext ``hot links.'' noweb includes a simple, efficient
LaTeX-to-HTML converter, so you can use hypertext browsers on your
legacy documents. noweb can also process nuweb programs, so you can
use noweb to convert a standard nuweb program to HTML with one
command.
Support: email to the author
8.17. 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
8.18. ProTeX
Developer: Eitan Gurari <gurari@cis.ohio-state.edu>
Version: ProTeX 1.1, AlProTeX 1.4
Hardware: Any platform with (La)TeX
Languages: Any language
Formatter: TeX or LaTeX
Availability: Anonymous ftp from:
ftp.cis.ohio-state.edu : pub/tex/osu/gurari/
LPA:/independent
Readme: With bundle above
Description:
+ Easy to use
+ Extensible
+ Language independent
+ Multiple output files
+ Fast (single compilation provides output and dvi files)
+ No installation is needed besides copying the files (written in TeX)
Introduction of main features and examples in pub/tex/osu/gurari/LitProg
Complete manual in Eitan M. Gurari, "TeX and LaTeX: Drawing and
Literate Programming", McGraw-Hill, 1994
Support: gurari@cis.ohio-state.edu
8.19. 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
8.20. 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.
8.21. 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.
8.22. 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.
8.23. 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.
9. 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.
9.1. 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.
9.2. c2cweb
Developer: Werner Lemberg
Version: 1.5
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 <a7971428@unet.univie.ac.at>
9.3. c2man
language: C, nroff, texinfo, latex, html
package: c2man
version: 2.0 patchlevel 33
parts: documentation generator (C -> nroff -man, -> texinfo, ->latex,
-> html)
author: Graham Stoney <greyham@research.canon.oz.au>
location: ftp from any comp.sources.misc archive, in volume42
(the version in the comp.sources.reviewed archive is obsolete)
ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl
Australia: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/*
from archie.au
N.America: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/*
from ftp.wustl.edu
Europe: ftp /News/comp.sources.misc/volume42/c2man-2.0/*
from ftp.irisa.fr
Japan: ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/*
from ftp.iij.ad.jp
Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se
description: c2man is an automatic documentation tool that extracts comments
from C source code to generate functional interface
documentation in the same format as sections 2 & 3 of the Unix
Programmer's Manual. It requires minimal effort from the
programmer by looking for comments in the usual places near the
objects they document, rather than imposing a rigid
function-comment syntax or requiring that the programmer learn
and use a typesetting language. Acceptable documentation can
often be generated from existing code with no modifications.
conformance: supports both K&R and ISO/ANSI C coding styles
features: + generates output in nroff -man, TeXinfo, LaTeX or HTML
format
+ handles comments as part of the language grammar
+ automagically documents enum parameter & return values
+ handles C (/* */) and C++ (//) style comments
- doesn't handle C++ grammar (yet)
requires: yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX.
ports: Unix, OS/2, MSDOS, VMS.
portability: very high for unix, via Configure
status: actively developed; contributions by users are encouraged.
discussion: via a mailing list: send "subscribe c2man <Your Name>" (in the
message body) to listserv@research.canon.oz.au
help: from the author and other users on the mailing list:
c2man@research.canon.oz.au
announcements: patches appear first in comp.sources.bugs, and then in
comp.sources.misc.
updated: 1994/10/07
9.4. 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.
9.5. 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
9.6. Funnelweb Mode
Developer: Daniel Simmons <simmdan@kenya.isu.edu>
Version: Unknown
Availability: http://www.miscrit.be/~ddw
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
9.7. 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
9.8. nuweb.el
Developer: Dominique de Waleffe <ddw@acm.org>
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@acm.org
9.9. TIE
Developer: Unknown
Version: Unknown
Hardware: Unknown
Availability: Anonymous ftp from:
LPA:/Tools
Readme: Unknown
Description:
This software merges change files.
Support: Unknown
9.10. 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
10. What other resources are available?
10.1. 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
or use a WWW browser and access the URL
ftp://rtfm.mit.edu/pub/usenet/news-answers/www/resources/literate-programming
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
rtfm.mit.edu and retrieve the official Usenet resource file
/pub/usenet/news.answers/www/resources/literate-programming
10.2. TeX Resources
Another resource of interest to literate programmers is the
comp.text.tex newsgroup. If you're using (La)TeX as your typsetting
system and have access to internet, then you should investigate this
resource.
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.
11. 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:
ftp://samson.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 writ-
ten in (Levy/Knuth) CWEB. More details in the distribution. It is
available via anonymous ftp from:
labrea.stanford.edu:/pub/sgb
12. 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 sev-
eral 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.
13. 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_sys-
tem_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.
14. 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.
15. 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.
Last-modified: 1997/08/15