\input texinfo   @c -*-texinfo-*-
@setfilename fweb.info
@settitle FWEB

@ifinfo
     This file documents FWEB...
     
        Copyright 1993 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 John A. Krommes
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993 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

@syncodeindex fn cp

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

@ifinfo
@chapter FWEB

This info browser for @sc{fweb} is a ``work-in-progress''.  The previous
large @sc{fweb} user manual (which was built in large measure from an
early version of Levy's @sc{cweb}) is presently frozen at version 1.30.
One can obtained a TeX'd copy of the present documention by saying
@samp{tex fweb.texinfo}.

   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. 

   This Texinfo documentation describes @sc{fweb} Version 1.40, which
initiates a major upgrade project.  This version contains significant
improvements and new features, both visible and invisible to the user.
@strong{THERE WILL BE BUGS.}  If you are involved in a large programming
project dependent on @sc{fweb}, it is not recommended that you upgrade
this version unless you have a need for specific bug fixes.  Versions
1.4? are not intended for new users, but only for very patient friends.
@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.
* Index::

 --- 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::          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.
* -L: -L_.      Select global language.
* -l::          Echo the input line.
* -m::          Define a WEB macro.
* -m4::         Understand the m4 built-in commands.
* -m;::         Append pseudo-semicolons to WEB macro definitions.
* -n::          Set global language to Fortran--77.
* -n9::         Set global language to Fortran--90.
* -n;::         For Fortran--77, supply semicolons automatically (default).
* -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 commands for @sc{ftangle}.

* -TD::                Permit processing of deferred macro definitions.
* -T%::                Don't retain trailing comments.

@samp{-W}:  Flag-setting commands for @sc{fweave}.

* -W[::                 Turn on processing of bracketed array indices.
* -Wdflmvw::             Don't print various things in woven output.

WEB 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 a WEB macro.
* @@m: ATm.      Define a WEB 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.
* @@/: AT/.         Insert a line break.
* @@|: 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).
* WEB macros::          Macros expanded by @sc{fweb} (@@m).
* Preprocessing::       @sc{fweb}'s preprocessing language (@@#if etc.)

WEB macros

* Macro features::      Various points about WEB macros.
* Tokens::              Special tokens used in WEB macros.
* Built-in functions::  Macro functions built into @sc{fweb}.

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 @code{DO} loop.
* $DUMPDEF::            Dump macro definitions to the terminal.
* $E::                  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 @sc{web} module.
* $MODULES::            Total number of independent modules.
* $OUTPUT_LINE::        Current line number of tangled output.
* $P::                  The C preprocessor symbol @code{'#'}.
* $PI::                 3.14159...
* $POW::                Raise to a power.
* $ROUTINE::            Current @sc{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 a @sc{web} 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.

RATFOR

* Commands::            Ratfor commands.
* Caviats::             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}.
* LaTeX::	Specifics of the LaTeX support.

La@TeX{} support

* Document style::	LaTeX's document style, options, etc.
* Sections::	        Section numbering, spacing, etc.
* Table of contents::   The table of contents.
* Customizing LaTeX::   Conditional flags, etc.

Customizing La@TeX{}'s output

* Page references::     Indexing by page numbers.
* 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.
* -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{web} macros.
* -ymb::        Size of the buffer for expanding @sc{web} macros.
* -yn::         Maximum number of identifiers, strings, and module names.
* -ynf::        Maximum number of open input 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 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 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 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.

* 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

* format.reserved: S_format.
* format.short_identifier: S_format.
* format.outer_macro: S_format.
* format.WEB_macro: S_format.
* format.intrinsic: 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.options: S_LaTeX.       Set options for document style.
* LaTeX.style: S_LaTeX.         Specify document style.

Miscellaneous style-file parameters

* ASCII_fcn::                   Routine for converting strings to ASCII.
* cchar::                       Continuation character for Fortran.
* cdir_start::                  @samp{@?} translates to this.
* line_length: S_line_length.

* 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::                       Default material to begin the limbo part

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

@sc{fweb} is a system for ``literate programming''.  
@cindex Literate programming
It was originally intended for scientific programming, 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, Ratfor, and @TeX{}.  It also supports a WYSIWYG
language-independent mode as well as a (closely-related but not
identical) verbatim `language'.

The origins of literate programming are described in the very enjoyable
book by D. E. Knuth, ``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 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 an early version 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.

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

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

@section @sc{fweb} features

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

@item
@sc{fweb} understands the syntaxes of several of the more important
compiler languages:  C, C++, Fortran, 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 Ratfor (RATional FORtran) translator.
@xref{Ratfor}. 

@item
@sc{fweb} has a built-in C-like macro preprocessor, which should be
especially useful for Fortran and Ratfor.
@xref{Macros}, @ref{Preprocessing}.

@item
Many aspects of @sc{fweb}'s behavior can be customized by means of setting
parameters in a style file.
@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

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 be
processed with @TeX{} or La@TeX{}.  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

An @sc{fweb} source file is structured into sections.  
@cindex Sections
Each section consists of three (optional) parts: 
@cindex Parts
the

@enumerate
@item
@TeX{} part;

@item
definition part; and

@item
code part.
@end enumerate

@noindent
Sections 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 two sections is as
follows:

@example
@@n

@@* INTRODUCTION. 
This code is intended...

@@m PI 3.14159

@@a
        program main
        call compute
        end

@@ The computational routine is pretty boring.
@@a
        subroutine compute
        write(*,*) 'pi = ', PI
        end
@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 Fortran-77.  For more information about languages,
see @ref{Languages}.

The @samp{@@*} command begins a major 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{@@*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.  

Minor sections are begun by @samp{@@ }; these have no associated names
and are not entered into the table of contents.

All sections begin with @TeX{} commentary.  This 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}, @samp{@@W}.
In the example, the first section has a
definition part consisting of one macro definition (@samp{@@m}); the
second section has no definition part.

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 `in limbo' or `the limbo
part'.  The only @samp{@@} commands that are allowed in limbo (in
addition to @samp{@@@@}, which is allowed anywhere) are the
language-changing commands, and one of those 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 style file @file{fwebmac.sty}.
(Another way of getting @TeX{} text into the limbo part is by means of
the @samp{@@l} command; see @ref{ATl}.)

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

@section Modules

Sections can be combined into modules.  
@cindex Modules
Modules can be named or unnamed. There is just one unnamed module.

@subsection The unnamed module

The unnamed module 
@cindex Unnamed module
is introduced by the command @samp{@@a}.  Subsequent
uses of @samp{@@a} accrete code to the unnamed module.
@emph{@sc{ftangle} outputs the unnamed module.}

