FWEB

A WEB system of structured documentation

for multiple languages

By John A. Krommes


NOTE: Because of translation problems with texi2html operating on the macro-expanded version of fweb.texi, user-defined macro expansion has temporarily been turned off in this html version. I'll fix this as soon as possible.

@FWEB{}

This Texinfo documentation describes @FWEB{} Version 1.60.

This documentation is now accessible on the World-Wide Web from

http://w3.pppl.gov/~krommes/fweb_toc.html.

Other sources of information about @FWEB{} are the archival files of the fweb-users and fweb-installers mailing lists. To learn how to obtain those, see section SUPPORT.

If you are learning @FWEB{} for the first time, you will probably find that this (unfinished) manual is not sufficiently pedagogical. For background, please refer to Knuth's book cited in section INTRODUCTION to @FWEB{}. You should also browse through section WEB CONCEPTS, in particular section The structure of a web.

@FWEB{} Copying Permissions

@FWEB{} is "free." This means that everyone is free to use them and free to redistribute them on a free basis. @FWEB{} operates under the terms of the GNU General Public License; see, for example, section `Distribution' in The GNU Emacs Manual.

Although it is hoped that @FWEB{} will be useful, there is ABSOLUTELY NO WARRANTY.

INTRODUCTION to @FWEB{}

@FWEB{} is a system for literate programming. It enables one to maintain both documentation and source code in a single place (the web file), and to explain the code in terms of a web of very small fragments. Because @FWEB{} is intimately integrated with TeX, one gains many advantages such as book-quality typesetting and extensive cross-referencing facilities. A simple example program is described in section The structure of a web.

@FWEB{} was originally intended for scientific programming (the 'F' stands for FORTRAN), and is in wide use in that arena; however, it has much broader applicability. It is an extension of Knuth's WEB system that handles the specific languages C, C++, Fortran (both F77 and F90), RATFOR, and (in a limited fashion) TeX itself. It also attempts to implement a WYSIWYG language-independent mode as well as a (closely-related but not identical) verbatim `language'. The language-independent features are highly experimental and are not recommended.

The origins and philosophy of literate programming are described in the very enjoyable book by D. E. Knuth, Literate Programming (Center for the Study of Language and Information, Leland Stanford Junior University, 1992).

Knuth's original WEB was written in Pascal, and it formatted Pascal code. Silvio Levy introduced CWEB, a WEB system written in C for C. @FWEB{} is a (by now, substantial) modification of version 0.5 of CWEB that was graciously supplied by Levy. It also borrows various ideas from the works of Ramsey and Briggs on language-independent webs.

The original WEB's worked with Plain TeX. More recently, many users have turned to Lamport's LaTeX because of its ease of use and higher-level features. Excellent and extensive development of LaTeX has been accomplished, as described by Goossens, Mittelbach, and Samarin, The LaTeX Companion (Addison--Wesley, Reading, MA, 1994). The present version of @FWEB{} is intended to be used with LaTeX (LaTeX2e, in particular); Plain TeX is no longer supported.

History of WEB and literate programming

(To be completed; see Knuth's book, cited in section INTRODUCTION to @FWEB{}.)

Features of @FWEB{}

@FWEB{} is distinguished from its relatives in several respects:

WEB CONCEPTS

The principle concepts of WEB programming are laid out in Knuth's book, the reference to which was given in section INTRODUCTION to @FWEB{}. @FWEB{} follows most conventions introduced by WEB and CWEB, except that the names of some commands have been changed for consistency, symmetry, and/or clarity.

The @FWEB{} processors: @FWEAVE{} and @FTANGLE{}

Following Knuth's original design, @FWEB{} consists of two processors, @FTANGLE{} and @FWEAVE{}. Both operate on a single source file, say `test.web'. @FTANGLE{} produces compilable code, say `test.c', whereas @FWEAVE{} produces a TeX file, `test.tex', that can (in principle) be processed with either TeX or LaTeX. (If a file `test.tex' already exists, @FWEAVE{} will ask for confirmation before overwriting it if it does not think that the file was created by a previous run of @FWEAVE{}.)

The output file produced by @FTANGLE{} is not intended for human eyes (or for editors!); it is for compiling only. All changes to the code should be made to the web file, since changes made directly to the output file would be overwritten the next time the web source is tangled. In an attempt to discourage messing with @FTANGLE{}'s output file, all unnecessary spaces are deliberately removed.

A common way of integrating @FWEB{} into ones program development is to do all compilations through a make file, into which one puts an extra dependency line that explains how to produce the compilable output file from the web source. For example,

test.c: test.web
        ftangle test

test.o: test.c
        gcc -c test test.c

With this approach, one is not so tempted to edit `test.c'.

@FWEB{} development is now based on LaTeX; Plain TeX is no longer supported. For detailed descriptions of the LaTeX support, see section LaTeX support.

The structure of a web

An @FWEB{} source file is structured into sections, which correspond to logical subunits of the code (either a function or a fragment of a function). Each section consists of three parts, each of which is optional: the

  1. TeX part;
  2. definition part; and
  3. code part.

When @FTANGLE{} outputs code, it can combine the code parts of (possibly noncontiguous) sections into larger units called modules, as explained in section Modules.

With the aid of sections, one's possibly huge and logically complex code can be broken down into bite-sized pieces, each one easily comprehensible. Since sections may correspond to only a small part of a function or subroutine, 1000-line main programs (they still exist!) should become a thing of the past.

Since sections can be combined into modules, there is no need for sections that must be physically contiguous in the output file to be contiguous in the source file. This allows for great flexibility in structuring the documentation of the code.

A simple example

A simple example of an @FWEB{} source file consisting of three sections is as follows:

@n/ % Set FWEB language to Fortran, and recognize short // comments.

\Title{example.web} % \Title is an FWEB TeX macro.
\author{J. A. Krommes} % \author is a LaTeX macro.

@* INTRODUCTION. 
This code is intended to illustrate the use of the |write| statement.
It also provides a simple example of the \FWEB\ macro preprocessor.

@m A_CONSTANT 1.2345 // \FWEB\ preprocessor macro definition.

@a
        program main
        call compute
        end

@ The computational routine is pretty boring.
@a
        subroutine compute
        write(*,*) 'Macro value = ', A_CONSTANT
        end

@* \INDEX.

Commands to @FWEB{} are begun by the `@' symbol (see section @FWEB{} COMMANDS). In this example, the first command, `@n', sets the global language to FORTRAN-77. One should always begin one's code with a language-setting command.

In this example, the language command is invoked with an optional argument `/'. That is necessary in FORTRAN in order to tell @FWEB{} to use the short (single-line) comment form beginning with `//', which otherwise conflicts with the concatenation operator. See section `-n/': Recognize short comments [FORTRAN].

For more information about languages, see section LANGUAGES. For a fuller discussion of optional arguments, see section Setting the language.

The `@*' command begins a major or named section (corresponding to LaTeX's \section command); this command is followed by the section name, terminated by a period. (The period is essential; if it is omitted, weird errors may result.) Major sections are entered in an automatically generated Table of Contents. They are also printed at the top of each output page. If the full section name is too long to so print, one can shorten it with an optional argument, as in

@* [INTRO]INTRODUCTION.

The command `@*n' (not illustrated in the above example) begins a major (sub)section of level n, where `@*0' is equivalent to the simple `@*', `@*1' indicates a subsection, and `@*2' indicates a subsubsection. The highest permissible major level is 2 (a subsubsection). Such subsections are also entered in the Table of Contents. For more information, see section Sections in LaTeX.

As the example demonstrates, the name of the very last section, which should be starred, should be `\INDEX'. Note the backslash; `\INDEX' is a TeX macro. This command tells @FWEAVE{} to write out the index in a special two-column format. By default, `\INDEX' expands to `INDEX', but this name can be overridden by the style-file parameter `index.name' (see section index.???). For more discussion of @FWEB{}'s indexing facilities, see section @FWEB{}'s INDEX..

Minor (unnamed) sections are begun by @ASP{} ("at-space"); these have no associated names and are not entered into the Table of Contents. A newline counts as a space.

The TeX part

All sections begin with (optional) TeX commentary. That can just be straight text; to input that, no knowledge of TeX is required. It can also include mathematical exposition or any of the other advanced features offered by TeX.

Whenever @FWEB{} is in TeX mode, one can temporarily shift into code mode by enclosing the code within vertical bars. That code is typeset just like code in the code part (see below), except that newlines are replaced by spaces. Thus, one can say things like

Consider the C code fragment `|@c for(i=0; i<10; i++){}|', which ...

(If the global language were C instead of FORTRAN, the `@c' inside the vertical bars would not be necessary.) The ability to switch back and forth between text mode and code mode at will allows for a very convenient and flexible style of exposition.

The definition part

The TeX part is followed by an optional definition part. The beginning of the definition part is signaled by the appearance of any one of the commands `@d', `@f', `@m', `@v', or `@W' (explained later). In the previous example, the first section has a definition part consisting of one @FWEB{} macro definition (`@m'); the second section has no definition part. For more information, see section MACROS and PREPROCESSING.

(Failure to appreciate how easy it is to shift from part to part can get one into trouble. For example, don't write documentation such as `Consider the @m command', because the `@m' will inadvertently terminate the documentation part and begin the definition part. What one needs to do here is to use the literal `@', as in `@@m'.)

The code part

An unnamed code part is begun by `@a'. A named code part is begun by the appearance of a module name, such as `@<Global variables@>', followed by an equals sign; see section Modules. Within the code part, one can place any sequence of code or code fragments (they need not be complete subroutines) that are valid for the current language. (Setting the language is described in section LANGUAGES.) The code part is terminated by the next appearance of `@*' or @ASP{} (which signal the beginning of a new section), or by the end of file.

The limbo section

