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


DOCUMENTATION

@FWEB{} uses LaTeX to produce its documentation. Plain TeX is no longer supported.

It is not necessary to be very familiar with LaTeX in order to use @FWEB{} effectively. @FWEB{} does complicated things behind the scenes, relieving the programmer of many burdens. If you don't need complicated mathematics, one needs to know virtually no LaTeX at all in order to document a section of code. And if you do need to typeset math, consider that LaTeX makes this daunting task about as simple as one could hope.

If you're an @FWEB{} beginner, don't bother diving into the details of this section until you really need to.

Typesetting

@FWEB{}'s "new look" (beginning with version 1.40) is designed to work only with LaTeX. The new look is more book-like, following ideas from Briggs' nuweb. By default, it uses default LaTeX section numbers such as 1.5.32; however, sections may be numbered with consecutive integers by specifying the LaTeX2e package fwebnum; see section Section numbering schemes.

@FWEAVE{}'s OUTPUT

When one says `fweave test', the file `test.tex' is created. Some TeX commands contained in this file are created automatically; others are copied from the web source file. They are organized into several sequential groups, as follows.

  1. \input command to read in @FWEAVE{}'s macro package. By default, the initial input command is `\input fwebmac.sty' (see section The macro package `fwebmac.sty'). The name of the macro package can be changed with the `-w' command-line option, but that is dangerous and useful only for very special effects. See section `-w': Change name of macro package (@FWEAVE{}).
  2. \Wbegin command. The \Wbegin macro sets up certain defaults (which can be overridden in the limbo section). In LaTeX, it also issues the `\documentclass{article}' and `\begin{document}' commands.
  3. Limbo text from the style-file parameter limbo.begin. See section limbo.begin, limbo.end.
  4. Limbo text from `@l' commands. See section `@l': Specify limbo text.
  5. User's limbo section.
  6. Limbo text from the style-file parameter limbo.end. See section limbo.begin, limbo.end.
  7. TeX commands for individual WEB sections.
  8. \input command to read in the index data file.
  9. \input command to read in the module-list data file.
  10. \Winfo command (summarizes some status information).
  11. \Wcon command (generates the Table of Contents, and ends the run).

The macro package `fwebmac.sty'

@FWEAVE{} works in conjunction with the macro package `fwebmac.sty', which is always read into the `.tex' file by default. This file is (overly) complicated, so one should not mess with it unless in dire emergency. Most of its commands are intended for behind-the-scenes processing. However, some features may be of general interest; these are described in the items below.

For the most part, macros used internally by `fwebmac.sty' begin with an uppercase `W'. If you are worried about macro conflicts, a complete list of the macros appearing in `fwebmac.sty' can be found in the Index produced by weaving `fwebmac.web'.

User macros

For the user's convenience, `fwebmac.sty' defines a variety of macros such as `\FWEB', `\Fortran', etc. Refer to `fwebmac.web' for a complete list.

@FWEAVE{} usurps various common single-character macros such as `\.' for its own purposes. So the user can still access their original definitions, those are `\let' equal to alternative commands such as `\period'. For example, commands such as the following are executed in fwebmac.sty:

\let\amp\&
\let\at\@@
\let\bslash\\
\let\caret\^
\let\dollar\$
\let\dstar\*
\let\equals\=
\let\leftbrace\{
\let\period\.
\let\rightbrace\}
\let\vertbar|
\let\PM\#
\let\PC\%

(Some of the more inscrutable synonyms are for historical reasons.)

For the most up-to-date and detailed information, refer to `fwebmac.web'.

Fonts

Several fonts have been declared. Those include

For illustrations and further details, see `fwebmac.web'.

To typeset a string of characters in typewriter type, one may use the `\.' macro. (More precisely, the name of this macro is the value of the style-file parameter format.typewriter. For more information, see section format.???.) When using this, one must escape the special characters ` \#%$^_{}~&', as in `\.{\\alpha}'. (@FWEAVE{} does that escaping automatically when typesetting strings in code mode.) You may wish to surround `\.{...}' with an `\hbox'; that is not done by default because @FWEAVE{} uses special trickery to break long strings in code mode automatically, and that breaking would be inhibited by an `\hbox'.

LaTeX support

Original LaTeX support (through version 1.30) was substantially incomplete in that LaTeX's \output routine was usurped by the relatively simple one used for @FWEB{}'s TeX support. However, beginning with version 1.40, full LaTeX support is provided (and Plain TeX is not supported); version 1.50 supports LaTeX2e. LaTeX's \output routine is used, as are its sectioning commands (with minor changes), Table-of-Contents facilities, etc.

The following discussion is based on LaTeX2e. If LaTeX2e is not installed, @FWEAVE{} recognizes that fact and issues the `\documentstyle' command instead of `\documentclass'.

Users are strongly encouraged to upgrade to LaTeX2e. A useful book that describes the present state of LaTeX is Goossens, Mittelbach, and Samarin, The LaTeX Companion (Addison--Wesley, Reading, MA, 1994).

LaTeX's document class

An @FWEB{}/LaTeX document is set up with the `\Wbegin' command, issued automatically by @FWEAVE{}. See the summary at the end of this section for the essence of what the `\Wbegin' command accomplishes.

@FWEAVE{} uses \documentclass{article} by default. In principle, the document class can be changed by the @FWEB{} style-file option `LaTeX.class'; see section Customizing the behavior of `fwebmac.sty' macros. However, @FWEAVE{ has not been tested with most other document classes}. It will probably not work with most document classes that redefine the sectioning commands from those of \documentclass{article}. However, it may work with the revtex scientific macro package. See section Using REVTeX.

To incorporate class options--i.e., to obtain the effect of `\documentclass[myoptions]{article}'---use the style-file parameter LaTeX.class.options, as in

LaTeX.class.options "myoptions"

To get two-sided printing, for example, one would say

LaTeX.class.options "twoside"

To specify user packages--i.e., to obtain the effect of `\usepackage[pkgoptions]{pkgname}'---use the style-file parameters LaTeX.package and LaTeX.package.options, as in

LaTeX.package "pkgname"
LaTeX.package.options "pkgoptions"

For example, to indent the first line of every section and to permit the use of the multicol package (the latter is a useful way of substantially cutting down on white space), say

LaTeX.package "indentfirst,multicol"

Note that specifying LaTeX.package and LaTeX.package.options results in the execution (by the \Wbegin macro) of precisely one line of the form

\usepackage[myoptions]{mypackages}

Sometimes one instead needs to have multiple \usepackage lines, such as

\usepackage[option1]{package1}
\usepackage[option2]{package2}

To get this effect, one can put these commands explicitly into the style-file parameter doc.preamble (see discussion two paragraphs below), as in

doc.preamble = "\\usepackage[option1]{package1}\
                \\usepackage[option2]{package2}"

TeX commands in the user's limbo section of the web source file will be processed after the \begin{document} command. Limbo commands from the style file can be inserted before and/or after those in the limbo section with the aid of the style-file parameters `limbo.begin' and `limbo.end'; see section limbo.begin, limbo.end.

If there is a compelling reason to insert one's own LaTeX commands between the `\usepackage' and `\begin{document}' commands, one may use the style-file parameter `doc.preamble', whose value is a string consisting of LaTeX commands (empty by default). Those commands are processed immediately before `\begin{document}'. One use of `doc.preamble' is to inhibit @FWEB{}'s tendency to keep a section together on one page. To make it break more readily in the middle of sections (particularly useful for multicolumn output), say

doc.preamble "\\secpenalty=0"

In summary, the beginning of the file output by @FWEAVE{} looks like the following, where `<parameter>' means the contents of the style-file string called `parameter':

\input fwebmac.sty
\Wbegin{many obscure arguments}
<limbo.begin>
Optional TeX commands copied from user's limbo section
<limbo.end>

The `\Wbegin' command essentially does the following:

\documentclass[<LaTeX.class.options>]{<LaTeX.class>}
\usepackage[<LaTeX.package.options>]{<LaTeX.package>}
<doc.preamble>
\begin{document}

For precise information about how `\Wbegin' works, see fwebmac.web. If you feel that macro absolutely needs to be changed, please inform the developer (see section SUPPORT).

Using REVTeX

REVTeX is the standard macro package used for formatting scientific papers submitted to the American Physical Society, the American Institute of Physics, and some European journals. It modifies the sectioning commands of \documentclass{article} and provides various other useful macros.

Unfortunately, as of August, 1998, REVTeX is not fully compatible with LaTeX2e; it must be invoked with \documentstyle{revtex}, not \documentclass. This is annoying, because @FWEB{}'s macros in `fwebmac.sty' default to \documentclass if they recognize that LaTeX2e is loaded.

To use REVTeX, uncomment the line in `fwebmac.sty' that says \useREVTeXtrue. (One cannot say `\useREVTeXtrue' in the limbo section of one's web source, because the document class has already been selected by that time.) You may wish to rename the resulting file, say to `rwebmac.sty', so it can be loaded in place of the standard `fwebmac.sty'. To do that, one would use the command-line option `-wrwebmac.sty' (see section `-w': Change name of macro package (@FWEAVE{})).

Saying \useREVTeXtrue selects \documentstyle rather than \documentclass. To implement a standard command such as \documentstyle[aps,my_macros]{revtex}, use the style-file (`fweb.sty') parameters LaTeX.style and LaTeX.options, as in

LaTeX.style "revtex"
LaTeX.options "aps,my_macros"

Here `my_macros.sty' would be a user's macro package loaded in addition to those of REVTeX and @FWEB{}.

REVTeX support is extremely recent. There may be glitches; please report those. In a pinch, if LaTeX stops while processing a REVTeX file produced by @FWEAVE{}, try typing `s' (scroll mode) to force it to continue; you might get usable output.

LaTeX packages related to @FWEB{}

The following packages are supplied with the @FWEB{} distribution and can be used to achieve special effects. Packages are invoked by giving their names as arguments to the LaTeX.package command; see section LaTeX.???.

Sections in LaTeX

@FWEB{}'s sectioning commands `@*' and `@*n' are converted into LaTeX's section commands such as \section (n=0), \subsection (n=1), and \subsubsection (n=2). During LaTeX's processing of the .tex file, it keeps track of the maximum depth achieved by `@*n'. This number is written as the last item in the `aux' file. During the next LaTeX run, that number is used to map the untitled @ASP{} commands to the next most insignificant sectioning command. That level of sectioning command is slightly redefined from LaTeX's default, so don't try to redefine it.

The previous scheme means that it may be necessary to run LaTeX as many as three times in order to resolve all sectioning and cross-reference information correctly. You should be warned in such cases. If not, you will recognize difficulties by noting that the Table of Contents or section numbering is incomplete.

The `aux' file is also used by both processors to generate appropriate error messages that refer to the LaTeX section number instead of the internal one.

A discussion of alternative section-numbering schemes is given in section Section numbering schemes.

LaTeX's index.

The Index should be the last section of the code, and should be begun by the command `@* \INDEX.'. For more information, see section index.???.

The challenge of typesetting the Index is to get it into two-column mode in the best possible way. In the original Plain-TeX @FWEB{}, special code was provided for this. With LaTeX, however, one wants to use standard features.

The best solution is to use the user package multicol. If that is loaded by means of the style-file statement `LaTeX.package "multicol"', then any text typed by the user following the `@* \INDEX.' command will be typeset in single-column mode, after which two-column mode is entered. If it is not loaded, a `\twocolumn' command is issued before the index section is begun (in order to get the Index started on a new page).

More precisely, what happens is the following. When the `@* \INDEX.' command is recognized, essentially the following operations are performed, where the results are bracketed in the form `[multicol : nomulticol]':

\beforeindex [\newpage : \twocolumn]
[print INDEX section heading]
\startindex  [\begin{multicols}{2} : \medskip]
\Wfin        [\end{multicols} : \relax]

(Use of the asymmetrical name `\Wfin' is for historical reasons.)

The positioning of `\beforeindex' suggests a way of printing the entire document in two-column mode. If one enters multi-column mode in the limbo section, then `\beforeindex' can be used to terminate it. It is best to do this at the end of the limbo section; otherwise user macro definitions in the limbo section must be made \global in order that they remain defined in the Index. The relevant commands can be placed in the style file:

LaTeX.package "multicol"

doc.preamble "\\secpenalty=0"

limbo.end "\\def\\beforeindex{\\end{multicols}\\newpage}\n\
\\begin{multicols}{2}\n\
\\raggedcolumns"

Just to repeat, use only the first command to get just the Index printed in two-column format; use the second and third ones to make the entire document two-column.

LaTeX's Table of Contents

LaTeX uses the `aux' file to accumulate the information for the Table of Contents.

When LaTeX is used, the Table of Contents appears at the front of the document by default (beginning with version 1.61). This is accomplished by setting the default value of the style-file parameter limbo.end to "\\FWEBtoc", where \FWEBtoc is defined in `fwebmac.sty'. If you initialize limbo.end yourself in `fweb.sty', you should include "\\FWEBtoc" at the end of that initialization if you want the Table of Contents to appear in the beginning. Otherwise, it will appear at the end.

In essence, the Table of Contents is produced by the LaTeX commands

\pagenumbering{roman}
\maketitle
\topofcontents
\tableofcontents
\botofcontents
\newpage

By default, the @FWEB{} hooks \topofcontents and \botofcontents are empty, but they may be used in special circumstances to override the usual behavior. One can set the parameters for \maketitle in the limbo section in the usual LaTeX way, except that it is better to use @FWEB{}'s \Title macro instead of \title:

\Title{MYCODE.WEB}
\author{My name}
\date{January 1, 2001}

By default, the argument of the \Title macro is printed both on the title page and as a running headline in the document. The default font for the title is \ttitlefont; that for the running headline is \large\tt. However, \Title has one optional argument that allows one to override the running headline, perhaps by specifying a shorter form. Say

\Title[Short title]{Long title}

to make the running headline be `\large\tt Short title' and the title-page title be `\ttitlefont Long title'.

The \@FWEB{} \Title macro calls LaTeX's \title macro with the long title as its argument. By default, @FWEAVE{} uses (in the `\Wbegin' macro)

\title{}%
\author{}%
\date{\today\\[3pt]\Time}%

Section numbers in the Table of Contents are produced by the LaTeX macro \numberline. LaTeX's default definition is inadequate when section numbers are very large; they extend to the right and can overwrite the section name. The macro is redefined more appropriately when the package fwebnum (see section Section numbering schemes) is used.

Customizing LaTeX's output

Several (TeX) flags are provided to change the appearance of the final LaTeX document. (This appearance is a bit experimental, and it is fair to say that not everything may be fully debugged; please report problems.) These are (`...' means either `true' or `false')

The defaults for these flags are

\pagerefsfalse
\numberTeXfalse
\numberdefstrue
\numbercodetrue

If desired, one may override these in the limbo section. (They are defined using Plain TeX's `\newif' rather than the equivalent LaTeX command because they may also be used when LaTeX is not present.)

\numberTeX is on the verge of obsolescence. Try to not use it; never use it in conjunction with the package fwebnum. See section Section numbering schemes

Page references

When one says `\pagerefstrue' (LaTeX only), index references are made by page numbers rather than module numbers or LaTeX section numbers. If there is more than one section per page, they are identified by `a', `b', `c', etc., such as `section 17b'. (Presently, this will not work correctly when multicol is used for the body of the document.)

The information necessary to process page references in this way is written into the `aux' file. As is usual with LaTeX, several runs may be required for the references to be fully consistent with the source file.

Page headers

The very top (header) line on each page of @FWEAVE{}'s output contains several pieces of information:

Section numbering schemes

The @FWEB{} commands `@*' and @ASP{} are translated by complicated magic into LaTeX commands such as \section, \subsection, etc. By default, use of \documentclass{article} then produces Dewey-decimal section numbers such as 2.13.4 (subsubsection 4 of subsection 13 of section 2). When the section tree is very deep, these numbers can look somewhat obtrusive.

An alternative scheme (that of the original WEB) is to merely number each section in ascending integer order, beginning with 1. This can be done by specifying the package fwebnum, as in

LaTeX.package = "fwebnum"

This package is supplied with the @FWEB{} distribution; it is still somewhat experimental.

By default, fwebnum numbers all sections, including unnamed ones. To prohibit numbering of unnamed sections, use the package option dontnumberunnamed, as in

LaTeX.package.options = "dontnumberunnamed"

This option will eventually make \numberTeX obsolete; do not use \numberTeX in conjunction with fwebnum.

Package fwebinsert: Inserting @FWEAVE{}'s output into a LaTeX document

Beginning with version 1.61, it is (barely) possible to insert the TeX output woven by @FWEAVE{} into a LaTeX document. For example, a code listing could be an appendix to a dissertation, or a handbook on numerical methods could insert fragments of code formatted by @FWEAVE{}.

Suppose one has the file `test.web' and used @FWEAVE{} to create `test.tex'. Unfortunately, it does not work to simply \input test.tex into a LaTeX document, because by default `test.tex' operates in a "stand-alone" mode and tries to issue a \begin{document} command.

Instead, one must use the package fwebinsert and the special input command \FWEBinput, as in the following example. There are two important steps.

  1. Use @FWEAVE{} to create `test.tex'. [You may wish to use the `-x' flag (see section `-x': Eliminate or reduce cross-reference information (@FWEAVE{}).) to prevent some of the lists at the end, such as the index or module list, from being printed.]
  2. Now `latex test' until all of the section numbering is up-to-date. (This step is necessary because information in the `aux' file is used in processing the section headings.)