@subsection Named modules

@cindex Named module
A module name is specified by

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

@noindent
Leading and trailing white space around the name text is ignored.

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 consists of the code from sections 2, 5, and 8, 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
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
This way, global variable definitions can be introduced as needed, 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.

@subsection The 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

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

@item
tokenizes source;

@item
expands @samp{@@'...'}, @samp{@@"..."}, and @samp{0b...} (in Fortran,
also @samp{0...} and @samp{0x...});

@item
stores code text in appropriate modules;

@item
memorizes macro definitions (@samp{@@d} and @samp{@@m}).  
@xref{ATd}, @xref{ATm}.  
@end itemize

Phase 2

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

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

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

@item
expands built-in macros (@pxref{Built-in functions});

@item
translates Ratfor statements.  @xref{Ratfor}
@end itemize

@subsection The 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 the cross-reference
information.  In phase 3, the index and table of contents are written.

More specifically, phase 1

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

@item
collects cross-reference information;

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

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

Phase 2

@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


@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 prefix end character.  Since this character differs for various
operating systems, it can be changed 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

@file{.fweb} --- Initialization file; always in the home directory.

@file{fweb.sty} --- Style file; in the directory of the @sc{web} file
   unless changed by 
   environment variable @code{FWEB_STYLE_DIR}.  The basic name can be
   changed by the @samp{-z} option (@pxref{-z}).

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

@file{name.ch} --- Change 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} --- Change file for include file.

@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

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

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

@file{CONTENTS.tex} --- Temporary file that accumulates
table-of-contents information. 

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

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

@file{name.ext} --- Compilable output file.

The names of the three temporary files can be changed with style-file
options.  @xref{Style}.
Commonly, one may put into the style file @file{fweb.sty} commands such as

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

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

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++            .cpp
 Fortran--77     suffix.N               .f              .for
 Fortran--90     suffix.N90             .f              .for
 Ratfor--77      suffix.R               .f              .for
 Ratfor--90      suffix.R90             .f              .for
 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

The primary input to the @sc{fweb} processors is the @file{test.web} source.
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 the 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}.

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

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

@chapter RUNNING @sc{fweb}

FWEB has a Unix-style command-line syntax.  There are many command-line
options, but most of these are unnecessary for standard appplications.

Commonly-used command-line options can be placed into the initialization
file @file{.fweb}. @xref{Options}.

@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

@example
ftangle-|
        | webfile[.web] [changefile[.ch]] [-option...]
fweave--|
@end example

@noindent
File names are anything that doesn't begin with a @samp{-}.  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 web file (source file); the second, if it exists, is
the change file.  [When no change file is specified, @sc{fweb} attempts
to read from the null file (@file{/dev/null} on Unix systems).  This
name should be specified when @sc{fweb} is installed, or can be set in
the style file.  @xref{null_file}.]

