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


RUNNING @FWEB{}

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

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

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

Command-line syntax

The command-line syntax is

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

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

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

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

Command-line options

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

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

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

Negating options

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

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

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

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

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

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

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

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

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

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

`-@': Display the control-code mappings

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

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

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

`-A': Turn on ASCII translations

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

`-B': Turn off audible beeps

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

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

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

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

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

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

`-C': Set the color mode

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

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

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

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

`-c': Set global language to C

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

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

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

`-D': Display reserved words

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

ftangle -Lr9 -D

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

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

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

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

`-d': Convert do...enddo

(This option is obsolete.)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`-h': Get help

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

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

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

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

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

The `-I' option appends to this list.

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

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

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

@I formats.hweb

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

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

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

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

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

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

@I formats.hweb

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

`-j': Inhibit multiple includes

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

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

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

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

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

`-L': Select global language

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

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

`-l': Echo input line

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

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

`-M': Set output message level

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

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

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

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

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

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

The command-line construction

-mA(x)=x

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

@m A(x) x

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

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

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

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

`-m4': Understand m4 built-in commands

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

`-m;': Append pseudo-semicolons

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

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

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

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

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

See also section LANGUAGES and section Special considerations for FORTRAN.

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

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

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

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

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

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

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

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

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

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

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

a = b; c = d

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

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

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

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

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

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

    EXIT: continue
    

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

    EXIT:
      continue
    

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            s = "A \! inside a string"
    

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

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

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

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

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

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

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

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

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

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

    `-o': Don't overload operators

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

    `-q': Don't translate RATFOR

    (This option is obsolete.)

    `-P': Select TeX processor

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

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

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

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

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

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

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

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

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

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

    `-rg': Set goto parameters

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            s = "A \! inside a string"
    

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

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

    `-s': Print statistics

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

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

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

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

    `-TD': Permit processing of deferred macro definitions

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

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

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

    `-Tm': Permit user macros to be redefined

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

    `-Tv': Don't print header info

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

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

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

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

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

    `-t': Truncate identifiers

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

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

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

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

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

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

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

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

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

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

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

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

    `-W@': Set module warning flag.

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

    1. Never used.
    2. Multiple uses.

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

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

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

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

    `-W[': Process bracketed array indices

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    `-y': Allocate dynamic memory

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

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

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

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

    `-Z': Display default style-file parameters

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

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

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

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

    `-z': Change name of style file

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

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

    `-.': Don't recognize dot constants

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

    `-\': Explicitly escape continued strings

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

    "This is \
          \continued";
    

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

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

    `-(': Continue parenthesized strings with backslashes

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

    `-:': Set starting automatic statement number

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

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

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

    This command has no effect for @FWEAVE{}.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            s = "A \! inside a string"
    

    Information options

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

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

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

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

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

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


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