This file documents FWEB...

Copyright 1993–2023 John A. Krommes

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to process this file through TeX and print the results, provided the printed document carries a copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual).

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled “Copying” is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author.

Short Table of Contents

Table of Contents

Next: , Previous: (dir), Up: (dir)   [Contents][Index]


This Texinfo documentation describes FWEB Version 1.70.

If you’re perusing this documentation for the first time, try first reading the discussion at just the top-level nodes in order to get a general sense of what’s here. Lower-level nodes have many details, but most of them are unnecessary for the casual user.

One can obtained a formatted copy of the present documention by saying ‘texi2pdf fweb.texi’, assuming that the relevant texinfo macros have been installed on one’s system. (texinfo.tex and the script texi2pdf are included in the standard GNU distributions.)

This documentation is accessible on the internet from


The distribution itself is available from Google Drive via the link


If you are learning FWEB for the first time, you will probably find that this (lengthy but still unfinished) manual is not sufficiently pedagogical. For background, please refer to Knuth’s book cited in Intro. You should also browse through Concepts, in particular Structure.

If you are contemplating converting an existing code to FWEB, please see Converting, where a suggested process is discussed.

The first part of this master menu lists the major nodes in this Info document. The rest of the menu lists all of the lower-level nodes in the document.

Next: , Previous: Top, Up: Top   [Contents][Index]

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, Distribution in The GNU Emacs Manual.

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

Next: , Previous: Copying, Up: Top   [Contents][Index]


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 Structure.

FWEB was originally intended for scientific programming (the ’F’ stands for FORTRAN), and has been widely used 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, F90, and the later language extensions through 20231), 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 for general use.

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 WEBs 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.2

Next: , Previous: Intro, Up: Intro   [Contents][Index]

1.1 History of WEB and literate programming

(To be completed; see Knuth’s book, cited in Intro.)

Previous: History, Up: Intro   [Contents][Index]

1.2 Features of FWEB

FWEB is distinguished from its relatives in several respects:

Next: , Previous: Intro, Up: Top   [Contents][Index]


The principle concepts of WEB programming are laid out in Knuth’s book, the reference to which was given in Intro. 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.

Next: , Previous: Concepts, Up: Concepts   [Contents][Index]

2.1 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, e.g. test.c or test.f90, whereas FWEAVE produces a TeX file, test.tex, that can be processed with LaTeX.3 (For detailed descriptions of the LaTeX support, see LaTeX.)

The output file produced by FTANGLE is not intended for human eyes (or for editors such as emacs!); 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 will be overwritten the next time the web source is tangled. In an attempt to discourage one from messing with FTANGLE’s output file, all unnecessary spaces are deliberately removed.4

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.

Next: , Previous: Phases, Up: Concepts   [Contents][Index]

2.2 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 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.

2.2.1 A simple example

A simple example of an FWEB source file for a FORTRAN-77 code consisting of three sections is as follows5:

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

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

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.

        program main
        call compute

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

@* \INDEX.

Commands to FWEB are begun by the ‘@’ symbol (see AT 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 -n/.

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

The ‘@*’ command begins a major section 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


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 Sections.

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 S_index). For more discussion of FWEB’s indexing facilities, see Index.

Minor (unnamed) sections are begun by ‘(“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 and LaTeX. It is possible to include LaTeX packages.

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, in the TeX commentary, 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’ language-changing command 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 Macros.

(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 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 Languages.) The code part is terminated by the next appearance of ‘@*’ or ‘(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 ‘) 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 ATl.)

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 LaTeX.

Previous: Structure, Up: Concepts   [Contents][Index]

2.3 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. To simplify just a bit, the fundamental action of FTANGLE is that

FTANGLE outputs the unnamed module.

That output goes to a compilable file with an extension appropriate to the current language. For example, FORTRAN codes with language versions greater than 90 are written to files like test.f90.6

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.)

2.3.1 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 action 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.7

(Why is the command called ‘@a’? One can think of it as standing for ’accrete’. Knuth’s original web used ‘@p’ here, where the ‘p’ stands for ’Pascal’. Given FWEB’s support for multiple languages, that is no longer appropriate; ‘@a’ is language-neutral.

2.3.2 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,

@ Here's how to use a named module.
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 AT;.

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

@* DEMO.
@<Include files@>@;
@<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:

@< 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 insert the invisible expression ‘@e’ (see ATe) before the equals sign.

Next: , Previous: Processors, Up: Concepts   [Contents][Index]

2.4 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.)

2.4.1 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

2.4.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 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 -x.) Specifically, it

Next: , Previous: Concepts, Up: Top   [Contents][Index]


FWEB works with a variety of files. File names have the form ‘[path]/root[.ext]’, where the brackets denote optional material. 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 Customization). The character that initiates the file-name extension (normally a period) can be changed with the ‘-E’ command-line option (see -E_).

Next: , Previous: Files, Up: Files   [Contents][Index]

3.1 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 Initialization.

fweb.sty — Style file (optional; for customizing the behavior of a particular web file or group of files). See Style. 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 -z). 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 Change files.

name.hweb — Code included into web file with ‘@i’ (see ATi). Include files are searched for in the path set by the environment variable FWEB_INCLUDES and/or the ‘-I’ option (see -I_). If that path is empty, then the current directory is searched.

name.hch — Optional change file for include file.

Previous: Input files, Up: Input files   [Contents][Index]

3.1.1 Automatic file-name completion

Automatic completion of input file names is turned on by the ‘-e’ command-line option (see -e). 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 fileStyle-file entryDefault
WEB fileext.webweb
Change fileext.chch
Include fileext.hwebhweb
Change file for include fileext.hchhch

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.

Next: , Previous: Input files, Up: Files   [Contents][Index]

3.2 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 Style). 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:

LanguageStyle-file entryUNIX defaultnon-UNIX default

For example, to change the default extension for a C++ file from ‘C’ to ‘c++’, put into fweb.sty the line

suffix.C = "c++"

Previous: Output files, Up: Files   [Contents][Index]

3.3 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:

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

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.

Next: , Previous: Files, Up: Top   [Contents][Index]


FWEB has a UNIX-style command-line syntax. There are many command-line options, but few or none of those 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 Options) that resides in one’s home directory.

A style file (patterned after the utility makeindex; see Style) 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 -p.

Next: , Previous: Starting, Up: Starting   [Contents][Index]

4.1 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 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 Customization), or can be set in the style file fweb.sty. See null_file.]

The web file is shown as required since one is normally processing a source. However, some of the information options (see Info 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.

Previous: Syntax, Up: Starting   [Contents][Index]

4.2 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.

Next: , Previous: Options, Up: Options   [Contents][Index]

4.2.1 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.

Next: , Previous: Negating options, Up: Options   [Contents][Index]

4.2.2 ‘-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.

Regarding grammar, it is useful to know that FWEAVE is not a compiler. Because it is designed to be fast and (relatively) easy for its author to program, it does not understand the full syntax of languages such as FORTRAN-90. If one presents it with proper syntax, FWEAVE should hopefully typeset it correctly. But it will also happily typeset various kinds of nonsense. Syntactical mistakes will ultimately be caught by your language compiler acting on the output of FTANGLE.

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. (However, certain macros in fwebmac.sty can be redefined to change certain things, such as the fonts used for identifiers, macros, intrinsic functions, etc.)

This brief debugging mode can be turned on more locally by means of the ‘@1’ command. See AT1.

Next: , Previous: -1, Up: Options   [Contents][Index]

4.2.3 ‘-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 -1.) 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 AT2.

Next: , Previous: -2, Up: Options   [Contents][Index]

4.2.4 ‘-@’: Display the control-code mappings

This option supplies information about the ‘@’ control codes (see AT 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.

Next: , Previous: -AT, Up: Options   [Contents][Index]

4.2.5 ‘-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.

Next: , Previous: -A_, Up: Options   [Contents][Index]

4.2.6 ‘-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.)

Next: , Previous: -B_, Up: Options   [Contents][Index]

4.2.7 ‘-b’: Number blocks (FWEAVE)

Number do and if blocks in woven FORTRAN and RATFOR output. This feature is particularly useful in FORTRAN to help one 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.

Next: , Previous: -b, Up: Options   [Contents][Index]

4.2.8 ‘-C’: Set the color mode

The option ‘-Cn’ sets the color mode to n, where the color modes are, briefly,


No color


ANSI color







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

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.

Next: , Previous: -C_, Up: Options   [Contents][Index]

4.2.9 ‘-c’: Set global language to C

This command sets the global language (Languages) to the basic ANSI-C language C89. Usually a global language is set in limbo, in this case by the command ‘@c’, rather than using a command-line option. 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 -D_.

The ‘-c’ option can take a numerical argument that indicates the language version. The choices are 89, 95, 99, 11 or 2011, 17 or 2017, and 23 or 2023. For example, the command ‘-c99’ loads in all reserved names, macro names, and intrinsic function names that are defined in the language specification for C99 (which includes those for C95 and C89).

Next: , Previous: -c, Up: Options   [Contents][Index]

4.2.10 ‘-c++’: Set global language to C++

For more information, see the discussion of ‘-c’ in -c. Note, however, that as of FWEB version 1.70, the ‘c++’ names have not yet been updated beyond C89.

Next: , Previous: -cpp, Up: Options   [Contents][Index]

4.2.11 ‘-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’), ‘m’ (‘macro’), 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’.

Next: , Previous: -D_, Up: Options   [Contents][Index]

4.2.12 ‘-d’: Convert do...enddo

This option is obsolete.

Next: , Previous: -d, Up: Options   [Contents][Index]

4.2.13 ‘-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.

Next: , Previous: -E_, Up: Options   [Contents][Index]

4.2.14 ‘-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.

Next: , Previous: -e, Up: Options   [Contents][Index]

4.2.15 ‘-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.

Modern C programmers will know that the tempnam function considered to be dangerous and should not be used; indeed, the gcc compiler will issue a warning about this usage. Removal of this warning requires a nontrivial rewrite of a section of FWEBs source code; that has not yet been done.

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 Customization.

Next: , Previous: -F_, Up: Options   [Contents][Index]

4.2.16 ‘-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 Subscript params). Sometimes these result in output that is too cluttered and confusing. The ‘-f’ option turns off the subscripting operations.

Next: , Previous: -f, Up: Options   [Contents][Index]

4.2.17 ‘-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 ATf), 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

#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:


Make index entries only for double-quoted include files.


Make index entries for all include files.


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. (Depending on your shell, you may need to export that variable.) 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 -WH_.

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 helpful side effect of displaying the actual command line that was sent to the preprocessor.

Next: , Previous: -H_, Up: Options   [Contents][Index]

4.2.18 ‘-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 Info options) and the on-line documentation (see 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'?'’.

Next: , Previous: -h, Up: Options   [Contents][Index]

4.2.19 ‘-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 ATi.

Next: , Previous: -I_, Up: Options   [Contents][Index]

4.2.20 ‘-i’: Don’t print ‘@I’ include files (FWEAVE)

If a web file is included via ‘@I’ (see ATI_), 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 -H_.)

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.

Next: , Previous: -i, Up: Options   [Contents][Index]

4.2.21 ‘-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 -i) is more often used.

Next: , Previous: -i!, Up: Options   [Contents][Index]

4.2.22 ‘-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.

Next: , Previous: -j, Up: Options   [Contents][Index]

4.2.23 ‘-k’: Don’t recognize lower-case forms of keywords (FWEAVE)

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.

Next: , Previous: -k, Up: Options   [Contents][Index]

4.2.24 ‘-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 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 -D_.

Next: , Previous: -L_, Up: Options   [Contents][Index]

4.2.25 ‘-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.

Next: , Previous: -l, Up: Options   [Contents][Index]

4.2.26 ‘-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:


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.


Print only error messages.


Print error and warning messages.


Print errors, warnings, and short information messages (excluding starred section numbers and line numbers).


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 -V_.

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 Color.

Next: , Previous: -M_, Up: Options   [Contents][Index]

4.2.27 ‘-m’: Define FWEB macro (FTANGLE)

The command-line construction


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 ATm) in the definition parts of the web file.

Next: , Previous: -m, Up: Options   [Contents][Index]

4.2.28 ‘-m4’: Understand m4 built-in commands

This tells FWEAVE to properly format the reserved words of the m4 preprocessor. Note, however, that the use of that preprocessor is not recommended in conjunction with FWEB; use FWEB’s built-in C-like preprocessor instead.

Next: , Previous: -m4, Up: Options   [Contents][Index]

4.2.29 ‘-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@;

Next: , Previous: -m;, Up: Options   [Contents][Index]

4.2.30 ‘-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 -L_.) However, variants of this option, as described below, may be useful.

The ‘-n’ option accepts a numerical argument, such as ‘-n2023’, which indicates which language version to use. The choices are 7 or 77, 9 or 90, 3 or 2003, 8 or 2008, 18 or 2018, and 23 or 2023.

See also Languages and Fortran.

Next: , Previous: -n, Up: Options   [Contents][Index]

4.2.31 ‘-n9’: Set global language to FORTRAN–90

This is a special case of the general ‘-n’ option with a numerial argument. See Languages, and Fortran; see also the discussion of ‘-L’ in -L_.

Next: , Previous: -n9, Up: Options   [Contents][Index]

4.2.32 ‘-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 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 -np.

For further discussion, see the companion command -n;.

Next: , Previous: -nAT;, Up: Options   [Contents][Index]

4.2.33 ‘-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 -nAT;, 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 -np).

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’):

F90-n;-n@; -np

Although free-form FORTRAN-90 (and later versions) automatically appends pseudo-semicolons to each line of source code, this is not really sensible. If you were a C programmer, you would be used to seeing something like

if(x < 0)
  x = -1;

Although it is syntactically correct to place a semicolon at the end of the first line, that would change the meaning! (In C, the semicolon is a null statement, which would terminate the if. x would always be set equal to -1.) In other situations, placing a semicolon at a line’s end is syntactically incorrect. However, FORTRAN syntax does not use semicolons. The default mode will treat

if(x < 0) then
  x = -1
end if

as though one had entered

if(x < 0) then;
  x = -1;
end if;

Although the semicolons after then and if make no sense, FWEAVE has been endowed with special grammar rules such that this and similar examples will be typeset correctly.

Note: For FORTRAN, the grammar rules of Version 1.70 (2023) have been tested only with the default, auto-pseudo-semicolon mode. It is highly likely that some constructions will not typeset correctly if one overrides the default and inserts semicolons in a ’logical’ way.