An option consisting of a lone hyphen stands for the special file name
@file{stdin}, which means `read from the standard input.'  (This option
should not be used except for very special effects.)

The web file is shown as required since one is normally processing a
source.  However, a few of the information options (@pxref{Info options})
will work even in the absence of a web file.

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

@section Command-line options

Command-line options may be put into the initialization file
@file{.fweb} (which is always in the user's home directory).
In that file, options beginning with a plus sign are processed before
the command-line options.  Otherwise, they are processed after the
command-line options.

@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::          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.
* -L: -L_.      Select global language.
* -l::          Echo the input line.
* -m::          Define a WEB macro.
* -m4::         Understand the m4 built-in commands.
* -m;::         Append pseudo-semicolons to WEB macro definitions.
* -n::          Set global language to Fortran--77.
* -n9::         Set global language to Fortran--90.
* -n;::         For Fortran--77, supply semicolons automatically (default).
* -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

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 is useful if an option such as  @samp{-v} is turned on in the
@file{.fweb} initialization file and you wish 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}).

This option tells @sc{fweave} to display irreducible scraps.  (Need
discussion somewhere of scraps.)

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

@subsection @samp{-2}:  Turn on verbose debugging mode (@sc{fweave}). 

This commands tells @sc{fweave} to display detailed reductions of the
scraps as it does the pretty-printing.  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 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.

This command supplies information about the @samp{@@} control codes:  it
shows the associated style-file parameters that can be used to remap the
codes, and it displays the precedence.  (Some codes may be used
anywhere; others begin  a new part.  Codes that begin the definition
part are labelled by @code{[D]}; codes that begin the code part are
labelled by @code{[C]}; codes that begin a new section are labelled by
@code{[S]}.)


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

@subsection @samp{-A_}:  Turn on ASCII translations.  

This command is used primarily for debugging.  @sc{fweb} works
internally with the ASCII character set.  If @sc{fweb} is run on a
non-ASCII machine, 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.

@sc{fweb} sometimes beeps the terminal for 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.

Number @b{do} and @b{if} blocks in woven Fortran and Ratfor output.

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

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

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

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

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

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

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

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

This option displays the list of reserved words for the language
currently in force.  Thus, to see the reserved words for 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 you say @samp{-Dabc}, you will get just the reserved words that begin with
"abc".

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

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

Obsolete.

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

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

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

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

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

When the @samp{-e} option is in effect, @sc{fweb} attempts to be helpful in
figuring out what file name you intend.  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.

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---e.g., @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 @file{make} files won't
recompile the output unless it really has to.

(Note that with this option in effect, if one used the Unix utility
@file{touch} to force processing of a group of files, but the @sc{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.)

The location of the temporary file as well as details of the renaming
procedure are determined by the automatic configuration script during
installation of the processors.  The script @code{./configure} 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 |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.

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

@subsection @samp{-f}:  Turn off module references for identifiers.

By default, @sc{fweave} gives certain entities such as function names a
section-number subscript to indicate where that function was defined.
The @samp{-f} command turns off the subscripting operation.

The subscript operations are further controlled by the settings of the
style-file parameters @code{mark_defined}.  @xref{S_mark_defined}.

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

@subsection @samp{-h}:  Get help.

This just prints a message saying where further help is available.

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

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

The fundamental search list for include files 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

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

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

@subsection @samp{-i}:  Don't print @samp{@@I} include files.

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 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 the time.

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

@node -i!,-L_,-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 -L_,-l,-i!,Options
@comment  node-name,  next,  previous,  up

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

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

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

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

The option @samp{-l[mmm[:nnn]]} echoes the input line 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.  It is often used to verify
that the input driver is inserting semicolons correctly.  For
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 WEB macro.

The command-line construction

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

@noindent
had appeared at the beginning of the web file.

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

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

This tells @sc{fweave} to properly format the reserved words of the @code{m4}
preprocessor.  The use of this preprocessor is @emph{not recommended}; use
@sc{fweb}'s built-in preprocessor instead.

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

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

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

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

@example
@@m SET(x,y) x=1; y=2@@;
@end example

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

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

@xref{Languages}, @ref{Fortran}.

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

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

@xref{Languages}, @ref{Fortran}.

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

@subsection @samp{-n;}:  Supply automatic semicolons (Fortran).

This is the default mode of operation in Fortran--77; the input driver
automatically appends a semicolon to each logical line of source code.
Since it's the default, you don't have to use it unless you wish to
negate it.  @xref{Negating options}.

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

@subsection @samp{-nb}:  Number @code{if}s and @code{do}s (Fortran).

In the woven output, extra comments are added to help one correlate the
block structure of the code.

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

@subsection @samp{-np}:  Print semicolons (Fortran).

Although the Fortran input driver automatically terminates logical lines
with semicolons so that the innards of @sc{fweave} can process them
correctly, the semicolons are by default not printed.  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.

In Fortran--90, this turns on free-form syntax and sets the continuation
character to be the backslash.  For example,

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

In the tangled output the backslash is converted into Fortran-90's
standard continuation character, the ampersand.

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

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

In Fortran--90, this turns on free-form syntax and sets the continuation
character to be the backslash.  For example,

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

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

@subsection @samp{-n/}:  Recognize short comments (Fortran).

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

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

@subsection @samp{-n!}:  Make @samp{!} denote short comment (Fortran).

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

@subsection @samp{-n)}:  Reverse array indices (Fortran)

This flag permits Fortran programmers to use C-style array indices.
Conversions such as the following are made:

@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
This feature permits convenient definitions of macros to deal with
multi-dimensional vectors.

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

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

(To be finished.)

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

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

@emph{(Obsolete.)}

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

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

Say @samp{-PT} or @samp{-PL} to inform @sc{fweave} that its output will be
processed by @TeX{} or La@TeX{}, respectively.  If you always use
La@TeX{}, it's easiest to put @samp{+PL} into the @file{.fweb}
initialization file.

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

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

This option can be used in the @file{.fweb} initialization file to
record style-file entries that are common to all runs.  This command
buffers up the entries.  They are effectively placed at the beginning of
the local style file, which is read after the command line is processed.
@xref{Style}.

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

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

@xref{Languages}, @ref{Ratfor}.

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

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

@xref{Languages}, @ref{Ratfor}.

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

@subsection @samp{-rg}:  Set @code{goto} parameters.

This obscure parameter is used for Ratfor (and really should be a
style-file parameter).  Please see the manual.

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

@subsection @samp{-k}:   Suppress comments about Ratfor translation.

By default, the Ratfor translator writes comments about what command it
is translating.  The @samp{-k} option suppresses those comments.  Arguments
to this command allows one to suppress comments about only particular
commands; please see the reference guide.

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

@subsection @samp{-K}:   Write comments about Ratfor translation.

This is the negative of @samp{-k}; it forces comments about particular Ratfor
commands. 

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

@subsection @samp{-r;}:  Turn on auto-semi mode (Ratfor).

Please don't use this command.  Insert semicolons by hand in your Ratfor
code.

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

@subsection @samp{-rb}:  Number @code{if}s and @code{do}s (Ratfor).

In the woven output, extra comments are added to help one correlate the
block structure of the code.

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

@subsection @samp{-r/}:  Recognize short comments (Ratfor).

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

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

@subsection @samp{-r!}:  Make @samp{!} denote short comment (Ratfor).

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

@subsection @samp{-r)}:  Reverse array indices (Ratfor)

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

@subsection @samp{-s}:  Print statistics.

@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{-smnnn} 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 commands for @sc{ftangle}.

This is a family of commands that set 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.
@end menu

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

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

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

By default, @sc{ftangle} attempts to be helpful and prints 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 is
in effect, since the header information includes a time stamp that would
defeat a successful file comparison.)

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

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

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, for @TeX{} comments that do not
begin a line are always retained unless the @samp{-T%} command is used.
This command has no effect for languages other than @TeX{}.

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

@subsection @samp{-t}:  Truncate identifiers.

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 Fortran, 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.

Particularly during @sc{Ratfor} expansion, certain output tokens such as
@samp{DO} are produced 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 macro.

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

@emph{CAUTION}:  This command 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.

By default, comments are not passed to the tangled output.  With @samp{-v},
all comments are included verbatim in the tangled output.

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

@subsection @samp{-W}:  Flag-setting commands for @sc{fweave}.

This is a family of commands that set flags appropriate only for @sc{fweave}.
Commands such as @samp{-W[} and @samp{-Wf} can be combined as @samp{-W[f}.

@menu
* -W[::                 Turn on processing of bracketed array indices.
* -Wdflmvw::             Don't print various things in woven output.
@end menu

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

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

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

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

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

@example
-Wd --- outer definitions
-Wf --- format statements
-Wl --- limbo text definitions
-Wm --- WEB macro definitions
-Wv --- operator overloads
-Ww --- identifier overloads
@end example

@noindent
When these commands are used, associated cross-referencing is suppressed
as well.

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

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

The command @samp{-w} means ``Don't print @samp{\input fwebmac.sty} as
the first 
line of the @file{.tex} output file.''  The command @samp{-wfname} means
``Print @samp{\input fname} as the first line.''

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

@subsection @samp{-x}:  Reduce cross-reference information.

Cross-reference information (for @sc{fweave}) includes the table of contents
('c'), the index ('i'), and the module list ('m').  The command @samp{-x}
eliminates all of that information.  The command @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.

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

@subsection @samp{-X}:  Print selected cross-reference information.

This command 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.

This command changes the default size for a dynamically allocated memory
buffer.  The buffers are indicated by a one- or two-character
abbreviation such as "op".  The command @samp{-yop200} allocates 200 units
for the "op" buffer.

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

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.

The command @samp{-Zabc} prints to the screen the default contents of the
style-file parameters beginning with "abc".  Just @samp{-Z} prints everything.

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

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

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

If this command is used, the processors will not understand that
constructions such as @samp{.LT.} are operators in Fortran or Ratfor.  This
command is useful if one is trying to modernize the source code to deal
with symbols such as @samp{<} instead of @samp{.LT.}.

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

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

(To be finished.)

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

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

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

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

Useful for Fortran and Ratfor.  Symbolic statement labels that are
defined with the @samp{#:0} macro command are incremented starting with
the default of 90000.  To change this to 789, say @samp{-:789}. 

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

@subsection @samp{->}:  Redirect output.

This changes the name of the output file.  If no name is given, output
is redirected to the terminal.

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

@subsection @samp{-=}:  Redirect output.

Equivalent to @samp{->}.

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

@subsection @samp{-#}:  Turn off comments about line and module numbers. 

By default, tangled output includes comments about the line and module
numbers corresponding to the current piece of code.  To eliminate this
clutter, say @samp{-#}.

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

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

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

Both Ratfor and 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{-+}.

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

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

If this command is not used, the @samp{//} construction will be interpreted
as concatenation.

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


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

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

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

@chapter WEB COMMANDS

All WEB 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 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 a WEB macro.
* @@m: ATm.      Define a WEB 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.
* @@/: AT/.         Insert a line break.
* @@|: 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

This cancels the effect of a previous @samp{@@1} or @samp{@@2}.
@xref{AT1}, @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

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

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

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

@section Literal control characters

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

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

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

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

In @TeX{} mode, @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 you want.)

In code mode, @samp{@@|} inserts an optional line break in an expression.

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

@section Beginning of section

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

@samp{@@ } begins a new minor (unstarred) section.  For example,

@example
@@ This is an example of a minor 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{@@*n}:  Begin major section.

@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

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

@samp{@@<} begins a module name, which has the form
@samp{@@< TeX text @@>}.  Module names inside @sc{web} macro definitions
begin with @samp{@@#}, not @samp{@@<}.

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

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

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

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

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


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

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

@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

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

@section Control codes b--z

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

(To be finished.  Useful only for very intimate debugging of @sc{web} codes.)


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

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

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

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

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

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

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

@subsection @samp{@@D}:  Define outer macro.

@emph{This command begins the definition part.}

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

@example
@@D A 1
@end example

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

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

@emph{This command begins the definition part.}

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

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

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

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

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

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.  These are
useful for dealing with macro constructions.

@example
$_BINOP_
$_COMMA_
$_EXPR
$_EXPR_
$EXPR_
$UNOP_
@end example

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

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

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

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.
@xref{Environment variables},
@ref{-I_}.

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

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

This commands 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},
@ref{-i!}.

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

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

@samp{@@Ll} sets the language to l, where l is one of
@code{@{c,c++,n,n9,r,r9,x,v@}}. 
@xref{Languages}.

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

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

(This command begins the definition part.)

Limbo text is material that @sc{fweave} should output before
the start of the first section.  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.
Sometime, 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 WEB macro.

@emph{This command begins the definition part.}

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

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

@subsection @samp{@@m}:  Define WEB macro, and mark.

@emph{This command begins the definition part.}

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

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

@subsection @samp{@@N}:  Turn on N mode

@emph{This command must appear before the code part.}

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, ``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 @code{\begin@{verbatim@}...\end@{verbatim@}} environment.

There are some subtleties with this mode (not to mention the likelihood
of bugs):

@enumerate
@item
@sc{web} 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 @code{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 Fortran,
cross-referencing of variables is done as usual.  However, if the
language is 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{@@+}.

@end enumerate

@node ATn, ATn9, ATN_, AT commands
@comment  node-name,  next,  previous,  up

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

@xref{Languages}.

@node ATn9, ATO_, ATn, AT commands
@comment  node-name,  next,  previous,  up

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

@xref{Languages}.

@node ATO_, ATo, ATn9, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@O}:  Open output file (global scope).

A statement of the form

@example
@@O newfile.c
@end example

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

This behaves like @samp{@@O}, except the new file name is in effect only
for the current section.

@node ATr, ATr9, ATo, AT commands
@comment  node-name,  next,  previous,  up

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

@xref{Languages}.

@node ATr9, ATu, ATr, AT commands
@comment  node-name,  next,  previous,  up

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

@xref{Languages}.

@node ATu, ATv, ATr9, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@u}:  Undefine outer macro.

@emph{This command begins the definition part.}

@samp{@@u} is the inverse of @samp{@@d}.  For example, in C it expands to
@samp{#undef}. 

@node ATv, ATW_, ATu, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@v}:  Overload operator.

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

@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

Please see the discussion of the @samp{@@z} command. @xref{ATz}.

@node ATy, ATz, ATx, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@y}:  Begin change material

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

@sc{fweb} files may begin with the construction

@example
@@z
.
.
@@x
@end example

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

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.

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 Fortran and Ratfor, it is converted to decimal; the
previous example would be output as @samp{65}.

If the native character set of your 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.

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

In Fortran and 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 @code{ASCII_fcn}.  @xref{ASCII_fcn}.

If the native character set of your 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

@subsection @samp{@@[}:  Mark as defined.

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

@node AT/*, AT//, AT[, AT commands
@comment  node-name,  next,  previous,  up

@section Comments

@subsection @samp{@@/*}:  Begin long verbatim comment.

The following comment is copied to the tangled output.  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.

See the discussion of @samp{@@/*}, above.

@node AT%, AT?, AT//, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@%}:  Ignorable comment.

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

@node AT?, ATlp, AT%, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@?}:  Begin compiler directive.

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.

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.

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.

This is for detailed debugging of @sc{fweb} codes.  It inserts a left
brace and suppresses the insertion of a breakpoint command.  @xref{ATb}.

@node AT_, AT-, ATlb, AT commands
@comment  node-name,  next,  previous,  up

@section Index entries

@subsection @samp{@@_}:  Force index entry to be underlined.

This command applies to the next identifier that appears after the
@samp{@@_}.  The index entry for that identifier will be underlined.  

This command is usually issued automatically.  For example, the index
entries for the variables @samp{i} and @samp{j} in the C statement
@code{int i,j;} will be underlined.

@node AT-, ATplus, AT_, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@-}:  Delete index entry.

This command applies to the next identifier that appears after the
@samp{@@-}; it prevents the index entry associated with that identifier
from being underlined.  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.

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

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

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

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
would 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

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

@section Control text

@subsection @samp{@@t}:  Put control text into a @TeX{} \hbox.

Control text is material terminated by @samp{@@>}; it must be all on one
line and must not contain any @samp{@@}s.  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.

For @sc{ftangle}, the command @samp{@@=controltext@@>} sends the control
text to the output exactly as input.  (`Control text' is defined in the
discussion of the @samp{@@t} command, @ref{ATt}.)
@sc{fweave} highlights the control
text by drawing a box around it.

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