The portion of the source file before the first section (i.e., before the first `@*' or @ASP{}) is called in limbo or the limbo section. The only `@' commands that are allowed in limbo (in addition to `@@', which stands for the character `@' and is allowed anywhere) are the language-changing commands, and one of those, such as `@c', should appear. Other text in limbo is ignored by @FTANGLE{} and is copied by @FWEAVE{} to the tex output file. Thus, one can make or issue TeX macro definitions in limbo that override the defaults in @FWEB{}'s macro package `fwebmac.sty'. In the above example, see the \Title command. This is defined in `fwebmac.sty', and basically issues LaTeX's \title command.

(Another way of getting TeX text into the limbo section is by means of the `@l' command; see section `@l': Specify limbo text.)

LaTeX users may need to know that TeX commands in limbo are executed after the `\begin{document}' command (which is issued automatically in `fwebmac.sty'). For more information, see section LaTeX support.

Modules

The code parts of (possibly noncontiguous) sections can be combined into modules. For @FWEAVE{}, this is a logical combination, for purposes of cross-referencing different pieces of the code. But for @FTANGLE{}, the combination is physical; @FTANGLE{}'s output proceeds module by module.

Modules can be named or unnamed. There is exactly one unnamed module. The fundamental operation of @FTANGLE{} is that

@FTANGLE{ outputs the unnamed module}.

That output goes to a compilable file with an extension appropriate to the current language.

The contents of a module, either unnamed or named, consists of a mixture of code and comments. @FTANGLE{} ignores the comments; @FWEAVE{} treats them as TeX text. Within any TeX text, including comments, constructions delimited by `|...|' signify a temporary shift into code mode. (In the present design, one cannot enclose a comment within the vertical bars.)

The unnamed module

The unnamed code module is introduced by the command `@a'. Subsequent uses of `@a' accrete code to the unnamed module. To repeat, the fundamental operation of @FTANGLE{} is that

@FTANGLE{ outputs the unnamed module}.

Thus, there must be at least one `@a' in the source file or @FTANGLE{} will output nothing.

(Why is the command called `@a'? Historically, it was the first letter of the alphabet, as befits its prominent status. However, one can also think of it as "accrete.")

Named modules

Named modules represent logically-connected fragments of code.

A module name is specified by the construction

@< Arbitrary TeX text @>

Leading and trailing white space around the name text is ignored. The name text can include the `|...|' construction, which tells @FWEAVE{} to typeset a code fragment. Thus, module names can be highly explicit--for example,

@< Check that |x >= 0.0|; |abort| if not @>

To define a named module, replace the `@a' that begins the unnamed code part of a section by `@< module name @>='. If one uses this construction with the same name in a later section, the effect is to accrete to the contents of the module. Thus, a named module might ultimately consist of the code from sections 2, 5, and 9, for example.

To use a named module, simply use the name anywhere in a code part; @FTANGLE{} will insert the contents of the module at the point where the name is used. For example,

@c
@ Here's how to use a named module.
@a
for(i=1; i<n; i++)
        @< Inner loop @>@;

@ Here's how to define a named module.  Definitions may occur after use.
@< Inner...@>=
{
a[i] = i;
}

There are several details to notice about the above example. First, @FWEAVE{} considers module names to be simple expressions (such as the single identifier x). In C, expressions are made into complete statements (as is required in the body of a for statement) by appending a semicolon. In this case, a pseudo-semicolon `@;' is appropriate; for more discussion of that, see section `@;': Pseudo-semicolon.

Second, after a name has appeared once in full, it may be abbreviated by a unique prefix followed by three periods, as demonstrated in the above example. By convention, a complete module name cannot be a subset of another. For example, `@<Test@>' and `@<Test of graphics@>' will elicit an error message.

Commonly, the first unnamed section in the code indicates its modular structure. For example, a C code might begin with

@c
@* DEMO.
@a
@<Include files@>@;
@<Typedefs@>@;
@<Function prototypes@>@;
@<Global variables@>@;

Subsequently one can accrete to the above named sections, as often as desired and in any order. This way, definitions of global variables can be introduced anywhere in the web source file as logical and pedagogical exposition dictates, but will be guaranteed to appear at the top of the code. Function prototypes could be handled this way as well; alternatively, they could all be collected into one section, perhaps at the end of the source file. (The above organization still guarantees that they will appear at the beginning of the output.) Functions could be introduced one at a time in subsequent unnamed sections.

Very rarely, one might try the following construction:

@
@a
@< Left side @> = @< Right side @>@;

Here the intent is to construct an assignment statement. However, this will be flagged as an error because @FWEB{} thinks one is trying to define the named module `@<Left side@>', which one shouldn't be doing while in code mode. To make it work, just put the invisible expression `@e' (see section Pseudo (invisible) operators) before the equals sign.

Phases of processing

The @FWEB{} processors perform their work in several distinct phases. (The following is somewhat technical. Scan it, then use it for reference later if necessary.)

The phases of @FTANGLE{}

@FTANGLE{} has two phases. In phase 1, the source file is read; in phase 2, compilable code is written out in the order specified by the web.

More specifically, phase 1

Phase 2

The phases of @FWEAVE{}

@FWEAVE{} has three phases. In phase 1, the source file is read and cross-reference information is collected. In phase 2, the source file is read again, then pretty-printed with some cross-reference information. (For discussion of pretty-printing, see section Pretty-printing.) In phase 3, an automatically-generated Index, List of Modules, and Table of Contents are written.

More specifically, phase 1

Phase 2

Phase 3 writes out cross-reference information. (To eliminate some of that, see section `-x': Eliminate or reduce cross-reference information (@FWEAVE{})..) Specifically, it

FILES

@FWEB{} works with a variety of files. File names have the form `[path]/root[.ext]', where the brackets denote optional. Here the slash is called the prefix end character. Since this character differs for various operating systems, it can be changed by system installers in `custom.h' (see section CUSTOMIZATION). The character that initiates the file-name extension (normally a period) can be changed with the `-E' command-line option (see section `-E': Change the delimiter of a file-name extension).

Input files

@FWEB{} reads files with a variety of default extensions.

`.fweb' -- Initialization file (optional; for setting up default options used for all runs). This file is always in the user's home directory. See section Initialization.

`fweb.sty' -- Style file (optional; for customizing the behavior of a particular web file or group of files). See section The Style file. This file is always in the directory of the web file that is being tangled unless that is changed by environment variable FWEB_STYLE_DIR. The basic name can be changed by the `-z' option (see section `-z': Change name of style file). A sample `fweb.sty' file is provided with the @FWEB{} distribution.

`name.web' -- Source file.

`name.ch' -- Change file (optional; for making incremental changes to a web source file). See section Change files.

`name.hweb' -- Code included into web file with `@i' (see section `@i': Include file (unconditional)). Include files are searched for in the path set by the environment variable FWEB_INCLUDES and/or the `-I' option (see section `-I': Append to search list for include files). If that path is empty, then the current directory is searched.

`name.hch' -- Optional change file for include file.

Automatic file-name completion

Automatic completion of input file names is turned on by the `-e' command-line option (see section `-e': Turn on automatic file-name completion). When this option is in effect, input file names that include no period (have no extension) are completed automatically according to the contents of the following style-file entries:

  • Type of file @tab Style-file entry @tab Default
  • WEB file @tab ext.web @tab web
  • Change file @tab ext.ch @tab ch
  • Include file @tab ext.hweb @tab hweb
  • Change file for include file @tab ext.hch @tab hch
  • More than one extension may be specified, as a space-delimited list--e.g., `ext.web = "web wb"'; the first one that matches is used.

    Output files

    @FWEAVE{} writes a variety of output files.

    `name.tex' -- Woven output to be processed with LaTeX.

    `CONTENTS.tex' -- Temporary file that accumulates Table-of-Contents information. (For LaTeX, the `aux' file is used instead.)

    `INDEX.tex' -- Temporary file that stores indexing information.

    `MODULES.tex' -- Temporary files that stores module list.

    The names of the three temporary files can be changed with style-file parameters (see section The Style file). Commonly, one may put into the style file `fweb.sty' commands such as

    index.tex "#.ndx"
    modules.tex "#.mds"
    contents.tex "#.cts"
    

    The `#' is replaced by the root name of the web file.

    @FTANGLE{} writes files of the form

    `name.ext' -- Compilable output file.

    The extensions for the compilable output file(s) have certain defaults, but can be changed by style-file parameters according to the following table:

  • Language @tab Style-file entry @tab UNIX default @tab non-UNIX default
  • C @tab suffix.C @tab c @tab c
  • C++ @tab suffix.Cpp @tab C @tab C
  • Fortran--77 @tab suffix.N @tab f @tab for
  • Fortran--90 @tab suffix.N90 @tab f90 @tab for90
  • Ratfor--77 @tab suffix.R @tab r @tab rat
  • Ratfor--90 @tab suffix.R90 @tab r90 @tab rat90
  • TeX @tab suffix.X @tab sty @tab sty
  • VERBATIM @tab suffix.V @tab mk @tab mk
  • For example, to change the default extension for a C++ file from `C' to `c++', put into `fweb.sty' the line

    suffix.C = "c++"
    

    Change files

    The primary input to the @FWEB{} processors is the `test.web' source file. However, a change file `test.ch' can also be specified. A change file consists of instances of the following structure:

    @x
    (One or more lines of text, EXACTLY as in the web file.  Copy these
    lines with an editor; don't type them from scratch.)
    @y
    (Replacement text.)
    @z
    

    The change-file mechanism allows one to insert local changes or test new code without physically modifying the original web file.

    To specify a change file, use its name as the second file name on the command line. The extension `.ch' is assumed by default. For example,

    ftangle test test
    

    processes `test.web' with the change file `test.ch'.

    In addition to `@x', `@y', and `@z', the only `@' commands allowed in a change file are language-changing commands such as `@c' and the special commands `@[' and `@]'. The command `@[' is used for column-oriented languages such as FORTRAN--77 and means switch into code mode. Similarly, `@]' means switch out of code mode.

    All `@' commands in a change file must begin in column 1. Lines not beginning with `@' are ignored, so may be used as comments. Comments may also be included on the `@x', `@y', and/or `@z' lines.

    RUNNING @FWEB{}

    @FWEB{} has a UNIX-style command-line syntax. There are many command-line options, but few or none of these are necessary for standard appplications. Proceed in blissful ignorance until you need to do something tricky, then scan the list of options to see if they can help.

    Commonly-used command-line options can be placed into the initialization file `.fweb' (see section Command-line options) that resides in one's home directory.

    A style file (patterned after the utility makeindex; see section The Style file) can be associated with each manuscript or collection of related manuscripts in order to customize their appearance. This file is read after the command-line options are processed, except that the `-p' option gets special treatment; see section `-p': Buffer up a style-file entry.

    Command-line syntax

    The command-line syntax is

    {ftangle | fweave} [-option...] webfile[.web] [changefile[.ch]] 
    

    A file name is anything that doesn't begin with a `-', except that a lone hyphen stands for the special file name `stdin', which means `read from the standard input.' (This should not be used except for very special effects.)

    Command-line options begin with a `-'. File names and options can be intermixed, or the options may appear after the file names. The first file name encountered is the web source file; the second, if it exists, is the change file (see section Change files). [When no change file is specified, @FWEB{} attempts to read from the null file (`/dev/null' on UNIX systems). This name should be specified when @FWEB{} is installed (see section CUSTOMIZATION), or can be set in the style file `fweb.sty'. See section null_file.]

    The web file is shown as required since one is normally processing a source. However, some of the information options (see section Information options) will work without specifying any file name. For example, one can obtain a list of all of the style-file parameters and their default values by saying `ftangle -Z'.

    Command-line options

    Command-line options may be put, one per line, into the initialization file `.fweb' (which is always in the user's home directory). In that file, options beginning with a hyphen are processed before the command-line options (so command-line options can override the defaults). To force an option to be processed after the command-line options, preface it with an ampersand rather than a hyphen; this is rarely necessary.

    To make sense of the plethora of options, it helps to know that options beginning with `n' are related to FORTRAN; those beginning with `r' are related to RATFOR. Some flags that can be set separately for those two languages also have a global option that sets the flags for both languages simultaneously; cf. `-n/', `-r/', and `-/'.

    Some options take arguments. For example, an @FWEB{} macro can be defined from the command line by saying something like `-mIBMPC=1'. Unlike many UNIX utilities, no spaces are allowed between any option and its argument. For example, if one says `-m IBMPC', @FWEB{} will think that `IBMPC' is a file name.

    Negating options

    To negate a command-line option, use an extra hyphen. For example, `--v' means `Don't make all comments verbatim.' This kind of construction isn't used very often, but it is useful if an option such as `-v' is turned on in the `.fweb' initialization file and one wishes to turn it off for just one run.

    `-1': Turn on brief debugging mode (@FWEAVE{})

    This option tells @FWEAVE{} to display irreducible scrap sequences.

    A scrap is a part of speech. The expression `x + y' consists of three scraps: `x' (an expression), `+' (a binary operator), and `y' (an expression). @FWEAVE{} contains production rules such as "replace the combination `expr binop expr' with `expr'." If all goes well, the result of @FWEAVE{}'s reduction process is ultimately just one scrap, such as `function'. If @FWEAVE{} is left with more than one scrap at the end of a section, this is called an irreducible scrap sequence; `-1' displays them.

    Irreducible scrap sequences can arise either because the programmer made a mistake or because @FWEAVE{} has not been taught the proper grammar.

    While @FWEAVE{} is reducing the scraps, it appends TeX macros that ultimately produce the pretty-printed output. Frequently people ask how to change the appearance of that output. Fundamentally, this is not possible at present; the grammar rules and the associated TeX are hard-coded. A completely general, user-customizable scheme is very complex and daunting; it has not been attempted.

    This brief debugging mode can be turned on more locally by means of the `@1' command. See section `@1': Display irreducible scraps.

    `-2': Turn on verbose debugging mode (@FWEAVE{})

    This option tells @FWEAVE{} to display detailed reductions of the scraps as it does the pretty-printing. (For a discussion of scraps, see section `-1': Turn on brief debugging mode (@FWEAVE{}).) Sometimes @FWEAVE{} fails spectacularly at pretty-printing a section, either because of a syntax error on the part of the user or because of a bug in @FWEAVE{}'s logic. This option helps one (usually the system developer!) to figure out why.

    This feature can be turned on more locally by means of the `@2' command. See section `@2': Display detailed reductions of the scraps.

    `-@': Display the control-code mappings

    This option supplies information about the `@' control codes (see section @FWEB{} COMMANDS). It shows the associated style-file parameters that can be used to remap the codes (but don't do that!), and it displays the precedence. (Some codes such as `@@' may be used anywhere; others such as `@*' begin a new section or part of section. Codes that begin the definition part are labelled by `[D]'; codes that begin the code part are labelled by `[C]'; codes that begin a new section are labelled by `[S]'.)

    The option produces two columns of output: the first is sorted numerically, the second alphabetically. The notation `USED_BY_OTHER' means that this command is ignored by whatever processor (@FTANGLE{} or @FWEAVE{}) is currently being run, but may be used by the other processor. (For technical reasons, a very few commands such as `@i' do not show up in this output at present.)

    If one says just `-@', information about all control codes is produced. Selected control codes may be queried by listing them after the `-@'. For example, to learn about the commands `@~' and `@a', say `-@~a'. Remember to quote certain characters on UNIX systems--e.g., `-@'*?''. If a command is used by neither processor, its description will be replaced by a question mark.

    `-A': Turn on ASCII translations

    This option is used primarily for debugging. @FWEB{} works internally with the ASCII character set. If @FWEB{} is run on a non-ASCII machine (notably IBM mainframes), translations to and from the internal ASCII are done automatically; on an ASCII machine, these translations are unnecessary and are not performed unless the `-A' option is used.

    `-B': Turn off audible beeps

    @FWEB{} sometimes beeps the terminal when it encounters certain errors. The `-B' option turns off the beeps, replacing them by a printed exclamation point.

    (This option is sometimes called the "marriage-saver," after the situation that prompted a user's request for this feature.)

    `-b': Number blocks (@FWEAVE{})

    Number do and if blocks in woven FORTRAN and RATFOR output. This feature is particularly useful in FORTRAN-77 to help correlate the beginnings and ends of long blocks (but note that appropriate use of literate programming techniques can keep all of one's blocks short!). Output something like the following is produced, where the comments are inserted automatically by the `-b' option:

    do i=1,10 // Block 1
     do j=1,10 // Block 2
      if(i==j) then // Block 3
            call sub1(i)
      else // Block 3
            call sub2(i,j)
      endif // Block 3
     end do // Block 2
    end do // Block 1
    

    The precise form of the block comment that is emitted can be changed by redefining the macro \Wblock in `fwebmac.sty'.

    `-C': Set the color mode

    The option `-Cn' sets the color mode to n, where the color modes are, briefly,

    0
    No color
    1
    ANSI color
    2
    Bilevel
    3
    Trilevel
    4
    User-defined

    These modes, and color output in general, are described more thoroughly in section Color output.

    For obscure technical reasons, this command is processed differently than all other command-line options. In the present incomplete implementation, the color mode must be set on the command line, not in `.fweb'! To work around this annoyance, UNIX users could alias commands such as `ftangle -C1'.

    `-c': Set global language to C

    Usually the global language (section LANGUAGES) is set to C by means of the command `@c' in limbo, rather than using `-c' on the command line. However, one may need to use the command-line option `-c' if a subsequent command-line option is language-dependent. See, for example, the discussion of the option `-D' in section `-D': Display reserved words.

    `-c++': Set global language to C++

    For more information, see the discussion of `-c' in section `-c': Set global language to C.

    `-D': Display reserved words

    This information option displays the list of reserved words for the language currently in force. (For the purposes of this option, `reserved words' include "true" reserved words such as `int'; they also include the names of intrinsic functions such as `sin' and, for FORTRAN and RATFOR, I/O keywords such as `IOSTAT'.) Thus, to see the reserved words for RATFOR--90, say

    ftangle -Lr9 -D
    

    (For this option one must set the language on the command line, because the `-D' option is processed before the limbo section of the web file is read.)

    If one says `-Dabc', one will get just the reserved words that begin with "abc".

    If one says `-D*', one will get all reserved words for all languages.

    The `-D' may be followed by a list of one or more optional letters enclosed in square brackets. (For UNIX systems, don't forget to quote the brackets, as they mean something special to the shell.) The letters represent which kind of reserved word to display; they may be `i' (`intrinsic'), `k' (`keyword'), or `r' (`reserved'). Thus, to see a list of the FORTRAN keywords, say `-D[k]'. To see a list of the intrinsic functions for C++ that begin with `s', say `-Lc++ -D[i]s'.

    `-d': Convert do...enddo

    (This option is obsolete.)

    `-E': Change the delimiter of a file-name extension

    The standard delimiter for file-name extensions is a period, as in `test.web'. To change this character to a comma, for example, say `-E,'. This feature is required by at least one perverse system.

    `-e': Turn on automatic file-name completion

    When the `-e' option is in effect, @FWEB{} attempts to be helpful in figuring out what file name one intends. For any input file name that has no extension (no embedded period), @FWEB{} completes the name by adding the extension contained in the style-file parameter listed in the following table:

            Type of file      Style-file entry        Default
            WEB file            ext.web        web
            Change file         ext.ch         ch
            Include file        ext.hweb       hweb
            Change file
             for include file   ext.hch        hch
    

    More than one extension may be specified, as a space-delimited list--e.g., `ext.web = "web wb"'; the first one that matches is used.

    `-F': Compare output files with old versions (@FTANGLE{})

    When the `-F' option is in effect, @FTANGLE{} writes its output to a temporary file (or files) instead of to its ultimate destination such as `test.c' and/or `test.f'. After all output is written, the temporary files are compared with the old version of the files, if they exist. If the files are identical, the appropriate temporary file is deleted; otherwise, the temporary file is renamed, effectively overwriting the old version. This feature avoids updating the time stamp on the file unnecessarily, so a make file won't recompile the output unless it really has to.

    Note that with this option in effect, if one uses the UNIX utility touch to force processing of a group of files, but the web sources are never changed, the make file will continue to tangle the sources no matter how many times it is run, since @FTANGLE{} will never update the time stamp on the files. This is harmless, but annoying. To get things back in sync, do a run without the `-F'.

    The location of the temporary file as well as details of the renaming procedure are determined by the automatic configuration script ./configure during installation of the processors. The script first looks for the (non-ANSI) function tempnam. If it finds it, it uses it to place the temporary file in the directory that @FWEB{} would normally use for output in the absence of the `-F' option. (That is usually the current directory.) If tempnam is not available, the ANSI routine tmpnam is used. That places the temporary file in a directory determined by the system.

    To implement the renaming, the rename function is used. That may fail if tmpnam placed the temporary file on a different device. If so, an attempt is made to force the rename by using the system routine to issue a mv command. Terminal output indicates the progress of the renaming. An asterisk following an output file name indicates that rename did not succeed, but the mv command did.

    Some of the above-mentioned file names and system commands are system-dependent; see section CUSTOMIZATION.

    `-f': Turn off module references for identifiers (@FWEAVE{})

    In an attempt to be helpful, @FWEAVE{} appends subscripts to many identifiers indicating in which section they are first defined (see section Customizing cross-reference subscripts). Sometimes these result in output that is too cluttered and confusing. The `-f' option turns off the subscripting operations.

    `-H': Scan C/C++ include files (@FWEAVE{})

    For C or C++, the `-H' option tells @FWEAVE{} to do a phase-1 scan of #include files for `typedef' and/or `class' declarations. This removes the necessity of including many redundant `@f' format statements (see section `@f': Format identifier or module name), which would otherwise be necessary in order that the code be pretty-printed correctly. For example, if one uses the `-H' option with the code

    @c++
    @
    #include <Complex.h>
    Complex z;
    

    the identifier Complex will be properly formatted as a reserved word (in boldface), as though one had said `@f Complex int'.

    In addition to the basic `-H', there are several more detailed options:

    -Hx
    Make index entries only for double-quoted include files.
    -HX
    Make index entries for all include files.
    -Hr
    Retain temporary files generated by the preprocessor.

    By default, index entries are not made for variables that are read during such scans. If one says `-Hx', index entries will be made only for include files whose names are enclosed in double quotes rather than angle brackets, such as `#include "myheader.h"' (usually these are defined by the user and reside in the local directory). If one says `-HX', index entries will be made for all include files. This can generate many entries, since system header files may be complicated and may include other files as well.

    This command is implemented as follows. When @FWEAVE{} reads an #include statement, it issues a system command to run the C preprocessor on the included file. Output from the preprocessor is written to a temporary file, which @FWEAVE{} scans.

    By default, the C preprocessor will look in certain default paths for the included files. To add to those defaults, use one or more `-I' options after the `-H'. These colon-delimited lists are concatenated to the contents of the environment variable FWEB_HDR_INCLUDES, if that is defined. The entire list is then passed as multiple `-I' options to the preprocessor.

    This command, new with version 1.53, is highly experimental and incomplete. The installation script attempts to determine what command to use to run the preprocessor, but that is not guaranteed to work in general. `-H' has been tested only with gcc.

    To send arguments to the C preprocessor, see section `-WH': Send additional arguments to the C preprocessor.

    The `-H' mechanism uses temporary files to do its work. By default, those are deleted after use. However, for debugging purposes, one can force those to be retained by saying `-Hr'. That option also has the side effect of displaying the actual command line that was sent to the preprocessor.

    `-h': Get help

    If just `-h' is typed, a message is printed saying where further help is available. It refers one to the various information options (see section Information options) and the on-line documentation (see section SUPPORT). If the stand-alone info program (the GNU hypertext browser) is installed, one can enter `info FWEB' at this time by typing `?' or a space-separated list of @FWEB{} menu items such as `Macros FWEB built-in $PI'. In fact, since `$PI' appears in the detailed node listing, one can simply type `$PI'. More generally, one can type anything that info accepts on its command line (the option `-f FWEB' is implicit).

    One can bypass the printed message and directly enter info by specifying the info arguments as arguments to `-h'. For example, on a UNIX system, one could type `-h'\$PI''. Here the dollar sign must be escaped because it has special significance to the shell, and the quotes are necessary in order to preserve that escape character as the argument is supplied to info. To get to the top-level @FWEB{} info directory, type `-h.' or `-h'?''.

    `-I': Append to search list for include files

    The fundamental search list for include files (read in via `@i' or `@I') is defined by the environment variable FWEB_INCLUDES, which is a colon-delimited list such as

    setenv FWEB_INCLUDES .:/usr/fweb:/other/stuff
    

    The `-I' option appends to this list.

    For information about include files, see section `@i': Include file (unconditional).

    `-i': Don't print `@I' include files (@FWEAVE{})

    If a web file is included via `@I' (see section `@I': Include file (conditional)), for example

    @I formats.hweb
    

    then the `-i' option means to read and process the web file, but don't print its contents. This option is often used for large files of macro definitions, formats, or typedef statements that must be included at the beginning of even very short web files; it clutters things up to print such header files all of the time. (C and C++ programmers will find that the `-H' option substantially reduces the need to include such header files; see section `-H': Scan C/C++ include files (@FWEAVE{}).)

    Note that files included via `@i' (lower case) do not respond to `-i' or `-i!'.

    By default, identifiers that are referenced in non-printed include files are not cross-referenced or indexed in any way. To force them to be cross-referenced, say `-ix' instead of `-i'. In the present implementation, the cross-reference information for such non-printed files is presented in the form `#n', where n is the integer section number. (The LaTeX section label is undefined for sections in non-printed files.)

    The option `-i!' means skip the include files completely. This is usually not very useful.

    `-i!': Don't read `@I' include files

    If a web file is included via `@I', for example

    @I formats.hweb
    

    then the `-i!' option means to ignore such files completely. This option is seldom useful; the `-i' option (see section `-i': Don't print `@I' include files (@FWEAVE{})) is more often used.

    `-j': Inhibit multiple includes

    File inclusion via @FWEB{}'s `@i' command suffers from a design deficiency: they cannot be inhibited by means of @FWEB{}'s preprocessor commands. (The reason is that `@i' is processed very early in the input stage, before tokenization. This design decision was inherited from CWEB, and is very difficult to change.) A particularly annoying situation arises when the same file is included multiple times; various array space may be eaten up unnecessarily. The `-j' option inhibits such multiple includes.

    `-k': Don't recognize lower-case forms of keywords

    By definition, in FORTRAN and RATFOR, a keyword is one of the parameters such as IOSTAT used in the parameter list of an I/O statement. For example,

    open(21, FILE=file_name, STATUS='old', IOSTAT=io_flag)
    

    Such keywords are typeset in typewriter type to better highlight them. In FORTRAN, these keywords are case-insensitive. However, note that certain of the lower-case forms--in particular, `end', `read', and `write'---have other special meanings, and one can in principle use any of these keywords as ordinary variables in other parts of the code; however, @FWEB{} identifiers can have just one meaning throughout the code. By default, the lower-case forms are also recognized as keywords (except for the three special identifiers just mentioned), so one shouldn't use those as regular variables. To cause only the upper-case forms to be recognized, use the `-k' option.

    `-L': Select global language

    To select a global language from the command line, say `-Ll', where l is one of {c,c++,n,n9,r,r9,v,x}. See section LANGUAGES.

    Usually, the global language is set via an `@' command in limbo, not on the command line. However, one may need to use a command-line option such as `-L_' if a subsequent command-line option is language-dependent. See, for example, the discussion of the option `-D' in section `-D': Display reserved words.

    `-l': Echo input line

    The option `-l[mmm[:nnn]]' echoes the input lines constructed by the input driver between lines mmm and nnn. Missing nnn means echo to the end of file. Missing mmm means echo from the beginning.

    This option is useful as a debugging tool (usually by the system developer). It is often used to verify that the input driver is inserting semicolons correctly. For FORTRAN--77, it is also useful to verify that comments are being processed correctly.

    `-M': Set output message level

    By default, @FWEB{} is relatively verbose; as it proceeds, it prints messages about what files it is reading and writing, numbers of the starred sections, line numbers, etc. However, different levels of verbosity can be set by the command `-Mlevel', where the level may be 0 (least verbose) through 4 (most verbose; the default), as described in the following table:

    0
    Like level 1, but the start-up banner is not printed. If @FWEB{} runs to completion with no errors, nothing at all will be printed.
    1
    Print only error messages.
    2
    Print error and warning messages.
    3
    Print errors, warnings, and short information messages (excluding starred section numbers and line numbers).
    4
    Print everything.

    The start-up banner, which includes the version number, is printed for all message levels except 0. For level 0, one can use the `-V' option to request the start-up banner. See section `-V': Print @FWEB{} version number.

    This option is very recent, and may not be fully debugged for obscure combinations of command-line options. Please report any annoyances.

    Another way of discriminating message types is via color output. See section Color output.

    `-m': Define @FWEB{} macro (@FTANGLE{})

    The command-line construction

    -mA(x)=x
    

    defines the @FWEB{} macro A as though the definition

    @m A(x) x
    

    had appeared in the first definition part of the web file.

    One can also say `-m'A(x) x'', where the quotes are removed by the shell. That is, an `=' appearing immediately after the macro name (or argument list, if there is one) plays the role of the space in the conventional definition. Thus, carefully distinguish the forms

    -m'A(x)=x'   // A(x) expands to `x'
    -m'A(x) =x'  // A(x) expands to `=x'
    -m'A(x)==x'  // Precisely equivalent to the previous example.
    

    The equals sign is permitted only with command-line macro definitions, not with `@m' commands (see section `@m': Define @FWEB{} macro, and mark) in the definition parts of the web file.

    `-m4': Understand m4 built-in commands

    This tells @FWEAVE{} to properly format the reserved words of the m4 preprocessor. The use of that preprocessor is not recommended in conjunction with @FWEB{}; use @FWEB{}'s built-in C-like preprocessor instead.

    `-m;': Append pseudo-semicolons

    When `-m;' is in effect, the construction `@;' is appended automatically to all @FWEB{} macro definitions.

    This option is not recommended. Please insert the `@;' by hand when necessary, as in

    @m SET(x,y) x=1; y=2@;
    @m TEST(x) if(x) y; else z@;
    

    `-n': Set global language to FORTRAN--77

    This is @FWEB{}'s default, so it generally does not need to be used explicitly. (See also the discussion of section `-L': Select global language.) However, variants of this option, as described below, may be useful.

    See also section LANGUAGES and section Special considerations for FORTRAN.

    `-n9': Set global language to FORTRAN--90

    See section LANGUAGES and section Special considerations for FORTRAN; see also the discussion of `-L' in section `-L': Select global language.

    `-n@;': Supply automatic pseudo-semicolons [FORTRAN]

    (Don't forget that a semicolon has special meaning to UNIX shells, so you'll probably have to quote this command: `-n'@;''.)

    This is the default mode of operation for free-form FORTRAN-90; the input driver automatically appends a pseudo-semicolon (invisible) to each logical line of source code. Since it is the default, one doesn't have to use it unless one wishes to negate it (see section Negating options). In that case, it is best to place the `--n@;' command in the source file, as `@n9[--n@;]'. If one places it on the command line, be sure to set the language first: -n9 --n@;.

    For free-format FORTRAN-90, when `-n@;' is in effect (the default), `-np' is also turned on. See section `-np': Print semicolons [FORTRAN] (@FWEAVE{}).

    For further discussion, see the companion command section `-n;': Supply automatic semicolons [FORTRAN].

    `-n;': Supply automatic semicolons [FORTRAN]

    (Don't forget that a semicolon has special meaning to UNIX shells, so you'll probably have to quote this command: `-n';''.)

    This command functions the same as `-n@;' (see section `-n@;': Supply automatic pseudo-semicolons [FORTRAN], except that actual (visible) semicolons rather than pseudo-semicolons are appended. This is the default mode of operation for FORTRAN-77 (and for that language, it cannot be turned off by negation).

    The distinction between `-n@;' and `-n;' has to do with what is visible on output. In FORTRAN-77, semicolons are not printed by default since that seemed to annoy many users. However, that causes trouble with FORTRAN-90 code containing multiple statements per line, as in

    a = b; c = d
    

    If `-np' is not used, then the semicolon in the above example is not printed, hindering legibility. Thus, the default mode of operation for free-format FORTRAN-90 is `-n@;' and `-np'. This turns the above example into `a = b; c = d@;' and displays it correctly.

    When `-n;' is used, semicolons will not be printed by default. To force them to be printed, use the `-np' option (see section `-np': Print semicolons [FORTRAN] (@FWEAVE{})).

    Do not insert semicolons by hand in FORTRAN-77; they are always inserted automatically. If you have terminated FORTRAN-90 statements by hand, turn off auto-semis by `-n;' (and use `-np' at your discretion).

    The following table summarizes the defaults for auto-semi insertion and semicolon printing in FORTRAN, both fixed and free formats (`N/A' means `not applicable'):

  • @tab Fixed @tab Free
  • F77 @tab `-n;' @tab N/A
  • F90 @tab `-n;' @tab `-n@; -np'
  • `-n:': Put statement label on separate line [FORTRAN]

    By default, in FORTRAN statement labels are placed on the same line, and backspaced from, the command that is being labeled, as in

    EXIT: continue
    

    This can look ugly if the label is very long. The command `-n:' places the label on a separate line, as is done automatically for RATFOR---e.g.,

    EXIT:
      continue
    

    If neither of these options appeals to you, you could try redefining the macro \Wlbl, found with some discussion in `fwebmac.web'. That macro is emitted only when `-n:' is not used.

    `-nb': Number ifs and dos [FORTRAN] (@FWEAVE{})

    In the woven output, extra comments are added to help one correlate the block structure of the code. For more discussion, see section `-b': Number blocks (@FWEAVE{}).

    `-nC': Ignore single-line comments [FORTRAN]

    Ignore, at the input-driver stage, comment lines beginning with `C', `c', or `*'.

    Interpretation: In the usual mode of operation, the FORTRAN-77 input driver makes a heroic attempt to mix the original single-line column-1 commenting style with the @FWEB{} style (`/*...*/' and `//'). It converts single-line comments to the `/*...*/' style and passes them along to the innards of the processors.

    Problems sometimes arise when converting an existing FORTRAN code to @FWEB{}. Such codes may have very large blocks of code or documentation commented out with a `C' in column 1. Special TeX characters in those comments can cause problems for @FWEAVE{}; sometimes @FTANGLE{} gets confused as well. The `-nC' option short-circuits these problems by simply throwing all such lines away at the input driver stage.

    This option is not a recommended long-term solution. Instead, consider the following:

    `-np': Print semicolons [FORTRAN] (@FWEAVE{})

    Although the FORTRAN input driver automatically terminates logical lines with semicolons (FORTRAN-77; see section `-n;': Supply automatic semicolons [FORTRAN]) or pseudo-semicolons (FORTRAN-90; see section `-n@;': Supply automatic pseudo-semicolons [FORTRAN]) so that the innards of @FWEAVE{} can process them correctly, the semicolons are not printed by default. To make actual semicolons be printed, use the `-np' option.

    `-np' is turned on automatically for free-format FORTRAN-90 when `-n@;' is in effect (the default). For more discussion, see section `-n;': Supply automatic semicolons [FORTRAN].

    `-n\': Free-form syntax continued by backslash

    In FORTRAN--90, this turns on free-form syntax and sets the continuation character to be the backslash (as it would be in C). For example,

    -n9[-n\]
    @
    @a
    program main
    x = \
     y
    end
    

    In the tangled output the backslash is converted into FORTRAN-90's standard continuation character, the ampersand.

    See also section `-n&': Free-form syntax continued by ampersand.

    `-n&': Free-form syntax continued by ampersand

    In FORTRAN--90, this turns on free-form syntax and sets the continuation character to be the ampersand. For example,

    -n9[-n&]
    @
    @a
    program main
    x = &
     y
    end
    

    For FORTRAN-90, free-form syntax continued by the ampersand is @FWEB{}'s default, so one probably will not need to use `-n&' explicitly.

    See also section `-n\': Free-form syntax continued by backslash.

    `-n/': Recognize short comments [FORTRAN]

    The standard @FWEB{} notation for a short comment (one terminated by the next newline) is `// ...'. However, in FORTRAN the `//' denotes concatenation by default. To make it denote a short comment, use the `-n/' option. One can do this in the `.fweb' file (see section CUSTOMIZATION) or with the language-setting command in limbo, as in `@n/'.

    In @FWEB{}, one may always use `\/' for concatenation, so there's no penalty for using `-n/'.

    `-n!': Make `!' denote short comment [FORTRAN]

    In FORTRAN-90, `!' starts a short comment. However, by default @FWEB{} usurps `!' for the logical not, as in `if(x != y)'. To force it to recognize `!' as a comment, use `-n!'. However, the recommended style is to use @FWEB{}'s standard convention that `//' denotes the start of a short comment (see section `-n/': Recognize short comments [FORTRAN]). See also section `-!': Make `!' denote short comment (FORTRAN & RATFOR) and section `-r!': Make `!' denote short comment [RATFOR].

    In FORTRAN-77, to include the exclamation point inside a string, escape it with a backslash, as in

            s = "A \! inside a string"
    

    This possibly annoying restriction arises because the unduly complicated FORTRAN input driver does some preprocessing of the FORTRAN source before it feeds it to the cores of the processors.

    `-n)': Reverse array indices [FORTRAN] (@FTANGLE{})

    This somewhat experimental flag permits FORTRAN programmers to use C-style array indices. Conversions such as the following are made (during the output phase of @FTANGLE{}):

    a(k)(i) => a(i,k)
    a(k)(i,j) => a(i,j,k)
    a(k)(j)(i) => a(i,j,k)
    

    [No spaces may intervene between `)' and `('; effectively, `)(' is treated as one token for the purposes of `-n)'.] This feature permits convenient definitions of macros that deal with multi-dimensional vectors.

    Unfortunately, @FTANGLE{} doesn't fully understand the syntax of the source code--and never will, unless it is fully integrated with a compiler. It will therefore be confused by situations like the following FORTRAN example:

    dimension x(0:4)(1:2) // OK
    character*90 ch(4) // OK
    write(6,*) ((x(i)(j),i=1,2), j=3,4) // Will reverse incorrectly.
    c = ch(4)(3:4) // Shouldn't reverse, but will.
    

    One solution, due to Charles Karney, is to insert a space to prevent `)(' from being recognized as a single token. However, since ordinary white space is eaten on input, one must resort to something like the following (`$UNQUOTE' is a built-in @FWEB{} function; see section $UNQUOTE: Remove quotes from string):

    @m SP $UNQUOTE(' ')
    @a
    dimension x(0:4)(1:2)
    character*90 ch(4)
    write(6,*) SP ((x(i)(j),i=1,2), j=3,4)
    c = ch(4)SP(3:4)
    

    This option is controlled by the three style-file parameters `paren.len', `paren.num', and `paren.nest'. (See section The Style file.) `paren.len' is the default number of bytes to be allocated for each index; if an index is longer than this number, the current length is increased by this number and storage is automatically reallocated. `paren.num' is the maximum number of allowed indices; for example, when processing `a(i)(j)(k)', `paren.num' is 3. `paren.nest' is the maximum parenthesis nesting level. In the example `x(a(i)(j)(k))', `paren.nest' is 2. If either of the last two parameters is exceeded, a message will be issued asking you to increase the appropriate value.

    `-o': Don't overload operators

    This option inhibits the operator-overloading feature invoked by the command `@v' (see section Overloading operators and identifiers).

    `-q': Don't translate RATFOR

    (This option is obsolete.)

    `-P': Select TeX processor

    Say `-PT' or `-PL' to inform @FWEAVE{} that its output will be processed by TeX or LaTeX, respectively. Beginning with Version 1.50, the default processor is LaTeX (`-PL'). If you always use TeX, it's easiest to put `-PT' into the `.fweb' initialization file.

    Please note that `-PT' is no longer supported; @FWEB{ development is now based exclusively on LaTeX.}

    `-p': Buffer up a style-file entry

    This option specifies a style-file entry (see section The Style file). Its argument is exactly the same as a line that one may put into the local @FWEB{} style file. Thus, if in `fweb.sty' one would say `entry="value"', the form of the `-p' option would be `-pentry='"value"''. (The single quotes are required on a UNIX system because the double quotes have special significance to the shell.)

    This option can be used either in the `.fweb' initialization file (see section Initialization), to record style-file entries that are common to all runs, or on the command line, to override a local style-file entry for a single run. This behavior is a consequence of the following order of processing style parameters:

    1. `-p' options in `.fweb';
    2. entries in the local style file `fweb.sty';
    3. `-p' options on the command line.

    `-r': Set global language to RATFOR--77

    See section LANGUAGES and section RATFOR. See also section `-L': Select global language.

    `-r9': Set global language to RATFOR--90

    See section LANGUAGES and section RATFOR. See also section `-L': Select global language.

    `-rg': Set goto parameters

    This obscure option is used for configuring RATFOR (and really should be a style-file parameter). (Discussion not finished.)

    `-rk': Suppress comments about RATFOR translation (@FTANGLE{})

    By default, the RATFOR translator writes comments about what command it is translating. The `-rk' option suppresses those comments. Arguments to this option allows one to suppress comments about only particular commands, according to the following list:

    b --- break
    c --- case
    t --- default
    d --- do
    f --- for
    i --- if
    n --- next
    p --- repeat, until
    r --- return
    s --- switch
    h --- where
    w --- while
    

    For example, one can say `-rkrb' to suppress comments about the return and break statements.

    `-rK': Write comments about RATFOR translation (@FTANGLE{})

    This is the negative of `-rk' (see section `-rk': Suppress comments about RATFOR translation (@FTANGLE{})); it forces comments about particular RATFOR commands.

    `-r@;': Turn on auto-semi mode using pseudo-semis [RATFOR]

    Please don't use this option (it may not work). Insert semicolons by hand in your RATFOR code, just as one does in C.

    `-r;': Turn on auto-semi mode using actual semis [RATFOR]

    Please don't use this option (it may not work). Insert semicolons by hand in your RATFOR code, just as one does in C.

    `-rb': Number ifs and dos [RATFOR]

    In the woven output, extra comments are added to help one correlate the block structure of the code. For more discussion, see section `-b': Number blocks (@FWEAVE{}).

    `-r/': Recognize short comments [RATFOR]

    The standard @FWEB{} notation for a short comment is `// ...'. However, in RATFOR the `//' denotes concatenation by default. To make it denote a short comment, use the `-r/' option. For concatenation, use `\/'.

    For an example, see section `-n/': Recognize short comments [FORTRAN].

    `-r!': Make `!' denote short comment [RATFOR]

    See the corresponding discussion of `-!' in section `-!': Make `!' denote short comment (FORTRAN & RATFOR) and section `-n!': Make `!' denote short comment [FORTRAN].

    In FORTRAN-77, to include the exclamation point inside a string, escape it with a backslash, as in

            s = "A \! inside a string"
    

    `-r)': Reverse array indices [RATFOR] (@FTANGLE{})

    See the corresponding discussion of `-n)' in section `-n)': Reverse array indices [FORTRAN] (@FTANGLE{}).

    `-s': Print statistics

    `-s' prints statistics about memory usage at the end of the run.

    `-sm' prints statistics about memory usage at the end of the run, just as does `-s'; it also prints information about dynamic memory allocations as they occur. `-smnnn' displays allocations of nnn bytes or more; if nnn is missing, 10000 is assumed.

    `-T': Flag-setting options for @FTANGLE{}

    This is a family of options that set miscellaneous flags appropriate only for @FTANGLE{}.

    `-TD': Permit processing of deferred macro definitions

    Deferred macro definitions are `@m' (or, equivalently, `@#define') commands that appear in the code part rather than the usual definition part. These definitions are evaluated during the output (phase 2), and can cause confusion when used with the preprocessor commands, which are evaluated during the input (phase 1). Because of this confusion, deferred macro definitions are prohibited by default. To permit them, use the `-TD' option (then be prepared to make some obscure programming errors).

    `-Tb': Permit built-functions to be redefined

    By default, built-in functions such as $IF (see section Built-in functions) may not be redefined by an @m command. To allow this extremely dangerous operation, use the `-Tb' option.

    `-Tm': Permit user macros to be redefined

    By default, user macros may not be redefined by an @m command. To permit this, use the `-Tm' option. Note that many functions described under section Built-in functions, such as $PI, are in fact implemented as macros.

    `-Tv': Don't print header info

    By default, @FTANGLE{} attempts to be helpful and writes some information about the command line, input and change files, etc. at the beginning of the output file. This information can be deleted by means of the `-Tv' flag. [This is done automatically when the `-F' flag (see section `-F': Compare output files with old versions (@FTANGLE{})) is in effect, since the header information includes a time stamp that would defeat a successful file comparison.]

    `-T%': Don't retain trailing comments (TeX)

    Unless the `-v' option is used, comments are generally deleted by @FTANGLE{} as it writes the output file. However, in the TeX language such deletions can change the behavior of the output (by introducing extra spaces). Therefore, TeX comments that do not begin a line are always retained unless the `-T%' option is used. This option has no effect for languages other than TeX.

    `-T#': Don't insert `#line' command after `@%'

    If the `@%' command (see section `@%': Ignorable comment) is used to comment out a line, it eats the trailing newline. An undesirable consequence of this is that, if nothing is done, the subsequent line numbering will be misunderstood by a debugger, at least until @FWEB{} inserts a `#line' command for some reason. To prevent this, @FWEB{} inserts by default an implicit `@#line' command (see section Preprocessing) after each `@%' that begins a line. To prevent this from happening (possibly because the feature doesn't work correctly, in which case you should report it; see section SUPPORT), use the `-T#' option.

    `-t': Truncate identifiers

    The truncation option enables one to use a wider character set for identifiers than the language compiler will accept. The standard example is vanilla-flavored FORTRAN-77, which doesn't allow the underscore. If one says ``-tn6{_}'', underscores will be removed from all identifiers, then the result will be truncated to length 6. If the truncation procedure results in non-unique identifiers, these are listed.

    `-U': Convert reserved output tokens to lower case (@FTANGLE{})

    Particularly during RATFOR expansion, certain tokens such as `DO' are output by @FTANGLE{} in upper case. The `-U' option forces such tokens to be produced in lower case.

    `-u': Undefine @FWEB{} macro (@FTANGLE{})

    `-uA' undefines the @FWEB{} macro `A' previously defined on the command line (or in `.fweb') via `-m'.

    CAUTION: This option can also undefine built-in functions such as $IF. Don't do that, since built-ins can use other built-ins behind the scenes; undefining one can cause very strange behavior.

    `-V': Print @FWEB{} version number

    This flag requests the startup banner, which includes the @FWEB{} version number, to be printed. This is usually done anyway, so it is only relevant when the message level is 0 (see section `-M': Set output message level).

    `-v': Make all comments verbatim (@FTANGLE{})

    By default, comments are not passed to the tangled output. With `-v', all comments are included verbatim in the tangled output. Since there's generally no harm in this, one might want to put this option into `.fweb' (see section Initialization).

    `-W': Flag-setting options for @FWEAVE{}

    This is a family of options that set miscellaneous flags appropriate only for @FWEAVE{}. Options such as `-W[' and `-Wf' can be combined as `-W[f'.

    `-W@': Set module warning flag.

    @FWEAVE{} can check module names for the possible anomalous conditions of "never used" or "multiple uses." These correspond to a module warning level, as in the following numbered list:

    1. Never used.
    2. Multiple uses.

    The module warning flag is the bitwise OR of the desired warning levels; warning messages are printed only when the relevant bits are turned on. By default, it is 1, so only messages about never-used modules are printed. The `-W@flag' overrides the default. For example, to get messages only about multiple uses, say `-W@2'; to get no messages, say `-W@0'. One can put such an option into the `.fweb' initialization file (see section Initialization).

    @FWEAVE{} will always complain about module names that are never defined.

    `-W1': Cross-reference single-character identifiers

    By default, @FWEB{} does not index uses of single-character identifiers (following Knuth's original design). (It does index their definitions.) To get complete cross-reference information for single-character identifiers, use the `-W1' option.

    `-W[': Process bracketed array indices

    This experimental option makes square brackets behave like parentheses in the context of array indices.

    In FORTRAN, @FTANGLE{} will just replace the brackets by parentheses. In C, the brackets will be left alone.

    @FWEAVE{}, however, will typeset the indices according to the `fwebmac.sty' macro `\WARRAY'. This macro takes one argument, which is just the array index or indices. (In C, indexing like `a[i][j][k]' generates the argument `i,j,k'.) By default, `\WARRAY' just surrounds its argument with brackets. However, the user may change its definition to get special effects such as superscripted or subscripted indices. A simple example macro `\WSUB' is provided in `fwebmac.sty'; one can say `\let\WARRAY\WSUB' in the limbo section to have bracketed indices print as subscripts.

    This feature may not work when the contents of the brackets are too complicated (so that @FWEAVE{} tries to typeset them by going in and out of math mode).

    For more information, experts can see `fwebmac.web', command \WXA.

    `-WH': Send additional arguments to the C preprocessor

    When the `-H' option (see section `-H': Scan C/C++ include files (@FWEAVE{})) is used, the C preprocessor is invoked to scan include header files for typedef's and class declarations. That is called with a standard set of options. (Presently, gcc is actually called to invoke the preprocessor; it is sent the options `-E', `-P', and `-I'.) Occasionally it may be necessary to send additional options. Those can be specified as the (string) argument to `-WH'. Thus, to define two macros to the preprocessor, one could say either of

    -WH-Dtest1=1 -WH-Dtest2=2
    -WH"-Dtest1=1 -Dtest2=2"
    

    The first form shows that `-WH' accretes to earlier uses. The second form shows how to handle embedded blanks (in a UNIX shell). Then, if one were programming in C, use of `-H' would issue the system command

    gcc -E -P -Dtest1=1 -Dtest2=2
    

    `-WdfFlmvw': Don't print various things in woven output

    The printing of selected definition-part commands can be suppressed as follows:

    -Wd --- outer definitions (`@d' or `@D')
    -Wf --- format statements (`@f')
    -WF --- format statements (`@F')
    -Wl --- limbo text definitions (`@l')
    -Wm --- FWEB macro definitions (`@m' or `@M')
    -Wv --- operator overloads (`@v')
    -Ww --- identifier overloads (`@w' or `@W')
    

    When these options used, associated cross-referencing is suppressed as well.

    `-w': Change name of macro package (@FWEAVE{})

    The option `-w' means "Don't print `\input fwebmac.sty' as the first line of the `.tex' output file." The option `-wfname' means "Print `\input fname' as the first line." For example, when working with REVTeX (see section Using REVTeX), one needs to say `-wrwebmac.sty'.

    This option can be used for special effects when one is trying to obtain behavior different from that defined by @FWEB{}'s macro package `fwebmac.sty' (see section The macro package `fwebmac.sty'). However, try to not do that. Please submit requests for such behavior modifications to the developer; see section SUPPORT.

    `-x': Eliminate or reduce cross-reference information (@FWEAVE{}).

    Cross-reference information (for @FWEAVE{}) includes the Table of Contents ('c'), the Index ('i'), and the Module List ('m'). The option `-x' eliminates all of that information. The option `-xletters' eliminates the piece of information corresponding to each letter in the list. For example, `-xim' eliminates the Index and the Module List.

    Another possibility is to say `-xu', which prevents cross-references from unnamed sections (begun with `@a' or `@A') from appearing in the Index.

    `-X': Print selected cross-reference information (@FWEAVE{})

    When used with any of the arguments `cim', this option is the opposite of `-x'. See section `-x': Eliminate or reduce cross-reference information (@FWEAVE{})..

    The option `-XI' tells @FWEAVE{} to write its index cross-references to a file formatted for input by the makeindex utility. This feature facilitates creation of a master index that spans several individual web files. For more discussion, see section Creating a stand-alone index with makeindex.

    The construction `-XI' stands alone; one may not mix the `I' with the list `cim'. Also, this option is overridden by `-xi', which suppresses output of all index information.

    `-y': Allocate dynamic memory

    This option changes the default size for a dynamically allocated memory buffer. The buffers are indicated by a one- or two-character abbreviation such as `op'. For example, the option `-yop200' allocates 200 units for the `op' buffer.

    To query the default allocations, just say `-y'.

    When @FWEB{} runs out of space, it usually (but not always) issues a message telling one which `-y' command to use in order to increase the allocations. (Someday it will reallocate automatically.) One may wish to add some such options to the `.fweb' file.

    For a more detailed discussion of memory allocation and a menu of the various dynamic arrays, see section Memory allocation.

    `-Z': Display default style-file parameters

    The information option `-Zabc' prints to the screen the default contents of the style-file parameters beginning with `abc'. Just `-Z' prints everything.

    After printing the defaults, the `-p' options (see section `-p': Buffer up a style-file entry) and the style file `fweb.sty' are processed. If that processing has overridden any of the defaults, the parameters are printed again, preceded by an asterisk.

    To see only the parameters that have been modified from the defaults, say `--Z'.

    The `-Z' option behaves slightly differently for color escape sequences than for other parameters; see section Color output.

    `-z': Change name of style file

    The command `-znew.sty' changes the default style-file name `fweb.sty' to `new.sty'. The command `-z' (with no argument) means "Don't read any style file."

    Normally the style file is read from the same directory in which the web source file resides (or from the path defined by the environment variable FWEB_STYLE_DIR). To force fweb.sty to be read from the current directory, say `-z.'.

    `-.': Don't recognize dot constants

    If this command is used, the processors will not understand that constructions such as `.LT.' are operators in FORTRAN or RATFOR. This command is useful if one is trying to modernize the source code to use @FWEB{} conventions such as `<' instead of `.LT.'.

    `-\': Explicitly escape continued strings

    In @FWEB{}, long strings are continued with the backslash. Normally, the continuation of the string must start in the first column of the next line; otherwise, spurious blanks will be introduced. However, when the `-\' option is in effect, @FWEB{} expects that the continuation will also begin with the backslash, and it will ignore leading white space and the backslash. (This feature was inspired by FORTRAN-90.) Thus, in the example

    "This is \
          \continued";
    

    the effective string is "This is continued" when `-\' is in effect.

    Note that this option affects all strings in the source file; one cannot mix and match.

    `-(': Continue parenthesized strings with backslashes

    This option is like `-\' (see section `-\': Explicitly escape continued strings), but it refers to certain strings that are not normally quoted, such as the arguments of `ifelse' commands in m4.

    `-:': Set starting automatic statement number

    This option is useful for FORTRAN and RATFOR. Symbolic statement labels that are defined with the `#:0' macro command (section Special tokens; section Special considerations for FORTRAN), as in `@m EXIT #:0', are incremented starting with the default of 90000. To change this to, e.g., 789, say `-:789'.

    `->': Redirect output (@FTANGLE{})

    This changes the name of @FTANGLE{}'s output file. If no name is given, output is redirected to the terminal.

    This command has no effect for @FWEAVE{}.

    Although the appearance of this command is highly intuitive, it may be hard to type quickly. An equivalent command is `-=' (see section `-=': Redirect output (@FTANGLE{})).

    `-=': Redirect output (@FTANGLE{})

    Equivalent to `->' (see section `->': Redirect output (@FTANGLE{})), and faster to type on many keyboards.

    `-#': Turn off comments about line and section numbers (@FTANGLE{})

    By default, tangled output includes comments about the line and section numbers corresponding to the current piece of code. To eliminate this clutter, say `-#'. (But note that the line-number information is very useful for debugging in C and C++, as it enables the debugger to display the source line in the web file.)

    In some cases, bugs in tangled output, particularly from FORTRAN, can be eliminated by using `-#'. (But please report the bug anyway; section SUPPORT.)

    In some cases, it is useful to turn off the line- and section-number information locally. This can be done with the `@q' command. See section `@q': Turn off module and line info locally.

    `-+': Don't interpret compound assignment operators

    Both RATFOR and FORTRAN attempt to translate the commands `++', `--', `+=', `-=', `*=', and `/=' into code that behaves as their C/C++ counterparts. To turn this feature off, use `-+'.

    Notice that in FORTRAN-90 `/=' is a token for "not equal," so if you want to use that you must turn off the compound assignment operators with use `-+'. However, a better solution is to leave them turned on and use @FWEB{}'s standard `!=' token for "not equal."

    See also section `-ylx': Maximum length of expressions that can be expanded with the post-increment operators of FORTRAN or RATFOR.

    `-/': Recognize short comments (FORTRAN & RATFOR)

    If this command is not used with the FORTRAN-like languages, the `//' construction will be interpreted as concatenation rather than as the beginning of a short comment.

    Concatenation can be signified with @FWEB{}'s token`\/', so no penalty is incurred for using `-/'.

    One way of invoking this option is with the global language command, such as `@n/'. Another is to put the command into the initialization file `.fweb'.

    See also section `-n/': Recognize short comments [FORTRAN] and section `-r/': Recognize short comments [RATFOR].

    `-!': Make `!' denote short comment (FORTRAN & RATFOR)

    This option is not recommended; use @FWEB{}'s standard `//' to begin short comments.

    To include the exclamation point inside a string, escape it with a backslash, as in

            s = "A \! inside a string"
    

    Information options

    Several of the command-line options can be used to elicit information about the initial state of @FWEB{}.

    `-@' displays information about the control codes. See section `-@': Display the control-code mappings.

    `-D' displays information about reserved words. See section `-D': Display reserved words.

    `-y' displays default dynamic memory allocations. See section `-y': Allocate dynamic memory.

    `-Z' displays default values of style-file parameters. See section `-Z': Display default style-file parameters.

    The `-h' option reminds one about these information options; it also provides convenient access to the GNU info browser. See section `-h': Get help.

    @FWEB{} COMMANDS

    All @FWEB{} commands begin with the character `@'. It is recommended that these begin in column 1 if possible. This is required in some cases [e.g., the `@x', `@y', and `@z' in change files (see section Change files), or column-oriented FORTRAN-77 processing].

    Some of these control codes may be used anywhere; others begin a new part of the current section. (For a discussion of sections and parts, see section The structure of a web.) For a quick summary of the control-code mappings and to see which codes begin new parts, say `ftangle -@'. See section `-@': Display the control-code mappings.

    Debugging commands

    Several commands provide localized versions of the `-1' and `-2' options related to debugging of pretty-printing.

    `@0': Turn off debugging

    This cancels the effect of a previous `@1' or `@2' (see section `@1': Display irreducible scraps and section `@2': Display detailed reductions of the scraps). The `@0' command should appear in a different section from the `@1' or `@2' commands.

    `@1': Display irreducible scraps

    This is a local version of the command-line option `-1' (see section `-1': Turn on brief debugging mode (@FWEAVE{})); refer to that discussion for more information.

    `@2': Display detailed reductions of the scraps

    This is a local version of the command-line option `-2' (see section `-2': Turn on verbose debugging mode (@FWEAVE{})); refer to that discussion for more information.

    Literal control characters

    Several commands insert specific characters.

    `@@': The character `@'

    `@@' inserts the single character `@'.

    Don't forget to double the `@' even inside strings. For example, the @FWEB{} source line

    puts("'@@' is represented by `@@@@'");
    

    will be tangled to

    puts("'@' is represented by `@@'");
    

    `@|': Literal vertical bar, or optional line break

    In the TeX (documentation) part of a section, `@|' inserts a vertical bar. This is useful inside LaTeX verbatim environments. (A simple bar would signal a shift into code mode, which is probably not what one wants.) For an example, see section `@|': Literal vertical bar, or optional line break.

    In a code part, `@|' inserts an optional line break in an expression--e.g.,

    `f(a,b,@|c+d,...)'.
    

    This helps TeX to break the line at an appropriate place. If the line does not need to be broken, the command does nothing. [Compare `@|' with `@\' (see section `@\': Force a line break, then indent) and `@/' (see section `@/': Force a line break, preserving indentation.), which always break the line.]

    Beginning of section

    Sections are begun by either `@*' or @ASP{}.

    `@ ': Begin minor section

    @ASP{} begins a new minor (unstarred or unnamed) section that is not entered into the Table of Contents. For example,

    @ This is an example of a minor (unnamed) section.  (No entry is made
    in the Table of Contents.)
    
    @a
    main()
    {}
    

    `@*', `@*n': Begin major section

    `@*' begins a new major (starred) section (of level 0). The command must be followed by the name of the section (entry in the Table of Contents), followed by a period. (If a period appears in the name itself, it must be protected by braces.)

    The section name is also used as a running head on the output pages. To deal with the possibility that the full name may be too long, the section name may be preceded by an optional argument enclosed in brackets. If it is present, the optional argument is used as the running head. (If a period appears as part of the optional argument, it must be protected by braces.)

    If `@*' is followed by a digit n, it begins a new major (sub)section of level n. This is also entered into the Table of Contents. Thus, the complete syntax to begin a major section is

    @*n [Short name]Full name.
    

    For example,

    @* MAIN PROGRAM.  This begins a major section (of level 0).
    
    @a
    main()
    {}
    
    @*1 [Input routines\dots]A very long section name that essentially
    means ``input routines.''  Now follow some subroutines. 
    
    @a
    get_input()
    {}
    

    For LaTeX, the highest permissible major level is 2 (a subsubsection).

    Section names can contain reasonably arbitrary TeX text, including font-changing commands and other macros. However, it is necessary to understand that fragile commands (in the sense of LaTeX) may not work because the section name is used in various contexts (e.g., as a page header). If a macro in a section name doesn't work properly, try preceding it with `\protect'.

    @FWEAVE{} converts `@*' commands to section numbers. For a discussion of section numbering, see section Section numbering schemes.

    Beginning of code part

    The code part is begun by the appearance of either `@a' or `@< Module name @>='.

    `@<': Begin module name

    `@<' begins a module name, which has the form `@< TeX text @>'. (Module names inside @FWEB{} macro definitions begin with `@#', not `@<'.)

    `@>': End module name

    `@>' ends a module name, of the form `@< TeX text @>'.

    Technically, `@>' is not a command; rather, it is a delimiter that terminates `@<'. An unmatched `@>' is simply ignored (after a warning message is issued).

    `@A': Begin code part of unnamed section

    `@A' begins the code part of an unnamed section. For example,

    @ In an unnamed section, the code part begins with `@a' or `@A'.
    @A
    main()
    {}
    

    For more discussion of the distinction between `@A' and `@a', see section `@a': Begin code part of unnamed section, and mark.

    `@a': Begin code part of unnamed section, and mark

    `@a' begins the code part of an unnamed section (just as does `@A'), and in addition marks the next unreserved identifier it finds as defined in this section. Precisely,

    `@a' == `@A@['
    

    Originally, @FWEB{} did not contain the `@A' command, so when the functionality of automatically marking the next unreserved identifier (see section Forward referencing) was added, it was natural to add it to `@a'. A reasonable style of coding is to always use `@a' if you don't know any better; if you sometime run into trouble, you can then change selected `@a's to `@A's. For example, it is appropriate to use `@a' if one codes one function per section. E.g.,

    @c
    @ 
    @a
    int
    subrtn()
    {}
    

    Here the `@a' marks `subrtn' as defined in this section; if that identifier is used elsewhere, it will be subscripted with the section number. (To turn this feature off, use `-f'; see section `-f': Turn off module references for identifiers (@FWEAVE{}).) However, if a section contains an arbitrary code fragment, the code part should probably begin with `@A'. E.g.,

    @c
    @
    @A
    x = y;
    

    If one had used `@a' here, the x would have been marked as defined here, which is not what one wants.

    Control codes b--z

    `@B': Suppress insertion of breakpoint command

    This is for detailed debugging of @FWEB{} codes. It inserts a left brace and suppresses the insertion of a breakpoint command. See the discussion of `@b' in section `@b': Insert a breakpoint command.

    `@b': Insert a breakpoint command

    (Discussion to be finished. Useful only for very intimate debugging of @FWEB{} codes. In these days of safe sex, such intimacy may not be desirable.)

    See also section Control codes b--z.

    `@c': Set language to C

    The command `@c' is a shorthand for `@Lc'. For a discussion of language commands in limbo, see section `@L': Set language.

    See section LANGUAGES and section Special considerations for C.

    `@c++': Set language to C++

    The command `@c++' is a shorthand for `@Lc++'. For a discussion of language commands in limbo, see section `@L': Set language.

    See section LANGUAGES and section Special considerations for C++.

    `@D': Define outer macro

    This command begins the definition part.

    `@D' defines an outer macro. For more discussion, see section Outer macros. For example, in C

    @D A 1
    

    will be tangled to the beginning of the output file as `#define A 1'.

    `@d': Define outer macro, and mark

    This command begins the definition part.

    `@d' defines an outer macro (just as `@D' does), and also marks the next identifier as defined in the present section. It is equivalent to

    `@d' == `@D@['

    (see section Forward referencing).

    The distinction between `@d' and `@D' is analagous to the distinction between `@a' and `@A'. See section `@a': Begin code part of unnamed section, and mark.

    `@E': Treat next identifier as ordinary expression (@FWEAVE{})

    For formatting purposes, treat the next identifier as an ordinary expression.

    This command is useful in pretty-printing certain kinds of macro constructions. Further discussion is given in @xref{Macros and formatting}.

    `@f': Format identifier or module name

    This command begins the definition part.

    The construction

    @f identifier old_identifier
    

    makes @FWEAVE{} treat identifier like old_identifier. For example,

    @f mytype int
    

    says to treat the variable mytype just as int is treated (e.g., as a reserved word in C or C++).

    Traditionally, C programmers needed to use this command to format identifiers that were defined in #include files. This annoying redundancy has now been eliminated by means of the `-H' command, which tells @FWEAVE{} to scan #include files automatically. See section `-H': Scan C/C++ include files (@FWEAVE{}).

    The old_identifier may be one of the following special names, which insert extra spaces according to the positions of the underscores and behave as the part of speech indicated by the base names:

    $_BINOP_
    $_COMMA_
    $_EXPR
    $_EXPR_
    $EXPR_
    $UNOP_
    

    These are useful for dealing with certain macro constructions. For example,

    @f PLUS $_BINOP_
    @m PLUS +
    @m ADD(x, y) ((x) PLUS (y))
    

    Without the format command, the `ADD' macro will pretty-print without spaces before and after the `PLUS'.

    When the current language is TeX, the format command can be used to change a category code according to the format

    @f `TeXchar new_cat_code
    

    Difficulties may ensue if one try to change the category code of `@' in this way; a fully operational WEB for TeX is quite difficult and has been neither accomplished nor attempted.

    `@i': Include file (unconditional)

    If one says

    @i test.hweb
    

    the file `test.hweb' is inserted at the present point of the web file. By default, the current directory is searched. Files can be included from other directories by means of the FWEB_INCLUDES environment variable and/or the `-I' command-line option. See section Environment variables and section `-I': Append to search list for include files.

    In principle, the included file may contain any fragment of source text. However, it is best to make it a complete section (begun by `@*' or @ASP{}) if at all possible.

    Unfortunately, the `@i' command cannot be commented out or conditionally included by use of an @FWEB{} preprocessor command. That is because `@i' is processed very early in the parsing process. (Consider: `@i' could include TeX text, but the preprocessor is only active in the definition and code parts.)

    Include commands may be nested to a depth set by the option `-yid'. See section `-yid': Maximum depth of file inclusion.

    In the woven output, if a section comes from an include file, the name of the include file is printed in square brackets as the first text of the TeX part. To inhibit printing of that name, say

    \def\WIF#1{}
    

    in the limbo section. To change the way that name is formatted, redefine the macro `\WIFfmt', whose single argument is the name of the include file. (It is not called when there is no current include file.) The default definition is

    \def\WIFfmt#1{[{\tt#1}]}
    

    `@I': Include file (conditional)

    This command behaves like `@i' if the command-line option `-i' is not used. If it is used, then the contents of the included file is not printed in the woven output. See section `-i': Don't print `@I' include files (@FWEAVE{}) and section @samp{-i!}: Don't read @samp{@I} include files.

    `@K': Extract global RCS-like keyword

    The construction `@K Keyword @>' accesses the value of a global RCS-like keyword. (For more discussion of such keywords, see section `@z': Begin ignorable material, or terminate change.) The command is treated differently by @FTANGLE{} and @FWEAVE{} depending on its location in the source file.

    @FWEAVE{} will expand the construction in the limbo section and TeX parts only. The value is not surrounded by quotes. For example,

    @z
    $Id:  test $
    @x
    
    @c
    
    \def\ID{Id = \.{"@K Id @>"}}
    
    @ \ID.  This is a @K Id @>.
    

    will expand into

    @c
    
    @ \ID.  This is a test.
    

    and when LaTeX is run the macro \ID will expand to `Id = \.{"Test"}'. The quotes are not necessary in the macro definition; they are included only to emphasize that in this (limbo) context the `@K' construction can effectively be put inside a string. This is possible because the routine that copies the limbo section simply copies characters; it does not tokenize anything.

    @FWEAVE{} does not expand `@K' constructions in the definition or code parts; it merely gives them a symbolic representation.

    @FTANGLE{}, on the other hand, expands `@K' constructions in the definition or code parts (during input). The values are surrounded by quotes. (As usual, @FTANGLE{} ignores material in the limbo section and TeX parts.)

    For @FTANGLE{}, the built-in function `$KEYWORD' (see section $KEYWORD: Value of global RCS-like keyword) behaves essentially as does `@K', except that it is expanded during output, not input. @FWEAVE{} does not expand `$KEYWORD'.

    The command `@k' behaves as does `@K' except that it accesses local keywords, not global ones. See section `@k': Access local RCS-like keyword.

    `@k': Access local RCS-like keyword

    The construction `@k keyword' behaves as `@K' does (see section `@K': Extract global RCS-like keyword), except it accesses local keywords (defined at the top of include files).

    `@L': Set language

    `@Ll' sets the language to l, where l is one of `{c,c++,n,n9,r,r9,v,x}'. See section LANGUAGES.

    There are shorthand forms of this command for some languages; see `@c' (section `@c': Set language to C), `@c++' (section `@c++': Set language to C++), `@n' (section `@n': Set language to FORTRAN--77), `@n9' (section `@n9': Set language to FORTRAN--90), `@r' (section `@r': Set language to RATFOR--77), and `@r9' (section `@r9': Set language to RATFOR--90).

    Generally, the global language should be set in the limbo section by means of `@L', `@c', etc. rather on the command line by options such as `-L' or `-c'.

    `@l': Specify limbo text

    This command begins the definition part.

    Limbo text is material that @FWEAVE{} should output before the start of the first section. For example,

    @l "\\def\\A{abc}"
    

    Note that `\\' stands for a backslash. In general, characters must be escaped just as in C [so that one can include things like `\n' (newline) in the definitions].

    Limbo text may also be typed directly into the limbo section; in that case, no escapes are necessary since one is typing ordinary TeX text. Sometimes, however, the `@l' command is useful for pedagogical purposes, as the limbo material can then be defined at the point where the logical discussion is made.

    `@M': Define @FWEB{} macro

    This command begins the definition part.

    For a detailed discussion of @FWEB{} macros, see section MACROS and PREPROCESSING.

    `@m': Define @FWEB{} macro, and mark

    This command begins the definition part.

    `@m' defines an @FWEB{} macro, and also marks the next identifier as defined here. It is equivalent to

    `@m' == `@M@['

    (see section Forward referencing).

    For a detailed discussion of @FWEB{} macros, see section MACROS and PREPROCESSING.

    The distinction between `@m' and `@M' is analagous to the distinction between `@a' and `@A'. See section `@a': Begin code part of unnamed section, and mark.

    `@N': Turn on N mode

    This command must appear before the code part. Generally, this means immediately before `@a'. Do not use this command in limbo; use `@Lv' instead.

    The N mode invokes language-independent behavior within the scope of a particular language. The scoping rules are the same as for language changes; i.e., using `@N' within a given section produces language-independent behavior for that section and for any modules first referenced in that section.

    Fundamentally, language-independent behavior essentially means a literal transcription of the input to the output. For example, it inhibits blank compression by @FTANGLE{} and tells @FWEAVE{} to turn off "pretty-printing" (instead, the output is printed in typewriter type within a `\begin{verbatim}...\end{verbatim}' environment).

    There are some subtleties with this mode (not to mention the likelihood of bugs):

    1. @FWEB{} macros and built-in functions will normally be expanded even in the N mode. To inhibit expansion of a particular identifier, place `@!' before the identifier. For example,
      @
      @m A 1
      @N
      @a
      @!A = A;
      
      expands to `A = 1'.
    2. Blank lines are significant. The N mode is ended by the appearance of the `@*' or @ASP{} denoting the start of the next section. If that were preceded by one or more blank lines, those would show up in both the tangled and woven output. They might or might not be significant in the tangled output, but they almost certainly will look ugly in the woven output. To avoid this, use the command `@%%', which deletes the remainder of the current line and all immediately following empty lines. For example,
      @
      @N
      @a
      x;@%%
      
      @ Next section.
      
    3. If the N mode is invoked from a compiler-like language such as FORTRAN, cross-referencing of variables is done as usual. However, if the language is VERBATIM (which turns on the N mode automatically), no cross-referencing is done. (Identifiers are still recognized according to @FWEB{}'s rules. Those rules as currently implemented may be essentially meaningless for some languages; in the future, provision may be made for generalizing these rules by the user.) To force an identifier to be placed into the Index, precede it by `@+'.
    4. A module name must be within the scope of an `@N' the first time the name is seen, if it is ever to be within such scope. Thus, the following does not work properly:
      @ Consider the module @<Test@>.  (Not yet within scope of \.{@N}.)
      @N
      @a
      x;
      @<Test@>@;
      y;
      
      What happens is that the N mode is not restored after the code-part use of `@<Test@>'. This is a bug. There are very tricky design issues to be dealt with here.

    `@n': Set language to FORTRAN--77

    FORTRAN-77 is @FWEB{}'s default language, so this command is usually not strictly necessary. However, it is good practice to include it, so a user looking at the web file can tell immediately what language it is supposed to process.

    For more discussion of languages, see section `@L': Set language and section LANGUAGES.

    `@n9': Set language to FORTRAN--90

    For more discussion of languages, see section `@L': Set language and section LANGUAGES.

    For hints about @FWEB{} programming in FORTRAN, see section Special considerations for @sc{Fortran}.

    `@O': Open output file (global scope)

    A statement of the form

    @O new_output_file_name
    

    changes the name of @FTANGLE{}'s output file. This change remains in effect for the duration of the file, or until another `@O' is encountered. (If that occurs, the previously open file is closed.)

    This command is expanded during output, so it must appear in the code part.

    For an example of using the `@O' command to produce both C header files (`.h') and source files (`.c'), see the discussion in section Outer macros.

    To change the name of the output file locally (for just the present section), see section `@o': Open output file (local scope).

    `@o': Open output file (local scope)

    This behaves like `@O', except that the new file name is in effect only for the current section. A subsequent `@o' issued in a different section but for the same file name accretes material to the file.

    An annoying problem arises in C programming when `@o's are used to create multiple source files that are subsequently compiled under the control of a Makefile. Remember that by default line-number information is written into the C files. This means that a change in the web file code for one source file can affect all of the others, because the line numbering in the web file changes. Therefore, a trivial change to the code for just one source file can cause all of the others to be recompiled.

    As long as one desires debugging information relative to the original web file, there is really no solution to this problem; one needs the proper line information in each file in order to work with the debugger, so if line numbers change the sources must be recompiled. One can, of course, turn off the line numbering with the command-line option `-#' (see section `-#': Turn off comments about line and section numbers (@FTANGLE{})), but then debugger statements will refer to the tangled C code, which is undesirable. A better partial solution is to use `@q' (see section `@q': Turn off module and line info locally) to turn off the line numbering for output code that is currently stable. In the following example, the code for each file is put into a module, then the modules are output in the unnamed section; it is assumed that the programmer is currently making changes to the code for `file2.c':

    @
    @a
    @q0
    @o file1.c
            @<File 1@>@;
    @q1
    @o file2.c
            @<File 2@>@;
    @q0
    @o file3.c
            @<File 3@>@;
    

    For very large projects, another solution is to maintain multiple web source files. To avoid losing the substantial benefits of the automatic index, refer to the discussion in section Using the idxmerge utility to merge indexes to learn how to create a master index that contains information about several web files.

    `@q': Turn off module and line info locally

    The command-line option `-#' (see section `-#': Turn off comments about line and section numbers (@FTANGLE{})) turns off comments about module and line numbers globally, for the entire code. However, in some cases one wants to turn that off in just a small block of code. One important example arises in FORTRAN. Consider

    @
    @a
          x = @<Some action@>
    
    @
    @<Some action@>=
    y + z
    

    This example will tangle to something like

          x = 
    C* 1: *
    *line 20 "test.web"
          y + z
    C* :1 *
    *line 5 "test.web"
    

    Unfortunately, the information comments have created invalid code that will not compile.

    The `@q' command solves this problem by turning off or on the information comments locally. `@q0' turns them off; `@q1' turns them on. Thus, if one rewrites the above example as

    @
    @a
    @q0
          x = @<Some action@>
    @q1
    

    it will tangle to

          x = y + z
    

    as one desires.

    For another use of the `@q' command, see section `@o': Open output file (local scope).

    `@R': Treat next identifier as integer-like reserved

    word (@FWEAVE{})

    For formatting purposes, treat the next identifier as an integer-like reserved word.

    This command is useful in pretty-printing certain kinds of macro constructions. Further discussion is given in @xref{Macros and formatting}.

    `@r': Set language to RATFOR--77

    See section `@L': Set language and section LANGUAGES.

    `@r9': Set language to RATFOR--90

    See section `@L': Set language and section LANGUAGES.

    `@u': Undefine outer macro

    This command begins the definition part.

    `@u' is the inverse of `@d'. For example, in C the command `@u A' tangles to `#undef A'.

    `@v': Overload operator

    This command begins the definition part.

    `@v' is used to change the woven appearance of an operator. If one defines a new operator, for example by a statement such as

    interface operator(.BETA.)
    

    in FORTRAN-90, one should also use an `@v' in the definition part--for example,

    @v .BETA. "\\beta" +
    

    For a detailed discussion of overloading (the output appearance of) operators, see section Overloading operators and identifiers.

    `@W': Overload identifier

    This command begins the definition part.

    For a detailed discussion of overloading (the output appearance of) identifiers, see section Overloading operators and identifiers.

    `@x': Terminate ignorable material, or begin material to be changed

    In a change file, this command begins material to be changes; see section Change files.

    In web source files, this command has a different use; see the discussion of the `@z' command (see section `@z': Begin ignorable material, or terminate change).

    `@y': Begin change material

    The `@y' command is permitted only in change files. See section Change files.

    `@z': Begin ignorable material, or terminate change

    @FWEB{} files may begin with the construction

    @z
    .
    .
    @x
    

    where the `@z' occupies the very first two characters of the file, and where the `@z' and `@x' must begin in column 1. Material between the `@z' and `@x' is pure commentary and is ignored by both processors, with one exception.

    The exception is that an RCS-like line (RCS stands for "revision-control system") with syntax

    $Keyword: Text of Keyword $
    

    (at least one blank after the colon, and at least one before the last dollar sign; UNIX users, see `man ident') is parsed, and the text of the Keyword is made available to the control codes `@K' (see section `@K': Extract global RCS-like keyword) and `@k' (see section `@k': Access local RCS-like keyword) as well as to @FTANGLE{}'s built-in function $KEYWORD (see section $KEYWORD: Value of global RCS-like keyword.

    A distinction is made between keywords that are found in the ignorable commentary at the beginning of the master web file, which are called global keywords, and ones that are found at the beginning of files included via `@i', which are called local keywords.

    The commands that access RCS-like keywords function as follows:

    The command `@z' is also used in change files to end a change. See section Change files.

    Conversion to ASCII

    Several commands are useful for generating machine-independent code. For example, @FWEB{} works internally with the ASCII character set, so uses these commands heavily to convert from the possibly non-ASCII native character set of the machine on which @FWEB{} is running.

    `@'': Convert character to ASCII

    The construction `@'c'' converts `c' to its ASCII value. In C and C++, it is converted to octal; for example, `@'A'' is output as `0101'. In FORTRAN and RATFOR, it is converted to decimal; the previous example would be output as `65'.

    If the native character set of one's machine is ASCII, the conversion will not be done unless the `-A' command-line option is used. See section `-A': Turn on ASCII translations.

    `@"': Convert string to ASCII

    The construction `@"abc"' converts the enclosed string to its ASCII representation. For example, in C and C++ `@"abc"' will be output as `"\141\142\143"'.

    In FORTRAN and RATFOR, no such simple mechanism exists in the language, so a function call is issued. For example, the previous example would be output as `ASCIIstr('abc')'. The user is responsible for defining the function `ASCIIstr'. The name of this function can be changed by the style-file entry `ASCII_fcn'. See section ASCII_Fcn.

    If the native character set of one's machine is ASCII, the conversion will not be done unless the `-A' command-line option is used. See section `-A': Turn on ASCII translations.

    Forward referencing

    `@[': Mark as defined

    This command marks the next (non-reserved) identifier that appears after the `@[' as being defined in the current section. It is usually issued automatically; for example, `@a' is equivalent to `@A@[', `@d' is equivalent to `@D@[', and `@m' is equivalent to `@M@['.

    If the appropriate style-file parameter mark_defined.??? is 1, this command causes any appearance of the identifier to be subscripted with a section number. For more information, see section Customizing cross-reference subscripts.

    The utility of this command can be seen from the characteristic construction

    @ This is section 5.
    @a @% Issues an implicit @[, which marks |test| as defined in section 5.
            subroutine test
            ...
            end
    
    @ This is section 6.
    @a
            program main
            call test // This will print as $|test|_5$.
            end
    

    The `@[' command should be distinguished from `@_' (see section Index entries). The latter causes the index entry for the identifier to be underlined; the former possibly causes the identifier to be subscripted by a section number. One may wish to turn off the subscripts because they become too cluttered; however, the underlined index entries remain useful and unobtrusive.

    Comments

    @FWEB{} supports a variety of commenting styles borrowed from C, C++, and TeX. For more discussion, see section COMMENTING STYLES.

    `@/*': Begin long verbatim comment

    The following comment is copied to the tangled output. (By default, comments are not copied.) If you desire all comments to be so copied, use `-v'. See section `-v': Make all comments verbatim (@FTANGLE{}).

    `@//': Begin short verbatim comment

    See the discussion of `@/*' in section `@//': Begin short verbatim comment.

    `@%': Ignorable comment

    If any line in a web source code contains the command `@%', all remaining material on that line (to and including the newline character) is ignored by the input driver and never processed at all.

    A stronger form of this command is `@%%'. This deletes the current line as well any empty lines that immediately follow. This command is particularly useful when the N mode is in effect. See section `@N': Turn on N mode.

    Line-numbering problems can arise when these commands are used. For a discussion, see section `-T#': Don't insert `#line' command after `@%'.

    `@?': Begin compiler directive

    The remainder of the line is processed as a compiler directive. Optional material may be inserted automatically at the beginning of the tangled output line by means of the style-file option cdir_start. See section Miscellaneous style-file parameters.

    `@(': Begin meta-comment

    Material between `@(' and `@)' is treated in the N mode. For example,

    @(
    Comment 1
    Comment 2
    @)
    

    Style-file parameters allow optional material to be insert at the beginning and end of the meta-comment, and at the beginning of each line of output. For more information, see the style-file parameters beginning with `meta' (see section Miscellaneous style-file parameters).

    `@)': End meta-comment

    See the discussion of `@(', section `@(': Begin meta-comment.

    Special left brace

    The command `@{' is useful in C/C++ programming to beautify some of the pretty-printing. It translates into a left brace, but also suppresses the automatic insertion of newlines into the subsequent function body or block. This is desirable for very short functions, such as simple constructors in C++. For example,

    class C
    {
    private:
            int i;
    
    public:
            C(int i0) @{i = i0;}
    }   
    

    Here the function will be typeset as

    C(int i0)
      { i = i0; }
    

    rather than the default

    C(int i0)
      {
      i = i0;
      }
    

    Index entries

    Although most information for the Index is gathered automatically, in some situations it must be done by hand.

    `@_': Force index entry to be underlined

    This command applies to the next identifier that appears after the `@_'. The index entry for that identifier will be underlined. (By convention, this means `defined' or `declared'.)

    This command is usually issued automatically. For example, the index entries for the variables `i' and `j' in the C statement `int i, j;' will be underlined, since @FWEAVE{} understands enough of the syntax to know that variables are being defined. Macro definitions (begun by `@D' or `@M') will also be underlined automatically.

    `@-': Delete index entry

    This command applies to the next identifier that appears after the `@-'; it prevents an index entry associated with that identifier from being made. This might be useful when the N mode is in effect.

    `@+': Force index entry

    This command applies to the next identifier that appears after the `@+'; it forces an index entry for that identifier. It is particularly useful when the language is VERBATIM, since cross-referencing is turned off in that case.

    `@^': Make index entry (Roman type)

    To insert one's own index entry in Roman type, say `@^My entry@>'.

    `@.': Make index entry (typewriter type)

    To insert one's own index entry in typewriter type, say `@.My entry'@>.

    `@9': Make index entry (user-defined format)

    The construction `@9Text@>' is used to create an index entry in a format defined by the user. It is associated with the macro \9, which will be called during TeX's processing of the Index as \9{Text}. The user must define \9 according to the format

    \def\9#1{...}
    

    where argument `#1' is the text between `@9' and `@>'. For example, to print that text in a sans serif font, say

    \def\9#1{{\sf #1}}
    

    (Note the extra level of braces to prevent the font command from propagating.)

    Control text

    Control text is material terminated by `@>'; it must be all on one line and must not contain any `@'s.

    `@t': Put control text into a TeX \hbox (@FWEAVE{})

    When @FWEAVE{} sees the command `@tcontrol text@>', it packages the control text into an \hbox and ships it to the output. This command is ignored by @FTANGLE{}.

    `@=': Pass control text verbatim to the output

    For @FTANGLE{}, the command `@=control text@>' sends the control text to the output exactly as input. @FWEAVE{} highlights the control text by drawing a box around it.

    Spacing

    The spacing commands are used to refine @FWEAVE{}'s pretty-printed output. Generally it's not necessary to bother with these until one is putting the final touches on a code.

    `@,': Insert a thin space

    Extra spacings are sometimes necessary when working with unusual macro constructions. `@,' inserts a thin space, analogous to TeX's \,.

    An example where explicit spacing would be necessary is as follows:

    @c
    @
    @m OP +
    @m A(x,y) x @, OP @, y
    
    @a
    z = A(a, b);
    

    Without the `@,''s, the body of the A macro will weave as the unappealing `xOPy'. This occurs because although OP is defined to be a binary operator, @FWEAVE{} thinks of it as just a mere expression, and one of its fundamental production rules is to concatenate expressions with no intervening expressions.

    This demonstrates that situations arise in which one needs to override @FWEAVE{}'s default processing. But for the above example, there is actually a better solution. Instead of using the `@,''s, include the format command `@f OP $_BINOP_'. See section `@f': Format identifier or module name.

    `@/': Force a line break, preserving indentation.

    This command is used to override @FWEAVE{}'s natural inclinations. For example, if one wants each piece of a declaration to appear on a separate line, one can say

    int@/
      i,@/
      j,@/
      k;
    

    This command preserves the natural indentation that would have happened if @FWEAVE{} or LaTeX had broken a long line spontaneously. Thus, the declared variables are indented in the above example. To remove that indent, use `@\' instead. See section `@\': Force a line break, then indent.

    Try to use the line-break commands sparingly--i.e., let @FWEAVE{} do the work. Often, if lines run together in an unexpected or unreadable way, it's because @FWEAVE{} wasn't able to parse the relevant block of code, perhaps because it didn't understand that some variable in an include file has a special meaning. In such cases, trying to fix things with `@/' is the wrong solution. Either use `@f' (see section `@f': Format identifier or module name) or `-H' (see section `-H': Scan C/C++ include files (@FWEAVE{})).

    Distinguish the `@/' command from `@|' (see section `@|': Literal vertical bar, or optional line break), which inserts an optional breakpoint into an expression.

    `@\': Force a line break, then indent

    The `@\' command behaves like `@/' (see section `@/': Force a line break, preserving indentation.), except that it backspaces one notch after the line break. This usually has the effect of undoing the natural indentation that would have been inserted had a long line been spontaneously broken. One common case where the `@\' command might be used would be to put the return type of a C function on a separate line:

    int @\
    main()
    {}
    

    It would be nice to have @FWEAVE{} do that automatically. Unfortunately, the syntax of a function isn't recognized until the opening braces are sensed; by that time, the declaration part of the statement has already been processed. This is one example of the fact that the @FWEB{} processors are much less intelligent and sophisticated than language compilers. A clever (and simple) idea for getting around this kind of problem is lacking at this point.

    `@|': Literal vertical bar, or optional line break

    In the TeX (documentation) part of a section, `@|' inserts a vertical bar. Here's a LaTeX example:

    \begin{verbatim}
      The constructions @|x@| and |x| are very different.
    \end{verbatim}
    

    You might wish to try this out to see what @FWEAVE{} produces.

    In a code part, `@|' inserts an optional line break in an expression.

    `@#': Blank line

    `@#' forces a line break with some extra vertical white space. However, note that blank lines in the source are significant, so this command should seldom if ever be necessary.

    if `@#' is immediately followed by a letter (e.g., `@#if'), it is assumed that a preprocessor command is beginning. See section Preprocessing.

    `@~': Cancel line break

    `@~' is analogous to TeX's `~' (tie); it prevents a line break, which @FWEAVE{} usually inserts after each complete statement it recognizes. For example,

    printf("Working..."); @~ fflush(stdout);
    x = y; @~ break;
    

    `@&': Join items

    During @FWEAVE{}'s output, `@&' joins the items to either side with no spaces or line breaks inbetween.

    This command must be distinguished from the preprocessor construction ## (paste tokens together). In a macro definition, `a##bc' creates the single identifier `abc'. If one said `a@&bc', two identifiers would be output with no spaces separating them. In simple cases, the results may look identical, but consider how things would differ if abc were itself an @FWEB{} macro that should itself be expanded.

    Pseudo (invisible) operators

    Pseudo- or invisible operators are ignored by @FTANGLE{} and not printed by @FWEAVE{}; however, they retain grammatical significance that helps out @FWEAVE{} in its attempts to understand the syntax.

    `@e': Pseudo-expression

    `@e' is an invisible expression (`pseudo-expression') (see section Pseudo-operators). It is sometimes useful in situations where @FWEAVE{}'s pretty-printing has broken down because it didn't properly understand the language syntax. If, for example, @FWEAVE{} failed to properly parse the C statement

    p = (int (*))q;
    

    one might get things to work properly by saying

    p = (int (*@e))q;
    

    In this particular case, one is patching up a deficiency (all right, a bug) in @FWEAVE{}'s "production rules." (This particular bug may no longer exist.) However, there are other situations in which the use of `@e' might be necessary. Consider, for example, the C macro definition

    #define A(x) = x
    

    Here the replacement text of the macro is `= x', which by itself is not a valid construction in C. When the `-1' or `-2' options are used, @FWEAVE{} will report an "irreducible scrap sequence" in this situation (although it may typeset it correctly anyway). To eliminate the warning message, say instead

    #define A(x) @e = x
    

    Now the fragment `@e = x' is interpreted as a valid expression.

    `@;': Pseudo-semicolon

    `@;' is an invisible semicolon. These are often used in C programming to terminate a module name that expands to a compound statement. Carefully compare the uses of `@;' and `;' in the following example:

    @c
    @a
    if(flag)
            @<Compound statement@>@;
    else
            @<Simple statement@>;
    
    @ This compound statement ends with a brace, but is used as an
    expression above.
    @<Com...@>=
    
    {
    x;
    y;
    }
    
    @ This fragment does not end with a semicolon, so one must be 
    supplied above.
    
    @<Sim...@>=
    z
    

    Here is a case for which the pseudo-semicolon is not necessary. Consider

    @c
    @ The code fragment |x = y| ...
    

    If the `-1' is turned on, one might think that @FWEAVE{} would report an "irreducible scrap sequence" because `x = y' is an expression but not a complete statement. (Turning on `-2' demonstrates this.) However, it is not necessary to say `|x = y@;|' because the warning message is not issued if the parsing reduces to just one unresolved scrap.

    On the other hand, `|goto done|' does not reduce to just one unresolved scrap, so say `|goto done@;|' in cases such as this. See section Pseudo-operators.

    In some situations, pseudo-semicolons are inserted automatically. An important case is free-format FORTRAN-90. There the language syntax says that newlines terminate statements (except when there's a trailing ampersand). However, newlines are thrown away before tokenized text is seen by @FWEAVE{}'s parser (and in any event would just be interpreted as white space). Therefore, by default newlines that terminate statements are replaced by pseudo-semicolons, so the parsing proceeds correctly.

    In the FORTRAN-90 case, one could also insert pseudo-semicolons or actual semicolons by hand, and some users prefer that. The possibilities are controlled by the options `-n@;' (see section `-n@;': Supply automatic pseudo-semicolons [FORTRAN]) and `-n;' (see section `-n;': Supply automatic semicolons [FORTRAN]).

    `@:': Pseudo-colon

    `@:' is an invisible colon (see section Pseudo-operators). It can be helpful in formatting certain C constructions correctly. For example, if one has a named module defined as

    @<Cases@>=
    case 1:
    case 2:
    case 3@: @;
    

    then one can use it as a case construction followed by the usual colon, as in

    switch(c)
            {
       @<Cases@>: 
            stuff;
            break;
            }
    

    Miscellaneous commands

    `@!': Inhibit macro expansion

    @FWEB{} macros and built-in functions are always expanded by default. This may not be desirable, particularly in the N mode. To inhibit expansion of an individual identifier, preface it by `@!'.

    COMMENTING STYLES

    @FWEB{} allows a variety of commenting styles. The visible comments are in the font \cmntfont, which defaults to \mainfont, a ten-point Roman font.

    Invisible comments

    @z...@x
    If a source or include file begins with `@z' (in the very first two characters of the file), then all material is skipped until and including a line beginning in column 1 with `@x' [except that lines of the form `$Keyword: text of keyword $' are processed; see section $KEYWORD: Value of global RCS-like keyword, section `@K': Extract global RCS-like keyword (source files), or section `@k': Access local RCS-like keyword (include files)].
    @%
    All material until and including the next newline is completely ignored.
    @%%
    As `@%', but also skip blank lines that immediately follow the current line.

    For example,

    @z
    Author:  J. A. Krommes
    @x
    @c @% This sets the global language to C.
    @* EXAMPLE.
    

    Visible comments

    `/* ... */' is a long comment (it may extend over several lines).

    `// ...' is a short comment (terminated by the next newline).

    `@(...@)' is a meta-comment. Meta-comments are a localized form of the N mode (see section LANGUAGES). Tangled meta-comments are begun by the contents of the style-file entry `meta.top' and terminated by `meta.bottom'. Each line of the meta-comment is begun by `meta.prefix'. Woven meta-comments are begun by `meta_code.begin' and ended by `meta_code.end'. See section Miscellaneous style-file parameters.

    @n
    @a
            program main
    /* Get input. */
            call get_input // Read the parameter file.
    /* Process information.  Comments like this
       can be split over several lines. */
    @(
    Meta-comments provide a poor-person's alignment feature
     i --- counter
     x --- data value
    @)
            i = 1
            x = 2.0
            call exec(i,x)
            end
    

    The use of meta-comments is not recommended; they are only marginally supported. Use ordinary long comments instead. Inside of them, use the various powerful features of TeX or LaTeX (such as \halign or \begin{verbatim} ... \end{verbatim}) to format your comment appropriately.

    Temporary comments

    During development, one frequently desires to temporarily comment out a section of code. C programmers sometimes try to do this by enclosing the code in /*...*/, but this is not good style for several reasons. First, it is impossible if the code itself includes comments, since comments do not nest in C. Second, @FWEAVE{} will treat the commented code as TeX rather than C code and will (at best) format it very poorly. In fact, LaTeX will frequently complain, because the commented code might contain characters such as underscores that TeX expects to be in math mode. (Those are dealt with automatically when @FWEAVE{} is in code mode.) The trivial example `/* a_b; */' is sufficient to illustrate this point.

    The proper way of commenting out sections of code is to use preprocessor constructions: #if 0...#endif in C, or more generally @#if 0...@#endif (usable in all languages). (The @FWEB{} preprocessor is described in section Preprocessing.) With this method, there is no trouble with nested comments, and @FWEAVE{} will continue to format the code as code, so the documentation will make sense.

    For FORTRAN programmers converting an existing code to @FWEB{}, the `-nC' option (see section `-nC': Ignore single-line comments [FORTRAN]) may be helpful.

    MACROS and PREPROCESSING

    @FWEB{} offers a built-in preprocessor facility, especially useful for FORTRAN programmers. It is closely patterned after the C/C++ preprocessor, but with some extensions such as variable numbers of arguments. In addition, there are some built-in functions that provide functionality that cannot be emulated by user-defined macros.

    When working with a language such as C that has its own preprocessor, the question arises when to use that and when to use @FWEB{}'s facilities. The answer generally comes with experience. Remember that @FWEB{}'s macros have been expanded by the time the tangled output file is produced, whereas language-specific preprocessor commands are just passed through to that file.

    If you're a FORTRAN programmer, strongly consider the use of @FWEB{}'s macro facilities; they will simplify your present and future life by creating more legible codes and reducing programming errors by eliminating redundant pieces of code. C/C++ programmers may also appreciate the preprocessor extensions.

    In addition to conventional macro processing, @FWEB{} also offers the convenience of certain built-in functions that behave in many ways like macros. As a trivial example, the value of @PI{} is available through the built-in function `$PI'. Built-in functions are described in section Built-in functions. They can be useful to programmers in all languages.

    @FWEB{} recognizes two kinds of macros: outer macros, and @dfn{WEB macros} (inner macros). Control codes associated with either of these kinds normally begin the definition part. However, @FWEB{} macros are sometimes allowed in the code part as well; see section @FWEB{} macros.

    Macros are expanded by @FTANGLE{} only; @FWEAVE{} merely prints them as they occur in the source file.

    Outer macros

    Outer macros provide a shorthand way of invoking macro definitions in the source language; they are not expanded by @FWEB{}. Outer macros are defined by `@d' (see section `@d': Define outer macro, and mark) or `@D' (see section `@D': Define outer macro). They may be placed in any definition part. @FTANGLE{} collects them during phase 1; during phase 2, they are simply copied in order of their appearance to the beginning of the output file. This is most useful for C or C++ codes; it's a quick way of typing `#define' when the positioning of the `#define' is unimportant.

    As an example,

    @c
    @
    @d YES 1
    @d NO 0
    @a
    main()
    {}
    
    @
    @d BUF_LEN 100
    @a
    ...
    

    The keyword into which the `@d' is translated is language-dependent; it is controlled by the style-file parameter `outer_def'. See section Miscellaneous style-file parameters.

    Outer macros can be undefined by `@u'. The translation is controlled by the style-file parameter `outer_undef'. See section Miscellaneous style-file parameters.

    The default behavior, in which the outer macro definitions are just copied to the top of the output file, is fine for simple applications. However, often C programmers prefer to maintain their macro definitions in a header file such as `test.h'. One way of accomplishing this is to redirect @FTANGLE{}'s output from the command line, as in `ftangle test -=test.h', then use an `@O' command immediately after the first `@a' in the web file to open up `test.c'. A more complicated variant of this allows additional information to be placed into the header file, as in the following example:

    @c
    @* INTRO.
    We assume command-line redirection into \.{test.h} (`\.{-=test.h}').
    
    @d A 1 // This will go into \.{test.h}.
    
    @a
    @<Header material@>@; // Also goes into \.{test.h}.
    @O test.c // Remaining unnamed sections go into \.{test.c}.
    
    @ Header material may be defined as needed throughout the code, but
    with this design it will all go into \.{test.h}.
    
    @<Header material@>=
    
    @<Includes@>@;
    @<Typedefs@>@;
    @<Global variables@>@;
    
    

    @FWEB{} macros

    @FWEB{} macros (sometimes called inner macros) are defined by `@m' (see section `@m': Define @FWEB{} macro, and mark) or `@M' (see section `@M': Define @FWEB{} macro). These should normally be placed in the definition part, as in

    @n
    @ Documentation...
    
    @m CUBE(x) (x)**3
    
    @a
            z3 = CUBE(x) + CUBE(y)
    

    (the appearance of an `@m' in the documentation part begins the definition part). They are collected during @FTANGLE{}'s phase 1 and effectively placed at the top of the unnamed section, so they are all known during the output in phase 2.

    In unusual situations when macros are being conditionally defined and/or undefined, the order of processing a macro definition becomes significant. If the command-line option `-TD' is used, then @FWEB{} macros may be used in the code part as well; they are then called deferred macros. These definitions will be processed during phase 2 in the order that the code sections are processed, which may not be the same as the physical order in the source file.

    The use of deferred macros is highly discouraged, for the following reason. @FWEB{} macros are often used in conjunction with the @FWEB{} preprocessor commands. @emph{Preprocessor commands are always processed during phase 1}, so they do not interact properly with deferred macros. It is for this reason that deferred macros are normally prohibited from appearing in the code part.

    Various features of @FWEB{} macros

    @FWEB{} macros with variable arguments

    An important extension to the ANSI-C syntax is to allow macros with variable (optional) arguments. @FWEB{} macros with a variable number of arguments are indicated by an ellipsis, as in

    @m VAR(x,y,z,...) text
    

    The tokens `#0' (number of variable arguments), `#n' (value of the nth optional argument), and `#.' (comma-delimited list of the optional arguments) are useful in this context.

    Recursion

    ANSI C does not permit recursive macros (for good reason). Thus, in the example

    @m recurse recurse
    

    the identifier recurse simply expands as `recurse', not as an infinite loop. However, in @FWEB{} recursion may be useful in conjunction with some of the built-in functions (see section Built-in functions). To permit a macro to be recursive, say `@m*'.

    No formal support is provided for recursive macros! If they don't work, or suddenly stop working in a new release, you're on your own!

    Protecting macros against redefinition

    Normally an @FWEB{} macro can be redefined at will. The example

    @m PI 3.14159
    @m PI (-3)
    

    is permissible, but probably not a good idea. If you want to ensure that a crucial macro definition is never redefined inadvertently, say `@m!', as in

    @m! PI 3.14159
    

    That is called protecting the macro.

    @FWEB{}'s built-in functions and macros (beginning with `$') are protected by default; see section Redefining built-in functions. To override that protection, use the command-line options `-Tb' (section `-Tb': Permit built-functions to be redefined; for built-in functions) or `-Tm' (section `-Tm': Permit user macros to be redefined; for macros).

    Special tokens

    The following special tokens may be used in the text of @FWEB{} macro definitions:

    ANSI C-compatible tokens

     ##          --- Paste tokens on either side to form a new identifier.
     #parameter  --- Convert parameter to string (without expansion).
    

    For example,

    @m FORTRAN(type, name) type _##name()
    @m TRACE(where) puts("At " #where)
    @a
    FORTRAN(int, fcalc); // Expands to `int _fcalc();'
    TRACE(predictor); // Expands to `puts("At " "predictor");'
    

    Extensions to ANSI C macro syntax

    The most frequently used extensions are the following ones associated with variable arguments: `#0', `#n', and `#.'. FORTRAN-77 users should also employ `#:0' to allow symbolic rather than numeric statement labels. Try not to use the other extensions; they are experimental, complicated, and unlikely to work in all situations.

    In the following list, the forms `#{n}' and `#[n]' may not work correctly in complicated situations. This is a design deficiency that may be corrected someday.

    #*param
    Like `#parameter', but pass a quoted string through unchanged.
    #!param
    Don't expand argument.
    #'param
    Convert parameter to a single-quoted string (no expansion).
    #"param
    Convert parameter to a double-quoted string (no expansion).
    #0
    Number of variable arguments.
    #n
    n-th variable argument, counting from 1.
    #{0}
    Like `#0', but the argument may be a macro expression known at run time.
    #{n}
    Like `#n', but the argument may be a macro expression.
    #[0]
    The total number of arguments (fixed + variable). (The argument inside the brackets may be a macro expression.)
    #[n]
    The nth argument (including the fixed ones), counting from 1. (The argument inside the brackets may be a macro expressions.
    #.
    Comma-separated list of all variable arguments.
    #:0
    Unique statement number (expanded in phase 1).
    #:nnn
    Unique statement number for each invocation of this macro (expanded in phase 2).
    #<
    Begin a module name.
    #,
    Internal comma; doesn't delimit macro argument.

    A few examples of the more important of these tokens are as follows:

    @c
    @m FPRINTF(fmt,...) fprintf(fp,fmt,#.) 
            // Use the whole list of variable args.
    @m B(...) printf("There were %i arguments\n", #0) 
            // Use the number of var args.
    
    @n
    @
    @m DONE #:0 // Symbolic statement label in FORTRAN.
    @a
            goto DONE
            ...
    DONE:
            call endup
    

    Built-in functions

    Built-in functions behave in most ways like macros. In some cases they actually are macros, but other times they implement functions that a user could not define. They all begin with a dollar sign and are in upper case.

    In using these built-ins, confusion may arise regarding the order of expansion of various arguments. When they are implemented as macros, they are subject to the same ANSI-C preprocessor rules as other @FWEB{} macros, which is that all arguments are fully expanded before generating the replacement text of the macro. When they are directly implemented as a primitive function, however, that rule may not apply. For example, $IF expands only its first argument during its first pass of processing; depending on the results of that expansion, it then expands either its second or third argument, but not both.

    The built-in function $DUMPDEF can be used to understand and debug the action of the built-in functions. See section $DUMPDEF: Dump macro definitions to the terminal.

    In the original @FWEB{} design, built-in functions began with an underscore. This usage conflicts with the conventions for reserved words in ANSI C, and has been eliminated. All @FWEB{ built-ins now begin with a dollar sign.}

    No user-defined macro should begin with a dollar sign! It might interfere with the functioning of some internal built-in function.

    Strings and quotes

    Several of the built-in functions expect or return a string argument. Examples include $STRING (see section $STRING: Expand, then stringize), $UNQUOTE (see section $UNQUOTE: Remove quotes from string), and $UNSTRING (see section $UNSTRING: Convert string into characters). In understanding the operation of those functions, it is important to understand just what a string means in the @FWEB{} context. As usual, it is a vector of characters. However, those need not be delimited by quotes, although they may be. Internally, a string is represented by the construction sqc...cqs, where s is a special string delimiter never seen by the user, q is an optional quote character (either single or double quote depending on the language), and c is an ordinary character. Whether or not the quotes are present, the string delimiters inhibit macro expansion.

    The difference between $UNQUOTE and $UNSTRING can now be stated as follows. Given a quoted string such as "abc" (in C),

    The built-ins $P (see section $P: The C preprocessor symbol) and $PP (see section $PP: The C preprocessor symbol), which both generate the preprocessor character `#', provide a good illustration of the differences between $UNQUOTE and $UNSTRING. Consider FORTRAN as an example. Essentially, $P is defined as `$UNQUOTE('#')', which is internally s#s. When this single-character string is sent to the output, it is treated like any other expression and therefore would appear in column 7 or greater even if the construction appeared at the very beginning of the line. On the other hand, $PP is (essentially) defined as `$UNSTRING('#')', which is internally the single character #. Because this character is not a string, the FORTRAN output driver treats it as a special control character, defined in this case to force the character into the first column.

    Redefining built-in functions

    By default, built-in functions are protected---that is, they may not be redefined by an @m command. (To do so cavalierly invites many kinds of weird disasters.) If it is absolutely necessary to redefine a built-in function, use the command-line option `-Tb' (see section `-Tb': Permit built-functions to be redefined).

    Many of @FWEB{}'s "built-in functions" are in fact ordinary macros that are implemented in terms of lower-level built-ins. An example is $POW (see section $POW: Exponentiation), which is constructed from the built-in function $EVAL (see section $EVAL: Evaluate a macro expression). By default, such macros are also protected against redefinition; to override, use the option `-Tm' (see section `-Tm': Permit user macros to be redefined).

    $A: Convert to ASCII

    `$A(string)' is the built-in equivalent of `@'...'' or `@"..."'. (See section Conversion to ASCII and section `@"': Convert string to ASCII.) Note the extra parentheses required by the built-in.

    $A first expands its argument, in case it is a macro defined as a string.

    $ABS: Absolute value

    `$ABS(expression)' returns the absolute value of the macro expression. It is a macro implemented in terms of $IF and $EVAL.

    $ASSERT: Assert a condition

    `$ASSERT(expression)' evaluates the macro expression. If the expression is false, an error message is printed and the run aborts.

    This built-in is useful for ensuring that @FWEB{} macros required by the code are properly initialized. Because it is expanded during the output phase, it must appear in the code part (not in the definition part).

    $AUTHOR: Value of RCS global keyword Author

    Equivalent to `$KEYWORD(Author)'. See section $KEYWORD: Value of global RCS-like keyword.

    $COMMENT: Generate a comment

    `$COMMENT'(string) generates a comment in the output file.

    This function is sometimes useful in conjunction with the processing of @FWEB{} macros, since ordinary comments are removed when macros are processed. For example, if one says

    @c
    @
    @m M "abc" $COMMENT("Test")
    @a
    m = M
    

    the tangled output will be `m= "abc"/* Test */'

    $DATE: Today's date

    `$DATE' generates a string consisting of the date in the form "August 16, 2001". It is implemented as a macro that calls other macros and primitive functions.

    $DATE_TIME: Value of RCS global keyword Date

    Equivalent to `$KEYWORD(Date)'. See section $KEYWORD: Value of global RCS-like keyword.

    $DAY: The day

    `$DAY' generates a string consisting of the day of the week, such as "Monday". It is implemented as a macro that calls other macros and primitive functions.

    $DECR: Decrement a macro

    `$DECR(N)' redefines the numeric macro N to be one less than its previous value. (If N does not simplify to a number, an error results.) In other words, in the language of C the effect is to say `N--'.

    The two-argument form `$DECR(N,m)' executes the equivalent of `N -= m'.

    $DEFINE: Deferred macro definition

    `$DEFINE' behaves like the @FWEB{} macro command @m, but it is intended to appear in the code part, not the definition part (so it is processed during output, not input). Thus, the code fragment

    a = A;
    $DEFINE(A 1)@%
    a = A;
    

    tangles to

    a= A;
    a= 1;
    

    (Notice how the `@%' command was used to kill an unwanted newline, analogous to the `dnl' macro in m4.)

    In the above example, one could also say `$DEFINE(A=1)'. To define a macro with arguments, say something like `$DEFINE(A(x)x*x)'. Do not say `$DEFINE(A(x)=x*x)', as in this case the equals sign will be included in the macro expansion. One must use the equals sign as a means of preventing parentheses from being interpreted as an argument in examples like

    $DEFINE(A=(x))
    

    This expands to `(x)'.

    A completely equivalent shorthand notation for $DEFINE is $M.

    $DO: Macro do loop

    `$DO(macro,imin,imax[,di]){...}' repetitively defines macro as would the FORTRAN statement `do macro = imin,imax,di'. For example,

    $DO(I,0,2)
      {
      a[I] = I;
      }
    

    generates the three statements

      a[0] = 0;
      a[1] = 1;
      a[2] = 2;
    

    In general, the macro name used as loop counter should not be explicitly defined as a macro prior to the $DO. If it is not, it will remain undefined after the end of the iteration.

    Instead of the delimiting braces, parentheses may be used. These may be useful to help @FWEAVE{} format certain constructions correctly.

    Nested delimiters are handled correctly. The delimiters are required even if only a single statement is to expanded.

    $DO is implemented in terms of a command $UNROLL. However, if one says something like `$DUMPDEF($UNROLL(0,5,1))', @FWEB{} will respond that $UNROLL is not an @FWEB{} macro. Rather, $UNROLL is processed like expandable commands in RATFOR such as while. This implies that it cannot be redefined as ordinary macros or built-in functions can be.

    $DUMPDEF: Dump macro definitions to the terminal

    In the call `$DUMPDEF(m1, m2, ...)', m1, m2, and so on are macro calls (with arguments if appropriate). Two lines of output are generated for each argument. Line 1 is the macro definition; line 2 is its expansion using the provided arguments.

    One can use this built-in to debug one's own macros, or to find out the secrets of @FWEB{}'s built-ins. As an example, if one says

    $DUMPDEF($EVAL(2^^4))@%
    

    it responds with the two lines

    $EVAL($0) = $$EVAL($0)
    $EVAL(2**4) = 16
    

    (The $n notation indicates the n-th argument of the macro.) If one replaces $EVAL with $$EVAL in the above $DUMPDEF, it will respond

    $$EVAL($0) = <built-in>
    $$EVAL(2**4) = 16
    

    The purpose of code such as `$EVAL($0) = $$EVAL($0)' is to ensure that the argument of $EVAL is expanded if it contains macros; the primitive function $$EVAL does not do that expansion automatically.

    Names indicated as `<built-in>' by $DUMPDEF may be redefined as ordinary macros, but this is in general a very bad idea; other parts of @FWEB{} may mysteriously stop working.

    $E: Base of the natural logarithms

    The expression `$E' returns e, the base of the natural logarithms, to the default machine precision. The expression `$E(iprec)' returns e to the decimal precision iprec (which must be less than 50).

    $ERROR: Send error message to output

    `$ERROR(string)' prints an error message in @FWEB{}'s standard form.

    $EVAL: Evaluate a macro expression

    `$EVAL(expression)' uses @FWEB{}'s macro-expression evaluator (see section Preprocessing) to reduce the macro expression to its simplest form. An attempt to perform arithmetic on combinations of non-macro identifiers and numbers generates a warning message.

    $EXP: Exponential function

    `$EXP(x)' returns

    $GETENV: Get value of environment variable

    `$GETENV(name)' returns a string consisting of the current value of the environment variable name. (Under VMS, logical names behave like environment variables.)

    The argument to $GETENV need not be a string (double-quoted), but it may be if necessary to avoid the expansion of a macro.

    $HEADER: Value of RCS global keyword Header

    Equivalent to `$KEYWORD(Header)'. See section $KEYWORD: Value of global RCS-like keyword.

    $HOME: The user's home directory

    `$HOME' is a convenience macro equivalent to `$GETENV(HOME)'.

    $ID: Value of RCS global keyword Id

    Equivalent to `$KEYWORD(Id)'. See section $KEYWORD: Value of global RCS-like keyword.

    $IF: Two-way conditional

    $IF is a primitive function (not a macro) that is the code-part version of `@#if'. The syntax is

    $IF(expr, action-if-true, action-if-false)
    

    The expr is an @FWEB{} macro expression that must reduce to 0 (false) or 1 (true). First that argument is expanded. If it is true, action-if-true is expanded; otherwise action-if-false is expanded.

    There may be peculiarities with this and the other built-in $IF function having to do with the order of expansion when the actions contain macros whose arguments themselves are macros. Therefore, do not use them unless absolutely necessary.

    Do not redefine $IF or any other built-in conditionals, as they are used internally to @FWEB{}.

    $IFCASE: n-way conditional

    This primitive built-in behaves like TeX's `\ifcase' command. The syntax is

    $IFCASE(expr, case-0, case-1, ...,case-n-1, default)
    

    If expr reduces to an integer between 0 and n-1, inclusively, the appropriate case is selected; otherwise, the default case is selected.

    As examples,

    $IFCASE(2, zero, one, two, default) => `two'
    $IFCASE(2, zero, one, three) => `three'
    $IFCASE(2, zero, one) => `one'
    

    $IFDEF: Two-way conditional

    This built-in primitive is the code-part version of `@#ifdef'. The syntax is

    $IFDEF(macro, action-if-defined,action-if-not-defined)
    

    $IFNDEF: Two-way conditional

    This built-in primitive is the code-part version of `@#ifndef'. The syntax is `$IFNDEF(macro, action-if-not-defined, action-if-defined)'.

    $IFELSE: Two-way conditional

    The syntax of this built-in primitive is `$IFELSE(expr1, expr2, action-if-equal, action-if-not-equal)'. The expansions of expr1 and expr2 are compared on a byte-by-byte basis. If they are equal, the first action is taken, otherwise the second action is taken.

    For example,

    $M(S="abc")@%
    $IFELSE("abc", S, yes, no)
    

    evaluates to `yes'.

    $INCR: Increment a macro

    `$INCR(N)' redefines the numeric macro N to be one greater than its previous value. (If N does not simplify to a number, an error results.) In other words, in the language of C the effect is to say `N++'.

    The two-argument form `$INCR(N,m)' executes the equivalent of `N += m'.

    $INPUT_LINE: Line number that begins current section

    `$INPUT_LINE' is the number of the line in the web source file that begins the current section (not the source line in which the $INPUT_LINE command appears). Compare $OUTPUT_LINE, section $OUTPUT_LINE: Current line number of tangled output.

    $KEYWORD: Value of global RCS-like keyword

    `$KEYWORD' provides a built-in function alternative to the use of `@K' in a code part. (see section `@K': Extract global RCS-like keyword).

    `$KEYWORD(Keyword)' extracts (as a character string) the text of an RCS-like keyword defined in the ignorable commentary between `@z' and `@x' at the beginning of the web source file (see section `@z': Begin ignorable material, or terminate change). (RCS stands for "revision-control system.") The general syntax is (UNIX users, see `man ident')

    $Keyword: text of keyword $
    

    For example,

    @z
    $Author: krommes $
    @x
    
    @c
    @
    @a
    char author[] = $KEYWORD(Author);
    

    This tangles to

    char author[] = "krommes";
    

    In this example, `$Author' is one of the standard RCS keywords. However, any keyword that fits the syntax `$keyword: contents $' can be accessed by `$KEYWORD'. (At least one blank is necessary before and after contents.) The argument of `$KEYWORD' need not be quoted, but it may be. In either event, the output is a quoted string.

    Keywords extracted from ignorable commentary at the beginning of a web file are called global and are known throughout the code. Distinguish these from local keywords extracted from ignorable commentary at the beginning of an include (`@i') file. Such keywords are known only during the time that file is being read and are accessible via `@k' (see section `@k': Access local RCS-like keyword).

    For convenience, built-ins are defined for some standard RCS global keywords. These are

    $AUTHOR    => $KEYWORD(Author)
    $DATE_TIME => $KEYWORD(Date)
    $HEADER    => $KEYWORD(Header)
    $ID        => $KEYWORD(Id)
    $LOCKER    => $KEYWORD(Locker)
    $NAME      => $KEYWORD(Name)
    $RCSFILE   => $KEYWORD(RCSfile)
    $REVISION  => $KEYWORD(Revision)
    $SOURCE    => $KEYWORD(Source)
    $STATE     => $KEYWORD(State)
    

    There are no such abbreviations for local keywords, because such abbreviations would be expanded during output whereas it is necessary to recognize and expand the local keywords during input. Presumably such local keywords will be used rarely, if at all.

    $L: Change to lower case

    `$L(string)' changes string to lower case. The argument is first expanded in case it is a macro.

    $L_KEYWORD: Value of local RCS-like keyword

    For most purposes, `$L_KEYWORD' behaves as `@k' (see section `@k': Access local RCS-like keyword). It is still under development and should not be used yet.

    `$L_KEYWORD("Keyword")' extracts (as a character string) the text of an RCS-like keyword defined in the ignorable commentary between `@z' and `@x' at the beginning of a file included via `@i'. `$L_KEYWORD("local keyword")' is expanded during input, and the results are known only during the time the include file is being read.

    Note that the argument of `$L_KEYWORD' must be a quoted string. For more discussion of the distinction between local and global keywords, please see section `@z': Begin ignorable material, or terminate change and section $KEYWORD: Value of global RCS-like keyword.

    It is expected that local keywords will rarely be used, as fundamental revision-control information should presumably be extracted from the top of the master web file.

    $LANGUAGE: Identifier for current language

    This expands to an identifier that denotes the current language, as follows:

  • Language @tab $LANGUAGE
  • C @tab $C
  • C++ @tab $CPP
  • Fortran @tab $N
  • Fortran-90 @tab $N90
  • Ratfor @tab $R
  • Ratfor-90 @tab $R90
  • TeX @tab $X
  • VERBATIM @tab $V
  • Note that this outputs identifiers, not @FWEB{} macros. They are intended to be used in $IF or $IFELSE statements such as

    $IF($LANGUAGE==$C, C-text, other-text)
    

    For multiway switches, the $LANGUAGE_NUM built-in is more useful; see section $LANGUAGE_NUM: Number of current language.

    $LANGUAGE_NUM: Number of current language

    `$LANGUAGE_NUM' expands to an integer that uniquely defines the current language, as follows:

  • Language @tab $LANGUAGE_NUM
  • C @tab 0
  • C++ @tab 1
  • Fortran @tab 2
  • Fortran-90 @tab 3
  • Ratfor @tab 4
  • Ratfor-90 @tab 5
  • TeX @tab 6
  • VERBATIM @tab 7
  • This built-in is useful in conjunction with an $IFCASE construction; see section $IFCASE: n-way conditional.

    $LEN: Length of string

    `$LEN(string)' returns the length of string in bytes. If string is not surrounded by quotes, it is interpreted as if it were quoted (so it is not expanded if it is a macro). Thus, in the example

    @m SS string
    $LEN(SS)
    

    the value returned is 2, not 5.

    To expand the argument before taking the length, one can say something like

    @m $XLEN(s) $LEN(s)
    

    $LOCKER: Value of RCS global keyword Locker

    Equivalent to `$KEYWORD(Locker)'. See section $KEYWORD: Value of global RCS-like keyword.

    $LOG: Natural logarithm

    `$LOG(x)' returns

    $LOG10: Logarithm to the base 10

    `$LOG10(x)' returns

    $M: Define a deferred macro

    $M is equivalent to $DEFINE. See section $DEFINE: Deferred macro definition.

    $MAX: Maximum of a list

    `$MAX(x1,x2,...)' returns the maximum of the list of arguments. (There must be at least one argument.)

    $MIN: Minimum

    `$MIN(x1,x2,...)' returns the minimum of the list of arguments. (There must be at least one argument.)

    $MODULE_NAME: Name of present web module

    `$MODULE_NAME' returns the name of the present web module. If the present module is unnamed, it returns the string "unnamed".

    $MODULES: Total number of independent modules

    `$MODULES' gives the total number of independent modules--that is, the number of independent module names, plus 1 for the unnamed module.

    $NAME: Value of RCS global keyword Name

    Equivalent to `$KEYWORD(Name)'. See section $KEYWORD: Value of global RCS-like keyword.

    $OUTPUT_LINE: Current line number of tangled output

    This returns the current line number of the tangled output. Contrast this with $INPUT_LINE, section $INPUT_LINE: Line number that begins current section.

    $P: The C preprocessor symbol

    $P is (essentially) a synonym for `$UNQUOTE("#")' (see section $UNQUOTE: Remove quotes from string). It is useful for constructing @FWEB{} macro definitions that expand to C preprocessor statements. For example,

    @m CHECK(flag)
            $P if(flag)
                    special code;
            $P endif
    

    Another version of the preprocessor symbol is $PP (see section $PP: The C preprocessor symbol). For most purposes, $P and $PP will behave in exactly the same way. The difference between them is that $P is treated as a string (without surrounding quotes), whereas $PP is treated as a character. The character nature of $PP is used by FORTRAN to reset the column number to 1, so C-like preprocessor commands appear there rather than in column 7. For further discussion of strings and the differences between $P and $PP, see section Strings and quotes.

    $PI: Pi

    The expression `$PI' returns @PI{} to the default machine precision. The expression `$PI(iprec)' returns to the decimal precision iprec (which must be less than 50).

    $POW: Exponentiation

    `$POW(x,y)' generates (It is a macro defined in terms of $EVAL (see section $EVAL: Evaluate a macro expression) and the exponentiation operator.)

    $PP: The C preprocessor symbol

    $PP is shorthand for `$UNSTRING($P)' (see section $P: The C preprocessor symbol), or (essentially) a synonym for `$UNSTRING("#")' (see section $UNSTRING: Convert string into characters). It is useful, particularly in FORTRAN, for constructing @FWEB{} macro definitions that expand to C preprocessor statements. For an example, see section $P: The C preprocessor symbol. For a detailed discussion of the difference between `$P' and `$PP', see section Strings and quotes.

    $RCSFILE: Value of RCS global keyword $RCSfile

    Equivalent to `$KEYWORD(RCSfile)'. See section $KEYWORD: Value of global RCS-like keyword.

    $REVISION: Value of RCS global keyword Revision

    Equivalent to `$KEYWORD(Revision)'. See section $KEYWORD: Value of global RCS-like keyword.

    $ROUTINE: Current function (RATFOR only)

    When RATFOR is the current language, $ROUTINE expands to a string built of the name of the current program, function, or subroutine. This function is not useful for other languages, for which it expands to the null string.

    $SECTION_NUM: Number of current @FWEB{} section

    `$SECTION_NUM' returns an integer greater than 0 that is the integer number of the current web section. (This is not the LaTeX section number such as 3.4.)

    $SECTIONS: Maximum section number

    `$SECTIONS' is the maximum section number as understood by @FWEAVE{}.

    $SOURCE: Value of RCS global keyword Source

    Equivalent to `$KEYWORD(Source)'. See section $KEYWORD: Value of global RCS-like keyword.

    $SQRT: Square root

    `$SQRT(x)' returns It is a convenience macro defined in terms of $POW. See section $POW: Exponentiation.

    $STATE: Value of RCS global keyword State

    Equivalent to `$KEYWORD(State)'. See section $KEYWORD: Value of global RCS-like keyword.

    $STRING: Expand, then stringize

    `$STRING(s)' expands its argument if it is a macro, then makes the expansion into a quoted string. If the argument is already a quoted string, it is returned unchanged.

    $STUB: Trap for missing module

    When a missing module is detected, @FTANGLE{} inserts the command `$STUB(module_name)' into the output code. The built-in $STUB expands to a function call appropriate to the current language. For example, in C it expands to `missing_mod', in FORTRAN it expands to `call nomod'.

    $TIME: The time

    `$TIME' returns a string consisting of the local time in the form "19:59".

    $TRANSLIT: Transliteration

    The macro `$TRANSLIT(s, from, to)' interprets each of its arguments as strings (without expanding anything). Then s is modified by replacing any of the characters found in from by the corresponding characters in to. If to is shorter than from, then the excess characters in from are deleted from s. As a limiting case, if to is empty, then all the characters in from are deleted from s. For example, `$TRANSLIT(s, aeiou, 12345)' replaces the vowels in s by the corresponding digits, and `$TRANSLIT(s, aeiou, )' deletes all the vowels. The backslash may be used to escape a character, as in ANSI C. For example, `$TRANSLIT("a\\"\\\\d", "d\\\\a\\"", "D,A'")' translates into `A',D'. Here one had to explicitly enclose strings involving `\\"' in double quotes in order to avoid a complaint about an unterminated string.

    $U: Change to upper case

    `$U(string)' changes string to upper case.

    $UNDEF: Undefine a macro

    `$UNDEF(macro)' undefines an @FWEB{} macro.

    $UNQUOTE: Remove quotes from string

    `$UNQUOTE(string)' returns string without its surrounding quotes. (However, the resulting construction is still treated as a string; no macro expansion is done.)

    For a more detailed discussion and a comparison with $UNSTRING (see section $UNSTRING: Convert string into characters), see section Strings and quotes.

    $UNSTRING: Convert string into characters

    `$UNSTRING(string)' removes quotes from the string, if they are present, and treats the result as a collection of characters. No tokenization is done, so macro expansion does not operate on those characters.

    For a more detailed discussion and a comparison with $UNQUOTE (see section $UNQUOTE: Remove quotes from string), see section Strings and quotes.

    $VERBATIM: (Obsolete)

    This was an old name for $UNQUOTE (see section $UNQUOTE: Remove quotes from string). Please remove all references to this macro from existing codes.

    $VERSION: Present @FWEB{} version number

    `$VERSION' returns a string built out of the @FWEB{} version number, such as "1.60".

    Debugging with macros

    If an @FWEB{} macro expands to more than one output line, debugging can be a bit confusing if the debugger (e.g., gdb) displays lines in the web source file instead of the output file (as it normally does for C and C++). While single-stepping through the code, the debugger will incorrectly step the screen display for each output line even if the macro call occupies just one line in the source file. To localize the debugger's confusion, insert a `@#line' command after the macro call. For example,

    @c
    @ Example of a macro that expands to several output lines.
    @m UPDATE(i, delta_i)
         i += delta_i;
         store(i)@;
    @a
    main()
    {
    UPDATE(j, 5);
    @#line
    // More code.  The debugger will be in sync from here on.
    }
    

    An alternative for highly confusing situations is to use the `-#' option (see section `-#': Turn off comments about line and section numbers (@FTANGLE{})).

    Another potentially confusing situation occurs when `@%' is used to comment out a line. @FWEB{} deals with the line-number problem that arises here automatically; see section `-T#': Don't insert `#line' command after `@%'.

    @FWEAVE{} makes a valiant attempt to pretty-print (see section Pretty-printing) the definitions of both outer macros and @FWEB{} macros in a reasonable way. However, this can be a formidable task, because macro syntax can be essentially arbitrary. Consider, for example, the following definition:

    @c
    @d GET(type) type get_##type()
    @a
    GET(int){}@; // Expands into `int get_int(){}'.
    

    The problem is that the identifier `type' is used in two different ways: as the type of a reserved word (the second `type'), and as an ordinary expression (the third `type'). The first `type' has both meanings simultaneously. Unfortunately, within any particular language @FWEAVE{} associates one unique type or ilk with each identifier.

    One solution to this problem is to use the `@R' command (see section `@R': Treat next identifier as integer-like reserved), which changes the ilk of the very next identifier to integer-like. Thus,

    @d GET(type) @R type get_##type()@;
    

    will format correctly. An alternative solution uses the related command `@E', which changes the ilk of the very next identifier to an ordinary expression. Thus,

    @f type int
    @d GET(type) type get_##@Etype()@;
    

    Other types of troublesome situations involve spaces. When @FWEB{} understands the syntax, it inserts spaces automatically to make the output pleasing. Consider, however, the (somewhat contrived) example

    @c
    @d A(x, y) x y
    @d B s1;
    @d C s2;
    @a
    A(B, C)@;
    

    Here @FWEAVE{} will consider `x' and `y' to be ordinary identifiers (simple expressions), and will abut them with no intervening spaces, which is confusing to read. The solution is to insert a space manually with `@,':

    @d A(x, y) x @, y
    

    (Whether one should write macros like this at all is a separate issue.) For a related example, see the discussion of section Spacing.

    Preprocessing

    Generally, the @FWEB{} preprocessor commands follow a syntax identical to their C/C++ counterparts. The one exception is the `@#line' command. Whereas the C command takes a line number and file name as arguments, the @FWEB{} command takes no arguments; its expansion automatically inserts the current line number and file name. This command should be necessary only in rare circumstances. One of those involves situations in which an @FWEB{} macro expands to more than one output line; see section Debugging with macros.

    The @FWEB{} preprocessor commands may appear in either the definition or the code parts. But BEWARE: No matter where they appear, they are expanded during INPUT, not output. (This is probably a design flaw.) For more discussion, see section @FWEB{} macros.

    The syntax of each command is as follows:

    @#line
    -- Insert a #line command.
    @#define identifier
    -- Define an FWEB macro; equivalent to `@m'.
    @#undef identifier
    -- Undefine an FWEB macro.
    @#ifdef identifier
    -- Is FWEB macro defined? Equivalent to `@#if defined identifier'.
    @#ifndef identifier
    -- Is FWEB macro not defined? Equivalent to `@#if !defined identifier'.
    @#if expression
    @#elif expression
    @#else
    @#endif

    In the `@#if' statement, the expression may contain @FWEB{} macros, but must ultimately evaluate to a number. If that number is zero, the expression is false; otherwise, it is true.

    The expression following constructions such as `@#if' is evaluated by a built-in expression evaluator that can also be used for other purposes, such as in macro expansion. Its behavior is again motivated by expression evaluation in ANSI C; it is not quite as general, but should be more than adequate. (One design flaw that will be fixed someday is that the order of expression evaluation is not necessarily left-to-right, as it is in C.) It supports both integer and floating-point arithmetic (with type promotion from integer to floating-point if necessary), and the ANSI defined operator. Operators with the highest precedence (see table below) are evaluated first; as usual, parentheses override the natural order of evaluation. The unary operator defined has the highest precedence; all the other unary operators have the next highest (and equal) precedence; then come the binary operators. When the operator exists in C, the action taken by @FWEB{} is precisely that that the C compiler would take. Arithmetic is done in either long or double variables, as implemented by the C compiler that compiled @FTANGLE{}. (This was the easy choice, not necessarily the most desirable one.)

    The operators, listed from highest precedence to lowest, are as follows

    LANGUAGES

    @FWEB{} has the ability to work with more than one source language during a single run. The language in effect at the beginning of the first section defines the global language. Further language changes within a section have scope local to that section.

    Usually, `language' means a compiler language like FORTRAN or C. These languages will be "pretty-printed" by @FWEAVE{}. Pretty-printing can be inhibited by turning on the N mode (globally, with the command-line option `-N'; locally, with `@N') or by selecting the VERBATIM `language'; in both of these cases, the input text is echoed literally to the output of both @FTANGLE{} and @FWEAVE{}.

    `Language' is a stronger concept than `mode'. For example, when a language is selected, the extension of the tangled output file is changed appropriately--for example, if `test.web' contains C code (that is, contains the command `@c'), `test.web' tangles into `test.c' (compressing blanks and otherwise (deliberately) making the tangled output relatively unreadable) and @FWEAVE{} pretty-prints using the C syntax. Turning on the N mode does not affect the language; @FTANGLE{} copies the source code literally into `test.c' (no blank compression or other modifications), and @FWEAVE{} typesets the source code within a verbatim environment (no pretty-printing). When the VERBATIM language is selected, the N mode is turned on automatically, but @FTANGLE{} writes its output to a file with a special default extension that can be customized in the style file. See section Miscellaneous style-file parameters.

    Setting the language

    The most general form of a language command is

    @[L]ltext[options]

    where l is a language symbol, text is converted into the option `-ltext', and options have the same syntax as on the command line.

    The language symbols must be in lower case; they are

  • C @tab c
  • C++ @tab c++
  • Fortran-77 @tab n
  • Fortran-90 @tab n9
  • Ratfor-77 @tab r
  • Ratfor-90 @tab r9
  • TeX @tab x
  • VERBATIM @tab v
  • An example of a command with the optional text field is `@n/'. By definition, this is equivalent to `@n[-n/]'. Thus, it both sets the language and invokes a command-line option.

    As another example, `@n9' really means `@n[-n9]'. Thus the language is first set to FORTRAN, then reset to FORTRAN-90. One doesn't need to worry about this detail.

    @n9[-n&]
    

    means set the language to FORTRAN--90 and use free-form syntax with the ampersand as the continuation character. (This construction is now @FWEB{}'s default.)

    The brackets may contain more than one space-delimited option.

    A language command should appear somewhere in limbo, before the start of the first section. The language in effect at the beginning of the first section defines the global language. For historical reasons, the default language is FORTRAN-77, but do not rely on this; always include a language command.

    Language commands may be used within sections, but the new language remains in force only for that section. The language of a named module is inherited from the language in effect at the time the name is first used. Thus, in the following example, the global language is FORTRAN--77, but an arbitrary number of C functions can be placed into a C-language module with just one `@c' language-changing command.

    @n
    @ 
    @a
            program main
            end
    
    @c
    @<C@>@;
    
    @ 
    @<C@>=
    int fcn()
    {}
    

    @FTANGLE{} will write two output files for this example--e.g., `test.f' and `test.c'. Particularly note that one did not need an `@c' command in the last section because the language was C when `@<C@>' was first encountered.

    Special hints and considerations for each language

    One important thing to keep in mind is that in @FWEB{} an identifier may have, for each language, precisely one meaning throughout the document. This restriction is not necessarily in accord with the syntaxes of the various source languages. See, for example, the discussions in section Special considerations for C++ and section Special considerations for FORTRAN.

    Special considerations for C

    (To be completed.)

    Special considerations for C++

    Special considerations for FORTRAN

    Items for both FORTRAN-77 and FORTRAN-90

    Items specific to FORTRAN-77 and fixed-form FORTRAN-90

    Items specific to FORTRAN-90

    (To be completed.)

    Special considerations for RATFOR

    For some warnings about RATFOR, see section Caveats about RATFOR.

    Special considerations for TeX

    `@Lx' is supported only to the extent that fwebmac.sty can be generated correctly from fwebmac.web. You are welcome to experiment, but you may encounter difficulties (which you should report; see section SUPPORT).

    (To be completed.)

    Special considerations for the VERBATIM language

    Unfortunately, the VERBATIM language is not fully debugged. Therefore, it is not recommended for general use. (To be completed.)

    RATFOR

    "RATFOR" stands for "RATIONAL FORTRAN." It endows FORTRAN with a C-like syntax. Certain loop and other constructions (such as `switch' or `i++') that are not allowed in FORTRAN are allowed in RATFOR; @FWEB{} translates those into proper FORTRAN.

    Although RATFOR is a definite improvement over FORTRAN, it certainly does not have the power of C (e.g., elegant pointer notation) or C++ (e.g., classes). Many advantages accrue by taking the time to learn C. RATFOR offers a gentle transition. (It is not supported very actively any more.)

    RATFOR syntax

    A sample RATFOR program is

    @r
    @
    @a
    program main
    {
    integer k;
    real fcn, x;
    
    for(k=0; k<10; k++)
            {
            x = fcn(k);
    
            if(x < 0.0)
                    {
                    x = 0.0;
                    break;
                    }
            }
    }
    

    The concluding brace of a function is translated into an END statement. Note the use of semicolons to terminate statements, braces to delimit compound statements, `<' instead of `.LT.', the C-like for construction, and the `k++' expression.

    Constructions like `k++' or `k -= l + 1' must be used with great care. They translate to statements involving `=' signs, so they can be used only where simple statements are allowed, not essentially anywhere as in C (for example, they cannot be used as function arguments).

    RATFOR commands

    RATFOR--77 commands

     break; // Used with case or to break out of loops, as in C.
     case i: // Used with switch.
     default: // Used with case, as in C.
     do ...; {...} // Note the semicolon (unnecessary if followed by a compound stmt).
     else {...} // Used after if as in C.
     for(a;b;c) {...} // As in C.
     if(condition) {...}
     next; // Equivalent to C's |continue| statement; go to bottom of loop.
     repeat {...} until(condition); // Equivalent to C's do {...} while();
     return expression; // As in C.
     switch(expression) {...} // As in C.
     while(condition) {...} // Like C's while.
    

    Additional RATFOR--90 commands

     contains:
     interface name {...}
     interface operator(op) {...}
     interface assignment(assgnmnt) {...}
     module name {...}
     private:
     sequence:
     type name {...}
     where(expression) {...}
    

    Caveats about RATFOR

    The version of RATFOR built into @FWEB{} differs slightly from its UNIX counterpart:

    1. Numeric statement labels must be followed by a colon; they should be first on their line. (Use symbolic statement labels instead; see the discussion of `#:0' in section Special tokens.)
    2. The quoting convention for characters and strings follows that of C: Single-quote single characters, double-quote strings.
    3. In a switch, cases fall through to the next case unless terminated by break (just as in C).
    4. The do statement must be terminated by a semicolon if followed by a simple statement. (It's unnecessary if followed by a left brace that begins a compound statement.)
    5. Use && and || for the logical AND and OR.
    6. Do not use an end statement at the very end of a RATFOR program unit; it is added automatically by @FWEB{} when the closing brace is sensed.

    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.60). 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.60, 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.

    @FWEB{}'s INDEX.

    @FWEB{} has several powerful indexing facilities:

    1. It sorts and writes its own self-contained (internal) index, including cross-references to all the variables as well as items inserted by the user.
    2. It can write its cross-reference information to a file formatted for use by the makeindex utility. This feature facilitates creation of a master index that contains information about several web files.

    @FWEB{}'s self-generated index

    One of the most useful features of @FWEB{} is that it automatically generates an Index of all variable usage. One can also insert one's own index entries by using the commands

    (More discussion to be completed.)

    Creating a stand-alone index with makeindex

    In addition to the internal index described in the previous section (see section @FWEB{}'s self-generated index), @FWEAVE{} can write the index data to a file formatted for later, stand-alone processing by the makeindex utility. (Several such indexes can be merged together; see section Using the idxmerge utility to merge indexes.) The procedure is simple, although the following discussion goes into some rather arcane details.

    Creating a stand-alone index: Summary

    As a quick reference for those who have already read the details in the next subsection, the procedure to print a stand-alone index with makeindex is as follows. First, create, if necessary, a file `index.tex' that \inputs `index.ind'. (A skeleton is illustrated in the next subsection.) Then:

    fweave -XI test.web % Creates test.idx and test.sty.
    makeindex -s test.sty -o index.ind test.idx % Creates index.ind.
    latex index
    

    If you're not happy with the \pg macro supplied in `fwebmac.sty', define it yourself in `index.tex'.

    In this procedure, note the use of the `-XI' option and the use of a different root name (`index' here) for the output file.

    Creating a stand-alone index: Details

    To create an index file in a form suitable for later stand-alone processing by makeindex, use the `-XI' option to @FWEAVE{}. If the web file is `test.web', the default name of the makeindex output file is `test.idx'. (This name can be overridden by the style-file parameter makeindex.out.) Run makeindex on `test.idx' to create the LaTeX file `index.ind' (see following discussion for details). A stand-alone index can then be produced by saying `latex index', where a skeleton version of `index.tex' would be

    % index.tex --- skeleton for printing a stand-alone index.
    \documentclass{article}
    \usepackage{fwebmac}
    
    \begin{document}
    
    \input{\jobname.ind}
    
    \end{document}
    

    (In practice, a more involved procedure will probably be followed; see below.)

    Usually makeindex works in conjunction with a style file. [In fact, the syntax of @FWEB{}'s style file (see section The Style file) was motivated by that of makeindex.] When the `-XI' option (see section `-X': Print selected cross-reference information (@FWEAVE{})) is used, @FWEAVE{} will create an appropriate style file for makeindex. (The default name of `test.sty' can be overridden by the style-file parameter makeindex.sty.) To run makeindex on the index data for `test.web' and create the output file `index.ind', one would thus say

    makeindex -s test.sty -o index.ind test[.idx]
    

    It's important to use the `-o' option with a name different than the original file name, because it simplifies the construction of the skeleton file `index.tex' that prints the stand-alone index.

    @FWEAVE{} writes `test.sty' because the contents of that file may depend on parameter settings in @FWEB{}'s style file `fweb.sty'. @FWEB{}'s style vocabulary includes all parameters understood by makeindex. If a makeindex parameter is called `param', one references it in `fweb.sty' by `makeindex.param'. Thus, to change the `headings_flag' of makeindex, one would put into `fweb.sty' a line like `makeindex.headings_flag = 1'. To see a list of all makeindex-related parameters, say `fweave -Zmakeindex' (see section `-Z': Display default style-file parameters). Remember, do all makeindex customizations in `fweb.sty'; the actual style file `test.sty' that will be read by makeindex is written automatically by @FWEAVE{.}

    The `.idx' file will contain a list of entries that begin with `\indexentry' (more precisely, the value of the parameter `makeindex.keyword'). The general form is

    \indexentry{sort key:identifier expression|macro}{page number}
    

    Typical entries are

    \indexentry{istream:"\>{istream}|pg{}{}}{1}
    \indexentry{main:"\>{main}|pg{}\underline}{1}
    \indexentry{pow:"\@{pow}|pg{}{}}{2}
    \indexentry{z:"\"|z|pg{}\underline}{2}
    

    Here the colon is the value of `makeindex.actual'; it separates the sort key (before the colon) from the actual expression to be printed. The macros such as `\>' typeset the identifiers in the appropriate way, depending on their use in the code. Note that the backslashes are quoted with the value of `makeindex.quote', which is by default the double quote.

    Although one might guess that the typesetting macros such as `\>' would be defined in `fwebmac.sty', that is not true. Rather, for various technical reasons they are equated to macros in `fwebmac.sty' as one of the operations of the `\Wbegin' macro that is executed at the beginning of every tex file output by @FWEAVE{}. For example, `\Wbegin' does the equivalent of `\let\>\Wid'. Unfortunately, without further action that equating would be forgotten by a LaTeX run made on the output `index.ind' of makeindex. For that reason, @FWEAVE{} appends the appropriate `\Wequate' macro to the end of `makeindex.preamble'. This is one specific instance that necessitates that @FWEAVE{} write the makeindex style file.

    Each of the `\indexentry's contains the encapsulation character `|' (the value of `makeindex.encap'). By the conventions of makeindex, everything between the encapsulation character and the closing right brace defines a macro expression that acts on the page number. E.g., the general form above generates the command `\macro{page number}'. The specific macro construction output by @FWEAVE{} is

    \pg{}{possible action macro}{page number}
    

    Here the name `pg' is the value of `makeindex.page'. The action macro is something like `\underline', which would be used by @FWEAVE{} to underline the page number to indicate where a variable is defined. A default definition of `\pg' is given is `fwebmac.sty'. It is a three-argument macro, `\def\pg#1#2#3{...}', where the arguments are as follows:

    #1 --- Integer file identification number
    #2 --- Action macro.
    #3 --- Page number.
    

    The definition should contain the construction `#2{#3}'---i.e., the page number must be the argument of the action macro. The first argument is left empty in the `.idx' file written by @FWEAVE{}. This can be filled in later by the utility idxmerge (see section Using the idxmerge utility to merge indexes) that merges the indices from several web files. For example, in a master index one might ultimately print page numbers like `II.5', where `II' refers to a file such as `test2.web'. To aid this merging process, the root name of the web file is written as a comment at the top of the `.idx' file output by @FWEAVE{}.

    Using the idxmerge utility to merge indexes

    In a large project, one may maintain and work with several @FWEB{} files. It may be useful to produce a global index that spans all of those files. To this end, the utility idxmerge and associated LaTeX package idxmerge are supplied with the @FWEB{} distribution.

    Using idxmerge: Summary

    As quick reference for those who have already plowed through the following details, here is a summary of the procedure. To print a stand-alone index by merging the indexes from several web sources, do the following. First, create, if necessary, a file `index.tex' that \inputs `index.ind'. Then:

    fweave -XI test1.web
    fweave -XI test2.web
    fweave -XI test3.web
    
    idxmerge -oindex test1.idx test2.idx test3.idx 
            % Creates index.ind and index-names.tex.
    makeindex -s test1.sty index
    latex index
    

    Note the use of the `-XI' option. For further background, see the previous section, section Creating a stand-alone index with makeindex.

    Using idxmerge: Details

    Suppose one has three files, `test1.web', `test2.web', and `test3.web'. To use idxmerge, weave each of the files separately, using the `-XI' option to create `test*.idx' and `test*.sty'. Then say

    idxmerge -oindex test1.idx test2.idx test3.idx
    

    This creates two output files: `index.idx', and `index-names.tex'. idxmerge first sorts the list of file names. It then writes one entry into `index-names.tex' for each file, of the form

    \idxname{n}{file_namen}
    

    This file can be \input by the \topofindex command (for an example, see the LaTeX2e package idxmerge) (supplied with the @FWEB{} distribution) and used to create a list of the merged files.

    Then it merges the \indexentry commands from each of the input files into `index.idx', filling in the integer file identifier n (the position of the file in the sorted list) into the first argument of the \pg macro. One can now say

    makeindex -s test1.sty index
    

    This creates `index.ind', which can be processed by, for example, a simple modification of the simple LaTeX template given above in section Creating a stand-alone index with makeindex. The only difference is that the package idxmerge was used; in that file, the macros \topofindex and \idxname are appropriately defined to print out a numbered list of the merged files to cross-reference into the numerical file- and page-number entries in the body of the index. Here is an example (provided in the @FWEB{} distribution):

    % index.tex --- skeleton for printing a stand-alone index.
    \documentclass{article}
    \usepackage{fwebmac,idxmerge}
    
    \begin{document}
    
    \input{\jobname.ind}
    
    \end{document}
    

    CUSTOMIZATION

    The default behavior of @FWEB{} can be changed in a variety of ways.

    1. UNIX environment variables (logical variables in VMS) affect path or file names.
    2. An initialization file resides in the home directory.
    3. A style file resides in the current directory.

    The initialization file (usually called `.fweb') is intended to contain command-line options (one per line) that are to be used in every run. See section Initialization.

    The style file (called `fweb.sty' by default; see section `-z': Change name of style file) is intended to provide more local customization, perhaps differing for each source file and group of source files. The style file does not contain command-line options; rather, it contains parameter settings that override @FWEB{}'s defaults. The `-p' option (see section @samp{-p}: Buffer up a style-file entry) may be used to specify a style-file entry in `.fweb' (i.e., a global value for all source files) or on the command line (i.e., a value used for a single run).

    The order of processing is:

    1. Evaluate environment variables. See section Environment variables.
    2. Read `.fweb' and remember its contents; sort those into three groups: options beginning with `-', beginning with `&', and beginning with a letter (file names) . See section Initialization.
    3. Process `.fweb' options beginning with `-' (or `+', for backward compatibility), except for `-p'.
    4. Read and process command-line options, except for `-p'. See section Command-line options.
    5. Process remaining `.fweb' options (either file names, or options beginning with `&').
    6. Process any `-p' options from `.fweb'. See section `-p': Buffer up a style-file entry.
    7. Process the style file. See section The Style file.
    8. Process any `-p' options from the command line.

    Unfortunately, because not all options are processed immediately when they are read, errors may not show up when one expects. For example, nothing is actually processed while `.fweb' is being read; its contents are just being stored. It could therefore happen that a syntax error in entering a `-p' option in `.fweb' may not be reported until after the style file has been read, possibly confusing the user as to the source of the error.

    Environment variables

    FWEB_HDR_INCLUDES -- Colon-delimited list of directories for the C preprocessor (in the form of gcc) to search for `#include' header files. This is used in conjunction with the `-H' option; see section `-H': Scan C/C++ include files (@FWEAVE{}). (One can append to this list by means of the `-I' option, provided that option comes after the `-H'; see section `-I': Append to search list for include files.)

    FWEB_INCLUDES -- Colon-delimited list of directories to search for `@i' include files. (One can append to this list by means of the `-I' option, provided that option comes before any use of `-H'; see section `-I': Append to search list for include files.)

    FWEB_INI -- Name of the initialization file. If not defined, either `.fweb' or `fweb.ini' is chosen, depending on the machine. The initialization file always resides in $HOME.

    FWEB_STYLE_DIR -- Directory in which the style file resides. If not defined, the current directory is used.

    Initialization

    Although some aspects of @FWEB{}'s behavior are hard-coded, many can be changed and/or initialized by the user.

    The initialization file

    On startup, @FWEB{} attempts to read an initialization file. This always resides in the user's home directory. It is usually called `.fweb' (`fweb.ini' on personal computers). The default file name can be overridden by the environment variable FWEB_INI.

    One may put into `.fweb' any option that might be used as a command-line option. (Presently, there must be just one entry per line.) If the option begins with a `-' (or a `+' for backward compatibility), it is processed before the actual command-line options; if it begins with `&' or is a file name, it is processed after. Generally, `.fweb' options should begin with `-' so that one may override them from the command line. The `%' sign begins a comment terminated by the end-of-line.

    Memory allocation

    The command-line option `-y' (see section `-y': Allocate dynamic memory) is used to change the default allocation for a dynamic array. The arrays have a one- or two-character abbreviation denoted by aa. Some error messages will use this abbreviation when suggesting that one increase a default allocation. To query the present allocations of variable aa, just say `-yaa'. To query everything, say `-y'.

    This whole scheme is somewhat annoying. In most cases, dynamic arrays should be reallocated automatically. That can be done without too much difficulty, but I was reluctant to try it for Version 1.60 in fear of breaking something. Please wait for the year 2000.

    If one uses `-y' to examine the maximum permitted values of these parameters, one will note the magic number 10239 appearing occasionally. This number is a bit less than 64K/5; it is a signature of an inherently 32-bit design that goes back to Knuth. Unfortunately, this number can't be increased without some radical redesign. Wait for the year 2100.

    `-yb': Maximum bytes for identifiers, index entries, and module names

    Unique identifiers, index entries, and module names are stored contiguously in a large memory area, the size of which is controlled by `-yb'. The default may need to be increased for very large source files, or decreased to squeeze things into a personal computer. See also section `-yn': Maximum number of identifiers and module names.

    `-ybs': Size of the change buffer, in bytes

    Information from change files is read into the change buffer, whose size is controlled by `-ybs'. It should not be necessary to change this unless an error message specifically tells one to do so.

    `-ycb': Size of line buffer for C output, in bytes

    @FTANGLE{} outputs lines of a fixed maximum length. It attempts to split them in a reasonable way, dependent on the language. When it absolutely can't figure out how to split the line, it will issue a warning message and split it anyway. The `-ycb' option controls the maximum output line length for C and C++.

    The analogous command `-yxb' controls the output line length for TeX and the verbatim mode. See section `-yxb': Size of line buffer for TeX and verbatim output.

    `-ycf': Size of a Ratfor buffer, in bytes

    The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by `-ycf' and `-ycg'.

    `-ycg': Size of another Ratfor buffer, in bytes

    The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by `-ycf' and `-ycg'.

    `-yd': Increment for expanding the dots table

    The "dots" table is used for FORTRAN to hold information relating to "dot" operators such as `.NE.'. In FORTRAN--90, additional such operators can be added by the program, so the table can grow dynamically. The `-yd' option controls how many additional entries are made available each time the table size needs to be reallocated.

    `-ydt': Maximum number of deferred macro tokens

    Deferred @FWEB{} macros are ones defined in the code part rather in the definition part. (Their use is normally prohibited; see section `-TD': Permit processing of deferred macro definitions.) `-ydt' controls how many bytes are set aside for the storage of these replacement text of those macros. See also section `-ydx': Maximum number of deferred macro texts.

    `-ydx': Maximum number of deferred macro texts

    `-ydx' controls how many deferred macros are permitted. See also section `-ydt': Maximum number of deferred macro tokens.

    `-yid': Maximum depth of file inclusion

    Files included by `@i' can themselves contain `@i' commands, to a nesting level controlled by `-yid'.

    `-yif': Maximum number of unique include-file names

    The number of unique file names appearing in `@i' commands is controlled by `-yif'.

    `-ykt': Stack size for @FTANGLE{}

    @FTANGLE{} uses a stack to deal with the web of module names--i.e., a named section can refer to another module name. The size of this stack is controlled by `-ykt'.

    `-ykw': Stack size for @FWEAVE{}

    @FWEAVE{}'s stack handles the possibilities that code mode can be embedded in a module name, or vice versa. The maximum nesting level for such mode changes is controlled by `-ykw'.

    `-yll': Line length for @FWEAVE{}'s output, in bytes

    `-yll' controls the length of each line in the .tex file output by @FWEAVE{}.

    `-yln': Maximum length of module names or strings, in bytes

    When each module name or string is parsed, it is stored temporarily in a buffer whose length is controlled by `-yln'.

    `-ylb': Maximum number of nested loops in RATFOR

    In RATFOR, various loops such as `while' are translated into their FORTRAN equivalents. `-ylb' controls the maximum nesting level of such expandable constructions.

    `-ylx': Maximum length of expressions that can be expanded with the post-increment operators of FORTRAN or RATFOR

    FORTRAN and RATFOR can expand expressions such as `x(i) += dx' into their FORTRAN counterparts such as `x(i) = x(i) + dx'. It does so in a very straightforward way, by copying the expression to the left of the equals sign. `-ylx' controls the maximum size of that expression.

    `-ym': Maximum number of sections

    `-ym' limits the maximum number of sections, both named and unnamed. (Each unnamed section is counted separately.) The absolute maximum number of sections is 10239, probably one of the most stringent restrictions in @FWEB{}'s design. (This number is a bit less than 1/5 of 64K.)

    `-yma': Maximum number of arguments to @FWEB{} macros

    The maximum number of arguments to @FWEB{} macros (defined by `@m') is limited by `-yma'.

    `-ymb': Size of the buffer for expanding @FWEB{} macros

    The expansion of each @FWEB{} macro is done in a buffer whose size is controlled by `-ymb'. (In some situations, particularly in RATFOR, more than one such buffer can be open at once.)

    `-yn': Maximum number of identifiers and module names

    A structure is associated with each unique identifier and module name. The maximum number of such structures is controlled by `-yn'. See also section `-yb': Maximum bytes for identifiers, index entries, and module names.

    `-ynf': Maximum number of open output files

    In addition to @FTANGLE{}'s usual output file--e.g., test.c---additional files may be opened by means of the `@O' (see section `@O': Open output file (global scope)) or `@o' (see section `@o': Open output file (local scope)) commands. Depending on the situation, some of these files may remain open simultaneously. The maximum number of such files is controlled by `-ynf'.

    `-yop': Maximum number of entries in the table for operator overloading.

    In @FWEAVE{}, the appearance of an operator can be changed (overloaded) by means of the `@v' command (see section `@v': Overload operator). Each such operator is entered into a table, the maximum size of which is controlled by `-yop'.

    `-yr': Maximum number of cross-references

    The Index cross-reference information (in which sections each identifier is used or defined) is maintained in a large array of structures, one structure for each cross-reference. The maximum number of cross-references is controlled by `-yr'.

    `-ys': Maximum number of scraps

    The maximum number of scraps is controlled by `-ys'. For a discussion of scraps, see section `-1': Turn on brief debugging mode (@FWEAVE{}).

    `-ysb': Size of style-file input-line buffer

    The maximum length of each input line of the style file (fweb.sty by default) is controlled by `-ysb'.

    `-ytt': Maximum number of tokens that @FTANGLE{} can process

    A token is an identifier, numerical constant, operator, etc. @FTANGLE{} must read in and store all tokens in the entire source file, because they can be output in a different order than they are input. The maximum number of tokens is controlled by `-ytt'.

    `-ytw': Maximum tokens in the current section being processed by @FWEAVE{}.

    Unlike @FTANGLE{}, @FWEAVE{} need only read in one section at a time. The maximum number of tokens in any section is controlled by `-ytw'.

    `-yx': Maximum number of texts

    For @FTANGLE{}, a text is either the replacement text of a macro, or the contents of a named section. The maximum number of such texts is controlled by `-yx'.

    For @FWEAVE{}, a text is a phrase that arises from combining primitive scraps during the translation stage of phase 2.

    For both processors, the absolute maximum number of texts is 10239.

    `-yxb': Size of line buffer for TeX and verbatim output

    This option is like `-ycb' (see section `-ycb': Size of line buffer for C output, in bytes), but controls the size of the output line for the TeX (`@Lx') and verbatim (`@Lv') languages.

    The Style file

    A style file (default name `fweb.sty') may reside in the user's current directory (or the directory specified by the environment variable FWEB_STYLE_DIR). The default name can be changed by the command-line option `-z' (see section `-z': Change name of style file).

    The style file is processed after all command-line options have been processed, except that the command-line option `-p' (see section `-p': Buffer up a style-file entry) gets special treatment. Note that that option buffers up style-file entries (i.e., one may use more than one `-p' option). `-p' options placed in `.fweb' are treated as residing in a temporary file that is read just before the local style file; thus, those behave as `global' style-file entries that will be overridden by a matching entry in the local style file. `-p' options on the command line will be processed after the local style file, thus override corresponding options in either `.fweb' or the local style file. To summarize the previous discussion, the local style file is intended to contain settings that are common to a particular source file. Settings common to all source files can be put into `.fweb' by means of the `-p' option. To override a setting for a single run, use a `-p' option on the command line.

    Style-file entries have the form

            keyword [=] value
    

    The equals sign is always optional. The `value' is usually a double-quoted string, but may sometimes be an integer or a single-quoted character. For example,

            LaTeX.class.options = "twoside"
            LaTeX.package "indentfirst,multicol"
            mark_defined.fcn_name 0
            line_char.N 'C'
            color.error = "red"
            Color.red = "\e[01;31m"
    

    The syntax is completely free-form. Periods within keywords are precisely equivalent to underscores, but are useful heuristically for associating a structure-like hierarchy to some of the commands. Non-printable characters in strings can be specified as octal constants (e.g., `\033'), hexadecimal constants (e.g., `\x1B'), or one of the ANSI escape sequences `\a', `\b', `\f', `\n', `\r', `\t', and `\v'. The non-ANSI escape sequence `\e' (escape) is also supported; that is particularly useful for color processing (see section Color output).

    Various of the style-file parameters take a language subscript. Those are

    C
    C
    Cpp
    C++
    N
    FORTRAN-77
    N90
    FORTRAN-90
    R
    RATFOR-77
    R90
    RATFOR-90
    V
    Verbatim
    X
    TeX

    Thus, line_char.N is the comment character for @FTANGLE{}'s line commands (see section line_char.l (@FTANGLE{})), for FORTRAN-77 code.

    Unfortunately, the descriptions of the parameters aren't all completed yet. To query the default values, say `ftangle -Z' (see section `-Z': Display default style-file parameters).

    Customizing @FWEAVE{}'s index

    In the following, `???' denotes the name of various subparameters.

    index.???

    index.name is the name of the index section. This string is used in \Wbegin to initialize the TeX macro \INDEX. The index section is recognized by matching, for a starred section, the actual section name against the contents of \INDEX. When they match, a new page and two-column mode are begun. These rules imply that the last section of one's source file can be titled `\INDEX', as in

    @* \INDEX.
    

    index.tex is the name of the file into which the Index is written. The character `#' is translated into the root name of the web file, as for example `#.ndx'.

    index.preamble are TeX commands that begin the Index.

    index.postamble are TeX commands that end the Index.

    index.collate specifies the collating sequence for the Index.

    delim_?

    delim_0 is the string to insert after the identifier in an index entry.

    delim_n is the string to insert between two section numbers in an index entry.

    group_skip

    group_skip is a string of TeX commands to insert between letter groups.

    item_0

    item_0 is the TeX command to begin an index entry.

    language.???

    language.prefix begins a language entry.; language.suffix ends one.

    lethead.???

    lethead.prefix begins a letter group; lethead.suffix ends one. The flag lethead.flag controls the format of the letter group: if it is zero, nothing is inserted; if it is positive, an upper-case letter is inserted; if it is negative, a lower-case letter is inserted.

    underline.???

    underline.prefix is the TeX command to begin an underlined index entry.

    underline.suffix is the TeX command to end an underlined index entry.

    Customizing the module list

    modules.tex is the name of the file into which the module names are written.

    modules.preamble is a string of TeX commands to begin the list of modules.

    modules.postamble is a string of TeX commands to end the list of modules.

    modules.info is the name of the TeX macro that formats the command line and related information.

    Customizing the Table of Contents

    contents.tex is the name of the file into which the Table of Contents is written.

    contents.preamble is the TeX string that begins printing the Table of Contents.

    contents.postamble is the TeX string that ends the Table of Contents.

    Customizing cross-reference subscripts

    When @FWEAVE{} pretty-prints code, it can attach cross-reference subscripts to various kinds of identifiers such as function or macro names. [A bullet for a subscript indicates that the name was defined in the current section.] The actual marking of the cross reference is done by the command `@[' (see section Forward referencing). This is usually done implicitly; for example, the commands `@a', `@d', and `@m' issue an implicit `@['. (See the discussion of `@a' in section `@a': Begin code part of unnamed section, and mark.) In C, various declarations of variables also result in such an implicit mark.

    Various nuances in the type (possibly underlined) used for the subscript give a hint about what kind of identifier @FWEAVE{} thinks it's working with. For more information about the typesetting conventions, see the definition of the primitive macro `\W@IN' in `fwebmac.web'.] The following flags select which identifiers are so subscripted.

    To see the default values of these parameters, say `ftangle -Zmark_defined'. To turn off the subscripting operations completely, use the `-f' option (see section `-f': Turn off module references for identifiers (@FWEAVE{})).

    (Discussion to be completed.)

    Customizing the behavior of `fwebmac.sty' macros

    To some extent, the behavior of @FWEB{}'s macro package `fwebmac.sty' can be changed by means of the following parameters. (Please try not to actually edit `fwebmac.sty' itself; it is produced automatically from `fwebmac.web'. And please don't edit that file either!)

    format.???

    The format parameters are strings that specify the macro to be used to pretty-print various kinds of identifiers. These macro names are usually written automatically by @FWEAVE{}, but they may also be used directly by the user in the TeX documentation. One can see their default values by typing `ftangle -Zformat.'. For example, the default value for format.typewriter is "\\.".

    The macro names defined by the format fields are not defined in `fwebmac.sty'. They are dummy names, and can be changed to any other name not already in use without affecting the operation of @FWEB{}. This ability is necessary because other packages might usurp macros like \. for their own purposes.

    Thus, @FWEAVE{} normally writes out the macro \. to typeset a string. Suppose, however, that some user package uses \. for something else. (One might realize this when LATEX crashes when it encounteres a \. that was written automatically by @FWEAVE{}.) To fix this problem, put into `fweb.sty' the lines

    format_KEYWORD = "\\WTT"
    format_keyword = "\\WTT"
    format_typewriter = "\\WTT"
    

    Here \WTT can be any name not already in use; you need not (and should not) give a definition for \WTT.

    Macros like \. or \WTT are given their values during the execution of the \Wbegin macro that begins the output from @FWEAVE{}. The style-file values are written as arguments to that macro, and essentially a command like \let\.\Wtypewriter is executed, where the internal macro \Wtypewriter is defined in `fwebmac.sty'. If you want to change the way @FWEB{} typesets a particular kind of identifier, you must redefine the internal macro name, not the one used in the format parameters.

    Here are the internal macros used by `fwebmac.sty' to typeset the various kinds of identifiers. The associated style-file parameters are shown in parentheses.

    \Wid
    ordinary identifiers (format.id)
    \WID
    completely upper-case ordinary identifiers (format.ID)
    \Wshort
    single-character ordinary identifiers (format.short_id)
    \WidD
    outer macros (format.outer_macro)
    \WIDD
    completely upper-case outer macros (format.outer_macro)
    \WidM
    FWEB macros (format.WEB_macro)
    \WIDM
    completely upper-case FWEB macros (format.WEB_macro)
    \Wreserved
    reserved words (format.reserved)
    \WRESERVED
    completely upper-case reserved words (format.RESERVED)
    \Wintrinsic
    library/intrinsic function names (format.intrinsic)
    \Wkeyword
    certain Fortran keywords (format.keyword)
    \WKEYWORD
    completely upper-case keywords (format.KEYWORD)
    \Wtypewriter
    character strings (format.typewriter)

    indent.???

    indent.TeX specifies paragraph indentation for the TeX part.

    indent.code specifies similar indentation for the code part.

    LaTeX.???

    For LaTeX2e, the default document class can be overridden by LaTeX.class. The default class is article, and @FWEB{} has not been tested with other document classes, except minimally with revtex (see section Using REVTeX).

    Options to the document class can be specified by LaTeX.class.options.

    User packages can be given by LaTeX.package.

    Options to user packages can be specified by LaTeX.package.options. There may be just one LaTeX.package command and just one LaTeX.package.options command. If it is necessary to issue multiple such commands, then put them into doc.preamble. See the discussion in section LaTeX's document class.

    When running under LaTeX prior to LaTeX2e (or with REVTeX; see section Using REVTeX), the document is (effectively) begun by the command \documentstyle[options]{style}. The options field can be specified by LaTeX.options; the style field by LaTeX.style.

    Remapping control codes

    Control-code remappings are sophisticated and unwise. They are mostly intended for the developer, so are not explained here.

    Color output

    In the design of @FWEB{}, provision has been made for writing various messages to the terminal in color--e.g., serious error messages might appear in red. This feature was motivated by the color ls of Linux. It is installed automatically if the termcap library is present.

    Messages output from @FWEB{} are ranked according to an internal message-type table; each type can be associated with a color that can be changed in the style file. Presently, the message types (hopefully self-explanatory) are

    ordinary
    program_name
    mod_name
    info
    warning
    error
    fatal
    mod_num
    line_num
    in_file
    include_file
    out_file
    timing
    

    The associated style-file parameters are the above names prefaced by `color.'---e.g., color.warning. Each of those has a default value, such as color.error = "red". Those defaults can be displayed by saying `ftangle -Zcolor'.

    What the color actually means in practice depends on the color mode, set by the `-C' option (see section `-C': Set the color mode). That selects one of several primitive palettes, as follows:

    0
    No color; ordinary black-and-white output. This is the default (and the mode used when the termcap library is not present).
    1
    ANSI color. With a color terminal that supports ANSI color escape sequences, one has available the following colors: "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", and "default". These are displayed with bold attribute (that is, bright, not dim). `"default"' stands for the usual black on white background, or vice versa.
    2
    Bilevel. This is for terminals that don't support true color, but do support a double-bright mode and reverse video. Colors are mapped onto various combinations of those two display attributes, according to an internally defined scheme. For example, "red" is mapped onto the pair of escape sequences `md', `mr' (double-bright mode in reverse video).
    3
    Trilevel. As above, but adds underlining capability.
    4
    User-defined colors. This implements a minimal set of defaults. It is intended that the user add definitions in the style file to override those defaults.

    The mechanism is intended to work with systems that support the termcap library. The terminal is controlled by writing appropriate escape sequences to it. The style-file parameters that store the escape sequences are the color name preceded by `Color.' (note the upper case `C')---e.g., `Color.red'. For cases like reverse video (standard termcap abbreviation `mr'), the escape sequences are determined by querying the termcap database (usually `/etc/termcap') through the termcap library functions. For ANSI color (color mode = 1), ANSI escape sequences are hard-coded into @FWEB{}. One can see the escape sequences @FWEB{} assigns to colors by saying `ftangle -ZColor'.

    For any non-zero color mode, one can override @FWEB{}'s default choices for color mappings and escape sequences by redefining one or more of the Color parameters in the style file. The escape sequences can either be specified in raw form--e.g., for color mode = 1, a default is Color.red = "\e[01;31m"---or in the form of a sequence of two-character abbreviations that are defined in the termcap documentation--e.g., for modes 2 and 3, the default is Color.red = "mdmr". (When one displays that with the `-Z' option, @FWEB{} will display the actual escape sequences that it determines from the termcap database, not the abbreviations. For both input and output, note that one may use the non-ANSI escape sequence `\e' to represent the escape character `\033'.)

    When one says `-ZColor', for color modes 1--3 all of the parameters are listed as modified, even if the user redefines none. That occurs because the defaults are overwritten internally when the color mode is set.

    @FWEB{}'s configuration script attempts to determine whether the termcap library is present; if not, they link in dummy termcap routines (`termcap0.web'). To override this behavior, change the appropriate lines in `defaults.mk', produced by the command ./configure.

    Color message output is not fully debugged (it's a frill, after all), so some messages that should reasonably be colored may not be so in the present release.

    Miscellaneous style-file parameters

    There are a variety of miscellaneous parameters.

    ASCII_Fcn

    See section `@"': Convert string to ASCII.

    cchar

    Continuation character for FORTRAN code output.

    cdir_start

    This parameter has the form cdir_start.l, where l is one of `C', `Cpp', `N', `N90', `R', `R90', `X', or `V'. The contents of this parameter is written immediately after the `@?' that begins a compiler directive.

    line_char.l (@FTANGLE{})

    By default, @FTANGLE{} outputs comments indicating line numbers in the web file from which the tangled output comes. (This information can be used by debuggers, especially those for C and C++, to correlate error messages to the web source.) The line_char parameter sets the comment character that begins the line comment.

    line_length.l (@FTANGLE{})

    This parameter is used by the FORTRAN-like languages to control the length of the output line in the `.f' file produced by @FTANGLE{}. For FORTRAN-77, its default value is the venerable 72. For FORTRAN-90, its default is 73. Using that value makes it possible to generate code that is compatible with both fixed- and free-form format (by continuing lines with an trailing ampersand in column 73 and another ampersand in column 6 of the next line).

    meta.???.?, meta.???.hdr.? (@FTANGLE{})

    These parameters customize the treatment of meta-comments. Fundamentally, meta-comments consist of material enclosed by `@(...@)'. The header information usually written at the top of the file output by @FTANGLE{} (see section @samp{-Tv}: Don't print header info) is also treated as a meta-comment. For that header material, a separate set of parameters is provided, such as meta.top.hdr.

    meta.top.l specifies text that precedes material enclosed by `@(...@)'. Here l is one of the standard language subscripts (see section The Style file) such as N90.

    meta.prefix.l begins each line of the meta-comment.

    meta.bottom.l specifies text that follows the meta-comment.

    outer.???

    @FTANGLE{} converts `@d' (see section @samp{@d}: Define outer macro, and mark) to outer.def, and `@u' (see section `@u': Undefine outer macro) to outer.undef.

    protect.?

    The strings protect.l specify the protection character(s) to end a continued line.

    suffix.?

    The extension for the files output by @FTANGLE{} is specified by suffix.l.

    macros

    The default name of the macro package to be read in. [This is usually `fwebmac.sty' (see section The macro package `fwebmac.sty'), but can be overridden by the command-line option `-w'; see section `-w': Change name of macro package (@FWEAVE{}).]

    limbo.begin, limbo.end

    `limbo.begin' is TeX material to be printed at the beginning of the limbo section, just before the text from `@l' commands. See section `@l': Specify limbo text. (This command was previous called just `limbo', and that still works.)

    Similarly, `limbo.end' is printed at the end of the limbo section.

    Thus, the beginning of the file output by @FWEAVE{} looks like this:

    \input fwebmac.sty
    
    \Wbegin{...} 
       [contains \documentclass, \usepackage, <doc.preamble>, \begin{document}]
    
    <limbo.begin>
    [contents of any @l commands]
    [user's TeX commands from the limbo section]
    <limbo.end>
    

    The `limbo.end' command is useful for printing the entire document in two-column format. For more discussion, see section LaTeX's index..

    meta.??? (@FWEAVE{})

    (To be finished.)

    preamble.???

    Additional TeX material can be inserted at the beginning of a named section with preamble.named and at the beginning of an unnamed one with preamble.unnamed.

    dot_constant.???.?

    In FORTRAN, `dot' constants such as .LT. are begun and ended by periods. In special circumstances, the beginning and ending characters may be modified by dot_constant.begin.l and dot_constant.end.l.

    null_file

    The name of the null file or device. For more discussion, see section Change files.

    Automatic file name completion

    For more information, see section `-e': Turn on automatic file-name completion.

    USAGE TIPS and SUGGESTIONS

    In this section are collected various tips and suggestions to help one make full use of @FWEB{}. Additional hints broken down by each supported source language can be found in section LANGUAGES.

    Converting an existing code to @FWEB{}

    To convert an existing code to @FWEB{}, one should do the following. (The following simple procedure assumes that one puts all the subroutines into the unnamed module. However, other more elaborate schemes are possible.)

    1. Place invisible commentary about the author, version, etc. at the beginning of the source file by bracketing it with `@z...@x'. The `@z' must be the first two characters of the file.
    2. Next, set the language by including a command such as `@n' or `@c++'.
    3. Place an `@a' command (switch into unnamed code) before each program unit (e.g., main program, subroutine, or function).
    4. Before each `@a', place an `@*' or @ASP{} command, followed by TeX documentation about that particular section of code.
    5. If you have program units longer than about twelve lines, either make them function calls, if you can afford the overhead and can impart sufficient information via the function name, or break them up into shorter fragments by using named modules. Insert the command `@<Name of module@>' in place of the fragment you're replacing, then put that fragment somewhere else, prefaced by @ASP{} and `@<Name of module@>='.
    6. Make sure your comments are valid TeX. (One can't have things like raw underscores or dollar signs in comments, since those cause TeX to take special actions.)
    7. Beautify and clarify your documentation by using code mode (enclosing stuff between vertical bars) liberally within your TeX.
    8. After you've seen the woven output, you may need to go back and format a few identifiers or section names so that @FWEAVE{} understands them properly, or you may need to insert some pseudo-semicolons (`@;'), pseudo-expressions (`@e'), or pseudo-colons (`@:') (see section Pseudo-operators).
    9. Consider using @FWEB{}'s built-in macro preprocessor (see section MACROS and PREPROCESSING) to make your code more readable--for example, replace raw numerical constants by symbolic names.
    10. Scientific programmers may benefit from built-in macro-like functions like $PI; see section Built-in functions.
    11. If you are a FORTRAN user, for ultimate readability consider converting to RATFOR. The initial annoyance is getting rid of column-6 continuations. With the aid of a good editor, this can be done simply. For example, in emacs one can replace the regular expression [carriage return, five spaces, something not equal to space, tab, or 0] with [backslash, carriage return, six spaces]:
      M-x replace-regexp RET
      C-q C-j \.{\ \ \ \ \ }[\^\.\ tab 0]RET
      \\\\ C-q C-j \.{\ \ \ \ \ \ }RET
      
      Get rid of the keywords such as then or end if in favor of braces. Change singly-quoted character strings to doubly-quoted ones. The `-nC' option (see section `-nC': Ignore single-line comments [FORTRAN]) may be helpful.

    Programming tips and other suggestions

    1. Learn how to use the GNU info browser to access the on-line documentation.
    2. Read the list of new features and changes for the last several releases. See section NEW FEATURES.
    3. Periodically check ftp.pppl.gov:/pub/fweb/READ_ME for bug reports and other news. Make bug reports! See section SUPPORT.
    4. If you have a color terminal, try the option `-C1' (see section `-C': Set the color mode, see section Color output).
    5. Any option in `.fweb' that is intended to be processed after the command-line options should begin with `&' rather than `-'. (This is rarely necessary.) See section Initialization
    6. Put standard command-line options into `.fweb'. Also put there standard style parameters--e.g.,
      -pindex.tex "#.ndx"
      -pmodules.tex "#.mds"
      -pcontents.tex "#.cts"
      
    7. Learn how to use the style file. See section The Style file.
    8. Use the info options `-@', `-D', `-y', and `-Z' to find out about various internal @FWEB{} tables (control codes, reserved words, memory allocations, and style-file parameters). See section Information options.
    9. Begin all @FWEB{} sources with invisible commentary bracketed by `@z...@x'. See section `@z': Begin ignorable material, or terminate change.
    10. Always include an explicit language-setting command in the limbo section. Under normal circumstances, do not set the language from the command line. See section LANGUAGES.
    11. Keep sections quite short. Knuth suggests a dozen lines. That's quite hard to achieve sometimes, but almost never should a section be more than a page long. If a block of code is longer than that, split it up using named modules.
    12. It's easy to define macros from the command line to expedite conditional preprocessing. See section `-m': Define @FWEB{} macro (@FTANGLE{}).
    13. Use the preprocessor construction `@#if 0...@#endif' to comment out unwanted code. See section Preprocessing.
    14. For logical operations with the preprocessor, use `||', not `|'.
    15. It's conventional to identify the ends of long preprocessor constructions as follows:
      @#if A
      .
      .
      @#endif // |A|
      
    16. To debug an errant @FWEB{} macro, use the built-in function `$DUMPDEF'. See section $DUMPDEF: Dump macro definitions to the terminal.
    17. Use `@?' for compiler directives. See section `@?': Begin compiler directive. Use the style-file parameters `cdir_start' to specify information that will be written out at the beginning of the line. See section cdir_start.
    18. Stick to the standard @FWEB{} commenting style `/*...*/' or `//...'. Don't use alternatives such as FORTRAN's column 1 convention; these may not work or may not be supported someday. See section COMMENTING STYLES.
    19. The meta-comment feature `@(...@)' provides a poor-person's alignment feature. But it doesn't work very well, and it's not in the spirit of TeX; learn to use `\halign' or the LaTeX alternatives.
    20. In FORTRAN, use `#:0' to declare readable alphabetic statement labels. See section Special tokens and section `-:': Set starting automatic statement number.
    21. When mixing languages, define the language of a module at the highest possible level--e.g., in the unamed module, not after `@<...@>='.
    22. Use LaTeX. Plain TeX is no longer supported. Upgrade to LaTeX2e. See section LaTeX support.
    23. If you are reading this documentation from printed pages, make sure it's also installed as an Info package on your system so it can be read interactively with emacs. You can also read it through a World-Wide Web browser such as Netscape. For the address, see section SUPPORT.

    Features for scientific programming

    @FWEB{} contains a few features particularly intended for scientific programming.

    1. Several built-in functions generate numerical constants. See `$PI' (section $PI: Pi) and `$E' (section $E: Base of the natural logarithms).
    2. Several built-in functions perform mathematical manipulations. See `$EXP' (section $EXP: Exponential function), `$POW' (section $POW: Exponentiation), `$SQRT' (section $SQRT: Square root), `$LOG' (section $LOG: Natural logarithm), `$LOG10' (section $LOG10: Logarithm to the base 10), `$MAX' (section $MAX: Maximum of a list), and `$MIN' (section $MIN: Minimum).
    3. The do-loop macro `$DO' may be useful. See section $DO: Macro do loop.
    4. C-style array indices can be used by means of the `-n)' option. See section `-n)': Reverse array indices [FORTRAN] (@FTANGLE{}).
    5. An active bracket feature helps improve the appearance of woven code that uses subscripts and/or superscripts heavily. See section `-W[': Process bracketed array indices.

    NEW FEATURES

    This info documentation is now accessible on the World-Wide Web; see section SUPPORT.

    Some things that have been added or changed in recent releases are described in the following.

    Version 1.60

    Updates to documentation (v1.60)

    1. @FWEB{} supports color modes in which messages to the terminal can appear in colors chosen by the user; see section Color output. The color mode is set by the new command-line option `-C' (see section `-C': Set the color mode).
    2. A previously undocumented feature is that for the C-like and Fortran-like languages, @FTANGLE{} expands the binary notation `0b...' to an unsigned decimal number. See section Phases of processing.

    Redefined commands (v1.60)

    A few obscure commands have been slightly redefined. Sorry about that, but it makes for more symmetry and ease of recall, and/or solves some technical problems.

    1. Although it was never documented, previous versions permitted either lower or upper case for the `@' commands that set the language--e.g., both `@c' and `@C' worked. Now only the lower-case forms work. (The upper-case forms may have other meanings.)
    2. The style-file parameter `Ext_delimiter' now begins with an upper-case `E'; formerly it was lower-case.
    3. The behavior of the optional argument of the \Title macro has been slightly redefined. The new, more symmetrical form is
      \Title[Short title]{Long title}
      
      where Long title is printed on the title page and Short title is used for the running header within the document. See section LaTeX's Table of Contents.
    4. The line-break commands `@/' and `@\' (formerly identical) now behave slightly differently. `@/' breaks the line just as it would if the line had been too long and been spontaneously broken. See section `@/': Force a line break, preserving indentation.. `@\' backspaces one unit of indentation after breaking the line. See section `@\': Force a line break, then indent. Usually, one should use `@/' (sorry; I was previously recommending `@\'. For an example in which it is natural to use `@\', see section `@\': Force a line break, then indent.
    5. The names of some of the code-typesetting macros in fwebmac.sty have been changed to conform to the convention that they should all start with `W'. This change will be invisible to you unless you happen to have user macros of your own that start that way or (perish the thought) you have redefined low-level and obscure code in `fwebmac.sty'.

    New features (v1.60)

    This release adds some features for managing large projects, including (i) the idxmerge utility that merges indexes produced by several @FWEB{} files, (ii) a mechanism for accessing RCS-like information in the ignorable commentary at the beginning of the file, and (iii) the ability to include @FWEAVE{}-formatted code into a standard LaTeX document. It also fixes a variety of miscellaneous bugs.

    1. A stand-alone index file suitable for processing by makeindex can be produced by the `-XI' option. See section Creating a stand-alone index with makeindex.
    2. Stand-alone indexes produced by `-XI' can be merged with the idxmerge utility. See section Using the idxmerge utility to merge indexes.
    3. @FWEAVE{}-formatted code can be included in a standard LaTeX2e document by means of the fwebinsert package. See section Package fwebinsert: Inserting @FWEAVE{}'s output into a LaTeX document.
    4. Revision-control-system (RCS) information that appears in the ignorable commentary between the optional `@z' and `@x' that begin an @FWEB{} file (see section @samp{@z}: Begin ignorable material, or terminate change) is accessible in the body of the file through the built-in function $KEYWORD (see section $KEYWORD: Value of global RCS-like keyword) and the new commands `@K' (see section `@K': Extract global RCS-like keyword) and `@k' (see section `@k': Access local RCS-like keyword). These features can access RCS-like keywords that are not known to RCS itself, as long as they fit the proper syntax (see section `@z': Begin ignorable material, or terminate change).
    5. The `-h' option now permits easy access to the GNU info browser if it is installed. See section `-h': Get help.
    6. Underscored versions of built-in functions have been removed!!! E.g., use $IF, not _IF. This change was warned about in the last release.
    7. Single-character identifiers can now be completely cross-referenced via the `-W1' option. See section `-W1': Cross-reference single-character identifiers.
    8. Some module warning messages can be eliminated with the `-W@' option. See section `-W@': Set module warning flag..
    9. The `@q' command (still experimental) has been added to locally turn on or off the the line and module comments in the tangled output. See section `@q': Turn off module and line info locally.
    10. The level of verbosity of @FWEB{}'s informational messages can be controlled with the `-M' option. See section `-M': Set output message level.
    11. C/C++ programmers may find the command `@{' useful. See section Special left brace.
    12. The `-nC' option has been added for FORTRAN users; it kills commented lines at a very early stage in the processing. This can be useful when converting existing codes to @FWEB{}. See section `-nC': Ignore single-line comments [FORTRAN]
    13. FORTRAN-90 (see section `-n9': Set global language to FORTRAN--90) now defaults to free-form syntax.
    14. As of the non-beta Version 1.60, free-form FORTRAN-90 now inserts semicolons automatically in the code part. Thus, textbook FORTRAN-90 examples will weave correctly without the annoyance of explicitly terminating each statement with a semicolon. (If you prefer to put in the semicolons explicitly, use `--n;' to turn off the auto-insertion.) See section `-n;': Supply automatic semicolons [FORTRAN]
    15. The default meaning of the `-k' option was changed; now both lower- and upper-case forms of FORTRAN I/O keywords are recognized. See section `-k': Don't recognize lower-case forms of keywords.
    16. Various changes were made to internal code in `fwebmac.sty'. This should not affect anyone unless you have redefined fwebmac macros. If so, you'll have to compare your versions with the present ones. For example, colons as argument delimiters in \defs have been removed.
    17. It is now (barely) possible to use \documentstyle{revtex} instead of the default \documentclass{article}. See section Using REVTeX.

    Significant bugs (v1.60)

    1. Perhaps the most significant bug is that some high-order (>= 128) characters in strings may not typeset or be processed correctly. This may be an issue for some users of foreign-language packages. The difficulty arises from a design decision made by a previous author. This has at least partly been fixed, but I eschewed a substantial overhaul for fear of breaking other things.

    Version 1.53

    This release fixes a relatively small number of obscure bugs in fweb-1.52-beta. A few minor enhancements were also made. They include

    1. Sections can be numbered by consecutive integers rather than LaTeX's default Dewey-decimal form by saying
      LaTeX.package = "fwebnum"
      
      See section Sections in LaTeX.
    2. The `-H' option (experimental and incomplete) was added. For C and C++, this option tells @FWEAVE{} to scan #include files for `typedef' and/or `class' definitions. See section `-H': Scan C/C++ include files (@FWEAVE{}).
    3. The `-k' option was added. This tells FORTRAN and RATFOR to understand the lower-case forms of I/O keywords such as `iostat' (with the exception of `read', `write', and `end'). See section `-k': Don't recognize lower-case forms of keywords.
    4. The `-n:' option was added. This tells FORTRAN to place statement labels on a separate line, which is useful when the labels are relatively long. (By default, FORTRAN labels are placed on the same line as the thing they are labeling, which looks good for short labels.) See section `-n:': Put statement label on separate line [FORTRAN]
    5. The preprocessor command `@#line' was added. For C code, this adds an explicit `#line' command to the tangled output file. This helps to keep the line numbers between debugger and source file in sync when an @FWEB{} preprocessor statement expands to several lines. See section Debugging with macros. An implicit `@#line' command is added after each `@%' (see section `@%': Ignorable comment) that begins a line (this keeps line numbering correct). To override this, use the option `-T#'. See section `-T#': Don't insert `#line' command after `@%'.
    6. `-p' (style-file) options (see section `-p': Buffer up a style-file entry) on the command line are now processed after the local style file. See section The Style file.
    7. The functionality of the `-D' command was enhanced to include optional arguments that limit the information that will be listed. See section `-D': Display reserved words.

    Version 1.52

    This release was issued only as a beta version. It consists mostly of bug fixes. However, there are a few other interesting points.

    1. fwebmac.sty was enhanced to warn the user to run LaTeX again when the section numbering hasn't yet been brought up to date. I'm not sure I've covered all the bases, but before it didn't complain at all.
    2. C++ classes are now formatted (identified as reserved words) on the first pass, so forward references such as
      @ The class |C|...
      @a
      class C
        {}
      
      will now work. Note that typedef has done this for a while, although there are still a few glitches.
    3. For two years, the documentation has described two control codes as follows:
      @~ --- inhibit line break.
      @+ --- force an index entry.
      
      Apparently the code had these definitions inverted; it has now been brought up to date with the documentation. Fortunately these commands are evidently not heavily used, since no one complained.
    4. fwebmac.sty was further reworked to interact properly with the user package multicol. If in fweb.sty one says `LaTeX.package "multicol"', then the two-column index is done with multicol; this gives various improvements over the \twocolumn format that was used previously. Furthermore, it's possible to use `multicol' to do one's entire document in two-column format. This turned out to be relatively simple, but one needs to get the commands in the proper order. See section LaTeX's index. for more details. Two-column format substantially cuts down the white space; I saved about 50% on a 200-page code. One known glitch with @FWEB{}/multicol is that if one selects page-number cross-references instead of LaTeX section numbers, page references such as 98c don't get the 'c' correct. This is presumably not a big deal. At this point, assume that the use of multicol is highly experimental.
    5. Further bugs in the C and C++ production rules were fixed.

    Version 1.50

    1. The syntax for entries in the initialization file `.fweb' (see section Initialization) has been modified (in a way that is as backward-compatible as possible). Previously, `+' meant process the option before the command-line options, `-' meant process it after. This convention was somewhat hard to remember, given the statement that any command-line option could be put into `.fweb'; furthermore, just about everything in `.fweb' should, in fact, be processed before the command-line options. So now both `+' and `-' mean the same thing, namely process before (and the `+' notation should fade away as time goes on). If you explicitly want something to be processed after all command-line options for some tricky reason, begin it with `&'. I.e., scan your `.fweb' file for any line beginning with `-' and replace that with `&'.
    2. The LaTeX processor (`-PL') is now the default.
    3. The experimental `fwebmacL.sty' macro package supplied with version 1.40 has been substantially reworked and is now the default `fwebmac.sty'. Remove any reference to `fwebmacL.sty' from your `.fweb' file.
    4. Support for LaTeX2e is now provided. See section LaTeX support.
    5. The style-file parameter index.name was added. This is the section name to be given to the Index (see section @FWEB{}'s INDEX.), which should be the last major (starred) section. It becomes the contents of the macro \INDEX. Therefore, one can end one's source file by saying
      @* \INDEX.
      
    6. The `$IF...' class of built-in functions was reworked. They should now be more robust, recursive, and intuitive. Simple uses of these functions should work as before. However, complicated uses that depended on tricky things about the order of expansion of arguments may require revision. Carefully compare the descriptions of these functions in the documentation (e.g., see section $IF: Two-way conditional) with your usage of them in any pre-existing code. In some cases, if a previous constructions using $IF no longer works, it might work if you say
      @m $IF(a,b,c) $$IF(a,b,c)
      
      and then use $$IF in your code. (This forces an extra level of macro expansion.) The same remark goes for $DEFINE. The old forms `_IF' etc. no longer work; convert to `$IF'.
    7. The option `-j' was added. This inhibits multiple inclusions via `@i' of the same include file. See section `-j': Inhibit multiple includes.
    8. One now has the ability to change the comment character that begins @FTANGLE{}'s `line' command. In the style file, say, e.g.,
      line_char.N '#'
      
      to change the default `*line' output by @FTANGLE{} in FORTRAN mode to `#line'. This could be useful if one runs the C preprocessor on the tangled FORTRAN output.
    9. @FWEAVE{}'s processing of typedef statements in C and C++ was improved.
    10. @FWEB{} should now be able to process C++ templates and exception handling, at least in simple situations. The typesetting of C++ references (e.g., `int&') was also improved. Please report any difficulties.
    11. There were various miscellaneous obscure bug fixes.

    Version 1.40

    1. The meaning of `@+' has changed. (SORRY!) Formerly, this inhibited a line break; that function is now performed by `@~'. The new meaning of `@+' is to force an index entry (the opposite of `@-', which inhibits an index entry). If you have large codes using the old `@+' that you do not wish to convert, you can recover the old mappings by placing the following commands into `fweb.sty':
      yes_index = "~"
      no_line_break = "+"
      
      However, please try to make the conversion; the new codes are intended to be more symmetrical and easier to remember.
    2. Built-in functions now begin with `$', not `_'. The underscore prefix was a bad design decision; it introduces conflicts with ANSI C in certain circumstances. To ease conversion, the old forms are still understood. Thus, one can use `$EVAL' and `_EVAL' interchangably. However, do not use the underscore forms; they will be deleted in future releases.
    3. Full LaTeX support. @FWEB{} no longer usurps LaTeX's \output routine, and LaTeX's sectioning commands, Table-of-Contents commands, etc. are used. The appearance of the woven output is changed to be more book-like. (This is an experiment.)
    4. Verbatim language. `@Lv' selects a language-independent format. See section Special considerations for the VERBATIM language
    5. Language-independent mode. The N mode inhibits pretty-printing, blank compression, etc.; source code is essentially copied literally from input to output. This mode is turned on automatically by the VERBATIM language, but it can also be used with the other languages. It is turned on by the command-line option `-N' or the local command `@N'. See section `@N': Turn on N mode.
    6. Writing of temporary files. When the `-F' command-line option is in effect, tangled output is written to temporary files instead of the final target files, and the temporary files are compared to the last version of the target files on disk. If there is no change, the target files are not updated. This avoid unnecessary recompilation if only the documentation, not the code, was changed. See section `-F': Compare output files with old versions (@FTANGLE{}).
    7. Converting output tokens to lower case. See section `-U': Convert reserved output tokens to lower case (@FTANGLE{}).
    8. The built-in functions `$E' and `$PI'. See section $E: Base of the natural logarithms, section $PI: Pi.
    9. The built-in functions `$EXP', `$LOG', and `$LOG10'. See section $EXP: Exponential function, section $LOG: Natural logarithm, and section $LOG10: Logarithm to the base 10.
    10. `$MAX' and `$MIN' generalized to take arbitrary list of arguments. See section $MAX: Maximum of a list, section $MIN: Minimum.
    11. The marriage-saver option. In response to a serious user request, see section `-B': Turn off audible beeps.

    SUPPORT

    @FWEB{} is supported by John Krommes, krommes@princeton.edu. This project is a definitively spare-time activity!!! Bug reports submitted with very short test files will be verified, although not necessarily in real time. For very simple fixes, a change file may be provided. Generally, however, bugs are not fixed until the next release. Releases occur intermittently, depending on my many other professional obligations.

    Suggestions are very welcome. Many of @FWEB{}'s current features were incorporated in response to users' requests. However, the queue for future improvements is long; nothing may happen immediately. The next major release of @FWEB{}, Version 2.00, is planned for approximately the year 2000. (You may be relieved to know that, to the best of my knowledge, @FWEB{} does not suffer from the Y2K bug.)

    This info documentation is now accessible on the World-Wide Web from

    http://w3.pppl.gov/~krommes/fweb_toc.html.

    You can subscribe to one or both of two @FWEB{} mailing lists, fweb-users and fweb-installers. To subscribe, send e-mail to majordomo@pppl.gov. In the body of the message, say, e.g.,

    subscribe fweb-users

    You will receive introductory information describing how these lists are intended to be used. To unsubscribe at any time, substitute unsubscribe for subscribe in the above instructions.

    Archive files containing the messages sent to the @FWEB{} mailing lists are kept in

    ftp.pppl.gov:/pub/fweb/archive/fweb-{users,installers}.archive.

    In addition to anonymous ftp, these files may be obtained by sending a message to majordomo@pppl.gov of the form

    get fweb-users fweb-users.archive.

    Installing @FWEB{}

    Here is the bare-bones installation procedure for UNIX users:

    1. Download the zgip-compressed tar file from ftp.pppl.gov:/pub/fweb. The name of the file contains the version number--e.g., `fweb-1.60.tar.gz'.
      ftp ftp.pppl.gov
      bin
      get fweb-1.60.tar.gz
      quit
      
    2. Uncompress and unpack the tar file:
      gunzip fweb-1.60.tar.gz
      tar -xf fweb-1.60.tar
      
      If the GNU tar is installed, these two steps can be combined into
      gtar -xzf fweb-1.60.tar.gz
      
      Unpacking creates the directory `fweb-1.60', with at least the two subdirectories `Web' and `Manual'.
    3. Change to the new `Web' subdirectory and run the configuration script.
      cd fweb-1.60/Web
      ./configure
      
      `./configure' is an sh script. It attempts to figure out various local system features automatically, then generates the three files `defaults.mk', `config.h', and `custom.h'; those are used in the make. For further information about the operation of `./configure', see `fweb-1.60/READ_ME.FWEB'.
    4. Make and install the release:
      make [CFLAGS='special compiler flags']
      make install
      
      If gcc is available, it will be used in the make; in that case, the default CFLAGS should be sufficient. If another compiler is used, ensure that it is run in ANSI-compatible mode, not the old-style Kernighan and Ritchie. @FWEB{} compiles on my system without any warnings with `gcc -ansi -pedantic'. Please report any compiler warnings from an allegedly ANSI-C environment.

    Concept index

    Jump to: . - @ - a - b - c - d - e - f - h - i - j - k - l - m - n - o - p - r - s - t - u - v - w

    .

  • .false.
  • .true.
  • @

  • @, literal
  • @FWEB{}, customizing
  • @FWEB{}, initializing
  • a

  • Absolute value
  • Allocation, memory, Allocation, memory
  • ASCII, converting to, ASCII, converting to
  • Asserting a condition
  • Assignment operators, compound, Assignment operators, compound
  • Author
  • Automatic pseudo-semicolons, Automatic pseudo-semicolons, Automatic pseudo-semicolons
  • Automatic semicolons, Automatic semicolons
  • b

  • Bar, vertical, Bar, vertical
  • Binary notation, Binary notation
  • Blocks, numbering, Blocks, numbering, Blocks, numbering
  • Brackets, active
  • Breakpoints, inserting
  • Breakpoints, suppressing
  • Bugs
  • Bugs, version 1.60
  • built-in functions, redefining
  • Bullet
  • Bullet subscript
  • c

  • C hints
  • C++ hints
  • Case, changing, Case, changing
  • Class options
  • Code mode
  • Code part, beginning unnamed, Code part, beginning unnamed
  • Code, converting to @FWEB{}
  • Code, temporarily commenting out, Code, temporarily commenting out
  • Code, typesetting
  • Colon, pseudo
  • Color
  • Color mode, ANSI
  • Color mode, bilevel
  • Color mode, trilevel
  • Color mode, user-defined
  • Color, and message types
  • Color, ANSI
  • Color, setting
  • Columns, multiple
  • Commands, redefined
  • Commentary, optional
  • Commenting styles
  • Comments, Comments
  • Comments, FORTRAN
  • Comments, generating
  • Comments, ignorable
  • Comments, ignore single-line Fortran
  • Comments, invisible
  • Comments, short, Comments, short, Comments, short
  • Comments, temporary
  • Comments, TeX
  • Comments, verbatim
  • Comments, visible
  • Compiler directives
  • Completion, automatic file-name
  • Concatenation
  • Condition, asserting
  • Conditional, n-way
  • Conditional, two-way, Conditional, two-way, Conditional, two-way, Conditional, two-way
  • Contents, table of
  • Control text
  • Converting an existing code to @FWEB{}
  • Cross-references, eliminating
  • Cross-references, suppressing
  • Customization
  • Customizing @FWEB{}
  • d

  • Date
  • Date, generating the
  • Day, generating the
  • Debugging, Debugging, Debugging, Debugging, Debugging
  • Debugging macros
  • Documentation format
  • Dot constants, recognizing
  • e

  • Environment variables, Environment variables
  • Environment, obtaining the
  • Error messages, printing
  • Escape sequences, ANSI
  • Example, of @FWEB{} file
  • Exponentiation, Exponentiation, Exponentiation
  • Expression evaluation
  • Expression, pseudo
  • Expressions, evaluating
  • f

  • Features, new
  • Features, version 1.40
  • Features, version 1.50
  • Features, version 1.52
  • Features, version 1.53
  • Features, version 1.60
  • File, including web, File, including web
  • File, initialization
  • File, opening output, File, opening output
  • File, RCS
  • File, style
  • File-name completion
  • Files
  • Files, change
  • Files, input
  • Files, output
  • Fonts
  • Formatting
  • FORTRAN hints
  • FORTRAN, Rational
  • Functions, built-in
  • Functions, intrinsic
  • FWEB output, inserting into LaTeX document
  • h

  • Header
  • Header comments, printing
  • Headers
  • Hexadecimal notation
  • Hints, C
  • Hints, C++
  • Hints, FORTRAN
  • Hints, TeX
  • i

  • I/O keywords
  • Identification
  • Identifier, formatting
  • Identifiers, overloading, Identifiers, overloading
  • Identifiers, single-character
  • Identifiers, truncating
  • Include file, formatting name of
  • Include file, printing name of
  • Include files, finding
  • Include files, indexing
  • Include files, inhibiting
  • Include files, scanning
  • Include files, skipping
  • Index, Index
  • Index entries, deleting
  • Index entries, forcing
  • Index entries, Roman type
  • Index entries, typewriter type
  • Index entries, underlining
  • Index entries, user format
  • Index, name of
  • Index, stand-alone
  • Indexes, merging
  • Indexing commands
  • Information options
  • Initialization file
  • Input line, number of
  • Installing @FWEB
  • Intrinsic functions
  • Items, joining
  • j

  • Joining items
  • k

  • Keyword, RCS, Keyword, RCS
  • Keyword, RCS-like
  • Keywords, I/O, Keywords, I/O
  • l

  • Language number
  • Language, determining
  • Language, determining the
  • Language, global
  • Language, setting, Language, setting, Language, setting
  • Languages
  • LaTeX
  • LaTeX section
  • LaTeX2e
  • Left brace, inserting
  • Length of string
  • Level, message
  • Limbo section, Limbo section
  • Limbo text
  • Line break, canceling
  • Line break, forcing
  • Line break, forcing with indent
  • Line break, optional, Line break, optional
  • Line number
  • Line numbering, turning off
  • Literate programming
  • Lock
  • Logarithms, base 10
  • Logarithms, natural, Logarithms, natural
  • Lower case
  • m

  • Macros
  • Macros, @FWEB{}
  • Macros, absolute value of
  • Macros, debugging
  • Macros, debugging with
  • Macros, decrementing
  • Macros, deferred
  • Macros, defining, Macros, defining
  • Macros, evaluating
  • Macros, formatting
  • Macros, incrementing
  • Macros, inhibiting expansion of
  • Macros, outer
  • Macros, preprocessing
  • macros, redefining
  • Macros, redefinition of
  • Macros, repetitively defining
  • Macros, special tokens for
  • Macros, undefining
  • Macros, with variable arguments
  • Major section, beginning
  • Major section, optional argument for
  • Major subsection
  • Makefiles, using
  • Makeindex, using
  • Marriage
  • Maximum
  • Memory allocation, Memory allocation
  • Message level
  • Message types, Message types
  • Mininum
  • Module name, beginning
  • Module name, ending
  • Module, name of
  • Module, named
  • Module, unnamed
  • Modules
  • Modules, missing
  • Modules, number of
  • Modules, warning level for
  • multicol, using
  • n

  • Named module
  • Not equal, Not equal
  • Notation, binary, Notation, binary
  • Notation, hexadecimal
  • Notation, octal
  • Numbering blocks, Numbering blocks, Numbering blocks
  • o

  • Octal notation
  • Operators, overloading, Operators, overloading, Operators, overloading
  • Operators, pseudo-
  • Options, class
  • Options, information, Options, information, Options, information, Options, information
  • Options, negating
  • Ouput, redirecting, Ouput, redirecting
  • Outer macro, defining
  • Outer macros, undefining
  • Output files, changing names of
  • Output line
  • Output, changing appearance of
  • Overloading
  • Overloading identifiers
  • Overloading operators
  • p

  • Package, fwebnum
  • Package, multicol
  • Packages, user
  • Page headers
  • Page numbers
  • Part, code, Part, code
  • Part, definition, Part, definition
  • Part, TeX, Part, TeX
  • Parts
  • Phases, of @FTANGLE{}
  • Phases, of @FWEAVE{}
  • Pi
  • Pound sign, Pound sign
  • Preprocessing
  • Preprocessor symbol, Preprocessor symbol
  • Preprocessor, m4
  • Preprocessor, sending additional arguments to
  • Pretty-printing
  • Printing, two-sided
  • Processor, LaTeX
  • Processor, TeX
  • Processors, @FWEB{}
  • Program unit
  • Programming tips
  • Pseudo-colon
  • Pseudo-expression
  • Pseudo-operators, Pseudo-operators
  • Pseudo-semicolon
  • Pseudo-semicolons, automatic, Pseudo-semicolons, automatic, Pseudo-semicolons, automatic
  • r

  • RATFOR
  • RATFOR commands
  • RATFOR, caveats about
  • Rational FORTRAN
  • RCS file
  • RCS-like keyword, RCS-like keyword, RCS-like keyword
  • Recursion
  • Redefined commands, version 1.60
  • References, forward
  • Reserved words
  • Revision
  • Root, square
  • s

  • Scientific programming
  • Scrap, irreducible
  • Section names, long
  • Section names, short
  • Section number, current
  • Section number, maximum
  • Section, beginning major
  • Section, beginning minor
  • Section, limbo
  • Sections
  • Sections, named
  • Sections, numbering, Sections, numbering
  • Sections, unnamed
  • Semicolon, pseudo
  • Semicolons, automatic, Semicolons, automatic
  • Semicolons, printing
  • Sharp sign, Sharp sign
  • Spacing commands
  • Spacing, thin space
  • Square root
  • State
  • Statement numbers, automatic
  • Statistics, printing
  • String length
  • String, definition of
  • String, quoted
  • String, quoting a
  • String, unquoted
  • Strings, continuing
  • Strings, long
  • Strings, parenthesized
  • Strings, unquoting
  • Style file
  • Style file, changing name of
  • Style file, for makeindex
  • Subscript, bullet
  • Subsection, beginning major
  • Suggestions
  • Support
  • Syntax, command-line
  • Syntax, free-form, Syntax, free-form, Syntax, free-form
  • t

  • Table of Contents
  • Table of contents, entries for
  • Tags, enum
  • Tags, structure
  • TeX hints
  • Text, control
  • Time, Time
  • Tokens, upper-case
  • Transliteration
  • Typesetting
  • u

  • Unnamed module
  • Upper case
  • User packages
  • v

  • Variable arguments
  • Variables, environment
  • Version number
  • Version, of FWEB
  • Vertical bar, Vertical bar
  • Vertical bars
  • w

  • Warning level for modules
  • Web, structure
  • Words, reserved
  • Option and command index

    Jump to: # - $ - - - . - @ - \ - a - c - f - i - m - t

    #

  • #line
  • $

  • $A
  • $ABS
  • $ASSERT
  • $AUTHOR
  • $COMMENT
  • $DATE
  • $DATE_TIME
  • $DAY
  • $DECR
  • $DEFINE
  • $DO
  • $DUMPDEF
  • $E
  • $ERROR
  • $EVAL
  • $EXP
  • $GETENV
  • $HEADER
  • $HOME
  • $ID
  • $IF
  • $IFCASE
  • $IFDEF
  • $IFELSE
  • $IFNDEF
  • $INCR
  • $INPUT_LINE
  • $KEYWORD, $KEYWORD
  • $L
  • $L_KEYWORD, $L_KEYWORD
  • $LANGUAGE
  • $LANGUAGE_NUM
  • $LEN
  • $LOCKER
  • $LOG
  • $LOG10
  • $M
  • $MAX
  • $MIN
  • $MODULE_NAME
  • $MODULES
  • $NAME
  • $OUTPUT_LINE
  • $P
  • $PI
  • $POW
  • $PP
  • $RCSfile
  • $REVISION
  • $ROUTINE
  • $SECTION_NUM
  • $SECTIONS
  • $SOURCE
  • $SQRT
  • $STATE
  • $STRING
  • $STUB
  • $TIME
  • $TRANSLIT
  • $U
  • $UNDEF
  • $UNQUOTE
  • $UNROLL
  • $UNSTRING
  • $VERBATIM
  • $VERSION
  • -

  • -
  • -!
  • -#, -#
  • -(
  • -+, -+
  • -.
  • -/
  • -1
  • -2
  • -:
  • -=
  • ->
  • -@
  • -\
  • -A
  • -B
  • -b
  • -C, -C
  • -c
  • -c++
  • -D
  • -d
  • -E
  • -e
  • -F
  • -f
  • -H
  • -h
  • -Hr
  • -HX
  • -Hx
  • -I
  • -i
  • -ix
  • -j
  • -k, -k
  • -L
  • -l
  • -M
  • -m
  • -m4
  • -m;
  • -n
  • -n!, -n!
  • -n&
  • -n)
  • -n/
  • -n9
  • -n:
  • -n;, -n;
  • -n@;, -n@;
  • -n\
  • -nb
  • -nC
  • -np
  • -o, -o
  • -p
  • -P
  • -r
  • -r!
  • -r)
  • -r/
  • -r9
  • -r;
  • -r@;
  • -rb
  • -rg
  • -rK
  • -rk
  • -s
  • -sm
  • -t
  • -T#
  • -T%
  • -Tb
  • -TD
  • -Tm
  • -Tv
  • -u
  • -U
  • -v
  • -V
  • -W, -W
  • -w
  • -W1
  • -W@
  • -W[
  • -WH
  • -x
  • -X
  • -XI
  • -y
  • -yb
  • -ybs
  • -ycb
  • -ycf
  • -ycg
  • -yd
  • -ydt
  • -ydx
  • -yid
  • -yif
  • -ykt
  • -ykw
  • -ylb
  • -yll
  • -yln
  • -ylx
  • -ym
  • -yma
  • -ymb
  • -yn
  • -ynf
  • -yop
  • -yr
  • -ys
  • -ysb
  • -ytt
  • -ytw
  • -yx
  • -yxb
  • -z
  • -Z
  • .

  • .fweb, .fweb
  • @

  • @
  • @!
  • @"
  • @#
  • @#define
  • @#elif
  • @#endif
  • @#if
  • @#ifdef
  • @#ifndef
  • @#line
  • @#undef
  • @%
  • @%%
  • @&
  • @'
  • @(
  • @)
  • @*, @*
  • @+
  • @,
  • @-
  • @.
  • @/
  • @/*
  • @//
  • @0
  • @1
  • @2
  • @9
  • @:
  • @;
  • @<
  • @=
  • @>
  • @?
  • @@
  • @[, @[
  • @\
  • @]
  • @^
  • @_
  • @a
  • @A
  • @B
  • @b
  • @c
  • @c++
  • @d
  • @D
  • @e
  • @E
  • @f
  • @i
  • @I
  • @K
  • @k
  • @l
  • @L
  • @M
  • @m
  • @n
  • @N
  • @n9
  • @o
  • @O
  • @q
  • @r
  • @R
  • @r9
  • @t
  • @u
  • @v
  • @W
  • @x
  • @y
  • @z
  • @|, @|
  • @~
  • \

  • \/
  • \beforeindex
  • \botofcontents
  • \documentclass
  • \documentstyle
  • \FWEBtoc
  • \idxname
  • \INDEX, \INDEX, \INDEX
  • \maketitle
  • \numbercode
  • \numberdefs
  • \numberline
  • \numberTeX
  • \pagerefs, \pagerefs
  • \pg
  • \section
  • \startindex
  • \subsection
  • \subsubsection
  • \Title
  • \title
  • \topofcontents
  • \topofindex
  • \twocolumn
  • \usepackage
  • \WARRAY
  • \Wbegin
  • \Wblock
  • \Wfin
  • \WID
  • \Wid
  • \WIDD
  • \WidD
  • \WidM
  • \WIDM
  • \WIF
  • \WIFfmt
  • \Wintrinsic
  • \Wkeyword
  • \WKEYWORD
  • \Wlbl, \Wlbl
  • \WRESERVED
  • \Wreserved
  • \Wshort
  • \Wtypewriter
  • \WXA
  • a

  • ASCIIstr
  • c

  • CONTENTS.tex
  • f

  • fweb.sty, fweb.sty
  • FWEB_HDR_INCLUDES
  • FWEB_INCLUDES
  • FWEB_INI
  • FWEB_STYLE_DIR
  • fwebinsert.sty
  • fwebmac.sty, fwebmac.sty
  • fwebmac.web
  • fwebnum.sty, fwebnum.sty
  • i

  • idxmerge.sty
  • INDEX.tex
  • m

  • MODULES.tex
  • multicol.sty
  • t

  • tempnam
  • termcap
  • termcap0
  • tmpnam
  • Parameter index

    Jump to: a - c - d - e - f - g - i - l - m - n - o - p - s - u

    a

  • ASCII_Fcn
  • c

  • cchar
  • cdir_start
  • Color.black
  • Color.blue
  • Color.cyan
  • Color.default
  • color.error
  • color.fatal
  • Color.green
  • color.in_file
  • color.include_file
  • color.info
  • color.line_num
  • Color.magenta
  • color.mod_name
  • color.mod_num
  • color.ordinary
  • color.out_file
  • color.program_name
  • Color.red
  • color.timing
  • color.warning
  • Color.white
  • Color.yellow
  • contents.postamble
  • contents.preamble
  • contents.tex
  • d

  • delim_0
  • delim_n
  • dot_constant.begin
  • dot_constant.end
  • e

  • ext.ch
  • ext.hch
  • ext.hweb
  • ext.web
  • f

  • format.ID
  • format.id
  • format.intrinsic
  • format.keyword
  • format.KEYWORD
  • format.outer_macro
  • format.RESERVED
  • format.reserved
  • format.short_id
  • format.typewriter
  • format.WEB_macro
  • g

  • group_skip
  • i

  • indent.code
  • indent.TeX
  • index.collate
  • index.name
  • index.postamble
  • index.preamble
  • index.tex
  • item_0
  • l

  • language.prefix
  • language.suffix
  • LaTeX.class
  • LaTeX.class.options
  • LaTeX.options
  • LaTeX.package
  • LaTeX.package.options
  • LaTeX.style
  • lethead.flag
  • lethead.prefix
  • lethead.suffix
  • limbo.begin
  • limbo.end
  • line_char
  • line_length
  • m

  • macros
  • mark_defined.exp_type
  • mark_defined.fcn_name
  • mark_defined.generic_name
  • mark_defined.outer_macro
  • mark_defined.typedef_name
  • mark_defined.WEB_macro
  • meta
  • meta.bottom
  • meta.bottom.hdr
  • meta.prefix
  • meta.prefix.hdr
  • meta.top
  • meta.top.hdr
  • modules.info
  • modules.postamble
  • modules.preamble
  • modules.tex
  • n

  • null_file
  • o

  • outer.def
  • outer.under
  • p

  • preamble.named
  • preamble.unnamed
  • protect
  • s

  • suffix
  • u

  • underline.prefix
  • underline.suffix

  • This document was generated on 16 September 1998 using the texi2html translator version 1.52.