NAME¶

tangle, otangle - translate a literate programming WEB to Pascal

SYNOPSIS¶

tangle [options] webfile[.web] [{changefile[.ch]|-} [outfile[.p]]]

DESCRIPTION¶

The tangle program converts a WEB literate programming source document into a Pascal program. In addition to being processed with a Pascal compiler, nowadays, the Pascal output is often translated to C; this is how the TeX family of programs are compiled in TeX Live.

The WEB language allows you to prepare a single document containing all the information that is needed to produce both a compilable Pascal program and a well-formatted document describing the program in as much detail as the writer may desire. The user of WEB must be familiar with both TeX and Pascal. WEB also provides a relatively simple, although adequate, macro facility that permits a Pascal program to be written in small modules, written in an arbitrary order.

The command line should have one, two or three filenames on it. The first is taken as the WEB file; ".web" is added if there is no extension.

If a second filename is given, it is taken as a change file, and ".ch" is added if there is no extension. The change file overrides parts of the WEB file, as described in the WEB system documentation. If no second filename, there is no change file.

If a third filename is given, it is taken as the Pascal output file, and ".p" is added if there is no extension. To specify an output file with no change, you can use "-" for the second argument, meaning an empty change file (not stdin). If no third filename is given, the name of the Pascal file is formed by adding ".p" to the root of the WEB file name.

The output file is packed into lines of 72 characters or less, with the only concession to readability being the termination of lines at semicolons when this can be done conveniently.

If the WEB program uses the built-in string handling feature (double-quoted strings), a second output file is a string pool file, whose name is always formed by adding ".pool" to the root of the Pascal file name.

The otangle variant supports a larger character range. It was written for the Omega project, the first TeX supporting Unicode, now provided as the aleph(1) descendant program.

OPTIONS¶

See tex(1) for details of command-line parsing.

Some of these options may render the output unsuitable for processing by a Pascal compiler.

--help

Print help message and exit.

--length number

Compare only the first number characters of identifiers when checking for collisions. The default is 32; the original tangle used 7.

--loose

When checking for collisions between identifiers, honor the settings of the --lowercase, --mixedcase, --uppercase, and --underline options. This is the default.

--lowercase

Convert all identifiers to lowercase.

--mixedcase

Retain the case of identifiers. This is the default.

--strict

When checking for collisions between identifiers, strip underlines and convert all identifiers to uppercase first.

--underline

Retain underlines (also known as underscores) in identifiers.

--uppercase

Convert all identifiers to uppercase. This is the behaviour of the original tangle.

--version

Print version information and exit.

otangle supports only the --help and --version options,

ENVIRONMENT¶

The programs look for the input files using the environment variable WEBINPUTS. If it is not set, it uses the system default. See the Kpathsea manual at https://tug.org/kpathsea for the details of the searching.

SEE ALSO¶

Donald E. Knuth, The WEB System of Structured Documentation.
https://mirrors.ctan.org/info/knuth-pdf/web/webman.pdf

Donald E. Knuth, LiterateProgramming, CSLI Lecture Notes, no. 27.
https://www-cs-faculty.stanford.edu/~knuth/lp.html

Donald E. Knuth, TeX: The Program (Volume B of Computers & Typesetting).
Donald E. Knuth, Metafont: The Program (Volume D of Computers & Typesetting).
These latter two are by far the largest extant examples of WEB programs.

Literate programming topic on CTAN: https://ctan.org/topic/litprog
Package page on CTAN: https://ctan.org/pkg/tangle
Section in the Web2c manual: https://tug.org/texinfohtml/web2c.html#tangle-invocation
Typeset source code for all the original Stanford WEB programs: https://ctan.org/pkg/knuth-pdf

AUTHORS¶

WEB was designed by Donald E. Knuth, based on an earlier system called DOC (implemented by Ignacio Zabala), inspired by considerable earlier work, notably Pierre-Arnoul de Marneffe's concept of ``holon programming'' (https://github.com/holon-scribe/holon-programming).

The updates for Omega were written by John Plaice and Yannis Haralambous.

The tangle and weave programs are themselves written in WEB. The system was originally ported to Unix at Stanford by Howard Trickey, and at Cornell by Pavel Curtis.

Public discussion list and bug reports: https://lists.tug.org/tex-k