FWEB

  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

FWEB

This Texinfo documentation describes FWEB Version 1.70.

• To learn about new features of this version, see V1.70.
• For a quick introduction to, and review of the structure of an FWEB source file, see Structure.
• FWEB is no longer regularly supported because its author is retired. There will probably be no further major release; there are too many other things to do in retirement. However, intermittent bug fixes and feature updates may be made from time to time.

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

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

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.

 — The Detailed Node Listing —

INTRODUCTION to FWEB

WEB CONCEPTS

FILES

Input files

RUNNING FWEB

Command-line options

‘-T’:  Flag-setting options for FTANGLE

‘-W’:  Flag-setting options for FWEAVE

Commands that inhibit printing:

FWEB COMMANDS

Literal control characters:

Beginning of section:

Beginning of code part:

Control codes b–z:

Conversion to ASCII:

Forward referencing:

Comments:

Special brace:

Index entries:

Control text:

Spacing:

Pseudo (invisible) operators:

Miscellaneous:

COMMENTING STYLES

MACROS and PREPROCESSING

FWEB macros

Various features of FWEB macros

Built-in functions

INDIVIDUAL BUILT-IN FUNCTIONS

LANGUAGES

Special hints and considerations for each language.

RATFOR

DOCUMENTATION

Typesetting

The macro package fwebmac.sty

LaTeX support

LaTeX packages related to FWEB

Customizing LaTeX’s output

Pretty-printing

FWEB’s INDEX.

CUSTOMIZATION

Memory allocation

The Style file

Customizing FWEAVE’s index

Customizing the module list

Customizing the Table of Contents

Customizing cross-reference subscripts

Customizing the behavior of fwebmac.sty macros

Miscellaneous style-file parameters

For FWEAVE:

For both processors:

Automatic file name completion

USAGE TIPS and SUGGESTIONS

NEW FEATURES

* V1.70

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.

1 INTRODUCTION to FWEB

FWEB is a system for literate programming. It enables one to maintain both documentation and source code in a single place (the web file), and to explain the code in terms of a web of very small fragments. Because FWEB is intimately integrated with TeX, one gains many advantages such as book-quality typesetting and extensive cross-referencing facilities. A simple example program is described in 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 2023¹), 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.²

1.1 History of WEB and literate programming

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

1.2 Features of FWEB

FWEB is distinguished from its relatives in several respects:

• FWEB introduces the concept of a current language (see Languages), so more than one compiler language can be processed in a single FWEB run. For example, mixtures of C or C++ and FORTRAN are common in modern scientific programming.
• FWEB understands the syntaxes of several of the more important compiler languages: C (both C89 and the later language extensions through 2023), C++, FORTRAN (both F77, F90, and the later language extensions through 2023), RATFOR, and TeX. For other languages, FWEB can work in a language-independent mode that essentially weaves and tangles the source code verbatim, but still provides the user with the powerful WEB features related to TEX documentation, module names, macro processing, etc.
• FWEB contains a built-in RATFOR (RATIONAL FORTRAN) translator. See Ratfor. (RATFOR has not been updated to the modern versions of FORTRAN and has not been recently tested.)
• FWEB has a built-in C-like macro preprocessor. This is especially useful for FORTRAN and RATFOR, which have no predefined preprocessor. However, certain extensions such as variable numbers of arguments make the FWEB preprocessor sometimes useful even for C and C++. See Macros, and Preprocessing.
• Many aspects of FWEB’s behavior, default strings, etc. can be customized by means of setting parameters in a makeindex-like style file (by default, fweb.sty). See Style.

