The default behavior of @FWEB{} can be changed in a variety of ways.
- UNIX environment variables (logical variables in VMS) affect path or file names.
- An initialization file resides in the home directory.
- A style file resides in the current directory.
The initialization file (usually called `.fweb') is intended to contain command-line options (one per line) that are to be used in every run. See section Initialization.
The style file (called `fweb.sty' by default; see section `-z': Change name of style file) is intended to provide more local customization, perhaps differing for each source file and group of source files. The style file does not contain command-line options; rather, it contains parameter settings that override @FWEB{}'s defaults. The `-p' option (see section @samp{-p}: Buffer up a style-file entry) may be used to specify a style-file entry in `.fweb' (i.e., a global value for all source files) or on the command line (i.e., a value used for a single run).
The order of processing is:
- Evaluate environment variables. See section Environment variables.
- Read `.fweb' and remember its contents; sort those into three groups: options beginning with `-', beginning with `&', and beginning with a letter (file names) . See section Initialization.
- Process `.fweb' options beginning with `-' (or `+', for backward compatibility), except for `-p'.
- Read and process command-line options, except for `-p'. See section Command-line options.
- Process remaining `.fweb' options (either file names, or options beginning with `&').
- Process any `-p' options from `.fweb'. See section `-p': Buffer up a style-file entry.
- Process the style file. See section The Style file.
- Process any `-p' options from the command line.
Unfortunately, because not all options are processed immediately when they are read, errors may not show up when one expects. For example, nothing is actually processed while `.fweb' is being read; its contents are just being stored. It could therefore happen that a syntax error in entering a `-p' option in `.fweb' may not be reported until after the style file has been read, possibly confusing the user as to the source of the error.
FWEB_HDR_INCLUDES
-- Colon-delimited list of directories for the
C preprocessor (in the form of gcc
) to
search for `#include' header files. This is used in conjunction
with the `-H' option; see section `-H': Scan C/C++ include files (@FWEAVE{}). (One can append to this list
by means of the `-I' option, provided that option comes
after the `-H'; see section `-I': Append to search list for include files.)
FWEB_INCLUDES
-- Colon-delimited list of directories to search for
`@i' include files. (One can append to this list by means of the
`-I' option, provided that option comes before any use of
`-H'; see section `-I': Append to search list for include files.)
FWEB_INI
-- Name of the initialization file. If not defined, either
`.fweb' or `fweb.ini' is chosen, depending on the machine. The
initialization file always resides in $HOME
.
FWEB_STYLE_DIR
-- Directory in which the style file resides. If not
defined, the current directory is used.
Although some aspects of @FWEB{}'s behavior are hard-coded, many can be changed and/or initialized by the user.
On startup, @FWEB{} attempts to read an initialization file. This always
resides in the user's home directory. It is usually called `.fweb'
(`fweb.ini' on personal computers). The default file name can be
overridden by the environment variable FWEB_INI
.
One may put into `.fweb' any option that might be used as a command-line option. (Presently, there must be just one entry per line.) If the option begins with a `-' (or a `+' for backward compatibility), it is processed before the actual command-line options; if it begins with `&' or is a file name, it is processed after. Generally, `.fweb' options should begin with `-' so that one may override them from the command line. The `%' sign begins a comment terminated by the end-of-line.
The command-line option `-y' (see section `-y': Allocate dynamic memory) is used to change the default allocation for a dynamic array. The arrays have a one- or two-character abbreviation denoted by aa. Some error messages will use this abbreviation when suggesting that one increase a default allocation. To query the present allocations of variable aa, just say `-yaa'. To query everything, say `-y'.
This whole scheme is somewhat annoying. In most cases, dynamic arrays should be reallocated automatically. That can be done without too much difficulty, but I was reluctant to try it for Version 1.61 in fear of breaking something. Please wait for the year 2000.
If one uses `-y' to examine the maximum permitted values of these parameters, one will note the magic number 10239 appearing occasionally. This number is a bit less than 64K/5; it is a signature of an inherently 32-bit design that goes back to Knuth. Unfortunately, this number can't be increased without some radical redesign. Wait for the year 2100.
Unique identifiers, index entries, and module names are stored contiguously in a large memory area, the size of which is controlled by `-yb'. The default may need to be increased for very large source files, or decreased to squeeze things into a personal computer. See also section `-yn': Maximum number of identifiers and module names.
Information from change files is read into the change buffer, whose size is controlled by `-ybs'. It should not be necessary to change this unless an error message specifically tells one to do so.
@FTANGLE{} outputs lines of a fixed maximum length. It attempts to split them in a reasonable way, dependent on the language. When it absolutely can't figure out how to split the line, it will issue a warning message and split it anyway. The `-ycb' option controls the maximum output line length for C and C++.
The analogous command `-yxb' controls the output line length for TeX and the verbatim mode. See section `-yxb': Size of line buffer for TeX and verbatim output.
The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by `-ycf' and `-ycg'.
The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by `-ycf' and `-ycg'.
The "dots" table is used for FORTRAN to hold information relating to "dot" operators such as `.NE.'. In FORTRAN--90, additional such operators can be added by the program, so the table can grow dynamically. The `-yd' option controls how many additional entries are made available each time the table size needs to be reallocated.
Deferred @FWEB{} macros are ones defined in the code part rather in the definition part. (Their use is normally prohibited; see section `-TD': Permit processing of deferred macro definitions.) `-ydt' controls how many bytes are set aside for the storage of these replacement text of those macros. See also section `-ydx': Maximum number of deferred macro texts.
`-ydx' controls how many deferred macros are permitted. See also section `-ydt': Maximum number of deferred macro tokens.
Files included by `@i' can themselves contain `@i' commands, to a nesting level controlled by `-yid'.
The number of unique file names appearing in `@i' commands is controlled by `-yif'.
@FTANGLE{} uses a stack to deal with the web of module names--i.e., a named section can refer to another module name. The size of this stack is controlled by `-ykt'.
@FWEAVE{}'s stack handles the possibilities that code mode can be embedded in a module name, or vice versa. The maximum nesting level for such mode changes is controlled by `-ykw'.
`-yll' controls the length of each line in the .tex
file
output by @FWEAVE{}.
When each module name or string is parsed, it is stored temporarily in a buffer whose length is controlled by `-yln'.
In RATFOR, various loops such as `while' are translated into their FORTRAN equivalents. `-ylb' controls the maximum nesting level of such expandable constructions.
FORTRAN and RATFOR can expand expressions such as `x(i) += dx' into their FORTRAN counterparts such as `x(i) = x(i) + dx'. It does so in a very straightforward way, by copying the expression to the left of the equals sign. `-ylx' controls the maximum size of that expression.
`-ym' limits the maximum number of sections, both named and unnamed. (Each unnamed section is counted separately.) The absolute maximum number of sections is 10239, probably one of the most stringent restrictions in @FWEB{}'s design. (This number is a bit less than 1/5 of 64K.)
The maximum number of arguments to @FWEB{} macros (defined by `@m') is limited by `-yma'.
The expansion of each @FWEB{} macro is done in a buffer whose size is controlled by `-ymb'. (In some situations, particularly in RATFOR, more than one such buffer can be open at once.)
A structure is associated with each unique identifier and module name. The maximum number of such structures is controlled by `-yn'. See also section `-yb': Maximum bytes for identifiers, index entries, and module names.
In addition to @FTANGLE{}'s usual output file--e.g.,
test.c
---additional files may be opened by means of the
`@O' (see section `@O': Open output file (global scope)) or `@o' (see section `@o': Open output file (local scope)) commands.
Depending on the situation, some of these files may remain open
simultaneously. The maximum number of such files is controlled by `-ynf'.
In @FWEAVE{}, the appearance of an operator can be changed (overloaded) by means of the `@v' command (see section `@v': Overload operator). Each such operator is entered into a table, the maximum size of which is controlled by `-yop'.
The Index cross-reference information (in which sections each identifier is used or defined) is maintained in a large array of structures, one structure for each cross-reference. The maximum number of cross-references is controlled by `-yr'.
The maximum number of scraps is controlled by `-ys'. For a discussion of scraps, see section `-1': Turn on brief debugging mode (@FWEAVE{}).
The maximum length of each input line of the style file (fweb.sty
by default) is controlled by `-ysb'.
A token is an identifier, numerical constant, operator, etc. @FTANGLE{} must read in and store all tokens in the entire source file, because they can be output in a different order than they are input. The maximum number of tokens is controlled by `-ytt'.
Unlike @FTANGLE{}, @FWEAVE{} need only read in one section at a time. The maximum number of tokens in any section is controlled by `-ytw'.
For @FTANGLE{}, a text is either the replacement text of a macro, or the contents of a named section. The maximum number of such texts is controlled by `-yx'.
For @FWEAVE{}, a text is a phrase that arises from combining primitive scraps during the translation stage of phase 2.
For both processors, the absolute maximum number of texts is 10239.
This option is like `-ycb' (see section `-ycb': Size of line buffer for C output, in bytes), but controls the size of the output line for the TeX (`@Lx') and verbatim (`@Lv') languages.
A style file (default name `fweb.sty') may reside in the
user's current directory (or the directory specified by the environment
variable FWEB_STYLE_DIR
). The default name can be changed by the
command-line option `-z' (see section `-z': Change name of style file).
The style file is processed after all command-line options have been processed, except that the command-line option `-p' (see section `-p': Buffer up a style-file entry) gets special treatment. Note that that option buffers up style-file entries (i.e., one may use more than one `-p' option). `-p' options placed in `.fweb' are treated as residing in a temporary file that is read just before the local style file; thus, those behave as `global' style-file entries that will be overridden by a matching entry in the local style file. `-p' options on the command line will be processed after the local style file, thus override corresponding options in either `.fweb' or the local style file. To summarize the previous discussion, the local style file is intended to contain settings that are common to a particular source file. Settings common to all source files can be put into `.fweb' by means of the `-p' option. To override a setting for a single run, use a `-p' option on the command line.
Style-file entries have the form
keyword [=] value
The equals sign is always optional. The `value' is usually a double-quoted string, but may sometimes be an integer or a single-quoted character. For example,
LaTeX.class.options = "twoside" LaTeX.package "indentfirst,multicol" mark_defined.fcn_name 0 line_char.N 'C' color.error = "red" Color.red = "\e[01;31m"
The syntax is completely free-form. Periods within keywords are precisely equivalent to underscores, but are useful heuristically for associating a structure-like hierarchy to some of the commands. Non-printable characters in strings can be specified as octal constants (e.g., `\033'), hexadecimal constants (e.g., `\x1B'), or one of the ANSI escape sequences `\a', `\b', `\f', `\n', `\r', `\t', and `\v'. The non-ANSI escape sequence `\e' (escape) is also supported; that is particularly useful for color processing (see section Color output).
Various of the style-file parameters take a language subscript. Those are
C
- C
Cpp
- C++
N
- FORTRAN-77
N90
- FORTRAN-90
R
- RATFOR-77
R90
- RATFOR-90
V
- Verbatim
X
- TeX
Thus, line_char.N
is the comment character for @FTANGLE{}'s
line
commands (see section line_char.l
(@FTANGLE{})), for FORTRAN-77 code.
Unfortunately, the descriptions of the parameters aren't all completed yet. To query the default values, say `ftangle -Z' (see section `-Z': Display default style-file parameters).
In the following, `???' denotes the name of various subparameters.
index.???
index.name
is the name of the index section. This string is used
in \Wbegin
to initialize the TeX macro \INDEX
. The
index section is recognized by matching, for a starred section, the
actual section name against the contents of \INDEX
. When they
match, a new page and two-column mode are begun. These rules imply that
the last section of one's source file can be titled `\INDEX', as in
@* \INDEX.
index.tex
is the name of the file into which the Index is
written. The character `#' is translated into the root name of the web
file, as for example `#.ndx'.
index.preamble
are TeX commands that begin the Index.
index.postamble
are TeX commands that end the Index.
index.collate
specifies the collating sequence for the Index.
delim_?
delim_0
is the string to insert after the identifier in an index
entry.
delim_n
is the string to insert between two section numbers in an
index entry.
group_skip
group_skip
is a string of TeX commands to insert between
letter groups.
item_0
item_0
is the TeX command to begin an index entry.
language.???
language.prefix
begins a language entry.; language.suffix
ends one.
lethead.???
lethead.prefix
begins a letter group; lethead.suffix
ends
one. The flag lethead.flag
controls the format of the letter
group: if it is zero, nothing is inserted; if it is positive, an
upper-case letter is inserted; if it is negative, a lower-case letter is
inserted.
underline.???
underline.prefix
is the TeX command to begin an underlined
index entry.
underline.suffix
is the TeX command to end an underlined index
entry.
modules.tex
is the name of the file into which the module names
are written.
modules.preamble
is a string of TeX commands to begin the list
of modules.
modules.postamble
is a string of TeX commands to end the list
of modules.
modules.info
is the name of the TeX macro that formats the
command line and related information.
contents.tex
is the name of the file into which the Table of
Contents is written.
contents.preamble
is the TeX string that begins printing the
Table of Contents.
contents.postamble
is the TeX string that ends the Table of
Contents.
When @FWEAVE{} pretty-prints code, it can attach cross-reference subscripts to various kinds of identifiers such as function or macro names. [A bullet for a subscript indicates that the name was defined in the current section.] The actual marking of the cross reference is done by the command `@[' (see section Forward referencing). This is usually done implicitly; for example, the commands `@a', `@d', and `@m' issue an implicit `@['. (See the discussion of `@a' in section `@a': Begin code part of unnamed section, and mark.) In C, various declarations of variables also result in such an implicit mark.
Various nuances in the type (possibly underlined) used for the subscript give a hint about what kind of identifier @FWEAVE{} thinks it's working with. For more information about the typesetting conventions, see the definition of the primitive macro `\W@IN' in `fwebmac.web'.] The following flags select which identifiers are so subscripted.
To see the default values of these parameters, say `ftangle -Zmark_defined'. To turn off the subscripting operations completely, use the `-f' option (see section `-f': Turn off module references for identifiers (@FWEAVE{})).
To some extent, the behavior of @FWEB{}'s macro package `fwebmac.sty' can be changed by means of the following parameters. (Please try not to actually edit `fwebmac.sty' itself; it is produced automatically from `fwebmac.web'. And please don't edit that file either!)
format.???
The format
parameters are strings that specify the macro to be
used to pretty-print various kinds of identifiers. These macro names
are usually written automatically by @FWEAVE{}, but they may also be
used directly by the user in the TeX documentation. One can see
their default values by typing `ftangle -Zformat.'. For example,
the default value for format.typewriter
is "\\."
.
The macro names defined by the format
fields are not
defined in `fwebmac.sty'. They are dummy names, and can be
changed to any other name not already in use without affecting the
operation of @FWEB{}. This ability is necessary because other
packages might usurp macros like \.
for their own purposes.
Thus, @FWEAVE{} normally writes out the macro \.
to typeset a
string. Suppose, however, that some user package uses \.
for
something else. (One might realize this when LATEX crashes
when it encounteres a \.
that was written automatically by
@FWEAVE{}.) To fix this problem, put into `fweb.sty' the lines
format_KEYWORD = "\\WTT" format_keyword = "\\WTT" format_typewriter = "\\WTT"
Here \WTT
can be any name not already in use; you need not (and
should not) give a definition for \WTT
.
Macros like \.
or \WTT
are given their values during the
execution of the \Wbegin
macro that begins the output from
@FWEAVE{}. The style-file values are written as arguments to that
macro, and essentially a command like \let\.\Wtypewriter
is
executed, where the internal macro \Wtypewriter
is defined in
`fwebmac.sty'. If you want to change the way @FWEB{} typesets a
particular kind of identifier, you must redefine the internal
macro name, not the one used in the format
parameters.
Here are the internal macros used by `fwebmac.sty' to typeset the various kinds of identifiers. The associated style-file parameters are shown in parentheses.
\Wid
- ordinary identifiers (
format.id
)\WID
- completely upper-case ordinary identifiers (
format.ID
)\Wshort
- single-character ordinary identifiers (
format.short_id
)\WidD
- outer macros (
format.outer_macro
)\WIDD
- completely upper-case outer macros (
format.outer_macro
)\WidM
- FWEB macros (
format.WEB_macro
)\WIDM
- completely upper-case FWEB macros (
format.WEB_macro
)\Wreserved
- reserved words (
format.reserved
)\WRESERVED
- completely upper-case reserved words (
format.RESERVED
)\Wintrinsic
- library/intrinsic function names (
format.intrinsic
)\Wkeyword
- certain Fortran keywords (
format.keyword
)\WKEYWORD
- completely upper-case keywords (
format.KEYWORD
)\Wtypewriter
- character strings (
format.typewriter
)
indent.???
indent.TeX
specifies paragraph indentation for the TeX part.
indent.code
specifies similar indentation for the code part.
LaTeX.???
For LaTeX2e, the default document class can be overridden by
LaTeX.class
. The default class is article
, and @FWEB{}
has not been tested with other document classes, except minimally with
revtex
(see section Using REVTeX).
Options to the document class can be specified by
LaTeX.class.options
.
User packages can be given by LaTeX.package
.
Options to user packages can be specified by
LaTeX.package.options
. There may be just one
LaTeX.package
command and just one LaTeX.package.options
command. If it is necessary to issue multiple such commands, then put
them into doc.preamble
. See the discussion in section LaTeX's document class.
When running under LaTeX prior to LaTeX2e (or with REVTeX; see
section Using REVTeX), the document is
(effectively) begun by the command
\documentstyle[options]{style}
. The options field can be
specified by LaTeX.options
; the style field by
LaTeX.style
.
Control-code remappings are sophisticated and unwise. They are mostly intended for the developer, so are not explained here.
In the design of @FWEB{}, provision has been made for writing various
messages to the terminal in color--e.g., serious error messages might
appear in red. This feature was motivated by the color ls
of Linux.
It is installed automatically if the termcap
library is present.
Messages output from @FWEB{} are ranked according to an internal message-type table; each type can be associated with a color that can be changed in the style file. Presently, the message types (hopefully self-explanatory) are
ordinary program_name mod_name info warning error fatal mod_num line_num in_file include_file out_file timing
The associated style-file parameters are the above names prefaced by
`color.'---e.g., color.warning
. Each of those has a default
value, such as color.error = "red"
. Those defaults can be
displayed by saying `ftangle -Zcolor'.
What the color actually means in practice depends on the color mode, set by the `-C' option (see section `-C': Set the color mode). That selects one of several primitive palettes, as follows:
- 0
- No color; ordinary black-and-white output. This is the default (and the mode used when the
termcap
library is not present).- 1
- ANSI color. With a color terminal that supports ANSI color escape sequences, one has available the following colors:
"black"
,"red"
,"green"
,"yellow"
,"blue"
,"magenta"
,"cyan"
,"white"
, and"default"
. These are displayed with bold attribute (that is, bright, not dim). `"default"' stands for the usual black on white background, or vice versa.- 2
- Bilevel. This is for terminals that don't support true color, but do support a double-bright mode and reverse video. Colors are mapped onto various combinations of those two display attributes, according to an internally defined scheme. For example,
"red"
is mapped onto the pair of escape sequences `md', `mr' (double-bright mode in reverse video).- 3
- Trilevel. As above, but adds underlining capability.
- 4
- User-defined colors. This implements a minimal set of defaults. It is intended that the user add definitions in the style file to override those defaults.
The mechanism is intended to work with systems that support the
termcap
library. The terminal is controlled by writing
appropriate escape sequences to it. The style-file parameters that
store the escape sequences are the color name preceded by `Color.'
(note the upper case `C')---e.g., `Color.red'. For cases like
reverse video (standard termcap abbreviation `mr'), the escape
sequences are determined by querying the termcap database (usually
`/etc/termcap') through the termcap
library functions. For
ANSI color (color mode = 1), ANSI escape sequences are hard-coded into
@FWEB{}. One can see the escape sequences @FWEB{} assigns to colors by
saying `ftangle -ZColor'.
For any non-zero color mode, one can override @FWEB{}'s default choices
for color mappings and escape sequences by redefining one or more of the
Color
parameters in the style file. The escape sequences can
either be specified in raw form--e.g., for color mode = 1, a
default is Color.red = "\e[01;31m"
---or in the form of a sequence
of two-character abbreviations that are defined in the termcap
documentation--e.g., for modes 2 and 3, the default is Color.red
= "mdmr"
. (When one displays that with the `-Z' option, @FWEB{}
will display the actual escape sequences that it determines from the termcap
database, not the abbreviations. For both input and output, note that
one may use the non-ANSI escape sequence `\e' to represent the
escape character `\033'.)
When one says `-ZColor', for color modes 1--3 all of the parameters are listed as modified, even if the user redefines none. That occurs because the defaults are overwritten internally when the color mode is set.
@FWEB{}'s configuration script attempts to determine whether the termcap
library is present; if not, they link in dummy termcap routines
(`termcap0.web'). To override this behavior, change the
appropriate lines in `defaults.mk', produced by the command
./configure
.
Color message output is not fully debugged (it's a frill, after all), so some messages that should reasonably be colored may not be so in the present release.
There are a variety of miscellaneous parameters.
ASCII_Fcn
See section `@"': Convert string to ASCII.
cchar
Continuation character for FORTRAN code output.
cdir_start
This parameter has the form cdir_start.l
, where l is one of
`C', `Cpp', `N', `N90', `R', `R90',
`X', or `V'. The contents of this parameter is written
immediately after the `@?' that begins a compiler directive.
line_char.l
(@FTANGLE{})
By default, @FTANGLE{} outputs comments indicating line numbers in the
web
file from which the tangled output comes. (This information
can be used by debuggers, especially those for C and C++, to correlate
error messages to the web
source.) The line_char
parameter sets the comment character that begins the line comment.
line_length.l
(@FTANGLE{})This parameter is used by the FORTRAN-like languages to control the length of the output line in the `.f' file produced by @FTANGLE{}. For FORTRAN-77, its default value is the venerable 72. For FORTRAN-90, its default is 73. Using that value makes it possible to generate code that is compatible with both fixed- and free-form format (by continuing lines with an trailing ampersand in column 73 and another ampersand in column 6 of the next line).
meta.???.?
, meta.???.hdr.?
(@FTANGLE{})
These parameters customize the treatment of meta-comments.
Fundamentally, meta-comments consist of material enclosed by
`@(...@)'. The header information usually written at the top of
the file output by @FTANGLE{} (see section @samp{-Tv}: Don't print header info) is also treated as a
meta-comment. For that header material, a separate set of parameters is
provided, such as meta.top.hdr
.
meta.top.l
specifies text that precedes material enclosed by
`@(...@)'. Here l is one of the standard language subscripts
(see section The Style file) such as N90
.
meta.prefix.l
begins each line of the meta-comment.
meta.bottom.l
specifies text that follows the meta-comment.
outer.???
@FTANGLE{} converts `@d' (see section @samp{@d}: Define outer macro, and mark) to outer.def
, and
`@u' (see section `@u': Undefine outer macro) to outer.undef
.
protect.?
The strings protect.l
specify the protection character(s) to end
a continued line.
suffix.?
The extension for the files output by @FTANGLE{} is specified by
suffix.l
.
macros
The default name of the macro package to be read in. [This is usually `fwebmac.sty' (see section The macro package `fwebmac.sty'), but can be overridden by the command-line option `-w'; see section `-w': Change name of macro package (@FWEAVE{}).]
limbo.begin
, limbo.end
`limbo.begin' is TeX material to be printed at the beginning of the limbo section, just before the text from `@l' commands. See section `@l': Specify limbo text. (This command was previous called just `limbo', and that still works.)
Similarly, `limbo.end' is printed at the end of the limbo section.
Thus, the beginning of the file output by @FWEAVE{} looks like this:
\input fwebmac.sty \Wbegin{...} [contains \documentclass, \usepackage, <doc.preamble>, \begin{document}] <limbo.begin> [contents of any @l commands] [user's TeX commands from the limbo section] <limbo.end>
The `limbo.end' command is useful for printing the entire document in two-column format. For more discussion, see section LaTeX's index..
meta.???
(@FWEAVE{})preamble.???
Additional TeX material can be inserted at the beginning of a named
section with preamble.named
and at the beginning of an unnamed
one with preamble.unnamed
.
dot_constant.???.?
In FORTRAN, `dot' constants such as .LT.
are begun and ended by
periods. In special circumstances, the beginning and ending characters
may be modified by dot_constant.begin.l
and
dot_constant.end.l
.
null_file
The name of the null file or device. For more discussion, see section Change files.
For more information, see section `-e': Turn on automatic file-name completion.
Go to the first, previous, next, last section, table of contents.