File: fweb.texi

package info (click to toggle)
fweb 1.62-3
links: PTS
area: main
in suites: slink
size: 4,504 kB
ctags: 5,148
sloc: ansic: 40,448; makefile: 388; sh: 170
file content (12264 lines) | stat: -rw-r--r-- 419,141 bytes
parent folder | download | duplicates (7)
\input texinfo   @c -*-texinfo-*-
@def@ifhtml{@doignore{ifhtml}}
@setfilename fweb.info
@settitle FWEB

@macro Fprog{name}
@sc{\name\}
@end macro

@macro FWEB
@Fprog{Fweb}
@end macro

@macro FWEAVE
@Fprog{Fweave}
@end macro

@macro FTANGLE
@Fprog{Ftangle}
@end macro

@macro ASP
@iftex
@tex`\hbox{\tt@@\char`\ }'@end tex
@end iftex
@ifinfo
@w{@samp{@@ }}@c
@end ifinfo
@end macro

@macro PI
@tex
$\pi$
@end tex
@ifinfo
@var{pi}@c
@end ifinfo
@end macro

@macro EQUIV
@tex
$\equiv$
@end tex
@ifinfo
==@c
@end ifinfo
@end macro


@
@ifinfo
     This file documents FWEB...
     
        Copyright 1993--1998 John A. Krommes
     
     Permission is granted to make and distribute verbatim
     copies of this manual provided the copyright notice and
     this permission notice are preserved on all copies.
     
@c     @ignore
     Permission is granted to process this file through TeX
     and print the results, provided the printed document
     carries a copying permission notice identical to this
     one except for the removal of this paragraph (this
     paragraph not being relevant to the printed manual).
     
@c     @end ignore
     Permission is granted to copy and distribute modified
     versions of this manual under the conditions for
     verbatim copying, provided also that the section
     entitled ``Copying'' is included exactly as in the original, and provided
     that the entire resulting derived work is distributed
     under the terms of a permission notice identical to this
     one.
     
     Permission is granted to copy and distribute
     translations of this manual into another language,
     under the above conditions for modified versions,
     except that this permission notice may be stated in a
     translation approved by the author.
@end ifinfo

@titlepage
@title FWEB
@subtitle A WEB system of structured documentation 
@subtitle for multiple languages
@author By John A. Krommes
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993--1998 John A. Krommes

     Permission is granted to make and distribute verbatim
     copies of this manual provided the copyright notice and
     this permission notice are preserved on all copies.
     
     Permission is granted to copy and distribute modified
     versions of this manual under the conditions for
     verbatim copying, provided also that the section
     entitled ``Copying'' is included exactly as in the original, and provided
     that the entire resulting derived work is distributed
     under the terms of a permission notice identical to this
     one.
     
     Permission is granted to copy and distribute
     translations of this manual into another language,
     under the above conditions for modified versions,
     except that this permission notice may be stated in a
     translation approved by the author.
@end titlepage


@node Top,Copying,(dir),(dir)

@ifhtml
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 @samp in section names.  These
are probably problems with texi2html; sorry for the inconvenience.
@end ifhtml

@unnumbered @FWEB{}

This Texinfo documentation describes @FWEB{} Version 1.61.


@quotation

@itemize @bullet
@item
To learn about new features of this version, see @ref{V1.61}.  

@item
For a quick introduction to, and review of the structure of an @FWEB{}
source file, see @ref{Structure}. 

@item
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 @code{fweb-users} mailing list.  Subscription instructions can be
found in @ref{Support}.

@item
Bug reports and suggestions are much appreciated, but are no longer
acknowledged individually.  See @ref{Support}.

@item
The next major release, @FWEB{} Version 2.00, is planned for
no earlier than January 1, 2000.

@end itemize
@end quotation

@ifinfo
If you're perusing this documentation for the first time, try first
reading the discussion at just the top-level nodes in order to get a
general sense of what's here.  Lower-level nodes have many details, but
most of them are unnecessary for the casual user.

One can obtained a TeX'd copy of the present documention by saying
@samp{texi2dvi fweb.texi}, assuming that the relevant @code{texinfo}
macros have been installed on one's system. (@file{texinfo.tex} and the
script @code{texi2dvi} are included in the standard GNU distributions.)
@end ifinfo

This documentation is now accessible on the World-Wide Web from

@quotation
@url{http://w3.pppl.gov/~krommes/fweb_toc.html}.
@end quotation

Other sources of information about @FWEB{} are the archival files of
the @code{fweb-users} and @code{fweb-installers} mailing lists.  To
learn how to obtain those, see @ref{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 @ref{Intro}.  You
should also browse through @ref{Concepts}, in particular
@ref{Structure}.

@ifinfo
   The first part of this master menu lists the major nodes in this Info
document.  The rest of the menu lists all of the lower-level nodes in
the document.
@end ifinfo

@menu
* 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: AT 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.
* -@@: -AT.      Display information about control codes.
* -A: -A_.      Turn on ASCII translations.
* -B: -B_.      Turn off audible beeps.
* -b::          Number blocks.
* -C: -C_.      Set the color mode.
* -c::          Set global language to C.
* -c++: -cpp.   Set global language to C++.
* -D: -D_.      Display information about @FWEB{}'s reserved words.
* -d::          Convert unnumbered `do...enddo's to Fortran--77.
* -E: -E_.      Change the delimiter of a file-name extension.
* -e::          Turn on automatic file-name completion.
* -F: -F_.	Compare output files with old versions.
* -f::          Turn off module references for identifiers.
* -H: -H_.      Scan #include files to format typedef and/or class commands.
* -h::          Where to get help.
* -I: -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: -L_.      Select global language.
* -l::          Echo the input line.
* -M: -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@@;: -nAT;. 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: -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: -rK_.    Write out comments about Ratfor statement translation.
* -r@@;: -rAT;. 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: -T_.      Flag-setting commands for @FTANGLE{}.
* -t::          Truncate identifiers.
* -U: -U_.      Convert reserved output tokens to lower case.
* -u::          Undefined a predefined or command-line macro.
* -V: -V_.      Print version number.
* -v::          Make all comments verbatim.
* -W: -W_.      Flag-setting commands for @FWEAVE{}.
* -w::          Change name of @FWEB{}'s macro package.
* -X: -X_.      Print selected cross-reference information.
* -x::          Reduce or eliminate cross-reference information.
* -y::          Allocate dynamic memory.
* -Z: -Z_.      Display default values of style-file parameters.
* -z::          Change name of style file.
* -.::          Don't recognize dot constants.
* -\::          Explicitly escape continued strings.
* -(: -lp.      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.
* -+: -plus.    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.

@samp{-T}:  Flag-setting options for @FTANGLE{}

* -TD::         Permit processing of deferred macro definitions.
* -Tb::         Permit built-functions such as @code{$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 @samp{#line} command after @samp{@@%}.        

@samp{-W}:  Flag-setting options for @FWEAVE{}

* -W@@: -WAT.            Set module warning flag.
* -W1::                 Completely cross-reference single-character identifiers.
* -W[::                 Turn on processing of bracketed array indices.
* -WH: -WH_.            Send extra arguments to the C preprocessor.

Commands that inhibit printing:

* -Wd: -Wnoprint.       Don't print @@d or @@D in woven output.
* -Wf: -Wnoprint.       Don't print @@f.
* -WF: -Wnoprint.       Don't print @@F.
* -Wl: -Wnoprint.       Don't print @@l.
* -Wm: -Wnoprint.       Don't print @@m or @@M.
* -Wv: -Wnoprint.       Don't print @@v.
* -Ww: -Wnoprint.       Don't print @@w or @@W.

@FWEB{} COMMANDS

* @@0: AT0.     Turn off debugging.
* @@1: AT1.     Display irreducible scraps.
* @@2: AT2.     Display detailed scrap reductions.

Literal control characters:
* @@@@: ATAT.     Insert an '@@'.
* @@|: AT|.      Vertical bar/optional line break.

Beginning of section:
* @@ : ATspace.  Begin minor section.
* @@*: AT*.      Begin major section.

Beginning of code part:
* @@<: AT<.      Begin module name.
* @@>: AT>.      End module name.
* @@A: ATA_.     Begin code part.
* @@a: ATa.      Begin code part and mark next identifier.

Control codes b--z:
* @@B: ATB_.      Insert left brace; suppress default insertion of breakpoint command.
* @@b: ATb.      Insert breakpoint command.
* @@c: ATc.      Set language to C.
* @@c++: ATcpp.  Set language to C++.
* @@D: ATD_.     Define outer macro.
* @@d: ATd.      Define outer macro and mark it.
* @@E: ATE_.     Treat next identifier as ordinary expression.
* @@e: ATe.      Invisible expression.
* @@f: ATf.      Format identifier or module name.
* @@I: ATI_.     Include a WEB file, but don't print it.
* @@i: ATi.      Include a WEB file.
* @@K: ATK_.     Expand global RCS-like keyword.
* @@k: ATk.      Expand local RCS-like keyword.
* @@L: ATL_.     Set language.
* @@l: ATl.      Specify limbo text.
* @@M: ATM_.     Define an @FWEB{} macro.
* @@m: ATm.      Define a @FWEB{} macro and mark it.
* @@N: ATN_.     Turn on language-independent mode.
* @@n: ATn.      Set language to Fortran--77.
* @@n9:ATn9.     Set language to Fortran--90.
* @@O: ATO_.     Open new output file (global scope).
* @@o: ATo.      Open new output file (local scope).
* @@q: ATq.      Turn off or on module and line information locally.
* @@R: ATR_.     Treat next identifier as integer-like reserved word.
* @@r: ATr.      Set language to Ratfor--77.
* @@r9: ATr9.    Set language to Ratfor--90.
* @@u: ATu.      Undefine an outer macro.
* @@v: ATv.      Overload an operator.
* @@W: ATW_.     Overload an identifier.
* @@x: ATx.      Terminate ignorable material.
* @@y: ATy.	 End first part of change.
* @@z: ATz.      Begin ignorable material.

Conversion to ASCII:
* @@': ATquote.     Convert single character to ASCII.
* @@": ATdquote.         Convert string to ASCII.

Forward referencing:
* @@[: AT[.         Mark next identifier as defined in this section.

Comments:
* @@/*: AT/*.        Begin a long verbatim comment.
* @@//: AT//.        Begin a short verbatim comment.
* @@%: AT%.          Ignore everything to next newline.
* @@?: AT?.          Begin a compiler directive.
* @@(: ATlp.         Begin a meta-comment.
* @@): AT).          End a meta-comment.

Special brace:
* @@@{: ATlb.       Insert left brace; suppress newlines in pretty-printing.

Index entries:
* @@_: AT_.         Force an index entry to be underlined (marked as defined).
* @@-: AT-.         Delete index entry for following identifier.
* @@+: ATplus.      Force index entry for following identifier.
* @@^: AT^.         Make index entry in Roman type.
* @@.: ATdot.       Make index entry in typewriter type.
* @@9: AT9.         Make index entry in format controlled by `\9'.

Control text:
* @@t: ATt.         Put control text into TeX \hbox.
* @@=: AT=.         Pass control text verbatim to the output.

Spacing:
* @@comma: ATcomma. Insert a thin space.
* @@/: AT/.         Insert a line break, preserving indentation.
* @@\: ATbs.         Insert a line break and backspace.
* @@|: AT|_.        Insert optional line break in an expression.
* @@#: AT#.         Force line break with blank line.
* @@~: AT~.         Cancel a line break (tie adjacent lines together).
* @@&: AT&.         Join left and right items.

Pseudo (invisible) operators:
* @@e: ATe.         Invisible expression.
* @@;: AT;.         Invisible semicolon.
* @@colon: ATcolon.     Invisible colon.

Miscellaneous:
* @@!: AT!.         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 @b{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 @code{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 @code{#} (an unquoted string).
* $PI::                 3.14159...
* $POW::                Raise to a power.
* $PP::                 The C preprocessor symbol @code{#} (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++: Cpp.             C++.
* Fortran::             Fortran--77 and Fortran--90.
* Ratfor: Ratfor_.      RATional FORtran.
* TeX::                 @TeX{}.
* Verbatim::            Literal mode.

@sc{Ratfor}

* Syntax: RSyntax.      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 @file{fwebmac.sty}

* User macros:: Macros defined for user convenience.
* Fonts::       Useful font commands.

La@TeX{} support

* Document class::	LaTeX's document class, options, etc.
* REVTeX::              The REV@TeX{} scientific macro package.
* Packages::            Special FWEB-related La@TeX{}2e packages.
* Sections::	        Section numbering, spacing, etc.
* Index:LIndex.         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 La@TeX{} document.

La@TeX{} packages related to @FWEB{}

* fwebinsert:Inserting woven code. Enable insertion of woven code into a La@TeX{} document.
* fwebnum:Numbering.              Number each section in ascending order.
* idxmerge:Merging indexes.       Merge several stand-alone indexes.

Customizing La@TeX{}'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 @code{makeindex}.
* Merging indexes::     Using the @code{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: S_delim.             Insert after identifier in index entry.
* delim_n: S_delim.             Insert between section numbers in index entry.

* encap.infix: S_encap.         Start the section number.
* encap.prefix: S_encap.        @TeX{} macro to begin a section number.
* encap.suffix: S_encap.        Ends the section number.

* group_skip::

* index.collate: S_index.       Collating sequence for the Index.
* index.postamble: S_index.     @TeX{} material to end the Index.
* index.preamble: S_index.      @TeX{} material to begin the Index.
* index.tex: S_index.           Name of file holding the Index.

* item_0::                      @TeX{} command to begin an index entry.

* language.prefix: S_language.  Begin a language entry in the Index.
* language.suffix: S_language.  End a language entry in the Index.

* lethead.prefix: S_lethead.    Begin a letter group.
* lethead.suffix: S_lethead.    End a letter group.
* lethead.flag: S_lethead.      Control beginning of letter group.

* name: S_index.                Name of index.

* underline.prefix: S_underline. Begin an underlined index entry.
* underline.suffix: S_underline. End an underlined index entry.

Customizing the module list

* modules.info: S_modules.
* modules.postamble: S_modules. @TeX{} commands to end module list.
* modules.preamble: S_modules.  @TeX{} commands to begin module list.
* modules.tex: S_modules.       Name of file containing list of modules.

Customizing the Table of Contents

* contents.postamble: S_contents. @TeX{} commands to end Table of Contents.
* contents.preamble: S_contents.  @TeX{} commands to begin Table of Contents.
* contents.tex: S_contents.       Name of contents file.

Customizing cross-reference subscripts

* mark_defined.generic_name: S_mark_defined.
* mark_defined.fcn_name: S_mark_defined.
* mark_defined.WEB_macro: S_mark_defined.
* mark_defined.outer_macro: S_mark_defined.
* mark_defined.exp_type: S_mark_defined.
* mark_defined.typedef_name: S_mark_defined.

Customizing the behavior of @file{fwebmac.sty} macros

* doc.preamble: S_LaTeX.        Preamble for entire document.
* doc.postamble: S_LaTeX.       Postamble for entire document.

* format_IDENTIFIER: S_format.  Macro name for typesetting upper-case identifiers.
* format.reserved: S_format.    Macro for reserved words.
* format.short_identifier: S_format. Macro for single-character identifiers.
* format_OUTER_MACRO: S_format. Macro for upper-case @samp{@@d} identifiers.
* format.outer_macro: S_format. Macro for lower-case @samp{@@d} identifiers.
* format_WEB_MACRO: S_format.   Macro for upper-case @samp{@@m} identifiers.
* format.WEB_macro: S_format.   Macro for lower-case @samp{@@m} identifiers.
* format.intrinsic: S_format.   Macro for intrinsic library functions.
* format_KEYWORD: S_format.     Macro for upper-case keywords.
* format.keyword: S_format.     Macro for lower-case keywords.
* format.typewriter: S_format.  Macro for strings.
* format.wildcard: S_format.    Macro for user-defined index entries.

* indent.TeX: S_indent.         Paragraph indentation for @TeX{} part.
* indent.code: S_indent.        Paragraph indentation for code part.

* LaTeX.class: S_LaTeX.         Specify the document class.
* LaTeX.class.options: S_LaTeX. Specify options for document class.
* LaTeX.package: S_LaTeX.         Specify user package(s)
* LATeX.package.options: S_LaTeX. 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::                  @samp{@?} translates to this.
* line_char::                   Comment char. for @FTANGLE{}'s @code{line} cmds.
* line_length: S_line_length.

* paren.len: -n).               Length of one parenthesized index for @samp{-n)}.
* paren.levels: -n).            Number of nested parentheses for @samp{-n)}.
* paren.num: -n).               Number of permitted indices for @samp{-n)}.

* meta.top: S_meta_t.           Material to precede tangled meta-comment. 
* meta.prefix: S_meta_t.        Begins each line of meta-comment.
* meta.bottom: S_meta_t.        Material that follows the meta-comment.

* meta.top.hdr: S_meta_t.       Like meta.top, but for info at start of file.
* meta.prefix.hdr: S_meta_t.    As above.
* meta.bottom.hdr: S_meta_t.    As above.

* outer.def: S_outer.           @FTANGLE{} converts @samp{@@d} to this.
* outer.undef: S_outer.         @FTANGLE{} converts @samp{@@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: S_limbo.         Default material to begin the limbo section.
* limbo.end: S_limbo.           Default material to end the limbo section.

* meta.code.begin: S_meta_w.
* meta.code.end: S_meta_w.

* meta.TeX.begin: S_meta_w.     @TeX{} material to begin @FWEAVE{}'s 
                                                output of a meta-comment.
* meta.TeX.end: S_meta_w.       As above, but end the meta-comment.

* preamble.named: S_preamble.   @TeX{} material to begin named section.
* preamble.unnamed: S_preamble. @TeX{} material to begin unnamed section. 

For both processors:

* dot_constant.begin: S_dot_constant.   Beginning character for dot constant.
* dot_constant.end: S_dot_constant.     Ending character for dot constant.

* null_file::                   Name of the null file.

Automatic file name completion

* Ext.web: S_Ext.        Extensions for the web file.
* Ext.ch: S_Ext.     Extensions for the change file.
* Ext.hweb: S_Ext.       Extensions for include files.
* Ext.hch: S_Ext.    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::
@end menu

@node Copying, Intro, Top, Top
@comment  node-name,  next,  previous,  up

@unnumbered @FWEB{} Copying Permissions

@FWEB{} is ``free.''  This means that everyone is free to use them and free to
redistribute them on a free basis.  @FWEB{} operates under the terms
of the GNU General Public License; see, for example, 
@ref{Distrib, , Distribution, emacs, The GNU Emacs Manual}.

Although it is hoped that @FWEB{} will be useful, 
there is @emph{ABSOLUTELY NO WARRANTY}.  

@node Intro, Concepts, Copying, Top
@comment  node-name,  next,  previous,  up

@chapter INTRODUCTION to @FWEB{}

@cindex Literate programming
@FWEB{} is a system for @dfn{literate programming}.  It enables one to
maintain both documentation and source code in a single place (the
@code{web} file), and to explain the code in terms of a @dfn{web} of
very small fragments.  Because @FWEB{} is intimately integrated with
@TeX{}, one gains many advantages such as book-quality typesetting and
extensive cross-referencing facilities.  A simple example program is
described in @ref{Structure}.


@FWEB{} was originally intended for scientific programming (the 'F'
stands for @sc{Fortran}), and is in wide use in that arena; however, it
has much broader applicability.  It is an extension of Knuth's WEB
system that handles the specific languages C, C++, Fortran (both F77 and
F90), @sc{Ratfor}, and (in a limited fashion) @TeX{} itself.  It also
attempts to implement a WYSIWYG language-independent mode as well as a
(closely-related but not identical) verbatim `language'.  @emph{The
language-independent features are highly experimental} and are not
recommended. 

The origins and philosophy of literate programming are described in the
very enjoyable book by D. E. Knuth, @cite{Literate Programming} (Center for
the Study of Language and Information, Leland Stanford Junior
University, 1992).

Knuth's original WEB 
@pindex WEB
was written in Pascal, and it formatted Pascal code.
Silvio Levy introduced @sc{Cweb}, 
@pindex CWEB
a WEB system written in C for C.  @FWEB{} 
@pindex FWEB
is a
(by now, substantial) modification of version 0.5 of @sc{Cweb} that was
graciously supplied by Levy.  It also borrows various ideas from the
works of Ramsey and Briggs on language-independent webs.

The original WEB's worked with Plain @TeX{}.  More recently, many users
have turned to Lamport's La@TeX{} because of its ease of use and
higher-level features.  Excellent and extensive development of La@TeX{} has been
accomplished, as described by Goossens, Mittelbach, and Samarin, @cite{The
La@TeX{} Companion} (Addison--Wesley, Reading, MA, 1994). 
The present version of @FWEB{} is intended to be used with
La@TeX{} (La@TeX{}2e, in particular); Plain @TeX{} is no longer supported.

@menu
* History::             History of literate programming.
* Features::            Special features of @FWEB{}.
@end menu

@node History, Features, Intro, Intro
@comment  node-name,  next,  previous,  up

@section History of WEB and literate programming
(To be completed; see Knuth's book, cited in @ref{Intro}.)

@node Features, , History, Intro
@comment  node-name,  next,  previous,  up

@section Features of @FWEB{}

@FWEB{} is distinguished from its relatives in several respects:

@quotation
@itemize @bullet
@item
@FWEB{} introduces the concept of a @emph{current language}
(@pxref{Languages}), so more than one compiler language can be processed
in a single @FWEB{} run.  For example, mixtures of C++ and
@sc{Fortran} are common in modern scientific programming.

@item
@FWEB{} understands the syntaxes of several of the more important
compiler languages: C, C++, @sc{Fortran} (both F77 and F90),
@sc{Ratfor}, and @TeX{}.  For other languages, @FWEB{} can work in a
language-independent mode that essentially weaves and tangles the source
code verbatim, but still provides the user with the powerful @sc{web}
features related to @sc{TeX} documentation, module names, macro
processing, etc.

@item
@FWEB{} contains a built-in @sc{Ratfor} (@sc{RATional} @sc{FORtran})
translator.  @xref{Ratfor}.

@item
@FWEB{} has a built-in C-like @emph{macro preprocessor}.  This is
especially useful for @sc{Fortran} and @sc{Ratfor}, which have no predefined
preprocessor.  However, certain extensions such as variable numbers of arguments
make the @FWEB{} preprocessor sometimes useful even for C and C++.
@xref{Macros} and @ref{Preprocessing}.

@item
Many aspects of @FWEB{}'s behavior, default strings, etc. can be
customized by means of setting parameters in a @code{makeindex}-like
@emph{style file} (by default, @file{fweb.sty}).  @xref{Style}.

@end itemize
@end quotation

@node Concepts, Files, Intro, Top
@comment  node-name,  next,  previous,  up

@chapter WEB CONCEPTS

The principle concepts of @sc{WEB} programming are laid out in Knuth's book,
the reference to which was given in @ref{Intro}.  @FWEB{} follows most
conventions introduced by @sc{web} and @sc{Cweb}, except that the names
of some commands have been changed for consistency, symmetry, and/or
clarity.

@menu
* 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.
@end menu

@node Processors, Phases, Concepts, Concepts
@comment  node-name,  next,  previous,  up

@section The @FWEB{} processors:  @FWEAVE{} and @FTANGLE{}

@cindex Processors, @FWEB{}
Following Knuth's original design, @FWEB{} consists of two processors,
@FTANGLE{} and @FWEAVE{}.  Both operate on a single source file, say
@file{test.web}.  @FTANGLE{} produces compilable code, say @file{test.c},
whereas @FWEAVE{} produces a @TeX{} file, @file{test.tex}, that can
(in principle) be processed with either @TeX{} or La@TeX{}.  (If a file
@file{test.tex} already exists, @FWEAVE{} will ask for confirmation
before overwriting it if it does not think that the file was created by
a previous run of @FWEAVE{}.)

The output file produced by @FTANGLE{} is not intended for human eyes
(or for editors!); it is for compiling only.  All changes to the code
should be made to the @code{web} file, since changes made directly to
the output file would be overwritten the next time the @code{web} source
is tangled.  In an attempt to discourage messing with @FTANGLE{}'s
output file, all unnecessary spaces are deliberately removed.

@cindex Makefiles, using
A common way of integrating @FWEB{} into ones program development is to
do all compilations through a @code{make} file, into which one puts an
extra dependency line that explains how to produce the compilable output
file from the @code{web} source.  For example,

@example
test.c: test.web
        ftangle test

test.o: test.c
        gcc -c test test.c
@end example
@noindent
With this approach, one is not so tempted to edit @file{test.c}.

@FWEB{} development is now based on La@TeX{}; Plain @TeX{} is no longer
supported.  For detailed descriptions of the La@TeX{} support, see @ref{LaTeX}.


@node Structure, Modules, Phases, Concepts
@comment  node-name,  next,  previous,  up

@section The structure of a web

@cindex Web, structure
An @FWEB{} source file is structured into @dfn{sections}, which
correspond to logical subunits of the code (either a function or a
fragment of a function).
@cindex Sections
Each section consists of three @dfn{parts}, each of which is optional:
@cindex Parts
@cindex Part, @TeX{}
@cindex Part, definition
@cindex Part, code
the

@quotation
@enumerate
@item
@TeX{} part;

@item
definition part; and

@item
code part.
@end enumerate
@end quotation
@noindent
When @FTANGLE{} outputs code, it can combine
the code parts of (possibly noncontiguous) sections into
larger units called @dfn{modules}, as explained in @ref{Modules}.

With the aid of sections, one's possibly huge and logically complex code
can be broken down into bite-sized pieces, each one easily
comprehensible.  Since sections may correspond to only a small part of a
function or subroutine, 1000-line main programs (they still exist!)
should become a thing of the past.

Since sections can be combined into modules, there is no
need for sections that must be physically contiguous in the output file
to be contiguous in the source file.  This allows for great flexibility
in structuring the documentation of the code.

@subsubsection A simple example

@cindex Example, of @FWEB{} file
A simple example of an @FWEB{} source file consisting of three sections is as
follows:

@example
@group
@@n/ % Set FWEB language to Fortran, and recognize short // comments.

\Title@{example.web@} % \Title is an FWEB TeX macro.
\author@{J. A. Krommes@} % \author is a LaTeX macro.

@@* INTRODUCTION. 
This code is intended to illustrate the use of the |write| statement.
It also provides a simple example of the \FWEB\ macro preprocessor.

@@m A_CONSTANT 1.2345 // \FWEB\ preprocessor macro definition.

@@a
        program main
        call compute
        end

@@ The computational routine is pretty boring.
@@a
        subroutine compute
        write(*,*) 'Macro value = ', A_CONSTANT
        end

@@* \INDEX.
@end group
@end example

Commands to @FWEB{} are begun by the @samp{@@} symbol (@pxref{AT
commands}).  In this example, the first command, @samp{@@n}, sets the
global language to @sc{Fortran}-77.  One should always begin one's code
with a language-setting command.  

In this example, the language command is invoked with an optional
argument @samp{/}.  That is necessary in @sc{Fortran} in order to tell
@FWEB{} to use the short (single-line) comment form beginning with
@samp{//}, which otherwise conflicts with the concatenation operator.  
@xref{-n/}. 

For more information about languages, see @ref{Languages}.  For a fuller
discussion of optional arguments, see @ref{Setting the language}.

@findex @@*
@cindex Sections, named
@cindex Sections, unnamed
The @samp{@@*} command begins a @dfn{major} or @dfn{named section}
(corresponding to La@TeX{}'s @code{\section} command); this command is
followed by the section name, terminated by a period.  (The period is
essential; if it is omitted, weird errors may result.)  Major sections
are entered in an automatically generated Table of Contents.  They are
also printed at the top of each output page.  If the full section name
is too long to so print, one can shorten it with an optional argument,
as in

@example
@@* [INTRO]INTRODUCTION.
@end example

The command @samp{@@*@i{n}} (not illustrated in the above example)
begins a major (sub)section of level @i{n}, where @samp{@@*0} is
equivalent to the simple @samp{@@*}, @samp{@@*1} indicates a subsection,
and @samp{@@*2} indicates a subsubsection.  The highest
permissible major level is 2 (a subsubsection).  Such subsections are
also entered in the Table of Contents.  For more information, see
@ref{Sections}.

@findex \INDEX
@cindex Index
As the example demonstrates, the name of the very last section, which
should be starred, should be @samp{\INDEX}.  Note the backslash;
@samp{\INDEX} is a @TeX{} macro.  This command tells @FWEAVE{} to
write out the index in a special two-column format.  By default,
@samp{\INDEX} expands to @samp{INDEX}, but this name can be overridden
by the style-file parameter @samp{index.name} (@pxref{S_index}).  For
more discussion of @FWEB{}'s indexing facilities, see @ref{Index}.

Minor (@dfn{unnamed}) sections are begun by @ASP{} (``at-space'');
these have no associated names and are not entered into the Table of
Contents.  A newline counts as a space.

@subsubsection The @TeX{} part

@cindex Commentary, optional
@cindex Part, @TeX{}
All sections begin with (optional) @TeX{} commentary.  That can just be
straight text; to input that, no knowledge of @TeX{} is required.  It
can also include mathematical exposition or any of the other advanced
features offered by @TeX{}.

Whenever @FWEB{} is in @TeX{} mode, one can temporarily shift into @dfn{code mode}
@cindex Code mode
@cindex Vertical bars
@cindex Code, typesetting
by enclosing the
code within vertical bars.  That code is typeset just like code in the
code part (see below), except that newlines are replaced by spaces.
Thus, one can say things like

@example
Consider the C code fragment `|@@c for(i=0; i<10; i++)@{@}|', which ...
@end example
@noindent
(If the global language were C instead of @sc{Fortran}, the @samp{@@c} inside
the vertical bars would not be necessary.)
The ability to switch back and forth between text mode and code mode at
will allows for a very convenient and flexible style of exposition. 

@subsubsection The definition part

@cindex Part, definition
The @TeX{} part is followed by an
optional @dfn{definition part}.  The beginning of the definition part is
signaled by the appearance of any one of the commands @samp{@@d}, @samp{@@f},
@samp{@@m}, @samp{@@v}, or @samp{@@W} (explained later).
In the previous example, the first section has a
definition part consisting of one @FWEB{} macro definition (@samp{@@m}); the
second section has no definition part.  For more information, see @ref{Macros}.

(Failure to appreciate how easy it is to shift from part to part can get
one into trouble.  For example, don't write documentation such as
@samp{Consider the @@m command}, because the @samp{@@m} will inadvertently
terminate the documentation part and begin the definition part.  What
one needs to do here is to use the literal @samp{@@}, as in
@samp{@@@@m}.)
@cindex @@, literal

@subsubsection The code part

@cindex Part, code
An unnamed @dfn{code part} is begun by @samp{@@a}.  A named code part is begun
by the appearance of a module name, such as @samp{@@<Global
variables@@>}, followed by an equals sign; see @ref{Modules}.  Within
the code part, one can place any sequence of code or code fragments
(they need not be complete subroutines) that are valid for the current
language.  (Setting the language is described in @ref{Languages}.)  The
code part is terminated by the next appearance of @samp{@@*} or @ASP{}
(which signal the beginning of a new section), or by the end of file.

@subsubsection The limbo section

@cindex Section, limbo
@cindex Limbo section
The portion of the source file before the first section (i.e., before
the first @samp{@@*} or @ASP{}) is called @dfn{in limbo} or
@dfn{the limbo section}.  
@cindex Limbo section
The only @samp{@@} commands that are allowed in limbo (in addition to
@samp{@@@@}, which stands for the character @samp{@@} and is allowed
anywhere) are the language-changing commands, and one of those, such as
@samp{@@c}, should appear.  Other text in limbo is ignored by @FTANGLE{}
and is copied by @FWEAVE{} to the @code{tex} output file.  Thus, one can make or
issue @TeX{} macro definitions in limbo that override the defaults in
@FWEB{}'s macro package @file{fwebmac.sty}.  In the above example, see
the @code{\Title} command.  This is defined in @file{fwebmac.sty}, and
basically issues La@TeX{}'s @code{\title} command.

(Another way of getting @TeX{} text into the limbo section is by means of
the @samp{@@l} command; see @ref{ATl}.)

La@TeX{} users may need to know that @TeX{} commands in limbo are
executed @emph{after} the @samp{\begin@{document@}} command (which is
issued automatically in @file{fwebmac.sty}).  For more information, see
@ref{LaTeX}.

@node Modules, , Structure, Concepts
@comment  node-name,  next,  previous,  up

@section Modules

@cindex Modules
The code parts of (possibly noncontiguous) sections can be combined into
@dfn{modules}.   For @FWEAVE{}, this is a @emph{logical} combination, for
purposes of cross-referencing different pieces of the code.  But for
@FTANGLE{}, the combination is physical; @FTANGLE{}'s output proceeds module
by module.

Modules can be @dfn{named} or @dfn{unnamed}. There is exactly one
unnamed module. The fundamental operation of @FTANGLE{} is that

@quotation
@emph{@FTANGLE{} outputs the unnamed module}.
@end quotation
@noindent
That output goes to a compilable file with an extension appropriate to
the current language.

The contents of a module, either unnamed or named, consists of a mixture
of code and comments.  @FTANGLE{} ignores the comments; @FWEAVE{}
treats them as @TeX{} text.  Within any @TeX{} text, including comments,
constructions delimited by @samp{|...|} signify a temporary shift into
code mode.  (In the present design, one cannot enclose a comment within
the vertical bars.)

@subsection The unnamed module

The unnamed code module 
@cindex Unnamed module
@cindex Module, unnamed
is introduced by the command @samp{@@a}.  Subsequent
uses of @samp{@@a} accrete code to the unnamed module.
To repeat, the fundamental operation of @FTANGLE{} is that

@quotation
@emph{@FTANGLE{} outputs the unnamed module}.
@end quotation

@noindent
Thus, there must be at least one @samp{@@a} in the source file or
@FTANGLE{} will output nothing.

(Why is the command called @samp{@@a}?  Historically, it was the first
letter of the alphabet, as befits its prominent status.  However, one
can also think of it as ``accrete.'')

@subsection Named modules

@cindex Named module
@cindex Module, named
Named modules represent logically-connected fragments of code.

A module name is specified by the construction

@example
@@< @i{Arbitrary @TeX{} text} @@>
@end example

@noindent
Leading and trailing white space around the name text is ignored.  The
name text can include the @samp{|...|} construction, which tells
@FWEAVE{} to typeset a code fragment.  Thus, module names can be
highly explicit---for example,

@example
@@< Check that |x >= 0.0|; |abort| if not @@>
@end example

To define a named module, replace the @samp{@@a} that begins the unnamed code
part of a section by @samp{@@< @i{module name} @@>=}.  If one uses this
construction with the same name in a later section, the effect is to
@emph{accrete} to the contents of the module.  Thus, a named module
might ultimately consist of the code from sections 2, 5, and 9, for
example.

To use a named module, simply use the name anywhere in a code part;
@FTANGLE{} will insert the contents of the module at the point where the
name is used.  For example,

@example
@@c
@@ Here's how to use a named module.
@@a
for(i=1; i<n; i++)
        @@< Inner loop @@>@@;

@@ Here's how to define a named module.  Definitions may occur after use.
@@< Inner...@@>=
@{
a[i] = i;
@}
@end example

@noindent
There are several details to notice about the above example.  First,
@FWEAVE{} considers module names to be simple expressions (such as the
single identifier @var{x}).  In C, expressions are made into complete
statements (as is required in the body of a @b{for} statement) by
appending a semicolon.  In this case, a @emph{pseudo-semicolon}
@samp{@@;} is appropriate; for more discussion of that,
see @ref{AT;}.  

Second, after a name has appeared once in full, it may be
abbreviated by a unique prefix followed by three periods, as demonstrated in
the above example.  By convention, a complete module name cannot be a
subset of another.  For example, @samp{@@<Test@@>} and @samp{@@<Test of
graphics@@>} will elicit an error message.

Commonly, the first unnamed section in the code indicates its modular
structure.  For example, a C code might begin with

@example
@@c
@@* DEMO.
@@a
@@<Include files@@>@@;
@@<Typedefs@@>@@;
@@<Function prototypes@@>@@;
@@<Global variables@@>@@;
@end example

@noindent
Subsequently one can accrete to the above named sections, as often as
desired and in any order.  This way, definitions of global variables can
be introduced anywhere in the @code{web} source file as logical and pedagogical
exposition dictates, but will 
be guaranteed to appear at the top of the code.  Function prototypes
could be handled this way as well; alternatively, they could all be
collected into one section, perhaps at the end of the source file.  (The
above organization still guarantees that they will appear at the
beginning of the output.)  Functions could be introduced one at a time
in subsequent unnamed sections.

Very rarely, one might try the following construction:

@example
@@
@@a
@@< @i{Left side} @@> = @@< @i{Right side} @@>@@;
@end example
@noindent
Here the intent is to construct an assignment statement.  However, this
will be flagged as an error because @FWEB{} thinks one is trying to
define the named module @samp{@@<@i{Left side}@@>}, which one shouldn't be
doing while in code mode.  To make it work, just put the invisible
expression @samp{@@e} (@pxref{ATe}) before the equals sign.

@node Phases, Structure, Processors, Concepts
@comment  node-name,  next,  previous,  up

@section Phases of processing

The @FWEB{} processors perform their work in several distinct phases.
(The following is somewhat technical.  Scan it, then use it for
reference later if necessary.)

@subsection The phases of @FTANGLE{}

@cindex Phases, of @FTANGLE{}
@FTANGLE{} has two phases.  In phase 1, the source file is read; in phase
2, compilable code is written out in the order specified by the web.

More specifically, phase 1

@quotation
@itemize @bullet
@item
discards @TeX{} documentation;

@item
tokenizes the source;

@item
expands @FWEB{} preprocessor commands such as @samp{@@#if}
(@pxref{Preprocessing}); 

@item
expands @samp{@@'...'} (@pxref{ATquote}), @samp{@@"..."} (@pxref{ATdquote}),
and the binary notation @samp{0b...} (@pxref{C}) [in @sc{Fortran}, also
the octal notation @samp{0...} and the hexadecimal notation @samp{0x...}]; 

@item
stores code text in appropriate modules;

@item
memorizes macro definitions (@samp{@@d} and @samp{@@m})
(@pxref{ATd} and @ref{ATm}).  
@end itemize
@end quotation

Phase 2

@quotation
@itemize @bullet
@item
outputs outer macro definitions (@samp{@@d});

@item
outputs the unnamed module (@samp{@@a});

@item
expands @FWEB{} macros (@samp{@@m});

@item
expands built-in macros such as @samp{$IF} or @samp{$PI}
(@pxref{Built-in functions}); 

@item
translates @sc{Ratfor} statements (@pxref{Ratfor}).
@end itemize
@end quotation

@subsection The phases of @FWEAVE{}

@cindex Phases, of @FWEAVE{}
@FWEAVE{} has three phases.  In phase 1, the source file is read and
cross-reference information is collected.  In phase 2, the source file
is read again, then pretty-printed with some cross-reference
information.  (For discussion of pretty-printing, see
@ref{Pretty-printing}.)  In phase 3, an automatically-generated Index,
List of Modules, and Table of Contents are written.

More specifically, phase 1

@quotation
@itemize @bullet
@item
tokenizes and stores identifiers and module names;

@item
collects cross-reference information (including, in C and C++, the
scanning of @samp{#include} files for @samp{typedef} and/or @samp{class}
declarations (@pxref{-H_}); 

@item
stores limbo text definitions made with @samp{@@l} (@pxref{ATl});

@item
collects information about overloaded operators (@samp{@@v}) and
identifiers (@samp{@@W}).  @xref{ATv} and @ref{ATW_}.
@end itemize
@end quotation

Phase 2

@quotation
@itemize @bullet
@item
outputs limbo text;

@item
outputs special @TeX{} macros for overloaded operators;

@item
copies @TeX{} material directly to output;

@item
treats material between vertical bars (@samp{|...|}) as code to be
typeset;

@item
tokenizes and stores contents of each code section;

@item
analyzes code syntax and converts it to appropriate @TeX{} macros.
@end itemize
@end quotation

Phase 3 writes out cross-reference information.  (To eliminate some of
that, see @ref{-x}.)  Specifically, it

@quotation
@itemize @bullet
@item
writes out the Index (@file{INDEX.tex} by default, but see @ref{Output
files} and @ref{Index params});

@item
writes out a list of named modules (@file{MODULES.tex} by default, but
see @ref{Output files} and @ref{Module params});

@item
writes out macros to generate the Table of Contents.  (Table of Contents
information is actually processed by La@TeX{}, not @FWEAVE{}.  The
information is written to the @file{aux} file.)
@end itemize

@end quotation


@node Files, Starting, Concepts, Top
@comment  node-name,  next,  previous,  up

@chapter FILES

@cindex Files
@FWEB{} works with a variety of files.  File names have the form
@samp{[path]/root[.ext]}, where the brackets denote optional.  Here the slash
is called the @dfn{prefix end character}.  Since this character differs
for various 
operating systems, it can be changed by system installers in @file{custom.h}
(@pxref{Customization}). 
The character that initiates the file-name extension (normally a period)
can be changed with the @samp{-E} command-line option (@pxref{-E_}).


@menu
* Input files::         Input files.
* Output files::        Output files.
* Change files::        Change files.
@end menu

@node Input files,Output files,Files,Files
@comment  node-name,  next,  previous,  up

@section Input files

@cindex Files, input
@FWEB{} reads files with a variety of default extensions.

@quotation

@file{.fweb} --- Initialization file (optional; for setting up default options
used for all runs).  This file is always in the user's home directory.
@xref{Initialization}.
@findex .fweb

@file{fweb.sty} --- Style file (optional; for customizing the behavior
of a particular @code{web} file or group of files).  @xref{Style}.  This
file is always in 
the directory of the @code{web} file that is being tangled unless that
is changed by environment variable @code{FWEB_STYLE_DIR}.  The basic
name can be changed by the @samp{-z} option (@pxref{-z}).
@findex fweb.sty
A sample @file{fweb.sty} file is provided with the @FWEB{} distribution.

@file{@i{name}.web} --- Source file.

@file{@i{name}.ch} --- Change file (optional; for making incremental changes
to a @code{web} source file).  @xref{Change files}.

@file{@i{name}.hweb} --- Code included into web file with @samp{@@i}
(@pxref{ATi}). 
Include files are searched for in the path set by the environment
variable @code{FWEB_INCLUDES} and/or the @samp{-I} option (@pxref{-I_}).
If that path is empty, then the current directory is searched.

@file{@i{name}.hch} --- Optional change file for include file.
@end quotation

@menu 
* Completion::          Automatic file-name completion.
@end menu

@node Completion,,Input files,Input files
@comment  node-name,  next,  previous,  up

@subsection Automatic file-name completion

@cindex File-name completion
@cindex Completion, automatic file-name
Automatic completion of input file names is turned on by the @samp{-e}
command-line option (@pxref{-e}). When this option is in effect, input
file names that 
include no period (have no extension) are completed automatically
according to the contents of the following style-file entries:

@quotation
@multitable { for include file} {Style-file entry} {Default}
@item
@r{Type of file} @tab    @r{Style-file entry} @tab      @r{Default}
@item
@r{WEB file} @tab           @code{ext.web} @tab         @code{web}
@item
@r{Change file} @tab       @code{ext.ch} @tab          @code{ch}
@item
@r{Include file}  @tab     @code{ext.hweb} @tab        @code{hweb}
@item
@r{Change file for include file} @tab @code{ext.hch} @tab         @code{hch}
@end multitable
@end quotation
@noindent 
More than one extension may be specified, as a space-delimited
list---e.g., @samp{ext.web = "web wb"}; the first one that matches is used.  

@node Output files,Change files,Input files,Files
@comment  node-name,  next,  previous,  up

@section Output files

@cindex Files, output
@FWEAVE{} writes a variety of output files.

@quotation
@file{@i{name}.tex} --- Woven output to be processed with La@TeX{}.

@file{CONTENTS.tex} --- Temporary file that accumulates
Table-of-Contents information.  (For La@TeX{}, the @file{aux} file is
used instead.)
@findex CONTENTS.tex

@file{INDEX.tex} --- Temporary file that stores indexing information.
@findex INDEX.tex

@file{MODULES.tex} --- Temporary files that stores module list.
@findex MODULES.tex
@end quotation

@noindent
@cindex Output files, changing names of
The names of the three temporary files can be changed with style-file
parameters (@pxref{Style}).  Commonly, one may put into the style file
@file{fweb.sty} commands such as

@example
index.tex "#.ndx"
modules.tex "#.mds"
contents.tex "#.cts"
@end example

@noindent
The @samp{#} is replaced by the root name of the @code{web} file.

@FTANGLE{} writes files of the form

@quotation
@file{@i{name}.@i{ext}} --- Compilable output file.
@end quotation
@noindent
The extensions for the compilable output file(s) have certain defaults,
but can be changed by style-file parameters according to the following
table:

@quotation
@multitable {Fortran-77} {style-file entry} {unix default} {non-unix default}
@item
@r{Language} @tab @r{Style-file entry} @tab @r{@sc{unix} default} @tab @r{non-@sc{unix} default}
@item
 C           @tab @code{suffix.C}    @tab @code{c} @tab    @code{c}
@item
 C++         @tab @code{suffix.Cpp}  @tab @code{C} @tab    @code{C}
@item
 Fortran--77 @tab @code{suffix.N}    @tab @code{f} @tab    @code{for}
@item
 Fortran--90 @tab @code{suffix.N90}  @tab @code{f90} @tab  @code{for90}
@item
 Ratfor--77  @tab @code{suffix.R}    @tab @code{r}  @tab    @code{rat}
@item
 Ratfor--90  @tab @code{suffix.R90}  @tab @code{r90} @tab @code{rat90}
@item
 TeX         @tab @code{suffix.X}    @tab @code{sty} @tab   @code{sty}
@item
 VERBATIM    @tab @code{suffix.V}    @tab @code{mk} @tab   @code{mk}
@end multitable
@end quotation
@noindent
For example, to change the default extension for a C++ file from
@samp{C} to @samp{c++}, put into @file{fweb.sty} the line

@example
suffix.C = "c++"
@end example
  
@node Change files,,Output files,Files
@comment  node-name,  next,  previous,  up

@section Change files

@cindex Files, change
The primary input to the @FWEB{} processors is the @file{test.web}
source file. However, a @dfn{change file} @file{test.ch} can also be
specified.  A change file consists of instances of the following
structure:

@example
@@x
(One or more lines of text, EXACTLY as in the web file.  Copy these
lines with an editor; don't type them from scratch.)
@@y
(Replacement text.)
@@z
@end example

@noindent
The change-file mechanism allows one to insert local changes or test new
code without physically modifying the original web file.

To specify a change file, use its name as the second file name on the
command line.  The extension @samp{.ch} is assumed by default.  For
example,

@example
ftangle test test
@end example

@noindent
processes @file{test.web} with the change file @file{test.ch}.

@findex @@[
@findex @@]
In addition to @samp{@@x}, @samp{@@y}, and @samp{@@z}, the only
@samp{@@} commands allowed in a change file are language-changing
commands such as @samp{@@c} and the special commands @samp{@@[} and
@samp{@@]}.  The command @samp{@@[} is used for column-oriented
languages such as @sc{Fortran}--77 and means @dfn{switch into code
mode}.  Similarly, @samp{@@]} means @dfn{switch out of code mode}.

All @samp{@@} commands in a change file must begin in column 1.  Lines
not beginning with @samp{@@} are ignored, so may be used as comments.
Comments may also be included on the @samp{@@x}, @samp{@@y}, and/or
@samp{@@z} lines.

@node Starting, AT commands, Files, Top
@comment  node-name,  next,  previous,  up

@chapter RUNNING @FWEB{}

@FWEB{} has a @sc{unix}-style command-line syntax.  There are many
command-line options, but few or none of these are necessary for
standard appplications.  Proceed in blissful ignorance until you need to
do something tricky, then scan the list of options to see if they can
help.

Commonly-used command-line options can be placed into the initialization
file @file{.fweb} (@pxref{Options}) that resides in one's home directory.

A @dfn{style file} (patterned after the utility @code{makeindex};
@pxref{Style}) can be associated with each manuscript or collection of
related manuscripts in order to customize their appearance.  This file
is read @emph{after} the command-line options are processed, except that
the @samp{-p} option gets special treatment; see @ref{-p}.

@menu
* Syntax::      Command-line syntax.
* Options::     Command-line options.
@end menu

@node Syntax, Options, Starting, Starting
@comment  node-name,  next,  previous,  up

@section Command-line syntax

The command-line syntax is
@cindex Syntax, command-line

@example
@{ftangle | fweave@} [-option...] webfile[.web] [changefile[.ch]] 
@end example
@noindent
A file name is anything that doesn't begin with a @samp{-}, except that
a lone hyphen stands for the special file name
@file{stdin}, which means `read from the standard input.'  (This should
not be used except for very special effects.) 
@findex -

Command-line options begin with a @samp{-}.  File names and options can
be intermixed, or the 
options may appear after the file names.  The first file name
encountered is the web source file; the second, if it exists, is
the change file (@pxref{Change files}).  [When no change file is
specified, @FWEB{} attempts 
to read from the null file (@file{/dev/null} on @sc{unix} systems).  This
name should be specified when @FWEB{} is installed
(@pxref{Customization}), or can be set in the style file @file{fweb.sty}.
@xref{null_file}.] 

The web file is shown as required since one is normally processing a
source.  However, some of the information options (@pxref{Info options})
will work without specifying any file name.  For example, one can obtain a
list of all of the style-file parameters and their default values by saying
@w{@samp{ftangle -Z}}.

@node Options, , Syntax, Starting
@comment  node-name,  next,  previous,  up

@section Command-line options

Command-line options may be put, one per line, into the initialization file
@file{.fweb} (which is always in the user's home directory).
In that file, options beginning with a hyphen are processed @emph{before}
the command-line options (so command-line options can override the
defaults).  To force an option to be processed @emph{after} the 
command-line options, preface it with an ampersand
rather than a hyphen; this is rarely necessary.

To make sense of the plethora of options, it helps to know that options
beginning with @samp{n} are related to @sc{Fortran}; those beginning
with @samp{r} are related to @sc{Ratfor}.  Some flags that can be set
separately for those two languages also have a global option that sets the
flags for both languages simultaneously; cf. @samp{-n/}, @samp{-r/}, and
@samp{-/}.

Some options take arguments.  For example, an @FWEB{} macro can be
defined from the command line by saying something like @samp{-mIBMPC=1}.
Unlike many @sc{unix} utilities, @emph{no spaces are allowed between any
option and its argument.}  For example, if one says @samp{-m IBMPC},
@FWEB{} will think that @file{IBMPC} is a file name.

@menu
* Negating options:: How to invert the meaning of an option.
* -1::          Brief debugging mode.
* -2::          Verbose debugging mode.
* -@@: -AT.      Display information about control codes.
* -A: -A_.      Turn on ASCII translations.
* -B: -B_.      Turn off audible beeps.
* -b::          Number blocks.
* -C: -C_.      Set the color mode.
* -c::          Set global language to C.
* -c++: -cpp.   Set global language to C++.
* -D: -D_.      Display information about @FWEB{}'s reserved words.
* -d::          Convert unnumbered `do...enddo's to Fortran--77.
* -E: -E_.      Change the delimiter of a file-name extension.
* -e::          Turn on automatic file-name completion.
* -F: -F_.	Compare output files with old versions.
* -f::          Turn off module references for identifiers.
* -H: -H_.      Scan #include files to format typedef and/or class commands.
* -h::          Where to get help.
* -I: -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: -L_.      Select global language.
* -l::          Echo the input line.
* -M: -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@@;: -nAT;. 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: -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: -rK_.    Write out comments about Ratfor statement translation.
* -r@@;: -rAT;. 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: -T_.      Flag-setting commands for @FTANGLE{}.
* -t::          Truncate identifiers.
* -U: -U_.      Convert reserved output tokens to lower case.
* -u::          Undefined a predefined or command-line macro.
* -V: -V_.      Print version number.
* -v::          Make all comments verbatim.
* -W: -W_.      Flag-setting commands for @FWEAVE{}.
* -w::          Change name of @FWEB{}'s macro package.
* -X: -X_.      Print selected cross-reference information.
* -x::          Reduce or eliminate cross-reference information.
* -y::          Allocate dynamic memory.
* -Z: -Z_.      Display default values of style-file parameters.
* -z::          Change name of style file.
* -.::          Don't recognize dot constants.
* -\::          Explicitly escape continued strings.
* -(: -lp.      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.
* -+: -plus.    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.
@end menu

@node Negating options,-1,Options,Options
@comment  node-name,  next,  previous,  up

@subsection Negating options

@cindex Options, negating
To negate a command-line option, use an extra hyphen.  For example,
@samp{--v} means `Don't make all comments verbatim.'  This kind of
construction isn't used very often, but it is useful if an option such
as @samp{-v} is turned on in the @file{.fweb} initialization file and
one wishes to turn it off for just one run.

@node -1,-2,Negating options,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-1}:  Turn on brief debugging mode (@FWEAVE{})

@findex -1
@cindex Debugging
This option tells @FWEAVE{} to display irreducible scrap sequences.
@cindex Scrap, irreducible

A @dfn{scrap} is a part of speech.  The expression @samp{x + y} consists of
three scraps: @samp{x} (an expression), @samp{+} (a binary operator),
and @samp{y} (an expression).  @FWEAVE{} contains @dfn{production rules}
such as ``replace the combination @samp{expr binop expr} with
@samp{expr}.''  If all goes well, the result of @FWEAVE{}'s reduction
process is ultimately just one scrap, such as @samp{function}.  If
@FWEAVE{} is left with more than one scrap at the end of a section,
this is called an @dfn{irreducible scrap sequence}; @samp{-1} displays
them.

Irreducible scrap sequences can arise either because the programmer made
a mistake or because @FWEAVE{} has not been taught the proper grammar.

@cindex Output, changing appearance of
While @FWEAVE{} is reducing the scraps, it appends @TeX{} macros that
ultimately produce the pretty-printed output.  Frequently people ask how
to change the appearance of that output.  Fundamentally, this is not
possible at present; the grammar rules and the associated @TeX{} are
hard-coded.  A completely general, user-customizable scheme is very
complex and daunting; it has not been attempted.

This brief debugging mode can be turned on more locally by means of the
@samp{@@1} command.  @xref{AT1}.

@node -2,-AT,-1,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-2}:  Turn on verbose debugging mode (@FWEAVE{})

@findex -2
@cindex Debugging
This option tells @FWEAVE{} to display detailed reductions of the
scraps as it does the pretty-printing.  (For a discussion of scraps, see
@ref{-1}.)  Sometimes @FWEAVE{} fails spectacularly at
pretty-printing a section, either because of a syntax error on the
part of the user or because of a bug in @FWEAVE{}'s logic.  This
option helps one (usually the system developer!) to figure out why.

This feature can be turned on more locally by means of the @samp{@@2}
command.  @xref{AT2}.

@node -AT, -A_, -2, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-@@}:  Display the control-code mappings

@findex -@@
@cindex Options, information
This option supplies information about the @samp{@@} control codes
(@pxref{AT commands}).  It shows the associated style-file parameters
that can be used to remap the codes (but @emph{don't do that!}), and it
displays the precedence.  (Some codes such as @samp{@@@@} may be used
anywhere; others such as @samp{@@*} begin 
a new section or part of section.  Codes that begin the definition part
are labelled by @samp{[D]}; codes that begin the code part are labelled
by @samp{[C]}; codes that begin a new section are labelled by
@samp{[S]}.)

The option produces two columns of output: the first is sorted
numerically, the second alphabetically.  The notation @samp{USED_BY_OTHER}
means that this command is ignored by whatever processor (@FTANGLE{}
or @FWEAVE{}) is currently being run, but may be used by the other
processor.  (For technical reasons, a very few commands such as
@samp{@@i} do not show up in this output at present.)

If one says just @samp{-@@}, information about all control codes is
produced.  Selected control codes may be queried by listing them after
the @samp{-@@}.  For example, to learn about the commands @samp{@@~} and
@samp{@@a}, say @samp{-@@~a}.  Remember to quote certain characters on
@sc{unix} systems---e.g., @samp{-@@'*?'}.  If a command is used by
neither processor, its description will be replaced by a question mark.

@node -A_,-B_,-AT,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-A}:  Turn on ASCII translations

@findex -A
This option is used primarily for debugging.  @FWEB{} works
internally with the ASCII character set.  If @FWEB{} is run on a
non-ASCII machine (notably IBM mainframes), translations to and from the
internal ASCII are done automatically; on an ASCII machine, these
translations are unnecessary and are not performed unless the @samp{-A}
option is used.

@node -B_, -b, -A_, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-B}:  Turn off audible beeps

@findex -B
@cindex Marriage
@FWEB{} sometimes beeps the terminal when it encounters certain errors.  The
@samp{-B} option turns off the beeps, replacing them by a printed
exclamation point.

(This option is sometimes called the ``marriage-saver,'' after the
situation that prompted a user's request for this feature.)

@node -b,-C_,-B_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-b}:  Number blocks (@FWEAVE{})

@findex -b
@cindex Numbering blocks
@cindex Blocks, numbering
Number @b{do} and @b{if} blocks in woven @sc{Fortran} and @sc{Ratfor} output.
This feature is particularly useful in @sc{Fortran}-77 to help correlate
the beginnings and ends of long blocks (but note that appropriate use of
literate programming techniques can keep all of one's blocks short!).
Output something like the following is produced, where the comments are
inserted automatically by the @samp{-b} option:

@example
do i=1,10 // Block 1
 do j=1,10 // Block 2
  if(i==j) then // Block 3
        call sub1(i)
  else // Block 3
        call sub2(i,j)
  endif // Block 3
 end do // Block 2
end do // Block 1
@end example
@noindent

The precise form of the block comment that is emitted can be changed by
redefining the macro @code{\Wblock} in @file{fwebmac.sty}.
@findex \Wblock

@node -C_, -c, -b, Options
@comment  node-name,  next,  previous,  up

@findex -C
@subsection @samp{-C}:  Set the color mode

@cindex Color, setting
The option @samp{-C@var{n}} sets the color mode to @var{n}, where the
color modes are, briefly, 

@quotation
@table @kbd
@item 0
No color
@item 1
ANSI color
@item 2
Bilevel
@item 3
Trilevel
@item 4
User-defined
@end table
@end quotation
@noindent
These modes, and color output in general, are described more thoroughly
in @ref{Color}. 

For obscure technical reasons, this command is processed differently
than all other command-line options.  In the present incomplete
implementation, @emph{the color mode must be set on the command line},
not in @file{.fweb}!  To work around this annoyance, @sc{unix} users
could alias commands such as @w{@samp{ftangle -C1}}.

@node -c, -cpp, -C_, Options
@comment  node-name,  next,  previous,  up

@findex -c
@subsection @samp{-c}:  Set global language to C

@cindex Language, setting
Usually the global language (@ref{Languages}) is set to C by means of
the command @samp{@@c} in limbo, rather than using @samp{-c} on the
command line.  However, one may need to use the command-line option
@samp{-c} if a subsequent command-line option is language-dependent.
See, for example, the discussion of the option @samp{-D} in @ref{-D_}.

@node -cpp, -D_, -c, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-c++}:  Set global language to C++

@findex -c++
For more information, see the discussion of @samp{-c} in @ref{-c}.

@node -D_, -d, -cpp, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-D}:  Display reserved words

@findex -D
@cindex Options, information
@cindex Reserved words
@cindex Words, reserved
@cindex Intrinsic functions
@cindex Functions, intrinsic
@cindex Keywords, I/O
@cindex I/O keywords
This information option displays the list of reserved words for the
language currently in force.  (For the purposes of this option,
`reserved words' include ``true'' reserved words such as @samp{int};
they also include the names of intrinsic functions such as @samp{sin}
and, for @sc{Fortran} and @sc{Ratfor}, I/O keywords such as
@samp{IOSTAT}.)  Thus, to see the reserved words for @sc{Ratfor}--90,
say

@example
ftangle -Lr9 -D
@end example

@noindent
(For this option one must set the language on the command line, because
the @samp{-D} option is processed before the limbo section of the web file is
read.)

If one says @samp{-Dabc}, one will get just the reserved words that begin with
"abc".

If one says @samp{-D*}, one will get all reserved words for all languages.

The @samp{-D} may be followed by a list of one or more optional letters
enclosed in square brackets.  (For @sc{unix} systems, don't forget to
quote the brackets, as they mean something special to the shell.)  The
letters represent which kind of reserved word to display; they may be
@samp{i} (`intrinsic'), @samp{k} (`keyword'), or @samp{r} (`reserved').
Thus, to see a list of the @sc{Fortran} keywords, say @samp{-D[k]}.  To
see a list of the intrinsic functions for C++ that begin with @samp{s},
say @samp{-Lc++ -D[i]s}.

@node -d,-E_,-D_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-d}:  Convert do...enddo

@findex -d
@emph{(This option is obsolete.)}

@node -E_,-e,-d,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-E}:  Change the delimiter of a file-name extension

@findex -E
The standard delimiter for file-name extensions is a period, as in
@file{test.web}.  To change this character to a comma, for example, say
@samp{-E,}.  This feature is required by at least one perverse system.

@node -e,-F_,-E_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-e}:  Turn on automatic file-name completion

@findex -e
When the @samp{-e} option is in effect, @FWEB{} attempts to be helpful in
figuring out what file name one intends.  For any input file name that
has no extension (no embedded period), @FWEB{} completes the name by adding
the extension contained in the style-file parameter listed in the
following table:

@example
        @r{Type of file}      @r{Style-file entry}        @r{Default}
        WEB file            @code{ext.web}        @code{web}
        Change file         @code{ext.ch}         @code{ch}
        Include file        @code{ext.hweb}       @code{hweb}
        Change file
         for include file   @code{ext.hch}        @code{hch}
@end example

@noindent
More than one extension may be specified, as a space-delimited
list---e.g., @samp{ext.web = "web wb"}; the first one that matches is used.  

@node -F_,-f,-e,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-F}:  Compare output files with old versions (@FTANGLE{})

@findex -F
When the @samp{-F} option is in effect, @FTANGLE{} writes its output
to a temporary file (or files) instead of to its ultimate
destination such as @file{test.c} and/or @file{test.f}.  After all
output is written, the temporary files are compared with the old version
of the files, if they exist.  If the files are identical, the
appropriate temporary file is deleted; otherwise, the temporary file is
renamed, effectively overwriting the old version.  This feature avoids
updating the time stamp on the file unnecessarily, so a @code{make} file won't
recompile the output unless it really has to.

Note that with this option in effect, if one uses the @sc{unix} utility
@code{touch} to force processing of a group of files, but the @code{web}
sources are never changed, the @code{make} file will continue to tangle
the sources no matter how many times it is run, since @FTANGLE{} will
never update the time stamp on the files.  This is harmless, but
annoying.  To get things back in sync, do a run without the @samp{-F}.

The location of the temporary file as well as details of the renaming
procedure are determined by the automatic configuration script
@code{./configure} during 
installation of the processors.  The script first looks for
the (non-ANSI) function @code{tempnam}.  
@findex tempnam
If it finds it, it uses it to place
the temporary file in the directory that @FWEB{} would normally use for
output in the absence of the @samp{-F} option.  (That is usually the current
directory.)  If @code{tempnam} is not available, the ANSI routine
@code{tmpnam} is used.
@findex tmpnam
That places the temporary file in a directory
determined by the system.  

To implement the renaming, the @code{rename} function is used.  That may fail
if @code{tmpnam} placed the temporary file on a different device.  If so, an
attempt is made to force the rename by using the @code{system} routine to
issue a @code{mv} command.  Terminal output indicates the progress of the
renaming.  An asterisk following an output file name indicates that
@code{rename} did not succeed, but the @code{mv} command did.

Some of the above-mentioned file names and system commands are
system-dependent; see @ref{Customization}.

@node -f,-H_,-F_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-f}:  Turn off module references for identifiers (@FWEAVE{})

@findex -f
In an attempt to be helpful, @FWEAVE{} appends subscripts to many
identifiers indicating in which section they are first defined
(@pxref{Subscript params}).  Sometimes these result in output that is
too cluttered and confusing.  The @samp{-f} option turns off the
subscripting operations.

@node -H_,-h,-f,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-H}:  Scan C/C++ include files (@FWEAVE{})

@findex -H
@findex -Hx
@findex -HX
@findex -Hr
@cindex Include files, scanning
For C or C++, the @samp{-H} option tells @FWEAVE{} to do a phase-1 scan
of @code{#include} files for @samp{typedef} and/or @samp{class}
declarations.  This removes the necessity of including many redundant
@samp{@@f} format statements (@pxref{ATf}), which would otherwise be
necessary in order that the code be pretty-printed correctly.  For
example, if one uses the @samp{-H} option with the code

@example
@@c++
@@
#include <Complex.h>
Complex z;
@end example
@noindent
the identifier @b{Complex} will be properly formatted as a reserved
word (in boldface), as though one had said @samp{@@f Complex int}.

In addition to the basic @samp{-H}, there are several more detailed
options:

@quotation
@table @code
@item -Hx     
Make index entries only for double-quoted include files.
@item -HX
Make index entries for all include files.
@item -Hr
Retain temporary files generated by the preprocessor.
@end table
@end quotation

By default, index entries are not made for variables that are read
during such scans.  If one says @samp{-Hx}, index entries will be made
only for include files whose names are enclosed in double quotes rather
than angle brackets, such as @samp{#include "myheader.h"}
(usually these are defined by the user and reside in the local
directory).  If one says @samp{-HX}, index entries will be made for all
include files.  This can generate many entries, since system header
files may be complicated and may include other files as well.

This command is implemented as follows.  When @FWEAVE{} reads an
@code{#include} statement, it issues a @code{system} command to run the
C preprocessor on the included file.  Output from the preprocessor is
written to a temporary file, which @FWEAVE{} scans.

By default, the C preprocessor will look in certain default paths for
the included files.  To add to those defaults, use one or more @samp{-I}
options @emph{after} the @samp{-H}.  These colon-delimited lists are
concatenated to the contents of the environment variable
@code{FWEB_HDR_INCLUDES}, if that is defined.  The entire list is then
passed as multiple @samp{-I} options to the preprocessor.

This command, new with version 1.53, is @emph{highly experimental} and
incomplete.  The installation script attempts to determine what command
to use to run the preprocessor, but that is not guaranteed to work in
general.  @samp{-H} has been tested only with @code{gcc}.

To send arguments to the C preprocessor, see @ref{-WH_}.

The @samp{-H} mechanism uses temporary files to do its work.  By
default, those are deleted after use.  However, for debugging purposes,
one can force those to be retained by saying @samp{-Hr}.  That option
also has the side effect of displaying the actual command line that was
sent to the preprocessor.

@node -h,-I_,-H_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-h}:  Get help

@findex -h
If just @samp{-h} is typed, a message is printed saying where further
help is available.  It refers one to the various information options
(@pxref{Info options}) and the on-line documentation
(@pxref{Support}).  If the stand-alone @code{info} program (the GNU
hypertext browser) is installed, one can enter
@samp{info FWEB} at this time by typing @samp{?} or a space-separated
list of @FWEB{} menu items such as @samp{Macros FWEB built-in $PI}.
In fact, since @samp{$PI} appears in the detailed node listing, one can
simply type @samp{$PI}.  More generally, one can type anything that
@code{info} accepts on its command line (the option @samp{-f FWEB} is
implicit). 

One can bypass the printed message and directly enter @code{info} by
specifying the @code{info} arguments as arguments to @samp{-h}.  For
example, on a @sc{unix} system, one could type @samp{-h'\$PI'}.  Here
the dollar sign must be escaped because it has special significance to
the shell, and the quotes are necessary in order to preserve that escape
character as the argument is supplied to @code{info}.  To get to the
top-level @FWEB{} info directory, type 
@samp{-h.} or @samp{-h'?'}.

@node -I_,-i,-h,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-I}:  Append to search list for include files

@findex -I
@cindex Include files, finding
The fundamental search list for @dfn{include files} (read in via @samp{@@i} or
@samp{@@I}) is defined by the environment variable @code{FWEB_INCLUDES},
which is a colon-delimited list such as

@example
setenv FWEB_INCLUDES .:/usr/fweb:/other/stuff
@end example

@noindent
The @samp{-I} option appends to this list.  

For information about include files, see @ref{ATi}.

@node -i,-i!,-I_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-i}:  Don't print @samp{@@I} include files (@FWEAVE{})

@findex -i
@findex -ix
@cindex Include files, skipping
@cindex Include files, indexing
If a web file is included via @samp{@@I} (@pxref{ATI_}),
for example

@example
@@I formats.hweb
@end example

@noindent
then the @samp{-i} option means to read and process the web file, but don't
print its contents.  This option is often used for large files of macro
definitions, formats, or @b{typedef} statements that must be included at the
beginning of even very short web files; it clutters things up to print
such header files all of the time.  (C and C++ programmers will find that the
@samp{-H} option substantially reduces the need to include such header
files; see @ref{-H_}.)

Note that files included via @samp{@@i} (lower case) do not respond to
@samp{-i} or @samp{-i!}. 

By default, identifiers that are referenced in non-printed include files
are not cross-referenced or indexed in any way.  To force them to be
cross-referenced, say @samp{-ix} instead of @samp{-i}.  In the present
implementation, the cross-reference information for such non-printed
files is presented in the form
@samp{#@i{n}}, where @i{n} is the integer section number.  (The La@TeX{}
section label is undefined for sections in non-printed files.)

The option @samp{-i!} means skip the include files completely.  This is
usually not very useful.

@node -i!,-j,-i,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-i!}:  Don't read @samp{@@I} include files

If a web file is included via @samp{@@I}, for example

@example
@@I formats.hweb
@end example

@noindent
then the @samp{-i!} option means to ignore such files completely.  This option
is seldom useful; the @samp{-i} option (@pxref{-i}) is more often used.

@node -j,-k,-i!,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-j}:  Inhibit multiple includes

@findex -j
@cindex Include files, inhibiting
File inclusion via @FWEB{}'s @samp{@@i} command suffers from a design
deficiency:  they cannot be inhibited by means of @FWEB{}'s
preprocessor commands.  (The reason is that @samp{@@i} is processed very
early in the input stage, before tokenization.  This design decision was
inherited from @sc{Cweb}, and is very difficult to change.)  A
particularly annoying situation arises when the same file is included
multiple times; various array space may be eaten up unnecessarily.  The
@samp{-j} option inhibits such multiple includes.

@node -k,-L_,-j,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-k}:  Don't recognize lower-case forms of keywords

@findex -k
By definition, in @sc{Fortran} and @sc{Ratfor}, a keyword is one of the
parameters such as @code{IOSTAT} used in the parameter list of an I/O
statement.  For example,

@example
open(21, FILE=file_name, STATUS='old', IOSTAT=io_flag)
@end example
@noindent
Such keywords are typeset in @code{typewriter type} to better highlight them.
In @sc{Fortran}, these keywords are case-insensitive.  However,
note that certain of the lower-case forms---in particular, @samp{end},
@samp{read}, and @samp{write}---have other special meanings, and one can
in principle use any of these keywords as ordinary variables in other parts of
the code; however, @FWEB{} identifiers can have just one meaning
throughout the code.  By default, the lower-case forms are also
recognized as keywords (except for the three special identifiers just 
mentioned), so one shouldn't use those as regular variables.  To cause
only the upper-case forms to be recognized, use the @samp{-k} option.

@node -L_,-l,-k,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-L}:  Select global language

@findex -L
To select a global language from the command line, say @samp{-L@i{l}},
where @i{l} is one of @code{@r{@{}c,c++,n,n9,r,r9,v,x@r{@}}}.  @xref{Languages}.

Usually, the global language is set via an @samp{@@} command in limbo,
not on the command line.  However, one may need to use a command-line
option such as @samp{-L_} if a subsequent command-line option is
language-dependent.  See, for example, the discussion of the option
@samp{-D} in @ref{-D_}.

@node -l,-M_,-L_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-l}:  Echo input line

@findex -l
The option @samp{-l@i{[mmm[:nnn]]}} echoes the input lines constructed
by the input 
driver between lines @i{mmm} and @i{nnn}.  Missing @i{nnn} means echo to
the end of file.  Missing @i{mmm} means echo from the beginning.

This option is useful as a debugging tool (usually by the system
developer).  It is often used to verify that the input driver is
inserting semicolons correctly.  For @sc{Fortran}--77, it is also useful to
verify that comments are being processed correctly.

@node -M_, -m, -l, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-M}:  Set output message level

@cindex Message level
@cindex Level, message
@findex -M
By default, @FWEB{} is relatively verbose; as it proceeds, it prints
messages about what files it is reading and writing, numbers of the
starred sections, line numbers, etc.  However, different levels of
verbosity can be set by the command @samp{-M@i{level}}, where the level
may be 0 (least verbose) through 4 (most verbose; the default), as
described in the following table:

@quotation

@table @kbd
@item 0
Like level 1, but the start-up banner is not printed.  If @FWEB{} runs
to completion with no errors, nothing at all will be printed.

@item 1
Print only error messages.

@item 2
Print error and warning messages.

@item 3
Print errors, warnings, and short information messages (excluding
starred section numbers and line numbers).

@item 4
Print everything.

@end table
@end quotation

The start-up banner, which includes the version number, is printed for
all message levels except 0.  For level 0, one can use the @samp{-V}
option to request the start-up banner. @xref{-V_}.

This option is very recent, and may not be fully debugged for obscure
combinations of command-line options.  Please report any annoyances.

Another way of discriminating message types is via color output.
@xref{Color}. 

@node -m,-m4,-M_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-m}:  Define @FWEB{} macro (@FTANGLE{})

@findex -m
The command-line construction

@example
-mA(x)=x
@end example
@noindent
defines the @FWEB{} macro @code{A} as though the definition

@example
@@m A(x) x
@end example

@noindent
had appeared in the first definition part of the web file.

One can also say @samp{-m'A(x) x'}, where the quotes are removed by the
shell.  That is, an @samp{=} appearing @emph{immediately} after the
macro name (or argument list, if there is one) plays the role of the
space in the conventional definition.  Thus, carefully distinguish the forms

@example
-m'A(x)=x'   // @r{A(x) expands to @samp{x}}
-m'A(x) =x'  // @r{A(x) expands to @samp{=x}}
-m'A(x)==x'  // @r{Precisely equivalent to the previous example.}
@end example

The equals sign is permitted only with command-line macro definitions,
not with @samp{@@m} commands (@pxref{ATm}) in the definition parts of
the web file. 

@node -m4,-m;,-m,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-m4}:  Understand @code{m4} built-in commands

@findex -m4
@cindex Preprocessor, m4
This tells @FWEAVE{} to properly format the reserved words of the @code{m4}
preprocessor.  The use of that preprocessor is @emph{not recommended} in
conjunction with @FWEB{}; use @FWEB{}'s built-in C-like preprocessor
instead. 

@node -m;,-n,-m4,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-m;}:  Append pseudo-semicolons

@findex -m;
When @samp{-m;} is in effect, the construction @samp{@@;} is appended
automatically to all @FWEB{} macro definitions.

@emph{This option is not recommended.}  Please insert the @samp{@@;} by
hand when necessary, as in

@example
@@m SET(x,y) x=1; y=2@@;
@@m TEST(x) if(x) y; else z@@;
@end example

@node -n,-n9,-m;,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n}:  Set global language to @sc{Fortran}--77

@findex -n
This is @FWEB{}'s default, so it generally does not need to be used
explicitly.  (See also the discussion of @ref{-L_}.)  However, variants
of this option, as described below, may be useful. 

See also @ref{Languages} and @ref{Fortran}.

@node -n9,-nAT;,-n,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n9}:  Set global language to @sc{Fortran}--90

@findex -n9
@xref{Languages} and @ref{Fortran}; see also the discussion of @samp{-L}
in @ref{-L_}.

@node -nAT;, -n;, -n9, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n@@;}:  Supply automatic pseudo-semicolons [@sc{Fortran}]

@findex -n@@;
@cindex Pseudo-semicolons, automatic
@cindex Automatic pseudo-semicolons
(Don't forget that a semicolon has special meaning to @sc{unix} shells,
so you'll probably have to quote this command:  @samp{-n'@@;'}.)

This is the default mode of operation for free-form @sc{Fortran}-90; the
input driver automatically appends a pseudo-semicolon (invisible) to
each logical line of source code.  Since it is the default, one doesn't
have to use it unless one wishes to negate it (@pxref{Negating
options}).  In that case, it is best to place the @samp{--n@@;} command
in the source file, as @samp{@@n9[--n@@;]}.  If one places it on the
command line, be sure to set the language first: @code{-n9 --n@@;}.

For free-format @sc{Fortran}-90, when @samp{-n@@;} is in effect (the
default), @samp{-np} is also turned on.  @xref{-np}.

For further discussion, see the companion command @ref{-n;}.

@node -n;,-ncolon,-nAT;,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n;}:  Supply automatic semicolons [@sc{Fortran}]

@findex -n;
@cindex Semicolons, automatic
@cindex Automatic semicolons
(Don't forget that a semicolon has special meaning to @sc{unix} shells,
so you'll probably have to quote this command:  @samp{-n';'}.)

This command functions the same as @samp{-n@@;} (@pxref{-nAT;}, except
that actual 
(visible) semicolons rather than pseudo-semicolons are appended.  This
is the default mode of operation for @sc{Fortran}-77 (and for that
language, it cannot be turned off by negation).

The distinction between @samp{-n@@;} and @samp{-n;} has to do with what
is visible on output.  In @sc{Fortran}-77, semicolons are not printed by
default since that seemed to annoy many users.  However, that causes
trouble with @sc{Fortran}-90 code containing multiple statements per
line, as in

@example
a = b; c = d
@end example
@noindent
If @samp{-np} is not used, then the semicolon in the above
example is not printed, hindering legibility.  Thus, the default mode of
operation for free-format @sc{Fortran}-90 is @samp{-n@@;} and
@samp{-np}.  This turns the above example into @samp{a = b; c = d@@;}
and displays it correctly.

When @samp{-n;} is used, semicolons will not be printed by default.
To force them to be printed, use the @samp{-np} option (@pxref{-np}).  

Do not insert semicolons by hand in @sc{Fortran}-77; they are always
inserted automatically.  If you have terminated @sc{Fortran}-90
statements by hand, turn off auto-semis by @samp{-n;} (and use
@samp{-np} at your discretion).

The following table summarizes the defaults for auto-semi insertion and
semicolon printing in @sc{Fortran}, both fixed and free formats (`N/A'
means `not applicable'):

@quotation
@multitable {F90}{Fixed}{ `-nA; -np' }

@item @tab Fixed @tab Free
@item F77 @tab @samp{-n;} @tab N/A
@item F90 @tab @samp{-n;} @tab @samp{-n@@; -np}

@end multitable
@end quotation


@node -ncolon,-nb,-n;,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n:}:  Put statement label on separate line [@sc{Fortran}]

@findex -n:
By default, in @sc{Fortran} statement labels are placed on the same
line, and backspaced from, the command that is being labeled, as in

@example
EXIT: continue
@end example
@noindent
This can look ugly if the label is very long.  The command @samp{-n:}
places the label on a separate line, as is done automatically for
@sc{Ratfor}---e.g.,

@example
EXIT:
  continue
@end example

If neither of these options appeals to you, you could try redefining the
macro @code{\Wlbl}, found with some discussion in @file{fwebmac.web}.
That macro is emitted only when @samp{-n:} is @emph{not} used.
@findex \Wlbl

@node -nb,-nC,-ncolon,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-nb}:  Number @b{if}s and @b{do}s [@sc{Fortran}] (@FWEAVE{})

@findex -nb
@cindex Numbering blocks
@cindex Blocks, numbering
In the woven output, extra comments are added to help one correlate the
block structure of the code.  For more discussion, see @ref{-b}.

@node -nC, -np, -nb, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-nC}:  Ignore single-line comments [@sc{Fortran}]

@findex -nC
@cindex Comments, ignore single-line Fortran
Ignore, at the input-driver stage, comment lines beginning with
@samp{C}, @samp{c}, or @samp{*}.

Interpretation:  In the usual mode of operation, the @sc{Fortran}-77 input
driver makes a heroic attempt to mix the original single-line column-1
commenting style with the @FWEB{} style (@samp{/*...*/} and
@samp{//}).  It converts single-line comments to the @samp{/*...*/}
style and passes them along to the innards of the processors.  

Problems sometimes arise when converting an existing @sc{Fortran} code
to @FWEB{}.  Such codes may have very large blocks of code or
documentation commented out with a @samp{C} in column 1.  Special @TeX{}
characters in those comments can cause problems for @FWEAVE{};
sometimes @FTANGLE{} gets confused as well.  The @samp{-nC} option
short-circuits these problems by simply throwing all such lines away at
the input driver stage.

This option is not a recommended long-term solution.  Instead, consider
the following:

@quotation
@itemize @bullet

@item
In @FWEB{}, blocks of code should be commented out with the
preprocessor commands @code{@@#if 0...@@#endif}; see @ref{Temporary
comments}.

@item
Textual comments for documentation should be converted to the standard
@FWEB{} commenting style.

@item
If one has a block of code prefaced by an extremely long comment,
replace that by a named module and put the comment into the @TeX{} part
of that section.

@end itemize
@end quotation

@node -np,-n\,-nC,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-np}:  Print semicolons [@sc{Fortran}] (@FWEAVE{})

@findex -np
@cindex Semicolons, printing
Although the @sc{Fortran} input driver automatically terminates logical
lines with semicolons (@sc{Fortran}-77; see @ref{-n;}) or pseudo-semicolons
(@sc{Fortran}-90; see @ref{-nAT;}) so that the innards of @FWEAVE{}
can process them correctly, the semicolons are not printed by default.
To make actual semicolons be printed, use the @samp{-np} option.

@samp{-np} is turned on automatically  for free-format @sc{Fortran}-90 when
@samp{-n@@;} is in effect (the default).  For more discussion, see
@ref{-n;}. 

@node -n\,-n&,-np,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n\}:  Free-form syntax continued by backslash

@findex -n\
@cindex Syntax, free-form
In @sc{Fortran}--90, this turns on free-form syntax and sets the continuation
character to be the backslash (as it would be in C).  For example,

@example
-n9[-n\]
@@
@@a
program main
x = \
 y
end
@end example
@noindent
In the tangled output the backslash is converted into @sc{Fortran}-90's
standard continuation character, the ampersand.

See also @ref{-n&}.

@node -n&,-n/,-n\,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n&}:  Free-form syntax continued by ampersand

@findex -n&
@cindex Syntax, free-form
In @sc{Fortran}--90, this turns on free-form syntax and sets the continuation
character to be the ampersand.  For example,

@example
-n9[-n&]
@@
@@a
program main
x = &
 y
end
@end example

For @sc{Fortran}-90, free-form syntax continued by the ampersand is
@FWEB{}'s default, so one probably will not need to use @samp{-n&}
explicitly.  

See also @ref{-n\}.

@node -n/,-n!,-n&,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n/}:  Recognize short comments [@sc{Fortran}]

@findex -n/
The standard @FWEB{} notation for a short comment (one terminated by
the next newline) is @samp{// ...}.  However, in @sc{Fortran} the
@samp{//} denotes concatenation by default.  To make it denote a short
comment, use the @samp{-n/} option.  One can do this in the @file{.fweb}
file (@pxref{Customization}) or with the language-setting command in
limbo, as in @samp{@@n/}.

@noindent
In @FWEB{}, one may always use @samp{\/} for concatenation, so there's
no penalty for using @samp{-n/}.
@cindex Concatenation
@findex \/

@node -n!,-n),-n/,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n!}:  Make @samp{!} denote short comment [@sc{Fortran}]

@findex -n!
@cindex Comments, @sc{Fortran}
In @sc{Fortran}-90, @samp{!} starts a short comment.  However,
by default @FWEB{} usurps @samp{!} for the logical not, as in
@samp{if(x != y)}.  To force it to recognize @samp{!} as a comment, use
@samp{-n!}.  However, the recommended style is to use @FWEB{}'s
standard convention that @samp{//} denotes the start of a short
comment (@pxref{-n/}).  See also @ref{-!} and @ref{-r!}.

In @sc{Fortran}-77, to include the exclamation point inside a string,
escape it with a backslash, as in

@example
        s = "A \! inside a string"
@end example
@noindent
This possibly annoying restriction arises because the unduly complicated
@sc{Fortran} input driver does some preprocessing of the @sc{Fortran}
source before it feeds it to the cores of the processors.

@node -n), -o, -n!, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-n)}:  Reverse array indices [@sc{Fortran}] (@FTANGLE{})

@findex -n)
This @emph{somewhat experimental} flag permits @sc{Fortran} programmers to
use C-style array indices. 
Conversions such as the following are made (during the output phase of
@FTANGLE{}): 

@example
a(k)(i) @r{=>} a(i,k)
a(k)(i,j) @r{=>} a(i,j,k)
a(k)(j)(i) @r{=>} a(i,j,k)
@end example
@noindent
[No spaces may intervene between @samp{)} and @samp{(}; effectively,
@samp{)(} is treated as one token for the purposes of @samp{-n)}.]
This feature permits convenient definitions of macros that deal with
multi-dimensional vectors.

Unfortunately, @FTANGLE{} doesn't fully understand the syntax of the
source code---and never will, unless it is fully integrated with a
compiler.  It will therefore be confused by situations like the
following @sc{Fortran} example:

@example
dimension x(0:4)(1:2) // @r{OK}
character*90 ch(4) // @r{OK}
write(6,*) ((x(i)(j),i=1,2), j=3,4) // @r{Will reverse incorrectly.}
c = ch(4)(3:4) // @r{Shouldn't reverse, but will.}
@end example
@noindent
One solution, due to Charles Karney, is to insert a space to prevent
@samp{)(} from being recognized as a single token.  However,
since ordinary white space is eaten on input, one must resort to
something like the following (@samp{$UNQUOTE} is a built-in @FWEB{}
function; @pxref{$UNQUOTE}):

@example
@@m SP $UNQUOTE(' ')
@@a
dimension x(0:4)(1:2)
character*90 ch(4)
write(6,*) SP ((x(i)(j),i=1,2), j=3,4)
c = ch(4)SP(3:4)
@end example

This option is controlled by the three style-file parameters
@samp{paren.len}, @samp{paren.num}, and @samp{paren.nest}.  (@xref{Style}.)
@samp{paren.len} is the default number of bytes to be allocated for each
index; if an index is longer than this number, the current length is
increased by this number and storage is automatically reallocated.
@samp{paren.num} is the maximum number of allowed indices; for example,
when processing @samp{a(i)(j)(k)}, @samp{paren.num} is 3.
@samp{paren.nest} is the maximum parenthesis nesting level.  In the
example @samp{x(a(i)(j)(k))}, @samp{paren.nest} is 2.  If either of the
last two parameters is exceeded, a message will be issued asking you to
increase the appropriate value.

@node -o,-q,-n),Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-o}:  Don't overload operators

@findex -o
@cindex Operators, overloading
This option inhibits the operator-overloading feature invoked by the
command @samp{@@v} (@pxref{Overloading}).

@node -q,-P_,-o,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-q}:  Don't translate @sc{Ratfor}

@findex -o
@emph{(This option is obsolete.)}

@node -P_,-p,-q,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-P}:  Select @TeX{} processor

@findex -P
@cindex Processor, @TeX{}
@cindex Processor, La@TeX{}
Say @samp{-PT} or @samp{-PL} to inform @FWEAVE{} that its output will
be processed by @TeX{} or La@TeX{}, respectively.  Beginning with
Version 1.50, the default processor is LaTeX (@samp{-PL}).  If you
always use @TeX{}, it's easiest to put @samp{-PT} into the @file{.fweb}
initialization file.  

@emph{Please note that @samp{-PT} is no longer supported;  @FWEB{}
development is now based exclusively on La@TeX{}.}

@node -p,-r,-P_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-p}:  Buffer up a style-file entry

@findex -p
This option specifies a style-file entry (@pxref{Style}).  Its argument
is exactly the same as a line that one may put into the local @FWEB{}
style file.  Thus, if in @file{fweb.sty} one would say
@samp{entry="value"}, the form of the @samp{-p} option would be
@samp{-pentry='"value"'}.  (The single quotes are required on a
@sc{unix} system because the double quotes have special significance to
the shell.)

This option can be used either in the @file{.fweb} initialization file
(@pxref{Initialization}), to record style-file entries that are common
to all runs, or on the command line, to override a local style-file
entry for a single run.  This behavior is a consequence of the following
order of processing style parameters:

@quotation
@enumerate
@item
@samp{-p} options in @file{.fweb};

@item
entries in the local style file @file{fweb.sty};

@item
@samp{-p} options on the command line.

@end enumerate
@end quotation

@node -r,-r9,-p,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-r}:  Set global language to @sc{Ratfor}--77

@xref{Languages} and @ref{Ratfor}.  See also @ref{-L_}.
@findex -r

@node -r9,-rg,-r,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-r9}:  Set global language to @sc{Ratfor}--90

@xref{Languages} and @ref{Ratfor}.  See also @ref{-L_}.
@findex -r9

@node -rg,-rk,-r9,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-rg}:  Set @b{goto} parameters

@findex -rg
This obscure option is used for configuring @sc{Ratfor} (and really
should be a style-file parameter).  (Discussion not finished.)

@node -rk,-rK_,-rg,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-rk}: Suppress comments about @sc{Ratfor} translation (@FTANGLE{})

@findex -rk
By default, the @sc{Ratfor} translator writes comments about what command it
is translating.  The @samp{-rk} option suppresses those comments.  Arguments
to this option allows one to suppress comments about only particular
commands, according to the following list:

@example
b @r{---} break
c @r{---} case
t @r{---} default
d @r{---} do
f @r{---} for
i @r{---} if
n @r{---} next
p @r{---} repeat, until
r @r{---} return
s @r{---} switch
h @r{---} where
w @r{---} while
@end example

@noindent
For example, one can say @samp{-rkrb} to suppress comments about the
@b{return} and @b{break} statements.

@node -rK_,-rAT;,-rk,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-rK}:   Write comments about @sc{Ratfor} translation (@FTANGLE{})

@findex -rK
This is the negative of @samp{-rk} (@pxref{-rk}); it forces comments
about particular @sc{Ratfor} commands. 

@node -rAT;, -r;, -rK_, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-r@@;}:  Turn on auto-semi mode using pseudo-semis [@sc{Ratfor}]

@findex -r@@;
Please don't use this option (it may not work).  Insert semicolons by
hand in your @sc{Ratfor} code, just as one does in C.

@node -r;, -rb, -rAT;, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-r;}:  Turn on auto-semi mode using actual semis [@sc{Ratfor}]

@findex -r;
Please don't use this option (it may not work).  Insert semicolons by
hand in your @sc{Ratfor} code, just as one does in C.

@node -rb,-r/,-r;,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-rb}:  Number @b{if}s and @b{do}s [@sc{Ratfor}]

@findex -rb
@cindex Numbering blocks
@cindex Blocks, numbering
In the woven output, extra comments are added to help one correlate the
block structure of the code.  For more discussion, see @ref{-b}.

@node -r/,-r!,-rb,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-r/}:  Recognize short comments [@sc{Ratfor}]

@findex -r/
The standard @FWEB{} notation for a short comment is @samp{// ...}.
However, in @sc{Ratfor} the @samp{//} denotes concatenation by default.
To make it denote a short comment, use the @samp{-r/} option.  For
concatenation, use @samp{\/}.

For an example, see @ref{-n/}.

@node -r!,-r),-r/,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-r!}:  Make @samp{!} denote short comment [@sc{Ratfor}]

@findex -r!
See the corresponding discussion of @samp{-!} in @ref{-!} and @ref{-n!}.

In @sc{Fortran}-77, to include the exclamation point inside a string,
escape it with a backslash, as in

@example
        s = "A \! inside a string"
@end example

@node -r), -s, -r!, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-r)}:  Reverse array indices [@sc{Ratfor}] (@FTANGLE{})

@findex -r)
See the corresponding discussion of @samp{-n)} in @ref{-n)}.

@node -s, -T_, -r), Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-s}:  Print statistics

@findex -s
@findex -sm
@cindex Statistics, printing
@samp{-s} prints statistics about memory usage at the end of the run.  

@samp{-sm} prints statistics about memory usage at the end of the run, just
as does @samp{-s}; it also prints information about dynamic memory
allocations as they occur.  @samp{-sm@i{nnn}} displays allocations of nnn bytes
or more; if @i{nnn} is missing, 10000 is assumed.

@node -T_, -t, -s, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-T}:  Flag-setting options for @FTANGLE{}

This is a family of options that set miscellaneous flags appropriate
only for @FTANGLE{}. 

@menu
* -TD::         Permit processing of deferred macro definitions.
* -Tb::         Permit built-functions such as @code{$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 @samp{#line} command after @samp{@@%}.        
@end menu

@node -TD, -Tb, -T_, -T_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-TD}:  Permit processing of deferred macro definitions

@findex -TD
@cindex Macros, deferred
@dfn{Deferred macro definitions} are @samp{@@m} (or, equivalently,
@samp{@@#define}) commands that appear in the code part rather than
the usual definition part.  These definitions are evaluated during the
output (phase 2), and can cause confusion when used with the
preprocessor commands, which are evaluated during the input (phase 1).
Because of this confusion, deferred macro definitions are prohibited by
default.  To permit them, use the @samp{-TD} option (then be prepared
to make some obscure programming errors).

@node -Tb, -Tm, -TD, -T_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-Tb}:  Permit built-functions to be redefined

@findex -Tb
@cindex built-in functions, redefining

By default, built-in functions such as @code{$IF} (@pxref{Built-in functions})
may not be redefined by an @code{@@m} command.  To allow this extremely
dangerous operation, use the @samp{-Tb} option.

@node -Tm, -Tv, -Tb, -T_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-Tm}:  Permit user macros to be redefined

@findex -Tm
@cindex macros, redefining

By default, user macros may not be redefined by an @code{@@m} command.
To permit this, use the @samp{-Tm} option.  Note that many functions
described under @ref{Built-in functions}, such as @code{$PI}, are in fact
implemented as macros.

@node -Tv, -T%, -Tm, -T_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-Tv}: Don't print header info

@findex -Tv
@cindex Header comments, printing
By default, @FTANGLE{} attempts to be helpful and writes some
information about the command line, input and change files, etc.@ at the
beginning of the output file.  This information can be deleted by means
of the @samp{-Tv} flag.  [This is done automatically when the @samp{-F}
flag (@pxref{-F_}) is in effect, since the header information includes a
time stamp that would defeat a successful file comparison.]

@node -T%, -T#, -Tv, -T_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-T%}:  Don't retain trailing comments (@TeX{})

@findex -T%
@cindex Comments, @TeX{}
Unless the @samp{-v} option is used, comments are generally deleted by
@FTANGLE{} as it writes the output file.  However, in the @TeX{}
language such deletions can change the behavior of the output (by
introducing extra spaces).  Therefore, @TeX{} comments that do not
begin a line are always retained unless the @samp{-T%} option is used.
This option has no effect for languages other than @TeX{}.

@node -T#, , -T%, -T_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-T#}:  Don't insert @samp{#line} command after @samp{@@%}

@findex -T#
If the @samp{@@%} command (@pxref{AT%}) is used to comment out a line,
it eats the trailing newline.  An undesirable consequence of this is
that, if nothing is done, the subsequent line numbering will be
misunderstood by a debugger, at least until @FWEB{} inserts a
@samp{#line} command for some reason.  To prevent this, @FWEB{}
inserts by default an implicit @samp{@@#line} command
(@pxref{Preprocessing}) after each @samp{@@%} that begins a line.  To
prevent this from happening (possibly because the feature doesn't work
correctly, in which case you should report it; @pxref{Support}), use the
@samp{-T#} option. 

@node -t, -U_, -T_, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-t}:  Truncate identifiers

@findex -t
@cindex Identifiers, truncating
The truncation option enables one to use a wider character set for
identifiers than the language compiler will accept.  The standard
example is vanilla-flavored @sc{Fortran}-77, which doesn't allow the underscore.
If one says @samp{`-tn6@{_@}}', underscores will be removed from all
identifiers, then the result will be truncated to length 6.  If the
truncation procedure results in non-unique identifiers, these are
listed.

@node -U_, -u, -t, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-U}:  Convert reserved output tokens to lower case (@FTANGLE{})

@findex -U
@cindex Tokens, upper-case
Particularly during @sc{Ratfor} expansion, certain tokens such as
@samp{DO} are output by @FTANGLE{} in upper case.  The @samp{-U}
option forces such tokens to be produced in lower case.

@node -u,-V_,-U_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-u}:  Undefine @FWEB{} macro (@FTANGLE{})

@findex -u
@samp{-uA} undefines the @FWEB{} macro @samp{A} previously defined on the
command line (or in @file{.fweb}) via @samp{-m}.  

@emph{CAUTION}:  This option can also undefine built-in
functions such as @code{$IF}.  Don't do that, since built-ins can use other
built-ins behind the scenes; undefining one can cause very strange behavior.

@node -V_, -v, -u, Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-V}:  Print @FWEB{} version number

@cindex Version number
@findex -V
This flag requests the startup banner, which includes the @FWEB{}
version number, to be printed.  This is usually done anyway, so it
is only relevant when the message level is 0 (@pxref{-M_}).  

@node -v,-W_,-V_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-v}:  Make all comments verbatim (@FTANGLE{})

@findex -v
@cindex Comments, verbatim
By default, comments are not passed to the tangled output.  With @samp{-v},
all comments are included verbatim in the tangled output.  Since there's
generally no harm in this, one might want to put this option into
@file{.fweb} (@pxref{Initialization}).

@node -W_,-w,-v,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-W}:  Flag-setting options for @FWEAVE{}

@findex -W
This is a family of options that set miscellaneous flags appropriate
only for @FWEAVE{}. 
Options such as @samp{-W[} and @samp{-Wf} can be combined as @samp{-W[f}.

@menu
* -W@@: -WAT.            Set module warning flag.
* -W1::                 Completely cross-reference single-character identifiers.
* -W[::                 Turn on processing of bracketed array indices.
* -WH: -WH_.            Send extra arguments to the C preprocessor.

Commands that inhibit printing:

* -Wd: -Wnoprint.       Don't print @@d or @@D in woven output.
* -Wf: -Wnoprint.       Don't print @@f.
* -WF: -Wnoprint.       Don't print @@F.
* -Wl: -Wnoprint.       Don't print @@l.
* -Wm: -Wnoprint.       Don't print @@m or @@M.
* -Wv: -Wnoprint.       Don't print @@v.
* -Ww: -Wnoprint.       Don't print @@w or @@W.
@end menu

@node -WAT, -W1, -W_, -W_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-W@@}:  Set module warning flag.

@findex -W@@
@cindex Modules, warning level for
@cindex Warning level for modules

@FWEAVE{} can check module names for the possible anomalous conditions of
``never used'' or ``multiple uses.''  These correspond to a module
warning level, as in the following numbered list:

@enumerate
@item
Never used.

@item
Multiple uses.

@end enumerate
@noindent
The module warning flag is the bitwise OR of the desired warning
levels; warning messages are printed only when the relevant bits are
turned on.  By default, it is 1, so only messages about never-used
modules are printed.  The @samp{-W@@@i{flag}} overrides the default.
For example, to get messages only about multiple uses, say @samp{-W@@2};
to get no messages, say @samp{-W@@0}.  One can put such an option into the
@file{.fweb} initialization file (@pxref{Initialization}).

@FWEAVE{} will always complain about module names that are never defined.


@node -W1, -W[, -WAT, -W_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-W1}:  Cross-reference single-character identifiers

@findex -W1
@cindex Identifiers, single-character
By default, @FWEB{} does not index uses of single-character
identifiers (following Knuth's original design).  (It does index their
definitions.)  To get complete cross-reference information for
single-character identifiers, use the @samp{-W1} option.

@node -W[, -WH_, -W1, -W_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-W[}:  Process bracketed array indices

@findex -W[
@cindex Brackets, active
This @emph{experimental} option makes square brackets behave like
parentheses in the context of array indices.  

In @sc{Fortran}, @FTANGLE{} will just replace the brackets by parentheses.
In C, the brackets will be left alone.

@findex \WARRAY
@FWEAVE{}, however, will typeset the indices according
to the @file{fwebmac.sty} macro @samp{\WARRAY}.  This macro takes one
argument, which is just the array index or indices.  (In C, indexing
like @samp{a[i][j][k]} generates the argument @samp{i,j,k}.)  By
default, @samp{\WARRAY} just surrounds its argument with brackets.
However, the user may change its definition to get special effects such
as superscripted or subscripted indices.  A simple example macro
@samp{\WSUB} is provided in @file{fwebmac.sty}; one can say
@samp{\let\WARRAY\WSUB} in the limbo section to have bracketed indices
print as subscripts.

This feature may not work when the contents of the brackets
are too complicated (so that @FWEAVE{} tries to typeset them by going
in and out of math mode).

For more information, experts can see @file{fwebmac.web}, command @code{\WXA}.
@findex \WXA

@node -WH_, -Wnoprint, -W[, -W_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-WH}:  Send additional arguments to the C preprocessor

@findex -WH
@cindex Preprocessor, sending additional arguments to
When the @samp{-H} option (@pxref{-H_}) is used, the C preprocessor is
invoked to scan include header files for @b{typedef}'s and @b{class}
declarations.  That is called with a standard set of options.
(Presently, @code{gcc} is actually called to invoke the preprocessor; it
is sent the options @samp{-E}, @samp{-P}, and @samp{-I}.)  Occasionally
it may be necessary to send additional options.  Those can be specified
as the (string) argument to @samp{-WH}.  Thus, to define two macros to the
preprocessor, one could say either of

@example
-WH-Dtest1=1 -WH-Dtest2=2
-WH"-Dtest1=1 -Dtest2=2"
@end example
@noindent
The first form shows that @samp{-WH} accretes to earlier uses.  The
second form shows how to handle embedded blanks (in a @sc{unix} shell).
Then, if one were programming in C, use of @samp{-H} would issue the
system command 

@example
gcc -E -P -Dtest1=1 -Dtest2=2
@end example


@node -Wnoprint, , -WH_, -W_
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-WdfFlmvw}:  Don't print various things in woven output

@findex -W
The printing of selected definition-part commands can be suppressed as
follows:

@example
-Wd @r{--- outer definitions (@samp{@@d} or @samp{@@D})}
-Wf @r{--- format statements (@samp{@@f})}
-WF @r{--- format statements (@samp{@@F})}
-Wl @r{--- limbo text definitions (@samp{@@l})}
-Wm @r{--- FWEB macro definitions (@samp{@@m} or @samp{@@M})}
-Wv @r{--- operator overloads (@samp{@@v})}
-Ww @r{--- identifier overloads (@samp{@@w} or @samp{@@W})}
@end example

@noindent
When these options used, associated cross-referencing is suppressed
as well.
@cindex Cross-references, suppressing

@node -w,-x,-W_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-w}:  Change name of macro package (@FWEAVE{})

@findex -w
The option @samp{-w} means ``Don't print @samp{\input fwebmac.sty} as
the first line of the @file{.tex} output file.''  The option
@samp{-w@i{fname}} means ``Print @samp{\input fname} as the first line.''
For example, when working with REV@TeX{} (@pxref{REVTeX}), one needs to
say @samp{-wrwebmac.sty}.

This option can be used for special effects when one is trying to obtain
behavior different from that defined by @FWEB{}'s macro package
@file{fwebmac.sty} (@pxref{fwebmac.sty}).  However, try to not do that.
Please submit requests for such behavior modifications to the developer;
see @ref{Support}.

@node -x,-X_,-w,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-x}:  Eliminate or reduce cross-reference information (@FWEAVE{}). 

@findex -x
@cindex Cross-references, eliminating
Cross-reference information (for @FWEAVE{}) includes the Table of Contents
('c'), the Index ('i'), and the Module List ('m').  The option @samp{-x}
eliminates all of that information.  The option @samp{-x@i{letters}}
eliminates the piece of information corresponding to each letter in the
list.  For example, @samp{-xim} eliminates the Index and the Module List.

Another possibility is to say @samp{-xu}, which prevents
cross-references from unnamed sections (begun with @samp{@@a} or
@samp{@@A}) from appearing in the Index.

@node -X_,-y,-x,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-X}:  Print selected cross-reference information (@FWEAVE{})

@findex -X
When used with any of the arguments @samp{cim}, this option is the
opposite of @samp{-x}.  @xref{-x}. 

The option @samp{-XI} tells @FWEAVE{} to write its index
cross-references to a file formatted for input by the @code{makeindex}
utility.  This feature facilitates creation of a master index that spans
several individual @code{web} files.  For more discussion, see
@ref{Using makeindex}.

The construction @samp{-XI} stands alone; one may not mix the @samp{I}
with the list @samp{cim}.  Also, this option is overridden by
@samp{-xi}, which suppresses output of all index information.

@node -y,-Z_,-X_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-y}:  Allocate dynamic memory

@findex -y
@cindex Memory allocation
@cindex Allocation, memory
This option changes the default size for a dynamically allocated memory
buffer.  The buffers are indicated by a one- or two-character
abbreviation such as @samp{op}.  For example, the option @samp{-yop200}
allocates 200 units for the @samp{op} buffer.

To query the default allocations, just say @samp{-y}.

When @FWEB{} runs out of space, it usually (but not always) issues a
message telling one which @samp{-y} command to use in order to increase
the allocations.  (Someday it will reallocate automatically.)  One may
wish to add some such options to the @file{.fweb} file.

For a more detailed discussion of memory allocation and a menu of the
various dynamic arrays, see @ref{Memory allocation}.

@node -Z_,-z,-y,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-Z}:  Display default style-file parameters

@findex -Z
@cindex Options, information
The information option @samp{-Zabc} prints to the screen the default
contents of the style-file parameters beginning with @samp{abc}.  Just
@samp{-Z} prints everything.

After printing the defaults, the @samp{-p} options (@pxref{-p}) and the
style file @file{fweb.sty} are processed.  If that processing has
overridden any of the defaults, the parameters are printed again, 
preceded by an asterisk.

To see only the parameters that have been modified from the defaults,
say @samp{--Z}.

The @samp{-Z} option behaves slightly differently for color escape
sequences than for other parameters; see @ref{Color}.


@node -z,-.,-Z_,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-z}:  Change name of style file

@findex -z
@cindex Style file, changing name of
The command @samp{-znew.sty} changes the default style-file name
@file{fweb.sty} to @file{new.sty}.  The command @samp{-z} (with no
argument) means ``Don't read any style file.'' 

Normally the style file is read from the same directory in which the
@code{web} source file resides (or from the path defined by the
environment variable @code{FWEB_STYLE_DIR}).  To force @code{fweb.sty}
to be read from the current directory, say @samp{-z.}.

@node -.,-\,-z,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-.}:  Don't recognize dot constants

@findex -.
@cindex Dot constants, recognizing
If this command is used, the processors will not understand that
constructions such as @samp{.LT.} are operators in @sc{Fortran} or
@sc{Ratfor}.  This command is useful if one is trying to modernize the
source code to use @FWEB{} conventions such as @samp{<} instead of
@samp{.LT.}.

@node -\,-lp,-.,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-\}:  Explicitly escape continued strings

@findex -\
@cindex Strings, long
@cindex Strings, continuing
In @FWEB{}, long strings are continued with the backslash.  Normally,
the continuation of the string must start in the first column of the
next line; otherwise, spurious blanks will be introduced.  However, when
the @samp{-\} option is in effect, @FWEB{} expects that the
continuation will also begin with the backslash, and it will ignore
leading white space and the backslash.  (This feature was inspired by
@sc{Fortran}-90.)  Thus, in the example

@example
"This is \
      \continued";
@end example
@noindent
the effective string is @code{"This is continued"} when @samp{-\} is in
effect.

Note that this option affects all strings in the source file; one cannot
mix and match.

@node -lp,-colon,-\,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-(}:  Continue parenthesized strings with backslashes

@findex -(
@cindex Strings, parenthesized
This option is like @samp{-\} (@pxref{-\}), but it refers to certain
strings that are not normally quoted, such as the arguments of
@samp{ifelse} commands in @code{m4}.

@node -colon,->,-lp,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-:}:  Set starting automatic statement number

@findex -:
@cindex Statement numbers, automatic
This option is useful for @sc{Fortran} and @sc{Ratfor}.  Symbolic
statement labels that are defined with the @samp{#:0} macro command
(@ref{Tokens}; @ref{Fortran}), as in @samp{@@m EXIT #:0}, are incremented
starting with the default of 90000.  To change this to, e.g., 789, say
@samp{-:789}.

@node ->,-=,-colon,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{->}:  Redirect output (@FTANGLE{})

@findex ->
@cindex Ouput, redirecting
This changes the name of @FTANGLE{}'s output file.  If no name is
given, output is redirected to the terminal.

This command has no effect for @FWEAVE{}.  

Although the appearance of this command is highly intuitive, it may be
hard to type quickly.  An equivalent command is @samp{-=} (@pxref{-=}).

@node -=,-#,->,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-=}:  Redirect output (@FTANGLE{})

@findex -=
@cindex Ouput, redirecting
Equivalent to @samp{->} (@pxref{->}), and faster to type on many keyboards.

@node -#,-plus,-=,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-#}:  Turn off comments about line and section numbers (@FTANGLE{}) 

@findex -#
By default, tangled output includes comments about the line and section
numbers corresponding to the current piece of code.  To eliminate this
clutter, say @samp{-#}.  (But note that the line-number information is very
useful for debugging in C and C++, as it enables the debugger to display
the source line in the web file.)

In some cases, bugs in tangled output, particularly from @sc{Fortran}, can be
eliminated by using @samp{-#}.  (But please report the bug anyway;
@ref{Support}.) 

In some cases, it is useful to turn off the line- and section-number
information locally.  This can be done with the @samp{@@q} command.
@xref{ATq}.

@node -plus,-/,-#,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-+}:  Don't interpret compound assignment operators

@findex -+
@cindex Assignment operators, compound
Both @sc{Ratfor} and @sc{Fortran} attempt to translate the commands
@samp{++}, @samp{--}, @samp{+=}, @samp{-=}, @samp{*=}, and @samp{/=}
into code that behaves as their C/C++ counterparts.  To turn this feature off,
use @samp{-+}.  

@cindex Not equal
Notice that in @sc{Fortran}-90 @samp{/=} is a token for ``not equal,''
so if you want to use that you must turn off the compound assignment
operators with use @samp{-+}.  However, a better solution is to leave
them turned on and use @FWEB{}'s standard @samp{!=} token for ``not equal.''

See also @ref{-ylx}.

@node -/,-!,-plus,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-/}:  Recognize short comments (@sc{Fortran} & @sc{Ratfor})

@findex -/

@cindex Comments, short
If this command is not used with the @sc{Fortran}-like languages, the
@samp{//} construction will be interpreted 
as concatenation rather than as the beginning of a short comment.

Concatenation can be signified with @FWEB{}'s token@samp{\/}, so no
penalty is incurred for using @samp{-/}.

One way of invoking this option is with the global language command,
such as @samp{@@n/}.  Another is to put the command into the
initialization file @file{.fweb}.

See also @ref{-n/} and @ref{-r/}.

@node -!,Info options,-/,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-!}:  Make @samp{!} denote short comment (@sc{Fortran} & @sc{Ratfor})

@findex -!
@cindex Comments, short
This option is not recommended; use @FWEB{}'s standard @samp{//} to
begin short comments.

To include the exclamation point inside a string, escape it with a
backslash, as in

@example
        s = "A \! inside a string"
@end example

@node Info options,,-!,Options
@comment  node-name,  next,  previous,  up

@subsection Information options

@cindex Options, information
@cindex Information options
Several of the command-line options can be used to elicit information
about the initial state of @FWEB{}.

@quotation
@samp{-@@} displays information about the control codes. @xref{-AT}.

@samp{-D} displays information about reserved words.  @xref{-D_}.

@samp{-y} displays default dynamic memory allocations.  @xref{-y}.

@samp{-Z} displays default values of style-file parameters.  @xref{-Z_}.
@end quotation
@noindent
The @samp{-h} option reminds one about these information options; it
also provides convenient access to the GNU @code{info} browser.
@xref{-h}.

@node AT commands,Comments,Starting,Top
@comment  node-name,  next,  previous,  up

@chapter @FWEB{} COMMANDS

All @FWEB{} commands begin with the character @samp{@@}.  It is recommended
that these begin in column 1 if possible.  This is required in some
cases [e.g., the @samp{@@x}, @samp{@@y}, and @samp{@@z} in change files
(@pxref{Change files}), or column-oriented @sc{Fortran}-77 processing].

Some of these control codes may be used anywhere; others begin a new
part of the current section.  (For a discussion of sections and parts,
see @ref{Structure}.)  For a quick summary of the control-code mappings
and to see which codes begin new parts, say @samp{ftangle -@@}.
@xref{-AT}.

@menu
Debugging commands:
* @@0: AT0.     Turn off debugging.
* @@1: AT1.     Display irreducible scraps.
* @@2: AT2.     Display detailed scrap reductions.

Literal control characters:
* @@@@: ATAT.     Insert an '@@'.
* @@|: AT|.      Vertical bar/optional line break.

Beginning of section:
* @@ : ATspace.  Begin minor section.
* @@*: AT*.      Begin major section.

Beginning of code part:
* @@<: AT<.      Begin module name.
* @@>: AT>.      End module name.
* @@A: ATA_.     Begin code part.
* @@a: ATa.      Begin code part and mark next identifier.

Control codes b--z:
* @@B: ATB_.      Insert left brace; suppress default insertion of breakpoint command.
* @@b: ATb.      Insert breakpoint command.
* @@c: ATc.      Set language to C.
* @@c++: ATcpp.  Set language to C++.
* @@D: ATD_.     Define outer macro.
* @@d: ATd.      Define outer macro and mark it.
* @@E: ATE_.     Treat next identifier as ordinary expression.
* @@e: ATe.      Invisible expression.
* @@f: ATf.      Format identifier or module name.
* @@I: ATI_.     Include a WEB file, but don't print it.
* @@i: ATi.      Include a WEB file.
* @@K: ATK_.     Expand global RCS-like keyword.
* @@k: ATk.      Expand local RCS-like keyword.
* @@L: ATL_.     Set language.
* @@l: ATl.      Specify limbo text.
* @@M: ATM_.     Define an @FWEB{} macro.
* @@m: ATm.      Define a @FWEB{} macro and mark it.
* @@N: ATN_.     Turn on language-independent mode.
* @@n: ATn.      Set language to Fortran--77.
* @@n9:ATn9.     Set language to Fortran--90.
* @@O: ATO_.     Open new output file (global scope).
* @@o: ATo.      Open new output file (local scope).
* @@q: ATq.      Turn off or on module and line information locally.
* @@R: ATR_.     Treat next identifier as integer-like reserved word.
* @@r: ATr.      Set language to Ratfor--77.
* @@r9: ATr9.    Set language to Ratfor--90.
* @@u: ATu.      Undefine an outer macro.
* @@v: ATv.      Overload an operator.
* @@W: ATW_.     Overload an identifier.
* @@x: ATx.      Terminate ignorable material.
* @@y: ATy.	 End first part of change.
* @@z: ATz.      Begin ignorable material.

Conversion to ASCII:
* @@': ATquote.     Convert single character to ASCII.
* @@": ATdquote.         Convert string to ASCII.

Forward referencing:
* @@[: AT[.         Mark next identifier as defined in this section.

Comments:
* @@/*: AT/*.        Begin a long verbatim comment.
* @@//: AT//.        Begin a short verbatim comment.
* @@%: AT%.          Ignore everything to next newline.
* @@?: AT?.          Begin a compiler directive.
* @@(: ATlp.         Begin a meta-comment.
* @@): AT).          End a meta-comment.

Special brace:
* @@@{: ATlb.       Insert left brace; suppress newlines in pretty-printing.

Index entries:
* @@_: AT_.         Force an index entry to be underlined (marked as defined).
* @@-: AT-.         Delete index entry for following identifier.
* @@+: ATplus.      Force index entry for following identifier.
* @@^: AT^.         Make index entry in Roman type.
* @@.: ATdot.       Make index entry in typewriter type.
* @@9: AT9.         Make index entry in format controlled by `\9'.

Control text:
* @@t: ATt.         Put control text into TeX \hbox.
* @@=: AT=.         Pass control text verbatim to the output.

Spacing:
* @@comma: ATcomma. Insert a thin space.
* @@/: AT/.         Insert a line break, preserving indentation.
* @@\: ATbs.         Insert a line break and backspace.
* @@|: AT|_.        Insert optional line break in an expression.
* @@#: AT#.         Force line break with blank line.
* @@~: AT~.         Cancel a line break (tie adjacent lines together).
* @@&: AT&.         Join left and right items.

Pseudo (invisible) operators:
* @@e: ATe.         Invisible expression.
* @@;: AT;.         Invisible semicolon.
* @@colon: ATcolon.     Invisible colon.

Miscellaneous:
* @@!: AT!.         Inhibit expansion for next macro.
@end menu

@node AT0, AT1, AT commands, AT commands
@comment  node-name,  next,  previous,  up

@section Debugging commands

Several commands provide localized versions of the @samp{-1} and
@samp{-2} options related to debugging of pretty-printing.

@subsection @samp{@@0}:  Turn off debugging

@findex @@0
@cindex Debugging
This cancels the effect of a previous @samp{@@1} or @samp{@@2}
(see @ref{AT1} and @ref{AT2}).  The @samp{@@0} command should appear in a
different section from the @samp{@@1} or @samp{@@2} commands.

@node AT1, AT2, AT0, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@1}:  Display irreducible scraps

@findex @@1
@cindex Debugging
This is a local version of the command-line option @samp{-1}
(@pxref{-1}); refer to that discussion for more information. 

@node AT2, ATAT, AT1, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@2}:  Display detailed reductions of the scraps

@findex @@2
@cindex Debugging
This is a local version of the command-line option @samp{-2}
(@pxref{-2}); refer to that discussion for more information. 

@node ATAT, AT|, AT2, AT commands
@comment  node-name,  next,  previous,  up

@section Literal control characters

Several commands insert specific characters.

@subsection @samp{@@@@}:  The character @samp{@@}

@findex @@@@
@samp{@@@@} inserts the single character @samp{@@}.

Don't forget to double the @samp{@@} even inside strings.  For example,
the @FWEB{} source line

@example
puts("'@@@@' is represented by `@@@@@@@@'");
@end example

@noindent
will be tangled to

@example
puts("'@@' is represented by `@@@@'");
@end example

@node AT|,ATspace,ATAT,AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@|}:  Literal vertical bar, or optional line break

@findex @@|
@cindex Bar, vertical
@cindex Vertical bar
In the @TeX{} (documentation) part of a section, @samp{@@|} inserts a
vertical bar.  This is useful inside La@TeX{} verbatim environments.  (A
simple bar would signal a shift into code mode, which is probably not
what one wants.)  For an example, see @ref{AT|_}.

@cindex Line break, optional
In a code part, @samp{@@|} inserts an optional line break in an
expression---e.g., 

@example
@samp{f(a,b,@@|c+d,...)}.
@end example
@noindent
This helps @TeX{} to break the line at an appropriate place.  If the
line does not need to be broken, the command does nothing.  [Compare
@samp{@@|} with @samp{@@\} (@pxref{ATbs}) and @samp{@@/} (@pxref{AT/}),
which always break the line.]

@node ATspace, AT*, AT|, AT commands
@comment  node-name,  next,  previous,  up

@section Beginning of section

Sections are begun by either @samp{@@*} or @ASP{}.

@subsection @samp{@@ }:  Begin minor section

@findex @@ 
@cindex Section, beginning minor
@ASP{}@ begins a new minor (unstarred or unnamed) section that is not entered
into the Table of Contents.  For example,

@example
@@ This is an example of a minor (unnamed) section.  (No entry is made
in the Table of Contents.)

@@a
main()
@{@}
@end example

@node AT*, AT<, ATspace, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@*}, @samp{@@*@i{n}}:  Begin major section

@findex @@*
@cindex Section, beginning major
@cindex Major section, beginning
@cindex Table of contents, entries for
@samp{@@*} begins a new major (starred) section (of level 0).  The
command must be followed by the name of the section (entry in the Table
of Contents), followed by a period.  (If a period appears in the name
itself, it must be protected by braces.)

@cindex Major section, optional argument for
@cindex Section names, long
@cindex Section names, short
The section name is also used as a running head on the output pages.  To
deal with the possibility that the full name may be too long, the
section name may be preceded by an optional argument enclosed in
brackets.  If it is present, the optional argument is used as the
running head.  (If a period appears as part of the optional argument, it
must be protected by braces.)

@cindex Subsection, beginning major
@cindex Major subsection
If @samp{@@*} is followed by a digit @i{n}, it begins a new major
(sub)section of level @i{n}.  This is also entered into the Table of Contents.
Thus, the complete syntax to begin a major section is

@example
@@*@i{n} [Short name]Full name.
@end example

For example,

@example
@@* MAIN PROGRAM.  This begins a major section (of level 0).

@@a
main()
@{@}

@@*1 [Input routines\dots]A very long section name that essentially
means ``input routines.''  Now follow some subroutines. 

@@a
get_input()
@{@}
@end example

For La@TeX{}, the highest permissible major level is 2 (a subsubsection).

Section names can contain reasonably arbitrary @TeX{} text, including
font-changing commands and other macros.  However, it is necessary to
understand that @emph{fragile} commands (in the sense of La@TeX{}) may
not work because the section name is used in various contexts (e.g., as
a page header).   If a macro in a section name doesn't work properly,
try preceding it with @samp{\protect}.

@FWEAVE{} converts @samp{@@*} commands to section numbers.  For a
discussion of section numbering, see @ref{Numbering}.

@node AT<, AT>, AT*, AT commands
@comment  node-name,  next,  previous,  up

@section Beginning of code part

The code part is begun by the appearance of either @samp{@@a} or
@samp{@@< @i{Module name} @@>=}.

@subsection @samp{@@<}:  Begin module name

@findex @@<
@cindex Module name, beginning
@samp{@@<} begins a module name, which has the form
@samp{@@< @i{@TeX{} text} @@>}.  (Module names inside @FWEB{} macro definitions
begin with @samp{@@#}, not @samp{@@<}.)

@node AT>, ATA_, AT<, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@>}:  End module name

@findex @@>
@cindex Module name, ending
@samp{@@>} ends a module name, of the form @samp{@@< @i{@TeX{} text} @@>}.

Technically, @samp{@@>} is not a command; rather, it is a delimiter
that terminates @samp{@@<}.  An unmatched @samp{@@>} is simply ignored
(after a warning message is issued).

@node ATA_, ATa, AT>, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@A}:  Begin code part of unnamed section

@findex @@A
@cindex Code part, beginning unnamed
@samp{@@A} begins the code part of an unnamed section.  For example,

@example
@@ In an unnamed section, the code part begins with @samp{@@a} or @samp{@@A}.
@@A
main()
@{@}
@end example

For more discussion of the distinction between @samp{@@A} and
@samp{@@a}, see @ref{ATa}.

@node ATa, ATB_, ATA_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@a}:  Begin code part of unnamed section, and mark

@findex @@a
@cindex Code part, beginning unnamed
@samp{@@a} begins the code part of an unnamed section (just as does
@samp{@@A}), and in addition marks the next unreserved identifier it
finds as defined in this section.  Precisely,

@example
@samp{@@a} == @samp{@@A@@[}
@end example

Originally, @FWEB{} did not contain the @samp{@@A} command, so when
the functionality of automatically marking the next unreserved
identifier (@pxref{AT[}) was added, it was natural to add it to @samp{@@a}.  A
reasonable style of coding is to always use @samp{@@a} if you don't know
any better; if you sometime run into trouble, you can then change
selected @samp{@@a}s to @samp{@@A}s.  For example, it is appropriate to
use @samp{@@a} if one codes one function per section.  E.g.,

@example
@@c
@@ 
@@a
int
subrtn()
@{@}
@end example
@noindent
Here the @samp{@@a} marks @samp{subrtn} as defined in this section; if
that identifier is used elsewhere, it will be subscripted with the
section number.  (To turn this feature off, use @samp{-f}; see @ref{-f}.)
However, if a section contains an arbitrary code fragment, the code part should
probably begin with @samp{@@A}.  E.g.,

@example
@@c
@@
@@A
x = y;
@end example
@noindent
If one had used @samp{@@a} here, the @code{x} would have been marked as
defined here, which is not what one wants.  


@node ATB_, ATb, ATa, AT commands
@comment  node-name,  next,  previous,  up

@section Control codes b--z

@subsection @samp{@@B}:  Suppress insertion of breakpoint command

@findex @@B
@cindex Breakpoints, suppressing
@cindex Left brace, inserting
This is for detailed debugging of @FWEB{} codes.  It inserts a left
brace and suppresses the insertion of a breakpoint command.  See the
discussion of @samp{@@b} in @ref{ATb}.

@node ATb, ATc, ATB_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@b}:  Insert a breakpoint command

@findex @@b
@cindex Breakpoints, inserting
(Discussion to be finished.  Useful only for very intimate debugging of
@FWEB{} codes.  In these days of safe sex, such intimacy may not be
desirable.)

See also @ref{ATB_}.

@node ATc, ATcpp, ATb, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@c}:  Set language to C

@findex @@c
The command @samp{@@c} is a shorthand for @samp{@@Lc}.  For a discussion
of language commands in limbo, see @ref{ATL_}.

@xref{Languages} and @ref{C}.

@node ATcpp, ATD_, ATc, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@c++}:  Set language to C++

@findex @@c++
The command @samp{@@c++} is a shorthand for @samp{@@Lc++}.  For a discussion
of language commands in limbo, see @ref{ATL_}.

@xref{Languages} and @ref{Cpp}.

@node ATD_, ATd, ATcpp, AT commands
@comment  node-name,  next,  previous,  up

@findex @@D
@cindex Outer macro, defining
@subsection @samp{@@D}:  Define outer macro

@emph{This command begins the definition part.}

@samp{@@D} defines an outer macro.  For more discussion, see @ref{Outer macros}.
For example, in C

@example
@@D A 1
@end example
@noindent
will be tangled to the beginning of the output file as @samp{#define A 1}.

@node ATd, ATE_, ATD_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@d}:  Define outer macro, and mark

@findex @@d
@emph{This command begins the definition part.}

@samp{@@d} defines an outer macro (just as @samp{@@D} does), and also marks the
next identifier as defined in the present section.  It is equivalent to 

@quotation
@samp{@@d} == @samp{@@D@@[}
@end quotation

@noindent
(@pxref{AT[}).

The distinction between @samp{@@d} and @samp{@@D} is analagous to the
distinction between @samp{@@a} and @samp{@@A}.  @xref{ATa}.

@node ATE_, ATf, ATd, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@E}:  Treat next identifier as ordinary expression (@FWEAVE{})

@findex @@E
For formatting purposes, treat the next identifier as an ordinary
expression.

This command is useful in pretty-printing certain kinds of macro
constructions.  Further discussion is given in @ref{Macros and
formatting}.  

@node ATf, ATi, ATE_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@f}:  Format identifier or module name

@findex @@f
@cindex Identifier, formatting
@emph{This command begins the definition part.}

The construction

@example
@@f identifier old_identifier
@end example

@noindent
makes @FWEAVE{} treat @i{identifier} like @i{old_identifier}.  For example,

@example
@@f mytype int
@end example

@noindent
says to treat the variable @code{mytype} just as @code{int} is treated
(e.g., as a reserved word in C or C++).

Traditionally, C programmers needed to use this command to format
identifiers that were defined in @code{#include} files.  This annoying
redundancy has now been eliminated by means of the @samp{-H} command,
which tells @FWEAVE{} to scan @code{#include} files automatically.
@xref{-H_}. 

The @i{old_identifier} may be one of the following special names, which
insert extra spaces according to the positions of the underscores and
behave as the part of speech indicated by the base names:

@example
$_BINOP_
$_COMMA_
$_EXPR
$_EXPR_
$EXPR_
$UNOP_
@end example
@noindent
These are useful for dealing with certain macro constructions.  For
example,

@example
@@f PLUS $_BINOP_
@@m PLUS +
@@m ADD(x, y) ((x) PLUS (y))
@end example
@noindent
Without the format command, the @samp{ADD} macro will pretty-print
without spaces before and after the @samp{PLUS}.  

When the current language is @TeX{}, the format command can be used to
change a category code according to the format

@example
@@f `TeXchar new_cat_code
@end example

@noindent
Difficulties may ensue if one try to change the category code of
@samp{@@} in this way; a fully operational @sc{web} for @TeX{} is quite
difficult and has been neither accomplished nor attempted.

@node ATi, ATI_, ATf, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@i}:  Include file (unconditional)

@findex @@i
@cindex File, including web
If one says

@example
@@i test.hweb
@end example

@noindent
the file @file{test.hweb} is inserted at the present point of the web file.  By
default, the current directory is searched.  Files can be included from
other directories by means of the @code{FWEB_INCLUDES} environment variable
and/or the @samp{-I} command-line option.  
See @ref{Environment variables} and @ref{-I_}.

In principle, the included file may contain any fragment of source text.
However, it is best to make it a complete section (begun by @samp{@@*}
or @ASP{}) if at all possible.

Unfortunately, the @samp{@@i} command cannot be commented out or
conditionally included by use of an @FWEB{} preprocessor command.
That is because @samp{@@i} is processed very early in the parsing
process.  (Consider:  @samp{@@i} could include @TeX{} text, but the
preprocessor is only active in the definition and code parts.)

Include commands may be nested to a depth set by the option
@samp{-yid}.  @xref{-yid}.

@cindex Include file, printing name of
@findex \WIF
@cindex Include file, formatting name of
@findex \WIFfmt
In the woven output, if a section comes from an include file, the name
of the include file is printed in square brackets as the first text of
the @TeX{} part.  To inhibit printing of that name, say

@example
\def\WIF#1@{@}
@end example
@noindent
in the limbo section.  To change the way that name is formatted,
redefine the macro @samp{\WIFfmt}, whose single argument is the name of
the include file.  (It is not called when there is no current include
file.)  The default definition is 

@example
\def\WIFfmt#1@{[@{\tt#1@}]@}
@end example


@node ATI_, ATK_, ATi, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@I}:  Include file (conditional)

@findex @@I
@cindex File, including web
This command behaves like @samp{@@i} if the command-line option
@samp{-i} is not used.  If it is used, then the contents of the included
file is not printed in the woven output.  
@xref{-i} and @ref{-i!}.

@node ATK_, ATk, ATI_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@K}:  Extract global RCS-like keyword

The construction @samp{@@K @i{Keyword} @@>} accesses the value of a global
RCS-like keyword.  (For more discussion of such keywords, see @ref{ATz}.)
The command is treated differently by @FTANGLE{} and @FWEAVE{}
depending on its location in the source file.

@FWEAVE{} will expand the construction
in the limbo section and @TeX{} parts only.  The value is not surrounded
by quotes.  For 
example,

@example
@@z
$Id:  test $
@@x

@@c

\def\ID@{Id = \.@{"@@K Id @@>"@}@}

@@ \ID.  This is a @@K Id @@>.
@end example
@noindent
will expand into

@example
@@c

@@ \ID.  This is a test.
@end example
@noindent
and when La@TeX{} is run the macro @code{\ID} will expand to @samp{Id =
\.@{"Test"@}}.  The quotes are not necessary in the macro definition;
they are included only to emphasize that in this (limbo) context the
@samp{@@K} construction can effectively be put inside a string.  This is
possible because the routine that copies the limbo section simply copies
characters; it does not tokenize anything.

@FWEAVE{} does not expand @samp{@@K} constructions in the definition
or code parts; it merely gives them a symbolic representation.

@FTANGLE{}, on the other hand, expands @samp{@@K} constructions in the
definition or code parts (during input).  The values are surrounded by
quotes.  (As usual, @FTANGLE{} ignores material in the limbo section
and @TeX{} parts.)

For @FTANGLE{}, the built-in function @samp{$KEYWORD}
(@pxref{$KEYWORD}) behaves essentially as does @samp{@@K}, except that
it is expanded during output, not input.  @FWEAVE{} does not expand
@samp{$KEYWORD}.

The command @samp{@@k} behaves as does @samp{@@K} except that it
accesses local keywords, not global ones.  @xref{ATk}.

@node ATk, ATL_, ATK_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@k}:  Access local RCS-like keyword

The construction @samp{@@k keyword} behaves as @samp{@@K} does
(@pxref{ATK_}), except it accesses local keywords (defined at the top of
include files).

@node ATL_, ATl, ATk, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@L}:  Set language

@findex @@L
@cindex Language, setting
@samp{@@Ll} sets the language to @i{l}, where @i{l} is one of
@samp{@{c,c++,n,n9,r,r9,v,x@}}. 
@xref{Languages}.

There are shorthand forms of this command for some languages; see
@samp{@@c} (@ref{ATc}), @samp{@@c++} (@ref{ATcpp}), @samp{@@n}
(@ref{ATn}), @samp{@@n9} (@ref{ATn9}), @samp{@@r} (@ref{ATr}), and
@samp{@@r9} (@ref{ATr9}).

Generally, the global language should be set in the limbo section by
means of @samp{@@L}, @samp{@@c}, etc.@  rather on the command line by
options such as @samp{-L} or @samp{-c}.

@node ATl, ATM_, ATL_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@l}:  Specify limbo text

@findex @@l
@emph{This command begins the definition part.}

Limbo text is material that @FWEAVE{} should output before
the start of the first section.  
@cindex Limbo text
For example,

@example
@@l "\\def\\A@{abc@}"
@end example
@noindent
Note that @samp{\\} stands for a backslash.  In general, characters must be
escaped just as in C [so that one can include things like @samp{\n}
(newline) in the definitions].

Limbo text may also be typed directly into the limbo section; in that
case, no escapes are necessary since one is typing ordinary @TeX{} text.
Sometimes, however, the @samp{@@l} command is useful for pedagogical
purposes, as the limbo material can then be defined at the point where
the logical discussion is made.

@node ATM_, ATm, ATl, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@M}:  Define @FWEB{} macro

@findex @@M
@emph{This command begins the definition part.}

For a detailed discussion of @FWEB{} macros, see @ref{Macros}.

@node ATm, ATN_, ATM_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@m}:  Define @FWEB{} macro, and mark

@findex @@m
@emph{This command begins the definition part.}

@samp{@@m} defines an @FWEB{} macro, and also marks the next identifier
as defined here.  It is equivalent to

@quotation
@samp{@@m} == @samp{@@M@@[}
@end quotation
@noindent
(@pxref{AT[}).

For a detailed discussion of @FWEB{} macros, see @ref{Macros}.

The distinction between @samp{@@m} and @samp{@@M} is analagous to the
distinction between @samp{@@a} and @samp{@@A}.  @xref{ATa}.

@node ATN_, ATn, ATm, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@N}:  Turn on N mode

@findex @@N
@emph{This command must appear before the code part.}  Generally, this
means immediately before @samp{@@a}.  @emph{Do not use this command in
limbo; use @samp{@@Lv} instead.}

The N mode invokes language-independent behavior within the scope of
a particular language.  The scoping rules are the same as for language
changes; i.e., using @samp{@@N} within a given section produces
language-independent behavior for that section and for any modules first
referenced in that section.  

Fundamentally, @dfn{language-independent} behavior essentially means a literal
transcription of the input to the output.  For example, it inhibits
blank compression by @FTANGLE{} and tells @FWEAVE{} to turn off
``pretty-printing'' (instead, the output is printed in typewriter type
within a @samp{\begin@{verbatim@}...\end@{verbatim@}} environment).

There are some subtleties with this mode (not to mention the likelihood
of bugs):

@enumerate
@item
@FWEB{} macros and built-in
functions will normally be expanded even in the N mode.  To inhibit
expansion of a particular identifier, place @samp{@@!} before the
identifier.  For example, 

@example
@@
@@m A 1
@@N
@@a
@@!A = A;
@end example

@noindent
expands to @samp{A = 1}.  

@item
Blank lines are significant.  The N mode is ended by the appearance of
the @samp{@@*} or @ASP{} denoting the start of the next section.  If
that were preceded by one or more blank lines, those would show up in
both the tangled and woven output.  They might or might not be
significant in the tangled output, but they almost certainly will look
ugly in the woven output.  To avoid this, use the command @samp{@@%%},
which deletes the remainder of the current line and all immediately
following empty lines.  For example,

@example
@@
@@N
@@a
x;@@%%



@@ Next section.
@end example

@item
If the N mode is invoked from a compiler-like language such as @sc{Fortran},
cross-referencing of variables is done as usual.  However, if the
language is @sc{verbatim} (which turns on the N mode automatically), no
cross-referencing is done.  (Identifiers are still recognized according
to @FWEB{}'s rules.  Those rules as currently implemented may be
essentially meaningless for some languages; in the future, provision may
be made for generalizing these rules by the user.)  To force an
identifier to be placed into the Index, precede it by @samp{@@+}.

@item
A  module name must be within the scope of an @samp{@@N} the first time
the name is seen, if it is ever to be within such scope.  Thus, the
following does not work properly:

@example
@@ Consider the module @@<Test@@>.  (Not yet within scope of \.@{@@N@}.)
@@N
@@a
x;
@@<Test@@>@@;
y;
@end example
@noindent
What happens is that the N mode is not restored after the code-part use
of @samp{@@<Test@@>}.  This is a bug.  There are very tricky design
issues to be dealt with here.

@end enumerate

@node ATn, ATn9, ATN_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@n}:  Set language to @sc{Fortran}--77

@findex @@n
@sc{Fortran}-77 is @FWEB{}'s default language, so this command is usually not
strictly necessary.  However, it is good practice to include it, so a
user looking at the @code{web} file can tell immediately what language
it is supposed to process.

For more discussion of languages, see @ref{ATL_} and @ref{Languages}.

@node ATn9, ATO_, ATn, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@n9}:  Set language to @sc{Fortran}--90

@findex @@n9
For more discussion of languages, see @ref{ATL_} and @ref{Languages}.

For hints about @FWEB{} programming in @sc{Fortran}, see @ref{Fortran}.

@node ATO_, ATo, ATn9, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@O}:  Open output file (global scope)

@findex @@O
@cindex File, opening output
A statement of the form

@example
@@O @i{new_output_file_name}
@end example

@noindent
changes the name of @FTANGLE{}'s output file.  This change remains
in effect for the duration of the file, or until another @samp{@@O} is
encountered.  (If that occurs, the previously open file is closed.)

This command is expanded during output, so it must appear in the code part. 

For an example of using the @samp{@@O} command to produce both C header
files (@samp{.h}) and source files (@samp{.c}), see the discussion in
@ref{Outer macros}. 

To change the name of the output file locally (for just the present
section), see @ref{ATo}. 

@node ATo, ATq, ATO_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@o}:  Open output file (local scope)

@findex @@o
@cindex File, opening output
This behaves like @samp{@@O}, except that the new file name is in effect only
for the current section.  A subsequent @samp{@@o} issued in a different
section but for the same file name accretes material to the file.  

An annoying problem arises in C programming when @samp{@@o}s are used to create
multiple source files that are subsequently compiled under the control
of a @code{Makefile}.  Remember that by default line-number information
is written into the C files.  This means that a change in the @code{web}
file code for one source file can affect all of the others, because the
line numbering in the @code{web} file changes.  Therefore, a trivial change to
the code for just one source file can cause all of the others to be
recompiled.

As long as one desires debugging information relative to the original
@code{web} file, there is really no solution to this problem; one needs
the proper line information in each file in order to work with the
debugger, so if line numbers change the sources must be recompiled.  One
can, of course, turn off the line numbering with the command-line option
@samp{-#} (@pxref{-#}), but then debugger statements will refer to the
tangled C code, which is undesirable.  A better partial solution is to
use @samp{@@q} (@pxref{ATq}) to turn off the line numbering for output
code that is currently stable.  In the following example, the code for
each file is put into a module, then the modules are output in the
unnamed section; it is assumed that the programmer is currently
making changes to the code for @file{file2.c}:

@example
@@
@@a
@@q0
@@o file1.c
        @@<File 1@@>@@;
@@q1
@@o file2.c
        @@<File 2@@>@@;
@@q0
@@o file3.c
        @@<File 3@@>@@;
@end example

For very large projects, another solution is to maintain multiple
@code{web} source files.  To avoid losing the substantial benefits of
the automatic index, refer to the discussion in @ref{Merging indexes} to
learn how to create a master index that contains information about
several @code{web} files. 


@node ATq, ATR_, ATo, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@q}:  Turn off module and line info locally

@findex @@q
@cindex Line numbering, turning off
The command-line option @samp{-#} (@pxref{-#}) turns off comments about
module and line numbers globally, for the entire code.  However, in some
cases one wants to turn that off in just a small block of code.  One
important example arises in @sc{Fortran}.  Consider

@example
@@
@@a
      x = @@<Some action@@>

@@
@@<Some action@@>=
y + z
@end example
@noindent
This example will tangle to something like

@example
      x = 
C* 1: *
*line 20 "test.web"
      y + z
C* :1 *
*line 5 "test.web"
@end example
@noindent
Unfortunately, the information comments have created invalid code that
will not compile.  

The @samp{@@q} command solves this problem by turning off or on the
information comments locally.  @samp{@@q0} turns them off; @samp{@@q1}
turns them on.  Thus, if one rewrites the above example as

@example
@@
@@a
@@q0
      x = @@<Some action@@>
@@q1
@end example
@noindent
it will tangle to

@example
      x = y + z
@end example
@noindent
as one desires.

For another use of the @samp{@@q} command, see @ref{ATo}.

@node ATR_, ATr, ATq, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@R}:  Treat next identifier as integer-like reserved
word (@FWEAVE{})

@findex @@R
For formatting purposes, treat the next identifier as an integer-like
reserved word.

This command is useful in pretty-printing certain kinds of macro
constructions.  Further discussion is given in @ref{Macros and
formatting}.  

@node ATr, ATr9, ATR_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@r}:  Set language to @sc{Ratfor}--77

@findex @@r
@xref{ATL_} and @ref{Languages}.

@node ATr9, ATu, ATr, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@r9}:  Set language to @sc{Ratfor}--90

@findex @@r9
@xref{ATL_} and @ref{Languages}.

@node ATu, ATv, ATr9, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@u}:  Undefine outer macro

@findex @@u
@cindex Outer macros, undefining
@emph{This command begins the definition part.}

@samp{@@u} is the inverse of @samp{@@d}.  For example, in C the command
@samp{@@u A} tangles to @samp{#undef A}. 

@node ATv, ATW_, ATu, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@v}:  Overload operator

@findex @@v
@cindex Operators, overloading
@emph{This command begins the definition part.}

@samp{@@v} is used to change the woven appearance of an operator.  If
one defines a new operator, for example by a statement such as

@example
interface operator(.BETA.)
@end example
@noindent
in @sc{Fortran}-90, one should also use an @samp{@@v} in the definition
part---for example,

@example
@@v .BETA. "\\beta" +
@end example
@noindent
For a detailed discussion of overloading (the output appearance of)
operators, see @ref{Overloading}. 

@node ATW_, ATx, ATv, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@W}:  Overload identifier

@findex @@W
@cindex Identifiers, overloading
@emph{This command begins the definition part.}

For a detailed discussion of overloading (the output appearance of)
identifiers, see @ref{Overloading}. 

@node ATx, ATy, ATW_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@x}:  Terminate ignorable material, or begin material to be changed

@findex @@x
In a change file, this command begins material to be changes; see
@ref{Change files}.  

In @code{web} source files, this command has a different use;
see the discussion of the @samp{@@z} command (@pxref{ATz}).

@node ATy, ATz, ATx, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@y}:  Begin change material

@findex @@y
The @samp{@@y} command is permitted only in change files.  @xref{Change
files}.

@node ATz, ATquote, ATy, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@z}:  Begin ignorable material, or terminate change

@findex @@z
@FWEB{} files may begin with the construction

@example
@@z
.
.
@@x
@end example

@noindent
where the @samp{@@z} occupies the very first two characters of the file, and
where the @samp{@@z} and @samp{@@x} must begin in column 1.
Material between the @samp{@@z} and @samp{@@x} is @dfn{pure commentary} and is
ignored by both processors, with one exception.

@findex @@K
@findex @@k
@findex $KEYWORD
@findex $L_KEYWORD
@cindex RCS-like keyword
@cindex Keyword, RCS-like
The exception is that an RCS-like line (RCS stands for
``revision-control system'') with syntax

@example
$Keyword: Text of Keyword $
@end example
@noindent
(at least one blank after the colon, and at least one before the last
dollar sign; @sc{unix} users, see @samp{man ident}) is parsed, and the
text of the @code{Keyword} is made 
available to the control codes @samp{@@K} (@pxref{ATK_}) and @samp{@@k}
(@pxref{ATk}) as well as to @FTANGLE{}'s built-in function @code{$KEYWORD}
(@pxref{$KEYWORD}.

A distinction is made between keywords that are found in the ignorable
commentary at the beginning of the master web file, which are called
@dfn{global keywords}, and ones that are found at the beginning of files
included via @samp{@@i}, which are called @dfn{local keywords}.

The commands that access RCS-like keywords function as follows:

@quotation
@itemize @bullet
@item
@samp{$KEYWORD(Keyword)} accesses a global keyword.  It is a built-in
function that is 
expanded by @FTANGLE{} (during output) into the quoted character
string @code{"Text of Keyword"}.

@item
@samp{@@K} and @samp{@@k} are expanded during input.  @samp{@@K}
accesses a global keyword, whereas @samp{@@k} accesses a local keyword.  

@item
In the limbo section or a @TeX{} part, @FWEAVE{} will expand @samp{@@K
Keyword @@>} into @code{Text of Keyword} (without the surrounding
quotes), and similarly for @samp{@@k}.  (The intention is that the
expanded text can be used as bodies of @TeX{} macros.)
@FWEAVE{} will also print the
values of global keywords at the end of its output, whether or not they
are referenced by @samp{@@K}.

@item
Elsewhere @FWEAVE{} will just print the keyword name itself,
surrounded by double angle brackets.  If the keyword was local
(@samp{@@k}), the brackets will carry the subscript 0.

@item
@FTANGLE{} treats the global command @samp{@@K Keyword @@>}
essentially like it does @samp{$Keyword}, except that the construction
is expanded on input rather than output.

@item
@FTANGLE{} expands the command @samp{@@k keyword @@>} on input,
generating a quoted string containing the value of the local keyword.

@end itemize
@end quotation

The command @samp{@@z} is also used in change files to end a change.
@xref{Change files}.

@node ATquote, ATdquote, ATz, AT commands
@comment  node-name,  next,  previous,  up

@section Conversion to ASCII

@cindex ASCII, converting to
Several commands are useful for generating machine-independent code.
For example, @FWEB{} works internally with the ASCII character set, so
uses these commands heavily to convert from the possibly non-ASCII
native character set of the machine on which @FWEB{} is running.

@subsection @samp{@@'}:  Convert character to ASCII

@findex @@'
The construction @samp{@@'c'} converts @samp{c} to its ASCII value.  In
C and C++, it is converted to octal; for example, @samp{@@'A'} is output
as @samp{0101}. In @sc{Fortran} and @sc{Ratfor}, it is converted to decimal; the
previous example would be output as @samp{65}.

If the native character set of one's machine is ASCII, the conversion
will not be done unless the @samp{-A} command-line option is used.
@xref{-A_}. 

@node ATdquote, AT[, ATquote, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@"}:  Convert string to ASCII

@findex @@"
The construction @samp{@@"abc"} converts the enclosed string to its ASCII
representation.  For example, in C and C++
@samp{@@"abc"} will be output as @samp{"\141\142\143"}.  

@findex ASCIIstr
In @sc{Fortran} and @sc{Ratfor}, no such simple mechanism exists in the
language, so a function call is issued.  For example, the previous
example would be output as @samp{ASCIIstr('abc')}.  The user is
responsible for defining the function @samp{ASCIIstr}.  The name of this
function can be changed by the style-file entry @samp{ASCII_fcn}.
@xref{ASCII_fcn}.

If the native character set of one's machine is ASCII, the conversion
will not be done unless the @samp{-A} command-line option is used.
@xref{-A_}. 

@node AT[, AT/*, ATdquote, AT commands
@comment  node-name,  next,  previous,  up

@section Forward referencing

@cindex References, forward

@subsection @samp{@@[}:  Mark as defined

@findex @@[
This command marks the next (non-reserved) identifier that appears after
the @samp{@@[} as being defined in the current section.  It is usually
issued automatically; for example, @samp{@@a} is equivalent to
@samp{@@A@@[}, @samp{@@d} is equivalent to @samp{@@D@@[}, and @samp{@@m}
is equivalent to @samp{@@M@@[}.

If the appropriate style-file parameter @code{mark_defined.???} is 1,
this command causes any appearance of the identifier to be subscripted
with a section number.  For more information, see @ref{Subscript params}.

The utility of this command can be seen from the characteristic
construction

@example
@@ This is section 5.
@@a @@% Issues an implicit @@[, which marks |test| as defined in section 5.
        subroutine test
        ...
        end

@@ This is section 6.
@@a
        program main
        call test // This will print as $|test|_5$.
        end
@end example

The @samp{@@[} command should be distinguished from @samp{@@_}
(@pxref{AT_}).  The  
latter causes the index entry for the identifier to be underlined; the
former possibly causes the identifier to be subscripted by a section
number.  One may wish to turn off the subscripts because they become too
cluttered; however, the underlined index entries remain useful and
unobtrusive. 

@node AT/*, AT//, AT[, AT commands
@comment  node-name,  next,  previous,  up

@section Comments

@FWEB{} supports a variety of commenting styles borrowed from C, C++,
and @TeX{}.  For more discussion, see @ref{Comments}.

@cindex Comments

@subsection @samp{@@/*}:  Begin long verbatim comment

@findex @@/*
The following comment is copied to the tangled output.  (By default,
comments are not copied.)  If you desire all comments to be so copied,
use @samp{-v}.  @xref{-v}.

@node AT//, AT%, AT/*, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@//}:  Begin short verbatim comment

@findex @@//
See the discussion of @samp{@@/*} in @ref{AT//}.

@node AT%, AT?, AT//, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@%}:  Ignorable comment

@findex @@%
@findex @@%%
@cindex Comments, ignorable
If any line in a web source code contains the command @samp{@@%}, all
remaining material on that line (to and including the newline character)
is ignored by the input driver and never processed at all.

A stronger form of this command is @samp{@@%%}.  This deletes the
current line as well any empty lines that immediately follow.  This command
is particularly useful when the N mode is in effect.  @xref{ATN_}.

Line-numbering problems can arise when these commands are used.  For a
discussion, see @ref{-T#}.

@node AT?, ATlp, AT%, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@?}:  Begin compiler directive

@findex @@?
@cindex Compiler directives
The remainder of the line is processed as a compiler directive.  Optional
material may be inserted automatically at the beginning of the tangled
output line by means of the style-file option @code{cdir_start}.
@xref{Miscellaneous params}.

@node ATlp, AT), AT?, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@(}:  Begin meta-comment

@findex @@(
Material between @samp{@@(} and @samp{@@)} is treated in the N mode.
For example,

@example
@@(
Comment 1
Comment 2
@@)
@end example

Style-file parameters allow optional material to be insert at the
beginning and end of the meta-comment, and at the beginning of each line
of output.  For more information, see the style-file parameters
beginning with @samp{meta} (@pxref{Miscellaneous params}).

@node AT), ATlb, ATlp, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@)}:  End meta-comment

@findex @@)
See the discussion of @samp{@@(}, @ref{ATlp}.

@node ATlb, AT_, AT), AT commands
@comment  node-name,  next,  previous,  up

@section Special left brace

The command @samp{@@@{} is useful in C/C++ programming to beautify some
of the pretty-printing.  It translates into a left brace, but also
suppresses the automatic insertion of newlines into the subsequent
function body or block.  This is desirable for very short functions, such
as simple constructors in C++.  For example,

@example
class C
@{
private:
        int i;

public:
        C(int i0) @@@{i = i0;@}
@}   
@end example
@noindent
Here the function will be typeset as

@example
C(int i0)
  @{ i = i0; @}
@end example
@noindent
rather than the default

@example
C(int i0)
  @{
  i = i0;
  @}
@end example

@node AT_, AT-, ATlb, AT commands
@comment  node-name,  next,  previous,  up

@section Index entries

@cindex Indexing commands
Although most information for the Index is gathered automatically, in
some situations it must be done by hand.

@subsection @samp{@@_}:  Force index entry to be underlined

@findex @@_
@cindex Index entries, underlining
This command applies to the next identifier that appears after the
@samp{@@_}.  The index entry for that identifier will be underlined.
(By convention, this means `defined' or `declared'.)

This command is usually issued automatically.  For example, the index
entries for the variables @samp{i} and @samp{j} in the C statement
@samp{int i, j;} will be underlined, since @FWEAVE{} understands
enough of the syntax to know that variables are being defined.  Macro
definitions (begun by 
@samp{@@D} or @samp{@@M}) will also be underlined automatically.

@node AT-, ATplus, AT_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@-}:  Delete index entry

@findex @@-
@cindex Index entries, deleting
This command applies to the next identifier that appears after the
@samp{@@-}; it prevents an index entry associated with that identifier
from being made.  This might be useful when the N mode is in effect.

@node ATplus, AT^, AT-, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@+}:  Force index entry

@findex @@+
@cindex Index entries, forcing
This command applies to the next identifier that appears after the
@samp{@@+}; it forces an index entry for that identifier. It is
particularly useful when the language is @sc{verbatim}, since
cross-referencing is turned off in that case.

@node AT^, ATdot, ATplus, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@^}:  Make index entry (Roman type)

@findex @@^
@cindex Index entries, Roman type
To insert one's own index entry in Roman type, say  @samp{@@^@i{My entry}@@>}.

@node ATdot, AT9, AT^, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@.}:  Make index entry (typewriter type)

@findex @@.
@cindex Index entries, typewriter type
To insert one's own index entry in typewriter type, say  @samp{@@.@i{My
entry}@@>}. 

@node AT9, ATt, ATdot, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@9}:  Make index entry (user-defined format)

@findex @@9
@cindex Index entries, user format
The construction @samp{@@9@i{Text}@@>} is used to create an index entry in a
format defined by the user.  It is associated with the macro @code{\9}, which
will be called during @TeX{}'s processing of the Index as
@code{\9@{@i{Text}@}}.  The user must define @code{\9} according to the format

@example
\def\9#1@{...@}
@end example
@noindent
where argument @samp{#1} is the text between @samp{@@9} and @samp{@@>}.
For example, to print that text in a sans serif font, say

@example
\def\9#1@{@{\sf #1@}@}
@end example
@noindent
(Note the extra level of braces to prevent the font command from propagating.)

@node ATt, AT=, AT9, AT commands
@comment  node-name,  next,  previous,  up

@section Control text

@cindex Control text
@cindex Text, control
@dfn{Control text} is material terminated by @samp{@@>}; it must be all
on one line and must not contain any @samp{@@}s.

@subsection @samp{@@t}:  Put control text into a @TeX{} \hbox (@FWEAVE{})

@findex @@t
When @FWEAVE{} sees the command @samp{@@t@i{control text}@@>}, it packages
the control text into an @code{\hbox} and ships it to the output.  This
command is ignored by @FTANGLE{}.

@node AT=, ATcomma, ATt, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@=}:  Pass control text verbatim to the output

@findex @@=
For @FTANGLE{}, the command @samp{@@=@i{control text}@@>} sends the control
text to the output exactly as input.  @FWEAVE{} highlights the control
text by drawing a box around it.

@node ATcomma, AT/, AT=, AT commands
@comment  node-name,  next,  previous,  up

@section Spacing

@cindex Spacing commands

The spacing commands are used to refine @FWEAVE{}'s pretty-printed
output.  Generally it's not necessary to bother with these until one is
putting the final touches on a code.  

@subsection @samp{@@,}:  Insert a thin space

@findex @@,
@cindex Spacing, thin space
Extra spacings are sometimes necessary when working with unusual macro
constructions.  @samp{@@,} inserts a thin space, analogous to @TeX{}'s
@code{\,}.  

An example where explicit spacing would be necessary is as follows:

@example
@@c
@@
@@m OP +
@@m A(x,y) x @@, OP @@, y

@@a
z = A(a, b);
@end example

@noindent
Without the @samp{@@,}'s, the body of the @code{A} macro will weave as
the unappealing @samp{xOPy}.  This occurs because although @code{OP} is
defined to be a binary operator, @FWEAVE{} thinks of it as just a mere
expression, and one of its fundamental production rules is to
concatenate expressions with no intervening expressions.

This demonstrates that situations arise in which one needs to override
@FWEAVE{}'s default processing.  But for the above example, there is
actually a better solution.  Instead of using the @samp{@@,}'s, include
the format command @samp{@@f OP $_BINOP_}.  @xref{ATf}.

@node AT/, ATbs, ATcomma, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@/}:  Force a line break, preserving indentation.

@findex @@/
@cindex Line break, forcing
This command is used to override @FWEAVE{}'s natural inclinations.
For example, if one wants each piece of a declaration to appear on a
separate line, one can say

@example
int@@/
  i,@@/
  j,@@/
  k;
@end example

This command preserves the natural indentation that would have happened
if @FWEAVE{} or La@TeX{} had broken a long line spontaneously.  Thus, the
declared variables are indented in the above example.  To remove that
indent, use @samp{@@\} instead.  @xref{ATbs}.

Try to use the line-break commands sparingly---i.e., let @FWEAVE{} do
the work. 
Often, if lines run together in an unexpected or unreadable way,
it's because @FWEAVE{} wasn't able to parse the relevant block of
code, perhaps because it didn't understand that some variable in an
include file has a special meaning.  In such cases, trying to fix things
with @samp{@@/} is the wrong solution.  Either use @samp{@@f}
(@pxref{ATf}) or @samp{-H} (@pxref{-H_}).

Distinguish the @samp{@@/} command from @samp{@@|} (@pxref{AT|}), which
inserts an optional breakpoint into an expression.

@node ATbs, AT|_, AT/, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@\}:  Force a line break, then indent

@findex @@\
@cindex Line break, forcing with indent
The @samp{@@\} command behaves like @samp{@@/} (@pxref{AT/}), except
that it backspaces one notch after the line break.  This usually has the
effect of undoing the natural indentation that would have been inserted
had a long line been spontaneously broken.  One common case where the
@samp{@@\} command might be used would be to put the return type of a C
function on a separate line:

@example
int @@\
main()
@{@}
@end example

It would be nice to have @FWEAVE{} do that automatically.
Unfortunately, the syntax of a function isn't recognized until the
opening braces are sensed; by that time, the declaration part of the
statement has already been processed.  This is one example of the fact
that the @FWEB{} processors are much less intelligent and sophisticated
than language compilers.  A clever (and simple) idea for getting around
this kind of problem is lacking at this point.

@node AT|_, AT#, ATbs, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@|}:  Literal vertical bar, or optional line break

@findex @@|
@cindex Bar, vertical
@cindex Vertical bar
In the @TeX{} (documentation) part of a section, @samp{@@|} inserts a
vertical bar.  Here's a La@TeX{} example:

@example
\begin@{verbatim@}
  The constructions @@|x@@| and |x| are very different.
\end@{verbatim@}
@end example

@noindent
You might wish to try this out to see what @FWEAVE{} produces.

@cindex Line break, optional
In a code part, @samp{@@|} inserts an optional line break in an expression.

@node AT#, AT~, AT|_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@#}:  Blank line

@findex @@#
@samp{@@#} forces a line break with some extra vertical white space.
However, note
that @emph{blank lines in the source are significant}, so this command should
seldom if ever be necessary.

if @samp{@@#} is immediately followed by a letter (e.g., @samp{@@#if}),
it is assumed that a preprocessor command is beginning.  @xref{Preprocessing}.


@node AT~, AT&, AT#, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@~}:  Cancel line break

@findex @@~
@cindex Line break, canceling
@samp{@@~} is analogous to @TeX{}'s @samp{~} (tie); it prevents a line
break, which @FWEAVE{} usually inserts after each complete statement
it recognizes.  For example,

@example
printf("Working..."); @@~ fflush(stdout);
x = y; @@~ break;
@end example

@node AT&, ATe, AT~, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@&}:  Join items

@findex @@&
@cindex Joining items
@cindex Items, joining
During @FWEAVE{}'s output, @samp{@@&} joins the items to either side
with no spaces or line breaks inbetween.  

This command must be distinguished from the preprocessor construction
@code{##} (paste tokens together).  In a macro definition, @samp{a##bc}
creates the single identifier @samp{abc}.  If one said @samp{a@@&bc},
two identifiers would be output with no spaces separating them.  In
simple cases, the results may look identical, but consider how things
would differ if @code{abc} were itself an @FWEB{} macro that should
itself be expanded.

@node ATe, AT;, AT&, AT commands
@comment  node-name,  next,  previous,  up

@section Pseudo (invisible) operators

@cindex Pseudo-operators
@cindex Operators, pseudo-
Pseudo- or invisible operators are ignored by @FTANGLE{} and not
printed by @FWEAVE{}; however, they retain grammatical significance
that helps out @FWEAVE{} in its attempts to understand the syntax.

@subsection @samp{@@e}:  Pseudo-expression

@cindex Pseudo-expression
@cindex Expression, pseudo
@findex @@e
@samp{@@e} is an invisible expression (`pseudo-expression')
(@pxref{Pseudo-operators}).  It is 
sometimes useful in situations where @FWEAVE{}'s pretty-printing has
broken down because it didn't properly understand the language syntax.
If, for example, @FWEAVE{} failed to properly parse the C statement

@example
p = (int (*))q;
@end example

@noindent
one might get things to work properly by saying

@example
p = (int (*@@e))q;
@end example

In this particular case, one is patching up a deficiency (all right, a
bug) in @FWEAVE{}'s ``production rules.''  (This particular bug may no
longer exist.) However, there are other situations in which the use of
@samp{@@e} might be necessary.  Consider, for example, the C macro
definition

@example
#define A(x) = x
@end example
@noindent
Here the replacement text of the macro is @samp{= x}, which by itself is
not a valid construction in C.  When the @samp{-1} or @samp{-2} options
are used, @FWEAVE{} will report an ``irreducible
scrap sequence'' in this situation (although it may typeset it correctly
anyway).  To eliminate the warning message, say instead

@example
#define A(x) @@e = x
@end example
@noindent
Now the fragment @samp{@@e = x} is interpreted as a valid expression.

@node AT;, ATcolon, ATe, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@;}:  Pseudo-semicolon

@cindex Pseudo-semicolon
@cindex Semicolon, pseudo
@findex @@;
@samp{@@;} is an invisible semicolon.  These are often used in C
programming to terminate a module name that expands to a compound
statement.  Carefully compare the uses of @samp{@@;} and @samp{;} in the
following example:

@example
@@c
@@a
if(flag)
        @@<Compound statement@@>@@;
else
        @@<Simple statement@@>;

@@ This compound statement ends with a brace, but is used as an
expression above.
@@<Com...@@>=

@{
x;
y;
@}

@@ This fragment does not end with a semicolon, so one must be 
supplied above.

@@<Sim...@@>=
z
@end example

Here is a case for which the pseudo-semicolon is not necessary.  Consider

@example
@@c
@@ The code fragment |x = y| ...
@end example
@noindent
If the @samp{-1} is turned on, one might think that @FWEAVE{} would
report an ``irreducible scrap sequence'' because @samp{x = y} is an
expression but not a complete statement.  (Turning on @samp{-2}
demonstrates this.)  However, it is not necessary to say @samp{|x = y@@;|} 
because the warning message is not issued if the parsing reduces to just
one unresolved scrap.  

On the other hand, @samp{|goto done|} does not reduce to just one
unresolved scrap, so say @samp{|goto done@@;|} in cases such as this.
@xref{Pseudo-operators}.

In some situations, pseudo-semicolons are inserted automatically.  An
important case is free-format @sc{Fortran}-90.  There the language
syntax says that newlines terminate statements (except when there's a
trailing ampersand).  However, newlines are thrown away before tokenized
text is seen by @FWEAVE{}'s parser (and in any event would just be
interpreted as white space).  Therefore, by default newlines that
terminate statements are replaced by pseudo-semicolons, so the parsing
proceeds correctly.

In the @sc{Fortran}-90 case, one could also insert pseudo-semicolons or
actual semicolons by hand, and some users prefer that.  The
possibilities are controlled by the options @samp{-n@@;} (@pxref{-nAT;})
and @samp{-n;} (@pxref{-n;}).
@findex -n@@;
@findex -n;
@cindex Pseudo-semicolons, automatic
@cindex Automatic pseudo-semicolons

@node ATcolon, AT!, AT;, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@:}:  Pseudo-colon

@cindex Pseudo-colon
@cindex Colon, pseudo
@findex @@:
@samp{@@:} is an invisible colon (@pxref{Pseudo-operators}).
It can be helpful in formatting certain C constructions correctly.  For
example, if one has a named module defined as

@example
@@<Cases@@>=
case 1:
case 2:
case 3@@: @@;
@end example

@noindent
then one can use it as a case construction followed by the usual colon,
as in

@example
switch(c)
        @{
   @@<Cases@@>: 
        stuff;
        break;
        @}
@end example

@node AT!, , ATcolon, AT commands
@comment  node-name,  next,  previous,  up

@section Miscellaneous commands

@subsection @samp{@@!}:  Inhibit macro expansion

@findex @@!
@cindex Macros, inhibiting expansion of
@FWEB{} macros and built-in functions are always expanded by default.
This may not be desirable, particularly in the N mode.  To inhibit
expansion of an individual identifier, preface it by @samp{@@!}.

@node Comments,Languages,AT commands,Top


@comment  node-name,  next,  previous,  up

@chapter COMMENTING STYLES

@FWEB{} allows a variety of commenting styles. The visible comments are in
the font @code{\cmntfont}, which defaults to @code{\mainfont}, a
ten-point Roman font.
@cindex Commenting styles
@cindex Comments

@menu
* Invisible comments::          Skipping input material.
* Visible comments::            Comments in code mode.
* Temporary comments::          Temporarily commenting out code.
@end menu

@node Invisible comments,Visible comments,Comments,Comments
@comment  node-name,  next,  previous,  up

@section Invisible comments

@cindex Comments, invisible
@table @code
@item @@z...@@x 
If a source or include file begins with @samp{@@z} (in the very first
two characters of the file), then all material is skipped until and
including a line beginning in column 1 with @samp{@@x} [except that
lines of the form @w{@samp{$Keyword: text of keyword $}} are processed; see
@ref{$KEYWORD}, @ref{ATK_} (source files), or @ref{ATk} (include
files)].

@item @@%
All material until and including the next newline is completely ignored.

@item @@%%
As @samp{@@%}, but also skip blank lines that immediately follow the current line.
@end table

For example,

@example
@@z
Author:  J. A. Krommes
@@x
@@c @@% This sets the global language to C.
@@* EXAMPLE.
@end example

@node Visible comments, Temporary comments, Invisible comments, Comments
@comment  node-name,  next,  previous,  up

@section Visible comments

@cindex Comments, visible

@samp{/* ... */} is a long comment (it may extend over several lines).

@samp{// ...} is a short comment (terminated by the next newline).

@samp{@@(...@@)} is a meta-comment.  Meta-comments are a localized form
of the N mode (@pxref{Languages}).  Tangled meta-comments are begun by
the contents of the style-file entry @samp{meta.top} and terminated by
@samp{meta.bottom}.  Each line of the meta-comment is begun by
@samp{meta.prefix}.  Woven meta-comments are begun by
@samp{meta_code.begin} and ended by @samp{meta_code.end}.
@xref{Miscellaneous params}.

@example
@@n
@@a
        program main
/* Get input. */
        call get_input // Read the parameter file.
/* Process information.  Comments like this
   can be split over several lines. */
@@(
Meta-comments provide a poor-person's alignment feature
 i --- counter
 x --- data value
@@)
        i = 1
        x = 2.0
        call exec(i,x)
        end
@end example

@emph{The use of meta-comments is not recommended;} they are only
marginally supported.  Use ordinary long comments
instead.  Inside of them, use the various powerful features of @TeX{} or
La@TeX{} (such as @code{\halign} or
@code{\begin@{verbatim@}} @code{...} @code{\end@{verbatim@}}) to format
your comment appropriately.

@node Temporary comments, , Visible comments, Comments
@comment  node-name,  next,  previous,  up

@section Temporary comments

@cindex Comments, temporary
@cindex Code, temporarily commenting out

During development, one frequently desires to temporarily comment out a
section of code.  C programmers sometimes try to do this by enclosing the 
code in @code{/*...*/}, but this is @emph{not} good
style for several reasons.  First, it is impossible if the code itself
includes comments, since comments do not nest in C.  Second, @FWEAVE{}
will treat the commented code as @TeX{} rather than C code and will (at best)
format it very poorly.  In fact, La@TeX{} will frequently complain,
because the commented code might contain characters such as underscores
that @TeX{} expects to be in math mode.  (Those are dealt with
automatically when @FWEAVE{} is in code mode.)  The trivial example 
@w{@samp{/* a_b; */}} is sufficient to illustrate this point.

The proper way of commenting out sections of code is to use preprocessor
constructions: @code{#if 0...#endif} in C, or more generally @code{@@#if
0...@@#endif} (usable in all languages).  (The @FWEB{} preprocessor is
described in @ref{Preprocessing}.)  With this method, there is no
trouble with nested comments, and @FWEAVE{} will continue to format
the code as code, so the documentation will make sense.

For @sc{Fortran} programmers converting an existing code to @FWEB{},
the @samp{-nC} option (@pxref{-nC}) may be helpful.

@node Macros,Ratfor,Languages,Top
@comment  node-name,  next,  previous,  up

@chapter MACROS and PREPROCESSING

@FWEB{} offers a built-in preprocessor facility, especially useful for
@sc{Fortran} programmers.  It is closely patterned after the C/C++
preprocessor, but with some extensions such as variable numbers of
arguments.  In addition, there are some built-in functions that provide
functionality that cannot be emulated by user-defined macros.

When working with a language such as C that has its own preprocessor,
the question arises when to use that and when to use @FWEB{}'s
facilities.  The answer generally comes with experience.  Remember that
@FWEB{}'s macros have been expanded by the time the tangled output
file is produced, whereas language-specific preprocessor commands are
just passed through to that file.  

If you're a @sc{Fortran} programmer, @emph{strongly} consider the use of
@FWEB{}'s macro facilities; they will simplify your present and future
life by creating more legible codes and reducing programming errors by
eliminating redundant pieces of code.  C/C++ programmers may also
appreciate the preprocessor extensions.

In addition to conventional macro processing, @FWEB{} also offers the
convenience of certain built-in functions that behave in many ways like
macros.  As a trivial example, the value of @PI{} is available through
the built-in function @samp{$PI}. Built-in functions are described in
@ref{Built-in functions}.  They can be useful to programmers in all languages.

@FWEB{} recognizes two kinds of macros:  @dfn{outer macros}, and @dfn{WEB
macros} (@dfn{inner macros}).  Control codes associated with either of
these kinds normally begin the definition part.  However, @FWEB{}
macros are sometimes allowed in the code part as well; see @ref{FWEB macros}.

Macros are expanded by @FTANGLE{} only; @FWEAVE{} merely prints
them as they occur in the source file.

@cindex Macros

@menu
* 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.)
@end menu

@node Outer macros,FWEB macros,Macros,Macros
@comment  node-name,  next,  previous,  up

@section Outer macros

@cindex Macros, outer
Outer macros provide a shorthand way of invoking macro definitions in
the source language; they are not expanded by @FWEB{}.  Outer macros are
defined by @samp{@@d} (@pxref{ATd}) or @samp{@@D}
(@pxref{ATD_}).  They may be placed in any definition part.  @FTANGLE{}
collects them during phase 1; during phase 2, they are simply copied in
order of their appearance to the beginning of the output file.  This is
most useful for C or C++ codes; it's a quick way of typing
@samp{#define} when the positioning of the @samp{#define} is
unimportant.

As an example,

@example
@@c
@@
@@d YES 1
@@d NO 0
@@a
main()
@{@}

@@
@@d BUF_LEN 100
@@a
...
@end example

The keyword into which the @samp{@@d} is translated is
language-dependent; it is controlled by the style-file parameter
@samp{outer_def}. @xref{Miscellaneous params}.

Outer macros can be undefined by @samp{@@u}.  The translation is
controlled by the style-file parameter @samp{outer_undef}.
@xref{Miscellaneous params}.

The default behavior, in which the outer macro definitions are just
copied to the top of the output file, is fine for simple applications.
However, often C programmers prefer to maintain their macro definitions
in a header file such as @file{test.h}.  One way of accomplishing this is to
redirect @FTANGLE{}'s output from the command line, as in
@samp{ftangle test -=test.h}, then use an @samp{@@O} command immediately
after the first @samp{@@a} in the @code{web} file to open up
@file{test.c}.  A more complicated variant of this allows additional
information to be placed into the header file, as in the following example:

@example
@@c
@@* INTRO.
We assume command-line redirection into \.@{test.h@} (`\.@{-=test.h@}').

@@d A 1 // This will go into \.@{test.h@}.

@@a
@@<Header material@@>@@; // Also goes into \.@{test.h@}.
@@O test.c // Remaining unnamed sections go into \.@{test.c@}.

@@ Header material may be defined as needed throughout the code, but
with this design it will all go into \.@{test.h@}.

@@<Header material@@>=

@@<Includes@@>@@;
@@<Typedefs@@>@@;
@@<Global variables@@>@@;

@end example

@node FWEB macros,Macros and formatting,Outer macros,Macros
@comment  node-name,  next,  previous,  up

@section @FWEB{} macros

@cindex Macros, @FWEB{}
@FWEB{} macros (sometimes called @dfn{inner macros}) are defined by
@samp{@@m} (@pxref{ATm}) or @samp{@@M} 
(@pxref{ATM_}).  These should normally be placed in the definition
part, as in 

@example
@@n
@@ Documentation...

@@m CUBE(x) (x)**3

@@a
        z3 = CUBE(x) + CUBE(y)
@end example
@noindent
(the appearance of an @samp{@@m} in the documentation part begins the
definition part).  They are collected during
@FTANGLE{}'s phase 1 and effectively placed at the top of the unnamed
section, so they are all known during the output in phase 2.

In unusual situations when macros are being conditionally defined and/or
undefined, the order of processing a macro definition becomes
significant.  If the command-line option @samp{-TD} is used, then
@FWEB{} macros may be used in the code part as well; they are then
called @dfn{deferred macros}.  These definitions will be processed during
phase 2 in the order that the code sections are processed, which may not
be the same as the physical order in the source file.  

@emph{The use of deferred macros is highly discouraged}, for the
following reason.  @FWEB{} macros are often used in conjunction with
the @FWEB{} preprocessor commands.  @emph{Preprocessor commands are
always processed during phase 1}, so they do not interact properly with
deferred macros.  It is for this reason that deferred macros are
normally prohibited from appearing in the code part.

@menu
* 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.
@end menu

@node Macro features, Tokens, FWEB macros, FWEB macros
@comment  node-name,  next,  previous,  up

@subsection Various features of @FWEB{} macros

@quotation
@itemize @bullet
@item 
Fundamentally, @FWEB{} macros follow the syntax for ANSI C.  There are
also a few extensions, notably the possibility of variable (optional) arguments
(@pxref{Variable arguments}) and some additional preprocessing tokens
(@pxref{Tokens}). 

@item
Adjacent strings in macro text are automatically concatenated.
@end itemize
@end quotation

@menu

EXTENSIONS of ANSI-C MACRO SYNTAX

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

@end menu

@node Variable arguments, Recursion, Macro features, Macro features
@comment  node-name,  next,  previous,  up

@subsubsection @FWEB{} macros with variable arguments

@cindex Macros, with variable arguments
@cindex Variable arguments
An important extension to the ANSI-C syntax is to allow macros with
variable (optional) arguments. @FWEB{} macros with a variable number of arguments
are indicated by an ellipsis, as in

@example
@@m VAR(x,y,z,...) text
@end example
@noindent
The tokens @samp{#0} (number of variable arguments), @samp{#@i{n}}
(value of the @i{n}th optional argument), and @samp{#.} (comma-delimited list of
the optional arguments) are useful in this context.

@node Recursion, Macro protection, Variable arguments, Macro features
@comment  node-name,  next,  previous,  up

@subsubsection Recursion

@cindex Recursion
ANSI C does not permit recursive macros (for good reason).  Thus, in the
example

@example
@@m recurse recurse
@end example
@noindent
the identifier @code{recurse} simply expands as `@code{recurse}', not as
an infinite loop.  However, in @FWEB{} recursion may be useful in
conjunction with some of the built-in functions 
(@pxref{Built-in functions}).  To permit a macro to be recursive, say @samp{@@m*}.  

@emph{No formal support is provided for recursive macros!}  If they
don't work, or suddenly stop working in a new release, @emph{you're on
your own}! 

@node Macro protection, , Recursion, Macro features
@comment  node-name,  next,  previous,  up

@subsubsection Protecting macros against redefinition

@cindex Macros, redefinition of
Normally an @FWEB{} macro can be redefined at will.  The example

@example
@@m PI 3.14159
@@m PI (-3)
@end example
@noindent
is permissible, but probably not a good idea.  If you want to ensure
that a crucial macro definition is never redefined inadvertently, say
@samp{@@m!}, as in

@example
@@m! PI 3.14159
@end example
@noindent
That is called @dfn{protecting} the macro.

@FWEB{}'s built-in functions and macros (beginning with @samp{$}) are
protected by default; see 
@ref{Protection}.  To override that protection, use the command-line
options @samp{-Tb} (@ref{-Tb}; for built-in functions) or @samp{-Tm}
(@ref{-Tm}; for macros).  


@node Tokens, Built-in functions, Macro features, FWEB macros
@comment  node-name,  next,  previous,  up

@subsection Special tokens

@cindex Macros, special tokens for
The following special tokens may be used in the text of @FWEB{} macro
definitions:

@subsubsection ANSI C-compatible tokens

@example 
 ##          @r{--- Paste tokens on either side to form a new identifier.}
 #@i{parameter}  @r{--- Convert parameter to string (without expansion).}
@end example

For example,

@example
@@m FORTRAN(type, name) type _##name()
@@m TRACE(where) puts("At " #where)
@@a
FORTRAN(int, fcalc); // @r{Expands to @samp{int _fcalc();}}
TRACE(predictor); // @r{Expands to @samp{puts("At " "predictor");}}
@end example

@subsubsection Extensions to ANSI C macro syntax

The most frequently used extensions are the following ones associated
with variable arguments: @samp{#0}, @samp{#@i{n}}, and @samp{#.}.
@sc{Fortran}-77 users should also employ @samp{#:0} to allow symbolic
rather than numeric statement labels.  Try not to use the other
extensions; they are experimental, complicated, and unlikely to work in
all situations. 

In the following list, the forms @samp{#@{n@}} and @samp{#[n]} may not
work correctly in complicated situations.  This is a design deficiency
that may be corrected someday.

@quotation
@table @code
@item #*@i{param} 
 Like @samp{#@i{parameter}}, but pass a quoted string through unchanged.
@item #!@i{param}
 Don't expand argument.
@item #'@i{param}
 Convert parameter to a single-quoted string (no expansion).
@item #"@i{param}
 Convert parameter to a double-quoted string (no expansion).
@item #0         
 Number of variable arguments.
@item #@i{n}     
 n-th variable argument, counting from 1.
@item #@{0@}     
 Like @samp{#0}, but the argument may be a macro expression known at run time.
@item #@{@i{n}@}       
 Like @samp{#@i{n}}, but the argument may be a macro expression.
@item #[0]       
 The total number of arguments (fixed + variable).  (The
 argument inside the brackets may be a macro expression.)
@item #[@i{n}]       
 The @i{n}th argument (including the fixed ones), counting
 from 1.  (The argument inside the brackets may be a macro expressions.
@item #.         
 Comma-separated list of all variable arguments.
@item #:0        
 Unique statement number (expanded in phase 1).
@item #:@i{nnn}      
 Unique statement number for each invocation of this macro (expanded in phase 2).
@item #<         
 Begin a module name.
@item #,         
 Internal comma; doesn't delimit macro argument.
@end table
@end quotation

A few examples of the more important of these tokens are as follows:

@example
@@c
@@m FPRINTF(fmt,...) fprintf(fp,fmt,#.) 
        // Use the whole list of variable args.
@@m B(...) printf("There were %i arguments\n", #0) 
        // Use the number of var args.

@@n
@@
@@m DONE #:0 // Symbolic statement label in @sc{Fortran}.
@@a
        goto DONE
        ...
DONE:
        call endup
@end example

@node Built-in functions, Debugging with macros, Tokens, FWEB macros
@comment  node-name,  next,  previous,  up

@subsection Built-in functions

@cindex Functions, built-in
Built-in functions behave in most ways like macros.  In some cases
they actually are macros, but other times they implement functions that a
user could not define.  They all begin with a dollar sign and are in
upper case.

In using these built-ins, confusion may arise regarding the order of
expansion of various arguments.  When they are implemented as macros,
they are subject to the same ANSI-C preprocessor rules as other
@FWEB{} macros, which is that all arguments are fully expanded before
generating the replacement text of the macro.  When they are directly
implemented as a primitive function, however, that rule may not apply.
For example, @code{$IF} expands only its first argument during its first
pass of processing; depending on the results of that expansion, it then
expands @emph{either} its second or third argument, but not both.

The built-in function @code{$DUMPDEF} can be used to understand and
debug the action of the built-in functions.  @xref{$DUMPDEF}.

In the original @FWEB{} design, built-in functions began with an
underscore.  This usage conflicts with the conventions for reserved
words in ANSI C, and has been eliminated.  @emph{All @FWEB{} built-ins
now begin with a dollar sign.}

@emph{No user-defined macro should begin with a dollar sign!}  It might
interfere with the functioning of some internal built-in function.

@menu

GENERAL INFORMATION ABOUT BUILT-IN FUNCTION DESIGN

* 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 @b{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 @code{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 @code{#} (an unquoted string).
* $PI::                 3.14159...
* $POW::                Raise to a power.
* $PP::                 The C preprocessor symbol @code{#} (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.
@end menu

@node Strings and quotes, Protection, Built-in functions, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection Strings and quotes

@cindex String, definition of
@cindex String, quoted
@cindex String, unquoted

Several of the built-in functions expect or return a string argument.
Examples include @code{$STRING} (@pxref{$STRING}), @code{$UNQUOTE}
(@pxref{$UNQUOTE}), and @code{$UNSTRING} (@pxref{$UNSTRING}). 
In understanding the operation of those functions, it is important to
understand just what a string means in the @FWEB{} context.  As usual,
it is a vector of characters.  However, @emph{those need not be
delimited by quotes}, although they may be.  Internally, a string is
represented by the construction @i{sqc...cqs}, where @i{s} is a special
string delimiter never seen by the user, @i{q} is an optional quote
character (either single or double quote depending on the language), and
@i{c} is an ordinary character.  Whether or not the quotes are present,
the string delimiters inhibit macro expansion.

The difference between @code{$UNQUOTE} and @code{$UNSTRING} can now be
stated as follows.  Given a quoted string such as @code{"abc"} (in C),

@itemize @bullet
@item
@samp{$UNQUOTE} removes the quote characters @i{q}, leaving @i{sabcs} (still a
string).

@item
@samp{$UNSTRING} removes both the quote characters @i{q} and the string
delimiters @i{s}, leaving @i{abc} (a collection of three characters).  This
collection is @emph{not} tokenized; it does @emph{not} represent the
single identifier name @code{abc} (and therefore is not very useful).
@code{$UNSTRING} is primarily used internally.  

@end itemize

The built-ins @code{$P} (@pxref{$P}) and @code{$PP} (@pxref{$PP}), which
both generate the preprocessor character @samp{#}, provide a good
illustration of the differences between @code{$UNQUOTE} and
@code{$UNSTRING}.  Consider @sc{Fortran} as an example.  Essentially,
@code{$P} is defined as @samp{$UNQUOTE('#')}, which is internally
@i{s@t{#}s}.  When this single-character string is sent to the output, it is
treated like any other expression and therefore would appear in column 7
or greater even if the construction appeared at the very beginning of
the line.  On the other hand, @code{$PP} is (essentially) defined as
@samp{$UNSTRING('#')}, which is internally the single character @t{#}.
Because this character is not a string, the @sc{Fortran} output driver
treats it as a special control character, defined in this case to force
the character into the first column.

@node Protection, $A, Strings and quotes, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection Redefining built-in functions

By default, built-in functions are @dfn{protected}---that is, they may not be
redefined by an @code{@@m} command.  (To do so cavalierly invites many
kinds of weird disasters.)  If it is absolutely necessary to redefine a
built-in function, use the command-line option @samp{-Tb} (@pxref{-Tb}).

Many of @FWEB{}'s ``built-in functions'' are in fact ordinary macros
that are implemented in terms of lower-level built-ins.  An example is
@code{$POW} (@pxref{$POW}), which is constructed from the built-in
function @code{$EVAL} (@pxref{$EVAL}).  By default, such macros are also
protected against redefinition; to override, use the option @samp{-Tm}
(@pxref{-Tm}).  

@node $A, $ABS, Protection, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$A}:  Convert to ASCII

@findex $A
@cindex ASCII, converting to
@samp{$A(@i{string})} is the built-in equivalent of @samp{@@'...'} or
@samp{@@"..."}.  (See @ref{ATquote} and @ref{ATdquote}.)
Note the extra parentheses required by the built-in.

@code{$A} first expands its argument, in case it is a macro defined as a
string.

@node $ABS,$ASSERT,$A,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$ABS}:  Absolute value

@findex $ABS
@cindex Absolute value
@cindex Macros, absolute value of
@samp{$ABS(@i{expression})} returns the absolute value of the macro
expression.  It is a macro implemented in terms of @code{$IF} and @code{$EVAL}.

@node $ASSERT,$AUTHOR,$ABS,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$ASSERT}:  Assert a condition

@findex $ASSERT
@cindex Asserting a condition
@cindex Condition, asserting
@samp{$ASSERT(@i{expression})} evaluates the macro expression.  If the
expression is false, an error message is printed and the run aborts.  

This built-in is useful for ensuring that @FWEB{} macros required by
the code are properly initialized.  Because it is expanded during the
output phase, it must appear in the @emph{code 
part} (not in the definition part).

@node $AUTHOR, $COMMENT, $ASSERT, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$AUTHOR}:  Value of RCS global keyword @code{Author}
@findex $AUTHOR
@cindex Author

Equivalent to @samp{$KEYWORD(Author)}.  @xref{$KEYWORD}.

@node $COMMENT,$DATE,$AUTHOR,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$COMMENT}:  Generate a comment

@findex $COMMENT
@cindex Comments, generating
@samp{$COMMENT}(@i{string}) generates a comment in the output file.  

This function is sometimes useful in conjunction with the processing of
@FWEB{} macros, since ordinary comments are removed when macros are
processed.  For example, if one says

@example
@@c
@@
@@m M "abc" $COMMENT("Test")
@@a
m = M
@end example
@noindent
the tangled output will be @samp{m= "abc"/* Test */}

@node $DATE,$DATE_TIME,$COMMENT,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DATE}:  Today's date

@findex $DATE
@cindex Date, generating the
@samp{$DATE} generates a string consisting of the date in the form
@code{"August 16, 2001"}.  It is implemented as a macro that calls other
macros and primitive functions.

@node $DATE_TIME, $DAY, $DATE, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DATE_TIME}:  Value of RCS global keyword @code{Date}

@findex $DATE_TIME
@cindex Date
@cindex Time
Equivalent to @samp{$KEYWORD(Date)}.  @xref{$KEYWORD}.

@node $DAY,$DECR,$DATE_TIME,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DAY}:  The day

@findex $DAY
@cindex Day, generating the
@samp{$DAY} generates a string consisting of the day of the week, such
as @code{"Monday"}.  It is implemented as a macro that calls other
macros and primitive functions.

@node $DECR,$DEFINE,$DAY,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DECR}:  Decrement a macro

@findex $DECR
@cindex Macros, decrementing
@samp{$DECR(@var{N})} redefines the numeric macro @var{N} to be one less
than its previous value.  (If @var{N} does not simplify to a number, an
error results.)  In other words, in the language of C the effect is to
say @samp{@i{N}--}.

The two-argument form @samp{$DECR(@var{N,m})} executes the equivalent of
@samp{@i{N} -= @i{m}}.

@node $DEFINE,$DO,$DECR,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DEFINE}:  Deferred macro definition

@findex $DEFINE
@cindex Macros, defining
@samp{$DEFINE} behaves like the @FWEB{} macro command @code{@@m}, but
it is intended to appear in the @emph{code} part, not the definition part (so
it is processed during @emph{output}, not input).  Thus, the code fragment

@example
a = A;
$DEFINE(A 1)@@%
a = A;
@end example
@noindent
tangles to

@example
a= A;
a= 1;
@end example
@noindent
(Notice how the @samp{@@%} command was used to kill an unwanted newline,
analogous to the @samp{dnl} macro in @code{m4}.)

In the above example, one could also say @samp{$DEFINE(A=1)}.
To define a macro with arguments, say something like
@samp{$DEFINE(A(x)x*x)}.  Do @emph{not} say @samp{$DEFINE(A(x)=x*x)}, as
in this case the equals sign will be included in the macro expansion.
One must use the equals sign as a means of preventing parentheses from
being interpreted as an argument in examples like

@example
$DEFINE(A=(x))
@end example
@noindent
This expands to @samp{(x)}.

A completely equivalent shorthand notation for @code{$DEFINE} is
@code{$M}.

@node $DO,$DUMPDEF,$DEFINE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DO}:  Macro do loop

@findex $DO
@cindex Macros, repetitively defining
@samp{$DO(@i{macro,imin,imax[,di]})@{...@}} repetitively defines
@i{macro} as would the @sc{Fortran} statement @samp{do macro =
imin,imax,di}.  For example,

@example
$DO(I,0,2)
  @{
  a[I] = I;
  @}
@end example

@noindent
generates the three statements

@example
  a[0] = 0;
  a[1] = 1;
  a[2] = 2;
@end example

In general, the macro name used as loop counter should @emph{not} be
explicitly defined as a macro prior to the @code{$DO}.  If it is not, it
will remain undefined after the end of the iteration.

Instead of the delimiting braces, parentheses may be used.  These may be
useful to help @FWEAVE{} format certain constructions correctly.

Nested delimiters are handled correctly.  The delimiters are required
even if only a single statement is to expanded.

@findex $UNROLL
@code{$DO} is implemented in terms of a command @code{$UNROLL}.
However, if one says something like @samp{$DUMPDEF($UNROLL(0,5,1))},
@FWEB{} will respond that @code{$UNROLL} is not an @FWEB{} macro.
Rather, @code{$UNROLL} is processed like expandable commands in
@sc{Ratfor} such as @code{while}.  This implies that it cannot be
redefined as ordinary macros or built-in functions can be.

@node $DUMPDEF,$E,$DO,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DUMPDEF}:  Dump macro definitions to the terminal

@findex $DUMPDEF
@cindex Debugging macros
@cindex Macros, debugging
In the call @samp{$DUMPDEF(@i{m1, m2, ...})}, @i{m1}, @i{m2}, and so on
are macro calls (with arguments if appropriate).  Two lines of output
are generated for each argument.  Line 1 is the macro definition; line 2
is its expansion using the provided arguments.

One can use this built-in to debug one's own macros, or to find out the
secrets of @FWEB{}'s built-ins.  As an example, if one says

@example
$DUMPDEF($EVAL(2^^4))@@%
@end example
@noindent
it responds with the two lines

@example
$EVAL($0) = $$EVAL($0)
$EVAL(2**4) = 16
@end example
@noindent
(The @code{$@i{n}} notation indicates the @i{n}-th argument of the macro.)
If one replaces @code{$EVAL} with @code{$$EVAL} in the above
@code{$DUMPDEF}, it will respond

@example
$$EVAL($0) = <built-in>
$$EVAL(2**4) = 16
@end example
@noindent

The purpose of code such as @samp{$EVAL($0) = $$EVAL($0)} is to ensure
that the argument of @code{$EVAL} is expanded if it contains macros; the
primitive function @code{$$EVAL} does not do that expansion
automatically.

Names indicated as @samp{<built-in>} by @code{$DUMPDEF} may be redefined
as ordinary macros, but this is in general a @emph{very bad idea}; other
parts of @FWEB{} may mysteriously stop working.

@node $E, $ERROR, $DUMPDEF, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$E}: Base of the natural logarithms

@findex $E
@cindex Logarithms, natural
The expression @samp{$E} returns @var{e}, the base of the natural
logarithms, to the default machine precision. 
The expression @samp{$E(@i{iprec})} returns @var{e} to the decimal precision
@var{iprec} (which must be less than 50).

@node $ERROR, $EVAL, $E, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$ERROR}:  Send error message to output

@findex $ERROR
@cindex Error messages, printing
@samp{$ERROR(@i{string})} prints an error message in @FWEB{}'s
standard form.

@node $EVAL, $EXP, $ERROR, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$EVAL}:  Evaluate a macro expression

@findex $EVAL
@cindex Expressions, evaluating
@cindex Macros, evaluating
@samp{$EVAL(@i{expression})} uses @FWEB{}'s macro-expression evaluator
(@pxref{Preprocessing}) to reduce the macro expression to its simplest
form.  An attempt to perform arithmetic on combinations of non-macro
identifiers and numbers generates a warning message.

@node $EXP, $GETENV, $EVAL, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$EXP}:  Exponential function

@findex $EXP
@cindex Exponentiation
@samp{$EXP(@i{x})} returns 
@tex
$e^x$.
@end tex
@ifinfo
@var{e} to the power @var{x}.
@end ifinfo

@node $GETENV, $HEADER, $EXP, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$GETENV}:  Get value of environment variable

@findex $GETENV
@cindex Environment, obtaining the
@cindex Environment variables
@samp{$GETENV(@var{name})} returns a string consisting of the current
value of the environment variable @var{name}.  (Under VMS, logical names
behave like environment variables.)

The argument to @code{$GETENV} need not be a string (double-quoted), but
it may be if necessary to avoid the expansion of a macro.

@node $HEADER, $HOME, $GETENV, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$HEADER}:  Value of RCS global keyword @code{Header}

@findex $HEADER
@cindex Header

Equivalent to @samp{$KEYWORD(Header)}.  @xref{$KEYWORD}.

@node $HOME,$ID,$HEADER,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$HOME}:  The user's home directory

@findex $HOME
@samp{$HOME} is a convenience macro equivalent to @samp{$GETENV(HOME)}.

@node $ID, $IF, $HOME, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$ID}:  Value of RCS global keyword @code{Id}

@findex $ID
@cindex Identification
Equivalent to @samp{$KEYWORD(Id)}.  @xref{$KEYWORD}.

@node $IF,$IFCASE,$ID,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IF}:  Two-way conditional

@findex $IF
@cindex Conditional, two-way
@code{$IF} is a primitive function (not a macro) that is the code-part
version of @samp{@@#if}. 
The syntax is 

@example
$IF(@i{expr}, @i{action-if-true}, @i{action-if-false})
@end example
@noindent
The @i{expr} is an @FWEB{} macro expression that must reduce to 0
(false) or 1 (true).  First that argument is expanded.  If it is true,
@i{action-if-true} is expanded; otherwise @i{action-if-false} is expanded.

There may be peculiarities with this and the other built-in @code{$IF}
function having to do with the order of expansion when the actions
contain macros whose arguments themselves are macros.  Therefore, do not
use them unless absolutely necessary.

@emph{Do not redefine} @code{$IF} or any other built-in conditionals, as they
are used internally to @FWEB{}.

@node $IFCASE,$IFDEF,$IF,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IFCASE}:  n-way conditional

@findex $IFCASE
@cindex Conditional, n-way
This primitive built-in behaves like @TeX{}'s @samp{\ifcase} command.
The syntax is 

@example
$IFCASE(@i{expr}, @i{case-0}, @i{case-1}, ...,@i{case-n-1}, @i{default})
@end example
@noindent
If @i{expr} reduces to an integer between 0 and @emph{n-1},
inclusively, the appropriate case is selected; otherwise, the default
case is selected.

As examples,

@example
$IFCASE(2, zero, one, two, default) @r{=>} `two'
$IFCASE(2, zero, one, three) @r{=>} `three'
$IFCASE(2, zero, one) @r{=>} `one'
@end example

@node $IFDEF,$IFNDEF,$IFCASE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IFDEF}:  Two-way conditional

@findex $IFDEF
@cindex Conditional, two-way
This built-in primitive is the code-part version of @samp{@@#ifdef}.
The syntax is 

@example
$IFDEF(@var{macro}, @i{action-if-defined},@i{action-if-not-defined})
@end example

@node $IFNDEF,$IFELSE,$IFDEF,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IFNDEF}:  Two-way conditional

@findex $IFNDEF
@cindex Conditional, two-way
This built-in primitive is the code-part version of @samp{@@#ifndef}.
The syntax is @samp{$IFNDEF(@var{macro}, @i{action-if-not-defined},
@i{action-if-defined})}. 

@node $IFELSE,$INCR,$IFNDEF,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IFELSE}:  Two-way conditional

@findex $IFELSE
@cindex Conditional, two-way
The syntax of this built-in primitive is @samp{$IFELSE(@i{expr1},
@i{expr2}, @i{action-if-equal}, @i{action-if-not-equal})}.  The
expansions of @i{expr1} and @i{expr2} are compared on a byte-by-byte
basis.  If they are equal, the first action is taken, otherwise the
second action is taken.

For example,

@example
$M(S="abc")@@%
$IFELSE("abc", S, yes, no)
@end example
@noindent
evaluates to @samp{yes}.

@node $INCR,$INPUT_LINE,$IFELSE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$INCR}:  Increment a macro

@findex $INCR
@cindex Macros, incrementing
@samp{$INCR(@var{N})} redefines the numeric macro @var{N} to be one greater
than its previous value.  (If @var{N} does not simplify to a number, an
error results.)  In other words, in the language of C the effect is to
say @samp{@var{N}++}.

The two-argument form @samp{$INCR(@var{N,m})} executes the equivalent of
@samp{@var{N} += @var{m}}.

@node $INPUT_LINE,$KEYWORD,$INCR,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$INPUT_LINE}:  Line number that begins current section

@findex $INPUT_LINE
@cindex Input line, number of
@samp{$INPUT_LINE} is the number of the line in the @code{web} source file
that @emph{begins the current section} (not the source line in which the
@code{$INPUT_LINE} command appears).  Compare @code{$OUTPUT_LINE},
@ref{$OUTPUT_LINE}. 

@node $KEYWORD, $L, $INPUT_LINE, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$KEYWORD}:  Value of global RCS-like keyword

@findex $KEYWORD
@cindex Keyword, RCS
@cindex RCS-like keyword
@samp{$KEYWORD} provides a built-in function alternative to the use of
@samp{@@K} in a code part.  (@pxref{ATK_}).  

@samp{$KEYWORD(@i{Keyword})} extracts (as a character string) the text of an
RCS-like keyword defined in the ignorable commentary between @samp{@@z}
and @samp{@@x} at the beginning of the web source file (@pxref{ATz}).
(@dfn{RCS} stands for ``revision-control system.'')  The general syntax
is (@sc{unix} users, see @samp{man ident})

@example
$@i{Keyword}: @r{text of keyword} $
@end example
@noindent
For example,

@example
@@z
$Author: krommes $
@@x

@@c
@@
@@a
char author[] = $KEYWORD(Author);
@end example
@noindent
This tangles to

@example
char author[] = "krommes";
@end example

In this example, @samp{$Author} is one of the standard RCS keywords.
However, any keyword that fits the syntax
@samp{$@i{keyword}: @i{contents} $} can be accessed by @samp{$KEYWORD}.
(At least one blank is necessary before and after @i{contents}.)
The argument of @samp{$KEYWORD} need not be quoted, but it may be.  In
either event, the output is a quoted string.

Keywords extracted from ignorable commentary at the beginning of a web
file are called @dfn{global} and are known throughout the code.
Distinguish these from @dfn{local} keywords extracted from ignorable
commentary at the beginning of an include (@samp{@@i}) file.  Such
keywords are known only during the time that file is being read and are
accessible via @samp{@@k} (@pxref{ATk}).

For convenience, built-ins are defined for some standard RCS global keywords.
These are

@example
$AUTHOR    @r{=>} $KEYWORD(Author)
$DATE_TIME @r{=>} $KEYWORD(Date)
$HEADER    @r{=>} $KEYWORD(Header)
$ID        @r{=>} $KEYWORD(Id)
$LOCKER    @r{=>} $KEYWORD(Locker)
$NAME      @r{=>} $KEYWORD(Name)
$RCSFILE   @r{=>} $KEYWORD(RCSfile)
$REVISION  @r{=>} $KEYWORD(Revision)
$SOURCE    @r{=>} $KEYWORD(Source)
$STATE     @r{=>} $KEYWORD(State)
@end example
@noindent
There are no such abbreviations for local keywords, because such
abbreviations would be expanded during output whereas it is necessary to
recognize and expand the local keywords during input.  Presumably such local
keywords will be used rarely, if at all.

@node $L,$L_KEYWORD,$KEYWORD,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$L}:  Change to lower case

@findex $L
@cindex Lower case
@cindex Case, changing
@samp{$L(@var{string})} changes @var{string} to lower case.  The argument is
first expanded in case it is a macro.

@node $L_KEYWORD, $LANGUAGE, $L, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$L_KEYWORD}:  Value of local RCS-like keyword

@findex $L_KEYWORD
@cindex Keyword, RCS
@cindex RCS-like keyword
For most purposes, @samp{$L_KEYWORD} behaves as @samp{@@k}
(@pxref{ATk}).  It is still under development and should not be used yet.

@samp{$L_KEYWORD("@i{Keyword}")} extracts (as a character string) the text of
an RCS-like keyword defined in the ignorable commentary between
@samp{@@z} and @samp{@@x} at the beginning of a file included via
@samp{@@i}.  @samp{$L_KEYWORD("@i{local keyword}")} is expanded during
input, and the results are known only during the time the include file
is being read.  

Note that the argument of @samp{$L_KEYWORD} must be a quoted string.
For more discussion of the distinction between local and global
keywords, please see @ref{ATz} and @ref{$KEYWORD}. 

It is expected that local keywords will rarely be used, as 
fundamental revision-control information should presumably be extracted
from the top of the master web file.  

@node $LANGUAGE,$LANGUAGE_NUM,$L_KEYWORD,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$LANGUAGE}:  Identifier for current language

@findex $LANGUAGE
@cindex Language, determining the
This expands to an identifier that denotes the current language, as
follows:

@quotation
@multitable {..VERBATIM..} {LANGUAGE}
@item Language      @tab  @code{$LANGUAGE}
@item  C            @tab @code{$C}
@item  C++          @tab @code{$CPP}
@item  Fortran      @tab @code{$N}
@item  Fortran-90   @tab @code{$N90}
@item  Ratfor       @tab @code{$R}
@item  Ratfor-90    @tab @code{$R90}
@item  TeX          @tab @code{$X}
@item VERBATIM     @tab @code{$V}
@end multitable
@end quotation

@noindent
Note that this outputs identifiers, not @FWEB{} macros.  They are intended
to be used in @code{$IF} or @code{$IFELSE} statements such as

@example
$IF($LANGUAGE==$C, @i{C-text}, @i{other-text})
@end example

For multiway switches, the @code{$LANGUAGE_NUM} built-in is more useful;
see @ref{$LANGUAGE_NUM}. 

@node $LANGUAGE_NUM,$LEN,$LANGUAGE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$LANGUAGE_NUM}:  Number of current language

@findex $LANGUAGE_NUM
@cindex Language number
@cindex Language, determining
@samp{$LANGUAGE_NUM} expands to an integer that uniquely defines the
current language, as follows:

@quotation
@multitable {..VERBATIM..} {LANGUAGE_NUM}
@item Language @tab  @code{$LANGUAGE_NUM}
@item  C          @tab   @code{0}
@item  C++        @tab   @code{1}
@item  Fortran    @tab   @code{2}
@item  Fortran-90 @tab   @code{3}
@item  Ratfor     @tab   @code{4}
@item  Ratfor-90  @tab   @code{5}
@item  TeX        @tab   @code{6}
@item VERBATIM    @tab   @code{7}
@end multitable
@end quotation
 
@noindent
This built-in is useful in conjunction with an @code{$IFCASE}
construction; see @ref{$IFCASE}.

@node $LEN, $LOCKER, $LANGUAGE_NUM, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$LEN}:  Length of string

@findex $LEN
@cindex String length
@cindex Length of string
@samp{$LEN(@var{string})} returns the length of @var{string} in bytes.  If
@var{string} is not surrounded by quotes, it is interpreted as if it were
quoted (so it is not expanded if it is a macro).  Thus, in the example

@example
@@m SS string
$LEN(SS)
@end example

@noindent
the value returned is 2, not 5.

To expand the argument before taking the length, one can say something
like

@example
@@m $XLEN(s) $LEN(s)
@end example

@node $LOCKER, $LOG, $LEN, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$LOCKER}:  Value of RCS global keyword @code{Locker}

@findex $LOCKER
@cindex Lock
Equivalent to @samp{$KEYWORD(Locker)}.  @xref{$KEYWORD}.

@node $LOG, $LOG10, $LOCKER, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$LOG}:  Natural logarithm

@findex $LOG
@cindex Logarithms, natural
@samp{$LOG(@i{x})} returns 
@tex
$\ln x$.
@end tex
@ifinfo
the natural logarithm of @i{x}.
@end ifinfo

@node $LOG10, $M, $LOG, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$LOG10}:  Logarithm to the base 10

@findex $LOG10
@cindex Logarithms, base 10
@samp{$LOG10(@i{x})} returns
@tex
$\log_{10}x$.
@end tex
@ifinfo
the logarithm to the base 10 of @i{x}.
@end ifinfo

@node $M, $MAX, $LOG10, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$M}:  Define a deferred macro

@findex $M
@cindex Macros, defining
@code{$M} is equivalent to @code{$DEFINE}.  @xref{$DEFINE}.

@node $MAX,$MIN,$M,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$MAX}:  Maximum of a list

@findex $MAX
@cindex Maximum
@samp{$MAX(@i{x1},@i{x2},...)} returns the maximum of the list of arguments.
(There must be at least one argument.)

@node $MIN,$MODULE_NAME,$MAX,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$MIN}:  Minimum

@findex $MIN
@cindex Mininum
@samp{$MIN(@i{x1},@i{x2},...)} returns the minimum of the list of arguments.
(There must be at least one argument.)

@node $MODULE_NAME,$MODULES,$MIN,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$MODULE_NAME}:  Name of present @code{web} module

@findex $MODULE_NAME
@cindex Module, name of
@samp{$MODULE_NAME} returns the name of the present @code{web} module.  If the
present module is unnamed, it returns the string @code{"unnamed"}.

@node $MODULES,$NAME,$MODULE_NAME,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$MODULES}:  Total number of independent modules

@findex $MODULES
@cindex Modules, number of
@samp{$MODULES} gives the total number of independent modules---that is,
the number of independent module names, plus 1 for the unnamed module.

@node $NAME, $OUTPUT_LINE, $MODULES, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$NAME}:  Value of RCS global keyword @code{Name}

@findex $NAME
Equivalent to @samp{$KEYWORD(Name)}.  @xref{$KEYWORD}.

@node $OUTPUT_LINE,$P,$NAME,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$OUTPUT_LINE}:  Current line number of tangled output

@findex $OUTPUT_LINE
@cindex Output line
@cindex Line number
This returns the current line number of the tangled output.  Contrast
this with @code{$INPUT_LINE}, @ref{$INPUT_LINE}.

@node $P,$PI,$OUTPUT_LINE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$P}:  The C preprocessor symbol

@findex $P
@cindex Sharp sign
@cindex Pound sign
@cindex Preprocessor symbol
@code{$P} is (essentially) a synonym for @samp{$UNQUOTE("#")}
(@pxref{$UNQUOTE}).  It is useful for constructing @FWEB{} macro
definitions that expand to C preprocessor statements.  For example,

@example
@@m CHECK(flag)
        $P if(flag)
                special code;
        $P endif
@end example

Another version of the preprocessor symbol is @code{$PP} (@pxref{$PP}).
For most purposes, @code{$P} and @code{$PP} will behave in exactly the
same way.  The difference between them is that @code{$P} is treated as a
string (without surrounding quotes), whereas @code{$PP} is treated as a
character.  The character nature of @code{$PP} is used by @sc{Fortran}
to reset the column number to 1, so C-like preprocessor commands appear
there rather than in column 7.
        
For further discussion of strings and the differences between @code{$P}
and @code{$PP}, see @ref{Strings and quotes}.

@node $PI, $POW, $P, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$PI}: Pi

@findex $PI
@cindex Pi
The expression @samp{$PI} returns 
@PI{} to the default machine
precision.  The expression @samp{$PI(@i{iprec})} returns 
@ifinfo
@var{pi}
@end ifinfo
@tex
$\pi$
@end tex
to the decimal precision @var{iprec} (which must be less than 50).

@node $POW, $PP, $PI, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$POW}:  Exponentiation

@findex $POW
@cindex Exponentiation
@samp{$POW(@i{x,y})} generates 
@tex
$x^y$.
@end tex
@ifinfo
@i{x} raised to the power @i{y}.
@end ifinfo
(It is a macro defined in terms of @code{$EVAL} (@pxref{$EVAL}) and the
exponentiation operator.) 

@node $PP, $RCSFILE, $POW, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$PP}:  The C preprocessor symbol

@findex $PP
@cindex Sharp sign
@cindex Pound sign
@cindex Preprocessor symbol
@code{$PP} is shorthand for @samp{$UNSTRING($P)} (@pxref{$P}), or
(essentially) a synonym for @samp{$UNSTRING("#")} (@pxref{$UNSTRING}).
It is useful, particularly in @sc{Fortran}, for constructing @FWEB{}
macro definitions that expand to C preprocessor statements.  For an
example, see @ref{$P}.  For a detailed discussion of the difference
between @samp{$P} and @samp{$PP}, see @ref{Strings and quotes}.

@node $RCSFILE, $REVISION, $PP, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$RCSFILE}:  Value of RCS global keyword @code{$RCSfile}

@findex $RCSfile
@cindex RCS file
@cindex File, RCS
Equivalent to @samp{$KEYWORD(RCSfile)}.  @xref{$KEYWORD}.

@node $REVISION, $ROUTINE, $RCSFILE, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$REVISION}:  Value of RCS global keyword @code{Revision}

@findex $REVISION
@cindex Revision
Equivalent to @samp{$KEYWORD(Revision)}.  @xref{$KEYWORD}.

@node $ROUTINE,$SECTION_NUM,$REVISION,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$ROUTINE}:  Current function (@sc{Ratfor} only)

@findex $ROUTINE
@cindex Program unit
When @sc{Ratfor} is the current language, @code{$ROUTINE} expands to a
string built of the name of the current program, function, or
subroutine.  This function is not useful for other languages, for which
it expands to the null string.

@node $SECTION_NUM,$SECTIONS,$ROUTINE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$SECTION_NUM}:  Number of current @FWEB{} section

@findex $SECTION_NUM
@cindex Section number, current
@samp{$SECTION_NUM} returns an integer greater than 0 that is the
integer number of the current @code{web} section.  (This is not the
La@TeX{} section number such as 3.4.)

@node $SECTIONS,$SOURCE,$SECTION_NUM,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$SECTIONS}:  Maximum section number

@findex $SECTIONS
@cindex Section number, maximum
@samp{$SECTIONS} is the maximum section number as understood by
@FWEAVE{}.

@node $SOURCE, $SQRT, $SECTIONS, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$SOURCE}:  Value of RCS global keyword @code{Source}

@findex $SOURCE
Equivalent to @samp{$KEYWORD(Source)}.  @xref{$KEYWORD}.

@node $SQRT, $STATE, $SOURCE, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$SQRT}:  Square root

@findex $SQRT
@cindex Square root
@cindex Root, square
@samp{$SQRT(@i{x})} returns
@tex
$\sqrt{x}$.
@end tex
@ifinfo
the square root of @i{x}.
@end ifinfo
It is a convenience macro defined in terms of @code{$POW}.  @xref{$POW}.

@node $STATE, $STRING, $SQRT, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$STATE}:  Value of RCS global keyword @code{State}

@findex $STATE
@cindex State
Equivalent to @samp{$KEYWORD(State)}.  @xref{$KEYWORD}.

@node $STRING, $STUB,$STATE, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$STRING}:  Expand, then stringize

@findex $STRING
@cindex String, quoting a
@samp{$STRING(@i{s})} expands its argument if it is a macro, then makes
the expansion into a quoted string.  If the argument is already a quoted
string, it is returned unchanged.

@node $STUB,$TIME,$STRING,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$STUB}:  Trap for missing module

@findex $STUB
@cindex Modules, missing
When a missing module is detected, @FTANGLE{} inserts the command
@samp{$STUB(@i{module_name})} into the output code.  The built-in
@code{$STUB} expands to a function call appropriate to the current
language.  For example, in C it expands to @samp{missing_mod}, in
@sc{Fortran} it expands to @samp{call nomod}.

@node $TIME,$TRANSLIT,$STUB,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$TIME}:  The time

@findex $TIME
@cindex Time
@samp{$TIME} returns a string consisting of the local time in the form
@code{"19:59"}.

@node $TRANSLIT,$U,$TIME,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$TRANSLIT}:  Transliteration

@findex $TRANSLIT
@cindex Transliteration
The macro @samp{$TRANSLIT(@var{s}, @var{from}, @var{to})} interprets each of
its arguments 
as strings (without expanding anything). Then @var{s} is modified by
replacing any of the characters found in @var{from} by the
corresponding characters in @var{to}. If @var{to} is shorter than
@var{from}, then the excess characters in @var{from} are deleted from
@var{s}. As a limiting case, if @var{to} is empty, then all the
characters in @var{from} are deleted from @var{s}. For example,
@samp{$TRANSLIT(s, aeiou, 12345)} replaces the vowels in @var{s} by the
corresponding digits, and @samp{$TRANSLIT(s, aeiou, )} deletes all the
vowels.  The backslash may be used to escape a character, as in ANSI C.
For example, @samp{$TRANSLIT("a\\"\\\\d", "d\\\\a\\"", "D,A'")}
translates into @samp{A',D}.  Here one had to explicitly enclose strings
involving @samp{\\"} in double quotes in order to avoid a complaint
about an unterminated string.


@node $U,$UNDEF,$TRANSLIT,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$U}:  Change to upper case

@findex $U
@cindex Case, changing
@cindex Upper case
@samp{$U(@i{string})} changes @i{string} to upper case.

@node $UNDEF,$UNQUOTE,$U,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$UNDEF}:  Undefine a macro

@findex $UNDEF
@cindex Macros, undefining
@samp{$UNDEF(@i{macro})} undefines an @FWEB{} macro.

@node $UNQUOTE,$UNSTRING,$UNDEF,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$UNQUOTE}:  Remove quotes from string

@findex $UNQUOTE
@cindex Strings, unquoting
@samp{$UNQUOTE(@var{string})} returns @var{string} without its surrounding
quotes.  (However, the resulting construction is still treated as a
string; no macro expansion is done.)

For a more detailed discussion and a comparison with @code{$UNSTRING}
(@pxref{$UNSTRING}), see @ref{Strings and quotes}.

@node $UNSTRING, $VERBATIM, $UNQUOTE, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$UNSTRING}:  Convert string into characters

@findex $UNSTRING
@samp{$UNSTRING(@var{string})} removes quotes from the string, if they are
present, and treats the result as a collection of characters.  No
tokenization is done, so macro expansion does not operate on those
characters.

For a more detailed discussion and a comparison with @code{$UNQUOTE}
(@pxref{$UNQUOTE}), see @ref{Strings and quotes}.

@node $VERBATIM, $VERSION, $UNSTRING, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$VERBATIM}:  (Obsolete)

@findex $VERBATIM
This was an old name for @code{$UNQUOTE} (@pxref{$UNQUOTE}).  Please
remove all references to this macro from existing codes.

@node $VERSION,,$VERBATIM,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$VERSION}:  Present @FWEB{} version number

@findex $VERSION
@cindex Version, of FWEB
@samp{$VERSION} returns a string built out of the @FWEB{} version
number, such as @code{"1.61"}.

@node Debugging with macros, , Built-in functions, FWEB macros
@comment  node-name,  next,  previous,  up

@subsection Debugging with macros

@cindex Macros, debugging with
@findex #line

If an @FWEB{} macro expands to more than one output line, debugging
can be a bit confusing if the debugger (e.g., @code{gdb}) displays lines
in the @code{web} source file instead of the output file (as it normally
does for C and C++).  While single-stepping through the code, the
debugger will incorrectly step the screen display for each output line
even if the macro call occupies just one line in the source file.  To
localize the debugger's confusion, insert a @samp{@@#line} command after
the macro call.  For example,

@example
@@c
@@ Example of a macro that expands to several output lines.
@@m UPDATE(i, delta_i)
     i += delta_i;
     store(i)@@;
@@a
main()
@{
UPDATE(j, 5);
@@#line
// More code.  The debugger will be in sync from here on.
@}
@end example    

An alternative for highly confusing situations is to use the @samp{-#}
option (@pxref{-#}).

Another potentially confusing situation occurs when @samp{@@%} is used
to comment out a line.  @FWEB{} deals with the line-number problem
that arises here automatically; see @ref{-T#}.

@node Macros and formatting, Preprocessing, FWEB macros, Macros
@comment  node-name,  next,  previous,  up

@cindex Macros, formatting
@FWEAVE{} makes a valiant attempt to pretty-print
(@pxref{Pretty-printing}) the definitions of 
both outer macros and @FWEB{} macros in a reasonable way. However, this
can be a formidable task, because macro syntax can be essentially
arbitrary.  Consider, for example, the following definition:

@example
@@c
@@d GET(type) type get_##type()
@@a
GET(int)@{@}@@; // @r{Expands into @samp{int get_int()@{@}}.}
@end example
@noindent
The problem is that the identifier @samp{type} is used in two different
ways:  as the type of a reserved word (the second @samp{type}), and as
an ordinary expression (the third @samp{type}).  The first @samp{type} has both
meanings simultaneously.  Unfortunately, within any particular language
@FWEAVE{} associates one unique type or @dfn{ilk} with each identifier.

One solution to this problem is to use the @samp{@@R} command
(@pxref{ATR_}), which changes the ilk of the very next identifier to
integer-like.  Thus,

@example
@@d GET(type) @@R type get_##type()@@;
@end example
@noindent
will format correctly.  An alternative solution uses the related command
@samp{@@E}, which 
changes the ilk of the very next identifier to an ordinary expression.
Thus,

@example
@@f type int
@@d GET(type) type get_##@@Etype()@@;
@end example

Other types of troublesome situations involve spaces.  When @FWEB{}
understands the syntax, it inserts spaces automatically to make the
output pleasing.  Consider, however, the (somewhat contrived) example

@example
@@c
@@d A(x, y) x y
@@d B s1;
@@d C s2;
@@a
A(B, C)@@;
@end example
@noindent
Here @FWEAVE{} will consider @samp{x} and @samp{y} to be ordinary
identifiers (simple expressions), and will abut them with no intervening
spaces, which is confusing to read.  The solution is to insert a space
manually with @samp{@@,}:

@example
@@d A(x, y) x @@, y
@end example
@noindent
(Whether one should write macros like this at all is a separate issue.)
For a related example, see the discussion of @ref{ATcomma}.

@node Preprocessing,,Macros and formatting,Macros
@comment  node-name,  next,  previous,  up

@section Preprocessing

@cindex Macros, preprocessing
@cindex Preprocessing
Generally, the @FWEB{} preprocessor commands follow a syntax identical
to their C/C++ counterparts.  The one exception is the @samp{@@#line}
command.  Whereas the C command takes a line number and file name as
arguments, the @FWEB{} command takes no arguments; its expansion
automatically inserts the current line number and file name.  This
command should be necessary only in rare circumstances.  One of those
involves situations in which an @FWEB{} macro expands to more than one
output line; see @ref{Debugging with macros}.

The @FWEB{} preprocessor commands may appear in either the definition or the
code parts.  But @emph{BEWARE:  No matter where they appear, they are expanded
during INPUT, not output.}  (This is probably a design flaw.)  For more
discussion, see @ref{FWEB macros}.

@findex @@#line
@findex @@#define
@findex @@#undef
@findex @@#ifdef
@findex @@#ifndef
@findex @@#if
@findex @@#elif
@findex @@#endif

The syntax of each command is as follows:

@quotation
@table @code
@item @@#line
  --- Insert a @code{#line} command.

@item @@#define @var{identifier}
 --- Define an FWEB macro; equivalent to @samp{@@m}.
@item @@#undef @var{identifier}
  --- Undefine an FWEB macro.

@item @@#ifdef @var{identifier}
 --- Is FWEB macro defined?  Equivalent to @w{@samp{@@#if defined identifier}}.
@item @@#ifndef @var{identifier}
 --- Is FWEB macro not defined?  Equivalent to @w{@samp{@@#if !defined identifier}}.

@item @@#if @i{expression}
@item @@#elif @i{expression}
@item @@#else
@item @@#endif
@end table
@end quotation

In the @samp{@@#if} statement, the @i{expression} may contain @FWEB{}
macros, but must ultimately evaluate to a number.  If that number is
zero, the expression is false; otherwise, it is true.

@cindex Expression evaluation
The @i{expression} following constructions such as @samp{@@#if} is
evaluated by a built-in expression evaluator that can also be used for
other purposes, such as in macro expansion.  Its behavior is again
motivated by expression 
evaluation in ANSI C; it is not quite as general, but should be more than
adequate.  (One design flaw that will be fixed someday is that the order
of expression evaluation is not necessarily left-to-right, as it is in C.)
It supports both integer and floating-point arithmetic (with type
promotion from integer to floating-point if necessary), and the ANSI
@code{defined} operator. Operators with the highest precedence 
(see table below) are evaluated first; as usual, parentheses override the
natural order of evaluation. The unary operator @code{defined}
has the highest
precedence; all the other unary operators have the next highest (and equal)
precedence; then come the binary operators. When the operator exists in C,
the action taken by @FWEB{} is precisely that that the C compiler would take.
Arithmetic is done in either @b{long} or @b{double} variables, as
implemented by the C compiler that compiled @FTANGLE{}.  (This was the
easy choice, not necessarily the most desirable one.)

The operators, listed from  highest precedence  to lowest, are as
follows
@ifinfo
(printed documentation only):
@end ifinfo

@page

@tex
\gdef\expr{{\it expr}}
\gdef\.#1{{\tt #1}}
\chardef\TL=`\~% Tilde in a string: '\.\~'.
\gdef\^{\ifmmode\raise0.45ex\hbox{$\,\scriptstyle\mathchar"25E\,$}%
	\else\char`^ \fi}% 
\global\let\amp\&
$$\def\<{{\rm ,$\,$}}
\def\mod{\Mathop{mod}}
\vtop{\halign{\tt\quad#\quad\hfil&\ ---\
\vtop{\hsize=0.75\hsize\noindent\hang \strut#\strut}\hfil\cr
\noalign{\medskip\leftline{@b{Unary operators}:}\smallskip}
defined&@code{defined} is a unary operator that acts on identifier tokens. 
@samp{defined id} or equivalently @samp{defined(id)} evaluates to~1 (true) if
the identifier is defined as an @sc{Fweb} macro; 
to~0 (false) otherwise.  The construction @samp{@@\#if defined A} works the
same way as @w{@samp{@@\#ifdef A}}, but one can use @samp{defined} in
expressions, as in 
$$
\hbox{@code{@@\#if defined(A) || defined(B)}}.
$$ 
(The parentheses around the macro names are optional.)
With the advent of @samp{defined}, the
@sc{Fweb} preprocessor statements @samp{@@\#ifdef} and @samp{@@\#ifndef}
become redundant, but are often useful shorthands.\cr
-&Unary minus.\cr
!&Logical \hbox{\.{NOT}}. \.{!\expr} evaluates to~0 if \.{\expr}
is nonzero, and evaluates to~1 if \.{\expr} is~0.\cr
\TL&One's complement of an integer. For example, $\.{\TL0} =
-1$.\cr 
\noalign{\medskip\leftline{@b{Binary operators}:}\smallskip}
\^\^&Exponentiation (all languages). $2\hbox{\.{\^\^}}3 = 8$.\cr
\^\<**&Exponentiation (@sc{Fortran} or @sc{Ratfor}).\cr
*\</\<\%&Multiplication, division, and modulus: 
`\.{$a$ \% $b$}' means `$a \hbox{ mod } b$'; for example, \.{5 \% 3 = 2}. \cr
+\<-&The usual plus and minus.\cr
<<&`\.{$a$ << $b$}' means shift integer~$a$ left $b$~bits. $1 \ll
3 = 8$.\cr
>>&As above, but right-shift. $7 \gg 2 = 1$.\cr
<\<<=\<>\<>=&Evaluates to~1 if the inequality holds, to~0 otherwise.
E.g., `\.{(2.0 < 3.0)}' evaluates to~1.\cr
==\<!=&`\.{$a$==$b$}' (`\.{$a$!=$b$'}) evaluates to~1 (0) if $a$
equals~$b$; evaluates to~0 (1) otherwise.\cr 
\amp&Bitwise \hbox{\.{AND}}. The truth table is \.{0b1100 \amp{
}0b1010 = 0b1000}.\cr 
\^&Bitwise \.{EXCLUSIVE OR} (C). (For @sc{Fortran}, use `\.{.xor.}'.)
The truth 
table is {\.{0b1100}~\.{.xor.}~\.{0b1010 = 0b0110}}.\cr
|&Bitwise~\hbox{\.{OR}}. The truth table is \.{0b1100 | 0b1010 =
0b1110}.\cr 
\amp\amp&Logical~\hbox{\.{AND}}.\ `\.{$a$ \amp\amp{ }$b$}'
evaluates to~1 if both~$a$ and~$b$ are true (nonzero).\cr 
||& Logical~\.{OR}. `\.{$a$ || $b$}' evaluates to~1 if either~$a$ or~$b$
are true.\cr 
  }}$$
Note in particular the use of the single caret, which is
language-dependent:  it is an 
exponentiation operator for @sc{Fortran} (just as in @TeX{}), but is the
exclusive-or operator for~C. Also, note that the bitwise operators
should almost never be used. For 
logic, almost always one will be using @samp{==}, @samp{!=}, @samp{\&\&},
and @samp{||}. 
@end tex

@node Languages,Macros,Comments,Top
@comment  node-name,  next,  previous,  up

@chapter LANGUAGES

@cindex Languages
@cindex Language, global
@FWEB{} has the ability to work with more than one source language
during a single run.  The language in effect at the beginning of the
first section defines the @emph{global language}.  Further language
changes within a section have scope local to that section.

Usually, `language' means a compiler language like @sc{Fortran} or C.
These languages will be ``pretty-printed'' by @FWEAVE{}.
Pretty-printing can be inhibited by turning on the N mode (globally,
with the command-line option @samp{-N}; locally, with @samp{@@N}) or by
selecting the @sc{verbatim} `language'; in both of these cases, the input
text is echoed literally to the output of both @FTANGLE{} and
@FWEAVE{}.

`Language' is a stronger concept than `mode'.  For example, when a
language is selected, the extension of the tangled output file is
changed appropriately---for example, if @file{test.web} contains C code
(that is, contains the command @samp{@@c}), @file{test.web} tangles into
@file{test.c} (compressing blanks and otherwise (deliberately) making
the tangled output relatively unreadable) and @FWEAVE{} pretty-prints
using the C syntax.  Turning on the N mode does not affect the language;
@FTANGLE{} copies the source code literally into @file{test.c} (no
blank compression or other modifications), and @FWEAVE{} typesets the
source code within a verbatim environment (no pretty-printing).  When
the @sc{verbatim} language is selected, the N mode is turned on
automatically, but @FTANGLE{} writes its output to a file with a
special default extension that can be customized in the style file.
@xref{Miscellaneous params}.

@menu
* Setting the language::             Setting the language.

Special hints and considerations for each language.
* C::                   C
* C++: Cpp.             C++.
* Fortran::             Fortran--77 and Fortran--90.
* Ratfor: Ratfor_.      RATional FORtran.
* TeX::                 @TeX{}.
* Verbatim::            Literal mode.
@end menu

@node Setting the language, C, Languages, Languages
@comment  node-name,  next,  previous,  up

@section Setting the language

@cindex Language, setting
The most general form of a language command is

@quotation
@@@i{[}L@i{]ltext}[@i{options}]
@end quotation

@noindent
where @i{l} is a language symbol, @i{text} is converted into the
option @samp{-@i{l}text}, and @i{options} have the same syntax as on the
command line.  

The language symbols must be in lower case; they are

@quotation
@multitable{..VERBATIM..}{cpp}
@item C          @tab  @code{c}
@item C++        @tab  @code{c++}
@item Fortran-77 @tab  @code{n}
@item Fortran-90 @tab  @code{n9}
@item Ratfor-77  @tab  @code{r}
@item Ratfor-90  @tab  @code{r9}
@item TeX        @tab  @code{x}
@item VERBATIM   @tab  @code{v}
@end multitable
@end quotation

An example of a command with the optional @i{text} field is @samp{@@n/}.
By definition, this is equivalent to @samp{@@n[-n/]}.  Thus, it both sets
the language and invokes a command-line option.

As another example, @samp{@@n9} really means @samp{@@n[-n9]}.  Thus the
language is first set to @sc{Fortran}, then reset to @sc{Fortran}-90.
One doesn't need to worry about this detail.

@example
@@n9[-n&]
@end example

@noindent
means set the language to @sc{Fortran}--90 and use free-form syntax with the
ampersand as the continuation character.  (This construction is now
@FWEB{}'s default.)

The brackets may contain more than one space-delimited option.

A language command should appear somewhere in limbo, before the start of
the first section.  The language in effect at the beginning of the first
section defines the global language.  For historical reasons, the
default language is @sc{Fortran}-77, but @emph{do not rely on this;
always include a language command}.

Language commands may be used within sections, but the new language
remains in force only for that section.  The language of a named module
is inherited from the language in effect at the time the name is first
used.  Thus, in the following example, the global language is
@sc{Fortran}--77, but an arbitrary number of C functions can be placed into a
C-language module with just one @samp{@@c} language-changing command.

@example
@@n
@@ 
@@a
        program main
        end

@@c
@@<C@@>@@;

@@ 
@@<C@@>=
int fcn()
@{@}
@end example

@noindent
@FTANGLE{} will write two output files for this example---e.g.,
@file{test.f} and @file{test.c}.  Particularly note that one did not
need an @samp{@@c} command in the last section because the language was
C when @samp{@@<C@@>} was first encountered.

@section Special hints and considerations for each language

One important thing to keep in mind is that in @FWEB{} an identifier
may have, for each language, precisely one meaning throughout the
document.  This restriction is not necessarily in accord with the
syntaxes of the various source languages.  See, for example, the
discussions in @ref{Cpp} and @ref{Fortran}. 

@node C, Cpp, Setting the language, Languages
@comment  node-name,  next,  previous,  up

@subsection Special considerations for C

@cindex C hints
@cindex Hints, C

@itemize @bullet

@item
@cindex Binary notation
@cindex Notation, binary
@FTANGLE{} treats the construction @samp{0b...} as a binary notation
that it expands to an unsigned decimal number.  Thus, @samp{0b101}
expands to 5 and @samp{0b1111111111111111} expands to 65535.  

@item
@FWEAVE{} processes @b{typedef} statements during phase one, so they will
format properly even if they are used in a documentation part before
they are defined in a code part.

@item
The @samp{-H} option helps one to deal with identifiers defined in
header files.  @xref{-H_}.

@item
@cindex Tags, enum
@cindex Tags, structure
Note that in C structure and enum tags do not define a new type, so the
tag name does not get highlighted in boldface, underlined in the index,
etc.  (That is, if one says @samp{struct S @{...@};}, one can't say
@samp{S s;}, one must say @samp{struct S s;}.)  This is a good reason
for using C++, where such tags do define a new type.

@end itemize

(To be completed.)

@node Cpp,Fortran,C,Languages
@comment  node-name,  next,  previous,  up

@subsection Special considerations for C++

@cindex C++ hints
@cindex Hints, C++
@itemize @bullet

@item
All of the items in the previous section (@pxref{C}) still apply.

@item
The @samp{@@@{} command is very useful for beautifying very short
definitions of member functions such as constructors.  @xref{ATlb}

@item
Essentially, @FWEAVE{} has only one name space, global to the entire
code; those names do not obey any concept of scope.  In various
situations in C and C++, however, multiple namespaces are used, or the
interpretation of a name changes according to its scope.  Thus, the
design of @FWEAVE{} imposes a few restrictions on one's programming
style.  (Remember, @FWEAVE{} doesn't know nearly as much as a language
compiler.)

One example in C++ has to do with formal types in templates.  Consider
the following example:

@example
template <class Type>
class A
@{
private:
        Type *p;
@}
@end example
@noindent
In order that the class definition be typeset correctly, @samp{Type}
must be understood to be a reserved word like @b{int}, and that is
correctly figured out by the first @b{class} command.  However,
according to C++, the scope of @samp{Type} is local to the class
definition; unfortunately, @FWEAVE{} does not respect that locality and will
always treat @samp{Type} as an @b{int} from the point of the
@samp{class Type} construction to the end of the source code.  Thus, one
should use such dummy variables as @samp{Type} only as formal template
parameters, never as ordinary variables.

@end itemize

@node Fortran,Ratfor_,Cpp,Languages
@comment  node-name,  next,  previous,  up

@subsection Special considerations for @sc{Fortran}

@cindex Hints, @sc{Fortran}
@cindex @sc{Fortran} hints

@subsubsection Items for both @sc{Fortran}-77 and @sc{Fortran}-90

@itemize @bullet

@item
@cindex Binary notation
@cindex Notation, binary
@cindex Octal notation
@cindex Notation, octal
@cindex Hexadecimal notation
@cindex Notation, hexadecimal
@FTANGLE{} will translate into unsigned decimal numbers the binary
notation @samp{0b...}, the octal notation @samp{0...}, and the
hexadecimal notation @samp{0x...}.  Thus, @samp{0b101} expands to 5,
@samp{0101} expands to 65, and @samp{0x101} expands to 257.

@item
Don't use the column 1 @samp{C} commenting convention.  Use @samp{/*
... */} or @samp{// ...}.  

@item
For compiler directives, use @samp{@@?} (@pxref{AT?}), not a @samp{C} in
column 1.

@item
If you are going to use the recommended @samp{// ...} convention for
short comments, you must say @samp{@@n/} (@pxref{-n/}) or
@samp{@@n9[-n/]} as your language command.  Otherwise, \FWEB\ will treat
the @samp{//} as \@sc{Fortran's} standard token for concatenation.  (You
may always use @samp{\/} for concatenation.)

@item
@cindex Code, temporarily commenting out
If you want to completely comment out a whole block of code,
use the preprocessor construction @samp{@@#if 0...@@#endif}
(@pxref{Preprocessing}).  Don't put a comment character at the beginning
of each line; that prevents @FWEAVE{} from formatting the code
sensibly and can be annoying to undo.  With the preprocessor form, one
can also implement conditional comments by using @FWEB{} preprocessor
macros:  e.g., @samp{@@#if(DEBUG)...@@#endif}.

Pre-@FWEB{} codes may have such blocks commented out with a @samp{C}
in column 1.  Those should be converted to the preprocessor
construction.  However, if you're in a real hurry, temporarily use the
@samp{-nC} option (@pxref{-nC}) to kill those lines very early in the
processing, before they can give you all kinds of trouble.

@item
@cindex Comments, short
An unfortunate byproduct of using @samp{//} for short comments is that,
in general, format constructions like @code{format(//)} won't work.  (It
will work if one uses @samp{-nC}; see @ref{-nC}.)  Alternatively, one
can say @code{format(/ /)}.

@item
Consecutive lines commented out with a @samp{C}, @samp{c}, @samp{*}, or
@samp{!} in column 1 are converted into a single comment before
processing by @FWEB{}.  Large blocks of such lines (common in
pre-@FWEB{} code) may overflow @FWEB{}'s tables.  To avoid that,
insert blank lines between some of the comments.  Better, however, is to
move most such blocks out of the code part to the @TeX{} part of the
section.  It's most readable to have only a few very short comments
interspersed in the code.

To help with conversion of existing codes, the command-line option
@samp{-nC} can be used to completely ignore comment lines.

@item
@samp{@@} commands should, by and large, start in column 1.  That's not
necessary for short module names that fit on one line.  However, a long
module name that must be broken across lines must begin in column 1, as
in

@example
@@n
@@
@@a
@@<This is a module name
broken across lines@@>@@;
@end example
@noindent
Failure to do this results in a spurious semicolon being inserted in the
middle of the name.  This happens because the @sc{Fortran}-77 input driver
does various low-level manipulations of the source before it presents it
to the innards of @FWEB{}; it's not tokenizing the source at that time
and doesn't understand all of the @FWEB{} syntax such as module names.

@item
Define symbolic statement labels with @samp{#:0}
(@pxref{Tokens}).  Such names should be followed by a colon.  Thus,

@example
@@n
@@
@@m EXIT #:0
@@m ABORT #:0
@@a
.
.
ABORT: continue
.
.
EXIT: continue
.
.
@end example

@item
By default, statement labels are @code{\llap}'d from the body of the
statement.  With this convention, long labels can extend too far into
the left margin.  Instead, try the command-line option @samp{-n:}
(@pxref{-ncolon}), which puts them on a separate line.  Alternatively, one
can redefine the macro @code{\Wlbl}, found with some discussion in
@file{fwebmac.sty}.
@findex \Wlbl

@item
@cindex Keywords, I/O
@findex -k
As a suggestion, use upper case for I/O keywords such as @code{IOSTAT}.
However, by default the lower-case forms are also recognized.  To permit
only upper case, use @samp{-k} (@pxref{-k}).  Note that although there
is a command @samp{-nk}, it is unfortunately not related to @samp{-k}.

@item
@cindex Exponentiation
One may use @samp{^} as an alternative for the exponentiation operator
@samp{**}. 

@item
@findex -+
@cindex Assignment operators, compound
@FWEB{} attempts to be helpful and tries to expand the operators
@samp{++}, @samp{--}, @samp{+=}, @samp{-=}, @samp{*=}, and @samp{/=}
in a way compatible with the usage in C and C++.  For example, it
expands @w{@samp{x += y}} into @w{@samp{x = x + (y)}}.  This feature can be a
great time-saver and also makes the code substantially more legible; it
is strongly recommended.  To turn off this feature, use the option
@samp{-+}.  @xref{-plus}. 

@cindex Not equal
Notice that in @sc{Fortran}-90 @samp{/=} is a token for ``not equal,''
so if you want to use that you must use the @samp{-+} option.  However,
a better solution is to use @samp{!=}, @FWEB{}'s preferred operator
for ``not equal.'' 

@item
@cindex .true.
@cindex .false.
By default, the operators @code{.true.} and @code{.false.} will weave as
caligraphic T and F.  That appearance be changed by redefining the macros
@code{\WTRUE} and @code{\WFALSE} in @file{fwebmac.sty} or in the limbo
section of your source file.

@item
@findex -#
If @FTANGLE{} messes up and outputs incorrect @sc{Fortran} code, try
tangling with the command-line option @samp{-#} (@pxref{-#}) (and then
report the problem.)

@end itemize

@subsubsection Items specific to @sc{Fortran}-77 and fixed-form @sc{Fortran-90}

@itemize @bullet

@item
@cindex Semicolons, automatic
@cindex Automatic semicolons
By default, when processing the code part the
@sc{Fortran} driver inserts semicolons automatically at the end of each
logical statement.  Thus, the core of @FWEB{} is presented with a
uniform syntax.  However, when one escapes into code mode by using
vertical bars, those semicolons aren't inserted, so something that
appears a first glance to be complete statement may not be formatted as
one might expect.  Thus, the construction @samp{|5: continue|} doesn't
format quite properly (the colon disappears); this problem is solved by
putting a semicolon after the @samp{continue}.  Also, if one is talking
about multiple statements (for example, with a shift into code mode
during @TeX{} documentation), there's no choice but to insert the
semicolon between statements.  For example, @w{@samp{|a = b; c = d;|}}.

@end itemize

@subsubsection Items specific to @sc{Fortran}-90

@itemize @bullet

@item
@cindex Syntax, free-form
If @sc{Fortran}-90 is selected (@pxref{-n9}), the default is
@emph{free-form} syntax (lines are continued by a trailing ampersand).
However, automatic line breaking is done in a way compatible with
fixed-form syntax as well.

@item
@findex -n!
With free-form syntax, comment lines in the tangled output file begin
with @samp{!}.  But such lines are not recognized on input unless
@samp{-n!} is used.  @xref{-n!}.

@item
@cindex Pseudo-semicolons, automatic
@cindex Automatic pseudo-semicolons
Beginning with Version 1.61, by default (pseudo-)semicolons are automatically
inserted in free-form \Fortran-90 code, as one would expect.  For more
discussion, see @ref{-nAT;} and @ref{-n;}.

@end itemize

(To be completed.)

@node Ratfor_,TeX,Fortran,Languages
@comment  node-name,  next,  previous,  up

@subsection Special considerations for @sc{Ratfor}

For some warnings about @sc{Ratfor}, see @ref{Caveats}.

@node TeX, Verbatim, Ratfor_, Languages
@comment  node-name,  next,  previous,  up

@subsection Special considerations for TeX

@cindex Hints, @TeX{}
@cindex @TeX{} hints
@samp{@@Lx} is supported only to the extent that @code{fwebmac.sty} can
be generated correctly from @code{fwebmac.web}.  You are welcome to
experiment, but you may encounter difficulties (which you should report;
@pxref{Support}).

(To be completed.)

@node Verbatim, , TeX, Languages
@comment  node-name,  next,  previous,  up

@subsection Special considerations for the @sc{verbatim} language

Unfortunately, the @sc{VERBATIM} language is not fully debugged.
Therefore, it is not recommended for general use.
(To be completed.)

@node Ratfor,Documentation,Macros,Top
@comment  node-name,  next,  previous,  up

@chapter @sc{Ratfor}

@cindex @sc{Ratfor}
@cindex @sc{Fortran}, Rational
@cindex Rational @sc{Fortran}
``@sc{Ratfor}'' stands for ``@sc{RATional} @sc{FORtran}.''  It endows
@sc{Fortran} with a 
C-like syntax.  Certain loop and other constructions (such as
@samp{switch} or @samp{i++}) that are not allowed in @sc{Fortran} are allowed
in @sc{Ratfor}; @FWEB{} translates those into proper @sc{Fortran}.

Although @sc{Ratfor} is a definite improvement over @sc{Fortran}, it certainly
does not have the power of C (e.g., elegant pointer notation) or C++
(e.g., classes).  Many advantages accrue by taking the time to learn C.
@sc{Ratfor} offers a gentle transition.  (It is not supported very
actively any more.)

@menu
* Syntax: RSyntax.      Ratfor syntax.
* Commands::            Ratfor commands.
* Caveats::             Nuances about @FWEB{} Ratfor.
@end menu

@node RSyntax, Commands, Ratfor, Ratfor
@comment  node-name,  next,  previous,  up

@section @sc{Ratfor} syntax

A sample @sc{Ratfor} program is

@example
@@r
@@
@@a
program main
@{
integer k;
real fcn, x;

for(k=0; k<10; k++)
        @{
        x = fcn(k);

        if(x < 0.0)
                @{
                x = 0.0;
                break;
                @}
        @}
@}
@end example
@noindent
The concluding brace of a function is translated into an @b{END}
statement.  Note the use of semicolons to terminate statements, braces
to delimit compound statements, @samp{<} instead of @samp{.LT.}, the
C-like @b{for} construction, and the @samp{k++} expression. 

Constructions like @samp{k++} or @samp{k -= l + 1} must be used with
great care.  They translate to statements involving @samp{=} signs, so they
can be used only where simple statements are allowed, not essentially
anywhere as in C (for example, they cannot be used as function
arguments).

@node Commands,Caveats,RSyntax,Ratfor
@comment  node-name,  next,  previous,  up

@section @sc{Ratfor} commands

@subsection @sc{Ratfor}--77 commands

@cindex @sc{Ratfor} commands
@example 
 break; // @r{Used with @code{case} or to break out of loops, as in C.}
 case i: // @r{Used with @code{switch}.}
 default: // @r{Used with @code{case}, as in C.}
 do ...; @{...@} // @r{Note the semicolon (unnecessary if followed by a compound stmt).}
 else @{...@} // @r{Used after @code{if} as in C.}
 for(a;b;c) @{...@} // @r{As in C.}
 if(condition) @{...@}
 next; // @r{Equivalent to C's |continue| statement; go to bottom of loop.}
 repeat @{...@} until(condition); // @r{Equivalent to C's @code{do @{...@} while();}}
 return expression; // @r{As in C.}
 switch(expression) @{...@} // @r{As in C.}
 while(condition) @{...@} // @r{Like C's @code{while}.}
@end example

@subsection Additional @sc{Ratfor}--90 commands

@example
 contains:
 interface name @{...@}
 interface operator(op) @{...@}
 interface assignment(assgnmnt) @{...@}
 module name @{...@}
 private:
 sequence:
 type name @{...@}
 where(expression) @{...@}
@end example

@node Caveats,,Commands,Ratfor
@comment  node-name,  next,  previous,  up

@section Caveats about @sc{Ratfor}

@cindex @sc{Ratfor}, caveats about
The version of @sc{Ratfor} built into @FWEB{} differs slightly from its @sc{unix}
counterpart:  

@quotation
@enumerate
@item 
Numeric statement labels must be followed by a colon; they should
be first on their line.  (Use symbolic statement labels instead; see the
discussion of @samp{#:0} in @ref{Tokens}.)

@item
The quoting convention for characters and strings follows that
of C:  Single-quote single characters, double-quote strings.

@item
In a @b{switch}, cases fall through to the next case unless
terminated by @b{break} (just as in C).

@item
The @b{do} statement must be terminated by a semicolon if
followed by a simple statement.  (It's unnecessary if followed by a left
brace that begins a compound statement.)

@item
Use @t{&&} and @t{||} for the logical AND and OR.

@item
Do not use an @b{end} statement at the very end of a @sc{Ratfor} program
unit; it is added automatically by @FWEB{} when the closing brace is sensed.
@end enumerate
@end quotation


@node Documentation,Index,Ratfor,Top
@comment  node-name,  next,  previous,  up

@chapter DOCUMENTATION

@cindex Formatting
@cindex Documentation format
@FWEB{} uses La@TeX{} to produce its documentation.  Plain @TeX{}
is no longer supported.

It is not necessary to be very familiar with La@TeX{} in order to use
@FWEB{} effectively.  @FWEB{} does complicated things behind
the scenes, relieving the programmer of many burdens.  If you don't need
complicated mathematics, one needs to know virtually no La@TeX{} at all
in order to document a section of code.  And if you do need to typeset
math, consider that La@TeX{} makes this daunting task about as simple as
one could hope.

If you're an @FWEB{} beginner, don't bother diving into the details of
this section until you really need to.

@menu
* Typesetting::         Woven output; TeX vs. LaTeX, etc.
* Pretty-printing::     Turning ugly input into beautiful output.
@end menu

@node Typesetting, Pretty-printing, Documentation, Documentation
@comment  node-name,  next,  previous,  up

@section Typesetting

@cindex Typesetting
@FWEB{}'s ``new look'' (beginning with version 1.40) is designed
to work only with La@TeX{}.  The new look is more
book-like, following ideas from Briggs' @code{nuweb}.  By default, it
uses default La@TeX{} section numbers such as 1.5.32; however, sections
may be numbered with consecutive integers by specifying the La@TeX{}2e package
@code{fwebnum}; see @ref{Numbering}.

@menu
* Output::	Structure of the TeX output from @FWEAVE{}.
* fwebmac.sty:: The macro package used with @FWEAVE{}.
* LaTeX::	Specifics of the LaTeX support.
@end menu

@node Output,  fwebmac.sty, Typesetting,  Typesetting
@comment  node-name,  next,  previous,  up

@subsection @FWEAVE{}'s OUTPUT

When one says @samp{fweave test}, the file @file{test.tex} is created.
Some @TeX{} commands contained in this file are created automatically;
others are copied from the web source file.  They are organized into several
sequential groups, as follows.

@quotation
@enumerate
@item 
@code{\input} command to read in @FWEAVE{}'s macro package.

@findex fwebmac.sty
By default, the initial input command is @samp{\input fwebmac.sty}
(@pxref{fwebmac.sty}).  The name of the macro package can be changed
with 
the @samp{-w} command-line option, but that is dangerous and useful only for
very special effects.  @xref{-w}.

@item 
@code{\Wbegin} command.

The @code{\Wbegin} macro sets up certain defaults (which can be overridden in
the limbo section).  In La@TeX{}, it also issues the
@samp{\documentclass@{article@}} and @samp{\begin@{document@}} commands.

@item 
Limbo text from the style-file parameter @code{limbo.begin}.  @xref{S_limbo}.

@item
Limbo text from @samp{@@l} commands. @xref{ATl}.

@item 
User's limbo section.

@item
Limbo text from the style-file parameter @code{limbo.end}.
@xref{S_limbo}.

@item 
@TeX{} commands for individual WEB sections.

@item 
@code{\input} command to read in the index data file.

@item 
@code{\input} command to read in the module-list data file.

@item 
@code{\Winfo} command (summarizes some status information).

@item 
@code{\Wcon} command (generates the Table of Contents, and ends the run).
@end enumerate
@end quotation



@node fwebmac.sty, LaTeX, Output, Typesetting
@comment  node-name,  next,  previous,  up

@subsection The macro package @file{fwebmac.sty}

@findex fwebmac.sty
@FWEAVE{} works in conjunction with the macro package
@file{fwebmac.sty}, which is always read into the @file{.tex} file by
default.  This file is (overly) complicated, so one should not mess with
it unless in dire emergency.  Most of its commands are intended for
behind-the-scenes  processing.  However, some features may be of general
interest; these are described in the items below.

For the most part, macros used internally by @file{fwebmac.sty} begin
with an uppercase @samp{W}.  If you are worried about macro conflicts, a
complete list of the macros appearing in @file{fwebmac.sty} can be found
in the Index produced by weaving @file{fwebmac.web}.

@menu
* User macros:: Macros defined for user convenience.
* Fonts::       Useful font commands.
@end menu

@node User macros, Fonts, fwebmac.sty, fwebmac.sty
@comment  node-name,  next,  previous,  up

@subsubsection User macros

For the user's convenience, @file{fwebmac.sty} defines a variety of
macros such as @samp{\FWEB}, @samp{\Fortran}, etc.  Refer to
@file{fwebmac.web} for a complete list.

@FWEAVE{} usurps various common single-character macros such as @samp{\.} for
its own purposes.  So the user can still access their original
definitions, those are @samp{\let} equal to alternative commands 
such as @samp{\period}.  For example, commands such as the following are
executed in @code{fwebmac.sty}: 

@example
\let\amp\&
\let\at\@@@@
\let\bslash\\
\let\caret\^
\let\dollar\$
\let\dstar\*
\let\equals\=
\let\leftbrace\@{
\let\period\.
\let\rightbrace\@}
\let\vertbar|
\let\PM\#
\let\PC\%
@end example
@noindent
(Some of the more inscrutable synonyms are for historical reasons.)

For the most up-to-date and detailed information, refer to @file{fwebmac.web}. 

@node Fonts, , User macros, fwebmac.sty
@comment  node-name,  next,  previous,  up

@subsubsection Fonts

@cindex Fonts
Several fonts have been declared.
Those include

@quotation
@itemize @bullet
@item
@samp{\titlefont} (large sans serif),

@item
@samp{\ttitlefont} (large typewriter), 

@item
@samp{\SC} (small caps),

@item
@samp{\Csc} (Caps/small caps), and

@item
@samp{\tentex} (@TeX{}'s extended character set). 

@end itemize
@end quotation

@noindent
For illustrations and further details, see @file{fwebmac.web}.

To typeset a string of characters in typewriter type, one may use the
@samp{\.} macro.  (More precisely, the name of this macro is the value
of the style-file parameter @code{format.typewriter}.  For more
information, see @ref{S_format}.)
When using this, one must escape the special
characters @samp{ \#%$^_@{@}~&}, as in @samp{\.@{\\alpha@}}.  (@FWEAVE{}
does that escaping automatically when typesetting strings in code mode.)
You may wish to surround @samp{\.@{...@}} with an @samp{\hbox}; that is
not done by default because @FWEAVE{} uses special trickery to break
long strings in code mode automatically, and that breaking would be
inhibited by an @samp{\hbox}.

@node LaTeX, , fwebmac.sty, Typesetting
@comment  node-name,  next,  previous,  up

@subsection La@TeX{} support

@cindex La@TeX{}
@cindex La@TeX{}2e
Original La@TeX{} support (through version 1.30) was substantially
incomplete in that La@TeX{}'s @code{\output} routine was usurped by the
relatively simple one used for @FWEB{}'s @TeX{} support.  However,
beginning with version 1.40, full La@TeX{} support is provided (and
Plain @TeX{} is @emph{not} supported); version 1.50 supports La@TeX{}2e.
La@TeX{}'s @code{\output} routine is used, as are its sectioning
commands (with minor changes), Table-of-Contents facilities, etc.

The following discussion is based on La@TeX{}2e.  If La@TeX{}2e is not
installed, @FWEAVE{} recognizes that fact and issues the
@samp{\documentstyle} command instead of @samp{\documentclass}.
@findex \documentstyle

Users are strongly encouraged to upgrade to La@TeX{}2e.  A useful book
that describes the present state of La@TeX{} is Goossens, Mittelbach,
and Samarin, @cite{The La@TeX{} Companion} (Addison--Wesley, Reading, MA,
1994).

@menu
* Document class::	LaTeX's document class, options, etc.
* REVTeX::              The REV@TeX{} scientific macro package.
* Packages::            Special FWEB-related La@TeX{}2e packages.
* Sections::	        Section numbering, spacing, etc.
* Index:LIndex.         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 La@TeX{} document.
@end menu

@node Document class, REVTeX,  LaTeX, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection La@TeX{}'s document class

@findex \documentclass
An @FWEB{}/La@TeX{} document is set up with the @samp{\Wbegin}
command, issued automatically by @FWEAVE{}.  See the summary at the
end of this section for the essence of what the @samp{\Wbegin} command
accomplishes.  

@FWEAVE{} uses @code{\documentclass@{article@}} by default.  In
principle, the document class can be changed by the @FWEB{} style-file
option @samp{LaTeX.class}; see @ref{Fwebmac params}.  However,
@emph{@FWEAVE{} has not been tested with most other document classes}.
It will probably not work with most document classes that redefine the
sectioning commands from those of @code{\documentclass@{article@}}.
However, it @emph{may} work with the @code{revtex} scientific macro
package.  @xref{REVTeX}.

To incorporate class options---i.e., to obtain the effect of
@samp{\documentclass[myoptions]@{article@}}---use the style-file parameter
@code{LaTeX.class.options}, as in
@cindex Class options
@cindex Options, class

@example
LaTeX.class.options "myoptions"
@end example
@noindent
To get two-sided printing, for example, one would say
@cindex Printing, two-sided

@example
LaTeX.class.options "twoside"
@end example

@findex \usepackage
@cindex User packages
@cindex Packages, user
To specify user packages---i.e., to obtain the effect of
@samp{\usepackage[pkgoptions]@{pkgname@}}---use the style-file parameters
@code{LaTeX.package} and @code{LaTeX.package.options}, as in

@example
LaTeX.package "pkgname"
LaTeX.package.options "pkgoptions"
@end example
@noindent
For example, to indent the first line of every section and to permit the
use of the @code{multicol} package (the latter is a useful way of
substantially cutting down on white space), say

@example
LaTeX.package "indentfirst,multicol"
@end example

Note that specifying @code{LaTeX.package} and
@code{LaTeX.package.options} results in the execution (by the
@code{\Wbegin} macro) of precisely @emph{one} line of the form

@example
\usepackage[myoptions]@{mypackages@}
@end example
@noindent
Sometimes one instead needs to have multiple @code{\usepackage} lines,
such as

@example
\usepackage[option1]@{package1@}
\usepackage[option2]@{package2@}
@end example
@noindent
To get this effect, one can put these commands explicitly into the
style-file parameter @code{doc.preamble} (see discussion two paragraphs
below), as in 

@example
doc.preamble = "\\usepackage[option1]@{package1@}\
                \\usepackage[option2]@{package2@}"
@end example

@TeX{} commands in the user's limbo section of the @code{web} source
file will be processed @emph{after} the @code{\begin@{document@}}
command.  Limbo commands from the style file can be inserted before
and/or after those in the limbo section with the aid of the style-file
parameters @samp{limbo.begin} and @samp{limbo.end}; see @ref{S_limbo}.

If there is a compelling reason to insert one's own La@TeX{}
commands between the @samp{\usepackage} and @samp{\begin@{document@}}
commands, one may use the style-file parameter @samp{doc.preamble},
whose value is a string consisting of La@TeX{} commands (empty by
default).  Those commands are processed immediately before
@samp{\begin@{document@}}.  One use of @samp{doc.preamble} is to inhibit
@FWEB{}'s tendency to keep a section together on one page.  To make it
break more readily in the middle of sections (particularly useful for
multicolumn output), say

@example
doc.preamble "\\secpenalty=0"
@end example

In summary, the beginning of the file output by @FWEAVE{} looks like
the following, where @samp{<parameter>} means the contents of the
style-file string called @samp{parameter}:

@example
\input fwebmac.sty
\Wbegin@{many obscure arguments@}
<limbo.begin>
Optional TeX commands copied from user's limbo section
<limbo.end>
@end example

@noindent
@findex \Wbegin
The @samp{\Wbegin} command essentially does the following:

@example
\documentclass[<LaTeX.class.options>]@{<LaTeX.class>@}
\usepackage[<LaTeX.package.options>]@{<LaTeX.package>@}
<doc.preamble>
\begin@{document@}
@end example
@noindent
For precise information about how @samp{\Wbegin} works, see
@code{fwebmac.web}.  If you feel that macro absolutely needs to be
changed, please inform the developer (@pxref{Support}).

@node REVTeX, Packages, Document class, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection Using REV@TeX{}

REV@TeX{} is the standard macro package used for formatting scientific
papers submitted to the American Physical Society, the American
Institute of Physics, and some European journals.  It modifies the
sectioning commands of @code{\documentclass@{article@}} and provides
various other useful macros.

Unfortunately, as of August, 1998, REV@TeX{} is not fully compatible
with La@TeX{}2e; it must be invoked with
@code{\documentstyle@{revtex@}}, not @code{\documentclass}.  This is
annoying, because @FWEB{}'s macros in @file{fwebmac.sty} default to
@code{\documentclass} if they recognize that La@TeX{}2e is loaded.

To use REV@TeX{}, uncomment the line in @file{fwebmac.sty} that says
@code{\useREVTeXtrue}.  (One cannot say @samp{\useREVTeXtrue} in the
limbo section of one's @code{web} source, because the document class has
already been selected by that time.)  You may wish to rename the
resulting file, say to @file{rwebmac.sty}, so it can be loaded in place
of the standard @file{fwebmac.sty}.  To do that, one would use the
command-line option @samp{-wrwebmac.sty} (see @ref{-w}).

Saying @code{\useREVTeXtrue} selects @code{\documentstyle} rather than
@code{\documentclass}.  To implement a standard command such as
@code{\documentstyle[aps,my_macros]@{revtex@}}, use the style-file
(@file{fweb.sty}) parameters @code{LaTeX.style} and
@code{LaTeX.options}, as in

@example
LaTeX.style "revtex"
LaTeX.options "aps,my_macros"
@end example
@noindent
Here @file{my_macros.sty} would be a user's macro package loaded in
addition to those of REV@TeX{} and @FWEB{}.

REV@TeX{} support is extremely recent.  There may be glitches; please
report those.  In a pinch, if La@TeX{} stops while processing a
REV@TeX{} file produced by @FWEAVE{}, try typing `s' (scroll mode) to
force it to continue; you might get usable output.

@node Packages, Sections, REVTeX, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection La@TeX{} packages related to @FWEB{}

The following packages are supplied with the @FWEB{} distribution and
can be used to achieve special effects.  Packages are invoked by giving
their names as arguments to the @code{LaTeX.package} command; see
@ref{S_LaTeX}.

@iftex
@itemize @bullet
@item
@code{fwebinsert} --- Enables insertion of woven code into a La@TeX{}
document.  
@xref{Inserting woven code}.

@item
@code{fwebnum} --- Number each section in ascending integer order.
@xref{Numbering}.

@item
@code{idxmerge} --- Merge several stand-alone indexes.  @xref{Merging indexes}.

@end itemize
@end iftex

@menu
* fwebinsert:Inserting woven code. Enable insertion of woven code into a La@TeX{} document.
* fwebnum:Numbering.              Number each section in ascending order.
* idxmerge:Merging indexes.       Merge several stand-alone indexes.
@end menu

@node Sections,  LIndex, Packages,  LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection Sections in La@TeX{}

@cindex La@TeX{} section
@findex \section
@findex \subsection
@findex \subsubsection
@FWEB{}'s sectioning commands @samp{@@*} and @samp{@@*@i{n}}
are converted into 
La@TeX{}'s section commands such as @code{\section} (@i{n}=0),
@code{\subsection} (@i{n}=1), and 
@code{\subsubsection} (@i{n}=2).  During La@TeX{}'s processing of the
@code{.tex} file, it 
keeps track of the maximum depth achieved by @samp{@@*@i{n}}.  This number is
written as the last item in the @file{aux} file.  During the next
La@TeX{} run, 
that number is used to map the untitled @ASP{} commands to the next most
insignificant sectioning command.  That level of sectioning command is
slightly redefined from La@TeX{}'s default, so don't try to redefine it.

The previous scheme means that it may be necessary to run La@TeX{} as
many as three times in order to resolve all sectioning and
cross-reference information correctly.  You should be warned in such
cases.  If not, you will recognize difficulties by noting that the Table
of Contents or section numbering is incomplete.

The @file{aux} file is also used by both processors to generate
appropriate error messages that refer to the La@TeX{} section number
instead of the internal one.

A discussion of alternative section-numbering schemes is given in
@ref{Numbering}. 

@node LIndex, Table of Contents, Sections, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection La@TeX{}'s index.

@cindex Index
@findex \INDEX
@findex \beforeindex
@findex \startindex
@findex \Wfin
The Index should be the last section of the code, and should be begun by the command @samp{@@* \INDEX.}.  For more
information, see @ref{S_index}.

The challenge of typesetting the Index is to get it into two-column mode
in the best possible way.  In the original Plain-@TeX{} @FWEB{},
special code was provided for this.  With La@TeX{}, however, one wants
to use standard features.

@cindex @code{multicol}, using
@cindex Package, @code{multicol}
@findex multicol.sty
@findex \twocolumn
The best solution is to use the user package @code{multicol}.  If that
is loaded by means of the style-file statement @samp{LaTeX.package
"multicol"}, then any text typed by the user following the @samp{@@*
\INDEX.} command will 
be typeset in single-column mode, after which two-column mode is
entered.  If it is not loaded, a @samp{\twocolumn} command is issued
@emph{before} the index section is begun (in order to get the Index
started on a new page).  

More precisely, what happens is the following.  When the @samp{@@*
\INDEX.} command is recognized, essentially the following operations are
performed, where the results are bracketed in the form @samp{[multicol :
nomulticol]}:  

@example
\beforeindex [\newpage : \twocolumn]
[print INDEX section heading]
\startindex  [\begin@{multicols@}@{2@} : \medskip]
\Wfin        [\end@{multicols@} : \relax]
@end example
@noindent
(Use of the asymmetrical name @samp{\Wfin} is for historical reasons.)

@cindex Columns, multiple
The positioning of @samp{\beforeindex} suggests a way of printing the
entire document in two-column mode.  If one enters multi-column mode in
the limbo section, then @samp{\beforeindex} can be used to terminate it.
It is best to do this at the @emph{end} of the limbo section; otherwise
user macro definitions in the limbo section must be made @code{\global} in order
that they remain defined in the Index.  The relevant commands can be
placed in the style file:

@example
LaTeX.package "multicol"

doc.preamble "\\secpenalty=0"

limbo.end "\\def\\beforeindex@{\\end@{multicols@}\\newpage@}\n\
\\begin@{multicols@}@{2@}\n\
\\raggedcolumns"
@end example
@noindent
Just to repeat, use only the first command to get just the Index printed
in two-column format; use the second and third ones to make the entire
document two-column.

@node Table of Contents, Customizing LaTeX, LIndex, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection La@TeX{}'s Table of Contents

@cindex Contents, table of
@cindex Table of Contents
@findex \FWEBtoc
La@TeX{} uses the @file{aux} file to accumulate the information for the
Table of Contents.

When La@TeX{} is used, the Table of Contents appears at the front of the
document by default (beginning with version 1.61).  This is accomplished
by setting the default value of the style-file parameter
@code{limbo.end} to @code{"\\FWEBtoc"}, where @code{\FWEBtoc} is defined
in @file{fwebmac.sty}.  If you initialize @code{limbo.end} yourself in
@file{fweb.sty}, you should include @code{"\\FWEBtoc"} at the end of
that initialization if you want the Table of Contents to appear in the
beginning.  Otherwise, it will appear at the end.

In essence, the Table of Contents is produced by the La@TeX{} commands

@example
\pagenumbering@{roman@}
\maketitle
\topofcontents
\tableofcontents
\botofcontents
\newpage
@end example

@noindent
@findex \topofcontents
@findex \botofcontents
@findex \maketitle
@findex \Title
@findex \title
By default, the @FWEB{} hooks @code{\topofcontents} and
@code{\botofcontents} are empty, 
but they may be used in special circumstances to override the usual
behavior.  One can set the parameters for @code{\maketitle} in the limbo
section in the usual La@TeX{} way, except that it is better to use
@FWEB{}'s @code{\Title} macro instead of @code{\title}:

@example
\Title@{MYCODE.WEB@}
\author@{My name@}
\date@{January 1, 2001@}
@end example

By default, the argument of the @code{\Title} macro is printed both on
the title page and as a running headline in the document.  The default
font for the title is @code{\ttitlefont}; that for the running headline
is @code{\large\tt}.  However, @code{\Title} has one optional argument
that allows one to override the running headline, perhaps by specifying
a shorter form.  Say

@example
\Title[@i{Short title}]@{@i{Long title}@}
@end example
@noindent
to make the running headline be @samp{\large\tt @i{Short title}} and the
title-page title be @samp{\ttitlefont @i{Long title}}.  

The \@FWEB{} @code{\Title} macro calls La@TeX{}'s @code{\title} macro
with the long title as its argument.
By default, @FWEAVE{} uses (in the @samp{\Wbegin} macro)

@example
\title@{@}%
\author@{@}%
\date@{\today\\[3pt]\Time@}%
@end example

@findex \numberline
Section numbers in the Table of Contents are produced by the La@TeX{}
macro @code{\numberline}.  La@TeX{}'s default definition is inadequate
when section numbers are very large; they extend to the right and can
overwrite the section name.  The macro is redefined more appropriately
when the package @code{fwebnum} (@pxref{Numbering}) is used.

@node Customizing LaTeX, Inserting woven code,  Table of Contents, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection Customizing La@TeX{}'s output

Several (@TeX{}) flags are provided to change the appearance of the final
La@TeX{} document.  (This appearance is a bit experimental, and it is
fair to say that not everything may be fully debugged; please report
problems.)  These are (@samp{...} means either @samp{true} or @samp{false})

@quotation
@itemize @bullet
@item 
@findex \pagerefs
@code{\pagerefs...} (index references by pages or section numbers);

@item 
@findex \numberTeX
@code{\numberTeX...} (number the beginning of unnamed TeX parts);

@item 
@findex \numberdefs
@code{\numberdefs...} (number the beginning of the definition part);

@item 
@findex \numbercode
@code{\numbercode...} (number the beginning of the code part).
@end itemize
@end quotation

@noindent
The defaults for these flags are

@example
\pagerefsfalse
\numberTeXfalse
\numberdefstrue
\numbercodetrue
@end example

@noindent
If desired, one may override these in the limbo section.
(They are defined using Plain @TeX{}'s @samp{\newif} rather than the
equivalent La@TeX{} command because they may also be used when La@TeX{}
is not present.)

@code{\numberTeX} is on the verge of obsolescence.  Try to not use it;
never use it in conjunction with the package @code{fwebnum}.
@xref{Numbering}

@menu
* Page references::     Indexing by page numbers.
* Headers::             The content of page headers.
* Numbering::           Various section numbering schemes.
@end menu

@node Page references, Headers, Customizing LaTeX, Customizing LaTeX
@comment  node-name,  next,  previous,  up

@subsection Page references

@findex \pagerefs
@cindex Page numbers
@cindex Sections, numbering
When one says @samp{\pagerefstrue} (La@TeX{} only), index references are
made by page numbers rather than module numbers or La@TeX{} section
numbers.  If there is more than one section per page, they are
identified by @samp{a}, @samp{b}, @samp{c}, etc., such as @samp{section
17b}.  (Presently, this will not work correctly when @code{multicol} is
used for the body of the document.)

The information necessary to process page references in this way is
written into the @file{aux} file.  As is usual with La@TeX{}, several runs
may be required for the references to be fully consistent with the
source file.

@node Headers, Numbering, Page references, Customizing LaTeX

@subsection Page headers

@cindex Headers
@cindex Page headers
The very top (header) line on each page of @FWEAVE{}'s output contains
several pieces of information:

@itemize @bullet

@item
the current section name or document title;

@item
the page number; 

@item
the range of La@TeX{} section numbers on the
page (these are preceded by the 
@ifinfo
@samp{\S}
@end ifinfo
@tex
\S\
@end tex
symbol); and

@item
the range of integer section numbers as understood internally by
@FWEAVE{} (those are in square brackets and preceded by the @samp{#} sign).

@end itemize

@node Numbering, , Headers, Customizing LaTeX
@comment  node-name,  next,  previous,  up

@subsection Section numbering schemes

@cindex Sections, numbering
@cindex Package, @code{fwebnum}
@findex fwebnum.sty
The @FWEB{} commands @samp{@@*} and @ASP{} are translated by
complicated magic into La@TeX{} commands such as @code{\section},
@code{\subsection}, etc.  By default, use of
@code{\documentclass@{article@}} then produces Dewey-decimal section
numbers such as 2.13.4 (subsubsection 4 of subsection 13 of section 2).
When the section tree is very deep, these numbers can look somewhat obtrusive.

An alternative scheme (that of the original @sc{web}) is to merely
number each section in ascending integer order, beginning with 1.  This
can be done by specifying the package @code{fwebnum}, as in

@example
LaTeX.package = "fwebnum"
@end example
@noindent
This package is supplied with the @FWEB{} distribution; it is still
somewhat experimental.

By default, @code{fwebnum} numbers all sections, including unnamed
ones.  To prohibit numbering of unnamed sections, use the package option
@code{dontnumberunnamed}, as in

@example
LaTeX.package.options = "dontnumberunnamed"
@end example
@noindent
This option will eventually make @code{\numberTeX} obsolete; do not use
@code{\numberTeX} in conjunction with @code{fwebnum}.

@node Inserting woven code, , Customizing LaTeX, Packages
@comment  node-name,  next,  previous,  up

@subsubsection Package @code{fwebinsert}:  Inserting @FWEAVE{}'s output into a La@TeX{} document

@cindex FWEB output, inserting into LaTeX document
@findex fwebinsert.sty
Beginning with version 1.61, it is (barely) possible to insert the
@TeX{} output woven by @FWEAVE{} into a La@TeX{} document.  For
example, a code listing could be an appendix to a dissertation, or a
handbook on numerical methods could insert fragments of code formatted
by @FWEAVE{}.

Suppose one has the file @file{test.web} and used @FWEAVE{} to create
@file{test.tex}.  Unfortunately, it does @emph{not} work to simply
@code{\input test.tex} into a La@TeX{} document, because by
default @file{test.tex} operates in a ``stand-alone'' mode and tries to
issue a @code{\begin@{document@}} command.

Instead, one must use the package @code{fwebinsert} and the special
input command @code{\FWEBinput}, as in the following example.  There are
two important steps.

@quotation
@enumerate
@item
Use @FWEAVE{} to create @file{test.tex}.
[You may wish to use the @samp{-x} flag
(@pxref{-x}) to prevent some of the lists at the end, such as the index
or module list, from being printed.]

@item 
Now @samp{latex test} until all of the section numbering is up-to-date.
(This step is necessary because information in the @file{aux} file is
used in processing the section headings.)
@end enumerate
@end quotation
@noindent
Now @file{test.tex} is ready to be inserted in a code like the
following:

@example
\documentclass@{article@}
\usepackage@{fwebinsert@}

\begin@{document@}

\section@{Body@}

The body of the document.

\appendix

\FWEBinput@{test@}

\end@{document@}
@end example

Note that the @samp{@@*} commands in @file{test.web} are converted into
La@TeX{} sectioning commands such as @code{\section}.  The above example
works correctly because the first @samp{@@*} in @file{test.web} is
equivalent to a @code{\section} (level 0) command, which should indeed
immediately follow an @code{\appendix} command.  Suppose, however, that
you wanted to input @file{test.web} as part of the body of the above
example, and wanted the @samp{@@*}s to be treated as subsections (level
1) rather than sections.  To tell @code{fwebinsert} what level number to
assign to the @samp{@@*}s, provide that number as an optional argument
to @code{\FWEBinput}, as in the following example:

@example
\documentclass@{article@}
\usepackage@{fwebinsert@}

\begin@{document@}

\section@{Body@}

The body of the document.

\FWEBinput[1]@{test@}

\end@{document@}
@end example
@noindent
Alternatively, say @code{\FWEBlevel@{1@}} before the @code{\FWEBinput}.
(The optional argument construction merely calls @code{\FWEBlevel}.)

Here are some caveats about @code{fwebinsert}:

@itemize @bullet

@item
Implementing this package was tricky.  It may work in simple
circumstances, but it is not fully debugged.

@item
The @code{\FWEBinput} command surrounds the included @TeX{} code with
@code{\begingroup}...@code{\endgroup}, in an attempt to prevent various
macro conflicts.  As it stands, the command @code{\fwebinput} is
@code{\let} equal to @code{\FWEBinput}.  If necessary, one could redefine
@code{\fwebinput} to not include the enclosing
@code{\begingroup}...@code{\endgroup}.  

@item
For anything except level-0 inclusions, one should have just one
@code{\FWEBinput} command following each sectioning command.  (This is a
bug.)

@item
@findex fwebnum.sty
One is supposed to be able to use the package @code{fwebnum}
(@pxref{Numbering}) in 
conjunction with @code{fwebinsert}.  One can apply that to either the
included file (via a @code{LaTeX.package} entry in @file{fweb.sty}), the
including file (via a @code{\usepackage} command), or both.  Try out
these various combinations to see what emerges.

@end itemize

@node Pretty-printing, , Typesetting, Documentation
@comment  node-name,  next,  previous,  up

@section Pretty-printing

@cindex Pretty-printing
@dfn{Pretty-printing} refers to @FWEAVE{}'s attempt to typeset and
highlight the code in a readable way.  This is usually done
automatically for all of the compiler-like languages such as C.
However, it can be inhibited by turning on the N mode with
@samp{@@N} or by using the @sc{verbatim} language (selected with @samp{@@Lv}).

Pretty-printing is one of those topics that can arouse strong passions:
your idea of what's esthetic may not be mine.  Unfortunately,
@FWEB{}'s formatting rules are mostly hard-coded, so if, for example,
you don't like 
the way braces are arranged in typeset C code, you're mostly stuck.
Most directly, this possibly undesirable choice comes from design
decisions made by previous authors.  It also makes @FWEAVE{} very
fast, and enables certain complicated tricks that seem difficult or
impossible to accomplish with a completely customizable approach.  The
latter seems quite formidable, and has not been attempted---a good
thesis project for the 21st century.

@menu
* Alternatives::        Alternatives for various input tokens.
* Pseudo-operators::    Invisible parts of speech.
* Overloading::         Changing the appearance of various quantities.
@end menu

@node Pseudo-operators, Overloading, Alternatives, Pretty-printing
@comment  node-name,  next,  previous,  up

@subsection Pseudo-operators

@cindex Pseudo-operators
Pseudo-operators behave like a particular part of speech for the
purposes of @FWEAVE{}'s formatting, but are invisible on output; they
are ignored by @FTANGLE{}.  The pseudo-operators are

@example
@@e @r{--- pseudo-expression.  @xref{ATe}.}
@@; @r{--- pseudo-semicolon.  @xref{AT;}.}
@@: @r{--- pseudo-colon.  @xref{ATcolon}.}
@end example

@node Alternatives,  Pseudo-operators, Pretty-printing, Pretty-printing
@comment  node-name,  next,  previous,  up

@subsection Alternatives for various input tokens

@FWEAVE{} translates various input constructions into allegedly more
readable symbols---for example, in @sc{Fortran} it translates
@samp{.LT.} into @samp{<}.  
@ifinfo
The printed documentation contains a table of what one can type on
input, and what @FWEAVE{} will output.
@end ifinfo

@tex
Here is a table of
what one can type on input, and what @sc{Fweave} will typeset. The first entry
is standard @sc{Fortran}; the parenthesized material is an allowable input
alternative. (In most cases,
the pretty input alternatives follow C's~convention.)
$$
\def\i(#1,#2){{\tt #1} \def\temp{#2}\ifx\temp\empty\else({\tt #2})\fi}
\def\htop#1{\vtop{\halign{##\hfil&$\to \hbox{##}$\hfil\cr#1}}}
\let\WL\le
\let\WS\equiv
\let\WI\neq
\let\WG\ge
\let\WW\land
\let\WV\lor
\def\EQV{\mathrel{?{=}}}
\def\NEQV{\not\equiv}
\let\WR\lnot
\let\SlSl\parallel
\chardef\BS=`\\
\htop{
\i(.lt.,<) & $<$\cr
\i(.le.,<=) & $\WL$\cr
\i(.eq.,==) & $\WS$\cr
\i(.ne.,!=,<>) & $\WI$\cr
\i(.gt.,>) & $>$\cr
\i(.ge.,>=) & $\WG$\cr
\i(.and.,\amp\amp) & $\WW$\cr}
\qquad\qquad
\htop{
\i(.or.,||) & $\WV$\cr
\i(.neqv.,) & $\NEQV$\cr
\i(.xor.,) & $\NEQV$\cr
\i(.eqv.,) & $\EQV$\cr
\i(.not.,!) & $\WR$\cr
\noalign{\smallskip}
\i(**,\^) & {\tt (a+b)\^(c+d)} $\to (a+b)^{c+d}$\cr
\i(//,\BS/) & $\SlSl$\cr
}$$
These same conventions are allowed in @sc{Ratfor} mode.  Note that in @sc{Fortran}
and @sc{Ratfor} @samp{//} is interpreted  by default as the concatenation
symbol, not the start of a short comment. 
To override that default, use one of the command-line options @samp{-n/},
@samp{-r/}, or @samp{-/}, 
or use a language-changing command of the form @samp{@@n/}.
@end tex


@node Overloading, , Pseudo-operators, Pretty-printing
@comment  node-name,  next,  previous,  up

@subsection Overloading operators and identifiers

@cindex Overloading
For special effects in the woven output, there are commands to help
one change the appearance of operators and identifiers.

@subsubsection Overloading operators

@cindex Overloading operators
@cindex Operators, overloading
A feature common to both C++ and @sc{Fortran}--90 is @dfn{operator overloading},
the ability to extend or redefine the definition of an operator such as
@samp{.FALSE.}
or @samp{=}.  @sc{Fortran--90} even allows one to define new @dfn{dot
operators}---for example, one might define the operator @samp{.IN.} to test
for inclusion in a set.  In a nontrivial extension of the original design,
@FWEAVE{} allows one to define how overloaded
operators should appear on output.
@tex
\def\&#1{{\bf #1}}%
\gdef\.#1{{\tt #1}}%
\def\\#1{\leavevmode\hbox{\it#1\/\kern.05em}}%
For example, in the opinion of the author it is much more readable
to read `$\&{if}\.(x \in \\{set}\.)$' than `\&{if}\.(x\ \.{.IN.}\
\\{set}\.).'
@end tex
Indeed, this feature can be used even when the compiler language itself
does not permit overloading in order to customize the appearance of the
woven output.

The @samp{@@v} control code is used to change the appearance of an operator.
The format is

@example
@@v new_operator_symbol_or_name "TeX material" old_operator
@end example

@noindent 
This means ``Display the new operator according to the @i{@TeX{}
material}, but treat it like the old operator---e.g., unary or binary---for
formatting purposes.  The 
quoted @TeX{} material is treated just like a C string, so if
one wants to include a backslash one must escape it with another backslash.
For example, one can make an equals sign display on output as
a large left arrow by saying

@example
@@v = "\\Leftarrow" =
@end example

@noindent
Two @sc{Fortran} examples are

@example
@@v .FALSE. "\\.@{.FALSE.@}" .FALSE.
@@v .IN. "\\in" +
@end example

This feature can go a long way toward enhancing readability of the woven
output, particularly when operators are actually being overloaded.  It can
also lead to arbitrarily bizarre output that no-one else will understand.
As usual, restraint is advised.

@subsubsection Overloading identifiers

@cindex Overloading identifiers
@cindex Identifiers, overloading
Although operator overloading is quite useful, it does not allow one to
change the appearance of identifiers.  In its most general form, such a
facility becomes quite complicated; one must endow @FWEAVE{} with a
macro-processing facility analogous to that of @FTANGLE{}.  This has
not been 
done yet (maybe it will be someday).  In the meantime, one has the
command @samp{@@W},
which provides a restricted form of such a facility.  @emph{This
command is experimental, and not firmly established.  Changes in usage
and/or syntax may be made in future versions.}

The most general form of the @samp{@@W} command is

@example
@@W identifier "replacement text"
@end example

@noindent 
This means:  Replace any references to @i{identifier} in the
woven output with the @i{replacement text}.  

A more restrictive form is

@example
@@W identifier \newmacro
@end example

@noindent 
which replaces references to @i{identifier} with a call to
@code{\newmacro}.  (Note that there are no quotes in this form.)

The shortest form is

@example
@@W identifier .
@end example

@noindent 
which replaces references to @i{identifier} with a call to
@code{\identifier}.  For example, the identifier @i{x} normally appears in
woven output as @samp{\.@{\Wshort\@{x\@}@}}.  If one says

@example
@@W x .
@end example

@noindent 
one will instead get the macro reference @samp{\x}, which could
be defined to give a variety of special effects.  (However, one may need
some rather intimate understanding of @FWEAVE{}'s output in order to
ensure that things always work correctly.)

One of the important uses of this facility is to expedite special
formatting of array references.  This subject is discussed separately below
in the section on ``Special array formatting'' (sorry, that isn't here
yet), where an example is given.


@node Index, Customization, Documentation, Top
@comment  node-name,  next,  previous,  up

@chapter @FWEB{}'s INDEX.

@FWEB{} has several powerful indexing facilities:

@quotation
@enumerate
@item
It sorts and writes its own self-contained (@dfn{internal}) index, including
cross-references to all the variables as well as items inserted by the
user.

@item
It can write its cross-reference information to a file formatted for use
by the @code{makeindex} utility.  This feature facilitates creation of a
master index that contains information about several @code{web} files.

@end enumerate
@end quotation

@menu
* Internal index::      The self-contained index produced by @FWEB{}.
* Using makeindex::     Writing index data for use by @code{makeindex}.
* Merging indexes::     Using the @code{idxmerge} utility to merge indexes.
@end menu

@node Internal index, Using makeindex, Index, Index
@comment  node-name,  next,  previous,  up

@section @FWEB{}'s self-generated index

One of the most useful features of
@FWEB{} is that it automatically generates an Index of all variable
usage.   One 
can also insert one's own index 
entries by using the commands

@itemize @bullet

@item
@samp{@@^} (entry in Roman type; see
@ref{AT^}),

@item
@samp{@@.} (entry in typewriter type; see @ref{ATdot}), and

@item
@samp{@@9} (user-defined format; see @ref{AT9}).


@end itemize

(More discussion to be completed.)

@node Using makeindex, Merging indexes, Internal index, Index
@comment  node-name,  next,  previous,  up

@section Creating a stand-alone index with @code{makeindex}

@cindex Index, stand-alone
@cindex Makeindex, using
In addition to the internal index described in the previous section
(@pxref{Internal index}), @FWEAVE{} can write the index data to a file
formatted for later, stand-alone processing by the @code{makeindex}
utility.  (Several such indexes can be merged together; see @ref{Merging
indexes}.)  The procedure is simple, although the following discussion goes
into some rather arcane details.

@subsection Creating a stand-alone index:  Summary

As a quick reference for those who have already read the details in the
next subsection, the procedure to print a stand-alone index with
@code{makeindex} is as follows.  First, create, if necessary, a file
@file{index.tex} that @code{\input}s @file{index.ind}.  (A skeleton
is illustrated in the next subsection.)  Then:

@example
fweave -XI test.web @r{% Creates test.idx and test.sty.}
makeindex -s test.sty -o index.ind test.idx @r{% Creates index.ind.}
latex index
@end example
@noindent
If you're not happy with the @code{\pg} macro supplied in
@file{fwebmac.sty}, define it yourself in @file{index.tex}.  

In this procedure, note the use of the @samp{-XI} option and the use of
a different root name (@file{index} here) for the output file.

@subsection Creating a stand-alone index:  Details

@findex -XI
To create an index file in a form suitable for later stand-alone
processing by @code{makeindex}, use the @samp{-XI} option to
@FWEAVE{}.  If the @code{web} file is @file{test.web}, the default
name of the @code{makeindex} output file is @file{test.idx}.  (This name
can be overridden by the style-file parameter @code{makeindex.out}.)  Run
@code{makeindex} on @file{test.idx} to create the La@TeX{} file
@file{index.ind} (see following discussion for details).  A stand-alone
index can then be produced by saying @samp{latex index}, where a skeleton
version of @file{index.tex} would be

@example
% index.tex --- skeleton for printing a stand-alone index.
\documentclass@{article@}
\usepackage@{fwebmac@}

\begin@{document@}

\input@{\jobname.ind@}

\end@{document@}
@end example
@noindent
(In practice, a more involved procedure will probably be followed; see below.)

@cindex Style file, for makeindex
Usually @code{makeindex} works in conjunction with a style file.  [In
fact, the syntax of @FWEB{}'s style file (@pxref{Style}) was motivated
by that of @code{makeindex}.]  When the @samp{-XI} option (@pxref{-X_}) is used,
@FWEAVE{} will @emph{create} an appropriate style file for
@code{makeindex}.  (The default name of @file{test.sty} can be overridden
by the style-file parameter @code{makeindex.sty}.)  To run
@code{makeindex} on the index data for @file{test.web} and create the
output file @file{index.ind}, one would thus say

@example
makeindex -s test.sty -o index.ind test[.idx]
@end example
@noindent
It's important to use the @samp{-o} option with a name different than
the original file name, because it simplifies the construction of the
skeleton file @file{index.tex} that prints the stand-alone index.

@FWEAVE{} writes @file{test.sty} because the contents of that file may
depend on parameter settings in @FWEB{}'s style file @file{fweb.sty}.
@FWEB{}'s style vocabulary includes all parameters understood by
@code{makeindex}.  If a @code{makeindex} parameter is called
@samp{param}, one references it in @file{fweb.sty} by
@samp{makeindex.param}.  Thus, to change the @samp{headings_flag} of
@code{makeindex}, one would put into @file{fweb.sty} a line like
@samp{makeindex.headings_flag = 1}.  To see a list of all
@code{makeindex}-related parameters, say @samp{fweave -Zmakeindex}
(@pxref{-Z_}).  Remember, @emph{do all @code{makeindex} customizations
in @file{fweb.sty}; the actual style file @file{test.sty} that will be
read by @code{makeindex} is written automatically by @FWEAVE{}.}

The @file{.idx} file will contain a list of entries that begin with
@samp{\indexentry} (more precisely, the value of the parameter
@samp{makeindex.keyword}).  The general form is 

@example
\indexentry@{sort key:identifier expression|macro@}@{page number@}
@end example
@noindent
Typical entries are

@example
\indexentry@{istream:"\>@{istream@}|pg@{@}@{@}@}@{1@}
\indexentry@{main:"\>@{main@}|pg@{@}\underline@}@{1@}
\indexentry@{pow:"\@@@{pow@}|pg@{@}@{@}@}@{2@}
\indexentry@{z:"\"|z|pg@{@}\underline@}@{2@}
@end example
@noindent
Here the colon is the value of @samp{makeindex.actual}; it separates the
sort key (before the colon) from the actual expression to be printed.
The macros such as @samp{\>} typeset the identifiers in the appropriate
way, depending on their use in the code.  Note that the backslashes are
quoted with the value of @samp{makeindex.quote}, which is by default the
double quote.

Although one might guess that the typesetting macros such as @samp{\>}
would be defined in @file{fwebmac.sty}, that is not true.  Rather, for
various technical reasons they
are equated to macros in @file{fwebmac.sty} as one of the operations of
the @samp{\Wbegin} macro that is executed at the beginning of every
@code{tex} file output by @FWEAVE{}.  For example, @samp{\Wbegin} does
the equivalent of @samp{\let\>\Wid}.  Unfortunately, without further
action that equating would be forgotten by a La@TeX{} run made on the
output @file{index.ind} of @code{makeindex}.  For that reason, @FWEAVE{}
appends the appropriate @samp{\Wequate} macro to the end of
@samp{makeindex.preamble}.  This is one specific instance that
necessitates that @FWEAVE{} write the @code{makeindex} style file.

Each of the @samp{\indexentry}s contains the encapsulation character
@samp{|} (the value of @samp{makeindex.encap}).  By the conventions of
@code{makeindex}, everything between the encapsulation character and the
closing right brace defines a macro expression that acts on the page
number.  E.g., the general form above generates the command
@samp{\macro@{@i{page number}@}}.  The specific macro construction
output by @FWEAVE{} is

@example
\pg@{@}@{@i{possible action macro}@}@{@i{page number}@}
@end example
@noindent
Here the name @samp{pg} is the value of @samp{makeindex.page}.  The
@dfn{action macro} is something like @samp{\underline}, which would be
used by @FWEAVE{} to underline the page number to indicate where a
variable is defined.  A default definition of @samp{\pg} is given is
@file{fwebmac.sty}.  It is a three-argument macro,
@samp{\def\pg#1#2#3@{...@}}, where the arguments are as follows:
@findex \pg

@example
#1 @r{--- Integer file identification number}
#2 @r{--- Action macro.}
#3 @r{--- Page number.}
@end example
@noindent
The definition should contain the construction @samp{#2@{#3@}}---i.e.,
the page number must be the argument of the action macro.  The first
argument is left empty in the @file{.idx} file written by @FWEAVE{}.
This can be filled in later by the utility @code{idxmerge}
(@pxref{Merging indexes}) that merges the indices
from several @code{web} files.  For example, in a master index one might
ultimately print page numbers like @samp{II.5}, where @samp{II} refers to
a file such as @file{test2.web}.  To aid this merging process, the root
name of the @code{web} file is written as a comment at the top of the
@file{.idx} file output by @FWEAVE{}.

@node Merging indexes, , Using makeindex, Index
@comment  node-name,  next,  previous,  up

@section Using the @code{idxmerge} utility to merge indexes

@cindex Indexes, merging
@findex idxmerge.sty
In a large project, one may maintain and work with several @FWEB{}
files.  It may be useful to produce a global index that spans all of
those files.  To this end, the utility @code{idxmerge} and associated
La@TeX{} package @code{idxmerge} are supplied with
the @FWEB{} distribution.  

@subsection Using @code{idxmerge}:  Summary

As quick reference for those who have already plowed through the
following details, here is a summary of the procedure.  To print a
stand-alone index by merging the indexes from several @code{web}
sources, do the following.  First, create, if necessary, a file
@file{index.tex} that @code{\input}s @file{index.ind}.  Then:

@example
fweave -XI test1.web
fweave -XI test2.web
fweave -XI test3.web

idxmerge -oindex test1.idx test2.idx test3.idx 
        % Creates index.ind and index-names.tex.
makeindex -s test1.sty index
latex index
@end example

Note the use of the @samp{-XI} option.  For further background, see the
previous section, @ref{Using makeindex}.

@subsection Using @code{idxmerge}:  Details

Suppose one has three files, @file{test1.web}, @file{test2.web}, and
@file{test3.web}.  To use @code{idxmerge}, weave each of the files
separately, using the @samp{-XI} option to create @file{test*.idx} and
@file{test*.sty}.  Then say

@example
idxmerge -oindex test1.idx test2.idx test3.idx
@end example
@noindent
This creates two output files:  @file{index.idx}, and
@file{index-names.tex}.  @code{idxmerge} first sorts the list of file
names.  It then writes one entry into @file{index-names.tex} for each
file, of the form

@example
\idxname@{@var{n}@}@{file_name@var{n}@}
@end example
@noindent
This file can be @code{\input} by the @code{\topofindex} command (for an
example, see the La@TeX{}2e package @code{idxmerge}) (supplied with
the @FWEB{} distribution) and used to create a list of the merged files.
@findex \topofindex
@findex \idxname

Then it merges the @code{\indexentry} commands from each of the input
files into @file{index.idx}, filling in the integer file identifier @var{n}
(the position of the file in the sorted list) into the first argument of
the @code{\pg} macro.  One can now say

@example
makeindex -s test1.sty index
@end example
@noindent
This creates @file{index.ind}, which can be processed by, for example,
a simple modification of the simple La@TeX{} template given above in
@ref{Using makeindex}.  The only difference is that the package
@code{idxmerge} was used; in that file, the macros @code{\topofindex}
and @code{\idxname} are appropriately defined to print out a numbered
list of the merged files to cross-reference into the numerical file- and
page-number entries in the body of the index.  Here is an example
(provided in the @FWEB{} distribution):

@example
% index.tex --- skeleton for printing a stand-alone index.
\documentclass@{article@}
\usepackage@{fwebmac,idxmerge@}

\begin@{document@}

\input@{\jobname.ind@}

\end@{document@}
@end example
@noindent

@node Customization, Hints, Index, Top
@comment  node-name,  next,  previous,  up

@chapter CUSTOMIZATION

@cindex Customization
@cindex Customizing @FWEB{}
@cindex @FWEB{}, customizing
The default behavior of @FWEB{} can be changed in a variety of ways.  

@quotation
@enumerate
@item 
@sc{unix} environment variables (logical variables in VMS) affect path or
file names. 

@item 
An initialization file resides in the home directory.

@item 
A style file resides in the current directory.
@end enumerate
@end quotation

The initialization file (usually called @file{.fweb}) is intended to contain
command-line options (one per line) that are to be used in every run.
@xref{Initialization}. 

The style file (called @file{fweb.sty} by default; see @ref{-z}) is
intended to provide more local customization, perhaps 
differing for each source file and group of source files.  The style
file does not contain command-line 
options; rather, it contains parameter settings that override
@FWEB{}'s defaults.  The @samp{-p} option (@pxref{-p})
may be used to specify a style-file entry in @file{.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:

@quotation
@enumerate
@item 
Evaluate environment variables.  @xref{Environment variables}.

@item 
Read @file{.fweb} and remember its contents; sort those into three
groups:  options beginning with @samp{-}, beginning with @samp{&}, and
beginning with a letter (file names) .  @xref{Initialization}.

@item 
Process @file{.fweb} options beginning with @samp{-} (or @samp{+}, for
backward compatibility), except for @samp{-p}.

@item 
Read and process command-line options, except for @samp{-p}.  @xref{Options}.

@item 
Process remaining @file{.fweb} options (either file names, or options
beginning with @samp{&}).

@item 
Process any @samp{-p} options from @file{.fweb}.  @xref{-p}.

@item 
Process the style file.  @xref{Style}.

@item
Process any @samp{-p} options from the command line.

@end enumerate
@end quotation

Unfortunately, because not all options are processed immediately when
they are read, errors may not show up when one expects.  For example,
nothing is actually processed while @file{.fweb} is being read; its
contents are just being stored.  It
could therefore happen that a syntax error in entering a @samp{-p}
option in @file{.fweb} may not be reported until after the style file
has been read, possibly confusing the user as to the source of the
error.

@menu
* Environment variables::       Environment or logical variables.
* Initialization::              Initialization file.
* Memory allocation::           Dynamic memory allocation.
* Style::                       Style file.
@end menu

@node Environment variables,Initialization,Customization,Customization
@comment  node-name,  next,  previous,  up

@section Environment variables

@cindex Environment variables
@cindex Variables, environment

@code{FWEB_HDR_INCLUDES} --- Colon-delimited list of directories for the
C preprocessor (in the form of @code{gcc}) to
search for @samp{#include} header files.  This is used in conjunction
with the @samp{-H} option; see @ref{-H_}.  (One can append to this list
by means of the @samp{-I} option, provided that option comes
@emph{after} the @samp{-H}; see @ref{-I_}.)
@findex FWEB_HDR_INCLUDES

@code{FWEB_INCLUDES} --- Colon-delimited list of directories to search for
@samp{@@i} include files.  (One can append to this list by means of the
@samp{-I} option, provided that option comes @emph{before} any use of
@samp{-H}; see @ref{-I_}.)  
@findex FWEB_INCLUDES

@code{FWEB_INI} --- Name of the initialization file. If not defined, either
@file{.fweb} or @file{fweb.ini} is chosen, depending on the machine.  The
initialization file always resides in @code{$HOME}.
@findex FWEB_INI


@code{FWEB_STYLE_DIR} --- Directory in which the style file resides.  If not
defined, the current directory is used.
@findex FWEB_STYLE_DIR

@node Initialization,Memory allocation,Environment variables,Customization
@comment  node-name,  next,  previous,  up

@section Initialization

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

@subsection The initialization file

@cindex Initialization file
@cindex File, initialization
@cindex @FWEB{}, initializing
@findex .fweb
On startup, @FWEB{} attempts to read an initialization file.  This always
resides in the user's home directory.  It is usually called @file{.fweb}
(@file{fweb.ini} on personal computers).  The default file name can be
overridden by the environment variable @code{FWEB_INI}.

One may put into @file{.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 @samp{-} (or a @samp{+} for backward
compatibility), it is processed @emph{before} the actual command-line
options; if it begins with @samp{&} or is a file name, it is processed
after.  Generally, @file{.fweb} options should begin with @samp{-} so
that one may override them from the command line.  The @samp{%} sign
begins a comment terminated by the end-of-line.
  
@node Memory allocation,Style,Initialization,Customization
@comment  node-name,  next,  previous,  up

@subsection Memory allocation

@cindex Memory allocation
@cindex Allocation, memory
The command-line option @samp{-y} (@pxref{-y}) is used to change the
default allocation for a dynamic array.  The arrays have a one- or
two-character abbreviation denoted by @i{aa}.  Some error messages will
use this abbreviation when suggesting that one increase a default
allocation.  To query the present allocations of variable @i{aa}, just say
@samp{-y@i{aa}}.  To query everything, say @samp{-y}.

This whole scheme is somewhat annoying.  In most cases, dynamic arrays
should be reallocated automatically.  That can be done without too much
difficulty, but I was reluctant to try it for Version 1.61 in fear of
breaking something.  Please wait for the year 2000.

If one uses @samp{-y} to examine the maximum permitted values of these
parameters, one will note the magic number 10239 appearing
occasionally.  This number is a bit less than 64K/5; it is a signature
of an inherently 32-bit design that goes back to Knuth.  Unfortunately,
this number can't be increased without some radical redesign.  Wait for
the year 2100.

@menu
* -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.
@end menu

@node -yb, -ybs, Memory allocation, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yb}:  Maximum bytes for identifiers, index entries, and module names

@findex -yb

Unique identifiers, index entries, and module names are stored
contiguously in a large memory area, the size of which is controlled by
@samp{-yb}.  The default may need to be increased for very large source
files, or decreased to squeeze things into a personal computer.  See
also @ref{-yn}.

@node -ybs, -ycb, -yb, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ybs}:  Size of the change buffer, in bytes

@findex -ybs

Information from change files is read into the change buffer, whose size
is controlled by @samp{-ybs}.  It should not be necessary to change this
unless an error message specifically tells one to do so.

@node -ycb, -ycf, -ybs, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ycb}:  Size of line buffer for C output, in bytes

@findex -ycb

@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 @samp{-ycb} option controls
the maximum output line length for C and C++.  

The analogous command @samp{-yxb} controls the output line length for
@TeX{} and the verbatim mode.  @xref{-yxb}.

@node -ycf, -ycg, -ycb, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ycf}:  Size of a Ratfor buffer, in bytes

@findex -ycf

The sizes of buffers used by @sc{Ratfor} for constructing messages about
the commands it is expanding are controlled by @samp{-ycf} and @samp{-ycg}.

@node -ycg, -yd, -ycf, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ycg}:  Size of another Ratfor buffer, in bytes

@findex -ycg

The sizes of buffers used by @sc{Ratfor} for constructing messages about
the commands it is expanding are controlled by @samp{-ycf} and @samp{-ycg}.

@node -yd, -ydt, -ycg, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yd}:  Increment for expanding the dots table

@findex -yd

The ``dots'' table is used for @sc{Fortran} to hold information relating
to ``dot'' operators such as @samp{.NE.}.  In @sc{Fortran--90},
additional such operators can be added by the program, so the table can
grow dynamically.  The @samp{-yd} option controls how many additional
entries are made available each time the table size needs to be
reallocated.

@node -ydt, -ydx, -yd, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ydt}:  Maximum number of deferred macro tokens

@findex -ydt

Deferred @FWEB{} macros are ones defined in the code part rather in
the definition part.  (Their use is normally prohibited; see @ref{-TD}.)
@samp{-ydt} controls how many bytes are set aside for the storage of
these replacement text of those macros.  See also @ref{-ydx}.

@node -ydx, -yid, -ydt, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ydx}:  Maximum number of deferred macro texts

@findex -ydx

@samp{-ydx} controls how many deferred macros are permitted.  See also
@ref{-ydt}. 

@node -yid, -yif, -ydx, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yid}:  Maximum depth of file inclusion

@findex -yid

Files included by @samp{@@i} can themselves contain @samp{@@i} commands,
to a nesting level controlled by @samp{-yid}.

@node -yif, -ykt, -yid, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yif}:  Maximum number of unique include-file names

@findex -yif

The number of unique file names appearing in @samp{@@i} commands is
controlled by @samp{-yif}.

@node -ykt, -ykw, -yif, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ykt}:  Stack size for @FTANGLE{}

@findex -ykt

@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 @samp{-ykt}.

@node -ykw, -yll, -ykt, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ykw}:  Stack size for @FWEAVE{}

@findex -ykw

@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 @samp{-ykw}.

@node -yll, -yln, -ykw, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yll}:  Line length for @FWEAVE{}'s output, in bytes

@findex -yll

@samp{-yll} controls the length of each line in the @code{.tex} file
output by @FWEAVE{}.

@node -yln, -ylb, -yll, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yln}:  Maximum length of module names or strings, in bytes

@findex -yln

When each module name or string is parsed, it is stored temporarily in a
buffer whose length is controlled by @samp{-yln}.

@node -ylb, -ylx, -yln, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ylb}:  Maximum number of nested loops in @sc{Ratfor}

@findex -ylb

In @sc{Ratfor}, various loops such as @samp{while} are translated into
their @sc{Fortran} equivalents.  @samp{-ylb} controls the maximum
nesting level of such expandable constructions.

@node -ylx, -ym, -ylb, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ylx}:  Maximum length of expressions that can be expanded with the post-increment operators of @sc{Fortran} or @sc{Ratfor}

@findex -ylx

@sc{Fortran} and @sc{Ratfor} can expand expressions such as @samp{x(i) +=
dx} into their @sc{Fortran} counterparts such as @samp{x(i) = x(i) + dx}.  
It does so in a very straightforward way, by copying the expression to
the left of the equals sign.  @samp{-ylx} controls the maximum size of
that expression.

@node -ym, -yma, -ylx, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ym}:  Maximum number of sections

@findex -ym

@samp{-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.)

@node -yma, -ymb, -ym, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yma}:  Maximum number of arguments to @FWEB{} macros

@findex -yma

The maximum number of arguments to @FWEB{} macros (defined by
@samp{@@m}) is limited by @samp{-yma}.

@node -ymb, -yn, -yma, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ymb}:  Size of the buffer for expanding @FWEB{} macros

@findex -ymb

The expansion of each @FWEB{} macro is done in a buffer whose size is
controlled by @samp{-ymb}.  (In some situations, particularly in
@sc{Ratfor}, more than one such buffer can be open at once.)

@node -yn, -ynf, -ymb, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yn}:  Maximum number of identifiers and module names

@findex -yn

A structure is associated with each unique identifier and module name.
The maximum number of such structures is controlled by @samp{-yn}.  See
also @ref{-yb}.

@node -ynf, -yop, -yn, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ynf}:  Maximum number of open output files

@findex -ynf

In addition to @FTANGLE{}'s usual output file---e.g.,
@code{test.c}---additional files may be opened by means of the
@samp{@@O} (@pxref{ATO_}) or @samp{@@o} (@pxref{ATo}) commands.
Depending on the situation, some of these files may remain open
simultaneously.  The maximum number of such files is controlled by @samp{-ynf}.

@node -yop, -yr, -ynf, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yop}:  Maximum number of entries in the table for operator overloading. 

@findex -yop

In @FWEAVE{}, the appearance of an operator can be changed
(@dfn{overloaded}) by means of the @samp{@@v} command (@pxref{ATv}).  Each
such operator is entered into a table, the maximum size of which is
controlled by @samp{-yop}.  

@node -yr, -ys, -yop, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yr}:  Maximum number of cross-references

@findex -yr

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 @samp{-yr}.

@node -ys, -ysb, -yr, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ys}:  Maximum number of scraps

@findex -ys

The maximum number of scraps is controlled by @samp{-ys}.  For a
discussion of scraps, see @ref{-1}.

@node -ysb, -ytt, -ys, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ysb}:  Size of style-file input-line buffer

@findex -ysb

The maximum length of each input line of the style file (@code{fweb.sty}
by default) is controlled by @samp{-ysb}.

@node -ytt, -ytw, -ysb, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ytt}:  Maximum number of tokens that @FTANGLE{} can process

@findex -ytt

A @dfn{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 @samp{-ytt}.

@node -ytw, -yx, -ytt, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-ytw}:  Maximum tokens in the current section being processed by @FWEAVE{}.

@findex -ytw

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

@node -yx, -yxb, -ytw, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yx}:  Maximum number of texts

@findex -yx

For @FTANGLE{}, a @dfn{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 @samp{-yx}.

For @FWEAVE{}, a @dfn{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.

@node -yxb, , -yx, Memory allocation
@comment  node-name,  next,  previous,  up

@subsubsection @samp{-yxb}:  Size of line buffer for @TeX{} and verbatim output

@findex -yxb

This option is like @samp{-ycb} (@pxref{-ycb}), but controls the size of
the output line for the @TeX{} (@samp{@@Lx}) and verbatim (@samp{@@Lv})
languages. 

@node Style,,Memory allocation,Customization
@comment  node-name,  next,  previous,  up

@section The Style file

@cindex Style file
@cindex File, style
@findex fweb.sty
A @dfn{style file} (default name @file{fweb.sty}) may reside in the
user's current directory (or the directory specified by the environment
variable @code{FWEB_STYLE_DIR}).  The default name can be changed by the
command-line option @samp{-z} (@pxref{-z}).

The style file is processed after all command-line options have been
processed, except that the command-line option @samp{-p} (@pxref{-p})
gets special treatment.  Note that that option buffers up style-file
entries (i.e., one may use more than one @samp{-p} option).  @samp{-p}
options placed in @file{.fweb} are treated as residing in a temporary
file that is read just @emph{before} the local style file; thus, those behave
as `global' style-file entries that will be overridden by a matching
entry in the local style file.  @samp{-p} options on the command line
will be processed @emph{after} the local style file, thus override
corresponding options in either @file{.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 @file{.fweb} by
means of the @samp{-p} option.  To override a setting for a single run,
use a @samp{-p} option on the command line.

Style-file entries have the form

@example
        @var{keyword} @i{[}=@i{]} @var{value}
@end example
@noindent
The equals sign is always optional.  The @samp{value} is usually a
double-quoted string, but may sometimes be an integer or a single-quoted
character.  For example,

@example
        LaTeX.class.options = "twoside"
        LaTeX.package "indentfirst,multicol"
        mark_defined.fcn_name 0
        line_char.N 'C'
        color.error = "red"
        Color.red = "\e[01;31m"
@end example
@noindent
The syntax is completely free-form.  Periods within keywords are
precisely equivalent to underscores, but are useful heuristically for
associating a structure-like hierarchy to some of the commands.
Non-printable characters in strings can be specified as octal constants
(e.g., @samp{\033}), hexadecimal constants (e.g., @samp{\x1B}), or one
of the ANSI escape sequences @samp{\a}, @samp{\b}, @samp{\f}, @samp{\n},
@samp{\r}, @samp{\t}, and @samp{\v}.  The non-ANSI escape sequence
@samp{\e} (escape) is also supported; that is particularly useful for
color processing (@pxref{Color}).

Various of the style-file parameters take a language subscript.  Those
are 

@quotation
@table @code
@item C
C
@item Cpp
C++
@item N
@sc{Fortran}-77
@item N90
@sc{Fortran}-90
@item R
@sc{RatFor}-77
@item R90
@sc{RatFor}-90
@item V
Verbatim
@item X
@TeX{}

@end table
@end quotation
@noindent
Thus, @code{line_char.N} is the comment character for @FTANGLE{}'s
@code{line} commands (@pxref{line_char}), for @sc{Fortran}-77 code.

Unfortunately, the descriptions of the parameters aren't all completed
yet.  To query the default values, say @samp{ftangle -Z} (see @ref{-Z_}).

@menu
* 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.
@end menu

@node Index params,Module params,Style,Style
@comment  node-name,  next,  previous,  up

@subsection  Customizing @FWEAVE{}'s index

In the following, @samp{???} denotes the name of various subparameters.

@menu
* delim_0: S_delim.             Insert after identifier in index entry.
* delim_n: S_delim.             Insert between section numbers in index entry.

* encap.infix: S_encap.         Start the section number.
* encap.prefix: S_encap.        @TeX{} macro to begin a section number.
* encap.suffix: S_encap.        Ends the section number.

* group_skip::

* index.collate: S_index.       Collating sequence for the Index.
* index.postamble: S_index.     @TeX{} material to end the Index.
* index.preamble: S_index.      @TeX{} material to begin the Index.
* index.tex: S_index.           Name of file holding the Index.

* item_0::                      @TeX{} command to begin an index entry.

* language.prefix: S_language.  Begin a language entry in the Index.
* language.suffix: S_language.  End a language entry in the Index.

* lethead.prefix: S_lethead.    Begin a letter group.
* lethead.suffix: S_lethead.    End a letter group.
* lethead.flag: S_lethead.      Control beginning of letter group.

* name: S_index.                Name of index.

* underline.prefix: S_underline. Begin an underlined index entry.
* underline.suffix: S_underline. End an underlined index entry.
@end menu

@node S_index, S_delim, Index params, Index params
@comment  node-name,  next,  previous,  up

@subsubsection @code{index.@i{???}}

@findex \INDEX
@cindex Index, name of
@vindex index.name
@code{index.name} is the name of the index section.  This string is used
in @code{\Wbegin} to initialize the @TeX{} macro @code{\INDEX}.  The
index section is recognized by matching, for a starred section, the
actual section name against the contents of @code{\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 @samp{\INDEX}, as in

@example
@@* \INDEX.
@end example

@vindex index.tex
@code{index.tex} is the name of the file into which the Index is
written.  The character @samp{#} is translated into the root name of the web
file, as for example @samp{#.ndx}.

@vindex index.preamble
@code{index.preamble} are @TeX{} commands that begin the Index.

@vindex index.postamble
@code{index.postamble} are @TeX{} commands that end the Index.

@vindex index.collate
@code{index.collate} specifies the collating sequence for the Index.

@node S_delim, S_encap, S_index, Index params
@comment  node-name,  next,  previous,  up

@subsubsection @code{delim_@i{?}}

@vindex delim_0
@code{delim_0} is the string to insert after the identifier in an index
entry.

@vindex delim_n
@code{delim_n} is the string to insert between two section numbers in an
index entry.

@node S_encap, group_skip, S_delim, Index params
@comment  node-name,  next,  previous,  up

@node group_skip, item_0, S_encap, Index params
@comment  node-name,  next,  previous,  up

@subsubsection @code{group_skip}

@vindex group_skip
@code{group_skip} is a string of @TeX{} commands to insert between
letter groups.

@node item_0, S_language, group_skip, Index params
@comment  node-name,  next,  previous,  up

@subsubsection @code{item_0}

@vindex item_0
@code{item_0} is the @TeX{} command to begin an index entry.

@node S_language, S_lethead, item_0, Index params
@comment  node-name,  next,  previous,  up

@subsubsection @code{language.@i{???}}

@vindex language.prefix
@vindex language.suffix
@code{language.prefix} begins a language entry.; @code{language.suffix}
ends one.

@node S_lethead, S_underline, S_language, Index params
@comment  node-name,  next,  previous,  up

@subsubsection @code{lethead.@i{???}}

@vindex lethead.prefix
@vindex lethead.suffix
@vindex lethead.flag
@code{lethead.prefix} begins a letter group; @code{lethead.suffix} ends
one.  The flag @code{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.


@node S_underline, , S_lethead, Index params
@comment  node-name,  next,  previous,  up

@subsubsection @code{underline.@i{???}}

@vindex underline.prefix
@code{underline.prefix} is the @TeX{} command to begin an underlined
index entry.

@vindex underline.suffix
@code{underline.suffix} is the @TeX{} command to end an underlined index
entry.


@node Module params,Contents params,Index params,Style
@comment  node-name,  next,  previous,  up

@subsection Customizing the module list

@menu
* modules.info: S_modules.
* modules.postamble: S_modules. @TeX{} commands to end module list.
* modules.preamble: S_modules.  @TeX{} commands to begin module list.
* modules.tex: S_modules.       Name of file containing list of modules.
@end menu

@node S_modules, , Module params, Module params
@comment  node-name,  next,  previous,  up

@vindex modules.tex
@code{modules.tex} is the name of the file into which the module names
are written.

@vindex modules.preamble
@code{modules.preamble} is a string of @TeX{} commands to begin the list
of modules.

@vindex modules.postamble
@code{modules.postamble} is a string of @TeX{} commands to end the list
of modules.

@vindex modules.info
@code{modules.info} is the name of the @TeX{} macro that formats the
command line and related information.

@node Contents params,Subscript params,Module params,Style
@comment  node-name,  next,  previous,  up

@subsection Customizing the Table of Contents

@menu
* contents.postamble: S_contents. @TeX{} commands to end Table of Contents.
* contents.preamble: S_contents.  @TeX{} commands to begin Table of Contents.
* contents.tex: S_contents.       Name of contents file.
@end menu

@node S_contents, , Contents params, Contents params
@comment  node-name,  next,  previous,  up

@vindex contents.tex
@code{contents.tex} is the name of the file into which the Table of
Contents is written.

@vindex contents.preamble
@code{contents.preamble} is the @TeX{} string that begins printing the
Table of Contents.

@vindex contents.postamble
@code{contents.postamble} is the @TeX{} string that ends the Table of
Contents.

@node Subscript params,Fwebmac params,Contents params,Style
@comment  node-name,  next,  previous,  up

@subsection Customizing cross-reference subscripts

@cindex Bullet
@cindex Subscript, bullet
When @FWEAVE{} pretty-prints code, it can attach cross-reference
subscripts to various kinds of identifiers such as function or macro
names.  [A bullet
@tex
($\bullet$)
@end tex
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 @samp{@@[} (@pxref{AT[}).  This is usually done
implicitly; for example, the commands @samp{@@a}, @samp{@@d}, and
@samp{@@m} issue an implicit @samp{@@[}.  (See the discussion of
@samp{@@a} in @ref{ATa}.)  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 @samp{\W@@IN} in @file{fwebmac.web}.]
@cindex Bullet subscript
The following flags select which identifiers are so subscripted.

To see the default values of these parameters, say @samp{ftangle
-Zmark_defined}.  To turn off the subscripting operations completely, use the
@samp{-f} option (@pxref{-f}).

@menu
* mark_defined.generic_name: S_mark_defined.
* mark_defined.fcn_name: S_mark_defined.
* mark_defined.WEB_macro: S_mark_defined.
* mark_defined.outer_macro: S_mark_defined.
* mark_defined.exp_type: S_mark_defined.
* mark_defined.typedef_name: S_mark_defined.
@end menu

@node S_mark_defined, , Subscript params, Subscript params
@comment  node-name,  next,  previous,  up

@vindex mark_defined.typedef_name
@vindex mark_defined.exp_type
@vindex mark_defined.outer_macro
@vindex mark_defined.WEB_macro
@vindex mark_defined.fcn_name
@vindex mark_defined.generic_name
(Discussion to be completed.)

@node Fwebmac params,Completion params,Subscript params,Style
@comment  node-name,  next,  previous,  up

@subsection Customizing the behavior of @file{fwebmac.sty} macros

@findex fwebmac.web
To some extent, the behavior of @FWEB{}'s macro package
@file{fwebmac.sty} can be changed by means of the following parameters.
(Please try not to actually edit @file{fwebmac.sty} itself; it is
produced automatically from @file{fwebmac.web}.  And please don't edit
that file either!)

@menu
* doc.preamble: S_LaTeX.        Preamble for entire document.
* doc.postamble: S_LaTeX.       Postamble for entire document.

* format_IDENTIFIER: S_format.  Macro name for typesetting upper-case identifiers.
* format.reserved: S_format.    Macro for reserved words.
* format.short_identifier: S_format. Macro for single-character identifiers.
* format_OUTER_MACRO: S_format. Macro for upper-case @samp{@@d} identifiers.
* format.outer_macro: S_format. Macro for lower-case @samp{@@d} identifiers.
* format_WEB_MACRO: S_format.   Macro for upper-case @samp{@@m} identifiers.
* format.WEB_macro: S_format.   Macro for lower-case @samp{@@m} identifiers.
* format.intrinsic: S_format.   Macro for intrinsic library functions.
* format_KEYWORD: S_format.     Macro for upper-case keywords.
* format.keyword: S_format.     Macro for lower-case keywords.
* format.typewriter: S_format.  Macro for strings.
* format.wildcard: S_format.    Macro for user-defined index entries.

* indent.TeX: S_indent.         Paragraph indentation for @TeX{} part.
* indent.code: S_indent.        Paragraph indentation for code part.

* LaTeX.class: S_LaTeX.         Specify the document class.
* LaTeX.class.options: S_LaTeX. Specify options for document class.
* LaTeX.package: S_LaTeX.         Specify user package(s)
* LATeX.package.options: S_LaTeX. Specify options for user package(s).
@end menu

@node  S_format, S_indent, Fwebmac params, Fwebmac params
@comment  node-name,  next,  previous,  up

@subsubsection @code{format.@i{???}}

The @code{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 @samp{ftangle -Zformat.}.  For example,
the default value for @code{format.typewriter} is @code{"\\."}.

The macro names defined by the @code{format} fields are @emph{not}
defined in @file{fwebmac.sty}.  They are @emph{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 @code{\.} for their own purposes.

Thus, @FWEAVE{} normally writes out the macro @code{\.} to typeset a
string.  Suppose, however, that some user package uses @code{\.} for
something else.  (One might realize this when @sc{LaTeX} crashes
when it encounteres a @code{\.} that was written automatically by
@FWEAVE{}.)  To fix this problem, put into @file{fweb.sty} the lines

@example
format_KEYWORD = "\\WTT"
format_keyword = "\\WTT"
format_typewriter = "\\WTT"
@end example
@noindent
Here @code{\WTT} can be any name not already in use; @emph{you need not (and
should not)} give a definition for @code{\WTT}.

Macros like @code{\.} or @code{\WTT} are given their values during the
execution of the @code{\Wbegin} macro that begins the output from
@FWEAVE{}.  The style-file values are written as arguments to that
macro, and essentially a command like @code{\let\.\Wtypewriter} is
executed, where the internal macro @code{\Wtypewriter} is defined in
@file{fwebmac.sty}.  If you want to change the way @FWEB{} typesets a
particular kind of identifier, you must redefine the @emph{internal}
macro name, not the one used in the @code{format} parameters.

Here are the internal macros used by @file{fwebmac.sty} to typeset the
various kinds of identifiers.  The associated style-file parameters are
shown in parentheses.  

@vindex format.id
@vindex format.ID
@vindex format.short_id
@vindex format.outer_macro
@vindex format.WEB_macro
@vindex format.reserved
@vindex format.RESERVED
@vindex format.intrinsic
@vindex format.keyword
@vindex format.KEYWORD
@vindex format.typewriter

@quotation
@ftable @code

@item \Wid 
ordinary identifiers (@code{format.id})

@item \WID 
completely upper-case ordinary identifiers (@code{format.ID})

@item \Wshort 
single-character ordinary identifiers (@code{format.short_id})

@item \WidD 
outer macros (@code{format.outer_macro})

@item \WIDD 
completely upper-case outer macros (@code{format.outer_macro})

@item \WidM 
FWEB macros (@code{format.WEB_macro})

@item \WIDM 
completely upper-case FWEB macros (@code{format.WEB_macro})

@item \Wreserved 
reserved words (@code{format.reserved})

@item \WRESERVED 
completely upper-case reserved words (@code{format.RESERVED})

@item \Wintrinsic 
library/intrinsic function names (@code{format.intrinsic})

@item \Wkeyword 
certain Fortran keywords (@code{format.keyword})

@item \WKEYWORD 
completely upper-case keywords (@code{format.KEYWORD})

@item \Wtypewriter 
character strings (@code{format.typewriter})

@end ftable
@end quotation


@node S_indent, S_LaTeX, S_format, Fwebmac params
@comment  node-name,  next,  previous,  up

@subsubsection @code{indent.@i{???}}

@vindex indent.TeX
@code{indent.TeX} specifies paragraph indentation for the @TeX{} part.

@vindex indent.code
@code{indent.code} specifies similar indentation for the code part.

@node S_LaTeX, , S_indent, Fwebmac params
@comment  node-name,  next,  previous,  up

@subsubsection @code{LaTeX.@i{???}}

@vindex LaTeX.class
For La@TeX{}2e, the default document class can be overridden by
@code{LaTeX.class}.  The default class is @code{article}, and @FWEB{}
has not been tested with other document classes, except minimally with
@code{revtex} (@pxref{REVTeX}).

@vindex LaTeX.class.options
Options to the document class can be specified by
@code{LaTeX.class.options}.

User packages can be given by @code{LaTeX.package}.

@vindex LaTeX.package
@vindex LaTeX.package.options
Options to user packages can be specified by
@code{LaTeX.package.options}.  There may be just one
@code{LaTeX.package} command and just one @code{LaTeX.package.options}
command.  If it is necessary to issue multiple such commands, then put
them into @code{doc.preamble}.  See the discussion in @ref{Document
class}. 

@vindex LaTeX.style
@vindex LaTeX.options
When running under La@TeX{} prior to La@TeX{}2e (or with REVTeX; see
@ref{REVTeX}), the document is 
(effectively) begun by the command
@code{\documentstyle[options]@{style@}}.  The options field can be
specified by @code{LaTeX.options}; the style field by
@code{LaTeX.style}.


@node Control-code mappings, Color, Completion params, Style
@comment  node-name,  next,  previous,  up

@subsection Remapping control codes

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

@node Color, Miscellaneous params, Control-code mappings, Style
@comment  node-name,  next,  previous,  up

@subsection Color output

@cindex Color
In the design of @FWEB{}, provision has been made for writing various
messages to the terminal in color---e.g., serious error messages might
appear in red.  This feature was motivated by the color @code{ls} of Linux.
It is installed automatically if the @code{termcap} library is present.

@cindex Message types
@cindex Color, and message types
Messages output from @FWEB{} are ranked according to an internal message-type
table; each type can be associated with a color that can be changed
in the style file.  Presently, the message types (hopefully
self-explanatory) are
@cindex Message types
@vindex color.ordinary
@vindex color.program_name
@vindex color.mod_name
@vindex color.info
@vindex color.warning
@vindex color.error
@vindex color.fatal
@vindex color.mod_num
@vindex color.line_num
@vindex color.in_file
@vindex color.include_file
@vindex color.out_file
@vindex color.timing

@quotation
@example
ordinary
program_name
mod_name
info
warning
error
fatal
mod_num
line_num
in_file
include_file
out_file
timing
@end example
@end quotation

@noindent
The associated style-file parameters are the above names prefaced by
@samp{color.}---e.g., @code{color.warning}.  Each of those has a default
value, such as @code{color.error = "red"}.  Those defaults can be
displayed by saying @samp{ftangle -Zcolor}.

What the color actually means in practice depends on the @dfn{color
mode}, set by the @samp{-C} option (@pxref{-C_}).  That selects one of
several primitive palettes, as follows:
@findex -C

@quotation
@table @kbd
@item 0
@strong{No color}; ordinary black-and-white output.  This is the default (and the
mode used when the @code{termcap} library is not present).

@item 1
@cindex Color, ANSI
@cindex Color mode, ANSI
@strong{ANSI color}.  With a color terminal that supports ANSI color escape
sequences, one has available the following colors:  @code{"black"},
@code{"red"}, @code{"green"}, @code{"yellow"}, @code{"blue"},
@code{"magenta"}, @code{"cyan"}, @code{"white"}, and @code{"default"}.
These are displayed with bold attribute (that is, bright, not dim).
@samp{"default"} stands for the usual black on white background, or vice
versa.

@item 2
@cindex Color mode, bilevel
@strong{Bilevel}.  This is for terminals that don't support true color,
but do support a double-bright mode and reverse video.  Colors are
mapped onto various combinations of those two display attributes,
according to an internally defined scheme.  For example, @code{"red"} is
mapped onto the pair of escape sequences @samp{md}, @samp{mr}
(double-bright mode in reverse video).

@item 3
@cindex Color mode, trilevel
@strong{Trilevel}.  As above, but adds underlining capability.

@item 4
@cindex Color mode, user-defined
@strong{User-defined colors}.  This implements a minimal set of defaults.  It is
intended that the user add definitions in the style file to override
those defaults. 

@end table
@end quotation

@findex termcap
@cindex Escape sequences, ANSI
@vindex Color.black
@vindex Color.red
@vindex Color.green
@vindex Color.yellow
@vindex Color.blue
@vindex Color.magenta
@vindex Color.cyan
@vindex Color.white
@vindex Color.default

The mechanism is intended to work with systems that support the
@code{termcap} library.  The terminal is controlled by writing
appropriate escape sequences to it.  The style-file parameters that
store the escape sequences are the color name preceded by @samp{Color.}
(note the upper case @samp{C})---e.g., @samp{Color.red}.  For cases like
reverse video (standard termcap abbreviation @samp{mr}), the escape
sequences are determined by querying the termcap database (usually
@file{/etc/termcap}) through the @code{termcap} library functions.  For
ANSI color (color mode = 1), ANSI escape sequences are hard-coded into
@FWEB{}.  One can see the escape sequences @FWEB{} assigns to colors by
saying @samp{ftangle -ZColor}.

For any non-zero color mode, one can override @FWEB{}'s default choices
for color mappings and escape sequences by redefining one or more of the
@code{Color} parameters in the style file.  The escape sequences can
either be specified in raw form---e.g., for color mode = 1, a
default is @code{Color.red = "\e[01;31m"}---or in the form of a sequence
of two-character abbreviations that are defined in the termcap
documentation---e.g., for modes 2 and 3, the default is @code{Color.red
= "mdmr"}.  (When one displays that with the @samp{-Z} option, @FWEB{}
will display the actual escape sequences that it determines from the termcap
database, not the abbreviations.  For both input and output, note that
one may use the non-ANSI escape sequence @samp{\e} to represent the
escape character @samp{\033}.)

When one says @samp{-ZColor}, for color modes 1--3 all of the
parameters are listed as modified, even if the user redefines none.
That occurs because the defaults are overwritten internally when the
color mode is set.

@findex termcap0
@FWEB{}'s configuration script attempts to determine whether the termcap
library is present; if not, they link in dummy termcap routines
(@file{termcap0.web}).  To override this behavior, change the
appropriate lines in @file{defaults.mk}, produced by the command
@code{./configure}. 

Color message output is not fully debugged (it's a frill, after all), so
some messages that should reasonably be colored may not be so in the
present release.  

@node Miscellaneous params,,Color,Style

@comment  node-name,  next,  previous,  up

@subsection Miscellaneous style-file parameters

There are a variety of miscellaneous parameters.

@menu
For @FTANGLE{}:

* ASCII_fcn::                   Routine for converting strings to ASCII.
* cchar::                       Continuation character for Fortran.
* cdir_start::                  @samp{@?} translates to this.
* line_char::                   Comment char. for @FTANGLE{}'s @code{line} cmds.
* line_length: S_line_length.

* paren.len: -n).               Length of one parenthesized index for @samp{-n)}.
* paren.levels: -n).            Number of nested parentheses for @samp{-n)}.
* paren.num: -n).               Number of permitted indices for @samp{-n)}.

* meta.top: S_meta_t.           Material to precede tangled meta-comment. 
* meta.prefix: S_meta_t.        Begins each line of meta-comment.
* meta.bottom: S_meta_t.        Material that follows the meta-comment.

* meta.top.hdr: S_meta_t.       Like meta.top, but for info at start of file.
* meta.prefix.hdr: S_meta_t.    As above.
* meta.bottom.hdr: S_meta_t.    As above.

* outer.def: S_outer.           @FTANGLE{} converts @samp{@@d} to this.
* outer.undef: S_outer.         @FTANGLE{} converts @samp{@@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: S_limbo.         Default material to begin the limbo section.
* limbo.end: S_limbo.           Default material to end the limbo section.

* meta.code.begin: S_meta_w.
* meta.code.end: S_meta_w.

* meta.TeX.begin: S_meta_w.     @TeX{} material to begin @FWEAVE{}'s 
                                                output of a meta-comment.
* meta.TeX.end: S_meta_w.       As above, but end the meta-comment.

* preamble.named: S_preamble.   @TeX{} material to begin named section.
* preamble.unnamed: S_preamble. @TeX{} material to begin unnamed section. 

For both processors:

* dot_constant.begin: S_dot_constant.   Beginning character for dot constant.
* dot_constant.end: S_dot_constant.     Ending character for dot constant.

* null_file::                   Name of the null file.
@end menu

@node ASCII_fcn, cchar, Miscellaneous params, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{ASCII_Fcn}

@vindex ASCII_Fcn
@xref{ATdquote}.

@node cchar, cdir_start, ASCII_fcn, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{cchar}

@vindex cchar
Continuation character for @sc{Fortran} code output.

@node cdir_start, line_char, cchar, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{cdir_start}

@vindex cdir_start
This parameter has the form @code{cdir_start.@i{l}}, where @i{l} is one of
@samp{C}, @samp{Cpp}, @samp{N}, @samp{N90}, @samp{R}, @samp{R90},
@samp{X}, or @samp{V}.  The contents of this parameter is written
immediately after the @samp{@@?} that begins a compiler directive.

@node line_char, S_line_length, cdir_start, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{line_char.@i{l}} (@FTANGLE{})

@vindex line_char
By default, @FTANGLE{} outputs comments indicating line numbers in the
@code{web} file from which the tangled output comes.  (This information
can be used by debuggers, especially those for C and C++, to correlate
error messages to the @code{web} source.)  The @code{line_char}
parameter sets the comment character that begins the line comment.

@node S_line_length, S_meta_t, line_char, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{line_length.@i{l}} (@FTANGLE{})

@vindex line_length
This parameter is used by the @sc{Fortran}-like languages to control the
length of the output line in the @file{.f} file produced by
@FTANGLE{}.  For @sc{Fortran}-77, its default value is the venerable
72.  For @sc{Fortran}-90, its default is 73.  Using that value makes it
possible to generate code that is compatible with both fixed- and
free-form format (by continuing lines with an trailing ampersand in
column 73 and another ampersand in column 6 of the next line).

@node S_meta_t, S_outer, S_line_length, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{meta.@i{???.?}}, @code{meta.@i{???}.hdr.@i{?}} (@FTANGLE{})

These parameters customize the treatment of meta-comments.
Fundamentally, meta-comments consist of material enclosed by
@samp{@@(...@@)}.  The header information usually written at the top of
the file output by @FTANGLE{} (@pxref{-Tv}) is also treated as a
meta-comment.  For that header material, a separate set of parameters is
provided, such as @code{meta.top.hdr}.

@vindex meta.top
@vindex meta.top.hdr
@code{meta.top.@var{l}} specifies text that precedes material enclosed by
@samp{@@(...@@)}.  Here @var{l} is one of the standard language subscripts
(@pxref{Style}) such as @code{N90}.

@vindex meta.prefix
@vindex meta.prefix.hdr
@code{meta.prefix.@var{l}} begins each line of the meta-comment.

@vindex meta.bottom
@vindex meta.bottom.hdr
@code{meta.bottom.@var{l}} specifies text that follows the meta-comment.

@node S_outer, protect, S_meta_t, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{outer.@i{???}}

@vindex outer.def
@vindex outer.under
@FTANGLE{} converts @samp{@@d} (@pxref{ATd}) to @code{outer.def}, and
@samp{@@u} (@pxref{ATu}) to @code{outer.undef}.

@node protect, suffix, S_outer, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{protect.?}

@vindex protect
The strings @code{protect.@var{l}} specify the protection character(s) to end
a continued line.

@node suffix, macros, protect, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{suffix.?}

@vindex suffix
The extension for the files output by @FTANGLE{} is specified by
@code{suffix.@var{l}}.


@node macros, S_limbo, suffix, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{macros}

@vindex macros
The default name of the macro package to be read in.  [This is usually
@file{fwebmac.sty} (@pxref{fwebmac.sty}), but can be overridden by the
command-line option @samp{-w}; see @ref{-w}.]

@node S_limbo, S_meta_w, macros, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{limbo.begin}, @code{limbo.end}

@vindex limbo.begin
@samp{limbo.begin} is @TeX{} material to be printed at the beginning of
the limbo section, just before the text from @samp{@@l} commands.  @xref{ATl}.
(This command was previous called just @samp{limbo}, and that still
works.)

@vindex limbo.end
Similarly, @samp{limbo.end} is printed at the end of the limbo section.

Thus, the beginning of the file output by @FWEAVE{} looks like this:

@example
\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>
@end example

The @samp{limbo.end} command is useful for printing the entire document
in two-column format.  For more discussion, see @ref{LIndex}.

@node S_meta_w, S_preamble, S_limbo, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{meta.@i{???}} (@FWEAVE{})

@vindex meta
(To be finished.)

@node S_preamble, S_dot_constant, S_meta_w, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{preamble.@i{???}}

@vindex preamble.named
@vindex preamble.unnamed
Additional @TeX{} material can be inserted at the beginning of a named
section with @code{preamble.named} and at the beginning of an unnamed
one with @code{preamble.unnamed}.

@node S_dot_constant, null_file, S_preamble, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{dot_constant.@i{???.?}}

@vindex dot_constant.begin
@vindex dot_constant.end
In @sc{Fortran}, `dot' constants such as @code{.LT.} are begun and ended by
periods.  In special circumstances, the beginning and ending characters
may be modified by @code{dot_constant.begin.@var{l}} and
@code{dot_constant.end.@var{l}}.

@node null_file, , S_dot_constant, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{null_file}

@vindex null_file
The name of the null file or device.  For more discussion, see
@ref{Change files}. 

@node Completion params,Control-code mappings,Fwebmac params,Style
@comment  node-name,  next,  previous,  up

@subsection  Automatic file name completion

@menu
* Ext.web: S_Ext.        Extensions for the web file.
* Ext.ch: S_Ext.     Extensions for the change file.
* Ext.hweb: S_Ext.       Extensions for include files.
* Ext.hch: S_Ext.    Extensions for change files associated with
                                include files. 
@end menu

@node S_Ext, , Completion params, Completion params
@comment  node-name,  next,  previous,  up

@vindex ext.web
@vindex ext.ch
@vindex ext.hweb
@vindex ext.hch

For more information, see @ref{-e}.

@node Hints, New features, Customization, Top
@comment  node-name,  next,  previous,  up

@chapter USAGE TIPS and SUGGESTIONS

In this section are collected various tips and suggestions to help one make
full use of @FWEB{}.  Additional hints broken down by each supported
source language can be found in @ref{Languages}.

@menu
* Converting::          Converting an existing code to @FWEB{}.
* Tips::                Usage tips and suggestions.
* Science::             Useful features for scientific programming.
@end menu

@node Converting, Tips, Hints, Hints
@comment  node-name,  next,  previous,  up

@section Converting an existing code to @FWEB{}

@cindex Converting an existing code to @FWEB{}
@cindex Code, converting to @FWEB{}
To convert an existing code to @FWEB{}, one should do the
following. (The following simple procedure assumes that one puts all the
subroutines into the unnamed module. However, other more elaborate schemes
are possible.)

@enumerate

@item
Place invisible commentary
about the author, version, etc. at the beginning of the source file by
bracketing it with @samp{@@z...@@x}.  The @samp{@@z} must be the first two
characters of the file.

@item
Next, set the language by including a command such as @samp{@@n} or
@samp{@@c++}. 

@item
Place an @samp{@@a} command (switch into unnamed code) before each
program unit (e.g., main @b{program}, @b{subroutine}, or @b{function}).

@item
Before each @samp{@@a}, place an @samp{@@*} or @ASP{} command,
followed by @TeX{} documentation about that particular section of code.

@item
If you have program units longer than about twelve lines, either
make them function calls, if you can afford the overhead and can impart
sufficient information via the function name, or break them up into shorter
fragments by using named modules. Insert the command @samp{@@<Name of
module@@>} in place of the fragment you're replacing, then put that
fragment somewhere else, prefaced by 
@ASP{} and @samp{@@<Name of module@@>=}.

@item
Make sure your comments are valid @TeX{}. (One can't have things
like raw underscores or dollar signs in comments, since those cause @TeX{}
to take special actions.)

@item
Beautify and clarify your documentation by using code mode
(enclosing stuff between vertical bars) liberally within your @TeX{}. 

@item
After you've seen the woven output, you may need to go back and 
format a few identifiers or section names so that @FWEAVE{} understands them
properly, or you may need to insert some pseudo-semicolons (@samp{@@;}),
pseudo-expressions (@samp{@@e}), or pseudo-colons (@samp{@@:})
(@pxref{Pseudo-operators}). 
 
@item
Consider using @FWEB{}'s built-in macro preprocessor (@pxref{Macros})
to make your code more readable---for example, replace raw numerical
constants by symbolic names. 

@item
Scientific programmers may benefit from built-in macro-like functions
like @code{$PI}; see @ref{Built-in functions}.

@item
If you are a @sc{Fortran} user,  for ultimate readability
consider converting to @sc{Ratfor}. The initial annoyance is getting rid of
column-6 continuations. With the aid of a good editor, this can be done
simply. For example, in @code{emacs} one can replace the regular expression
[carriage return, five spaces, something not equal to space, tab, or 0]
with [backslash, carriage return, six spaces]:

@example
M-x replace-regexp RET
C-q C-j \.@{\ \ \ \ \ @}[\^\.\ tab 0]RET
\\\\ C-q C-j \.@{\ \ \ \ \ \ @}RET
@end example

@noindent 
Get rid of the keywords such as @b{then} or @b{end if} in favor
of braces. Change singly-quoted character strings to doubly-quoted
ones.  The @samp{-nC} option (@pxref{-nC}) may be helpful.

@end enumerate

@node Tips, Science, Converting, Hints
@comment  node-name,  next,  previous,  up

@cindex Suggestions
@cindex Programming tips

@section Programming tips and other suggestions

@enumerate

@item
Learn how to use the GNU @code{info} browser to access the on-line
documentation.

@item
Read the list of new features and changes for the last several
releases.  @xref{New features}.

@item
Periodically check @code{ftp.pppl.gov:/pub/fweb/READ_ME} for bug
reports and other news.  Make bug reports!  @xref{Support}.

@item
If you have a color terminal, try the option @samp{-C1} (@pxref{-C_},
@pxref{Color}). 

@item
Any option in @file{.fweb} that is intended to be processed @emph{after}
the command-line options should begin with @samp{&} rather than
@samp{-}.  (This is rarely necessary.)
@xref{Initialization}

@item
Put standard command-line options into @file{.fweb}.  Also put there
standard style parameters---e.g.,

@example
-pindex.tex "#.ndx"
-pmodules.tex "#.mds"
-pcontents.tex "#.cts"
@end example

@item
Learn how to use the style file. @xref{Style}.

@item
Use the info options @samp{-@@}, @samp{-D}, @samp{-y}, and @samp{-Z}
to find out about various internal @FWEB{} tables (control codes,
reserved words, memory allocations, and style-file parameters).
@xref{Info options}.

@item
Begin all @FWEB{} sources with invisible commentary 
bracketed by @samp{@@z...@@x}.
@xref{ATz}.

@item
Always include an explicit language-setting command in the limbo
section.  Under normal circumstances, do not set the language from the
command line.
@xref{Languages}.

@item
Keep sections quite short.
Knuth suggests a dozen lines.  That's
quite hard to achieve sometimes, but almost never should a section be more
than a page long.  If a block of code is longer than that, split it up
using named modules.

@item
It's easy to define macros from the command line to expedite
conditional preprocessing. 
@xref{-m}.

@item
Use the preprocessor construction @samp{@@#if 0...@@#endif} to
comment out unwanted code.
@xref{Preprocessing}.

@item
For logical operations with the preprocessor, use @samp{||}, not @samp{|}. 

@item
It's conventional to identify the ends of long preprocessor
constructions as follows:

@example
@@#if A
.
.
@@#endif // |A|
@end example

@item
To debug an errant @FWEB{} macro, use the built-in function
@samp{$DUMPDEF}. 
@xref{$DUMPDEF}.

@item
Use @samp{@@?} for compiler directives.  @xref{AT?}.
Use the style-file parameters @samp{cdir_start} to specify 
information that will be written out at the beginning of the line.
@xref{cdir_start}. 

@item
Stick to the standard @FWEB{} commenting style @samp{/*...*/} or
@samp{//...}.  Don't use alternatives such as @sc{Fortran}'s column 1
convention; these may not work or may not be supported someday.
@xref{Comments}.

@item
The meta-comment feature @samp{@@(...@@)} provides a poor-person's
alignment feature.  But it doesn't work very well, and it's not in the
spirit of @TeX{}; learn to use @samp{\halign} or the La@TeX{} alternatives.

@item
In @sc{Fortran}, use @samp{#:0} to declare readable alphabetic statement
labels.  See @ref{Tokens} and @ref{-colon}.

@item
When mixing languages, define the language of a module at the highest
possible level---e.g., in the unamed module, not after @samp{@@<...@@>=}.

@item
Use La@TeX{}.  Plain @TeX{} is no longer supported.   Upgrade to
La@TeX{}2e.  @xref{LaTeX}.

@item
If you are reading this documentation from printed pages, make sure it's
also installed as an Info package on your system so it can be read
interactively with @code{emacs}.  You can also read it through a
World-Wide Web browser such as Netscape.  For the address, see
@ref{Support}. 

@end enumerate


@node Science, , Tips, Hints
@comment  node-name,  next,  previous,  up

@cindex Scientific programming

@section Features for scientific programming

@FWEB{} contains a few features particularly intended for scientific
programming.

@enumerate
@item
Several built-in functions generate numerical constants.  See @samp{$PI}
(@ref{$PI}) and @samp{$E} (@ref{$E}).

@item
Several built-in functions perform mathematical manipulations.  See
@samp{$EXP} (@ref{$EXP}), @samp{$POW} (@ref{$POW}), @samp{$SQRT}
(@ref{$SQRT}), @samp{$LOG} (@ref{$LOG}), @samp{$LOG10} (@ref{$LOG10}), 
@samp{$MAX} (@ref{$MAX}), and @samp{$MIN} (@ref{$MIN}).

@item
The do-loop macro @samp{$DO} may be useful.  @xref{$DO}.

@item
C-style array indices can be used by means of the @samp{-n)} option.
@xref{-n)}. 

@item
An active bracket feature helps improve the appearance of
woven code that uses subscripts and/or superscripts heavily.  @xref{-W[}.

@end enumerate

@node New features, Support, Hints, Top
@comment  node-name,  next,  previous,  up

@chapter NEW FEATURES

@cindex Features, new

This info documentation is now accessible on the World-Wide Web; see
@ref{Support}. 

Some things that have been added or changed in recent releases are
described in the following.

@menu
* V1.61::
* V1.53::
* V1.52::
* V1.50::
* V1.40::
@end menu

@node V1.61, V1.53, New features, New features
@comment  node-name,  next,  previous,  up

@section Version 1.61

@subsection Updates to documentation (v1.61)

@quotation
@enumerate

@item
@FWEB{} supports color modes in which messages to the terminal can
appear in colors chosen by the user; see @ref{Color}.  The color mode is
set by the new command-line option @samp{-C} (@pxref{-C_}).  

@item
A previously undocumented feature is that for the C-like and
Fortran-like languages, @FTANGLE{} expands the binary notation
@samp{0b...} to an unsigned decimal number. @xref{Phases}.

@end enumerate
@end quotation

@subsection Redefined commands (v1.61)

@cindex Commands, redefined
@cindex Redefined commands, version 1.61

A few obscure commands have been slightly redefined.  Sorry about that,
but it makes for more symmetry and ease of recall, and/or solves some
technical problems.

@quotation
@enumerate

@item
Although it was never documented, previous versions permitted either
lower or upper case for the @samp{@@} commands that set the
language---e.g., both @samp{@@c} and @samp{@@C} worked.  Now only the
lower-case forms work.  (The upper-case forms may have other meanings.)

@item
The style-file parameter @samp{Ext_delimiter} now begins with an
upper-case @samp{E}; formerly it was lower-case.

@item
The behavior of the optional argument of the @code{\Title} macro has
been slightly redefined.  The new, more symmetrical form is

@example
\Title[Short title]@{Long title@}
@end example
@noindent
where @code{Long title} is printed on the title page and @code{Short
title} is used for the running header within the document.  @xref{Table
of Contents}.

@item
The line-break commands @samp{@@/} and @samp{@@\} (formerly identical)
now behave slightly differently.  @samp{@@/} breaks the line just as it
would if the line had been too long and been spontaneously broken.
@xref{AT/}.  @samp{@@\} backspaces one unit of indentation after
breaking the line.  @xref{ATbs}.  Usually, one should use @samp{@@/}
(sorry; I was previously recommending @samp{@@\}.  For an example in
which it is natural to use @samp{@@\}, see @ref{ATbs}.

@item
The names of some of the code-typesetting macros in @code{fwebmac.sty}
have been changed to conform to the convention that they should all
start with @samp{W}.  This change will be invisible to you unless you
happen to have user macros of your own that start that way or (perish
the thought) you have redefined low-level and obscure code in
@file{fwebmac.sty}. 

@end enumerate
@end quotation

@subsection New features (v1.61)

@cindex Features, version 1.61
This release adds some features for managing large projects, including
(i) the @code{idxmerge} utility that merges indexes produced by several
@FWEB{} files, (ii) a mechanism for accessing RCS-like information in
the ignorable commentary at the beginning of the file, and (iii) the
ability to include @FWEAVE{}-formatted code into a standard La@TeX{}
document.  It also fixes a variety of miscellaneous bugs.

@quotation
@enumerate

@item
A stand-alone index file suitable for processing by @code{makeindex} can
be produced by the @samp{-XI} option.  @xref{Using makeindex}.

@item
Stand-alone indexes produced by @samp{-XI} can be merged with the
@code{idxmerge} utility.  @xref{Merging indexes}.

@item
@FWEAVE{}-formatted code can be included in a standard La@TeX{}2e
document by means of the @code{fwebinsert} package.  
@xref{Inserting woven code}. 

@item
Revision-control-system (RCS) information that appears in the ignorable
commentary between the optional @samp{@@z} and @samp{@@x} that begin an
@FWEB{} file (@pxref{ATz}) is accessible in the body of the file
through the built-in function @code{$KEYWORD} (@pxref{$KEYWORD}) and the
new commands @samp{@@K} (@pxref{ATK_}) and @samp{@@k} (@pxref{ATk}).
These features can access RCS-like keywords that are not known to RCS
itself, as long as they fit the proper syntax (@pxref{ATz}).

@item
The @samp{-h} option now permits easy access to the GNU @code{info} browser if
it is installed.  @xref{-h}.

@item
Underscored versions of built-in functions have been removed!!!  E.g.,
use @code{$IF}, not @code{_IF}.  This change was warned about in the
last release.

@item
Single-character identifiers can now be completely cross-referenced via
the @samp{-W1} option.  @xref{-W1}.

@item
Some module warning messages can be eliminated with the @samp{-W@@}
option.  @xref{-WAT}.

@item
The @samp{@@q} command (still experimental) has been added to locally
turn on or off the the line and module comments in the tangled output.
@xref{ATq}. 

@item
The level of verbosity of @FWEB{}'s informational messages can be
controlled with the @samp{-M} option. @xref{-M_}.

@item
C/C++ programmers may find the command @samp{@@@{} useful.  @xref{ATlb}.

@item
The @samp{-nC} option has been added for @sc{Fortran} users; it kills
commented lines at a very early stage in the processing.  This can be
useful when converting existing codes to @FWEB{}.
@xref{-nC}

@item
@sc{Fortran}-90 (@pxref{-n9}) now defaults to free-form syntax.

@item
As of the non-beta Version 1.61, free-form @sc{Fortran}-90 now inserts
semicolons automatically in the code part.  Thus, textbook
@sc{Fortran}-90 examples will weave correctly without the annoyance of
explicitly terminating each statement with a semicolon.  (If you prefer
to put in the semicolons explicitly, use @samp{--n;} to turn off the
auto-insertion.) @xref{-n;}

@item
The default meaning of the @samp{-k} option was changed; now both lower-
and upper-case forms of @sc{Fortran} I/O keywords are recognized.
@xref{-k}. 

@item
Various changes were made to internal code in @file{fwebmac.sty}.  This
should not affect anyone @emph{unless} you have redefined @code{fwebmac}
macros.  If so, you'll have to compare your versions with the present
ones.  For example, colons as argument delimiters in @code{\def}s have
been removed.

@item
It is now (barely) possible to use @code{\documentstyle@{revtex@}}
instead of the default @code{\documentclass@{article@}}.  @xref{REVTeX}.

@end enumerate
@end quotation

@subsection Significant bugs (v1.61)

@cindex Bugs, version 1.61
@quotation
@enumerate
@item
Perhaps the most significant bug is that some high-order (>= 128)
characters in strings may not typeset or be processed correctly.  This
may be an issue for some users of foreign-language packages.  The
difficulty arises from a design decision made by a previous author.
This has at least partly been fixed, but I eschewed a substantial
overhaul for fear of breaking other things.

@end enumerate
@end quotation

@node V1.53, V1.52, V1.61, New features
@comment  node-name,  next,  previous,  up

@section Version 1.53

@cindex Features, version 1.53
This release fixes a relatively small number of obscure bugs in
@code{fweb-1.52-beta}.  A few minor enhancements were also made.  They include

@quotation
@enumerate

@item
Sections can be numbered by consecutive integers rather than LaTeX's
default Dewey-decimal form by saying

@example
LaTeX.package = "fwebnum"
@end example
@noindent
@xref{Sections}.

@item
The @samp{-H} option (experimental and incomplete) was added.
For C and C++, this option tells @FWEAVE{} to scan @code{#include}
files for @samp{typedef} and/or @samp{class} definitions.  @xref{-H_}.

@item
The @samp{-k} option was added.  This tells @sc{Fortran} and @sc{Ratfor}
to understand the lower-case forms of I/O keywords such as
@samp{iostat} (with the exception of @samp{read}, @samp{write}, and
@samp{end}).  @xref{-k}. 

@item
The @samp{-n:} option was added.  This tells @sc{Fortran} to place
statement labels on a separate line, which is useful when the labels are
relatively long.  (By default, @sc{Fortran} labels are placed on the
same line as the thing they are labeling, which looks good for short
labels.)  @xref{-ncolon}

@item
The preprocessor command @samp{@@#line} was added.  For C code, this
adds an explicit @samp{#line} command to the tangled output file.  This
helps to keep the line numbers between debugger and source file in sync
when an @FWEB{} preprocessor statement expands to several lines.
@xref{Debugging with macros}.

An implicit @samp{@@#line} command is added after each @samp{@@%}
(@pxref{AT%}) that begins a line (this keeps line numbering correct).
To override this, use the option @samp{-T#}.  @xref{-T#}.

@item 
@samp{-p} (style-file) options (@pxref{-p}) on the command line are now
processed @emph{after} the local style file.  @xref{Style}.

@item
The functionality of the @samp{-D} command was enhanced to include
optional arguments that limit the information that will be listed.  @xref{-D_}.

@end enumerate
@end quotation

@node V1.52, V1.50, V1.53, New features
@comment  node-name,  next,  previous,  up

@section Version 1.52

@cindex Features, version 1.52
This release was issued only as a beta version.  It consists mostly of
bug fixes.  However, there are a few other interesting points.

@quotation
@enumerate
@item
@code{fwebmac.sty} was enhanced to warn the user to run La@TeX{} again
when the section numbering hasn't yet been brought up to date.  I'm not
sure I've covered all the bases, but before it didn't complain at all.

@item
C++ classes are now formatted (identified as reserved words) on the first
pass, so forward references such as

@example
@@ The class |C|...
@@a
class C
  @{@}
@end example
@noindent
will now work.  Note that @b{typedef} has done this for a while, although
there are still a few glitches.

@item
For two years, the documentation has described two control codes as
follows:

@example
@@~ --- inhibit line break.
@@+ --- force an index entry.
@end example
@noindent
Apparently the code had these definitions inverted; it has now been brought
up to date with the documentation.  Fortunately these commands are
evidently not heavily used, since no one complained.

@item
@code{fwebmac.sty} was further reworked to interact properly with the
user package @code{multicol}.  If in @code{fweb.sty} one says
@samp{LaTeX.package "multicol"}, then the two-column index is done with
@code{multicol}; this gives various improvements over the
@code{\twocolumn} format that was used previously.  Furthermore, it's
possible to use @samp{multicol} to do one's entire document in
two-column format.  This turned out to be relatively simple, but one
needs to get the commands in the proper order.  See @ref{LIndex} for more
details.  Two-column format substantially cuts down the white space; I
saved about 50% on a 200-page code.

  One known glitch with @FWEB{}/@code{multicol} is that if one selects
page-number cross-references instead of La@TeX{} section numbers, page
references such as 98c don't get the 'c' correct.  This is presumably not a big
deal.  At this point, assume that the use of @code{multicol} is highly
experimental. 

@item
Further bugs in the C and C++ production rules were fixed.

@end enumerate
@end quotation

@node V1.50, V1.40, V1.52, New features
@comment  node-name,  next,  previous,  up

@section Version 1.50

@cindex Features, version 1.50
@quotation
@enumerate
@item
The syntax for entries in the initialization file @file{.fweb}
(@pxref{Initialization}) has been
modified (in a way that is as backward-compatible as possible).
Previously, @samp{+} meant process the option before the command-line
options, @samp{-} meant process it after.  This convention was somewhat
hard to remember, given the statement that any command-line option could
be put into @file{.fweb}; furthermore, just about everything in
@file{.fweb} should, in fact, be processed before the command-line
options.  So now both @samp{+} and @samp{-} mean the same thing, namely
process before (and the @samp{+} notation should fade away as time goes
on).  If you explicitly want something to be processed after 
all command-line options for some tricky reason, begin it with @samp{&}.
I.e., scan your @samp{.fweb} file for any line beginning with @samp{-}
and replace that with @samp{&}.

@item
The La@TeX{} processor (@samp{-PL}) is now the default.

@item
The experimental @file{fwebmacL.sty} macro package supplied with version
1.40 has been substantially reworked and is now the default
@file{fwebmac.sty}.  Remove any reference to @file{fwebmacL.sty} from
your @file{.fweb} file.

@item
Support for La@TeX{}2e is now provided.  @xref{LaTeX}.

@item
The style-file parameter @code{index.name} was added.  This is the
section name to be given to the Index (@pxref{Index}), which should be
the last major (starred) section.  It becomes the contents of the macro
@code{\INDEX}.  Therefore, one can end one's source file by saying

@example
@@* \INDEX.
@end example

@item
The @samp{$IF...} class of built-in functions was reworked.  They should
now be more robust, recursive, and intuitive.  Simple uses of these
functions should work as before.  However, complicated uses that
depended on tricky things about the order of expansion of arguments may
require revision.  Carefully compare the descriptions of these functions
in the documentation (e.g., see @ref{$IF}) with your usage of them in
any pre-existing code.

In some cases, if a previous constructions using @code{$IF} no longer works, it
might work if you say

@example
@@m $IF(a,b,c) $$IF(a,b,c)
@end example
@noindent
and then use @code{$$IF} in your code.  (This forces an extra level of macro
expansion.)  The same remark goes for @code{$DEFINE}.

The old forms @samp{_IF} etc. no longer work; convert to @samp{$IF}.

@item
The option @samp{-j} was added.  This inhibits multiple inclusions via
@samp{@@i} of the same include file.
@xref{-j}.

@item
One now has the ability to change the comment character that begins
@FTANGLE{}'s @samp{line} command.  In the style file, say, e.g.,

@example
line_char.N '#'
@end example

@noindent
to change the default @samp{*line} output by @FTANGLE{} in @sc{Fortran}
mode to @samp{#line}.  This could be useful if one runs the C
preprocessor on the tangled @sc{Fortran} output.

@item
@FWEAVE{}'s processing of @b{typedef} statements in C and C++ was
improved. 

@item
@FWEB{} should now be able to process C++ templates and exception handling,
at least in simple situations.  The typesetting of C++ references (e.g.,
@samp{int&}) was also improved.  Please report any difficulties.

@item
There were various miscellaneous obscure bug fixes.

@end enumerate
@end quotation

@node V1.40, , V1.50, New features
@comment  node-name,  next,  previous,  up@section Version 1.40

@section Version 1.40

@cindex Features, version 1.40
@quotation
@enumerate
@item
@emph{The meaning of @samp{@@+} has changed.}  (SORRY!)  Formerly, this
inhibited a line break; that function is now performed by @samp{@@~}.
The new meaning of @samp{@@+} is to force an index entry (the opposite
of @samp{@@-}, which inhibits an index entry).

If you have large codes using the old @samp{@@+} that you do not wish to
convert, you can recover the old mappings by placing the following
commands into @file{fweb.sty}:  

@example
yes_index = "~"
no_line_break = "+"
@end example

@noindent
However, please try to make the
conversion; the new codes are intended to be more symmetrical and easier
to remember.  

@item
@emph{Built-in functions now begin with @samp{$}, not @samp{_}.}  The
underscore prefix was a bad design decision; it introduces conflicts
with ANSI C in certain circumstances.  To ease conversion, the old forms
are still understood.  Thus, one can use @samp{$EVAL} and @samp{_EVAL}
interchangably.  However, @emph{do not use} the underscore forms; they
will be deleted in future releases.

@item
@emph{Full La@TeX{} support.}  @FWEB{} no longer usurps La@TeX{}'s
@code{\output} routine, and La@TeX{}'s sectioning commands,
Table-of-Contents commands, etc. are used.  The appearance of the woven
output is changed to be more book-like.  (This is an experiment.)

@item 
@emph{Verbatim language.}  @samp{@@Lv} selects a language-independent format.
@xref{Verbatim}

@item
@emph{Language-independent mode.}  The N mode inhibits pretty-printing,
blank compression, etc.; source code is essentially copied literally
from input to output.  This mode is turned on automatically by the
@sc{verbatim} language, but it can also be used with the other languages.  It
is turned on by the command-line option @samp{-N} or the local command
@samp{@@N}. @xref{ATN_}.

@item
@emph{Writing of temporary files.}  When the @samp{-F} command-line option is
in effect, tangled output is written to temporary files instead of the
final target files, and the temporary files are compared to the last
version of the target files on disk.  If there is no change, the target
files are not updated.  This avoid unnecessary recompilation if only the
documentation, not the code, was changed.  @xref{-F_}.

@item
@emph{Converting output tokens to lower case.}  @xref{-U_}.

@item
@emph{The built-in functions @samp{$E} and @samp{$PI}.}  @xref{$E},
@ref{$PI}.

@item
@emph{The built-in functions @samp{$EXP}, @samp{$LOG}, and
@samp{$LOG10}.}  @xref{$EXP}, @ref{$LOG}, and @ref{$LOG10}.

@item
@emph{@samp{$MAX} and @samp{$MIN} generalized to take arbitrary list of
arguments.}  @xref{$MAX}, @ref{$MIN}.

@item
@emph{The marriage-saver option}.  In response to a serious user
request, see @ref{-B_}.

@end enumerate
@end quotation

@node Support, Installing, New features, Top
@comment  node-name,  next,  previous,  up

@chapter SUPPORT

@cindex Support
@cindex Bugs
@FWEB{} is supported by John Krommes, @email{krommes@@princeton.edu}.
This project is a definitively @emph{spare-time activity}!!!  Bug
reports submitted with very short test files will be verified, although
not necessarily in real time.  For very simple fixes, a change file may
be provided.  Generally, however, bugs are not fixed until the next
release.  Releases occur intermittently, depending on my many other
professional obligations.

Suggestions are very welcome.  Many of @FWEB{}'s current features were
incorporated in response to users' requests.  However, the queue for
future improvements is long; nothing may happen immediately.  The next
major release of @FWEB{}, Version 2.00, is planned for approximately the
year 2000.  (You may be relieved to know that, to the best of my
knowledge, @FWEB{} does not suffer from the Y2K bug.)

This info documentation is now accessible on the World-Wide Web from

@quotation
@url{http://w3.pppl.gov/~krommes/fweb_toc.html}.
@end quotation

You can subscribe to one or both of two @FWEB{} mailing lists,
@code{fweb-users} and @code{fweb-installers}.  To subscribe, send e-mail
to @email{majordomo@@pppl.gov}.  In the @emph{body} of the message, say, e.g.,

@quotation
@code{subscribe fweb-users}
@end quotation
@noindent
You will receive introductory information describing how these lists are
intended to be used.  To unsubscribe at any time, substitute
@code{unsubscribe} for @code{subscribe} in the above instructions.

Archive files containing the messages sent to the @FWEB{} mailing
lists are kept in

@quotation
@code{ftp.pppl.gov:/pub/fweb/archive/fweb-@{users,installers@}.archive}.
@end quotation
@noindent
In addition to anonymous @code{ftp}, these files may be obtained by
sending a message to @code{majordomo@@pppl.gov} of the form 

@quotation
@code{get fweb-users fweb-users.archive}.
@end quotation

@node Installing, Concept index, Support, Top
@comment  node-name,  next,  previous,  up

@appendix  Installing @FWEB{}

Here is the bare-bones installation procedure for @sc{unix} users:

@cindex Installing @FWEB
@enumerate
@item 
Download the @code{zgip}-compressed @code{tar} file from
@code{ftp.pppl.gov:/pub/fweb}. 
The name of the file contains the version number---e.g.,
@file{fweb-1.61.tar.gz}. 

@example
ftp ftp.pppl.gov
bin
get fweb-1.61.tar.gz
quit
@end example

@item
Uncompress and unpack the tar file:

@example
gunzip fweb-1.61.tar.gz
tar -xf fweb-1.61.tar
@end example
@noindent
If the GNU @code{tar} is installed, these two steps can be combined into

@example
gtar -xzf fweb-1.61.tar.gz
@end example

Unpacking creates the directory @file{fweb-1.61}, with at least the two
subdirectories @file{Web} and @file{Manual}.

@item
Change to the new @file{Web} subdirectory and run the configuration script.

@example
cd fweb-1.61/Web
./configure
@end example

@file{./configure} is an @code{sh} script.  It attempts to figure out
various local system features automatically, then generates the three
files @file{defaults.mk}, @file{config.h}, and @file{custom.h}; those
are used in the @code{make}.  For further information about the
operation of @file{./configure}, see @file{fweb-1.61/READ_ME.FWEB}.

@item
Make and install the release:

@example
make @i{[}CFLAGS='@i{special compiler flags}'@i{]}
make install
@end example

If @code{gcc} is available, it will be used in the @code{make}; in that
case, the default @code{CFLAGS} should be sufficient.  If another
compiler is used, ensure that it is run in ANSI-compatible mode, not the
old-style Kernighan and Ritchie.

@FWEB{} compiles on my system without any warnings with 
@w{@samp{gcc -ansi -pedantic}}.  Please report any compiler warnings
from an allegedly ANSI-C environment. 

@end enumerate

@node Concept index, Option and command index, Installing, Top
@comment  node-name,  next,  previous,  up

@unnumbered Concept index

@printindex cp

@node Option and command index, Parameter index, Concept index, Top

@unnumbered Option and command index

@printindex fn

@node Parameter index, , Option and command index, Top
@comment  node-name,  next,  previous,  up

@unnumbered Parameter index

@printindex vr

@shortcontents
@contents

@bye