Now `test.tex' is ready to be inserted in a code like the following:

\documentclass{article}
\usepackage{fwebinsert}

\begin{document}

\section{Body}

The body of the document.

\appendix

\FWEBinput{test}

\end{document}

Note that the `@*' commands in `test.web' are converted into LaTeX sectioning commands such as \section. The above example works correctly because the first `@*' in `test.web' is equivalent to a \section (level 0) command, which should indeed immediately follow an \appendix command. Suppose, however, that you wanted to input `test.web' as part of the body of the above example, and wanted the `@*'s to be treated as subsections (level 1) rather than sections. To tell fwebinsert what level number to assign to the `@*'s, provide that number as an optional argument to \FWEBinput, as in the following example:

\documentclass{article}
\usepackage{fwebinsert}

\begin{document}

\section{Body}

The body of the document.

\FWEBinput[1]{test}

\end{document}

Alternatively, say \FWEBlevel{1} before the \FWEBinput. (The optional argument construction merely calls \FWEBlevel.)

Here are some caveats about fwebinsert:

Pretty-printing

Pretty-printing refers to @FWEAVE{}'s attempt to typeset and highlight the code in a readable way. This is usually done automatically for all of the compiler-like languages such as C. However, it can be inhibited by turning on the N mode with `@N' or by using the VERBATIM language (selected with `@Lv').

Pretty-printing is one of those topics that can arouse strong passions: your idea of what's esthetic may not be mine. Unfortunately, @FWEB{}'s formatting rules are mostly hard-coded, so if, for example, you don't like the way braces are arranged in typeset C code, you're mostly stuck. Most directly, this possibly undesirable choice comes from design decisions made by previous authors. It also makes @FWEAVE{} very fast, and enables certain complicated tricks that seem difficult or impossible to accomplish with a completely customizable approach. The latter seems quite formidable, and has not been attempted--a good thesis project for the 21st century.

Pseudo-operators

Pseudo-operators behave like a particular part of speech for the purposes of @FWEAVE{}'s formatting, but are invisible on output; they are ignored by @FTANGLE{}. The pseudo-operators are

@e --- pseudo-expression.  See section Pseudo (invisible) operators.
@; --- pseudo-semicolon.  See section `@;:  Pseudo-semicolon.'
@: --- pseudo-colon.  See section `@::  Pseudo-colon.'

Alternatives for various input tokens

@FWEAVE{} translates various input constructions into allegedly more readable symbols--for example, in FORTRAN it translates `.LT.' into `<'.

Overloading operators and identifiers

For special effects in the woven output, there are commands to help one change the appearance of operators and identifiers.

Overloading operators

A feature common to both C++ and FORTRAN--90 is operator overloading, the ability to extend or redefine the definition of an operator such as `.FALSE.' or `='. FORTRAN--90 even allows one to define new dot operators---for example, one might define the operator `.IN.' to test for inclusion in a set. In a nontrivial extension of the original design, @FWEAVE{} allows one to define how overloaded operators should appear on output. Indeed, this feature can be used even when the compiler language itself does not permit overloading in order to customize the appearance of the woven output.

The `@v' control code is used to change the appearance of an operator. The format is

@v new_operator_symbol_or_name "TeX material" old_operator

This means "Display the new operator according to the TeX material, but treat it like the old operator--e.g., unary or binary--for formatting purposes. The quoted TeX material is treated just like a C string, so if one wants to include a backslash one must escape it with another backslash. For example, one can make an equals sign display on output as a large left arrow by saying

@v = "\\Leftarrow" =

Two FORTRAN examples are

@v .FALSE. "\\.{.FALSE.}" .FALSE.
@v .IN. "\\in" +

This feature can go a long way toward enhancing readability of the woven output, particularly when operators are actually being overloaded. It can also lead to arbitrarily bizarre output that no-one else will understand. As usual, restraint is advised.

Overloading identifiers

Although operator overloading is quite useful, it does not allow one to change the appearance of identifiers. In its most general form, such a facility becomes quite complicated; one must endow @FWEAVE{} with a macro-processing facility analogous to that of @FTANGLE{}. This has not been done yet (maybe it will be someday). In the meantime, one has the command `@W', which provides a restricted form of such a facility. This command is experimental, and not firmly established. Changes in usage and/or syntax may be made in future versions.

The most general form of the `@W' command is

@W identifier "replacement text"

This means: Replace any references to identifier in the woven output with the replacement text.

A more restrictive form is

@W identifier \newmacro

which replaces references to identifier with a call to \newmacro. (Note that there are no quotes in this form.)

The shortest form is

@W identifier .

which replaces references to identifier with a call to \identifier. For example, the identifier x normally appears in woven output as `\.{\Wshort\{x\}}'. If one says

@W x .

one will instead get the macro reference `\x', which could be defined to give a variety of special effects. (However, one may need some rather intimate understanding of @FWEAVE{}'s output in order to ensure that things always work correctly.)

One of the important uses of this facility is to expedite special formatting of array references. This subject is discussed separately below in the section on "Special array formatting" (sorry, that isn't here yet), where an example is given.


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