Next: , Previous: -n;, Up: Options   [Contents][Index]

4.2.34 ‘-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.,


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.

Next: , Previous: -ncolon, Up: Options   [Contents][Index]

4.2.35 ‘-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 -b.

Next: , Previous: -nb, Up: Options   [Contents][Index]

4.2.36 ‘-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:

Next: , Previous: -nC, Up: Options   [Contents][Index]

4.2.37 ‘-np’: Print semicolons [FORTRAN] (FWEAVE)

Although the FORTRAN input driver automatically terminates logical lines with semicolons (FORTRAN-77; see -n;) or pseudo-semicolons (FORTRAN-90; see -nAT;) 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 -n;.

Next: , Previous: -np, Up: Options   [Contents][Index]

4.2.38 ‘-n\’: Free-form syntax continued by backslash

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

program main
x = \

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

See also -n&.

Next: , Previous: -n\, Up: Options   [Contents][Index]

4.2.39 ‘-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,

program main
x = &

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 -n\.

Next: , Previous: -n&, Up: Options   [Contents][Index]

4.2.40 ‘-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 string concatenation by default. To make it denote a short comment, use the ‘-n/’ option. One can do this in the .fweb file (see Customization) or with the language-setting command in limbo, as in ‘@n/’.

Obviously, use of this options assumes that you will never concatenate strings with ‘//’; therefore, if you want to hark strictly to the syntax of modern FORTRAN, use of this option is not recommended.

However, FWEB permits one to instead use ‘\/’ for concatenation, so there’s no penalty for using ‘-n/’.

Next: , Previous: -n/, Up: Options   [Contents][Index]

4.2.41 ‘-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 -n/). See also -! and -r!.

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.

Next: , Previous: -n!, Up: Options   [Contents][Index]

4.2.42 ‘-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 $UNQUOTE):

@m SP $UNQUOTE(' ')
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 Style.) ‘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.

Next: , Previous: -n), Up: Options   [Contents][Index]

4.2.43 ‘-o’: Don’t overload operators

This option inhibits the operator-overloading feature invoked by the command ‘@v’ (see Overloading).

Next: , Previous: -o, Up: Options   [Contents][Index]

4.2.44 ‘-q’: Don’t translate RATFOR

This option is obsolete.

Next: , Previous: -q, Up: Options   [Contents][Index]

4.2.45 ‘-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.

Next: , Previous: -P_, Up: Options   [Contents][Index]

4.2.46 ‘-p’: Buffer up a style-file entry

This option specifies a style-file entry (see Style). 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 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.

Next: , Previous: -p, Up: Options   [Contents][Index]

4.2.47 ‘-r’: Set global language to RATFOR–77

See Languages, and Ratfor. See also -L_.

Next: , Previous: -r, Up: Options   [Contents][Index]

4.2.48 ‘-r9’: Set global language to RATFOR–90

See Languages, and Ratfor. See also -L_.

Next: , Previous: -r9, Up: Options   [Contents][Index]

4.2.49 ‘-rg’: Set goto parameters

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

Next: , Previous: -rg, Up: Options   [Contents][Index]

4.2.50 ‘-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.

Next: , Previous: -rk, Up: Options   [Contents][Index]

4.2.51 ‘-rK’: Write comments about RATFOR translation (FTANGLE)

This is the negative of ‘-rk’ (see -rk); it forces comments about particular RATFOR commands.

Next: , Previous: -rK_, Up: Options   [Contents][Index]

4.2.52 ‘-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.

Next: , Previous: -rAT;, Up: Options   [Contents][Index]

4.2.53 ‘-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.

Next: , Previous: -r;, Up: Options   [Contents][Index]

4.2.54 ‘-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 -b.

Next: , Previous: -rb, Up: Options   [Contents][Index]

4.2.55 ‘-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 -n/.

Next: , Previous: -r/, Up: Options   [Contents][Index]

4.2.56 ‘-r!’: Make ‘!’ denote short comment [RATFOR]

See the corresponding discussion of ‘-!’ in -! and -n!.

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

        s = "A \! inside a string"

Next: , Previous: -r!, Up: Options   [Contents][Index]

4.2.57 ‘-r)’: Reverse array indices [RATFOR] (FTANGLE)

See the corresponding discussion of ‘-n)’ in -n).

Next: , Previous: -r), Up: Options   [Contents][Index]

4.2.58 ‘-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.

Next: , Previous: -s, Up: Options   [Contents][Index]

4.2.59 ‘-T’: Flag-setting options for FTANGLE

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

Next: , Previous: -T_, Up: -T_   [Contents][Index] ‘-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).

Next: , Previous: -TD, Up: -T_   [Contents][Index] ‘-Tb’: Permit built-functions to be redefined

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

Next: , Previous: -Tb, Up: -T_   [Contents][Index] ‘-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 Built-in functions, such as $PI, are in fact implemented as macros.

Next: , Previous: -Tm, Up: -T_   [Contents][Index] ‘-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 -F_) is in effect, since the header information includes a time stamp that would defeat a successful file comparison.]

Next: , Previous: -Tv, Up: -T_   [Contents][Index] ‘-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.

Previous: -T%, Up: -T_   [Contents][Index] ‘-T#’: Don’t insert ‘#line’ command after ‘@%

If the ‘@%’ command (see AT%) 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 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 Support), use the ‘-T#’ option.

Next: , Previous: -T_, Up: Options   [Contents][Index]

4.2.60 ‘-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.

Next: , Previous: -t, Up: Options   [Contents][Index]

4.2.61 ‘-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.

Next: , Previous: -U_, Up: Options   [Contents][Index]

4.2.62 ‘-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.

Next: , Previous: -u, Up: Options   [Contents][Index]

4.2.63 ‘-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 -M_).

Next: , Previous: -V_, Up: Options   [Contents][Index]

4.2.64 ‘-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 Initialization).

Next: , Previous: -v, Up: Options   [Contents][Index]

4.2.65 ‘-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’.

Next: , Previous: -W_, Up: -W_   [Contents][Index] ‘-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 Initialization).

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

Next: , Previous: -WAT, Up: -W_   [Contents][Index] ‘-W1’: Cross-reference single-character identifiers

By default, FWEAVE 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.

Next: , Previous: -W1, Up: -W_   [Contents][Index] ‘-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.

Note: FORTRAN added square brackets to the language in 2003. Therefore, the ‘-W[’ option should not be used for F03 and above.

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.

Next: , Previous: -W[, Up: -W_   [Contents][Index] ‘-WH’: Send additional arguments to the C preprocessor

When the ‘-H’ option (see -H_) 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

Previous: -WH_, Up: -W_   [Contents][Index] ‘-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.

Next: , Previous: -W_, Up: Options   [Contents][Index]

4.2.66 ‘-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 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 fwebmac.sty). However, try to not do that. Please submit requests for such behavior modifications to the developer; see Support.

Next: , Previous: -w, Up: Options   [Contents][Index]

4.2.67 ‘-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.

Next: , Previous: -x, Up: Options   [Contents][Index]

4.2.68 ‘-X’: Print selected cross-reference information (FWEAVE)

When used with any of the arguments ‘cim’, this option is the opposite of ‘-x’. See -x.

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 Using 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.

Next: , Previous: -X_, Up: Options   [Contents][Index]

4.2.69 ‘-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 Memory allocation.

Next: , Previous: -y, Up: Options   [Contents][Index]

4.2.70 ‘-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 -p) 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 Color.

Next: , Previous: -Z_, Up: Options   [Contents][Index]

4.2.71 ‘-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.’.

Next: , Previous: -z, Up: Options   [Contents][Index]

4.2.72 ‘-.’: 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.’.

Next: , Previous: -., Up: Options   [Contents][Index]

4.2.73 ‘-\’: 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 \

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.

Next: , Previous: -\, Up: Options   [Contents][Index]

4.2.74 ‘-(’: Continue parenthesized strings with backslashes

This option is like ‘-\’ (see -\), but it refers to certain strings that are not normally quoted, such as the arguments of ‘ifelse’ commands in m4.

Next: , Previous: -lp, Up: Options   [Contents][Index]

4.2.75 ‘-:’: Set starting automatic statement number

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

Next: , Previous: -colon, Up: Options   [Contents][Index]

4.2.76 ‘->’: 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 -=).

Next: , Previous: ->, Up: Options   [Contents][Index]

4.2.77 ‘-=’: Redirect output (FTANGLE)

Equivalent to ‘->’ (see ->), and faster to type on many keyboards.

Next: , Previous: -=, Up: Options   [Contents][Index]

4.2.78 ‘-#’: 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; 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 ATq.

Next: , Previous: -#, Up: Options   [Contents][Index]

4.2.79 ‘-+’: 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 -ylx.

Next: , Previous: -plus, Up: Options   [Contents][Index]

4.2.80 ‘-/’: 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 -n/ and -r/.

Next: , Previous: -/, Up: Options   [Contents][Index]

4.2.81 ‘-!’: 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"

Previous: -!, Up: Options   [Contents][Index]

4.2.82 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 -AT.

-D’ displays information about reserved words. See -D_.

-y’ displays default dynamic memory allocations. See -y.

-Z’ displays default values of style-file parameters. See -Z_.

The ‘-h’ option reminds one about these information options; it also provides convenient access to the GNU info browser. See -h.

Next: , Previous: Starting, Up: Top   [Contents][Index]


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 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 Structure.) For a quick summary of the control-code mappings and to see which codes begin new parts, say ‘ftangle -@’. See -AT.

Next: , Previous: AT commands, Up: AT commands   [Contents][Index]

5.1 Debugging commands

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

5.1.1 ‘@0’: Turn off debugging

This cancels the effect of a previous ‘@1’ or ‘@2’ (see AT1 and AT2). The ‘@0’ command should appear in a different section from the ‘@1’ or ‘@2’ commands.

Next: , Previous: AT0, Up: AT commands   [Contents][Index]

5.1.2 ‘@1’: Display irreducible scraps

This is a local version of the command-line option ‘-1’ (see -1); refer to that discussion for more information.

Next: , Previous: AT1, Up: AT commands   [Contents][Index]

5.1.3 ‘@2’: Display detailed reductions of the scraps

This is a local version of the command-line option ‘-2’ (see -2); refer to that discussion for more information.

Next: , Previous: AT2, Up: AT commands   [Contents][Index]

5.2 Literal control characters

Several commands insert specific characters.

