\input texinfo   @c -*-texinfo-*-
@def@ifhtml{@doignore{ifhtml}}
@setfilename fweb.info
@settitle FWEB

@ifinfo
     This file documents FWEB...
     
        Copyright 1993--1995 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--1995 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)


@unnumbered @sc{Fweb}

This Texinfo documentation describes @sc{Fweb} Version 1.53.
Versions 1.5x provide improvements of Version 1.40 to (1) include
support for La@TeX{}2e; (2) handle templates and exceptions for C++.
Versions 1.4x contained significant improvements over the previous
stable Version 1.30 and new features, both visible and invisible to the
user. 

If you used to receive e-mail information about @sc{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}.

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

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

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

The FWEB-FAQ can be found in 
@ifhtml
<A href="http://www.arsc.sunyit.edu/fwebdocs/fweb.html>fweb-faq</A>,
@end ifhtml

@quotation
@code{http://www.arsc.sunyit.edu/fwebdocs/fweb.html}.
@end quotation
@noindent
This is not necessarily up-to-date with the documentation you're reading
now.

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

@menu
* Copying::             Your rights; NO WARRANTY.
* Intro::               An introduction to @sc{Fweb}.
* Concepts::            General concepts of WEB programming.
* Files::               Files used by @sc{Fweb}.
* Starting::            Command-line syntax and options
* @@ commands: AT commands.  @sc{Fweb} commands.
* Comments::            Commenting styles.
* Languages::           Languages.
* Macros::              Macro definitions and preprocessing.
* Ratfor::              RATional FORtran.
* Formatting::          Features and hints about formatting with @sc{Fweave}.
* Customization::       Customizing @sc{Fweb}, learning about parameters, etc.
* Hints::               Various usage tips, etc.
* New features::        New features/changes in the current version.
* Support::             Help, bug reports, etc.
* Concept index::       Significant concepts.
* Option and function index::  Command-line options, @@ commands, etc.

 --- The Detailed Node Listing ---

INTRODUCTION to @sc{Fweb}

* History::             History of literate programming.
* Features::            Special features of @sc{Fweb}.

WEB CONCEPTS

* Processors::          @sc{Ftangle} and @sc{Fweave}.
* Phases::              Phases of operation of the @sc{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 @sc{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::          Set global language to C.
* -c++: -cpp.   Set global language to C++.
* -D: -D_.      Display information about @sc{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::          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::          Recognize lower-case forms of Fortran I/O keywords.
* -L: -L_.      Select global language.
* -l::          Echo the input line.
* -m::          Define an @sc{Fweb} macro.
* -m4::         Understand the m4 built-in commands.
* -m;::         Append pseudo-semicolons to @sc{Fweb} macro definitions.
* -n::          Set global language to Fortran--77.
* -n9::         Set global language to Fortran--90.
* -n;::         For Fortran--77, supply semicolons automatically (default).
* -ncolon::     In Fortran, place statement labels on separate lines.
* -nb::         In Fortran, number the ifs and dos.
* -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 @sc{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;::         Turn on Ratfor's auto-semi mode.
* -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 @sc{Ftangle}.
* -t::          Truncate identifiers.
* -U: -U_.      Convert reserved output tokens to lower case.
* -u::          Undefined a predefined or command-line macro.
* -v::          Make all comments verbatim.
* -W: -W_.      Flag-setting commands for @sc{Fweave}.
* -w::          Modify processing of @code{fwebmac.sty}.
* -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 @sc{Ftangle}

* -TD::         Permit processing of deferred macro definitions.
* -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 @sc{Fweave}

* -W[::                 Turn on processing of bracketed array indices.
* -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.

@sc{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 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.
* @@f: ATf.      Format identifier or module name.
* @@I: ATI_.     Include a WEB file, but don't print it.
* @@i: ATi.      Include a WEB file.
* @@L: ATL_.     Set language.
* @@l: ATl.      Specify limbo text.
* @@M: ATM_.     Define an @sc{Fweb} macro.
* @@m: ATm.      Define a @sc{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).
* @@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.
* @@": AT".         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.        Suppress default insertion of breakpoint command.

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.
* @@\: ATbs.         Insert a line break.
* @@/: AT/.         Insert a line break (obsolete).
* @@|: 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.

MACROS and PREPROCESSING

* Outer macros::        Macros copied to beginning of output file (@@d).
* FWEB macros::         Macros expanded by @sc{Fweb} (@@m).
* Preprocessing::       @sc{Fweb}'s preprocessing language (@@#if etc.)

@sc{Fweb} macros

* Macro features::      Various points about @sc{Fweb} macros.
* Tokens::              Special tokens used in @sc{Fweb} macros.
* Built-in functions::  Macro-like functions built into @sc{Fweb}.
* Debugging with macros:: Debugging glitches, and their solutions.

Built-in functions

* $A::                  Convert to ASCII.
* $ABS::                Absolute value.
* $ASSERT::             Assert a condition.
* $COMMENT::            Generate a comment.
* $DATE::               Today's date.
* $DAY::                Today.
* $DECR::               Decrement a macro.
* $DEFINE::             Define a 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.
* $HOME::               The user's home directory.
* $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.
* $L::                  Change string to lower case.
* $LANGUAGE::           Identifier for current language.
* $LANGUAGE_NUM::       Number of current language.
* $LEN::                Length of string.
* $LOG::                Natural logarithm.
* $LOG10::              Logarithm to the base 10.
* $M::                  Define a 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.
* $OUTPUT_LINE::        Current line number of tangled output.
* $P::                  The C preprocessor symbol '#'.
* $PI::                 3.14159...
* $POW::                Raise to a power.
* $ROUTINE::            Current Ratfor program, function, or subroutine.
* $SECTION_NUM::        Number of current section.
* $SECTIONS::           Maximum number of sections.
* $SQRT::               Square root.
* $STRING::             Expand argument, then stringize.
* $STUB::               
* $TIME::               The local time.
* $TRANSLIT::           Transliterate a string.
* $U::                  Change string to upper case.
* $UNDEF::              Undefine an @sc{Fweb} macro.
* $UNQUOTE::            Remove quotes from string.
* $VERBATIM::           (Obsolete.)
* $VERSION::            @sc{Fweb} version number.

LANGUAGES

* Setting::             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 @sc{Fweb} Ratfor.

FORMATTING

* Typesetting::         Woven output; TeX vs. LaTeX, etc.
* Pretty-printing::     Turning ugly input into beautiful output.

Typesetting

* Output::	Structure of the TeX output from @sc{Fweave}.
* fwebmac.sty:: The macro package used with @sc{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.
* Sections::	        Section numbering, spacing, etc.
* Index::               Technical details about multi-columns and the Index.
* Table of Contents::   The Table of Contents.
* Customizing LaTeX::   Conditional flags, etc.

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.

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 @sc{Ftangle}.
* -ykw::        Stack size for @sc{Fweave}.
* -yll::        Line length for @sc{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 @sc{Fweb} macros.
* -ymb::        Size of the buffer for expanding @sc{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 @sc{Ftangle} can process.
* -ytw::        Maximum number of tokens in the current section being
                        processed by @sc{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 @sc{Fweb}'s macros.
* Completion params::           Automatic selection of file extensions, etc.
* Control-code mappings::       Remapping @sc{Fweb}'s control codes (danger)!
* Miscellaneous params::        Other customizations.

Customizing @sc{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.
* format.reserved: S_format.
* format.short_identifier: S_format.
* format_OUTER_MACRO: S_format.
* format.outer_macro: S_format.
* format_WEB_MACRO: S_format.
* format.WEB_macro: S_format.
* format.intrinsic: S_format.
* format_KEYWORD: S_format.
* format.keyword: S_format.
* format.typewriter: S_format.
* format.wildcard: S_format.

* 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: S_meta_t.          Comment char. for @sc{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.

* outer.def: S_outer.           @sc{Ftangle} converts @samp{@@d} to this.
* outer.undef: S_outer.         @sc{Ftangle} converts @samp{@@u} to this.

* protect::                     Protection character to end a continued line.
* suffix::                      Suffixes for output files.

For @sc{Fweave}:

* macros::                      Default name of the macro package to be
                                        read in by @sc{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 @sc{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.change: S_ext.     Extensions for the change file.
* ext.hweb: S_ext.       Extensions for include files.
* ext.hchange: S_ext.    Extensions for change files associated with
                                include files. 

USAGE TIPS and SUGGESTIONS

* Converting::          Converting an existing code to @sc{Fweb}.
* Tips::                Usage tips and suggestions.
* Science::             Useful features for scientific programming.

NEW FEATURES

* V1.53::
* V1.52::
* V1.50::
* V1.40::
@end menu

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

@unnumbered @sc{Fweb} Copying Permissions

@sc{Fweb} is "free"; this means that everyone is free to use them and free to
redistribute them on a free basis.  @sc{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 @sc{Fweb} will be useful, 
there is @emph{ABSOLUTELY NO WARRANTY}.  

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

@chapter INTRODUCTION to @sc{Fweb}

@cindex Literate programming
@sc{Fweb} is a system for @dfn{literate programming}.  It enables one to
maintain both documentation and source code in a single document (the
@code{web} file), and to explain the code in terms of a @dfn{web} of very
small fragments.  Because it 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}. 


@sc{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{}.  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.} 

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 Standard 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.  @sc{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
work of Ramsey and Briggs on language-independent webs.

The original WEBs 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, ``The
La@TeX{} Companion'' (Addison--Wesley, Reading, MA, 1994). 
Future @sc{Fweb} development will assume that users have a recent
version of La@TeX{}.  Version 1.50 of @sc{Fweb} includes support for
La@TeX{}2e, to which users should upgrade as soon as possible.

@menu
* History::             History of literate programming.
* Features::            Special features of @sc{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 @sc{Fweb}

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

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

@item
@sc{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, @sc{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
@sc{Fweb} contains a built-in @sc{Ratfor} (@sc{RATional} @sc{FORtran})
translator.  @xref{Ratfor}.

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

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

@end itemize

@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 is given in @ref{Intro}.  @sc{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::          @sc{Ftangle} and @sc{Fweave}.
* Phases::              Phases of operation of the @sc{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 @sc{Fweb} processors

@cindex Processors, @sc{Fweb}
Following Knuth's original design, @sc{Fweb} consists of two processors,
@sc{Ftangle} and @sc{Fweave}.  Both operate on a single source file, say
@file{test.web}.  @sc{Ftangle} produces compilable code, say @file{test.c},
whereas @sc{Fweave} produces a @TeX{} file, @file{test.tex}, that can
(in principle) be processed with either @TeX{} or La@TeX{}.  

Future @sc{Fweb} development will be based on La@TeX{}, and it will no
longer be guaranteed that Plain @TeX{} will work in all circumstances.
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 @sc{Fweb} source file is structured into @dfn{sections}.  
@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
Sections, possibly noncontiguous, can be combined into larger units
called @dfn{modules}, as explained in @ref{Modules}.

A simple example of an @sc{Fweb} source file consisting of three sections is as
follows:

@example
@@n

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

@@m PI 3.14159 // FWEB macro definition.

@@a
        program main
        call compute
        end

@@ The computational routine is pretty boring.
@@a
        subroutine compute
        write(*,*) 'pi = ', PI
        end

@@* \INDEX.
@end example

Commands to @sc{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.  For more information about languages,
see @ref{Languages}.

@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.  Major sections are entered in the
Table of Contents.  The command @samp{@@*@i{n}} begins a major
(sub)section of level @i{n}, where @samp{@@*0} is equivalent to the
simple @samp{@@*}, @samp{@@*1} indicates a subsection, @samp{@@*2}
indicates a subsubsection, and so on.  For La@TeX{}, the highest
permissible major level is 3 (a subsubsubsection).  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}.  This command tells
@sc{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}.  For more
information, see @ref{S_index}.

Minor (@dfn{unnamed}) sections are begun by @samp{@@ }; these have no
associated names and are not entered into the Table of Contents.

All sections begin with (optional) @TeX{} commentary.  
@cindex Commentary, optional
Within that
commentary, 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 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. 

@TeX{} commentary is followed by an
optional 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 @sc{Fweb} macro definition (@samp{@@m}); the
second section has no definition part.  For more information, see @ref{Macros}.

An unnamed 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}.

The portion of the source file before the first section (i.e., before
the first @samp{@@*} or @samp{@@ }) 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 @sc{Ftangle} and is copied by @sc{Fweave} to the
output file.  Thus, one can make @TeX{} macro definitions in limbo that
override the defaults in @sc{Fweb}'s macro package @file{fwebmac.sty}.
(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.  For more
information, see @ref{LaTeX}.

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

@section Modules

Sections, possibly noncontiguous, can be combined into @dfn{modules}.  
@cindex Modules
Modules can be @dfn{named} or @dfn{unnamed}. There is just one unnamed module.

@subsection The unnamed module

The unnamed 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.
The fundamental operation of @sc{Ftangle} is that
@emph{@sc{Ftangle} outputs the unnamed module}.  Thus, there must be at
least one @samp{@@a} in the source file or @sc{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
A module name is specified by

@example
@@< 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
@sc{Fweave} to typeset a code fragment.

To define a named module, replace the @samp{@@a} that begins the unnamed code
part of a section by @samp{@@< 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 original section.  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;
@sc{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, it
uses the pseudo-semicolon @samp{@@;}; for more discussion of its use,
see @ref{AT;}.  Second, after a name has appeared once in full, it may be
abbreviated by a unique prefix followed by 3 dots, 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 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 unnamed sections.

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

@section Phases of processing

The @sc{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 @sc{Ftangle}

@cindex Phases, of @sc{Ftangle}
@sc{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 source;

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

@item
expands @samp{@@'...'} (@pxref{ATquote}), @samp{@@"..."} (@pxref{AT"}),
and @samp{0b...} (in @sc{Fortran}, also @samp{0...} and @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 @sc{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 @sc{Fweave}

@cindex Phases, of @sc{Fweave}
@sc{Fweave} has three phases.  In phase 1, the source file is read and
cross-reference information is collected.  In phase2, the source file is
read again, then pretty-printed (including some cross-reference
information).  In phase 3, an 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 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 the Table of Contents (@file{CONTENTS.tex} by default, but
see @ref{Output files} and @ref{Contents params}).
@end itemize

@end quotation


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

@chapter FILES

@cindex Files
@sc{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
@sc{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 home directory.
@xref{Initialization}
@findex .fweb

@file{fweb.sty} --- Style file (optional; for customizing the behavior
of a particular @code{web} file).  @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

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

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

@file{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{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 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:

@example
Type of file    Style-file entry      Default

WEB file           @file{ext.web}          @file{.web}
Change file        @file{ext.ch}           @file{.ch}
Include file       @file{ext.hweb}         @file{.hweb}
Change file
 for include file  @file{ext.hch}          @file{.hch}
@end example

@noindent 
More than one extension may be specified, as a space-delimited
list---e.g., @samp{"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
@sc{Fweave} writes a variety of output files.

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

@file{CONTENTS.tex} --- Temporary file that accumulates
Table-of-Contents information.  
@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.

@sc{Ftangle} writes files of the form

@quotation
@file{name.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:

@example
Language        Style-file entry    UNIX default   non-UNIX default

 C               suffix.C               .c              .c
 C++             suffix.Cpp             .C              .C
 Fortran--77     suffix.N               .f              .for
 Fortran--90     suffix.N90             .f90            .for90
 Ratfor--77      suffix.R               .r              .rat
 Ratfor--90      suffix.R90             .r90            .rat90
 TeX             suffix.X               .sty            .sty
 VERBATIM        suffix.V               .mk             .mk
@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 @sc{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
@sc{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 @sc{Fweb}

@sc{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}).

A @dfn{style} file (@pxref{Style}) can be associated with each manuscript
in order to customize its 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@} webfile[.web] [changefile[.ch]] [-option...]
@end example
@noindent
File names are 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 before the file names.  The first file name
encountered is the @code{web} file (source file); the second, if it exists, is
the change file (@pxref{Change files}).  [When no change file is
specified, @sc{Fweb} attempts 
to read from the null file (@file{/dev/null} on @sc{unix} systems).  This
name should be specified when @sc{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.

@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 @sc{Fweb} macro can be
defined from the command line by saying something like @samp{-mIBMPC=1}.
No spaces are allowed between any option and its argument.  If one says
@samp{-m IBMPC}, @sc{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::          Set global language to C.
* -c++: -cpp.   Set global language to C++.
* -D: -D_.      Display information about @sc{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::          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::          Recognize lower-case forms of Fortran I/O keywords.
* -L: -L_.      Select global language.
* -l::          Echo the input line.
* -m::          Define an @sc{Fweb} macro.
* -m4::         Understand the m4 built-in commands.
* -m;::         Append pseudo-semicolons to @sc{Fweb} macro definitions.
* -n::          Set global language to Fortran--77.
* -n9::         Set global language to Fortran--90.
* -n;::         For Fortran--77, supply semicolons automatically (default).
* -ncolon::     In Fortran, place statement labels on separate lines.
* -nb::         In Fortran, number the ifs and dos.
* -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 @sc{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;::         Turn on Ratfor's auto-semi mode.
* -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 @sc{Ftangle}.
* -t::          Truncate identifiers.
* -U: -U_.      Convert reserved output tokens to lower case.
* -u::          Undefined a predefined or command-line macro.
* -v::          Make all comments verbatim.
* -W: -W_.      Flag-setting commands for @sc{Fweave}.
* -w::          Modify processing of @code{fwebmac.sty}.
* -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 (@sc{Fweave})

@findex -1
@cindex Debugging
This option tells @sc{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).  @sc{Fweave} contains @dfn{production rules}
such as ``replace the combination @samp{expr binop expr} with
@samp{expr}.''  If all goes well, the result of @sc{Fweave}'s reduction
process is ultimately just one scrap, such as @samp{function}.  If
@sc{Fweave} is left with more than one scrap at the end of a section,
this is called an @dfn{irreducible scrap sequence}, and @samp{-1} displays
them.

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

@cindex Output, changing appearance of
While @sc{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, and 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 (@sc{Fweave})

@findex -2
@cindex Debugging
This option tells @sc{Fweave} to display detailed reductions of the
scraps as it does the pretty-printing.  (For a discussion of scraps, see
@ref{-1}.)  Sometimes @sc{Fweave} fails spectacularly at
printing-printing a section, either because of a syntax error on the
part of the user or because of a bug in @sc{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 may be used anywhere; others 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 (@sc{Ftangle}
or @sc{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.  @sc{Fweb} works
internally with the ASCII character set.  If @sc{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
@sc{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 (@sc{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, -cpp, -b, 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, not 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, @sc{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), @sc{Fweb} completes the name by adding
the extension contained in the style-file parameter listed in the
following table:

@example
        Type of file    Style-file entry      Default

        WEB file           @file{ext.web}          @file{.web}
        Change file        @file{ext.ch}           @file{.ch}
        Include file       @file{ext.hweb}         @file{.hweb}
        Change file
         for include file  @file{ext.hch}          @file{.hch}
@end example

@noindent
More than one extension may be specified, as a space-delimited
list---e.g., @samp{"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 (@sc{Ftangle})

@findex -F
When the @samp{-F} option is in effect, @sc{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 @file{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
@file{touch} to force processing of a group of files, but the @code{web}
sources are never changed, the @file{make} file will continue to tangle
the sources no matter how many times it is run, since @sc{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 @sc{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.  This 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 (@sc{Fweave})

@findex -f
The @samp{-f}
option turns off the subscripting operations inserted by @sc{Fweave} to
indicate where various identifiers are defined.  Sometimes these are
very helpful; sometimes they are too cluttered and confusing.
@xref{Subscript params}.


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

@subsection @samp{-H}:  Scan include files (@sc{Fweave})

@findex -H
@cindex Include files, scanning
For C or C++, the @samp{-H} option tells @sc{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} statements, which would otherwise be necessary in order that
the code be pretty-printed correctly.  For example, in the code

@example
@@c++
@@
#include <Complex.h>

Complex z;
@end example
@noindent
the identifier @b{Complex} will be properly formatted as a reserved
word, as though one had said @samp{@@f Complex int}.

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
(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 @sc{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 @sc{Fweave} scans.

This command, new with version 1.53, is @emph{highly experimental} and
incomplete.  There is, as yet, no mechanism for sending macro definitions to the
preprocessor, so conditional preprocessing that relies on macro
definitions made outside of the header file will not work correctly.
Furthermore, it works only when one's compiler is @file{gcc} or
@file{g++}.  (I haven't yet added code that automatically figures out
how to run the preprocessor on an arbitrary system.)

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

@subsection @samp{-h}:  Get help

@findex -h
This just prints a message saying where further help is available.  It
refers one to the on-line documentation (@pxref{Support}) and to
the various information options (@pxref{Info options}).

@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 (@sc{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
command @samp{-H} 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 @sc{Fweb}'s @samp{@@i} command suffers from a design
deficiency:  they cannot be inhibited by means of @sc{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}:  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.
By default, only the upper-case forms of these words are recognized,
because certain of the lower-case forms---in particuler, @samp{end},
@samp{read}, and @samp{write}---have other special meanings (and
@sc{Fweb} identifiers can have just one meaning throughout the code).
However, when the @samp{-k} option is used, the lower-case forms are
recognized as well (except for the three special identifiers just
mentioned).

@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 @samp{@{c,c++,n,n9,r,r9,v,x@}}.  @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,-m4,-l,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-m}:  Define @sc{Fweb} macro (@sc{Ftangle})

@findex -m
The command-line construction

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

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

@noindent
had appeared at the beginning 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'   // A(x) expands to `x'
-m'A(x) =x'  // A(x) expands to `=x'
-m'A(x)==x'  // Precisely equivalent to the previous example.
@end example


@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 @sc{Fweave} to properly format the reserved words of the @code{m4}
preprocessor.  The use of this preprocessor is @emph{not recommended} in
conjunction with @sc{Fweb}; use @sc{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 @sc{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 @sc{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,-n;,-n,Options
@comment  node-name,  next,  previous,  up

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

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

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

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

@findex -n;
@cindex Semicolons, automatic
This is the default mode of operation in @sc{Fortran}--77; the input driver
automatically appends a semicolon to each logical line of source code.
Since it's the default, one doesn't have to use it unless one wishes to
negate it.  @xref{Negating options}.

Although semicolons are appended automatically for @sc{Fortran}--77,
@sc{Fweave} will not print them by default since that seemed to annoy
many users.  To force the semicolons to be printed, use the @samp{-np}
option (@pxref{-np}).

Currently, this option has no effect for @sc{Fortran}--90 in free-form
syntax (see @ref{-n\} and @ref{-n&}).  That is, one must supply the
semicolons oneself (as one would do in C or @sc{Ratfor}).  (Without the
semicolons, one's code may tangle correctly, but @sc{Fweave} will be
confused.)  Consider this to be a feature.  It is an attempt to provide
some uniformity of style for the various free-form languages (C,
@sc{Ratfor}, and @sc{Fortran}-90) that @sc{Fweb} supports.  I expect
some arguments on this point, and may back down.

@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}.
This macro is emitted only when @samp{-n:} is @emph{not} used.
@findex \Wlbl

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

@subsection @samp{-nb}:  Number @b{if}s and @b{do}s [@sc{Fortran}] (@sc{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 -np,-n\,-nb,Options
@comment  node-name,  next,  previous,  up

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

@findex -np
@cindex Semicolons, printing
Although for fixed-form syntax the @sc{Fortran} input driver
automatically terminates logical lines 
with semicolons so that the innards of @sc{Fweave} can process them
correctly (@pxref{-n;}), the semicolons are not printed by default.
To make them be printed, use the @samp{-np} option.

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

In free-form syntax, an @sc{Fweb} convention is that at present the user must
supply semicolons by hand at the end of each statement.  For more
discussion, see @ref{-n;}. 

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

In free-form syntax, an @sc{Fweb} convention is that at present the user must
supply semicolons by hand at the end of each statement.  For more
discussion, see @ref{-n;}. 

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 @sc{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

@example
@@n[-n/]
@end example

@noindent
In @sc{Fweb}, one may always use @samp{\/} for concatenation, 
@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 @sc{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 @sc{Fweb}'s
standard convention that @samp{//} denotes the start of a short
comment (@pxref{-n/}).  See also @ref{-!} and @ref{-r!}.

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

@subsection @samp{-n)}:  Reverse array indices [@sc{Fortran}] (@sc{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
@sc{Ftangle}): 

@example
a(k)(i) => a(i,k)
a(k)(i,j) => a(i,j,k)
a(k)(j)(i) => 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, @sc{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) // OK
character*90 ch(4) // OK
write(6,*) ((x(i)(j),i=1,2), j=3,4) // Will reverse incorrectly.
c = ch(4)(3:4) // 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 @sc{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 @sc{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.  (But note that future @sc{Fweb} development will
be based on La@TeX{}; @samp{-PT} is no longer fully supported.)

@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. (@xref{Style}.)
Its argument is exactly the
same as a line that one may put into the local 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:

@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 (@sc{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 --- break
c --- case
t --- default
d --- do
f --- for
i --- if
n --- next
p --- repeat, until
r --- return
s --- switch
h --- where
w --- while
@end example

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

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

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

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

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

@subsection @samp{-r;}:  Turn on auto-semi mode [@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 @sc{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!}.

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

@subsection @samp{-r)}:  Reverse array indices [@sc{Ratfor}] (@sc{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 @sc{Ftangle}

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

@menu
* -TD::         Permit processing of deferred macro definitions.
* -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, -Tv, -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.

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

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

@findex -Tv
@cindex Header comments, printing
By default, @sc{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
@sc{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 @sc{Fweb} inserts a
@samp{#line} command for some reason.  To prevent this, @sc{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 (@sc{Ftangle})

@findex -U
@cindex Tokens, upper-case
Particularly during @sc{Ratfor} expansion, certain tokens such as
@samp{DO} are output by @sc{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 @sc{Fweb} macro (@sc{Ftangle})

@findex -u
@samp{-uA} undefines the @sc{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,-W_,-u,Options
@comment  node-name,  next,  previous,  up

@subsection @samp{-v}:  Make all comments verbatim (@sc{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 @sc{Fweave}

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

@menu
* -W[::                 Turn on processing of bracketed array indices.
* -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 -W[,-Wnoprint,-W_,-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}, @sc{Ftangle} will just replace the brackets by parentheses.
In C, the brackets will be left alone.

@findex \WARRAY
@sc{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 @sc{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 -Wnoprint, , -W[, -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 --- outer definitions (@@d or @@D)
-Wf --- format statements (@@f)
-WF --- format statements (@@F)
-Wl --- limbo text definitions (@@l)
-Wm --- FWEB macro definitions (@@m or @@M)
-Wv --- operator overloads (@@v)
-Ww --- identifier overloads (@@w or @@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 (@sc{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.''

This option can be used for special effects when one is trying to obtain
behavior different from that defined by @sc{Fweb}'s macro package
@file{fwebmac.sty} (@pxref{fwebmac.sty}).  However, try not to use it.
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 (@sc{Fweave}). 

@findex -x
@cindex Cross-references, eliminating
Cross-reference information (for @sc{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 (@sc{Fweave})

@findex -X
This option is the opposite of @samp{-x}.  @xref{-x}.

@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 @sc{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.  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 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}.

@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} 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 @sc{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 @sc{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, @sc{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 @file{"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 -l(
@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 @file{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 (@sc{Ftangle})

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

This command has no effect for @sc{Fweave}.  

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

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

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

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

@subsection @samp{-#}:  Turn off comments about line and section numbers (@sc{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{-#}.

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.  It is possible to do this, but the command is
still experimental and has not yet been announced.  If you need to do this,
please contact the developer (@pxref{Support}).

@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 its C counterpart.  To turn this feature off, use
@samp{-+}.  

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, the @samp{//} construction will be interpreted
as concatenation rather than as the beginning of a short comment.

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 @sc{Fweb}'s standard @samp{//} to
begin short comments.

@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 @sc{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.
@xref{-h}.

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

@chapter @sc{Fweb} COMMANDS

All @sc{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} processing].

Some of these control codes may be used anywhere; others begin a new
part.  For a quick summary of the control-code mappings and to see which
codes begin new parts, use the @samp{-@@} option.  @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 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.
* @@f: ATf.      Format identifier or module name.
* @@I: ATI_.     Include a WEB file, but don't print it.
* @@i: ATi.      Include a WEB file.
* @@L: ATL_.     Set language.
* @@l: ATl.      Specify limbo text.
* @@M: ATM_.     Define an @sc{Fweb} macro.
* @@m: ATm.      Define a @sc{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).
* @@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.
* @@": AT".         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.        Suppress default insertion of breakpoint command.

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.
* @@\: ATbs.         Insert a line break.
* @@/: AT/.         Insert a line break (obsolete).
* @@|: 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}.
@xref{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 @sc{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.)

@cindex Line break, optional
In a code part, @samp{@@|} inserts an optional line break in an
expression---e.g., @samp{f(a,b,@@|c+d,...)}.  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}), which always breaks 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 @samp{@@ }.

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

@findex @@ 
@cindex Section, beginning minor
@samp{@@ } 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
@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 @samp{@@*} is followed by a digit @i{n}, it begins a new major section of
level @i{n}.  For example,

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

@@*1 Input routines.  Now follow some subroutines.
@@a
get_input()
@{@}
@end example

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

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

@sc{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{@@< Module name @@>=}.

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

@findex @@<
@cindex Module name, beginning
@samp{@@<} begins a module name, which has the form
@samp{@@< TeX text @@>}.  (Module names inside @sc{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{@@< TeX text @@>}.

@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, @sc{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 @code{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, ATc, ATa, AT commands
@comment  node-name,  next,  previous,  up

@section Control codes b--z

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

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


@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, ATf, 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 ATf, ATi, ATd, 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 @sc{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 @sc{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 @samp{@@ }) if at all possible.

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_, ATL_, 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 ATL_, ATl, ATI_, 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 @sc{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 newlines 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 near the point where
the logical discussion is made.

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

@subsection @samp{@@M}:  Define @sc{Fweb} macro

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

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

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

@subsection @samp{@@m}:  Define @sc{Fweb} macro, and mark

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

@samp{@@m} defines an @sc{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 @sc{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 @sc{Ftangle} and tells @sc{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
@sc{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 @samp{@@ } 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 @sc{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 @sc{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.

@xref{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
@xref{ATL_} and @ref{Languages}.

@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 newfile.c
@end example

@noindent
changes the name of @sc{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. 

@node ATo, ATr, 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 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.  This
feature is useful for producing C header files.  For an example, see the
discussion in @ref{Outer macros}.

@node ATr, ATr9, ATo, 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.}

For a detailed discussion of overloading 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 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
@sc{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.

@samp{@@z} is also used in change files to end a change.  @xref{Change
files}.

@node ATquote, AT", 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, @sc{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 @sc{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 AT", 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/*, AT", 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

@sc{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 brace

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

@findex @@@{
This is for detailed debugging of @sc{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 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.  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{@@^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{@@.My entry@@>}.

@node AT9, ATt, ATdot, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@9}:  Make index entry (\9 format)

@findex @@9
@cindex Index entries, user format
The construction @samp{@@9Text@@>} 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@{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
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 (@sc{Fweave})

@findex @@t
When @sc{Fweave} sees the command @samp{@@tControltext@@>}, it packages
the control text into an @code{\hbox} and ships it to the output.  This
command is ignored by @sc{Ftangle}.

@node AT=, ATcomma, ATt, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@=}:  Pass control text verbatim to the output

@findex @@=
For @sc{Ftangle}, the command @samp{@@=Controltext@@>} sends the control
text to the output exactly as input.  @sc{Fweave} highlights the control
text by drawing a box around it.

@node ATcomma, ATbs, AT=, AT commands
@comment  node-name,  next,  previous,  up

@section Spacing

@cindex Spacing commands

The spacing commands are used to refine @sc{Fweave}'s pretty-printed
output.  Generally it's not necessary to bother with these until one's
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.  (Need an example here.)

@node ATbs, AT/, ATcomma, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@\}:  Force a line break

@findex @@\
@cindex Line break, forcing
For example,

@example
int@@\
  i,@@\
  j,@@\
  k;
@end example

Distinguish this command from @samp{@@|} (@pxref{AT|}), which inserts an
optional breakpoint into an expression.

@node AT/, AT|_, ATbs, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@/}:  Force a line break (obsolete)

@findex @@/
This is an obsolete form of @samp{@@\}.
@xref{ATbs}.

@node AT|_, AT#, AT/, 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 @sc{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
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 @sc{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 @sc{Fweb} macro.

@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 @sc{Ftangle} and not
printed by @sc{Fweave}; however, they retain grammatical significance
that helps out @sc{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 @sc{Fweave}'s pretty-printing has
broken down because it didn't properly understand the language syntax.
If, for example, @sc{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 @sc{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, @sc{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 @sc{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}.

@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, 

@example
@@<Cases@@>=
case 1:
case 2:
case 3@@:
@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
@sc{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

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

@node Invisible comments,Visible comments,Comments,Comments
@comment  node-name,  next,  previous,  up

@section Invisible comments

@cindex Comments, invisible
@example
@@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}.

@@%       --- All material until and including the next newline is
            completely ignored.

@@%%      --- As @samp{@@%}, but also skip blank lines that immediately
             follow the current line.
@end example

For example,

@example
@@z
Author:  J. A. Krommes
@@x
@@c @@% This sets the global language to C.
@@* EXAMPLE.
@end example

@node Visible comments,,Invisible comments,Comments
@comment  node-name,  next,  previous,  up

@section Visible comments

@cindex Comments, visible

@samp{/* ... */} is a long comment (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-man'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.}  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 Macros,Ratfor,Languages,Top
@comment  node-name,  next,  previous,  up

@chapter MACROS and PREPROCESSING

@cindex Macros

@menu
* Outer macros::        Macros copied to beginning of output file (@@d).
* FWEB macros::         Macros expanded by @sc{Fweb} (@@m).
* Preprocessing::       @sc{Fweb}'s preprocessing language (@@#if etc.)
@end menu

@node Outer macros,FWEB macros,Macros,Macros
@comment  node-name,  next,  previous,  up

@sc{Fweb} recognizes two kinds of macros:  @dfn{outer macros}, and @dfn{WEB
macros} or @dfn{inner macros}.  Control codes associated with either of
these kinds normally begin the definition part.  However, @sc{Fweb}
macros are sometimes allowed in the code part as well; see @ref{FWEB macros}.

Macros are processed by @sc{Ftangle} only; @sc{Fweave} merely prints
them as they occur in the source file.

@section Outer macros

@cindex Macros, outer
Outer macros are defined by @samp{@@d} (@pxref{ATd}) or @samp{@@D}
(@pxref{ATD_}).  They may be placed in any definition part.  @sc{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 shorthand 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 @file{test.h}.  One way of accomplishing this is to
redirect @sc{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:

@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,Preprocessing,Outer macros,Macros
@comment  node-name,  next,  previous,  up

@section @sc{Fweb} macros

@cindex Macros, @sc{Fweb}
@sc{Fweb} macros are defined by @samp{@@m} (@pxref{ATm}) or @samp{@@M}
(@pxref{ATM_}).  These should normally be placed in the definition
section, as in 

@example
@@ Documentation...

@@m CUBE(x) pow(x, 3.0)

@@a
@end example
@noindent
They are collected during
@sc{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
@sc{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.  @sc{Fweb} macros are often used in conjunction with
the @sc{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 @sc{Fweb} macros.
* Tokens::              Special tokens used in @sc{Fweb} macros.
* Built-in functions::  Macro-like functions built into @sc{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 @sc{Fweb} macros

@quotation
@itemize @bullet
@item 
Fundamentally, @sc{Fweb} macros follow the syntax for ANSI C.  There are
also a few extensions, notably the possibility of variable (optional) arguments
(see next item) and some additional preprocessing tokens
(@pxref{Tokens}).

@item
@cindex Macros, with variable arguments
@cindex Variable arguments
@sc{Fweb} macros with a variable number of arguments are indicated by an ellipsis,
as in

@example
@@m VAR(x,y,z,...) text
@end example

@item
Adjacent strings in macro text are automatically concatenated.
@end itemize
@end quotation

@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 @sc{Fweb} macro
definitions:

@subsubsection ANSI C-compatible tokens

@example 
 ##          --- Paste tokens on either side to form a new identifier.
 #parameter  --- 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); // Expands to `int _fcalc();'
TRACE(predictor); // Expands to `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 to use the other extensions
sparingly; 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.

@example
 #*parameter --- Like #parameter, but pass a quoted string through unchanged.
 #!parameter --- Don't expand argument.
 #'parameter --- Convert parameter to a single-quoted string (no expansion).
 #"parameter --- Convert parameter to a double-quoted string (no expansion).
 #0          --- Number of variable arguments.
 #n          --- n-th variable argument, counting from 1.
 #@{0@}        --- Like #0, but the argument may be a macro expression
                 known at run time.
 #@{n@}        --- Like #n, but the argument may be a macro expression.
 #[0]        --- The total number of arguments (fixed + variable).  (The
                 argument inside the brackets may be a macro expression.)
 #[n]        --- The n-th argument (including the fixed ones), counting
                 from 1.  (The argument inside the brackets may be a
                 macro expressions.)
 #.          --- Comma-separated list of all variable arguments.
 #:0         --- Unique statement number (expanded in phase 1).
 #:nnn       --- Unique statement number for each invocation of this
                 macro (expanded in phase 2).
 #<          --- Begin a module name.
 #,          --- Internal comma; doesn't delimit macro argument.
@end example

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 more often 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
@sc{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 @sc{Fweb} design, built-in functions began with an
underscore.  This usage conflicts with the conventions for reserved
words in ANSI C.  In fact, in most (but not all!) @sc{Fweb} currently
understands built-in 
function names that begin with either a dollar sign or an underscore.
If you don't like the underscore convention for some name, you can
undefine it, as in
@cindex Underscores

@example
@@#undef _A
@end example
@noindent
However, @emph{Please do not use the underscore version of these names
for new code, 
and convert old code to use the dollar-sign form.  The underscore
version will disappear in future releases (and some such as @samp{_IF}
and @samp{_DEFINE} have disappeared already)!} 

@emph{No user-defined macro should begin with an underscore or a dollar
sign!}  It might interfere with the functioning of some internal
built-in function.

@menu
* $A::                  Convert to ASCII.
* $ABS::                Absolute value.
* $ASSERT::             Assert a condition.
* $COMMENT::            Generate a comment.
* $DATE::               Today's date.
* $DAY::                Today.
* $DECR::               Decrement a macro.
* $DEFINE::             Define a 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.
* $HOME::               The user's home directory.
* $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.
* $L::                  Change string to lower case.
* $LANGUAGE::           Identifier for current language.
* $LANGUAGE_NUM::       Number of current language.
* $LEN::                Length of string.
* $LOG::                Natural logarithm.
* $LOG10::              Logarithm to the base 10.
* $M::                  Define a 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.
* $OUTPUT_LINE::        Current line number of tangled output.
* $P::                  The C preprocessor symbol '#'.
* $PI::                 3.14159...
* $POW::                Raise to a power.
* $ROUTINE::            Current Ratfor program, function, or subroutine.
* $SECTION_NUM::        Number of current section.
* $SECTIONS::           Maximum number of sections.
* $SQRT::               Square root.
* $STRING::             Expand argument, then stringize.
* $STUB::               
* $TIME::               The local time.
* $TRANSLIT::           Transliterate a string.
* $U::                  Change string to upper case.
* $UNDEF::              Undefine an @sc{Fweb} macro.
* $UNQUOTE::            Remove quotes from string.
* $VERBATIM::           (Obsolete.)
* $VERSION::            @sc{Fweb} version number.
@end menu

@node $A,$ABS,Built-in functions,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{AT"}.)
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,$COMMENT,$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 @sc{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 $COMMENT,$DATE,$ASSERT,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
@sc{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,$DAY,$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 $DAY,$DECR,$DATE,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 @sc{Fweb} macro command @code{@@m}, but
it is intended to appear in the 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 @file{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 @code{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 @sc{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 @samp{$DUMPDEF($UNROLL(0,5,1))}, it will respond
that @code{$UNROLL} is not an @sc{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 @sc{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 @sc{Fweb} may mysteriously stop working.

@node $E, $ERROR, $DUMPDEF, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$E}: Base of 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(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 @sc{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 @sc{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, $HOME, $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(@i{name})} returns a string consisting of the current
value of the environment variable @i{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 $HOME,$IF,$GETENV,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 $IF,$IFCASE,$HOME,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 @samp{$IF(expr, action-if-true, action-if-false)}.
The @i{expr} is an @sc{Fweb} macro expression that must reduce to 0
(false) or 1 (true).  First that argument is expanded.  If it is true,
@code{action-if-true} is expanded; otherwise @code{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 @sc{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 @samp{$IFCASE(expr, case-0, case-1, ..., case-n-1, default)}.
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) => `two'
$IFCASE(2, zero, one, three) => `three'
$IFCASE(2, zero, one) => `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 @samp{$IFDEF(macro, action-if-defined, action-if-not-defined)}.

@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(macro, action-if-not-defined, 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(expr1, expr2,
action-if-equal, action-if-not-equal)}.  The expansions of @samp{expr1}
and @samp{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{@i{N}++}.

The two-argument form @samp{$INCR(@var{N,m})} executes the equivalent of
@samp{@i{N} += @i{m}}.

@node $INPUT_LINE,$L,$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 $L,$LANGUAGE,$INPUT_LINE,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(@i{string})} changes @i{string} to lower case.  The argument is
first expanded in case it is a macro.

@node $LANGUAGE,$LANGUAGE_NUM,$L,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:

@example
Language    $LANGUAGE
 C             $C
 C++           $CPP
 Fortran       $N
 Fortran-90    $N90
 Ratfor        $R
 Ratfor-90     $R90
 TeX           $X
 VERBATIM      $V
@end example

@noindent
Note that this outputs identifiers, not @sc{Fweb} macros.  They are intended
to be used in @code{$IF} or @code{$IFELSE} statements such as

@example
$IF($LANGUAGE==$C, C-text, 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:

@example
Language  $LANGUAGE_NUM
 C             0
 C++           1
 Fortran       2
 Fortran-90    3
 Ratfor        4
 Ratfor-90     5
 TeX           6
 VERBATIM      7
@end example
 
@noindent
This built-in is useful in conjunction with an @code{$IFCASE}
construction; see @ref{$IFCASE}.

@node $LEN, $LOG, $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(@i{string})} returns the length of @i{string} in bytes.  If
@i{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.

@node $LOG, $LOG10, $LEN, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$LOG}:  Natural logarithm

@findex $LOG
@cindex Logarithms, natural
@samp{$LOG(@i{x})} returns the natural logarithm of @i{x}.

@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 the logarithm to the base 10 of @i{x}.

@node $M, $MAX, $LOG10, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$M}:  Define a 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,$OUTPUT_LINE,$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 $OUTPUT_LINE,$P,$MODULES,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
@samp{$P} is a synonym for @samp{$UNQUOTE("#")} (@pxref{$UNQUOTE}).
It is useful for constructing @sc{Fweb} macro definitions that expand to
C preprocessor statements.  For example,

@example
@@m CHECK(flag)
        $P if(flag)
                special code;
        $P endif
@end example

        
@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 
@ifinfo
@var{pi}
@end ifinfo
@tex
$\pi$
@end tex
to the default machine
precision.  The expression @samp{$PI(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, $ROUTINE, $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} and the exponentiation
operator.) 

@node $ROUTINE,$SECTION_NUM,$POW,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 @sc{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,$SQRT,$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
@sc{Fweave}.

@node $SQRT, $STRING, $SECTIONS, 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 $STRING, $STUB,$SQRT, 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, @sc{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(@i{s}, @i{from}, @i{to})} interprets each of
its arguments 
as strings (without expanding anything). Then @samp{s} is modified by
replacing any of the characters found in @samp{from} by the
corresponding characters in @samp{to}. If @samp{to} is shorter than
@samp{from}, then the excess characters in @samp{from} are deleted from
@samp{s}. As a limiting case, if @samp{to} is empty, then all the
characters in @samp{from} are deleted from @samp{s}. For example,
@samp{$TRANSLIT(s, aeiou, 12345)} replaces the vowels in @samp{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 @sc{Fweb} macro.

@node $UNQUOTE,$VERBATIM,$UNDEF,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$UNQUOTE}:  Remove quotes from string

@findex $UNQUOTE
@cindex Strings, unquoting
@samp{$UNQUOTE(@i{string})} returns @i{string} without its surrounding
quotes.  (However, the resulting construction is still treated as a
string; no macro expansion is done.)

@node $VERBATIM,$VERSION,$UNQUOTE,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 @sc{Fweb} version number

@findex $VERSION
@cindex Version, of FWEB
@samp{$VERSION} returns a string built out of the @sc{Fweb} version
number, such as @code{"1.50"}.

@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 @sc{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.  @sc{Fweb} deals with the line-number problem
that arises here automatically; see @ref{-T#}.

@node Preprocessing,,FWEB macros,Macros
@comment  node-name,  next,  previous,  up

@section Preprocessing

@cindex Macros, preprocessing
@cindex Preprocessing
Generally, the @sc{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 @sc{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 @sc{Fweb} macro expands to more than one
output line; see @ref{Debugging with macros}.

The @sc{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:

@example
@@#line              --- Insert a @code{#line} command.

@@#define identifier --- Define an FWEB macro; equivalent to @samp{@@m}.
@@#undef identifier  --- Undefine an FWEB macro.

@@#ifdef identifier  --- Is FWEB macro defined?  Equivalent to
                         @samp{@@#if defined identifier}.
@@#ifndef identifier --- Is FWEB macro not defined?  Equivalent to
                         @samp{@@#if !defined identifier}.

@@#if expression
@@#elif expression
@@#else
@@#endif
@end example

In the @samp{@@#if} statement, the @i{expression} may contain @sc{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 @sc{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 @sc{Ftangle}.  (This was the
easy choice, not necessarily the most desirable one.)

The operators, listed from  highest precedence  to lowest, are as
follows (printed documentation only):

@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 @samp{@@\#ifdef A}, but one can use @samp{defined} in
expressions, as in 
$$
\hbox{@samp{@@\#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
@sc{Fweb} has the ability to work with more than one 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 @sc{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 @sc{Ftangle} and
@sc{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 making the tangled
output relatively unreadable) and @sc{Fweave} pretty-prints using the C
syntax.  Turning on the N mode does not affect the language;
@sc{Ftangle} copies the source code literally into @file{test.c} (no
blank compression or other modifications), and @sc{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 @sc{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::             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, 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 a
hyphenated option, and @i{options} have the same syntax as on the
command line.  The language symbols must be in lower case; they are

@example
C          --- c
C++        --- c++
Fortran-77 --- n
Fortran-90 --- n9
Ratfor-77  --- r
Ratfor-90  --- r9
TeX        --- x
VERBATIM   --- v
@end example

@noindent
Thus, for example,

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

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.

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
@sc{Ftangle} will write two output files for this example---e.g.,
@file{test.f} and @file{test.c}.

@section Special hints and considerations for each language

One important thing to keep in mind is that in @sc{Fweb} an identifier
may have, for each language, precisely one meaning throughout the
document.  See, for example, the discussions in @ref{Cpp} and @ref{Fortran}.

@node C, Cpp, Setting, Languages
@comment  node-name,  next,  previous,  up

@subsection Special considerations for C

@cindex C hints
@cindex Hints, C

@itemize @bullet
@item
@sc{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.

@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
Essentially, @sc{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 @sc{Fweave} imposes a few restrictions on one's programming
style.

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; however, @sc{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 @samp{Type} only as a formal template parameter, never as an
ordinary variable.

@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

@itemize @bullet
@item
For @sc{Fortran}-77, define symbolic statement names 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}ed 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
Don't use the column 1 @samp{C} commenting convention.  Use @samp{/*
... */} or @samp{// ...}.

@item
Use upper-case for I/O keywords such as @code{IOSTAT}.  The lower-case
forms are not recognized by default.  To permit lower-case, use
@samp{-k}. @xref{-k}.

@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

Special remarks.  (To be completed.)

@node Ratfor,Formatting,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}; @sc{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.

@menu
* Syntax: RSyntax.      Ratfor syntax.
* Commands::            Ratfor commands.
* Caveats::             Nuances about @sc{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; // Used with |case| or to break out of loops, as in C.
 case i: // Used with |switch|.
 default: // Used with |case|, as in C.
 do ...; @{...@} // Note the semicolon (unnecessary if followed by a compound stmt).
 else @{...@} // Used after |if| as in C.
 for(a;b;c) @{...@} // As in C.
 if(condition) @{...@}
 next; // Equivalent to C's |continue| statement; go to bottom of loop.
 repeat @{...@} until(condition); // Equivalent to C's |do @{...@} while();|
 return expression; // As in C.
 switch(expression) @{...@} // As in C.
 while(condition) @{...@} // Like C's |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 @sc{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 program
unit; it is added automatically by @sc{Fweb} when the closing brace is sensed.
@end enumerate
@end quotation


@node Formatting,Customization,Ratfor,Top
@comment  node-name,  next,  previous,  up

@chapter FORMATTING

@cindex Formatting
@cindex Documentation format
@sc{Fweb} uses @TeX{} to format its documentation.  Either Plain @TeX{}
or La@TeX{} may be used.  @sc{Fweb}'s ``new look'' beginning with
Version 1.40 is very flexible, but works only with La@TeX{}.  Future
@sc{Fweb} development will be based on La@TeX{}; it will no longer be
guaranteed that applying Plain @TeX{} to the output of @sc{Fweave} will
work in all circumstances.

@menu
* Typesetting::         Woven output; TeX vs. LaTeX, etc.
* Pretty-printing::     Turning ugly input into beautiful output.
@end menu

@node Typesetting, Pretty-printing, Formatting, Formatting
@comment  node-name,  next,  previous,  up

@section Typesetting

@cindex Typesetting
@sc{Fweave} works in conjunction with either @TeX{} or La@TeX{}.  It is always
possible to create an adequately typeset document by processing with @TeX{}.
However, @sc{Fweb}'s ``new look'' (beginning with version 1.40) is designed
to work with La@TeX{}; it probably will not be retrofitted to @TeX{}
unless days become longer than 24 hours.  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 consecutively by specifying the La@TeX{}2e package
@code{fwebnum}; see @ref{Numbering}.

To inform @sc{Fweave} you will be using La@TeX{} as the formatter, you
need to do nothing special; just say @samp{@sc{Fweave} test}.  You could
also say @samp{@sc{Fweave} -PL test}, but beginning with version 1.50
La@TeX{} is the default processor.  

To inform it you will be using @TeX{}, say @samp{@sc{Fweave} -PT test}.
If you will always be using the @TeX{} processor, you should probably
put something like @samp{-PT} into your @file{.fweb} file
(@pxref{Initialization}).  But remember, Plain @TeX{} is no longer
supported!


@menu
* Output::	Structure of the TeX output from @sc{Fweave}.
* fwebmac.sty:: The macro package used with @sc{Fweave}.
* LaTeX::	Specifics of the LaTeX support.
@end menu

@node Output,  fwebmac.sty, Typesetting,  Typesetting
@comment  node-name,  next,  previous,  up

@subsection @sc{Fweave}'s OUTPUT

When one says @samp{@sc{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 @sc{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 (sets up the environment for @TeX{} or La@TeX{}).

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
@sc{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.

@sc{Fweave} usurps various common single-character macros such as @samp{\.} for
its own purposes; these are @samp{\let} equal to alternative commands
such as @samp{\period}.  In version 1.50, the following commands 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 in addition to the ones of Plain @TeX{}.
These include @samp{\titlefont} (large sans serif), @samp{\ttitlefont}
(large typewriter), @samp{\SC} (small caps), @samp{\Csc} (Caps/small
caps), and @samp{\tentex} (@TeX{}'s extended character set).  For
illustrations and further details, see @file{fwebmac.web}.

To typeset a string of characters in typewriter type, one may use the
@samp{\.} macro.  When using this, one must escape the special
characters @samp{ \#%$^_@{@}~&}, as in @samp{\.@{\\alpha@}}.  (@sc{Fweave}
does that escaping automatically when typesetting strings in code mode.)
You may wish to surround @samp{\.@{...@}} with an @samp{\hbox}; this is
not done by default because @sc{Fweave} uses special trickery to break
long strings in code mode automatically.

@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 @sc{Fweb}'s @TeX{} support.  However, beginning
with version 1.40, full La@TeX{} support is provided; 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, @sc{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.
* Sections::	        Section numbering, spacing, etc.
* Index::               Technical details about multi-columns and the Index.
* Table of Contents::   The Table of Contents.
* Customizing LaTeX::   Conditional flags, etc.
@end menu

@node Document class, Sections,  LaTeX, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection La@TeX{}'s document class

@findex \documentclass
An @sc{Fweb}/La@TeX{} document is set up with the @samp{\Wbegin}
command, issued automatically by @sc{Fweave}.  See the summary at the
end of this section for the essence of what the @samp{\Wbegin} command
accomplishes.  

@sc{Fweave} uses @code{\documentclass@{article@}} by default.  In
principle, the
document class can be changed by the @sc{Fweb} style-file option
@samp{LaTeX.class}; see @ref{Fwebmac params}.  However, @emph{@sc{Fweave} has
not been tested with other document classes}.

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
cutting down on white space), say

@example
LaTeX.package "indentfirst,multicol"
@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 (enpty by
default).  Those commands are processed immediately before
@samp{\begin@{document@}}.  One use of @samp{doc.preamble} is to inhibit
@sc{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 @sc{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 Sections,  Index, Document class,  LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection Sections in La@TeX{}

@cindex La@TeX{} section
@findex \section
@findex \subsection
@findex \subsubsection
@sc{Fweb}'s sectioning commands (@samp{@@*}, @samp{@@*@i{n}}, and
@samp{@@ }) 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 @samp{@@ } 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 Index, 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{} @sc{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 this
is loaded by means of the style-file statement @samp{LaTeX.package
"multicol"}, then any text 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, Index, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection La@TeX{}'s Table of Contents

@cindex Contents, table of
@cindex Table of Contents
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 @sc{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
@sc{Fweb}'s @code{\Title} macro instead of @code{\title}:

@example
\Title@{MYCODE.WEB@}
\author@{My name@}
\date@{January 1, 2001@}
@end example
By default, @sc{Fweave} uses (in the @samp{\Wbegin} macro)
@example
\title@{@}%
\author@{@}%
\date@{\today\\[3pt]\Time@}%
@end example

In La@TeX{}2e, using the @code{\Title} macro allows one to have separate
appearances for the title on the title page and on the page headers.
By default, both of those are printed in an appropriately sized
typewriter font.  However, an optional argument permits one to override
the appearance of the title-page title.  Say

@example
\Title[@i{font-commands}]@{My title@}
@end example
@noindent
to have the @i{font-commands} act on the title for the title-page only.

@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,  ,  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
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 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 @sc{Fweave}'s output contains
several pieces of information:  the current section name or document
title; the page number; the range of La@TeX{} section numbers on the
page (these are preceded by the @samp{\S} symbol); and the range of
integer section numbers as understood internally by @sc{Fweave} (these
are in square brackets and preceded by the @samp{#} sign).

@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 @sc{Fweb} commands @samp{@@*} and @samp{@@ } 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 @sc{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 Pretty-printing, , Typesetting, Formatting
@comment  node-name,  next,  previous,  up

@section Pretty-printing

@cindex Pretty-printing
@dfn{Pretty-printing} refers to @sc{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}).

(More...)

@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 @sc{Fweave}'s formatting, but are invisible on output; they
are ignored by @sc{Ftangle}.  The pseudo-operators are

@example
@@e --- pseudo-expression.  @xref{ATe}.
@@; --- pseudo-semicolon.  @xref{AT;}.
@@: --- 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

@sc{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 @sc{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,
@sc{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, 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 @sc{Fweave} with a
macro-processing facility analogous to that of @sc{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, new with version~1.30, 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 @sc{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, this isn't here
yet), where an example is given.


@node Customization, Hints, Formatting, Top
@comment  node-name,  next,  previous,  up

@comment  node-name,  next,  previous,  up
@chapter CUSTOMIZATION

@cindex Customization
@cindex Customizing @sc{Fweb}
@cindex @sc{Fweb}, customizing
The default behavior of @sc{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.  The style file does not contain command-line
options; rather, it contains parameter settings that override
@sc{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}.  @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 and @samp{-p} options from the command line.

@end enumerate
@end quotation

@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_INCLUDES} --- Colon-delimited list of directories to search for
include files.  (One can append to this list by means of the
@samp{-I} option; 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 @sc{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 @sc{Fweb}, initializing
@findex .fweb
On startup, @sc{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.
  
@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 you 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}.

@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 @sc{Ftangle}.
* -ykw::        Stack size for @sc{Fweave}.
* -yll::        Line length for @sc{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 @sc{Fweb} macros.
* -ymb::        Size of the buffer for expanding @sc{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 @sc{Ftangle} can process.
* -ytw::        Maximum number of tokens in the current section being
                        processed by @sc{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

@sc{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 @sc{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 @sc{Ftangle}

@findex -ykt

@sc{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 @sc{Fweave}

@findex -ykw

@sc{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 @sc{Fweave}'s output, in bytes

@findex -yll

@samp{-yll} controls the length of each line in the @code{.tex} file
output by @sc{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 @code{x(i) +=
dx} into their @sc{Fortran} counterparts such as @code{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 @sc{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 @sc{Fweb} macros

@findex -yma

The maximum number of arguments to @sc{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 @sc{Fweb} macros

@findex -ymb

The expansion of each @sc{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 @sc{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
simulaneously.  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 @sc{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 @sc{Ftangle} can process

@findex -ytt

A @dfn{token} is an identifier, numerical constant, operator, etc.
@sc{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 @sc{Fweave}.

@findex -ytw

Unlike @sc{Ftangle}, @sc{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 @sc{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 @sc{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, these 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
        keyword [=] 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'
@end example
@noindent
The syntax is completely free-form.  Periods within keywords are
precisely equivalent to underscores, but are useful for associating a
structure-like hierarchy to some of the commands.

Unfortunately, the descriptions of the parameters aren't all completed
yet.  To query the default values, say @samp{ftangle -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 @sc{Fweb}'s macros.
* Completion params::           Automatic selection of file extensions, etc.
* Control-code mappings::       Remapping @sc{Fweb}'s control codes (danger)!
* Miscellaneous params::        Other customizations.
@end menu

@node Index params,Module params,Style,Style
@comment  node-name,  next,  previous,  up

@subsection  Customizing @sc{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
@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

@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}.

@code{index.preamble} are @TeX{} commands that begin the Index.

@code{index.postamble} are @TeX{} commands that end the Index.

@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{?}}

@code{delim_0} is the string to insert after the identifier in an index
entry.

@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}

@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}

@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{???}}

@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{???}}

@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{???}}

@code{underline.prefix} is the @TeX{} command to begin an underlined
index entry.

@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

@code{modules.tex} is the name of the file into which the module names
are written.

@code{modules.preamble} is a string of @TeX{} commands to begin the list
of modules.

@code{modules.postamble} is a string of @TeX{} commands to end the list
of modules.

@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

@code{contents.tex} is the name of the file into which the Table of
Contents is written.

@code{contents.preamble} is the @TeX{} string that begins printing the
Table of Contents.

@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 @sc{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 @sc{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

@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 @sc{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.
* format.reserved: S_format.
* format.short_identifier: S_format.
* format_OUTER_MACRO: S_format.
* format.outer_macro: S_format.
* format_WEB_MACRO: S_format.
* format.WEB_macro: S_format.
* format.intrinsic: S_format.
* format_KEYWORD: S_format.
* format.keyword: S_format.
* format.typewriter: S_format.
* format.wildcard: S_format.

* 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} fields specify the macro to use to pretty-print
various kinds of identifiers.  One can see their default values by
typing @samp{ftangle -Zformat.}.


@node S_indent, S_LaTeX, S_format, Fwebmac params
@comment  node-name,  next,  previous,  up

@subsubsection @code{indent.@i{???}}

@code{indent.TeX} specifies paragraph indentation for the @TeX{} part.

@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{???}}

When running under La@TeX{} prior to La@TeX{}2e, 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, Miscellaneous params, 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 Miscellaneous params,,Control-code mappings,Style

@comment  node-name,  next,  previous,  up

@subsection Miscellaneous style-file parameters

There are a variety of miscellaneous parameters.

@menu
For @sc{Ftangle}:

* ASCII_fcn::                   Routine for converting strings to ASCII.
* cchar::                       Continuation character for Fortran.
* cdir_start::                  @samp{@?} translates to this.
* line_char: S_meta_t.          Comment char. for @sc{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.

* outer.def: S_outer.           @sc{Ftangle} converts @samp{@@d} to this.
* outer.undef: S_outer.         @sc{Ftangle} converts @samp{@@u} to this.

* protect::                     Protection character to end a continued line.
* suffix::                      Suffixes for output files.

For @sc{Fweave}:

* macros::                      Default name of the macro package to be
                                        read in by @sc{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 @sc{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}

@xref{AT"}.

@node cchar, cdir_start, ASCII_fcn, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{cchar}

Continuation character for @sc{Fortran} code output.

@node cdir_start, S_line_length, cchar, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{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 S_line_length, S_meta_t, cdir_start, Miscellaneous params
@comment  node-name,  next,  previous,  up

@node S_meta_t, S_outer, S_line_length, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{meta.@i{???.?}} (@sc{Ftangle})

@code{meta.top.@i{l}} specifies text that precedes material enclosed by
@samp{@@(...@@)}. 

@code{meta.prefix.@i{l}} begins each line of the meta-comment.

@code{meta.bottom.@i{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{???}}

@sc{Ftangle} converts @samp{@@d} to @code{outer.def}, and @samp{@@u} to
@code{outer.undef}.

@node protect, suffix, S_outer, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{protect.?}

The strings @code{protect.@i{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.?}

The extension for the files output by @sc{Ftangle} is specified by
@code{suffix.@i{l}}.


@node macros, S_limbo, suffix, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{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}

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

Similarly, @samp{limbo.end} is printed at the end of the limbo section.

Thus, the beginning of the file output by @sc{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{Index}.

@node S_meta_w, S_preamble, S_limbo, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{meta.@i{???}} (@sc{Fweave})

(To be finished.)

@node S_preamble, S_dot_constant, S_meta_w, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{preamble.@i{???}}

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{???.?}}

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.@i{l}} and
@code{dot_constant.end.@i{l}}.

@node null_file, , S_dot_constant, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{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.change: S_ext.     Extensions for the change file.
* ext.hweb: S_ext.       Extensions for include files.
* ext.hchange: 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

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 @sc{Fweb}.

@menu
* Converting::          Converting an existing code to @sc{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 @sc{Fweb}

@cindex Converting an existing code to @sc{Fweb}
@cindex Code, converting to @sc{Fweb}
To convert an existing code to @sc{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}.

@item
Place an @samp{@@a} command before each program unit (e.g., main
@b{program}, @b{subroutine}, or @b{function}).

@item
Before each @samp{@@a}, place an @samp{@@*} or @samp{@@ } 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 @samp{@@ } 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 @sc{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 @sc{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.

@end enumerate

@node Tips, Science, Converting, Hints
@comment  node-name,  next,  previous,  up

@cindex Suggestions
@cindex Programming tips

@section Programming tips and other suggestions

@emph{This section will be enlarged in the future!}  Meanwhile, please feel
free to contact @samp{krommes@@princeton.edu} for help and advice, and to
suggest items to include here.

@enumerate

@item
Read the @sc{Fweb} FAQ, available on the World Wide Web from 

@quotation
@code{http://www.arsc.sunyit.edu/fwebdocs/fweb.html}
@end quotation

@item
Periodically check @code{ftp.pppl.gov:/pub/fweb/READ_ME} for bug
reports and other news.  Make bug reports!  @xref{Support}.

@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 @sc{Fweb} tables (control codes,
reserved words, memory allocations, and style-file parameters).
@xref{Info options}.

@item
Begin all @sc{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.

@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 @sc{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 @sc{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-man'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{}, not Plain @TeX{}; upgrade to La@TeX{}2e as soon as
possible.  @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

@sc{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.

@menu
* V1.53::
* V1.52::
* V1.50::
* V1.40::
@end menu

@node V1.53, V1.52, New features, 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 @sc{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 @sc{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{Index} 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 @sc{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
@sc{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 @sc{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
@sc{Fweave}'s processing of @b{typedef} statements in C and C++ was
improved. 

@item
@sc{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.}  @sc{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 @xref{-B_}.

@end enumerate
@end quotation

@node Support, Concept index, New features, Top
@comment  node-name,  next,  previous,  up

@chapter SUPPORT

@cindex Support
@cindex Bugs
@sc{Fweb} is supported by John Krommes, @samp{krommes@@princeton.edu}.
This project is a definitively @emph{spare-time activity}!!!  Bug
reports submitted 
with very short test files will be verified.  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
other professional obligations.

Suggestions are very welcome.  Many of @sc{Fweb}'s current features were
incorporated in response to users' requests.  However, the queue for
future improvements is long; nothing may happen immediately.

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

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

The FWEB-FAQ can be found in 
@ifhtml
<A href="http://www.arsc.sunyit.edu/fwebdocs/fweb.html>fweb-faq</A>,
@end ifhtml

@quotation
@code{http://www.arsc.sunyit.edu/fwebdocs/fweb.html}.
@end quotation

You may subscribe to one or both of two @sc{Fweb} mailing lists,
@code{fweb-users} and @code{fweb-installers}.  To subscribe, send e-mail
to @code{majordomo@@pppl.gov}.  In the 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.

@node Concept index, Option and function index, Support, Top
@comment  node-name,  next,  previous,  up

@unnumbered Concept index

@printindex cp

@node Option and function index, , Concept index, Top

@unnumbered Option and function index

@printindex fn

@shortcontents
@contents

@bye