@section Spacing

The spacing commands are used to refine @sc{fweave}'s pretty-printed
output.  Generally it's not necessary to bother with these until you're
putting the final touches on a code.  

@subsection @samp{@@,}:  Insert a thin space.

Extra spacings are sometimes necessary when working with unusual macro
constructions.  (Need an example here.)

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

@subsection @samp{@@/}:  Force a line break.

For example,

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

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

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

In @TeX{} mode, @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.

In code mode, @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.

@samp{@@#} forces a line break with some extra vertical white space.  Note
that blank lines in the source are significant, so this command should
seldom be necessary.

if @samp{@@#} is immediately followed by a letter, 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.

For example,

@example
printf("Working..."); @@~ fflush(stdout);
@end example

@node AT&, ATe, AT~, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@&}:  Join items.

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, @code{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 a @sc{web} macro.

@node ATe, AT;, AT&, AT commands
@comment  node-name,  next,  previous,  up

@section Pseudo (invisible) operators

@subsection @samp{@@e}:  Pseudo-expression.

@samp{@@e} is an invisible expression.  @xref{Pseudo-operators}.

@node AT;, ATcolon, ATe, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@;}:  Pseudo-semicolon.

@samp{@@;} is an invisible semicolon.  These are often used in C
programming to terminate a module name that expands to a compound
statement.  For example,

@example
@@c
@@a
if(flag)
        @@<Compound statement@@>@@;
else
        @@<Simple statement@@>;

@@
@@<Com...@@>=
@{
x;
y;
@}

@@
@@<Sim...@@>=
z
@end example

@xref{Pseudo-operators}.

@node ATcolon, AT!, AT;, AT commands
@comment  node-name,  next,  previous,  up

@subsection @samp{@@:}:  Pseudo-colon.

@samp{@@:} is an invisible colon.  @xref{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

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

@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

@example
@@z...@@x --- If a source or include file begins with @samp{@@z}, 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

@samp{/* ... */} is a long comment (may extend over several lines).

@samp{// ...} is a short comment (terminated by next newline).

@samp{@@(...@@)} is a meta-comment.  Meta-comments are a localized form
of the N mode.  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

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}) to format your comment appropriately.

@node Macros,Ratfor,Languages,Top
@comment  node-name,  next,  previous,  up

@chapter MACROS and PREPROCESSING

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

@node Outer macros,WEB 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{web}
macros are sometimes allowed in the code part as well; @ref{WEB macros}.


@section Outer macros

Outer macros are defined by @samp{@@d}.  These may be placed in any
definition part.  They are collected 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}.

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

