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


CUSTOMIZATION

The default behavior of FWEB can be changed in a variety of ways.

  1. UNIX environment variables (logical variables in VMS) affect path or file names.
  2. An initialization file resides in the home directory.
  3. 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:

  1. Evaluate environment variables. See section Environment variables.
  2. Read `.fweb'. See section Initialization.
  3. Process `.fweb' options beginning with `-' (or `+', for backward compatibility), except for `-p'.
  4. Read and process command-line options, except for `-p'. See section Command-line options.
  5. Process remaining `.fweb' options (either file names, or options beginning with `&').
  6. Process any `-p' options from `.fweb'. See section `-p': Buffer up a style-file entry.
  7. Process the style file. See section The Style file.
  8. Process any `-p' options from the command line.

Environment variables

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.

Initialization

Although some aspects of FWEB's behavior are hard-coded, many can be changed and/or initialized by the user.

The initialization file

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.

Memory allocation

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

`-yb': Maximum bytes for identifiers, index entries, and module names

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.

`-ybs': Size of the change buffer, in bytes

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.

`-ycb': Size of line buffer for C output, in bytes

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.

`-ycf': Size of a Ratfor buffer, in bytes

The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by `-ycf' and `-ycg'.

`-ycg': Size of another Ratfor buffer, in bytes

The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by `-ycf' and `-ycg'.

`-yd': Increment for expanding the "dots" table

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.

`-ydt': Maximum number of deferred macro tokens

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': Maximum number of deferred macro texts

`-ydx' controls how many deferred macros are permitted. See also section `-ydt': Maximum number of deferred macro tokens.

`-yid': Maximum depth of file inclusion

Files included by `@i' can themselves contain `@i' commands, to a nesting level controlled by `-yid'.

`-yif': Maximum number of unique include-file names

The number of unique file names appearing in `@i' commands is controlled by `-yif'.

`-ykt': Stack size for FTANGLE

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

`-ykw': Stack size for FWEAVE

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': Line length for FWEAVE's output, in bytes

`-yll' controls the length of each line in the .tex file output by FWEAVE.

`-yln': Maximum length of module names or strings, in bytes

When each module name or string is parsed, it is stored temporarily in a buffer whose length is controlled by `-yln'.

`-ylb': Maximum number of nested loops in RATFOR

In RATFOR, various loops such as `while' are translated into their FORTRAN equivalents. `-ylb' controls the maximum nesting level of such expandable constructions.

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

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': Maximum number of sections

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

`-yma': Maximum number of arguments to FWEB macros

The maximum number of arguments to FWEB macros (defined by `@m') is limited by `-yma'.

`-ymb': Size of the buffer for expanding FWEB macros

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

`-yn': Maximum number of identifiers and module names

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.

`-ynf': Maximum number of open output files

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

`-yop': Maximum number of entries in the table for operator overloading.

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

`-yr': Maximum number of cross-references

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

`-ys': Maximum number of scraps

The maximum number of scraps is controlled by `-ys'. For a discussion of scraps, see section `-1': Turn on brief debugging mode (FWEAVE).

`-ysb': Size of style-file input-line buffer

The maximum length of each input line of the style file (fweb.sty by default) is controlled by `-ysb'.

`-ytt': Maximum number of tokens that FTANGLE can process

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

`-ytw': Maximum tokens in the current section being processed by FWEAVE.

Unlike FTANGLE, FWEAVE need only read in one section at a time. The maximum number of tokens in any section is controlled by `-ytw'.

`-yx': Maximum number of texts

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.

`-yxb': Size of line buffer for TeX and verbatim output

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.

The Style file

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

Customizing FWEAVE's index

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.

Customizing the module list

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.

Customizing the Table of Contents

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.

Customizing cross-reference subscripts

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

Customizing the behavior of `fwebmac.sty' macros

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.

Remapping control codes

Control-code remappings are sophisticated and unwise. They are mostly intended for the developer, so are not explained here.

Miscellaneous style-file parameters

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.

Automatic file name completion

For more information, see section `-e': Turn on automatic file-name completion.


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