FWEB

 

Next: , Previous: , Up: (dir)   [Contents][Index]

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.

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  

Next: , Previous: , Up: (dir)   [Contents][Index]