2 WEB CONCEPTS

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.

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.³ (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.⁴

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.

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 follows⁵:

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

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

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

@a
        program main
        call compute
        end

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

@* \INDEX.

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

@* [INTRO]INTRODUCTION.

The command ‘@*n’ (not illustrated in the above example) begins a major (sub)section of level n, where ‘@*0’ is equivalent to the simple ‘@*’, ‘@*1’ indicates a subsection, and ‘@*2’ indicates a subsubsection. The highest permissible major level is 2 (a subsubsection). Such subsections are also entered in the Table of Contents. For more information, see 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.

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

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

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

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

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

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

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

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

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

There are several details to notice about the above example. First, FWEAVE considers module names to be simple expressions (such as the single identifier x). In C, expressions are made into complete statements (as is required in the body of a for statement) by appending a semicolon. In this case, a pseudo-semicolon ‘@;’ is appropriate; for more discussion of that, see 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

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

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

Very rarely, one might try the following construction:

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

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

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

• discards TeX documentation;
• tokenizes the source;
• expands FWEB preprocessor commands such as ‘@#if’ (see Preprocessing);
• expands ‘@'...'’ (see ATquote), ‘@"..."’ (see ATdquote), and the binary notation ‘0b...’ (see C) [in FORTRAN, also the octal notation ‘0...’ and the hexadecimal notation ‘0x...’];
• stores code text in appropriate modules;
• memorizes macro definitions (‘@d’ and ‘@m’) (see ATd and ATm).

Phase 2

• outputs outer macro definitions (‘@d’);
• outputs the unnamed module (‘@a’);
• expands FWEB macros (‘@m’);
• expands built-in macros such as ‘$IF’ or ‘$PI’ (see Built-in functions);
• translates RATFOR statements (see Ratfor).

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

• tokenizes and stores identifiers and module names;
• collects cross-reference information (including, in C and C++, the scanning of ‘#include’ files for ‘typedef’ and/or ‘class’ declarations (see -H_);
• stores limbo text definitions made with ‘@l’ (see ATl);
• collects information about overloaded operators (‘@v’) and identifiers (‘@W’). See ATv, and ATW_.

Phase 2

• outputs limbo text;
• outputs special TeX macros for overloaded operators;
• copies TeX material directly to output;
• treats material between vertical bars (‘|...|’) as code to be typeset;
• tokenizes and stores contents of each code section;
• analyzes code syntax and converts it to appropriate TeX macros.

Phase 3 writes out cross-reference information. (To eliminate some of that, see -x.) Specifically, it

• writes out the Index (INDEX.tex by default, but see Output files and Index params);
• writes out a list of named modules (MODULES.tex by default, but see Output files and Module params);
• writes out macros to generate the Table of Contents. (Table of Contents information is actually processed by LaTeX, not FWEAVE. The information is written to the aux file.)

3 FILES

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

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.

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

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:

Language	Style-file entry	UNIX default	non-UNIX default
C	suffix.C	c	c
C++	suffix.Cpp	C	C
Fortran–77	suffix.N	f	for
Fortran–90	suffix.N90	f90	for90
Ratfor–77	suffix.R	r	rat
Ratfor–90	suffix.R90	r90	rat90
TeX	suffix.X	sty	sty
VERBATIM	suffix.V	mk	mk

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

suffix.C = "c++"

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:

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

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

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

ftangle test test

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

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

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

4 RUNNING FWEB

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.

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

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.

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.

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.

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.

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.

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.

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

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.

4.2.8 ‘-C’: Set the color mode

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

0

No color

1

ANSI color

2

Bilevel

3

Trilevel

4

User-defined

These modes, and color output in general, are described more thoroughly in 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’.

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

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.

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

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

This option is obsolete.

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.

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.

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.

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.

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

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

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

In addition to the basic ‘-H’, there are several more detailed options:

-Hx

Make index entries only for double-quoted include files.

-HX

Make index entries for all include files.

-Hr

Retain temporary files generated by the preprocessor.

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

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

By default, the C preprocessor will look in certain default paths for the included files. To add to those defaults, use one or more ‘-I’ options after the ‘-H’. These colon-delimited lists are concatenated to the contents of the environment variable FWEB_HDR_INCLUDES, if that is defined. (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.

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

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.

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.

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.

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.

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.

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

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.

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:

0

Like level 1, but the start-up banner is not printed. If FWEB runs to completion with no errors, nothing at all will be printed.

1

Print only error messages.

2

Print error and warning messages.

3

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

4

Print everything.

The start-up banner, which includes the version number, is printed for all message levels except 0. For level 0, one can use the ‘-V’ option to request the start-up banner. See -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.

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

The command-line construction

-mA(x)=x

defines the FWEB macro A as though the definition

@m A(x) x

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

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

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

The equals sign is permitted only with command-line macro definitions, not with ‘@m’ commands (see ATm) in the definition parts of the web file.

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.

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

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.

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

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

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

	Fixed	Free
F77	‘-n;’	N/A
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.

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

EXIT:
  continue

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

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.

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:

• In FWEB, blocks of code should be commented out with the preprocessor commands @#if 0...@#endif; see Temporary comments.
• Textual comments for documentation should be converted to the standard FWEB commenting style.
• If one has a block of code prefaced by an extremely long comment, replace that by a named module and put the comment into the TeX part of that section.

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

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,

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

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

See also -n&.

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,

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

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

See also -n\.

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

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.

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(' ')
@a
dimension x(0:4)(1:2)
character*90 ch(4)
write(6,*) SP ((x(i)(j),i=1,2), j=3,4)
c = ch(4)SP(3:4)

This option is controlled by the three style-file parameters ‘paren.len’, ‘paren.num’, and ‘paren.nest’. (See 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.

4.2.43 ‘-o’: Don’t overload operators

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

4.2.44 ‘-q’: Don’t translate RATFOR

This option is obsolete.

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.

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.

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

See Languages, and Ratfor. See also -L_.

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

See Languages, and Ratfor. See also -L_.

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

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.

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.

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.

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.

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.

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

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"

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

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

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.

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

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

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

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

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

4.2.59.4 ‘-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.]

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

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

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.

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.

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.

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

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

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

Commands that inhibit printing:

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

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

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

4.2.65.4 ‘-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

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

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.

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.

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.

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.

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.

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

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

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 \
      \continued";

the effective string is "This is continued" when ‘-\’ is in effect.

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

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.

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

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

4.2.77 ‘-=’: Redirect output (FTANGLE)

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

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