5.2.1 ‘@@’: 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 `@@'");

Next: , Previous: ATAT, Up: AT commands   [Contents][Index]

5.2.2 ‘@|’: 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 AT|_.

In a code part, ‘@|’ inserts an optional line break in an expression—e.g.,


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 ATbs) and ‘@/’ (see AT/), which always break the line.]

Next: , Previous: AT|, Up: AT commands   [Contents][Index]

5.3 Beginning of section

Sections are begun by either ‘@*’ or ‘.

5.3.1 ‘@ ’: Begin minor section

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.)


Next: , Previous: ATspace, Up: AT commands   [Contents][Index]

5.3.2 ‘@*’, ‘@*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).


@*1 [Input routines\dots]A very long section name that essentially
means ``input routines.''  Now follow some subroutines. 


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 Numbering.

Next: , Previous: AT*, Up: AT commands   [Contents][Index]

5.4 Beginning of code part

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

5.4.1 ‘@<’: Begin module name

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

Next: , Previous: AT<, Up: AT commands   [Contents][Index]

5.4.2 ‘@>’: 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).

Next: , Previous: AT>, Up: AT commands   [Contents][Index]

5.4.3 ‘@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’.

For more discussion of the distinction between ‘@A’ and ‘@a’, see ATa.

Next: , Previous: ATA_, Up: AT commands   [Contents][Index]

5.4.4 ‘@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 AT[) 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.,


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 -f.) However, if a section contains an arbitrary code fragment, the code part should probably begin with ‘@A’. E.g.,

x = y;

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

Next: , Previous: ATa, Up: AT commands   [Contents][Index]

5.5 Control codes b–z

5.5.1 ‘@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 ATb.

Next: , Previous: ATB_, Up: AT commands   [Contents][Index]

5.5.2 ‘@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 ATB_.

Next: , Previous: ATb, Up: AT commands   [Contents][Index]

5.5.3 ‘@c’: Set language to C

The command ‘@c’ is a shorthand for ‘@Lc’. Usually, this command appears in the limbo section. (For a discussion of language commands in limbo, see ATL_.)

If a language-changing command such as ‘@c’ occurs in the code section of a module, the language remains in effect only until the end of the module. Any module names that are encountered during the scan of the module inherit that new language.

See Languages, and C.

Next: , Previous: ATc, Up: AT commands   [Contents][Index]

5.5.4 ‘@c++’: Set language to C++

The command ‘@c++’ is a shorthand for ‘@Lc++’. For a discussion of language commands in limbo, see ATL_.

See Languages, and Cpp.

Next: , Previous: ATcpp, Up: AT commands   [Contents][Index]

5.5.5 ‘@D’: Define outer macro

This command begins the definition part.

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

@D A 1

will be tangled to the beginning of the output file as ‘#define A 1’.

Next: , Previous: ATD_, Up: AT commands   [Contents][Index]

5.5.6 ‘@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 AT[).

The distinction between ‘@d’ and ‘@D’ is analagous to the distinction between ‘@a’ and ‘@A’. See ATa.

Next: , Previous: ATd, Up: AT commands   [Contents][Index]

5.5.7 ‘@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 Macros and formatting.

Next: , Previous: ATE_, Up: AT commands   [Contents][Index]

5.5.8 ‘@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, if the language is C,

@f mytype int

says to treat the variable mytype just as int is treated (e.g., as a reserved word in C or C++). If, on the other hand, the language is FORTRAN, mytype will be treated as an ordinary identifier, since int is not a reserved word, an intrinsic macro, an intrinsic function, or a keyword in that language.

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 -H_.

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:


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

@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.

Next: , Previous: ATf, Up: AT commands   [Contents][Index]

5.5.9 ‘@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 Environment variables and -I_.

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 ‘) 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 -yid.

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


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


Next: , Previous: ATi, Up: AT commands   [Contents][Index]

5.5.10 ‘@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 -i, and -i!.

Next: , Previous: ATI_, Up: AT commands   [Contents][Index]

5.5.11 ‘@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 ATz.) 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,

$Id:  test $


\def\ID{Id = \.{"@K Id @>"}}

@ \ID.  This is a @K Id @>.

will expand into


@ \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 $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 ATk.

Next: , Previous: ATK_, Up: AT commands   [Contents][Index]

5.5.12 ‘@k’: Access local RCS-like keyword

The construction ‘@k keyword’ behaves as ‘@K’ does (see ATK_), except it accesses local keywords (defined at the top of include files).

Next: , Previous: ATk, Up: AT commands   [Contents][Index]

5.5.13 ‘@L’: Set language

@Ll sets the language to l, where l is one of ‘{c,c++,n,r,v,x}’. The letters ‘c’ and ‘n’ can be followed by a numeric argument that specifies the language version. See Languages.

There are shorthand forms of this command for some languages; see ‘@c’ (ATc), ‘@c++’ (ATcpp), ‘@n’ (ATn), ‘@n9’ (ATn9), ‘@r’ (ATr), and ‘@r9’ (ATr9).

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’.

The optional command ‘@LWl is used only by FWEAVE. (If it is used, it sets the language FWEAVE uses to parse the TeX and code parts of each section (thus overriding the global language for those parts). This command may be used only in limbo. For more discussion of the use of ‘@LW’, see @LW.

Next: , Previous: ATL_, Up: AT commands   [Contents][Index]

5.5.14 ‘@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.

Next: , Previous: ATl, Up: AT commands   [Contents][Index]

5.5.15 ‘@M’: Define FWEB macro

This command begins the definition part.

For a detailed discussion of FWEB macros, see Macros.

Next: , Previous: ATM_, Up: AT commands   [Contents][Index]

5.5.16 ‘@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 AT[).

For a detailed discussion of FWEB macros, see Macros.

The distinction between ‘@m’ and ‘@M’ is analagous to the distinction between ‘@a’ and ‘@A’. See ATa.

Next: , Previous: ATm, Up: AT commands   [Contents][Index]

5.5.17 ‘@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
    @!A = A;

    expands to ‘A = 1’.

  2. Blank lines are significant. The N mode is ended by the appearance of the ‘@*’ or ‘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,
    @ 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}.)

    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.

Next: , Previous: ATN_, Up: AT commands   [Contents][Index]

5.5.18 ‘@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.

This command may be followed by one of the following numeric arguments: 7, 77, 9, 90, 3, 2003, 8, 2008, 18, 2018, 23, 2023.

For more discussion of languages, see ATL_ and Languages.

Next: , Previous: ATn, Up: AT commands   [Contents][Index]

5.5.19 ‘@n9’: Set language to FORTRAN–90

For more discussion of languages, see ATL_ and Languages.

For hints about FWEB programming in FORTRAN, see Fortran.

Next: , Previous: ATn9, Up: AT commands   [Contents][Index]

5.5.20 ‘@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 Outer macros.

To change the name of the output file locally (for just the present section), see ATo.

Next: , Previous: ATO_, Up: AT commands   [Contents][Index]

5.5.21 ‘@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 -#), but then debugger statements will refer to the tangled C code, which is undesirable. A better partial solution is to use ‘@q’ (see ATq) 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:

@o file1.c
        @<File 1@>@;
@o file2.c
        @<File 2@>@;
@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 Merging indexes to learn how to create a master index that contains information about several web files.

Next: , Previous: ATo, Up: AT commands   [Contents][Index]

5.5.22 ‘@q’: Turn off module and line info locally

The command-line option ‘-#’ (see -#) 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

      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

      x = @<Some action@>

it will tangle to

      x = y + z

as one desires.

For another use of the ‘@q’ command, see ATo.

Next: , Previous: ATq, Up: AT commands   [Contents][Index]

5.5.23 ‘@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 Macros and formatting.

Next: , Previous: ATR_, Up: AT commands   [Contents][Index]

5.5.24 ‘@r’: Set language to RATFOR–77

See ATL_, and Languages.

Next: , Previous: ATr, Up: AT commands   [Contents][Index]

5.5.25 ‘@r9’: Set language to RATFOR–90

See ATL_, and Languages.

Next: , Previous: ATr9, Up: AT commands   [Contents][Index]

5.5.26 ‘@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’.

Next: , Previous: ATu, Up: AT commands   [Contents][Index]

5.5.27 ‘@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 Overloading.

Next: , Previous: ATv, Up: AT commands   [Contents][Index]

5.5.28 ‘@W’: Overload identifier

This command begins the definition part.

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

Next: , Previous: ATW_, Up: AT commands   [Contents][Index]

5.5.29 ‘@x’: Terminate ignorable material, or begin material to be changed

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

In web source files, this command has a different use; see the discussion of the ‘@z’ command (see ATz).

Next: , Previous: ATx, Up: AT commands   [Contents][Index]

5.5.30 ‘@y’: Begin change material

The ‘@y’ command is permitted only in change files. See Change files.

Next: , Previous: ATy, Up: AT commands   [Contents][Index]

5.5.31 ‘@z’: Begin ignorable material, or terminate change

FWEB files may begin with the construction


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 ATK_) and ‘@k’ (see ATk) as well as to FTANGLE’s built-in function $KEYWORD (see $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 Change files.

Next: , Previous: ATz, Up: AT commands   [Contents][Index]

5.6 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.

5.6.1 ‘@'’: 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 -A_.

Next: , Previous: ATquote, Up: AT commands   [Contents][Index]

5.6.2 ‘@"’: 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 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 -A_.

Next: , Previous: ATdquote, Up: AT commands   [Contents][Index]

5.7 Forward referencing

5.7.1 ‘@[’: 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 Subscript params.

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

@ This is section 6.
        program main
        call test // This will print as $|test|_5$.

The ‘@[’ command should be distinguished from ‘@_’ (see AT_). 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.

Next: , Previous: AT[, Up: AT commands   [Contents][Index]


FWEB supports a variety of commenting styles borrowed from C, C++, and TeX. For more discussion, see Comments.

5.8.1 ‘@/*’: Begin long verbatim comment

The following comment (terminated by ‘*/’) is copied to the tangled output. (By default, comments are not copied.) If you desire all comments to be so copied, use ‘-v’. See -v.

Next: , Previous: AT/*, Up: AT commands   [Contents][Index]

5.8.2 ‘@//’: Begin short verbatim comment

See the discussion of ‘@/*’ in AT//.

Next: , Previous: AT//, Up: AT commands   [Contents][Index]

5.8.3 ‘@%’: 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 ATN_.

Line-numbering problems can arise when these commands are used. For a discussion, see -T#.

Next: , Previous: AT%, Up: AT commands   [Contents][Index]

5.8.4 ‘@?’: 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 Miscellaneous params.

Next: , Previous: AT?, Up: AT commands   [Contents][Index]

5.8.5 ‘@(’: 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 Miscellaneous params).

Next: , Previous: ATlp, Up: AT commands   [Contents][Index]

5.8.6 ‘@)’: End meta-comment

See the discussion of ‘@(’, ATlp.

Next: , Previous: AT), Up: AT commands   [Contents][Index]

5.9 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
        int i;

        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;

Next: , Previous: ATlb, Up: AT commands   [Contents][Index]

5.10 Index entries

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

5.10.1 ‘@_’: 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.

Next: , Previous: AT_, Up: AT commands   [Contents][Index]

5.10.2 ‘@-’: 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.

Next: , Previous: AT-, Up: AT commands   [Contents][Index]

5.10.3 ‘@+’: 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.

Next: , Previous: ATplus, Up: AT commands   [Contents][Index]

5.10.4 ‘@^’: Make index entry (Roman type)

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

Next: , Previous: AT^, Up: AT commands   [Contents][Index]

5.10.5 ‘@.’: Make index entry (typewriter type)

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

Next: , Previous: ATdot, Up: AT commands   [Contents][Index]

5.10.6 ‘@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


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.)

Next: , Previous: AT9, Up: AT commands   [Contents][Index]

5.11 Control text

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

5.11.1 ‘@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.

Next: , Previous: ATt, Up: AT commands   [Contents][Index]

5.11.2 ‘@=’: 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.

Next: , Previous: AT=, Up: AT commands   [Contents][Index]

5.12 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.

5.12.1 ‘@,’: 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:

@m OP +
@m A(x,y) x @, OP @, y

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 ATf.

Next: , Previous: ATcomma, Up: AT commands   [Contents][Index]

5.12.2 ‘@/’: 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


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 ATbs.

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 ATf) or ‘-H’ (see -H_).

Distinguish the ‘@/’ command from ‘@|’ (see AT|), which inserts an optional breakpoint into an expression.

Next: , Previous: AT/, Up: AT commands   [Contents][Index]

5.12.3 ‘@\’: Force a line break, then indent

The ‘@\’ command behaves like ‘@/’ (see AT/), 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 @\

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.

Next: , Previous: ATbs, Up: AT commands   [Contents][Index]

5.12.4 ‘@|’: Literal vertical bar, or optional line break

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

  The constructions @|x@| and |x| are very different.

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

In a code part, ‘@|’ inserts an optional line break in an expression.

Next: , Previous: AT|_, Up: AT commands   [Contents][Index]

5.12.5 ‘@#’: 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 Preprocessing.

Next: , Previous: AT#, Up: AT commands   [Contents][Index]

5.12.6 ‘@~’: 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;

Next: , Previous: AT~, Up: AT commands   [Contents][Index]

5.12.7 ‘@&’: 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.

Next: , Previous: AT&, Up: AT commands   [Contents][Index]

5.13 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.

5.13.1 ‘@e’: Pseudo-expression

@e’ is an invisible expression (‘pseudo-expression’) (see 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.

Next: , Previous: ATe, Up: AT commands   [Contents][Index]

5.13.2 ‘@;’: 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:

        @<Compound statement@>@;
        @<Simple statement@>;

@ This compound statement ends with a brace, but is used as an
expression above.


@ This fragment does not end with a semicolon, so one must be 
supplied above.


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

@ 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 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 -nAT;) and ‘-n;’ (see -n;).

Next: , Previous: AT;, Up: AT commands   [Contents][Index]

5.13.3 ‘@:’: Pseudo-colon

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

case 1:
case 2:
case 3@: @;

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


Previous: ATcolon, Up: AT commands   [Contents][Index]

5.14 Miscellaneous commands

5.14.1 ‘@!’: 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 ‘@!’.

Next: , Previous: AT commands, Up: Top   [Contents][Index]


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

Next: , Previous: Comments, Up: Comments   [Contents][Index]

6.1 Invisible comments


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 $KEYWORD, ATK_ (source files), or ATk (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,

Author:  J. A. Krommes
@c @% This sets the global language to C.
void test()
int i;

i = 1;
@%i = 2;

Next: , Previous: Invisible comments, Up: Comments   [Contents][Index]

6.2 Visible comments

FWEB supports several commenting styles.

/* ... */’ 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 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 Miscellaneous params.

        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)

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.

Previous: Visible comments, Up: Comments   [Contents][Index]

6.3 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 the FWEB form @#if 0...@#endif (usable in all languages). (The FWEB preprocessor is described in 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.

This important discussion is repeated in Converting.

For FORTRAN programmers converting an existing code to FWEB, the ‘-nC’ option (see -nC) may be helpful.

Next: , Previous: Languages, Up: Top   [Contents][Index]


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 (such as ‘#if ... #endif’ in C) 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 Built-in functions. They can be useful to programmers in all languages.

FWEB recognizes two kinds of macros: outer macros, and 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 FWEB macros.

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

Next: , Previous: Macros, Up: Macros   [Contents][Index]

7.1 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 ATd) or ‘@D’ (see ATD_). 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,

@d YES 1
@d NO 0

@d BUF_LEN 100

The keyword into which the ‘@d’ is translated is language-dependent; it is controlled by the style-file parameter ‘outer_def’. See Miscellaneous params.

Outer macros can be undefined by ‘@u’. The translation is controlled by the style-file parameter ‘outer_undef’. See Miscellaneous params.

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:

We assume command-line redirection into \.{test.h} (`\.{-=test.h}').

@d A 1 // This will go into \.{test.h}.

@<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@>=

@<Global variables@>@;

Next: , Previous: Outer macros, Up: Macros   [Contents][Index]

7.2 FWEB macros

FWEB macros (sometimes called inner macros) are defined by ‘@m’ (see ATm) or ‘@M’ (see ATM_). These should normally be placed in the definition part, as in

@ Documentation...

@m CUBE(x) (x)**3

        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. 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.

Next: , Previous: FWEB macros, Up: FWEB macros   [Contents][Index]

7.2.1 Various features of FWEB macros

Next: , Previous: Macro features, Up: Macro features   [Contents][Index] 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’ (the number of variable arguments), ‘#n’ (the value of the nth optional argument), and ‘#.’ (a comma-delimited list of the optional arguments) are useful in this context.

Next: , Previous: Variable arguments, Up: Macro features   [Contents][Index] 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 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!

Previous: Recursion, Up: Macro features   [Contents][Index] 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 Protection. To override that protection, use the command-line options ‘-Tb’ (-Tb; for built-in functions) or ‘-Tm’ (-Tm; for macros).

Next: , Previous: Macro features, Up: FWEB macros   [Contents][Index]

7.2.2 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)
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.


Like ‘#parameter’, but pass a quoted string through unchanged.


Don’t expand argument.


Convert parameter to a single-quoted string (no expansion).


Convert parameter to a double-quoted string (no expansion).


Number of variable arguments.


n-th variable argument, counting from 1.


Like ‘#0’, but the argument may be a macro expression known at run time.


Like ‘#n’, but the argument may be a macro expression.


The total number of arguments (fixed + variable). (The argument inside the brackets may be a macro expression.)


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.


Unique statement number (expanded in phase 1).


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:

@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.

@m DONE #:0 // Symbolic statement label in FORTRAN.
        goto DONE
        call endup

Next: , Previous: Tokens, Up: FWEB macros   [Contents][Index]

7.2.3 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 $DUMPDEF.

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.

Next: , Previous: Built-in functions, Up: Built-in functions   [Contents][Index] Strings and quotes

Several of the built-in functions expect or return a string argument. Examples include $STRING (see $STRING), $UNQUOTE (see $UNQUOTE), and $UNSTRING (see $UNSTRING). 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 $P) and $PP (see $PP), 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.

Next: , Previous: Strings and quotes, Up: Built-in functions   [Contents][Index] 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 -Tb).

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 $POW), which is constructed from the built-in function $EVAL (see $EVAL). By default, such macros are also protected against redefinition; to override, use the option ‘-Tm’ (see -Tm).