@section WEB macros

WEB macros are defined by @samp{@@m}.  These should normally be placed in the
definition section.  They are collected during @sc{ftangle}'s phase 1 and
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{WEB} macros may be used in the code part as well; they are then
called 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. 

@sc{web} macros are often used in conjunction with the @sc{web}
preprocessor commands.  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 WEB macros.
* Tokens::              Special tokens used in WEB macros.
* Built-in functions::  Macro functions built into @sc{fweb}.
@end menu

@node Macro features, Tokens, WEB macros, WEB macros
@comment  node-name,  next,  previous,  up

@subsection Various features of WEB macros

@itemize @bullet
@item
WEB 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

@node Tokens, Built-in functions, Macro features, WEB macros
@comment  node-name,  next,  previous,  up

@subsection Special tokens

The following special tokens may be used in the text of WEB 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

@subsubsection Extensions to ANSI C macro syntax

(In the following list, the forms @samp{#@{n@}} and @samp{#[n]} may not
work correctly 
in complicated situations.  This is a design deficiency that will 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 teh 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

@node Built-in functions, $A, Tokens, WEB macros
@comment  node-name,  next,  previous,  up

@subsection Built-in functions

Built-in functions are essentially macros, but they sometimes implement
functions that a user could not define.  They all begin with a dollar
sign and are in upper case.

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

@example
@@#undef _A
@end example

@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 @code{DO} loop.
* $DUMPDEF::            Dump macro definitions to the terminal.
* $E::                  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 @sc{web} module.
* $MODULES::            Total number of independent modules.
* $OUTPUT_LINE::        Current line number of tangled output.
* $P::                  The C preprocessor symbol @code{'#'}.
* $PI::                 3.14159...
* $POW::                Raise to a power.
* $ROUTINE::            Current @sc{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 a @sc{web} 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.

@code{$A}(@i{string}) is the built-in equivalent of @code{@@'...'} or
@code{@@"..."}.  (See @pxref{ATquote} and @pxref{AT"}.)
Note the extra parentheses required by the built-in.

@node $ABS,$ASSERT,$A,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$ABS}:  Absolute value.

@code{$ABS}(@i{expression}) returns the absolute value of the macro
expression.

@node $ASSERT,$COMMENT,$ABS,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$ASSERT}:  Assert a condition.

@code{$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{web} macros required by
the code are properly initialized.  It must appear in the @emph{code
part} (not the definition part).

@node $COMMENT,$DATE,$ASSERT,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$COMMENT}:  Generate a comment.

@code{$COMMENT}(@i{string}) generates a comment in the output file.  

This built-in is sometimes useful in conjunction with the processing of
@sc{web} macros, since ordinary comments are removed when macros are
processed.

@node $DATE,$DAY,$COMMENT,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DATE}:  Today's date.

@code{$DATE} generates a string consisting of the date in the form
@code{"August 16, 2001"}.

@node $DAY,$DECR,$DATE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DAY}:  The day.

@code{$DAY} generates a string consisting of the day of the week, such
as @code{"Monday"}.

@node $DECR,$DEFINE,$DAY,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DECR}:  Decrement a macro.

@code{$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 @code{N--}.

The two-argument form @code{$DECR}(@var{N,m}) executes the equivalent of
@code{N -= m}.

@node $DEFINE,$DO,$DECR,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DEFINE}:  Deferred macro definition.

@code{$DEFINE} (to be finished).

@node $DO,$DUMPDEF,$DEFINE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$DO}:  Macro do loop.

@code{$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

Do not assume that the macro remains defined 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 only a single statement is to expanded.

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

@subsubsection @code{$DUMPDEF}:  Dump macro definitions to the terminal.

In the call @code{$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.

You can use this built-in to debug your own macros, or to find out the
secrets of @sc{fweb}'s built-ins.

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

@subsubsection @code{$E}: Base of natural logarithms.

The expression @code{$E} returns @var{e} to the default machine precision.
The expression @code{$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.

@code{$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.

@code{$EVAL}(@i{expression}) used @sc{fweb}'s expression evaluator 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.

@code{$EXP(x)} returns @var{e} to the power @var{x}.

@node $GETENV, $HOME, $EXP, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$GETENV}:  Get value of environment variable.

@code{$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.)

@node $HOME,$IF,$GETENV,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$HOME}:  The user's home directory.

@code{$HOME} is equivalent to @code{$GETENV(HOME)}.

@node $IF,$IFCASE,$HOME,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IF}:  Two-way conditional.

(To be finished.)

@node $IFCASE,$IFDEF,$IF,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IFCASE}:  n-way conditional.

