Go to the first, previous, next, last section, table of contents.

# 8. WEB: Literate programming

WEB languages allow you to write a single source file that can produce both a compilable program and a well-formatted document describing the program in as much detail as you wish to prepare. Writing in this kind of dual-purpose language is called literate programming. (The Usenet newsgroup ``comp.programming.literate'` and the mailing list litprog@shsu.edu are devoted to this subject; they are gatewayed to each other.)

WEB-like languages have been implemented with many pairs of base languages: Cweb provides C and Troff (see section B. References); CWEB provides C and TeX (``CTAN:/web/c_cpp/cweb'`); Spiderweb provides C, C++, Awk, Ada, many others, and TeX (``CTAN:/web/spiderweb'`); and, of course, the original WEB provides Pascal and TeX, the implementation languages for the original TeX, Metafont, MetaPost, and related programs to come from the TeX project at Stanford.

The original WEB language is documented in the file ``webman.tex'`, which is included in the ftp://ftp.tug.org/tex/lib.tar.gz archive (and available in many other places, of course).

- tangle invocation
- weave invocation
- pooltype invocation

## 8.1 Tangle: Translate WEB to Pascal

Tangle creates a compilable Pascal program from a WEB source file (see section 8. WEB: Literate programming). Synopsis:

    tangle [option]... webfile[.web] [changefile[.ch]]

The Pascal output is written to the basename of webfile extended with ``.p'`; for example, ``tangle /wherever/foo.web'` creates ``./foo.p'`. Tangle applies changefile to webfile before writing the output; by default, there is no change file.

If the program makes use of the WEB string facility, Tangle writes the string pool to the basename of webfile extended with ``.pool'`.

The Pascal output 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.

The program accepts the following options, as well as the standard ``--help'` and ``--version'` (see section 3.2 Common options):

``-length=number'`
  The number of characters that are considered significant in an identifier. Whether underline characters are counted depends on the ``-underline'` option. The default value is 32, the original tangle used 7, but this proved too restrictive for use by Web2c.
``-lowercase'`
``-mixedcase'`
``-uppercase'`
  These options specify the case of identifiers in the output of tangle. If ``-uppercase'` (``-lowercase'`) is specified, tangle will convert all identfiers to uppercase (lowercase). The default is ``-mixedcase'`, which specifies that the case will not be changed.
``-underline'`
  When this option is given, tangle does not strip underline characters from identifiers.
``-loose'`
``-strict'`
  These options specify how strict tangle must be when checking identifiers for equality. The default is ``-loose'`, which means that tangle will follow the rules set by the case-smashing and underline options above. If ``-strict'` is set, then identifiers will always be stripped of underlines and converted to uppercase before checking whether they collide.

## 8.2 Weave: Translate WEB to TeX

Weave creates a TeX document from a WEB source file (see section 8. WEB: Literate programming), assuming various macros defined in ``webmac.tex'`. It takes care of typographic details such as page layout, indentation, and italicizing identifiers. It also automatically gathers and outputs extensive cross-reference information. Synopsis:

    weave [option]... webfile[.web] [changefile[.ch]]

The output is to the basename of webfile extended with ``.tex'`; for example, ``weave /wherever/foo.web'` creates ``./foo.tex'`. Weave applies changefile to webfile before writing the output; by default, there is no change file.

The program accepts the following option, as well as the standard ``-verbose'`, ``-help'` and ``-version'` (see section 3.2 Common options):

``-x'`
  Omit the cross-reference information: the index, the list of WEB module names, and the table of contents (an empty ``CONTENTS.tex'` file will still be written when the Weave output file is processed by TeX using the default ``webmac.tex'`, though).

Conventionally, WEB programmers should define the TeX `\title` macro at the beginning of the source file. Also, to get output of only changed modules, one can say `\let\maybe=\iffalse` (usually as the first change in the change file).

## 8.3 Pooltype: Display WEB pool files

Pooltype shows the so-called string number of each string in a WEB pool file (see section 8. WEB: Literate programming), as output by Tangle (see section 8.1 Tangle: Translate WEB to Pascal), including the first 256 strings corresponding to the possible input characters. Pooltype primarily serves as an example of WEB conventions to implementors of the TeX system. Synopsis:

    pooltype [option]... poolfile[.pool]

No path searching is done for poolfile. Output is to standard output.

The only options are ``--help'` and ``--version'` (see section 3.2 Common options).

As an example of the output, here is the (edited) output for ``tex.pool'`:

    0: "^^@"
    1: "^^A"
    ...
    255: "^^ff"
    256: "pool size"
    ...
    1314: "Using character substitution: "
    (23617 characters in all.)

In Metafont and MetaPost, the first 256 characters are actually represented as single bytes (i.e., themselves), not in the ``^^'` notation. Consider Pooltype as showing the results after conversion for output.

Go to the first, previous, next, last section, table of contents.