Next: , Previous: Protection, Up: Built-in functions   [Contents][Index] $A: Convert to ASCII

$A(string)’ is the built-in equivalent of ‘@'...'’ or ‘@"..."’. (See ATquote and ATdquote.) Note the extra parentheses required by the built-in.

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

Next: , Previous: $A, Up: Built-in functions   [Contents][Index] $ABS: Absolute value

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

Next: , Previous: $ABS, Up: Built-in functions   [Contents][Index] $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).

Next: , Previous: $ASSERT, Up: Built-in functions   [Contents][Index] $AUTHOR: Value of RCS global keyword Author

Equivalent to ‘$KEYWORD(Author)’. See $KEYWORD.

Next: , Previous: $AUTHOR, Up: Built-in functions   [Contents][Index] $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

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

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

Next: , Previous: $COMMENT, Up: Built-in functions   [Contents][Index] $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.

Next: , Previous: $DATE, Up: Built-in functions   [Contents][Index] $DATE_TIME: Value of RCS global keyword Date

Equivalent to ‘$KEYWORD(Date)’. See $KEYWORD.

Next: , Previous: $DATE_TIME, Up: Built-in functions   [Contents][Index] $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.

Next: , Previous: $DAY, Up: Built-in functions   [Contents][Index] $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’.

Next: , Previous: $DECR, Up: Built-in functions   [Contents][Index] $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


This expands to ‘(x)’.

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

Next: , Previous: $DEFINE, Up: Built-in functions   [Contents][Index] $DO: Macro do loop

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

  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.

Next: , Previous: $DO, Up: Built-in functions   [Contents][Index] $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


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.

Next: , Previous: $DUMPDEF, Up: Built-in functions   [Contents][Index] $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).

Next: , Previous: $E, Up: Built-in functions   [Contents][Index] $ERROR: Send error message to output

$ERROR(string)’ prints an error message in FWEB’s standard form.

Next: , Previous: $ERROR, Up: Built-in functions   [Contents][Index] $EVAL: Evaluate a macro expression

$EVAL(expression)’ uses FWEB’s macro-expression evaluator (see 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.

Next: , Previous: $EVAL, Up: Built-in functions   [Contents][Index] $EXP: Exponential function

$EXP(x)’ returns e to the power x.

Next: , Previous: $EXP, Up: Built-in functions   [Contents][Index] $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.

Next: , Previous: $GETENV, Up: Built-in functions   [Contents][Index] $HEADER: Value of RCS global keyword Header

Equivalent to ‘$KEYWORD(Header)’. See $KEYWORD.

Next: , Previous: $HEADER, Up: Built-in functions   [Contents][Index] $HOME: The user’s home directory

$HOME’ is a convenience macro equivalent to ‘$GETENV(HOME)’.

Next: , Previous: $HOME, Up: Built-in functions   [Contents][Index] $ID: Value of RCS global keyword Id

Equivalent to ‘$KEYWORD(Id)’. See $KEYWORD.

Next: , Previous: $ID, Up: Built-in functions   [Contents][Index] $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.

Next: , Previous: $IF, Up: Built-in functions   [Contents][Index] $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'

Next: , Previous: $IFCASE, Up: Built-in functions   [Contents][Index] $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)

Next: , Previous: $IFDEF, Up: Built-in functions   [Contents][Index] $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)’.

Next: , Previous: $IFNDEF, Up: Built-in functions   [Contents][Index] $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,

$IFELSE("abc", S, yes, no)

evaluates to ‘yes’.

Next: , Previous: $IFELSE, Up: Built-in functions   [Contents][Index] $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’.

Next: , Previous: $INCR, Up: Built-in functions   [Contents][Index] $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, $OUTPUT_LINE.

Next: , Previous: $INPUT_LINE, Up: Built-in functions   [Contents][Index] $KEYWORD: Value of global RCS-like keyword

$KEYWORD’ provides a built-in function alternative to the use of ‘@K’ in a code part. (see ATK_).

$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 ATz). (RCS stands for “revision-control system.”) The general syntax is (UNIX users, see ‘man ident’)

$Keyword: text of keyword $

For example,

$Author: krommes $

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 ATk).

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

$AUTHOR    => $KEYWORD(Author)
$HEADER    => $KEYWORD(Header)
$ID        => $KEYWORD(Id)
$LOCKER    => $KEYWORD(Locker)
$NAME      => $KEYWORD(Name)
$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.

Next: , Previous: $KEYWORD, Up: Built-in functions   [Contents][Index] $L: Change to lower case

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

Next: , Previous: $L, Up: Built-in functions   [Contents][Index] $L_KEYWORD: Value of local RCS-like keyword

For most purposes, ‘$L_KEYWORD’ behaves as ‘@k’ (see ATk). 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 ATz and $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.

Next: , Previous: $L_KEYWORD, Up: Built-in functions   [Contents][Index] $LANGUAGE: Identifier for current language

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


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 $LANGUAGE_NUM.

Next: , Previous: $LANGUAGE, Up: Built-in functions   [Contents][Index] $LANGUAGE_NUM: Number of current language

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


This built-in is useful in conjunction with an $IFCASE construction; see $IFCASE.

Next: , Previous: $LANGUAGE_NUM, Up: Built-in functions   [Contents][Index] $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

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)

Next: , Previous: $LEN, Up: Built-in functions   [Contents][Index] $LOCKER: Value of RCS global keyword Locker

Equivalent to ‘$KEYWORD(Locker)’. See $KEYWORD.

Next: , Previous: $LOCKER, Up: Built-in functions   [Contents][Index] $LOG: Natural logarithm

$LOG(x)’ returns the natural logarithm of x.

Next: , Previous: $LOG, Up: Built-in functions   [Contents][Index] $LOG10: Logarithm to the base 10

$LOG10(x)’ returns the logarithm to the base 10 of x.

Next: , Previous: $LOG10, Up: Built-in functions   [Contents][Index] $M: Define a deferred macro

$M is equivalent to $DEFINE. See $DEFINE.

Next: , Previous: $M, Up: Built-in functions   [Contents][Index] $MAX: Maximum of a list

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

Next: , Previous: $MAX, Up: Built-in functions   [Contents][Index] $MIN: Minimum

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

Next: , Previous: $MIN, Up: Built-in functions   [Contents][Index] $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".

Next: , Previous: $MODULE_NAME, Up: Built-in functions   [Contents][Index] $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.

Next: , Previous: $MODULES, Up: Built-in functions   [Contents][Index] $NAME: Value of RCS global keyword Name

Equivalent to ‘$KEYWORD(Name)’. See $KEYWORD.

Next: , Previous: $NAME, Up: Built-in functions   [Contents][Index] $OUTPUT_LINE: Current line number of tangled output

This returns the current line number of the tangled output. Contrast this with $INPUT_LINE, $INPUT_LINE.

Next: , Previous: $OUTPUT_LINE, Up: Built-in functions   [Contents][Index] $P: The C preprocessor symbol

$P is (essentially) a synonym for ‘$UNQUOTE("#")’ (see $UNQUOTE). 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 $PP). 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 Strings and quotes.

Next: , Previous: $P, Up: Built-in functions   [Contents][Index] $PI: Pi

The expression ‘$PI’ returns pito the default machine precision. The expression ‘$PI(iprec)’ returns pi to the decimal precision iprec (which must be less than 50).

Next: , Previous: $PI, Up: Built-in functions   [Contents][Index] $POW: Exponentiation

$POW(x,y)’ generates x raised to the power y. (It is a macro defined in terms of $EVAL (see $EVAL) and the exponentiation operator.)

Next: , Previous: $POW, Up: Built-in functions   [Contents][Index] $PP: The C preprocessor symbol

$PP is shorthand for ‘$UNSTRING($P)’ (see $P), or (essentially) a synonym for ‘$UNSTRING("#")’ (see $UNSTRING). It is useful, particularly in FORTRAN, for constructing FWEB macro definitions that expand to C preprocessor statements. For an example, see $P. For a detailed discussion of the difference between ‘$P’ and ‘$PP’, see Strings and quotes.

Next: , Previous: $PP, Up: Built-in functions   [Contents][Index] $RCSFILE: Value of RCS global keyword $RCSfile

Equivalent to ‘$KEYWORD(RCSfile)’. See $KEYWORD.

Next: , Previous: $RCSFILE, Up: Built-in functions   [Contents][Index] $REVISION: Value of RCS global keyword Revision

Equivalent to ‘$KEYWORD(Revision)’. See $KEYWORD.

Next: , Previous: $REVISION, Up: Built-in functions   [Contents][Index] $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.

Next: , Previous: $ROUTINE, Up: Built-in functions   [Contents][Index] $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.)

Next: , Previous: $SECTION_NUM, Up: Built-in functions   [Contents][Index] $SECTIONS: Maximum section number

$SECTIONS’ is the maximum section number as understood by FWEAVE.

Next: , Previous: $SECTIONS, Up: Built-in functions   [Contents][Index] $SOURCE: Value of RCS global keyword Source

Equivalent to ‘$KEYWORD(Source)’. See $KEYWORD.

Next: , Previous: $SOURCE, Up: Built-in functions   [Contents][Index] $SQRT: Square root

$SQRT(x)’ returns the square root of x. It is a convenience macro defined in terms of $POW. See $POW.

Next: , Previous: $SQRT, Up: Built-in functions   [Contents][Index] $STATE: Value of RCS global keyword State

Equivalent to ‘$KEYWORD(State)’. See $KEYWORD.

Next: , Previous: $STATE, Up: Built-in functions   [Contents][Index] $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.

Next: , Previous: $STRING, Up: Built-in functions   [Contents][Index] $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’.

Next: , Previous: $STUB, Up: Built-in functions   [Contents][Index] $TIME: The time

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

Next: , Previous: $TIME, Up: Built-in functions   [Contents][Index] $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.

Next: , Previous: $TRANSLIT, Up: Built-in functions   [Contents][Index] $U: Change to upper case

$U(string)’ changes string to upper case.

Next: , Previous: $U, Up: Built-in functions   [Contents][Index] $UNDEF: Undefine a macro

$UNDEF(macro)’ undefines an FWEB macro.

Next: , Previous: $UNDEF, Up: Built-in functions   [Contents][Index] $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 $UNSTRING), see Strings and quotes.

Next: , Previous: $UNQUOTE, Up: Built-in functions   [Contents][Index] $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 $UNQUOTE), see Strings and quotes.

Next: , Previous: $UNSTRING, Up: Built-in functions   [Contents][Index] $VERBATIM: (Obsolete)

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

Previous: $VERBATIM, Up: Built-in functions   [Contents][Index] $VERSION: Present FWEB version number

$VERSION’ returns a string built out of the FWEB version number, such as "1.61".

Previous: Built-in functions, Up: FWEB macros   [Contents][Index]

7.2.4 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,

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

An alternative for highly confusing situations is to use the ‘-#’ option (see -#).

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 -T#.

Next: , Previous: FWEB macros, Up: Macros   [Contents][Index]

Macros and formatting

FWEAVE makes a valiant attempt to pretty-print (see 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:

@d GET(type) type get_##type()
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 ATR_), 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

@d A(x, y) x y
@d B s1;
@d C s2;
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 ATcomma.

Previous: Macros and formatting, Up: Macros   [Contents][Index]

7.3 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 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 FWEB macros.

The syntax of each command is as follows:


— 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

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 (printed documentation only):

Next: , Previous: Comments, Up: Top   [Contents][Index]


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 Miscellaneous params.

Next: , Previous: Languages, Up: Languages   [Contents][Index]

8.1 Setting the language

The most general form of a language command is (italic brackets denote optional)


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 optional ‘W’ denotes a special language command used only by FWEAVE; see below.

The language symbols must be in lower case; they are


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.


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.

The TeX part of each section, named or unnamed, starts off in the global language (FORTRAN in the example below). Suppose that in that TeX commentary one wants to discuss code in another language, say C. One can always enter code mode (surrounding code by vertical bars) and use an explicit language command, such as ‘|@c strcpy()|’. But if there are going to be many such language changes, an alternative is to issue a language command at the beginning of the commentary; see the example.

When control passes into the code part of the section, the language reverts to the language of the current module — either the unnamed module (begun by ‘@a’) or a named module. If a language commands is used within an unnamed code part, the language of the unnamed module is changed, and that change persists through all subsequent additions to the unnamed module.

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. A language command may be used within a named module, but that change is local to the current section.

To summarize these points:

These points are illustrated in the following example.

@n // Set the global language to Fortran-77.

@ If code mode is used within the commentary in this unnamed section,
it will be in Fortran unless an explicit language command is used
inside the vertical bars, like |@c strcpy()|.  

@ @c Because the \TeX\ part of this section begins with '@c', the
code-mode language in this part will be in C, 
so language changes inside vertical bars for C code are
unnecessary, e.g., |strcpy()|, |int i|. But consider |@n integer j|.