@node $IFDEF,$IFNDEF,$IFCASE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IFDEF}:  Two-way conditional.

@node $IFNDEF,$IFELSE,$IFDEF,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IFNDEF}:  Two-way conditional.

@node $IFELSE,$INCR,$IFNDEF,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$IFELSE}:  Two-way conditional.

@node $INCR,$INPUT_LINE,$IFELSE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$INCR}:  Increment a macro.

@code{$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 @code{N++}.

The two-argument form @code{$INCR}(@var{N,m}) executes the equivalent of
@code{N += 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.

@code{$INPUT_LINE} is the number of the line in the @sc{web} source file
that begins the current section.

@node $L,$LANGUAGE,$INPUT_LINE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$L}:  Change to lower case.

@code{$L}(@i{string}) changes @i{string} to lower case.

@node $LANGUAGE,$LANGUAGE_NUM,$L,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$LANGUAGE}:  Identifier for current language.

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 these are identifiers, not @sc{web} macros.  They are intended
to be used in @samp{$IF} or @samp{$IFELSE} statements such as

@example
$IF($LANGUAGE==$C, C-text, other-text)
@end example

For multiway switches, the @samp{$LANGUAGE_NUM} built-in is more useful;
@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.

@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 @samp{$IFCASE}
construction; @ref{$IFCASE}.

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

@subsubsection @code{$LEN}:  Length of string.

