2.3 Options

FunnelWeb's options are internal parameters which can be modified by corresponding arguments on FunnelWeb's command line. A description of each argument and option follows.

B1...B6: Tracedumps: These six options have been provided to assist in the debugging and testing of FunnelWeb. They determine which of six possible trace dumps are to be written to the listing file. Only the boolean attributes of these options are ever used. The six dumps are identified by the digits 1..6 as follows:

1. Dump a hexdump of each mapped input and include file.
2. Dump the global line list created by the scanner.
3. Dump the token list created by the scanner.
4. Dump the macro table created by the parser.
5. Dump the document list created by the parser.
6. Dump a table summarizing CPU and real time usage.

Because these options are so closely related, a hack has been pulled to enable them to all to be controlled by the B argument. The string argument to the B argument determines which of the six options are to be affected by the sign. Examples: +B134 turns on options B1, B3, and B4. -B1 turns off option B1. Default: -B123456.

B7: Determinism: If the B7 option is turned on, FunnelWeb suppresses the output of anything non-deterministic, or machine dependent. This assists in regression testing. Only the boolean attribute is used in this option. This option is controlled by the B7 argument which falls under the same argument syntax as the other B options. Examples: +B7, -B7. Default: -B7.

C: Listing File Context: The C option is always turned on and cannot be turned off. Its only attribute is a number which determines the number of lines of context that the lister will place around lines flagged with diagnostics in the listing file (if a listing file is written). A value of 100 indicates infinite context which means that the entire listing file will be written out if a single diagnostic occurs. The value of this number can be specified by specifying it as a string of decimal digits to the +C argument. Examples: +C100, +C10. Default: +C2.

D: Delete Identical Output Files: Only the boolean attribute of this option is used. When turned on, the option causes the suppression (deletion) of product files and documentation files (but not listing or journal files) that are identical to the currently existing files of the same name. For example, if FunnelWeb is instructed to generate stack.h as an product file, and the text to be written to stack.h is identical to the currently existing stack.h, then FunnelWeb will simply not write any product file, leaving the currently existing stack.h as it is (and in particular leaving the file's date attribute the same). This prevents unnecessary make propagations. For example, in a C program, if stack.fw is a FunnelWeb input file that generates stack.h and stack.c, a modification to stack.fw that affects stack.c but does not affect stack.h will not provoke the recompilation of modules that #include stack.h, so long as the intervening FunnelWeb run has +D set. Examples: -D, +D. Default: -D.

F: FunnelWeb Input File: If this option is turned on, FunnelWeb processes the input file whose name is specified by the option string. Examples: +Fsloth.fw, +Fwalrus, -F. Default: -F.

H: Display Help Message: If this option is turned on, FunnelWeb displays the message specified by the argument string. Each message has a name. The main help message is called "menu" and contains a list of the other help messages. Examples: +Hregistration, +Hoptions. Default: -Hmenu.

I: Include default file specification: This option is always turned on and cannot be turned off. Its string attribute is used as the default file specification for include files. Usually this option is used to specify a directory from which include files should be obtained. Examples: =I/usr/dave/includes/. Default: +I.

J: Journal File: If this option is turned on, FunnelWeb generates a journal file. A journal file contains a log of all the console input and output to FunnelWeb during a single invocation of the FunnelWeb program (Note: The Q option does not affect this.). The journal file is particularly useful for examining what happened during a FunnelWeb shell run. The string attribute is the name of the journal file. Examples: +Jjournfile, -J. Default: -J.

K: Keyboard: If this option is turned on, FunnelWeb enters an interactive mode in which the user can enter FunnelWeb shell commands interactively. The string attribute is unused. Examples: +K, -K. Default: -K.

L: Listing File: If this option is turned on, FunnelWeb generates a listing file containing a summary of a run on FunnelWeb proper. The string argument is the name of the listing file to be created. Examples: +L, -L, +Llisting.lis. Default: -L.

O: Product Files: If this option is turned on, FunnelWeb generates a product file for each macro in the input file that is bound to an output file. The string attribute contributes to the name of the product files. This option is controlled by the O argument because product files used to be called "Output files"). Examples: -O, +O/usr/dave/product/. Default: +O.

Q: Quiet: If this option is turned on, FunnelWeb suppresses all output to the screen (standard output) unless one or more errors occur, in which case a single line summarizing the errors is sent to standard output at the end of the run. If this option is turned off, FunnelWeb writes to the console in its normal garrulous way. The string attribute is unused in this option. Examples: -Q, +Q. Default: -Q.

S: Screen: If this option is turned on, FunnelWeb writes all diagnostics to the screen (standard output) as well as to the listing file. By default, they are sent only to the listing file. This option has a single numerical attribute that can be specified as a decimal string in the string component of the S argument. The number is the number of lines of context that should surround each diagnostic sent to the screen. Examples: -S, +S6, +S0. Default: -S.

T: TeX Documentation file: If this option is turned on, FunnelWeb generates a documentation file in TeX format. The string argument contributes to the name of the documentation file to be created. By default this option is turned off, as experience has shown that most FunnelWeb runs are made during program development; documentation runs occur far more rarely. This option is controlled by the T command line argument because documentation files used to be called typesetter files. Examples: -T, +Tsloth.tex. Default: -T.

U: HTML Documentation file: If this option is turned on, FunnelWeb generates a documentation file in HTML format. The string argument contributes to the name of the documentation file to be created. By default this option is turned off, as experience has shown that most FunnelWeb runs are made during program development; documentation runs occur far more rarely. U was chosen for this feature because it follows T, and H and W were already allocated to other functions. Examples: -U, +Usloth.html. Default: -U.

W: Width of Product Files: If this option is turned on, a limit is placed on the length of lines in product files generated during the run. Lines that breach the limit are flagged with error messages. This option has a single numerical attribute that can be specified as a decimal string in the string component of the W argument. The number is the specified maximum width. This option is one of two limits that are placed on the width of product files. The other limit is an attribute of the input file that defaults to 80 characters, but can be raised or lowered using an output line length pragma. The width that is enforced is the lower of this value and the value of the W option (if turned on). Examples: -W, +W100. Default: -W80.

X: Execute: If this option is turned on, FunnelWeb executes the FunnelWeb shell script file specified by the string attribute. Examples: +Xmaster, -X. Default: -X.