@a // Begin the unnamed module, which is in Fortran.

        program main

  Change the unnamed language to C.
  Any named modules that are subsequently referenced in the unnamed
  module will be in C (unless there is a another subsequent language
@<C module@>@; 

@ Code within this commentary is still in Fortran (the global
language).  But the named module definition that follows will be in C.

@<C module@>=
int fcn()
{ }

@ Code mode in this TeX part is still in Fortran.  To reference C
code, one must use a language command between the vertical bars:
|@c fcn()|.

@a /* An addition to the unnamed module, which at this point is in C.  
       Note that no ‘@c’ command is necessary here. */
int another_fcn()
{ }

@ If we want, we can change the unnamed language back to Fortran (and
that change will persist).
@a // More unnamed module
      subroutine test
      end subroutine test      

FTANGLE will write two output files for this example—e.g., test.f and test.c, appropriately accreting the contents of the Fortran and C parts of the unnamed module.

Although language changes in the TeX parts of each section are easy to deal with, frequent language changes for entire code parts can be confusing. In that case, consider using a separate web file for each language. The construction of a master index that encompasses several web files is discussed in Merging indexes.

8.2 The ‘@LW’ command

A special situation arises when the global language is VERBATIM. A particular use case is the creation of C header files from a web source file. With the global language set to VERBATIM, FTANGLE will output the unnamed module as usual (preserving spaces, unlike C output where the spaces are deliberately remored). FWEAVE will attempt to typeset all code in typewriter type. That is fine for the unnamed module, but it leads to a possible difficulty in the TeX commentary at the beginning of each section. If one is describing code intended, for example, for the C language, each instance of code between vertical bars would have to be begun with ‘@c’. That can be annoying and tedious. Furthermore, the replacement text of an outer macro definition (‘@d’) would not format correctly because the reserved words and production rules for C are not known to the VERBATIM language.

A solution is to use the command ‘@LWl’ command in limbo. For FWEAVE only, that overrides the global language for the TeX and definition parts.

This scheme is used by FWEB itself to create the files typedefs.h and typedefs.hweb from the master file typedefs.web. The basic structure of that file is as follows (the actual version is slightly more complex). This file is processed with the command ‘ftangle typedefs -=typedefs.h’.


@O typedefs.hweb
@<Macro definitions@>@;

@ Outer macro definitions are written to the top of FTANGLE's
output file, which for the VERBATIM language has the extension
‘.mk’.  That is overridden with the command-line redirection
option ‘-=’.

@d DEBUG 0

@@ (This commentary and the subsequent web macro
definition will be tangled literally into a proper FWEB section in
typedefs.hweb, which will later be included into the FWEB
sources via ‘@I’.)

A simple error message with no arguments is used frequently.  Error
messages now carry an indication of their origin.

@@m err_print(origin, msg, ...) 
	err0_print(ERR_##origin, OC(msg), #0, #.)

@ (This is commentary in typedefs.web itself.)  
In certain cases \.{TANGLE} and \.{WEAVE} should do almost, but not
quite, the same thing.  In these case we've written common code for
both, differentiating between the two by means of the global variable
|program|. (The identifier 'program' will be interpreted in the C
language, so it will be formatted as italics, not with typewriter type.)

The next command accretes to the unnamed module, placing the typedef
after all of the macro definitions.

typedef enum {tangle=0, weave=1} PROGRAM; /* The two processors. */


8.3 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 Cpp and Fortran.

Next: , Previous: Setting the language, Up: Languages   [Contents][Index]

8.3.1 Special considerations for C

(To be completed.)

Next: , Previous: C, Up: Languages   [Contents][Index]

8.3.2 Special considerations for C++

Next: , Previous: Cpp, Up: Languages   [Contents][Index]

8.3.3 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.)

Next: , Previous: Fortran, Up: Languages   [Contents][Index]

8.3.4 Special considerations for RATFOR

For some warnings about RATFOR, see Caveats.

Next: , Previous: Ratfor_, Up: Languages   [Contents][Index]

8.3.5 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 Support).

(To be completed.)

Previous: TeX, Up: Languages   [Contents][Index]

8.3.6 Special considerations for the VERBATIM language

Because the VERBATIM language is not fully debugged, it is not recommended for general use. It is, however, used by FWEB itself to create the header file typedefs.h and the include file typedefs.hweb from the web source typedefs.web. For more discussion, see @LW.

Next: , Previous: Macros, Up: Top   [Contents][Index]


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.)

Next: , Previous: Ratfor, Up: Ratfor   [Contents][Index]

9.1 RATFOR syntax

A sample RATFOR program is

program main
integer k;
real fcn, x;

for(k=0; k<10; k++)
        x = fcn(k);

        if(x < 0.0)
                x = 0.0;

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).

Next: , Previous: RSyntax, Up: Ratfor   [Contents][Index]

9.2 RATFOR commands

9.2.1 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.

9.2.2 Additional RATFOR–90 commands

 interface name {...}
 interface operator(op) {...}
 interface assignment(assgnmnt) {...}
 module name {...}
 type name {...}
 where(expression) {...}

Previous: Commands, Up: Ratfor   [Contents][Index]

9.3 Caveats about RATFOR

RATFOR is no longer supported (not because it is not a good idea but rather because of lack of time).

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 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.

Next: , Previous: Ratfor, Up: Top   [Contents][Index]


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.

Next: , Previous: Documentation, Up: Documentation   [Contents][Index]

10.1 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’s 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 as a style-file option; see Numbering.

Next: , Previous: Typesetting, Up: Typesetting   [Contents][Index]


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 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 -w.

  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 S_limbo.
  4. Limbo text from ‘@l’ commands. See ATl.
  5. User’s limbo section.
  6. Limbo text from the style-file parameter limbo.end. See S_limbo.
  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).

Next: , Previous: Output, Up: Typesetting   [Contents][Index]

10.1.2 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. Note that this file is produced by tangling fwebmac.web; changes made to fwebmac.sty will be overwritten the next time fwebmac.web is tangled. If you absolutely must make a change, copy fwebmac.web to something like myfwebmac.web, make changes to that file, then tangle it with the command-line option ‘-=fwebmac.sty’.

Most of the commands in fwebmac.sty 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.

Next: , Previous: fwebmac.sty, Up: fwebmac.sty   [Contents][Index] 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:


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

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

Previous: User macros, Up: fwebmac.sty   [Contents][Index] 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 S_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’.

Previous: fwebmac.sty, Up: Typesetting   [Contents][Index]

10.1.3 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).

Next: , Previous: LaTeX, Up: LaTeX   [Contents][Index] 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 Fwebmac params. 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 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


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


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}\

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 S_limbo.

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}
Optional TeX commands copied from user's limbo section

The ‘\Wbegin’ command essentially does the following:


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 Support).

Next: , Previous: Document class, Up: LaTeX   [Contents][Index] 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 -w).

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.

Next: , Previous: REVTeX, Up: LaTeX   [Contents][Index] 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 S_LaTeX.

Next: , Previous: Packages, Up: LaTeX   [Contents][Index] 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 ‘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 Numbering.

Next: , Previous: Sections, Up: LaTeX   [Contents][Index] 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 S_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\

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.

Next: , Previous: LIndex, Up: LaTeX   [Contents][Index] LaTeX’s Table of Contents

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

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

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


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:

\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)


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 Numbering) is used.

Next: , Previous: Table of Contents, Up: LaTeX   [Contents][Index] 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


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 Numbering.

Next: , Previous: Customizing LaTeX, Up: Customizing LaTeX   [Contents][Index]

10.1.4 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.

Next: , Previous: Page references, Up: Customizing LaTeX   [Contents][Index]

10.1.5 Page headers

The very top (header) line on each page of FWEAVE’s output contains several pieces of information:

Previous: Headers, Up: Customizing LaTeX   [Contents][Index]

10.1.6 Section numbering schemes

The FWEB commands ‘@*’ and ‘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 through the style-file option ‘LaTeX.package’ (see S_LaTeX), 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.

Previous: Customizing LaTeX, Up: Packages   [Contents][Index] Package fwebinsert: Inserting FWEAVE’s output into a LaTeX document

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

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

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

  1. Use FWEAVE to create test.tex. [You may wish to use the ‘-x’ flag (see -x) 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:




The body of the 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:




The body of the document.



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

Here are some caveats about fwebinsert:

Previous: Typesetting, Up: Documentation   [Contents][Index]

10.2 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 it 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.

Next: , Previous: Alternatives, Up: Pretty-printing   [Contents][Index]

10.2.1 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 ATe.
@; — pseudo-semicolon.  See AT;.
@: — pseudo-colon.  See ATcolon.

Next: , Previous: Pretty-printing, Up: Pretty-printing   [Contents][Index]

10.2.2 Alternatives for various input tokens

FWEAVE translates various input constructions into allegedly more readable symbols—for example, in FORTRAN it translates ‘.LT.’ into ‘<’. The printed documentation contains a table of what one can type on input, and what FWEAVE will output.

Previous: Pseudo-operators, Up: Pretty-printing   [Contents][Index]

10.2.3 The appearance of identifiers

When FWEB is parsing source, it uses the syntax rules for the current language (such as FORTRAN-90) to recognize an identifier. Identifiers come in several flavors, and in FWEAVE’s output they are highlighted by surrounding the identifier with a particular macro according to the following table (printed documentation only). For example, an intrinsic function name such as cos will be written into the .tex output file as ‘\\@{cos}’.

If one desires, one can change the appearance of the various identifiers by changing the appropriate macro definitions. However, there is a subtlety: Macros such as ‘\@’ are not directly defined in fwebmac.sty. Rather, they are \let equal to other internal macros that are defined in that file. For a complete discussion, see Style.

10.2.4 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.

Next: , Previous: Documentation, Up: Top   [Contents][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.

Next: , Previous: Index, Up: Index   [Contents][Index]

11.1 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.)

Next: , Previous: Internal index, Up: Index   [Contents][Index]

11.2 Creating a stand-alone index with makeindex

In addition to the internal index described in the previous section (see Internal 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 Merging indexes.) The procedure is simple, although the following discussion goes into some rather arcane details.

11.2.1 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.

11.2.2 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.




(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 Style) was motivated by that of makeindex.] When the ‘-XI’ option (see -X_) 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 -Z_). 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


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 Merging 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.

Previous: Using makeindex, Up: Index   [Contents][Index]

11.3 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.

11.3.1 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, Using makeindex.

11.3.2 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


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 Using 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 numeric 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.




Next: , Previous: Index, Up: Top   [Contents][Index]


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 Initialization.

The style file (called fweb.sty by default; see -z) 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 -p) 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 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 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 Options.
  5. Process remaining .fweb options (either file names, or options beginning with ‘&’).
  6. Process any ‘-p’ options from .fweb. See -p.
  7. Process the style file. See Style.
  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.

Next: , Previous: Customization, Up: Customization   [Contents][Index]

12.1 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 -H_. (One can append to this list by means of the ‘-I’ option, provided that option comes after the ‘-H’; see -I_.)

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 -I_.)

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.

Next: , Previous: Environment variables, Up: Customization   [Contents][Index]

12.2 Initialization

Although some aspects of FWEB’s behavior are hard-coded, many can be changed and/or initialized by the user.

12.2.1 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.

Next: , Previous: Initialization, Up: Customization   [Contents][Index]

12.2.2 Memory allocation

The command-line option ‘-y’ (see -y) 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.61 in fear of breaking something. Please wait for the year 3000.

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.

Next: , Previous: Memory allocation, Up: Memory allocation   [Contents][Index] ‘-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 -yn.

Next: , Previous: -yb, Up: Memory allocation   [Contents][Index] ‘-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.

Next: , Previous: -ybs, Up: Memory allocation   [Contents][Index] ‘-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 -yxb.

Next: , Previous: -ycb, Up: Memory allocation   [Contents][Index] ‘-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’.

Next: , Previous: -ycf, Up: Memory allocation   [Contents][Index] ‘-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’.

Next: , Previous: -ycg, Up: Memory allocation   [Contents][Index] ‘-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.

Next: , Previous: -yd, Up: Memory allocation   [Contents][Index] ‘-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 -TD.) ‘-ydt’ controls how many bytes are set aside for the storage of these replacement text of those macros. See also -ydx.

Next: , Previous: -ydt, Up: Memory allocation   [Contents][Index] ‘-ydx’: Maximum number of deferred macro texts

-ydx’ controls how many deferred macros are permitted. See also -ydt.

Next: , Previous: -ydx, Up: Memory allocation   [Contents][Index] ‘-yid’: Maximum depth of file inclusion

Files included by ‘@i’ can themselves contain ‘@i’ commands, to a nesting level controlled by ‘-yid’.

Next: , Previous: -yid, Up: Memory allocation   [Contents][Index] ‘-yif’: Maximum number of unique include-file names

The number of unique file names appearing in ‘@i’ commands is controlled by ‘-yif’.

Next: , Previous: -yif, Up: Memory allocation   [Contents][Index] ‘-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’.

Next: , Previous: -ykt, Up: Memory allocation   [Contents][Index] ‘-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’.

Next: , Previous: -ykw, Up: Memory allocation   [Contents][Index] ‘-yll’: Line length for FWEAVE’s output, in bytes

-yll’ controls the length of each line in the .tex file output by FWEAVE.

Next: , Previous: -yll, Up: Memory allocation   [Contents][Index] ‘-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’.

Next: , Previous: -yln, Up: Memory allocation   [Contents][Index] ‘-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.

Next: , Previous: -ylb, Up: Memory allocation   [Contents][Index] ‘-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.

Next: , Previous: -ylx, Up: Memory allocation   [Contents][Index] ‘-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.)

Next: , Previous: -ym, Up: Memory allocation   [Contents][Index] ‘-yma’: Maximum number of arguments to FWEB macros

The maximum number of arguments to FWEB macros (defined by ‘@m’) is limited by ‘-yma’.

Next: , Previous: -yma, Up: Memory allocation   [Contents][Index] ‘-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.)

Next: , Previous: -ymb, Up: Memory allocation   [Contents][Index] ‘-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 -yb.

Next: , Previous: -yn, Up: Memory allocation   [Contents][Index] ‘-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 ATO_) or ‘@o’ (see ATo) commands. Depending on the situation, some of these files may remain open simultaneously. The maximum number of such files is controlled by ‘-ynf’.

Next: , Previous: -ynf, Up: Memory allocation   [Contents][Index] ‘-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 ATv). Each such operator is entered into a table, the maximum size of which is controlled by ‘-yop’.

Next: , Previous: -yop, Up: Memory allocation   [Contents][Index] ‘-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’.

Next: , Previous: -yr, Up: Memory allocation   [Contents][Index] ‘-ys’: Maximum number of scraps

The maximum number of scraps is controlled by ‘-ys’. For a discussion of scraps, see -1.

Next: , Previous: -ys, Up: Memory allocation   [Contents][Index] ‘-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’.

Next: , Previous: -ysb, Up: Memory allocation   [Contents][Index] ‘-ytt’: Maximum number of tokens that FTANGLE can process

A token is an identifier, numeric 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’.

Next: , Previous: -ytt, Up: Memory allocation   [Contents][Index] ‘-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’.

Next: , Previous: -ytw, Up: Memory allocation   [Contents][Index] ‘-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.

Previous: -yx, Up: Memory allocation   [Contents][Index] ‘-yxb’: Size of line buffer for TeX and verbatim output

This option is like ‘-ycb’ (see -ycb), but controls the size of the output line for the TeX (‘@Lx’) and verbatim (‘@Lv’) languages.

Previous: Memory allocation, Up: Customization   [Contents][Index]

12.3 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 -z).

The style file is processed after all command-line options have been processed, except that the command-line option ‘-p’ (see -p) 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 Color).

Various of the style-file parameters take a language subscript. Those are

















