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. The style file does not contain command-line options; rather, it contains parameter settings that override FWEB's defaults. The `-p' option (see section `-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'. 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.
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 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'.
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, these 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'
The syntax is completely free-form. Periods within keywords are precisely equivalent to underscores, but are useful for associating a structure-like hierarchy to some of the commands.
Unfortunately, the descriptions of the parameters aren't all completed yet. To query the default values, say `ftangle -Z'.
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.)
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, 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.
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.
meta.???.?
(FTANGLE)
meta.top.l
specifies text that precedes material enclosed by
`@(...@)'.
meta.prefix.l
begins each line of the meta-comment.
meta.bottom.l
specifies text that follows the meta-comment.
outer.???
FTANGLE converts `@d' to outer.def
, and `@u' 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)(To be finished.)
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.