@code{$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.

@code{$LOG(x)} returns the natural logarithm of @var{x}.

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

@subsubsection @code{$LOG10}:  Logarithm to the base 10.

@code{$LOG10(x)} returns the logarithm to the base 10 of @var{x}.

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

@subsubsection @code{$M}:  Define a macro.

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

@code{$MAX(x1,x2,...)} returns the minimum 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

(To be finished.)

@subsubsection @code{$MIN}:  Minimum.

@code{$MIN(x1,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 @sc{web} module.

@node $MODULES,$OUTPUT_LINE,$MODULE_NAME,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$MODULES}:  Total number of independent modules.

@code{$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.

@node $P,$PI,$OUTPUT_LINE,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$P}:  The C preprocessor symbol '#'.

@code{$P} is a synonym for @code{$UNQUOTE("#")}.  @xref{$UNQUOTE}.
It is useful for constructing @sc{web} 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.

The expression @code{$PI} returns @var{pi} to the default machine
precision.  The expression @code{$PI(iprec)} returns @var{pi} 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.

@code{$POW}(@i{x,y}) generates @i{x} raised to the power @i{y}.

@node $ROUTINE,$SECTION_NUM,$POW,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$ROUTINE}:  Current function (@sc{Ratfor} only).

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{web} section.

@code{$SECTION_NUM} returns an integer greater than 0 that is the number
of the current @sc{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.

@code{$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.

@code{$SQRT(x)} return the square root of x.

@node $STRING, $STUB,$SQRT, Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$STRING}:  Expand, then stringize.

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

(To be finished.)

@node $TIME,$TRANSLIT,$STUB,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$TIME}:  The time.

@code{$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.

(To be finished.)

@node $U,$UNDEF,$TRANSLIT,Built-in functions
@comment  node-name,  next,  previous,  up

@subsubsection @code{$U}:  Change to upper case.

@code{$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.

@code{$UNDEF}(@i{macro}) undefines a @sc{web} macro.

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

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

@code{$UNQUOTE}(@i{string}) returns @i{string} without its surrounded
quotes.

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

@subsubsection @code{$VERBATIM}:  (Obsolete)

This was an old name for @code{$UNQUOTE}.  @xref{$UNQUOTE}.

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

@subsubsection @code{$VERSION}:  Present @sc{fweb} version number.

@code{$VERSION} returns a string built out of the @sc{fweb} version
number, such as @code{"1.32"}.

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

@section Preprocessing

@sc{fweb} preprocessor commands may appear in either the definition or the
code parts.  But BEWARE:  No matter where they appear, they are expanded
during INPUT, not output.  (This is probably a design flaw.)  For more
discussion, @ref{WEB macros}.

@example
@@#define identifier --- Define a WEB macro; equivalent to @samp{@@m}.
@@#undef identifier  --- Undefine a WEB macro.

@@#ifdef identifier  --- Is WEB macro defined?  Equivalent to
                         @samp{@@#if defined identifier}.
@@#ifndef identifier --- Is WEB 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 WEB
macros, but must ultimately evaluate to a number.  If that number is
zero, the expression is false; otherwise, it is true.

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):

@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 a @sc{web} macro; 
to~0 (false) otherwise.  The construction @samp{@@\#if defined A} works the
same way as @samp{@@\#ifdef A}, but you 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{web} 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 the
exclusive or operator for~C. Also, note that the bitwise operators
should almost never be used. For 
logic, almost always you will be using @samp{==}, @samp{!=}, @samp{\&\&},
and @samp{||}. 
@end tex

@node Languages,Macros,Comments,Top
@comment  node-name,  next,  previous,  up

@chapter LANGUAGES

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

The most general form of a language command is

@@@i{[}L@i{]ltext}[@i{options}]

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

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

@section Special hints and considerations for each language

@subsection C
Special remarks.  (To be completed.)

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

@subsection C++
Special remarks.  (To be completed.)

@node Fortran,Ratfor_,Cpp,Languages
@comment  node-name,  next,  previous,  up

@subsection Fortran
Special remarks.  (To be completed.)

@node Ratfor_,TeX,Fortran,Languages
@comment  node-name,  next,  previous,  up

@subsection Ratfor
Special remarks.  (To be completed.)

@node TeX, Verbatim, Ratfor_, Languages
@comment  node-name,  next,  previous,  up

@subsection TeX
Special remarks.  (To be completed.)

@node Verbatim, , TeX, Languages
@comment  node-name,  next,  previous,  up

@subsection Verbatim

Special remarks.

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

@chapter RATFOR

``Ratfor'' stands for ``RATional FORtran''.  More...

@menu
* Commands::            Ratfor commands.
* Caviats::             Nuances about @sc{fweb} Ratfor.
@end menu

@node Commands,Caviats,Ratfor,Ratfor
@comment  node-name,  next,  previous,  up

@section Ratfor commands

@subsection Ratfor--77 commands

@example 
 break;
 case i:
 default:
 do ...; @{...@}
 else @{...@}
 for(a;b;c) @{...@}
 if(condition) @{...@}
 next;
 repeat @{...@} until(condition);
 return expression;
 switch(expression) @{...@}
 while(condition) @{...@}
@end example

@subsection Additional Ratfor--90 commands

@example
 contains:
 interface name @{...@}
 interface operator(op) @{...@}
 interface assignment(assgnmnt) @{...@}
 module name @{...@}
 private:
 sequence:
 type name @{...@}
 where(expression) @{...@}
@end example

@node Caviats,,Commands,Ratfor
@comment  node-name,  next,  previous,  up

@section Caviats about Ratfor

The version of Ratfor built into @sc{fweb} differs slightly from its Unix
counterpart:  

@enumerate
@item 
Numeric statement labels must be followed by a colon; they should
be first on their line.

@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 when the closing brace is sensed.
@end enumerate


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

@chapter FORMATTING

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

@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

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

To inform @sc{fweave} you will be using @TeX{} as the formatter, just say
@samp{@sc{fweave} test} or @samp{@sc{fweave} -PT test}.  To inform it
you will be using La@TeX{}, say @samp{@sc{fweave} -PL test}.

If you will always be using a particular processor, you should probably
put @samp{+PL} into your @file{.@sc{fweb}} file (@pxref{Initialization}).

@menu
* Output::	Structure of the TeX output from @sc{fweave}.
* LaTeX::	Specifics of the LaTeX support.
@end menu

@node Output,  LaTeX, 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.
The @TeX{} commands contained in this file are organized into several
sequential groups.

@enumerate
@item 
@code{\input} command to read in @sc{fweave}'s macro package.

By default, the initial input command is @samp{\input fwebmac.sty}.  The
name of the macro package can be changed with the @samp{-w} command-line
option.  @xref{-w}.

@item 
@code{\Wbegin} command (sets up the environment for @TeX{} or La@TeX{}).

The @code{\Wbegin} macro sets up certain defaults.  These can be overridden in
the limbo section.

@item 
Limbo text from the style-file parameter @code{limbo}.  @xref{limbo}.

@item 
Beginning of user's limbo section.

@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



@node LaTeX, , Output, Typesetting
@comment  node-name,  next,  previous,  up

@subsection La@TeX{} support

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.  La@TeX{}'s
@code{\output} routine is used, as are its sectioning commands (with
minor changes), table-of-contents facilities, etc.

@menu
* Document style::	LaTeX's document style, options, etc.
* Sections::	        Section numbering, spacing, etc.
* Table of contents::   The table of contents.
* Customizing LaTeX::   Conditional flags, etc.
@end menu

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

@subsubsection La@TeX{}'s document style

@sc{fweave} uses @code{\documentstyle@{article@}}.  The document style can be
changed by the style-file option @samp{La@TeX{}.style}.  @xref{Fwebmac params}.
However, @sc{fweave} has not been tested with other document styles.

To incorporate style options---i.e., to obtain the effect of
@samp{\documentstyle[myoptions]@{article@}}, use the style-file option
@code{La@TeX{}.options}, as in

@example
LaTeX.options "myoptions"
@end example

@TeX{} commands in the user's limbo section will appear after the
@code{\documentstyle} and @code{\begin@{document@}} commands, so may be
used to redefine macro definitions in the style file.

@node Sections,  Table of contents, Document style,  LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection Sections in La@TeX{}

@sc{fweb}'s sectioning commands (@samp{@@*}, @samp{@@*}@i{n}, and
@samp{@@ }) are converted into 
La@TeX{}'s section commands such as @code{\section} (n=0),
@code{\subsection} (n=1), and 
@code{\subsubsection} (n=2).  During La@TeX{}'s processing of the tex file, it
keeps track of the maximum depth achieved by @samp{@@*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 @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.

@node Table of contents, Customizing LaTeX,  Sections, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection La@TeX{}'s table of contents

In essence, the table of contents is produced by the La@TeX{} commands

@example
\pagenumbering@{roman@}
\topofcontents
\maketitle
\tableofcontents
\botofcontents
\newpage
@end example

@noindent
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 \maketitle in the limbo
section in the usual La@TeX{} way, except that one is encouraged to use
@sc{fweb}'s \Title macro instead of @code{\title}:

@example
\Title@{MYCODE.WEB@}
\author@{My name@}
\date@{January 1, 2001@}
@end example
By default, @sc{fweave} uses
@example
\title@{@}%
\author@{@}%
\date@{\today\\[3pt]\Time@}%
@end example

@node Customizing LaTeX,  ,  Table of contents, LaTeX
@comment  node-name,  next,  previous,  up

@subsubsection Customizing La@TeX{}'s output

Several flags are provided to change the appearance of the final La@TeX{}
document.  These are

@itemize @bullet
@item 
\ifpagerefs (index references by pages or section numbers).

@item 
\numberTeX (number the beginning of the TeX part).

@item 
\numberdefs (number the beginning of the definition part).

@item 
\numbercode (number the beginning of the code part).
@end itemize

@noindent
The defaults for these flags are

@example
\pagerefsfalse
\numberTeXfalse
\numberdefstrue
\numbercodetrue
@end example

@menu
* Page references::     Indexing by page numbers.
* Numbering::           Various section numbering schemes.
@end menu

@node Page references, Numbering, Customizing LaTeX, Customizing LaTeX
@comment  node-name,  next,  previous,  up

@subsection Page references

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

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 Numbering, , Page references, Customizing LaTeX
@comment  node-name,  next,  previous,  up

(To be finished.)

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

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

Pseudo-operators behave like a particular part of speech for the
purposes of @sc{fweave}'s formatting, but are invisible on output.  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 you can type on
input, and what @sc{fweave} will output.
@end ifinfo

@tex
Here is a table of
what you can type on input, and what @sc{fweave} will typeset. The first entry
is standard @c{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(**,\^) & \.{(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

For special effects in the woven output, there are commands to help
one change the appearance of operators and identifiers.

@subsubsection Overloading operators

A feature common to both C++ and @sc{fortran--90} is @i{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 `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 language
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 for example if
you want to include a backslash you must escape it with another backslash.
For example, we can make an equals sign display on output as
a large left arrow by saying

@example
@@v = "\\Leftarrow" =
@end example

@noindent
Two \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

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 (probably 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.

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,'' where an example is given.


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

@subsection Information options

Several of the command-line options can be used to elicit information
about the initial state of @sc{fweb}.

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

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

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

The default behavior of @sc{fweb} can be changed in a variety of ways.  

@enumerate
@item 
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

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.

The style file is intended to provide more local customization, perhaps
differing for each run.  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})
provides a means of incorporating style-file entries into @file{.fweb}.

The order of processing is:

@enumerate
@item 
Evaluate environment variables.

@item 
Read @file{.fweb}.

@item 
Process @file{.fweb} options beginning with @samp{+}.

@item 
Read and process command-line options (except for @samp{-p}).

@item 
Process remaining @file{.fweb} options.

@item 
Process any @samp{-p} options.

@item 
Read and process the style file.
@end enumerate

@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

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

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

@code{FWEB_STYLE_DIR} --- Directory in which style file resides.  If not
defined, the current directory is used.

@node Initialization,Memory allocation,Environment variables,Customization
@comment  node-name,  next,  previous,  up

@section Initialization

@subsection The initialization file

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{+}, it is processed before the actual command-line
options; otherwise, 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

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 aa, just say
@samp{-y}@i{aa}.  To query everything, say @samp{-y}.

(The detailed explanations for these arrays aren't here yet.  The
on-line info has a terse list.)

@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.
* -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{web} macros.
* -ymb::        Size of the buffer for expanding @sc{web} macros.
* -yn::         Maximum number of identifiers, strings, and module names.
* -ynf::        Maximum number of open input 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 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

@node -ybs, -ycb, -yb, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ycb, -ycf, -ybs, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ycf, -ycg, -ycb, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ycg, -yd, -ycf, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yd, -ydt, -ycg, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ydt, -ydx, -yd, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ydx, -ykt, -ydt, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ykt, -ykw, -ydx, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ykw, -yll, -ykt, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yll, -yln, -ykw, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yln, -ylb, -yll, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ylb, -ylx, -yln, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ylx, -ym, -ylb, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ym, -yma, -ylx, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yma, -ymb, -ym, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ymb, -yn, -yma, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yn, -ynf, -ymb, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ynf, -yop, -yn, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yop, -yr, -ynf, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yr, -ys, -yop, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ys, -ysb, -yr, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ysb, -ytt, -ys, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ytt, -ytw, -ysb, Memory allocation
@comment  node-name,  next,  previous,  up

@node -ytw, -yx, -ytt, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yx, -yxb, -ytw, Memory allocation
@comment  node-name,  next,  previous,  up

@node -yxb, , -yx, Memory allocation
@comment  node-name,  next,  previous,  up

@node Style,,Memory allocation,Customization
@comment  node-name,  next,  previous,  up

@section The Style file

A style file (default name @file{fweb.sty}) may reside in the user's current
directory (or 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.  Note that the command-line option @samp{-p} (@pxref{-p})
buffers up style-file entries.  Effectively, these are treated as
residing in a temporary file that is read just before the local style
file.  Thus, @samp{-p} options placed in @file{.fweb} behave as `global'
style-file entries and will be overridden by a matching entry in the
local style file.
 
Style-file entries have the form

@example
        keyword [=] value
@end example

@noindent
For example,

@example
        LaTeX.options = "eqalign"
@end example

@noindent
The syntax is completely free-form.

The descriptions of the parameters aren't completed yet.  Please see the
reference guide.

@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

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

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

@code{index.tex} is the name of the file into which the index is
written.  The character '#' is translated into the root name of the web
file.

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

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

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

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

@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

When @sc{fweave} pretty-prints code, it can attach cross-reference
subscripts to various kinds of identifiers.  The following flags select
which identifiers are so subscripted.

@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

To some extent, the behavior of @sc{fweb}'s macro package
@file{fwebmac.sty} can be changed by means of the following parameters,
instead of actually editing @file{fwebmac.web} itself.

@menu
* format.reserved: S_format.
* format.short_identifier: S_format.
* format.outer_macro: S_format.
* format.WEB_macro: S_format.
* format.intrinsic: 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.options: S_LaTeX.       Set options for document style.
* LaTeX.style: S_LaTeX.         Specify document style.
@end menu

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

@subsubsection @code{format}

The @code{format} fields specify the macro to use to pretty-print
various kinds of identifiers, as follows:
(not finished).

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

@subsubsection @code{indent}

@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

When running under La@TeX{}, the documents 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

(To be finished.)

@node Miscellaneous params,,Control-code mappings,Style

@comment  node-name,  next,  previous,  up

@subsection Miscellaneous style-file 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_length: S_line_length.

* 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::                       Default material to begin the limbo part

* 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 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.l}, where l is one of
@code{C}, @code{Cpp}, @code{N}, @code{N90}, @code{R}, @code{R90},
@code{X}, or @code{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} (@sc{ftangle})

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

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

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

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


@node macros, 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 can be
overridden by the command-line option @samp{-w}; see @ref{-w}.)

@node limbo, S_meta_w, macros, Miscellaneous params
@comment  node-name,  next,  previous,  up

@subsubsection @code{limbo}

@TeX{} material to be printed at the beginning of the limbo part, just
before the text from @samp{@@l} commands.  @xref{ATl}.

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

@subsubsection @code{meta} (@sc{fweave})

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

@subsubsection @code{preamble}

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}

In 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.l} and
@code{dot_constant.end.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.  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 we collect various tips and suggestions to help one make
full use of @sc{fweb}.  @emph{(There's more to come here!)}

@section Converting an existing code to @sc{fweb}

In summary, to convert an existing code to @sc{fweb}, you should do the
following. (The following simple procedure assumes that you put 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{}. (You 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{@@i}), or pseudo-colons (@samp{@@:}).
 
@item
Consider using the built-in macro preprocessor to make your code
more readable---for example, replace raw numerical constants by symbolic
names. 

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

@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
Periodically check @code{ftp.pppl.gov:/pub/fweb/READ_ME} for bug
reports and other news.  Make bug reports!  @xref{Support}.

@item
Most options in @file{.fweb}
should begin with @samp{+} so they can be
overridden by command-line options for the job itself.
@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.
@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{web} 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.

@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 that'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.   
@xref{Macros}

@item
When mixing languages, define the language of a module at the highest
possible level---e.g., in the unamed module, not after @samp{@@<...@@>=}.

@end enumerate


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

@chapter NEW FEATURES, version 1.40

@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, the underscore forms may 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
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

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

@chapter SUPPORT

@sc{fweb} is supported by John Krommes, @samp{krommes@@princeton.edu}.  
This project is a @emph{spare-time activity}!  I try for, but cannot
promise, reasonably quick (one week) response to questions.  Bug reports
submitted with very short test files will be verified.  For very simple
fixes, a change file will 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.

Marcus Speh moderates an @sc{fweb} FAQ.  See @file{/pub/fweb/faq}.

@node Index, , Support, Top
@comment  node-name,  next,  previous,  up

@unnumbered Index

The index is obviously not complete; the following are tests.

@printindex cp

@shortcontents
@contents

@bye