Thus, line_char.N is the comment character for FTANGLE’s line commands (see line_char), for FORTRAN-77 code.

Unfortunately, the descriptions of the parameters aren’t all completed yet. To query the default values, say ‘ftangle -Z’ (see -Z_).

Next: , Previous: Style, Up: Style   [Contents][Index]

12.3.1 Customizing FWEAVE’s index

In the following, ‘???’ denotes the name of various subparameters.

Next: , Previous: Index params, Up: Index params   [Contents][Index] 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.

Next: , Previous: S_index, Up: Index params   [Contents][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.

Next: , Previous: S_delim, Up: Index params   [Contents][Index]


Next: , Previous: S_encap, Up: Index params   [Contents][Index] group_skip

group_skip is a string of TeX commands to insert between letter groups.

Next: , Previous: group_skip, Up: Index params   [Contents][Index] item_0

item_0 is the TeX command to begin an index entry.

Next: , Previous: item_0, Up: Index params   [Contents][Index] language.???

language.prefix begins a language entry.; language.suffix ends one.

Next: , Previous: S_language, Up: Index params   [Contents][Index] 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.

Previous: S_lethead, Up: Index params   [Contents][Index] 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.

Next: , Previous: Index params, Up: Style   [Contents][Index]

12.3.2 Customizing the module list

Previous: Module params, Up: Module params   [Contents][Index]


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.

Next: , Previous: Module params, Up: Style   [Contents][Index]

12.3.3 Customizing the Table of Contents

Previous: Contents params, Up: Contents params   [Contents][Index]


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.

Next: , Previous: Contents params, Up: Style   [Contents][Index]

12.3.4 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 AT[). This is usually done implicitly; for example, the commands ‘@a’, ‘@d’, and ‘@m’ issue an implicit ‘@[’. (See the discussion of ‘@a’ in ATa.) 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 -f).

Previous: Subscript params, Up: Subscript params   [Contents][Index]


(Discussion to be completed.)

Next: , Previous: Subscript params, Up: Style   [Contents][Index]

12.3.5 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!)

Next: , Previous: Fwebmac params, Up: Fwebmac params   [Contents][Index] 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’. Part of that output looks like the following:

  format_ID = "\\WUC"
  format_IDENTIFIER = "\\WUC"
  format_KEYWORD = "\\."
  format_MACRO = "\\<"
  format_OUTER_MACRO = "\\WUC"
  format_RESERVED = "\\WRS"
  format_WEB_MACRO = "\\WUC"
  format_WEB_macro = "\\>"
  format_id = "\\>"
  format_identifier = "\\>"
  format_intrinsic = "\\@"
  format_keyword = "\\."
  format_macro = "\\<"
  format_outer_macro = "\\>"
  format_reserved = "\\&"
  format_short_id = "\\|"
  format_short_identifier = "\\|"
  format_typewriter = "\\."

For example, the default value for format.intrinsic 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 \gdef\.{\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 square brackets.


ordinary identifiers [format.id]


completely upper-case ordinary identifiers [format.ID]


single-character ordinary identifiers [format.short_id]


outer macros (‘@d’) [format.outer_macro]


outer macros (‘@d’) that are completely upper-case [format.outer_macro]


FWEB macros (‘@m’) [format.WEB_macro]


FWEB macros (‘@m’) that are completely upper-case [format.WEB_macro]


reserved words [format.reserved]


reserved words that are completely upper-case [format.RESERVED]


language macros [format.macro]


language macros that are completely upper-case [format.MACRO]


library/intrinsic function names [format.intrinsic]


certain Fortran keywords [format.keyword]


keywords that are completely upper-case [format.KEYWORD]


character strings [format.typewriter]

Next: , Previous: S_format, Up: Fwebmac params   [Contents][Index] indent.???

indent.TeX specifies paragraph indentation for the TeX part.

indent.code specifies similar indentation for the code part.

Previous: S_indent, Up: Fwebmac params   [Contents][Index] 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 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 Document class.

When running under LaTeX prior to LaTeX2e (or with REVTeX; see 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.

Next: , Previous: Completion params, Up: Style   [Contents][Index]

12.3.6 Remapping control codes

Control-code remappings are sophisticated and unwise. They are mostly intended for the developer, so are not explained here.

Next: , Previous: Control-code mappings, Up: Style   [Contents][Index]

12.3.7 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


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 -C_). That selects one of several primitive palettes, as follows:


No color; ordinary black-and-white output. This is the default (and the mode used when the termcap library is not present).


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.


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).


Trilevel. As above, but adds underlining capability.


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.

Previous: Color, Up: Style   [Contents][Index]

12.3.8 Miscellaneous style-file parameters

There are a variety of miscellaneous parameters.

Next: , Previous: Miscellaneous params, Up: Miscellaneous params   [Contents][Index] ASCII_Fcn

See ATdquote.

Next: , Previous: ASCII_fcn, Up: Miscellaneous params   [Contents][Index] cchar

Continuation character for FORTRAN code output.

Next: , Previous: cchar, Up: Miscellaneous params   [Contents][Index] 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.

Next: , Previous: cdir_start, Up: Miscellaneous params   [Contents][Index] 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.

Next: , Previous: line_char, Up: Miscellaneous params   [Contents][Index] 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).

Next: , Previous: S_line_length, Up: Miscellaneous params   [Contents][Index] 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 -Tv) 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 Style) such as N90.

meta.prefix.l begins each line of the meta-comment.

meta.bottom.l specifies text that follows the meta-comment.

Next: , Previous: S_meta_t, Up: Miscellaneous params   [Contents][Index] outer.???

FTANGLE converts ‘@d’ (see ATd) to outer.def, and ‘@u’ (see ATu) to outer.undef.

Next: , Previous: S_outer, Up: Miscellaneous params   [Contents][Index] protect.?

The strings protect.l specify the protection character(s) to end a continued line.

Next: , Previous: protect, Up: Miscellaneous params   [Contents][Index] suffix.?

The extension for the files output by FTANGLE is specified by suffix.l.

Next: , Previous: suffix, Up: Miscellaneous params   [Contents][Index] macros

The default name of the macro package to be read in. [This is usually fwebmac.sty (see fwebmac.sty), but can be overridden by the command-line option ‘-w’; see -w.]

Next: , Previous: macros, Up: Miscellaneous params   [Contents][Index] 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 ATl. (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

   [contains \documentclass, \usepackage, <doc.preamble>, \begin{document}]

[contents of any @l commands]
[user's TeX commands from the limbo section]

The ‘limbo.end’ command is useful for printing the entire document in two-column format. For more discussion, see LIndex.

Next: , Previous: S_limbo, Up: Miscellaneous params   [Contents][Index] meta.??? (FWEAVE)

(To be finished.)

Next: , Previous: S_meta_w, Up: Miscellaneous params   [Contents][Index] 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.

Next: , Previous: S_preamble, Up: Miscellaneous params   [Contents][Index] 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.

Previous: S_dot_constant, Up: Miscellaneous params   [Contents][Index] null_file

The name of the null file or device. For more discussion, see Change files.

Next: , Previous: Fwebmac params, Up: Style   [Contents][Index]

12.3.9 Automatic file name completion

Previous: Completion params, Up: Completion params   [Contents][Index]


For more information, see -e.

Next: , Previous: Customization, Up: Top   [Contents][Index]


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 Languages.

Next: , Previous: Hints, Up: Hints   [Contents][Index]

13.1 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, and the ‘@x’ must be in the first two characters of a line.
  2. Next, set the language in limbo (before the first ‘@*’ or ‘) by including a command such as ‘@n90’ or ‘@c++’.
  3. Divide the code into short sections, each of which will contain TeX documentation and (usually) source code. To begin each section, place an ‘@*’ or ‘command, followed by TeX documentation about that particular section of code.
  4. After the documentation, place an ‘@a’ command (switch into unnamed code). Follow that by a program unit of code (e.g., main program, subroutine, or function).
  5. If you have program units longer than about twelve lines (some people say 25, but you get the idea), 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 ‘, documentation, and ‘@<Name of module@>=’.
  6. Beautify and clarify your documentation (both at the beginning of each section and in comments) by using code mode (enclosing stuff between vertical bars) liberally within your TeX. Code mode is your friend. If you are explaining or referring to a particular code construction, don’t try to tediously format that by hand by going into TeX’s math mode; just enclose it with the vertical bars. For example, write
    // The assignment |a_tot = 100| ...


    // The assignment $a\_tot = 100$ ...

    and certainly not

    // The assignment a_tot = 100

    for which TeX will complain because the underscore is not in math mode.

  7. The following repeats the discussion of Temporary comments. Do not comment out code by using either ‘/* ... */’ or ‘//’. (Although that would work for FTANGLE, FWEAVE will not format such comments correctly and may get confused.) Instead, use the preprocessor construction ‘#if 0 ... #endif’ (if in C) or the FWEB version ‘@#if 0 ... @#endif’. Thus, in FORTRAN,
    @#if 0
           write(*, *) a_min, a_max

    A side benefit of this approach is that it is easily extended to conditional inclusion; for example, replace the ‘@#if 0’ by ‘@ifdef DEBUG’, then use the command-line option ‘-mDEBUG’ (see -m) to include the relevant sections of code.

  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 Pseudo-operators).
  9. Consider using FWEB’s built-in macro preprocessor (see Macros) to make your code more readable—for example, replace raw numeric constants by symbolic names.
  10. Scientific programmers may benefit from built-in macro-like functions like $PI; see Built-in functions.
  11. If you are a FORTRAN-77 user, strongly consider switching to FORTRAN-90 with free format. Some FORTRAN-77 constructions are no longer supported by the formal language specifications, and the meanings of some keywords have changed. For example, the ‘type’ statement in FORTRAN-77 (write out a message) conflicts with the keyword for FORTRAN-90’s derived data type.
  12. For C and FORTRAN, use the highest language version with which you are comfortable, e.g., FORTRAN-23 (‘@n23’). The point is to avoid using identifiers for your own purposes that might not be special in an older language version but have specific meanings in a newer one.
  13. If after reading the last two items you are still a FORTRAN-77 user, for ultimate readability consider converting to RATFOR. (However, RATFOR is no longer supported!) 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 -nC) may be helpful.

Next: , Previous: Converting, Up: Hints   [Contents][Index]

13.2 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 New features.
  3. If you have a color terminal, try the option ‘-C1’ (see -C_, see Color).
  4. Any option in the initialization file .fweb (see ini-file and Options) that is intended to be processed after the command-line options should begin with ‘&’ rather than ‘-’. (This is rarely necessary.) See Initialization.
  5. Put standard command-line options into .fweb (see ini-file). Also put there standard style parameters—e.g.,
    -pindex.tex "#.ndx"
    -pmodules.tex "#.mds"
    -pcontents.tex "#.cts"
  6. Learn how to use the style file. See Style.
  7. 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 Info options.
  8. Begin all FWEB sources with invisible commentary bracketed by ‘@z...@x’. See ATz.
  9. Always include an explicit language-setting command in the limbo section. Under normal circumstances, do not set the language from the command line. See Languages.
  10. 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 by using named modules.
  11. It’s easy to define macros from the command line to expedite conditional preprocessing. See -m.
  12. Use the preprocessor construction ‘@#if 0...@#endif’ to comment out unwanted code. See Preprocessing.
  13. For logical operations with the preprocessor, use ‘||’, not ‘|’.
  14. It’s conventional to identify the ends of long preprocessor constructions as follows:
    @#if A
    @#endif // |A|
  15. To debug an errant FWEB macro, use the built-in function ‘$DUMPDEF’. See $DUMPDEF.
  16. Use ‘@?’ for compiler directives. See AT?. Use the style-file parameters ‘cdir_start’ to specify information that will be written out at the beginning of the line. See cdir_start.
  17. 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 Comments.
  18. 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.
  19. In FORTRAN, use ‘#:0’ to declare readable alphabetic statement labels. See Tokens and -colon.
  20. When mixing languages, define the language of a module at the highest possible level—e.g., in the unamed module, not after ‘@<...@>=’.
  21. Use LaTeX. Plain TeX is no longer supported. Upgrade to LaTeX2e. See LaTeX.
  22. 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 web browser. For the address, see Support.

Previous: Tips, Up: Hints   [Contents][Index]

13.3 Features for scientific programming

