NOTE: Because of translation problems with texi2html operating on the macro-expanded version of fweb.texi, user-defined macro expansion has temporarily been turned off in this html version. I'll fix this as soon as possible.
This Texinfo documentation describes @FWEB{} Version 1.60.
- To learn about new features of this version, see section Version 1.60.
- For a quick introduction to, and review of the structure of an @FWEB{} source file, see section The structure of a web.
- If you used to receive e-mail information about @FWEB{} but don't any longer, it's probably because you need to update your e-mail address in the
fweb-usersmailing list. Subscription instructions can be found in section SUPPORT.- Bug reports and suggestions are much appreciated, but are no longer acknowledged individually. See section SUPPORT.
- The next major release, @FWEB{} Version 2.00, is planned for no earlier than January 1, 2000.
This documentation is now accessible on the World-Wide Web from
Other sources of information about @FWEB{} are the archival files of
the fweb-users and fweb-installers mailing lists. To
learn how to obtain those, see section SUPPORT.
If you are learning @FWEB{} for the first time, you will probably find that this (unfinished) manual is not sufficiently pedagogical. For background, please refer to Knuth's book cited in section INTRODUCTION to @FWEB{}. You should also browse through section WEB CONCEPTS, in particular section The structure of a web.
@FWEB{} is "free." This means that everyone is free to use them and free to redistribute them on a free basis. @FWEB{} operates under the terms of the GNU General Public License; see, for example, section `Distribution' in The GNU Emacs Manual.
Although it is hoped that @FWEB{} will be useful, there is ABSOLUTELY NO WARRANTY.
@FWEB{} is a system for literate programming. It enables one to
maintain both documentation and source code in a single place (the
web file), and to explain the code in terms of a web of
very small fragments. Because @FWEB{} is intimately integrated with
TeX, one gains many advantages such as book-quality typesetting and
extensive cross-referencing facilities. A simple example program is
described in section The structure of a web.
@FWEB{} was originally intended for scientific programming (the 'F' stands for FORTRAN), and is in wide use in that arena; however, it has much broader applicability. It is an extension of Knuth's WEB system that handles the specific languages C, C++, Fortran (both F77 and F90), RATFOR, and (in a limited fashion) TeX itself. It also attempts to implement a WYSIWYG language-independent mode as well as a (closely-related but not identical) verbatim `language'. The language-independent features are highly experimental and are not recommended.
The origins and philosophy of literate programming are described in the very enjoyable book by D. E. Knuth, Literate Programming (Center for the Study of Language and Information, Leland Stanford Junior University, 1992).
Knuth's original WEB was written in Pascal, and it formatted Pascal code. Silvio Levy introduced CWEB, a WEB system written in C for C. @FWEB{} is a (by now, substantial) modification of version 0.5 of CWEB that was graciously supplied by Levy. It also borrows various ideas from the works of Ramsey and Briggs on language-independent webs.
The original WEB's worked with Plain TeX. More recently, many users have turned to Lamport's LaTeX because of its ease of use and higher-level features. Excellent and extensive development of LaTeX has been accomplished, as described by Goossens, Mittelbach, and Samarin, The LaTeX Companion (Addison--Wesley, Reading, MA, 1994). The present version of @FWEB{} is intended to be used with LaTeX (LaTeX2e, in particular); Plain TeX is no longer supported.
(To be completed; see Knuth's book, cited in section INTRODUCTION to @FWEB{}.)
@FWEB{} is distinguished from its relatives in several respects:
- @FWEB{} introduces the concept of a current language (see section LANGUAGES), so more than one compiler language can be processed in a single @FWEB{} run. For example, mixtures of C++ and FORTRAN are common in modern scientific programming.
- @FWEB{} understands the syntaxes of several of the more important compiler languages: C, C++, FORTRAN (both F77 and F90), RATFOR, and TeX. For other languages, @FWEB{} can work in a language-independent mode that essentially weaves and tangles the source code verbatim, but still provides the user with the powerful WEB features related to TEX documentation, module names, macro processing, etc.
- @FWEB{} contains a built-in RATFOR (RATIONAL FORTRAN) translator. See section RATFOR.
- @FWEB{} has a built-in C-like macro preprocessor. This is especially useful for FORTRAN and RATFOR, which have no predefined preprocessor. However, certain extensions such as variable numbers of arguments make the @FWEB{} preprocessor sometimes useful even for C and C++. See section MACROS and PREPROCESSING and section Preprocessing.
- Many aspects of @FWEB{}'s behavior, default strings, etc. can be customized by means of setting parameters in a
makeindex-like style file (by default, `fweb.sty'). See section The Style file.
The principle concepts of WEB programming are laid out in Knuth's book, the reference to which was given in section INTRODUCTION to @FWEB{}. @FWEB{} follows most conventions introduced by WEB and CWEB, except that the names of some commands have been changed for consistency, symmetry, and/or clarity.
Following Knuth's original design, @FWEB{} consists of two processors, @FTANGLE{} and @FWEAVE{}. Both operate on a single source file, say `test.web'. @FTANGLE{} produces compilable code, say `test.c', whereas @FWEAVE{} produces a TeX file, `test.tex', that can (in principle) be processed with either TeX or LaTeX. (If a file `test.tex' already exists, @FWEAVE{} will ask for confirmation before overwriting it if it does not think that the file was created by a previous run of @FWEAVE{}.)
The output file produced by @FTANGLE{} is not intended for human eyes
(or for editors!); it is for compiling only. All changes to the code
should be made to the web file, since changes made directly to
the output file would be overwritten the next time the web source
is tangled. In an attempt to discourage messing with @FTANGLE{}'s
output file, all unnecessary spaces are deliberately removed.
A common way of integrating @FWEB{} into ones program development is to
do all compilations through a make file, into which one puts an
extra dependency line that explains how to produce the compilable output
file from the web source. For example,
test.c: test.web
ftangle test
test.o: test.c
gcc -c test test.c
With this approach, one is not so tempted to edit `test.c'.
@FWEB{} development is now based on LaTeX; Plain TeX is no longer supported. For detailed descriptions of the LaTeX support, see section LaTeX support.
An @FWEB{} source file is structured into sections, which correspond to logical subunits of the code (either a function or a fragment of a function). Each section consists of three parts, each of which is optional: the
- TeX part;
- definition part; and
- code part.
When @FTANGLE{} outputs code, it can combine the code parts of (possibly noncontiguous) sections into larger units called modules, as explained in section Modules.
With the aid of sections, one's possibly huge and logically complex code can be broken down into bite-sized pieces, each one easily comprehensible. Since sections may correspond to only a small part of a function or subroutine, 1000-line main programs (they still exist!) should become a thing of the past.
Since sections can be combined into modules, there is no need for sections that must be physically contiguous in the output file to be contiguous in the source file. This allows for great flexibility in structuring the documentation of the code.
A simple example of an @FWEB{} source file consisting of three sections is as follows:
@n/ % Set FWEB language to Fortran, and recognize short // comments.
\Title{example.web} % \Title is an FWEB TeX macro.
\author{J. A. Krommes} % \author is a LaTeX macro.
@* INTRODUCTION.
This code is intended to illustrate the use of the |write| statement.
It also provides a simple example of the \FWEB\ macro preprocessor.
@m A_CONSTANT 1.2345 // \FWEB\ preprocessor macro definition.
@a
program main
call compute
end
@ The computational routine is pretty boring.
@a
subroutine compute
write(*,*) 'Macro value = ', A_CONSTANT
end
@* \INDEX.
Commands to @FWEB{} are begun by the `@' symbol (see section @FWEB{} COMMANDS). In this example, the first command, `@n', sets the global language to FORTRAN-77. One should always begin one's code with a language-setting command.
In this example, the language command is invoked with an optional argument `/'. That is necessary in FORTRAN in order to tell @FWEB{} to use the short (single-line) comment form beginning with `//', which otherwise conflicts with the concatenation operator. See section `-n/': Recognize short comments [FORTRAN].
For more information about languages, see section LANGUAGES. For a fuller discussion of optional arguments, see section Setting the language.
The `@*' command begins a major or named section
(corresponding to LaTeX's \section command); this command is
followed by the section name, terminated by a period. (The period is
essential; if it is omitted, weird errors may result.) Major sections
are entered in an automatically generated Table of Contents. They are
also printed at the top of each output page. If the full section name
is too long to so print, one can shorten it with an optional argument,
as in
@* [INTRO]INTRODUCTION.
The command `@*n' (not illustrated in the above example) begins a major (sub)section of level n, where `@*0' is equivalent to the simple `@*', `@*1' indicates a subsection, and `@*2' indicates a subsubsection. The highest permissible major level is 2 (a subsubsection). Such subsections are also entered in the Table of Contents. For more information, see section Sections in LaTeX.
As the example demonstrates, the name of the very last section, which
should be starred, should be `\INDEX'. Note the backslash;
`\INDEX' is a TeX macro. This command tells @FWEAVE{} to
write out the index in a special two-column format. By default,
`\INDEX' expands to `INDEX', but this name can be overridden
by the style-file parameter `index.name' (see section index.???). For
more discussion of @FWEB{}'s indexing facilities, see section @FWEB{}'s INDEX..
Minor (unnamed) sections are begun by @ASP{} ("at-space"); these have no associated names and are not entered into the Table of Contents. A newline counts as a space.
All sections begin with (optional) TeX commentary. That can just be straight text; to input that, no knowledge of TeX is required. It can also include mathematical exposition or any of the other advanced features offered by TeX.
Whenever @FWEB{} is in TeX mode, one can temporarily shift into code mode by enclosing the code within vertical bars. That code is typeset just like code in the code part (see below), except that newlines are replaced by spaces. Thus, one can say things like
Consider the C code fragment `|@c for(i=0; i<10; i++){}|', which ...
(If the global language were C instead of FORTRAN, the `@c' inside the vertical bars would not be necessary.) The ability to switch back and forth between text mode and code mode at will allows for a very convenient and flexible style of exposition.
The TeX part is followed by an optional definition part. The beginning of the definition part is signaled by the appearance of any one of the commands `@d', `@f', `@m', `@v', or `@W' (explained later). In the previous example, the first section has a definition part consisting of one @FWEB{} macro definition (`@m'); the second section has no definition part. For more information, see section MACROS and PREPROCESSING.
(Failure to appreciate how easy it is to shift from part to part can get one into trouble. For example, don't write documentation such as `Consider the @m command', because the `@m' will inadvertently terminate the documentation part and begin the definition part. What one needs to do here is to use the literal `@', as in `@@m'.)
An unnamed code part is begun by `@a'. A named code part is begun by the appearance of a module name, such as `@<Global variables@>', followed by an equals sign; see section Modules. Within the code part, one can place any sequence of code or code fragments (they need not be complete subroutines) that are valid for the current language. (Setting the language is described in section LANGUAGES.) The code part is terminated by the next appearance of `@*' or @ASP{} (which signal the beginning of a new section), or by the end of file.
The portion of the source file before the first section (i.e., before
the first `@*' or @ASP{}) is called in limbo or
the limbo section.
The only `@' commands that are allowed in limbo (in addition to
`@@', which stands for the character `@' and is allowed
anywhere) are the language-changing commands, and one of those, such as
`@c', should appear. Other text in limbo is ignored by @FTANGLE{}
and is copied by @FWEAVE{} to the tex output file. Thus, one can make or
issue TeX macro definitions in limbo that override the defaults in
@FWEB{}'s macro package `fwebmac.sty'. In the above example, see
the \Title command. This is defined in `fwebmac.sty', and
basically issues LaTeX's \title command.
(Another way of getting TeX text into the limbo section is by means of the `@l' command; see section `@l': Specify limbo text.)
LaTeX users may need to know that TeX commands in limbo are executed after the `\begin{document}' command (which is issued automatically in `fwebmac.sty'). For more information, see section LaTeX support.
The code parts of (possibly noncontiguous) sections can be combined into modules. For @FWEAVE{}, this is a logical combination, for purposes of cross-referencing different pieces of the code. But for @FTANGLE{}, the combination is physical; @FTANGLE{}'s output proceeds module by module.
Modules can be named or unnamed. There is exactly one unnamed module. The fundamental operation of @FTANGLE{} is that
@FTANGLE{ outputs the unnamed module}.
That output goes to a compilable file with an extension appropriate to the current language.
The contents of a module, either unnamed or named, consists of a mixture of code and comments. @FTANGLE{} ignores the comments; @FWEAVE{} treats them as TeX text. Within any TeX text, including comments, constructions delimited by `|...|' signify a temporary shift into code mode. (In the present design, one cannot enclose a comment within the vertical bars.)
The unnamed code module is introduced by the command `@a'. Subsequent uses of `@a' accrete code to the unnamed module. To repeat, the fundamental operation of @FTANGLE{} is that
@FTANGLE{ outputs the unnamed module}.
Thus, there must be at least one `@a' in the source file or @FTANGLE{} will output nothing.
(Why is the command called `@a'? Historically, it was the first letter of the alphabet, as befits its prominent status. However, one can also think of it as "accrete.")
Named modules represent logically-connected fragments of code.
A module name is specified by the construction
@< Arbitrary TeX text @>
Leading and trailing white space around the name text is ignored. The name text can include the `|...|' construction, which tells @FWEAVE{} to typeset a code fragment. Thus, module names can be highly explicit--for example,
@< Check that |x >= 0.0|; |abort| if not @>
To define a named module, replace the `@a' that begins the unnamed code part of a section by `@< module name @>='. If one uses this construction with the same name in a later section, the effect is to accrete to the contents of the module. Thus, a named module might ultimately consist of the code from sections 2, 5, and 9, for example.
To use a named module, simply use the name anywhere in a code part; @FTANGLE{} will insert the contents of the module at the point where the name is used. For example,
@c
@ Here's how to use a named module.
@a
for(i=1; i<n; i++)
@< Inner loop @>@;
@ Here's how to define a named module. Definitions may occur after use.
@< Inner...@>=
{
a[i] = i;
}
There are several details to notice about the above example. First, @FWEAVE{} considers module names to be simple expressions (such as the single identifier x). In C, expressions are made into complete statements (as is required in the body of a for statement) by appending a semicolon. In this case, a pseudo-semicolon `@;' is appropriate; for more discussion of that, see section `@;': Pseudo-semicolon.
Second, after a name has appeared once in full, it may be abbreviated by a unique prefix followed by three periods, as demonstrated in the above example. By convention, a complete module name cannot be a subset of another. For example, `@<Test@>' and `@<Test of graphics@>' will elicit an error message.
Commonly, the first unnamed section in the code indicates its modular structure. For example, a C code might begin with
@c @* DEMO. @a @<Include files@>@; @<Typedefs@>@; @<Function prototypes@>@; @<Global variables@>@;
Subsequently one can accrete to the above named sections, as often as
desired and in any order. This way, definitions of global variables can
be introduced anywhere in the web source file as logical and pedagogical
exposition dictates, but will
be guaranteed to appear at the top of the code. Function prototypes
could be handled this way as well; alternatively, they could all be
collected into one section, perhaps at the end of the source file. (The
above organization still guarantees that they will appear at the
beginning of the output.) Functions could be introduced one at a time
in subsequent unnamed sections.
Very rarely, one might try the following construction:
@ @a @< Left side @> = @< Right side @>@;
Here the intent is to construct an assignment statement. However, this will be flagged as an error because @FWEB{} thinks one is trying to define the named module `@<Left side@>', which one shouldn't be doing while in code mode. To make it work, just put the invisible expression `@e' (see section Pseudo (invisible) operators) before the equals sign.
The @FWEB{} processors perform their work in several distinct phases. (The following is somewhat technical. Scan it, then use it for reference later if necessary.)
@FTANGLE{} has two phases. In phase 1, the source file is read; in phase 2, compilable code is written out in the order specified by the web.
More specifically, phase 1
- discards TeX documentation;
- tokenizes the source;
- expands @FWEB{} preprocessor commands such as `@#if' (see section Preprocessing);
- expands `@'...'' (see section Conversion to ASCII), `@"..."' (see section `@"': Convert string to ASCII), and the binary notation `0b...' (see section Special considerations for C) [in FORTRAN, also the octal notation `0...' and the hexadecimal notation `0x...'];
- stores code text in appropriate modules;
- memorizes macro definitions (`@d' and `@m') (see section `@d': Define outer macro, and mark and section `@m': Define @FWEB{} macro, and mark).
Phase 2
- outputs outer macro definitions (`@d');
- outputs the unnamed module (`@a');
- expands @FWEB{} macros (`@m');
- expands built-in macros such as `$IF' or `$PI' (see section Built-in functions);
- translates RATFOR statements (see section RATFOR).
@FWEAVE{} has three phases. In phase 1, the source file is read and cross-reference information is collected. In phase 2, the source file is read again, then pretty-printed with some cross-reference information. (For discussion of pretty-printing, see section Pretty-printing.) In phase 3, an automatically-generated Index, List of Modules, and Table of Contents are written.
More specifically, phase 1
- tokenizes and stores identifiers and module names;
- collects cross-reference information (including, in C and C++, the scanning of `#include' files for `typedef' and/or `class' declarations (see section `-H': Scan C/C++ include files (@FWEAVE{}));
- stores limbo text definitions made with `@l' (see section `@l': Specify limbo text);
- collects information about overloaded operators (`@v') and identifiers (`@W'). See section `@v': Overload operator and section `@W': Overload identifier.
Phase 2
- outputs limbo text;
- outputs special TeX macros for overloaded operators;
- copies TeX material directly to output;
- treats material between vertical bars (`|...|') as code to be typeset;
- tokenizes and stores contents of each code section;
- analyzes code syntax and converts it to appropriate TeX macros.
Phase 3 writes out cross-reference information. (To eliminate some of that, see section `-x': Eliminate or reduce cross-reference information (@FWEAVE{})..) Specifically, it
- writes out the Index (`INDEX.tex' by default, but see section Output files and section Customizing @FWEAVE{}'s index);
- writes out a list of named modules (`MODULES.tex' by default, but see section Output files and section Customizing the module list);
- writes out macros to generate the Table of Contents. (Table of Contents information is actually processed by LaTeX, not @FWEAVE{}. The information is written to the `aux' file.)
@FWEB{} works with a variety of files. File names have the form `[path]/root[.ext]', where the brackets denote optional. Here the slash is called the prefix end character. Since this character differs for various operating systems, it can be changed by system installers in `custom.h' (see section CUSTOMIZATION). The character that initiates the file-name extension (normally a period) can be changed with the `-E' command-line option (see section `-E': Change the delimiter of a file-name extension).
@FWEB{} reads files with a variety of default extensions.
`.fweb' -- Initialization file (optional; for setting up default options used for all runs). This file is always in the user's home directory. See section Initialization.
`fweb.sty' -- Style file (optional; for customizing the behavior of a particular
webfile or group of files). See section The Style file. This file is always in the directory of thewebfile that is being tangled unless that is changed by environment variableFWEB_STYLE_DIR. The basic name can be changed by the `-z' option (see section `-z': Change name of style file). A sample `fweb.sty' file is provided with the @FWEB{} distribution.`name.web' -- Source file.
`name.ch' -- Change file (optional; for making incremental changes to a
websource file). See section Change files.`name.hweb' -- Code included into web file with `@i' (see section `@i': Include file (unconditional)). Include files are searched for in the path set by the environment variable
FWEB_INCLUDESand/or the `-I' option (see section `-I': Append to search list for include files). If that path is empty, then the current directory is searched.`name.hch' -- Optional change file for include file.
Automatic completion of input file names is turned on by the `-e' command-line option (see section `-e': Turn on automatic file-name completion). When this option is in effect, input file names that include no period (have no extension) are completed automatically according to the contents of the following style-file entries:
Type of file @tab Style-file entry @tab Default WEB file @tab ext.web@tabwebChange file @tab ext.ch@tabchInclude file @tab ext.hweb@tabhwebChange file for include file @tab ext.hch@tabhch
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.
@FWEAVE{} writes a variety of output files.
`name.tex' -- Woven output to be processed with LaTeX.
`CONTENTS.tex' -- Temporary file that accumulates Table-of-Contents information. (For LaTeX, the `aux' file is used instead.)
`INDEX.tex' -- Temporary file that stores indexing information.
The names of the three temporary files can be changed with style-file parameters (see section The Style file). Commonly, one may put into the style file `fweb.sty' commands such as
index.tex "#.ndx" modules.tex "#.mds" contents.tex "#.cts"
The `#' is replaced by the root name of the web file.
@FTANGLE{} writes files of the form
`name.ext' -- Compilable output file.
The extensions for the compilable output file(s) have certain defaults, but can be changed by style-file parameters according to the following table:
Language @tab Style-file entry @tab UNIX default @tab non-UNIX default C @tab suffix.C@tabc@tabcC++ @tab suffix.Cpp@tabC@tabCFortran--77 @tab suffix.N@tabf@tabforFortran--90 @tab suffix.N90@tabf90@tabfor90Ratfor--77 @tab suffix.R@tabr@tabratRatfor--90 @tab suffix.R90@tabr90@tabrat90TeX @tab suffix.X@tabsty@tabstyVERBATIM @tab suffix.V@tabmk@tabmk
For example, to change the default extension for a C++ file from `C' to `c++', put into `fweb.sty' the line
suffix.C = "c++"
The primary input to the @FWEB{} processors is the `test.web' source file. However, a change file `test.ch' can also be specified. A change file consists of instances of the following structure:
@x (One or more lines of text, EXACTLY as in the web file. Copy these lines with an editor; don't type them from scratch.) @y (Replacement text.) @z
The change-file mechanism allows one to insert local changes or test new code without physically modifying the original web file.
To specify a change file, use its name as the second file name on the command line. The extension `.ch' is assumed by default. For example,
ftangle test test
processes `test.web' with the change file `test.ch'.
In addition to `@x', `@y', and `@z', the only `@' commands allowed in a change file are language-changing commands such as `@c' and the special commands `@[' and `@]'. The command `@[' is used for column-oriented languages such as FORTRAN--77 and means switch into code mode. Similarly, `@]' means switch out of code mode.
All `@' commands in a change file must begin in column 1. Lines not beginning with `@' are ignored, so may be used as comments. Comments may also be included on the `@x', `@y', and/or `@z' lines.
@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.
{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 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.
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.
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.
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.
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.
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.
@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.)
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'.
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'.
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.
For more information, see the discussion of `-c' in section `-c': Set global language to C.
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'.
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.
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.
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.
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.
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.
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'?''.
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).
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.
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.
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.
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.
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.
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.
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.
-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 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.
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@;
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.
See section LANGUAGES and section Special considerations for FORTRAN; see also the discussion of `-L' in section `-L': Select global language.
(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].
(Don't forget that a semicolon has special meaning to UNIX shells, so you'll probably have to quote this command: `-n';''.)
This command functions the same as `-n@;' (see section `-n@;': Supply automatic pseudo-semicolons [FORTRAN], except that actual (visible) semicolons rather than pseudo-semicolons are appended. This is the default mode of operation for FORTRAN-77 (and for that language, it cannot be turned off by negation).
The distinction between `-n@;' and `-n;' has to do with what is visible on output. In FORTRAN-77, semicolons are not printed by default since that seemed to annoy many users. However, that causes trouble with FORTRAN-90 code containing multiple statements per line, as in
a = b; c = d
If `-np' is not used, then the semicolon in the above example is not printed, hindering legibility. Thus, the default mode of operation for free-format FORTRAN-90 is `-n@;' and `-np'. This turns the above example into `a = b; c = d@;' and displays it correctly.
When `-n;' is used, semicolons will not be printed by default. To force them to be printed, use the `-np' option (see section `-np': Print semicolons [FORTRAN] (@FWEAVE{})).
Do not insert semicolons by hand in FORTRAN-77; they are always inserted automatically. If you have terminated FORTRAN-90 statements by hand, turn off auto-semis by `-n;' (and use `-np' at your discretion).
The following table summarizes the defaults for auto-semi insertion and semicolon printing in FORTRAN, both fixed and free formats (`N/A' means `not applicable'):
@tab Fixed @tab Free F77 @tab `-n;' @tab N/A F90 @tab `-n;' @tab `-n@; -np'
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.
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{}).
Ignore, at the input-driver stage, comment lines beginning with `C', `c', or `*'.
Interpretation: In the usual mode of operation, the FORTRAN-77 input driver makes a heroic attempt to mix the original single-line column-1 commenting style with the @FWEB{} style (`/*...*/' and `//'). It converts single-line comments to the `/*...*/' style and passes them along to the innards of the processors.
Problems sometimes arise when converting an existing FORTRAN code to @FWEB{}. Such codes may have very large blocks of code or documentation commented out with a `C' in column 1. Special TeX characters in those comments can cause problems for @FWEAVE{}; sometimes @FTANGLE{} gets confused as well. The `-nC' option short-circuits these problems by simply throwing all such lines away at the input driver stage.
This option is not a recommended long-term solution. Instead, consider the following:
- In @FWEB{}, blocks of code should be commented out with the preprocessor commands
@#if 0...@#endif; see section Temporary comments.- Textual comments for documentation should be converted to the standard @FWEB{} commenting style.
- If one has a block of code prefaced by an extremely long comment, replace that by a named module and put the comment into the TeX part of that section.
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].
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.
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.
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/'.
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.
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.
This option inhibits the operator-overloading feature invoked by the command `@v' (see section Overloading operators and identifiers).
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.}
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:
- `-p' options in `.fweb';
- entries in the local style file `fweb.sty';
- `-p' options on the command line.
See section LANGUAGES and section RATFOR. See also section `-L': Select global language.
See section LANGUAGES and section RATFOR. See also section `-L': Select global language.
This obscure option is used for configuring RATFOR (and really should be a style-file parameter). (Discussion not finished.)
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.
This is the negative of `-rk' (see section `-rk': Suppress comments about RATFOR translation (@FTANGLE{})); it forces comments about particular RATFOR commands.
Please don't use this option (it may not work). Insert semicolons by hand in your RATFOR code, just as one does in C.
Please don't use this option (it may not work). Insert semicolons by hand in your RATFOR code, just as one does in C.
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{}).
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].
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"
See the corresponding discussion of `-n)' in section `-n)': Reverse array indices [FORTRAN] (@FTANGLE{}).
`-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.
This is a family of options that set miscellaneous flags appropriate only for @FTANGLE{}.
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).
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.
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.
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.]
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.
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.
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.
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.
`-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.
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).
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).
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'.
@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:
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.'.
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.'.
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.
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.
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'.
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{})).
Equivalent to `->' (see section `->': Redirect output (@FTANGLE{})), and faster to type on many keyboards.
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.
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.
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].
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"
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.
All @FWEB{} commands begin with the character `@'. It is recommended that these begin in column 1 if possible. This is required in some cases [e.g., the `@x', `@y', and `@z' in change files (see section Change files), or column-oriented FORTRAN-77 processing].
Some of these control codes may be used anywhere; others begin a new part of the current section. (For a discussion of sections and parts, see section The structure of a web.) For a quick summary of the control-code mappings and to see which codes begin new parts, say `ftangle -@'. See section `-@': Display the control-code mappings.
Several commands provide localized versions of the `-1' and `-2' options related to debugging of pretty-printing.
This cancels the effect of a previous `@1' or `@2' (see section `@1': Display irreducible scraps and section `@2': Display detailed reductions of the scraps). The `@0' command should appear in a different section from the `@1' or `@2' commands.
This is a local version of the command-line option `-1' (see section `-1': Turn on brief debugging mode (@FWEAVE{})); refer to that discussion for more information.
This is a local version of the command-line option `-2' (see section `-2': Turn on verbose debugging mode (@FWEAVE{})); refer to that discussion for more information.
Several commands insert specific characters.
`@@' inserts the single character `@'.
Don't forget to double the `@' even inside strings. For example, the @FWEB{} source line
puts("'@@' is represented by `@@@@'");
will be tangled to
puts("'@' is represented by `@@'");
In the TeX (documentation) part of a section, `@|' inserts a vertical bar. This is useful inside LaTeX verbatim environments. (A simple bar would signal a shift into code mode, which is probably not what one wants.) For an example, see section `@|': Literal vertical bar, or optional line break.
In a code part, `@|' inserts an optional line break in an expression--e.g.,
`f(a,b,@|c+d,...)'.
This helps TeX to break the line at an appropriate place. If the line does not need to be broken, the command does nothing. [Compare `@|' with `@\' (see section `@\': Force a line break, then indent) and `@/' (see section `@/': Force a line break, preserving indentation.), which always break the line.]
Sections are begun by either `@*' or @ASP{}.
@ASP{} begins a new minor (unstarred or unnamed) section that is not entered into the Table of Contents. For example,
@ This is an example of a minor (unnamed) section. (No entry is made
in the Table of Contents.)
@a
main()
{}
`@*' begins a new major (starred) section (of level 0). The command must be followed by the name of the section (entry in the Table of Contents), followed by a period. (If a period appears in the name itself, it must be protected by braces.)
The section name is also used as a running head on the output pages. To deal with the possibility that the full name may be too long, the section name may be preceded by an optional argument enclosed in brackets. If it is present, the optional argument is used as the running head. (If a period appears as part of the optional argument, it must be protected by braces.)
If `@*' is followed by a digit n, it begins a new major (sub)section of level n. This is also entered into the Table of Contents. Thus, the complete syntax to begin a major section is
@*n [Short name]Full name.
For example,
@* MAIN PROGRAM. This begins a major section (of level 0).
@a
main()
{}
@*1 [Input routines\dots]A very long section name that essentially
means ``input routines.'' Now follow some subroutines.
@a
get_input()
{}
For LaTeX, the highest permissible major level is 2 (a subsubsection).
Section names can contain reasonably arbitrary TeX text, including font-changing commands and other macros. However, it is necessary to understand that fragile commands (in the sense of LaTeX) may not work because the section name is used in various contexts (e.g., as a page header). If a macro in a section name doesn't work properly, try preceding it with `\protect'.
@FWEAVE{} converts `@*' commands to section numbers. For a discussion of section numbering, see section Section numbering schemes.
The code part is begun by the appearance of either `@a' or `@< Module name @>='.
`@<' begins a module name, which has the form `@< TeX text @>'. (Module names inside @FWEB{} macro definitions begin with `@#', not `@<'.)
`@>' ends a module name, of the form `@< TeX text @>'.
Technically, `@>' is not a command; rather, it is a delimiter that terminates `@<'. An unmatched `@>' is simply ignored (after a warning message is issued).
`@A' begins the code part of an unnamed section. For example,
@ In an unnamed section, the code part begins with `@a' or `@A'.
@A
main()
{}
For more discussion of the distinction between `@A' and `@a', see section `@a': Begin code part of unnamed section, and mark.
`@a' begins the code part of an unnamed section (just as does `@A'), and in addition marks the next unreserved identifier it finds as defined in this section. Precisely,
`@a' == `@A@['
Originally, @FWEB{} did not contain the `@A' command, so when the functionality of automatically marking the next unreserved identifier (see section Forward referencing) was added, it was natural to add it to `@a'. A reasonable style of coding is to always use `@a' if you don't know any better; if you sometime run into trouble, you can then change selected `@a's to `@A's. For example, it is appropriate to use `@a' if one codes one function per section. E.g.,
@c
@
@a
int
subrtn()
{}
Here the `@a' marks `subrtn' as defined in this section; if that identifier is used elsewhere, it will be subscripted with the section number. (To turn this feature off, use `-f'; see section `-f': Turn off module references for identifiers (@FWEAVE{}).) However, if a section contains an arbitrary code fragment, the code part should probably begin with `@A'. E.g.,
@c @ @A x = y;
If one had used `@a' here, the x would have been marked as
defined here, which is not what one wants.
This is for detailed debugging of @FWEB{} codes. It inserts a left brace and suppresses the insertion of a breakpoint command. See the discussion of `@b' in section `@b': Insert a breakpoint command.
(Discussion to be finished. Useful only for very intimate debugging of @FWEB{} codes. In these days of safe sex, such intimacy may not be desirable.)
See also section Control codes b--z.
The command `@c' is a shorthand for `@Lc'. For a discussion of language commands in limbo, see section `@L': Set language.
See section LANGUAGES and section Special considerations for C.
The command `@c++' is a shorthand for `@Lc++'. For a discussion of language commands in limbo, see section `@L': Set language.
See section LANGUAGES and section Special considerations for C++.
This command begins the definition part.
`@D' defines an outer macro. For more discussion, see section Outer macros. For example, in C
@D A 1
will be tangled to the beginning of the output file as `#define A 1'.
This command begins the definition part.
`@d' defines an outer macro (just as `@D' does), and also marks the next identifier as defined in the present section. It is equivalent to
`@d' == `@D@['
(see section Forward referencing).
The distinction between `@d' and `@D' is analagous to the distinction between `@a' and `@A'. See section `@a': Begin code part of unnamed section, and mark.
For formatting purposes, treat the next identifier as an ordinary expression.
This command is useful in pretty-printing certain kinds of macro constructions. Further discussion is given in @xref{Macros and formatting}.
This command begins the definition part.
The construction
@f identifier old_identifier
makes @FWEAVE{} treat identifier like old_identifier. For example,
@f mytype int
says to treat the variable