Top
Node:Top ,
Next:Copying
NOTE: Because of last-minute 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.
Multitable is also giving trouble, as is "ATsamp" in section names. These
are probably problems with texi2html; sorry for the inconvenience.
FWEB
This Texinfo documentation describes FWEB Version 1.61.
To learn about new features of this version, see V1.61 .
For a quick introduction to, and review of the structure of an FWEB
source file, see Structure .
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-users
mailing list. Subscription instructions can be
found in Support .
Bug reports and suggestions are much appreciated, but are no longer
acknowledged individually. See 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
<http://w3.pppl.gov/~krommes/fweb_toc.html
>.
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 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 Intro . You
should also browse through Concepts , in particular
Structure .
Copying : Your rights; NO WARRANTY.
Intro : An introduction to FWEB .
Concepts : General concepts of WEB programming.
Files : Files used by FWEB .
Starting : Command-line syntax and options
@ commands : FWEB commands.
Comments : Commenting styles.
Languages : Languages.
Macros : Macro definitions and preprocessing.
Ratfor : RATional FORtran.
Documentation : Features and hints about working with FWEAVE .
Index : The index produced by FWEB .
Customization : Customizing FWEB , learning about parameters, etc.
Hints : Various usage tips, etc.
New features : New features/changes in the current version.
Support : Help, bug reports, etc.
Installing : Installing FWEB .
Concept index : Significant concepts.
Option and command index : Command-line options, @ commands, etc.
Parameter index : Style-file parameters.
--- The Detailed Node Listing ---
INTRODUCTION to FWEB
History : History of literate programming.
Features : Special features of FWEB .
WEB CONCEPTS
Processors : FTANGLE and FWEAVE .
Phases : Phases of operation of the FWEB processors.
Structure : The structure of a web.
Modules : Use of named and unnamed modules.
FILES
Input files : Input files.
Output files : Output files.
Change files : Change files.
Input files
Completion : Automatic file-name completion.
RUNNING FWEB
Syntax : Command-line syntax.
Options : Command-line options.
Command-line options
Negating options : How to invert the meaning of an option.
-1 : Brief debugging mode.
-2 : Verbose debugging mode.
-@ : Display information about control codes.
-A : Turn on ASCII translations.
-B : Turn off audible beeps.
-b : Number blocks.
-C : Set the color mode.
-c : Set global language to C.
-c++ : Set global language to C++.
-D : Display information about FWEB 's reserved words.
-d : Convert unnumbered `do...enddo's to Fortran--77.
-E : Change the delimiter of a file-name extension.
-e : Turn on automatic file-name completion.
-F : Compare output files with old versions.
-f : Turn off module references for identifiers.
-H : Scan #include files to format typedef and/or class commands.
-h : Where to get help.
-I : Append a directory to search list for include files.
-i : Don't print contents of @I include files.
-i! : Don't even read @I include files.
-j : Inhibit multiple includes of the same file.
-k : Don't recognize lower-case forms of Fortran I/O keywords.
-L : Select global language.
-l : Echo the input line.
-M : Set output message level.
-m : Define an FWEB macro.
-m4 : Understand the m4 built-in commands.
-m; : Append pseudo-semicolons to FWEB macro definitions.
-n : Set global language to Fortran--77.
-n9 : Set global language to Fortran--90.
-n@; : For Fortran, supply pseudo-semicolons automatically (default).
-n; : For Fortran, supply actual semicolons automatically.
-ncolon : In Fortran, place statement labels on separate lines.
-nb : In Fortran, number the ifs and dos.
-nC : In Fortran, ignore single-line comments ('C', 'c', or '*').
-np : Print semicolons in woven Fortran output.
-n\ : In Fortran--90, free-form syntax continued with '\\'.
-n& : In Fortran--90, free-form syntax continued with '&'.
-n/ : In Fortran, recognize '//' as the start of a short comment.
-n! : In Fortran, make '!' denote the start of a short comment.
-n) : In Fortran, reverse array indices.
-o : Turn off FWEAVE 's mechanisms for overloading operators.
-q : Don't translate Ratfor.
-P : Select TeX processor.
-p : Set style parameter.
-r : Set the global language to Ratfor--77.
-r9 : Set the global language to Ratfor--90.
-rb : In Ratfor, number the ifs and dos.
-rg : Set |goto| parameters.
-rk : Suppress comments about Ratfor statement translation.
-rK : Write out comments about Ratfor statement translation.
-r@; : Turn on Ratfor's auto-semi mode, using pseudo-semicolons.
-r; : Turn on Ratfor's auto-semi mode, using actual semicolons.
-r/ : In Ratfor, recognize '//' as the start of a short comment.
-r! : In Ratfor, make '!' denote the start of a short comment.
-r) : In Ratfor, reverse array indices.
-s : Print statistics about memory usage.
-T : Flag-setting commands for FTANGLE .
-t : Truncate identifiers.
-U : Convert reserved output tokens to lower case.
-u : Undefined a predefined or command-line macro.
-V : Print version number.
-v : Make all comments verbatim.
-W : Flag-setting commands for FWEAVE .
-w : Change name of FWEB 's macro package.
-X : Print selected cross-reference information.
-x : Reduce or eliminate cross-reference information.
-y : Allocate dynamic memory.
-Z : Display default values of style-file parameters.
-z : Change name of style file.
-. : Don't recognize dot constants.
-\ : Explicitly escape continued strings.
-( : Continue parenthesized strings with backslashes.
-colon : Set starting automatic statement number
-> : Redirect tangled output.
-= : Redirect tangled output.
-# : Don't print comments about line numbers and module names
in tangled output.
-+ : Don't interpret compound assignment operators.
-/ : Recognize '//' as the start of a short comment.
-! : Make '!' denoted the start of a short comment.
Info options : Information options.
-T
: Flag-setting options for FTANGLE
-TD : Permit processing of deferred macro definitions.
-Tb : Permit built-functions such as $IF
to be redefined.
-Tm : Permib user-defined macros to be redefined.
-Tv : Don't print header info at top of output.
-T% : Don't retain trailing comments.
-T# : Don't insert #line
command after @%
.
-W
: Flag-setting options for FWEAVE
-W@ : Set module warning flag.
-W1 : Completely cross-reference single-character identifiers.
-W[ : Turn on processing of bracketed array indices.
-WH : Send extra arguments to the C preprocessor.
Commands that inhibit printing:
-Wd : Don't print @d or @D in woven output.
-Wf : Don't print @f.
-WF : Don't print @F.
-Wl : Don't print @l.
-Wm : Don't print @m or @M.
-Wv : Don't print @v.
-Ww : Don't print @w or @W.
FWEB COMMANDS
@0 : Turn off debugging.
@1 : Display irreducible scraps.
@2 : Display detailed scrap reductions.
Literal control characters:
@@ : Insert an '@'.
@| : Vertical bar/optional line break.
Beginning of section:
@ : Begin minor section.
@* : Begin major section.
Beginning of code part:
@< : Begin module name.
@> : End module name.
@A : Begin code part.
@a : Begin code part and mark next identifier.
Control codes b--z:
@B : Insert left brace; suppress default insertion of breakpoint command.
@b : Insert breakpoint command.
@c : Set language to C.
@c++ : Set language to C++.
@D : Define outer macro.
@d : Define outer macro and mark it.
@E : Treat next identifier as ordinary expression.
@e : Invisible expression.
@f : Format identifier or module name.
@I : Include a WEB file, but don't print it.
@i : Include a WEB file.
@K : Expand global RCS-like keyword.
@k : Expand local RCS-like keyword.
@L : Set language.
@l : Specify limbo text.
@M : Define an FWEB macro.
@m : Define a FWEB macro and mark it.
@N : Turn on language-independent mode.
@n : Set language to Fortran--77.
@n9 : Set language to Fortran--90.
@O : Open new output file (global scope).
@o : Open new output file (local scope).
@q : Turn off or on module and line information locally.
@R : Treat next identifier as integer-like reserved word.
@r : Set language to Ratfor--77.
@r9 : Set language to Ratfor--90.
@u : Undefine an outer macro.
@v : Overload an operator.
@W : Overload an identifier.
@x : Terminate ignorable material.
@y : End first part of change.
@z : Begin ignorable material.
Conversion to ASCII:
@' : Convert single character to ASCII.
@" : Convert string to ASCII.
Forward referencing:
@[ : Mark next identifier as defined in this section.
Comments:
@/* : Begin a long verbatim comment.
@// : Begin a short verbatim comment.
@% : Ignore everything to next newline.
@? : Begin a compiler directive.
@( : Begin a meta-comment.
@) : End a meta-comment.
Special brace:
@{ : Insert left brace; suppress newlines in pretty-printing.
Index entries:
@_ : Force an index entry to be underlined (marked as defined).
@- : Delete index entry for following identifier.
@+ : Force index entry for following identifier.
@^ : Make index entry in Roman type.
@. : Make index entry in typewriter type.
@9 : Make index entry in format controlled by `\9'.
Control text:
@t : Put control text into TeX \hbox.
@= : Pass control text verbatim to the output.
Spacing:
@comma : Insert a thin space.
@/ : Insert a line break, preserving indentation.
@\ : Insert a line break and backspace.
@| : Insert optional line break in an expression.
@# : Force line break with blank line.
@~ : Cancel a line break (tie adjacent lines together).
@& : Join left and right items.
Pseudo (invisible) operators:
@e : Invisible expression.
@; : Invisible semicolon.
@colon : Invisible colon.
Miscellaneous:
@! : Inhibit expansion for next macro.
COMMENTING STYLES
Invisible comments : Skipping input material.
Visible comments : Comments in code mode.
Temporary comments : Temporarily commenting out code.
MACROS and PREPROCESSING
Outer macros : Macros copied to beginning of output file (@d).
FWEB macros : Macros and built-in functions expanded by FWEB (@m).
Macros and formatting : How to format macros for pretty-printing.
Preprocessing : FWEB 's preprocessing language (@#if, etc.)
FWEB macros
Macro features : Various points about FWEB macros.
Tokens : Special tokens used in FWEB macros.
Built-in functions : Macro-like functions built into FWEB .
Debugging with macros : Debugging glitches, and their solutions.
Various features of FWEB macros
Variable arguments : FWEB macros with variable arguments.
Recursion : FWEB macros may be recursive (proceed at your own risk).
Macro protection : Protecting FWEB macros against redefinition.
Built-in functions
Strings and quotes : Quoted and non-quoted strings.
Protection : By default, built-in functions may not be redefined.
INDIVIDUAL BUILT-IN FUNCTIONS
$A : Convert to ASCII.
$ABS : Absolute value.
$ASSERT : Assert a condition.
$AUTHOR : RCS global keyword; see $KEYWORD.
$COMMENT : Generate a comment.
$DATE : Today's date.
$DATE_TIME : RCS global keyword; see $KEYWORD.
$DAY : Today.
$DECR : Decrement a macro.
$DEFINE : Define a (deferred) macro.
$DO : Macro DO loop.
$DUMPDEF : Dump macro definitions to the terminal.
$E : Base of the natural logarithms: 2.71828...
$ERROR : Send error message to output.
$EVAL : Evaluate an expression.
$EXP : Exponential function.
$GETENV : Get value of environment variable.
$HEADER : RCS global keyword; see $KEYWORD.
$HOME : The user's home directory.
$ID : RCS global keyword; see $KEYWORD.
$IF : Two-way conditional: ``If expression is true''
$IFCASE : n-way conditional.
$IFDEF : Two-way conditional: ``If macro is defined''
$IFNDEF : Two-way conditional: ``If macro is not defined''
$IFELSE : Two-way conditional: ``If macro1 equals macro2''
$INCR : Increment a macro.
$INPUT_LINE : Line number that begins current section.
$KEYWORD : Extract text of global RCS-like keyword.
$L : Change string to lower case.
$L_KEYWORD : Extract text of local RCS-like keyword.
$LANGUAGE : Identifier for current language.
$LANGUAGE_NUM : Number of current language.
$LEN : Length of string.
$LOCKER : RCS global keyword; see $KEYWORD.
$LOG : Natural logarithm.
$LOG10 : Logarithm to the base 10.
$M : Define a (deferred) macro.
$MAX : Maximum of one or more elements.
$MIN : Minimum of one or more elements.
$MODULE_NAME : Name of present web
module.
$MODULES : Total number of independent modules.
$NAME : RCS global keyword; see $KEYWORD.
$OUTPUT_LINE : Current line number of tangled output.
$P : The C preprocessor symbol #
(an unquoted string).
$PI : 3.14159...
$POW : Raise to a power.
$PP : The C preprocessor symbol #
(a character).
$RCSFILE : RCS global keyword; see $KEYWORD.
$REVISION : RCS global keyword; see $KEYWORD.
$ROUTINE : Current Ratfor program, function, or subroutine.
$SECTION_NUM : Number of current section.
$SECTIONS : Maximum number of sections.
$SOURCE : RCS global keyword; see $KEYWORD.
$SQRT : Square root.
$STATE : RCS global keyword; see $KEYWORD.
$STRING : Expand argument, then stringize.
$STUB :
$TIME : The local time.
$TRANSLIT : Transliterate a string.
$U : Change string to upper case.
$UNDEF : Undefine an FWEB macro.
$UNQUOTE : Remove quotes from string (leaving an unquoted string).
$UNSTRING : Remove quotes and string delimiters from string.
$VERBATIM : (Obsolete.)
$VERSION : FWEB version number.
LANGUAGES
Setting the language : Setting the language.
Special hints and considerations for each language.
C : C
C++ : C++.
Fortran : Fortran--77 and Fortran--90.
Ratfor : RATional FORtran.
TeX : TeX.
Verbatim : Literal mode.
RATFOR
Syntax : Ratfor syntax.
Commands : Ratfor commands.
Caveats : Nuances about FWEB Ratfor.
DOCUMENTATION
Typesetting : Woven output; TeX vs. LaTeX, etc.
Pretty-printing : Turning ugly input into beautiful output.
Typesetting
Output : Structure of the TeX output from FWEAVE .
fwebmac.sty : The macro package used with FWEAVE .
LaTeX : Specifics of the LaTeX support.
The macro package fwebmac.sty
User macros : Macros defined for user convenience.
Fonts : Useful font commands.
LaTeX support
Document class : LaTeX's document class, options, etc.
REVTeX : The REVTeX scientific macro package.
Packages : Special FWEB-related LaTeX2e packages.
Sections : Section numbering, spacing, etc.
Index : Technical details about multi-columns and the Index.
Table of Contents : The Table of Contents.
Customizing LaTeX : Conditional flags, etc.
Inserting woven code : How to insert FWEAVE 's output into a LaTeX document.
LaTeX packages related to FWEB
fwebinsert : Enable insertion of woven code into a LaTeX document.
fwebnum : Number each section in ascending order.
idxmerge : Merge several stand-alone indexes.
Customizing LaTeX's output
Page references : Indexing by page numbers.
Headers : The content of page headers.
Numbering : Various section numbering schemes.
Pretty-printing
Alternatives : Alternatives for various input tokens.
Pseudo-operators : Invisible parts of speech.
Overloading : Changing the appearance of various quantities.
FWEB 's INDEX.
Internal index : The self-contained index produced by FWEB .
Using makeindex : Writing index data for use by makeindex
.
Merging indexes : Using the idxmerge
utility to merge indexes.
CUSTOMIZATION
Environment variables : Environment or logical variables.
Initialization : Initialization file.
Memory allocation : Dynamic memory allocation.
Style : Style file.
Memory allocation
-yb : Maximum bytes for identifiers, index entries, and module names.
-ybs : Size of the change buffer.
-ycb : Size of line buffer for C output.
-ycf : A Ratfor buffer.
-ycg : Another Ratfor buffer.
-yd : Increment for expanding the dots table.
-ydt : Maximum number of deferred macro tokens.
-ydx : Maximum number of deferred macro texts.
-yid : Maximum depth of file inclusion.
-yif : Maximum number of unique include-file names.
-ykt : Stack size for FTANGLE .
-ykw : Stack size for FWEAVE .
-yll : Line length for FWEAVE 's output.
-yln : Maximum length of module names or strings.
-ylb : Maximum number of nested loops in Ratfor.
-ylx : Maximum length of expressions that can be expanded with
the post-increment operators of Fortran or Ratfor.
-ym : Maximum number of sections.
-yma : Maximum number of arguments to FWEB macros.
-ymb : Size of the buffer for expanding FWEB macros.
-yn : Maximum number of identifiers and module names.
-ynf : Maximum number of open output files.
-yop : Maximum number of entries in the table for operator
overloading.
-yr : Maximum number of cross-references.
-ys : Maximum number of scraps.
-ysb : Size of style-file input-line buffer.
-ytt : Maximum number of tokens that FTANGLE can process.
-ytw : Maximum number of tokens in the current section being
processed by FWEAVE .
-yx : Maximum number of texts.
-yxb : Size of line buffer for TeX output.
The Style file
Index params : Customizing the Index.
Module params : Customizing the list of sections.
Contents params : Customizing the Table of Contents.
Subscript params : Customizing subscripting for cross-references.
Fwebmac params : Customizing behavior of FWEB 's macros.
Completion params : Automatic selection of file extensions, etc.
Control-code mappings : Remapping FWEB 's control codes (danger)!
Color : FWEB 's color output.
Miscellaneous params : Other customizations.
Customizing FWEAVE 's index
delim_0 : Insert after identifier in index entry.
delim_n : Insert between section numbers in index entry.
encap.infix : Start the section number.
encap.prefix : TeX macro to begin a section number.
encap.suffix : Ends the section number.
group_skip :
index.collate : Collating sequence for the Index.
index.postamble : TeX material to end the Index.
index.preamble : TeX material to begin the Index.
index.tex : Name of file holding the Index.
item_0 : TeX command to begin an index entry.
language.prefix : Begin a language entry in the Index.
language.suffix : End a language entry in the Index.
lethead.prefix : Begin a letter group.
lethead.suffix : End a letter group.
lethead.flag : Control beginning of letter group.
name : Name of index.
underline.prefix : Begin an underlined index entry.
underline.suffix : End an underlined index entry.
Customizing the module list
modules.info :
modules.postamble : TeX commands to end module list.
modules.preamble : TeX commands to begin module list.
modules.tex : Name of file containing list of modules.
Customizing the Table of Contents
contents.postamble : TeX commands to end Table of Contents.
contents.preamble : TeX commands to begin Table of Contents.
contents.tex : Name of contents file.
Customizing cross-reference subscripts
mark_defined.generic_name :
mark_defined.fcn_name :
mark_defined.WEB_macro :
mark_defined.outer_macro :
mark_defined.exp_type :
mark_defined.typedef_name :
Customizing the behavior of fwebmac.sty
macros
doc.preamble : Preamble for entire document.
doc.postamble : Postamble for entire document.
format_IDENTIFIER : Macro name for typesetting upper-case identifiers.
format.reserved : Macro for reserved words.
format.short_identifier : Macro for single-character identifiers.
format_OUTER_MACRO : Macro for upper-case @d
identifiers.
format.outer_macro : Macro for lower-case @d
identifiers.
format_WEB_MACRO : Macro for upper-case @m
identifiers.
format.WEB_macro : Macro for lower-case @m
identifiers.
format.intrinsic : Macro for intrinsic library functions.
format_KEYWORD : Macro for upper-case keywords.
format.keyword : Macro for lower-case keywords.
format.typewriter : Macro for strings.
format.wildcard : Macro for user-defined index entries.
indent.TeX : Paragraph indentation for TeX part.
indent.code : Paragraph indentation for code part.
LaTeX.class : Specify the document class.
LaTeX.class.options : Specify options for document class.
LaTeX.package : Specify user package(s)
LATeX.package.options : Specify options for user package(s).
Miscellaneous style-file parameters
ASCII_fcn : Routine for converting strings to ASCII.
cchar : Continuation character for Fortran.
cdir_start : ?
translates to this.
line_char : Comment char. for FTANGLE 's line
cmds.
line_length :
paren.len : Length of one parenthesized index for -n)
.
paren.levels : Number of nested parentheses for -n)
.
paren.num : Number of permitted indices for -n)
.
meta.top : Material to precede tangled meta-comment.
meta.prefix : Begins each line of meta-comment.
meta.bottom : Material that follows the meta-comment.
meta.top.hdr : Like meta.top, but for info at start of file.
meta.prefix.hdr : As above.
meta.bottom.hdr : As above.
outer.def : FTANGLE converts @d
to this.
outer.undef : FTANGLE converts @u
to this.
protect : Protection character to end a continued line.
suffix : Suffixes for output files.
For FWEAVE :
macros : Default name of the macro package to be
read in by FWEAVE .
limbo.begin : Default material to begin the limbo section.
limbo.end : Default material to end the limbo section.
meta.code.begin :
meta.code.end :
meta.TeX.begin : TeX material to begin FWEAVE 's
output of a meta-comment.
meta.TeX.end : As above, but end the meta-comment.
preamble.named : TeX material to begin named section.
preamble.unnamed : TeX material to begin unnamed section.
For both processors:
dot_constant.begin : Beginning character for dot constant.
dot_constant.end : Ending character for dot constant.
null_file : Name of the null file.
Automatic file name completion
Ext.web : Extensions for the web file.
Ext.ch : Extensions for the change file.
Ext.hweb : Extensions for include files.
Ext.hch : Extensions for change files associated with
include files.
USAGE TIPS and SUGGESTIONS
Converting : Converting an existing code to FWEB .
Tips : Usage tips and suggestions.
Science : Useful features for scientific programming.
NEW FEATURES
V1.61 :
V1.53 :
V1.52 :
V1.50 :
V1.40 :