FWEB contains a few features particularly intended for scientific programming.

  1. Several built-in functions generate numeric constants. See

    $PI’ ($PI)

    $E’ ($E).

  2. Several built-in functions perform mathematical manipulations. See

    $EXP’ ($EXP),

    $POW’ ($POW),

    $SQRT’ ($SQRT),

    $LOG’ ($LOG),

    $LOG10’ ($LOG10),

    $MAX’ ($MAX),

    $MIN’ ($MIN).

  3. The do-loop macro ‘$DO’ may be useful. See $DO.
  4. C-style array indices can be used by means of the ‘-n)’ option. See -n).
  5. An active bracket feature helps improve the appearance of woven code that uses subscripts and/or superscripts heavily. See -W[.

Next: , Previous: Hints, Up: Top   [Contents][Index]


This info documentation is accessible on the internet; see Support.

Some things that have been added or changed in recent releases are described in the following.

Next: , Previous: New features, Up: New features   [Contents][Index]

14.1 Version 1.70

14.1.1 Bux fixes (v1.70)

  1. Several incorrect uses of the C-language strncpy function were identified. The behavior of that function is undefined when the memory buffers overlap; it should not have been used in that situation. In those situations, the code now uses memmove. This cures certain memory-overwrite conditions that led to incorrect tangled code on some machines (but not others!).
  2. The TeX macros in fwebmac.sty that handle the beginning of a named section were improved so that square brackets within a section name are handled correctly.
  3. Mishandling of short verbatim comments (‘@//’) by FWEAVE in FORTRAN was fixed.
  4. Code relating to the VERBATIM language has been improved (although it is possibly still not totally debugged). A consequence is that FWEAVE can now weave the important file typedefs.web, which was not the case for earlier versions.

14.1.2 Known issues (v1.70)

  1. The change-file mechanism does not work for fixed-column FORTRAN-77. It is unlikely that this will be fixed. Please do not use FORTRAN-77; upgrade to free-format FORTRAN-90.
  2. If the global language is set to VERBATIM (‘@Lv’), built-in FWEB macros such as $PI may not expand correctly and FWEB may crash. As a temporary work-around, If you need to expand such a macro in VERBATIM mode and you have issues, try using the ‘@Lv’ command within the code section.

14.1.3 New features (v1.70)

  1. The installation procedure has changed; it now uses cmake. See Installing.
  2. A language change within the unnamed module is no longer local to the section in which the language command was issued; it remains in effect globally uless possiblly another language command is issued within a subsequent unnamed part.
  3. The special language command ‘@LW’, used by FWEAVE only, has been introduced. See @LW.
  4. The C and FORTRAN language commands have been updated to accept a numeric argument that sets the language version, such as ‘-c99’. See C-numeric and F-numeric.
  5. For C and FORTRAN, special identifiers, intrinsic function names, etc. are loaded hierarchically, based on the language version. For example, ‘@n77’ loads only the names for FORTRAN-77, whereas ‘@n95’ loads names for FORTRAN-95, FORTRAN-90, and FORTRAN-77.
  6. The production rules were updated, especially for FORTRAN, to deal with the new language features beyond FORTRAN-90 and C-89. These still need some work. C++ has not yet been updated.
  7. The new identifier class macros was added. This class includes such language macros as ‘complex’ in C. It also includes named constants such as ‘INT32’in FORTRAN.

14.1.4 Updates to documentation (v1.70)

  1. The discussion of the use of multiple languages within a single web file was improved; see Setting the language.
  2. Miscellaneous changes and amplications were made throughout the manual.

Next: , Previous: New features, Up: New features   [Contents][Index]

14.2 Version 1.61

14.2.1 Updates to documentation (v1.61)

  1. FWEB supports color modes in which messages to the terminal can appear in colors chosen by the user; see Color. The color mode is set by the new command-line option ‘-C’ (see -C_).
  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 Phases.

14.2.2 Redefined commands (v1.61)

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 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 AT/. ‘@\’ backspaces one unit of indentation after breaking the line. See ATbs. Usually, one should use ‘@/’ (sorry; I was previously recommending ‘@\’. For an example in which it is natural to use ‘@\’, see ATbs.
  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.

14.2.3 New features (v1.61)

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 Using makeindex.
  2. Stand-alone indexes produced by ‘-XI’ can be merged with the idxmerge utility. See Merging indexes.
  3. FWEAVE-formatted code can be included in a standard LaTeX2e document by means of the fwebinsert package. See Inserting woven code.
  4. Revision-control-system (RCS) information that appears in the ignorable commentary between the optional ‘@z’ and ‘@x’ that begin an FWEB file (see ATz) is accessible in the body of the file through the built-in function $KEYWORD (see $KEYWORD) and the new commands ‘@K’ (see ATK_) and ‘@k’ (see ATk). These features can access RCS-like keywords that are not known to RCS itself, as long as they fit the proper syntax (see ATz).
  5. The ‘-h’ option now permits easy access to the GNU info browser if it is installed. See -h.
  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 -W1.
  8. Some module warning messages can be eliminated with the ‘-W@’ option. See -WAT.
  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 ATq.
  10. The level of verbosity of FWEB’s informational messages can be controlled with the ‘-M’ option. See -M_.
  11. C/C++ programmers may find the command ‘@{’ useful. See ATlb.
  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 -nC.
  13. FORTRAN-90 (see -n9) now defaults to free-form syntax.
  14. As of the non-beta Version 1.61, 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 -n;.
  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 -k.
  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 REVTeX.

14.2.4 Significant bugs (v1.61)

  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.

Next: , Previous: V1.61, Up: New features   [Contents][Index]

14.3 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 Sections.

  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 -H_.
  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 -k.
  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 -ncolon.
  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 Debugging with macros.

    An implicit ‘@#line’ command is added after each ‘@%’ (see AT%) that begins a line (this keeps line numbering correct). To override this, use the option ‘-T#’. See -T#.

  6. -p’ (style-file) options (see -p) on the command line are now processed after the local style file. See Style.
  7. The functionality of the ‘-D’ command was enhanced to include optional arguments that limit the information that will be listed. See -D_.

Next: , Previous: V1.53, Up: New features   [Contents][Index]

14.4 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|...
    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 LIndex 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.

Next: , Previous: V1.52, Up: New features   [Contents][Index]

14.5 Version 1.50

  1. The syntax for entries in the initialization file .fweb (see 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 LaTeX.
  5. The style-file parameter index.name was added. This is the section name to be given to the Index (see 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 $IF) 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 -j.
  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.

Previous: V1.50, Up: New features   [Contents][Index]

14.6 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 Verbatim.
  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 ATN_.
  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 -F_.
  7. Converting output tokens to lower case. See -U_.
  8. The built-in functions ‘$E’ and ‘$PI’. See $E, $PI.
  9. The built-in functions ‘$EXP’, ‘$LOG’, and ‘$LOG10’. See $EXP, $LOG, and $LOG10.
  10. $MAX’ and ‘$MIN’ generalized to take arbitrary list of arguments. See $MAX, $MIN.
  11. The marriage-saver option. In response to a serious user request, see -B_.

Next: , Previous: New features, Up: Top   [Contents][Index]


FWEB has been supported by John Krommes, krommes@princeton.edu. Now that he has retired, that support is coming to an end, However, significant bugs that turn up may still be fixed; please report them.

Next: , Previous: Support, Up: Top   [Contents][Index]

Appendix A Installing FWEB

Here are the bare-bones installation procedures for Unix and Windows users. For further information about this process, see fweb-1.70/READ_ME.FWEB.

A.1 Creating the build (all systems)

  1. Download the zgip-compressed tar file from Google Drive using the link https://drive.google.com/open?id=1-0tXujRtBw8biePfqW0TLkJ36tCdbgzu&authuser=krommes%40pppl.gov&usp=drive_fs. The name of the file contains the version number—e.g., fweb-1.70.tar.gz. Place this file into a directory one level higher than the fweb-1.70 directory you want to create. Change (‘cd’) to that directory.
  2. Uncompress and unpack the tar file:
    gunzip fweb-1.70.tar.gz
    tar -xf fweb-1.70.tar

    If the GNU tar is installed, those two steps can be combined into

    gtar -xzf fweb-1.70.tar.gz

    Unpacking creates the top-level FWEB directory fweb-1.70 and the subdirectories Web, Manual, and Demos.

  3. You must have cmake (version 1.22 or greater), installed on your system. If necessary, you can download it from https://cmake.org/download/. Then, in the top-level FWEB directory, issue one of the commands
    cmake . # Unix


    cmake -A Win32 . # Windows

    This attempts to figure out various local system features automatically, then generates the files Bin/config.h and Bin/custom.h; those are used when the processors are compiled.

A.2 Building the processors (Unix)

  1. To build the processors, ‘cd’ to the top-level FWEB directory, then just say

    This builds the ftangle and fweave processors into the Bin subdirectory.

    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 linux system with just one warning using the command ‘gcc -ansi -pedantic. That warning relates to the use of the tempnam function; see tempnam. Please report any other compiler warnings from an allegedly ANSI-C environment.

  2. To install the processors and associated files onto your system, say (while still in the top-level directory)
    <Log on as root>
    make install

A.3 Building the processors (Windows)

For a Windows build, the ‘cmake’ command does not produce a Makefile; rather, it generates the Visual Studio solution file ./Fweb.sln.

  1. Open ./Fweb/sln with Windows Visual Studio 2022 Community.
  2. In the Solution Explorer on the right, verify that the project list includes ftangle and fweave.
  3. From the Toolbar at the top, select ‘Build’, then click on ‘Build Solution’. The processors will be built into ./Bin/Debug/{ftangle,fweave}. Test those by using PowerShell.
  4. The Debug versions of the processors are more demanding than the corresponding Unix builds, and they may not have been fully tested on a PC. Please report any compile messages or run-time crashes that you encounter while running FWEB on a Windows machine.

Next: , Previous: Installing, Up: Top   [Contents][Index]

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  
Index Entry  Section

.false.: Fortran
.true.: Fortran

@, literal: Structure

Absolute value: $ABS
Allocation, memory: -y
Allocation, memory: Memory allocation
ASCII, converting to: ATquote
ASCII, converting to: $A
Asserting a condition: $ASSERT
Assignment operators, compound: -plus
Assignment operators, compound: Fortran
Author: $AUTHOR
Automatic pseudo-semicolons: -nAT;
Automatic pseudo-semicolons: AT;
Automatic pseudo-semicolons: Fortran
Automatic semicolons: -n;
Automatic semicolons: Fortran

Bar, vertical: AT|
Bar, vertical: AT|_
Binary notation: C
Binary notation: Fortran
Blocks, numbering: -b
Blocks, numbering: -nb
Blocks, numbering: -rb
Brackets, active: -W[
Breakpoints, inserting: ATb
Breakpoints, suppressing: ATB_
Bugs: Support
Bugs, version 1.61: V1.61
built-in functions, redefining: -Tb
Bullet: Subscript params
Bullet subscript: Subscript params

C hints: C
C++ hints: Cpp
Case, changing: $L
Case, changing: $U
Class options: Document class
Code mode: Structure
Code part, beginning unnamed: ATA_
Code part, beginning unnamed: ATa
Code, converting to FWEB: Converting
Code, temporarily commenting out: Temporary comments
Code, temporarily commenting out: Fortran
Code, typesetting: Structure
Colon, pseudo: ATcolon
Color: Color
Color mode, ANSI: Color
Color mode, bilevel: Color
Color mode, trilevel: Color
Color mode, user-defined: Color
Color, and message types: Color
Color, ANSI: Color
Color, setting: -C_
Columns, multiple: LIndex
Commands, redefined: V1.61
Commentary, optional: Structure
Commenting styles: Comments
Comments: AT/*
Comments: Comments
Comments, FORTRAN: -n!
Comments, generating: $COMMENT
Comments, ignorable: AT%
Comments, ignore single-line Fortran: -nC
Comments, invisible: Invisible comments
Comments, short: -/
Comments, short: -!
Comments, short: Fortran
Comments, temporary: Temporary comments
Comments, TeX: -T%
Comments, verbatim: -v
Comments, visible: Visible comments
Compiler directives: AT?
Completion, automatic file-name: Completion
Concatenation: -n/
Condition, asserting: $ASSERT
Conditional, n-way: $IFCASE
Conditional, two-way: $IF
Conditional, two-way: $IFDEF
Conditional, two-way: $IFNDEF
Conditional, two-way: $IFELSE
Contents, table of: Table of Contents
Control text: ATt
Converting an existing code to FWEB: Converting
Cross-references, eliminating: -x
Cross-references, suppressing: -Wnoprint
Customization: Customization
Customizing FWEB: Customization

Date, generating the: $DATE
Day, generating the: $DAY
Debugging: -1
Debugging: -2
Debugging: AT0
Debugging: AT1
Debugging: AT2
Debugging macros: $DUMPDEF
Documentation format: Documentation
Dot constants, recognizing: -.

Environment variables: $GETENV
Environment variables: Environment variables
Environment, obtaining the: $GETENV
Error messages, printing: $ERROR
Escape sequences, ANSI: Color
Example, of FWEB file: Structure
Exponentiation: $EXP
Exponentiation: $POW
Exponentiation: Fortran
Expression evaluation: Preprocessing
Expression, pseudo: ATe
Expressions, evaluating: $EVAL

Features, new: New features
Features, version 1.40: V1.40
Features, version 1.50: V1.50
Features, version 1.52: V1.52
Features, version 1.53: V1.53
Features, version 1.61: V1.61
File, including web: ATi
File, including web: ATI_
File, initialization: Initialization
File, opening output: ATO_
File, opening output: ATo
File, style: Style
File-name completion: Completion
Files: Files
Files, change: Change files
Files, input: Input files
Files, output: Output files
Fonts: Fonts
Formatting: Documentation
FORTRAN hints: Fortran
FORTRAN, Rational: Ratfor
Functions, built-in: Built-in functions
Functions, intrinsic: -D_
FWEB output, inserting into LaTeX document: Inserting woven code
FWEB, customizing: Customization
FWEB, initializing: Initialization

Header: $HEADER
Header comments, printing: -Tv
Headers: Headers
Hexadecimal notation: Fortran
Hints, C: C
Hints, C++: Cpp
Hints, FORTRAN: Fortran
Hints, TeX: TeX

I/O keywords: -D_
Identification: $ID
Identifier, formatting: ATf
Identifiers, overloading: ATW_
Identifiers, overloading: Overloading
Identifiers, single-character: -W1
Identifiers, truncating: -t
Include file, formatting name of: ATi
Include file, printing name of: ATi
Include files, finding: -I_
Include files, indexing: -i
Include files, inhibiting: -j
Include files, scanning: -H_
Include files, skipping: -i
Index: Structure
Index: LIndex
Index entries, deleting: AT-
Index entries, forcing: ATplus
Index entries, Roman type: AT^
Index entries, typewriter type: ATdot
Index entries, underlining: AT_
Index entries, user format: AT9
Index, name of: S_index
Index, stand-alone: Using makeindex
Indexes, merging: Merging indexes
Indexing commands: AT_
Information options: Info options
Initialization file: Initialization
Input line, number of: $INPUT_LINE
Installing FWEB: Installing
Intrinsic functions: -D_
Items, joining: AT&

Joining items: AT&

Keyword, RCS: $KEYWORD
Keyword, RCS: $L_KEYWORD
Keyword, RCS-like: ATz
Keywords, I/O: -D_
Keywords, I/O: Fortran

Language number: $LANGUAGE_NUM
Language, determining: $LANGUAGE_NUM
Language, determining the: $LANGUAGE
Language, global: Languages
Language, setting: -c
Language, setting: ATL_
Language, setting: Setting the language
Languages: Languages
LaTeX: LaTeX
LaTeX section: Sections
LaTeX2e: LaTeX
Left brace, inserting: ATB_
Length of string: $LEN
Level, message: -M_
Limbo section: Structure
Limbo section: Structure
Limbo text: ATl
Line break, canceling: AT~
Line break, forcing: AT/
Line break, forcing with indent: ATbs
Line break, optional: AT|
Line break, optional: AT|_
Line number: $OUTPUT_LINE
Line numbering, turning off: ATq
Literate programming: Intro
Logarithms, base 10: $LOG10
Logarithms, natural: $E
Logarithms, natural: $LOG
Lower case: $L

Macros: Macros
Macros, absolute value of: $ABS
Macros, debugging: $DUMPDEF
Macros, debugging with: Debugging with macros
Macros, decrementing: $DECR
Macros, deferred: -TD
Macros, defining: $DEFINE
Macros, defining: $M
Macros, evaluating: $EVAL
Macros, formatting: Macros and formatting
Macros, FWEB: FWEB macros
Macros, incrementing: $INCR
Macros, inhibiting expansion of: AT!
Macros, outer: Outer macros
Macros, preprocessing: Preprocessing
macros, redefining: -Tm
Macros, redefinition of: Macro protection
Macros, repetitively defining: $DO
Macros, special tokens for: Tokens
Macros, undefining: $UNDEF
Macros, with variable arguments: Variable arguments
Major section, beginning: AT*
Major section, optional argument for: AT*
Major subsection: AT*
Makefiles, using: Processors
Makeindex, using: Using makeindex
Marriage: -B_
Maximum: $MAX
Memory allocation: -y
Memory allocation: Memory allocation
Message level: -M_
Message types: Color
Message types: Color
Mininum: $MIN
Module name, beginning: AT<
Module name, ending: AT>
Module, name of: $MODULE_NAME
Module, named: Modules
Module, unnamed: Modules
Modules: Modules
Modules, missing: $STUB
Modules, number of: $MODULES
Modules, warning level for: -WAT
multicol, using: LIndex

Named module: Modules
Not equal: -plus
Not equal: Fortran
Notation, binary: C
Notation, binary: Fortran
Notation, hexadecimal: Fortran
Notation, octal: Fortran
Numbering blocks: -b
Numbering blocks: -nb
Numbering blocks: -rb

Octal notation: Fortran
Operators, overloading: -o
Operators, overloading: ATv
Operators, overloading: Overloading
Operators, pseudo-: ATe
Options, class: Document class
Options, information: -AT
Options, information: -D_
Options, information: -Z_
Options, information: Info options
Options, negating: Negating options
Ouput, redirecting: ->
Ouput, redirecting: -=
Outer macro, defining: ATD_
Outer macros, undefining: ATu
Output files, changing names of: Output files
Output line: $OUTPUT_LINE
Output, changing appearance of: -1
Overloading: Overloading
Overloading identifiers: Overloading
Overloading operators: Overloading

Package, fwebnum: Numbering
Package, multicol: LIndex
Packages, user: Document class
Page headers: Headers
Page numbers: Page references
Part, code: Structure
Part, code: Structure
Part, definition: Structure
Part, definition: Structure
Part, TeX: Structure
Part, TeX: Structure
Parts: Structure
Phases, of FTANGLE: Phases
Phases, of FWEAVE: Phases
Pi: $PI
Pound sign: $P
Pound sign: $PP
Preprocessing: Preprocessing
Preprocessor symbol: $P
Preprocessor symbol: $PP
Preprocessor, m4: -m4
Preprocessor, sending additional arguments to: -WH_
Pretty-printing: Pretty-printing
Printing, two-sided: Document class
Processor, LaTeX: -P_
Processor, TeX: -P_
Processors, FWEB: Processors
Program unit: $ROUTINE
Programming tips: Tips
Pseudo-colon: ATcolon
Pseudo-expression: ATe
Pseudo-operators: ATe
Pseudo-operators: Pseudo-operators
Pseudo-semicolon: AT;
Pseudo-semicolons, automatic: -nAT;
Pseudo-semicolons, automatic: AT;
Pseudo-semicolons, automatic: Fortran

RATFOR: Ratfor
RATFOR commands: Commands
RATFOR, caveats about: Caveats
Rational FORTRAN: Ratfor
RCS-like keyword: ATz
RCS-like keyword: $KEYWORD
RCS-like keyword: $L_KEYWORD
Recursion: Recursion
Redefined commands, version 1.61: V1.61
References, forward: AT[
Reserved words: -D_
Revision: $REVISION
Root, square: $SQRT

Scientific programming: Science
Scrap, irreducible: -1
Section names, long: AT*
Section names, short: AT*
Section number, current: $SECTION_NUM
Section number, maximum: $SECTIONS
Section, beginning major: AT*
Section, beginning minor: ATspace
Section, limbo: Structure
Sections: Structure
Sections, named: Structure
Sections, numbering: Page references
Sections, numbering: Numbering
Sections, unnamed: Structure
Semicolon, pseudo: AT;
Semicolons, automatic: -n;
Semicolons, automatic: Fortran
Semicolons, printing: -np
Sharp sign: $P
Sharp sign: $PP
Spacing commands: ATcomma
Spacing, thin space: ATcomma
Square root: $SQRT
State: $STATE
Statement numbers, automatic: -colon
Statistics, printing: -s
String length: $LEN
String, definition of: Strings and quotes
String, quoted: Strings and quotes
String, quoting a: $STRING
String, unquoted: Strings and quotes
Strings, continuing: -\
Strings, long: -\
Strings, parenthesized: -lp
Strings, unquoting: $UNQUOTE
Style file: Style
Style file, changing name of: -z
Style file, for makeindex: Using makeindex
Subscript, bullet: Subscript params
Subsection, beginning major: AT*
Suggestions: Tips
Support: Support
Syntax, command-line: Syntax
Syntax, free-form: -n\
Syntax, free-form: -n&
Syntax, free-form: Fortran

Table of Contents: Table of Contents
Table of contents, entries for: AT*
Tags, enum: C
Tags, structure: C
TeX hints: TeX
Text, control: ATt
Time: $TIME
Tokens, upper-case: -U_
Transliteration: $TRANSLIT
Typesetting: Typesetting

Unnamed module: Modules
Upper case: $U
User packages: Document class

Variable arguments: Variable arguments
Variables, environment: Environment variables
Version number: -V_
Version, of FWEB: $VERSION
Vertical bar: AT|
Vertical bar: AT|_
Vertical bars: Structure

Warning level for modules: -WAT
Web, structure: Structure
Words, reserved: -D_

Jump to:   .   @  
A   B   C   D   E   F   H   I   J   K   L   M   N   O   P   R   S   T   U   V   W  

Next: , Previous: Concept index, Up: Top   [Contents][Index]

Option and command index

Jump to:   #   $   -   .   @   \  
A   C   F   I   M   T  
Index Entry  Section

#line: Debugging with macros

$A: $A
$DO: $DO
$E: $E
$ID: $ID
$IF: $IF
$L: $L
$LOG10: $LOG10
$M: $M
$P: $P
$PI: $PI
$PP: $PP
$U: $U

-: Syntax
-!: -!
-#: -#
-#: Fortran
-(: -lp
-+: -plus
-+: Fortran
-.: -.
-/: -/
-1: -1
-2: -2
-:: -colon
-=: -=
->: ->
-@: -AT
-A: -A_
-B: -B_
-b: -b
-C: -C_
-c: -c
-C: Color
-c++: -cpp
-D: -D_
-d: -d
-E: -E_
-e: -e
-F: -F_
-f: -f
-H: -H_
-h: -h
-Hr: -H_
-Hx: -H_
-HX: -H_
-I: -I_
-i: -i
-ix: -i
-j: -j
-k: -k
-k: Fortran
-L: -L_
-l: -l
-M: -M_
-m: -m
-m4: -m4
-m;: -m;
-n: -n
-n!: -n!
-n!: Fortran
-n&: -n&
-n): -n)
-n/: -n/
-n9: -n9
-n:: -ncolon
-n;: -n;
-n;: AT;
-n@;: -nAT;
-n@;: AT;
-nb: -nb
-nC: -nC
-np: -np
-n\: -n\
-o: -o
-o: -q
-P: -P_
-p: -p
-r: -r
-r!: -r!
-r): -r)
-r/: -r/
-r9: -r9
-r;: -r;
-r@;: -rAT;
-rb: -rb
-rg: -rg
-rk: -rk
-rK: -rK_
-s: -s
-sm: -s
-t: -t
-T#: -T#
-T%: -T%
-Tb: -Tb
-TD: -TD
-Tm: -Tm
-Tv: -Tv
-U: -U_
-u: -u
-V: -V_
-v: -v
-W: -W_
-W: -Wnoprint
-w: -w
-W1: -W1
-W@: -WAT
-WH: -WH_
-W[: -W[
-x: -x
-X: -X_
-XI: Using makeindex
-y: -y
-yb: -yb
-ybs: -ybs
-ycb: -ycb
-ycf: -ycf
-ycg: -ycg
-yd: -yd
-ydt: -ydt
-ydx: -ydx
-yid: -yid
-yif: -yif
-ykt: -ykt
-ykw: -ykw
-ylb: -ylb
-yll: -yll
-yln: -yln
-ylx: -ylx
-ym: -ym
-yma: -yma
-ymb: -ymb
-yn: -yn
-ynf: -ynf
-yop: -yop
-yr: -yr
-ys: -ys
-ysb: -ysb
-ytt: -ytt
-ytw: -ytw
-yx: -yx
-yxb: -yxb
-Z: -Z_
-z: -z
-\: -\

.fweb: Input files
.fweb: Initialization

@: ATspace
@!: AT!
@": ATdquote
@#: AT#
@#define: Preprocessing
@#elif: Preprocessing
@#endif: Preprocessing
@#if: Preprocessing
@#ifdef: Preprocessing
@#ifndef: Preprocessing
@#line: Preprocessing
@#undef: Preprocessing
@%: AT%
@%%: AT%
@&: AT&
@': ATquote
@(: ATlp
@): AT)
@*: Structure
@*: AT*
@+: ATplus
@,: ATcomma
@-: AT-
@.: ATdot
@/: AT/
@/*: AT/*
@//: AT//
@0: AT0
@1: AT1
@2: AT2
@9: AT9
@:: ATcolon
@;: AT;
@<: AT<
@=: AT=
@>: AT>
@?: AT?
@@: ATAT
@A: ATA_
@a: ATa
@B: ATB_
@b: ATb
@c: ATc
@c++: ATcpp
@D: ATD_
@d: ATd
@E: ATE_
@e: ATe
@f: ATf
@i: ATi
@I: ATI_
@K: ATz
@k: ATz
@L: ATL_
@l: ATl
@M: ATM_
@m: ATm
@N: ATN_
@n: ATn
@n9: ATn9
@O: ATO_
@o: ATo
@q: ATq
@R: ATR_
@r: ATr
@r9: ATr9
@t: ATt
@u: ATu
@v: ATv
@W: ATW_
@x: ATx
@y: ATy
@z: ATz
@[: Change files
@[: AT[
@\: ATbs
@]: Change files
@^: AT^
@_: AT_
@|: AT|
@|: AT|_
@~: AT~

\/: -n/
\beforeindex: LIndex
\botofcontents: Table of Contents
\documentclass: Document class
\documentstyle: LaTeX
\FWEBtoc: Table of Contents
\idxname: Merging indexes
\INDEX: Structure
\INDEX: LIndex
\INDEX: S_index
\maketitle: Table of Contents
\numbercode: Customizing LaTeX
\numberdefs: Customizing LaTeX
\numberline: Table of Contents
\numberTeX: Customizing LaTeX
\pagerefs: Customizing LaTeX
\pagerefs: Page references
\pg: Using makeindex
\section: Sections
\startindex: LIndex
\subsection: Sections
\subsubsection: Sections
\Title: Table of Contents
\title: Table of Contents
\topofcontents: Table of Contents
\topofindex: Merging indexes
\twocolumn: LIndex
\usepackage: Document class
\Wbegin: Document class
\Wblock: -b
\Wfin: LIndex
\Wid: S_format
\WID: S_format
\WidD: S_format
\WIDD: S_format
\WidM: S_format
\WIDM: S_format
\WIFfmt: ATi
\Wintrinsic: S_format
\Wkeyword: S_format
\WKEYWORD: S_format
\Wlbl: -ncolon
\Wlbl: Fortran
\Wma: S_format
\WMA: S_format
\Wreserved: S_format
\WRESERVED: S_format
\Wshort: S_format
\Wtypewriter: S_format
\WXA: -W[

ASCIIstr: ATdquote

CONTENTS.tex: Output files

fweb.sty: Input files
fweb.sty: Style
fwebinsert.sty: Inserting woven code
fwebmac.sty: Output
fwebmac.sty: fwebmac.sty
fwebmac.web: Fwebmac params
fwebnum.sty: Numbering
fwebnum.sty: Inserting woven code
FWEB_HDR_INCLUDES: Environment variables
FWEB_INCLUDES: Environment variables
FWEB_INI: Environment variables
FWEB_STYLE_DIR: Environment variables

idxmerge.sty: Merging indexes
INDEX.tex: Output files

MODULES.tex: Output files
multicol.sty: LIndex

tempnam: -F_
termcap: Color
termcap0: Color
tmpnam: -F_

Jump to:   #   $   -   .   @   \  
A   C   F   I   M   T  

Previous: Option and command index, Up: Top   [Contents][Index]

Parameter index

Jump to:   A   C   D   E   F   G   I   L   M   N   O   P   S   U  
Index Entry  Section


cchar: cchar
cdir_start: cdir_start
Color.black: Color
Color.blue: Color
Color.cyan: Color
Color.default: Color
color.error: Color
color.fatal: Color
Color.green: Color
color.include_file: Color
color.info: Color
color.in_file: Color
color.line_num: Color
Color.magenta: Color
color.mod_name: Color
color.mod_num: Color
color.ordinary: Color
color.out_file: Color
color.program_name: Color
Color.red: Color
color.timing: Color
color.warning: Color
Color.white: Color
Color.yellow: Color
contents.postamble: S_contents
contents.preamble: S_contents
contents.tex: S_contents

delim_0: S_delim
delim_n: S_delim
dot_constant.begin: S_dot_constant
dot_constant.end: S_dot_constant

ext.ch: S_Ext
ext.hch: S_Ext
ext.hweb: S_Ext
ext.web: S_Ext

format.id: S_format
format.ID: S_format
format.intrinsic: S_format
format.keyword: S_format
format.KEYWORD: S_format
format.macro: S_format
format.MACRO: S_format
format.outer_macro: S_format
format.reserved: S_format
format.RESERVED: S_format
format.short_id: S_format
format.typewriter: S_format
format.WEB_macro: S_format

group_skip: group_skip

indent.code: S_indent
indent.TeX: S_indent
index.collate: S_index
index.name: S_index
index.postamble: S_index
index.preamble: S_index
index.tex: S_index
item_0: item_0

language.prefix: S_language
language.suffix: S_language
LaTeX.class: S_LaTeX
LaTeX.class.options: S_LaTeX
LaTeX.options: S_LaTeX