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

A style file (patterned after the utility `makeindex'; see section The Style file) can be associated with each manuscript in order to customize its 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} webfile[.web] [changefile[.ch]] [-option...]

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 before the file names. The first file name encountered is the web file (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.

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'. No spaces are allowed between any option and its argument. 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, and `-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 may be used anywhere; others 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 global language to C

Usually the global language (section LANGUAGES) is set to C by means of the command `@c' in limbo, not 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., `"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)

The `-f' option turns off the subscripting operations inserted by FWEAVE to indicate where various identifiers are defined. Sometimes these are very helpful; sometimes they are too cluttered and confusing. See section Customizing cross-reference subscripts.

`-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' statements, which would otherwise be necessary in order that the code be pretty-printed correctly. For example, in the code

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

Complex z;

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

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 (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. There is, as yet, no mechanism for sending macro definitions to the preprocessor, so conditional preprocessing that relies on macro definitions made outside of the header file will not work correctly. Furthermore, it works only when one's compiler is `gcc' or `g++'. (Code hasn't yet been added to automatically figure out how to run the preprocessor on an arbitrary system.)

The `-H' mechanism uses temporary files to do its work. By default, these are deleted after use. However, for debugging purposes, one can force these to be retained by saying `-Hr'. This 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 (`-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 quotes are necessary because the argument list contains spaces, and the dollar sign must be escaped because it has special significance to the shell. 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 command `-H' 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': 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. By default, only the upper-case forms of these words are recognized, because certain of the lower-case forms--in particuler, `end', `read', and `write'---have other special meanings (and FWEB identifiers can have just one meaning throughout the code). However, when the `-k' option is used, the lower-case forms are recognized as well (except for the three special identifiers just mentioned).

`-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': 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 at the beginning 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 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 semicolons [FORTRAN]

This is the default mode of operation in FORTRAN--77; the input driver automatically appends a semicolon to each logical line of source code. Since it's the default, one doesn't have to use it unless one wishes to negate it. See section Negating options.

Although semicolons are appended automatically for FORTRAN--77, FWEAVE will not print them by default since that seemed to annoy many users. To force the semicolons to be printed, use the `-np' option (see section `-np': Print semicolons [FORTRAN] (FWEAVE)).

Currently, this option has no effect for FORTRAN--90 in free-form syntax (see section `-n\': Free-form syntax continued by backslash and section `-n&': Free-form syntax continued by ampersand). That is, one must supply the semicolons oneself (as one would do in C or RATFOR). (Without the semicolons, one's code may tangle correctly, but FWEAVE will be confused.) Consider this to be a feature. It is an attempt to provide some uniformity of style for the various free-form languages (C, RATFOR, and FORTRAN-90) that FWEB supports. I expect some arguments on this point, and may back down.

`-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'. This 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).

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

Although for fixed-form syntax the FORTRAN input driver automatically terminates logical lines with semicolons so that the innards of FWEAVE can process them correctly (see section `-n;': Supply automatic semicolons [FORTRAN]), the semicolons are not printed by default. To make them be printed, use the `-np' option.

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

In free-form syntax, an FWEB convention is that at present the user must supply semicolons by hand at the end of each statement. For more discussion, see section `-n;': Supply automatic semicolons [FORTRAN].

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;

In free-form syntax, an FWEB convention is that at present the user must supply semicolons by hand at the end of each statement. For more discussion, see section `-n;': Supply automatic semicolons [FORTRAN].

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[-n/]

In FWEB, one may always use `\/' for concatenation,

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

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

        s = "A \! inside a string"

`-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. (But note that future FWEB development will be based on LaTeX; `-PT' is no longer fully supported.)

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

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

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.

`-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': 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 checks 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 3, so messages about both of the above conditions are printed. The `-W@flag' overrides the default. For example, to get messages only about multiple uses, say `-W@2'.

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

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 not to use it. 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 an 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. 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 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'.

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

`-=': Redirect output (FTANGLE)

Equivalent to `->' (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 `-#'.

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 use `-+'. This is unnecessary, however, because in FWEB you can always use `!=' instead.

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, the `//' construction will be interpreted as concatenation rather than as the beginning of a short comment.

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.