This is Info file fweb.info, produced by Makeinfo-1.55 from the input
file fweb.texinfo.
   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.
   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).
   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.
File: fweb.info,  Node: AT~,  Next: AT&,  Prev: AT#,  Up: AT commands
`@~':  Cancel line break.
-------------------------
   For example,
     printf("Working..."); @~ fflush(stdout);
File: fweb.info,  Node: AT&,  Next: ATe,  Prev: AT~,  Up: AT commands
`@&':  Join items.
------------------
   During FWEAVE's output, `@&' joins the items to either side with no
spaces or line breaks inbetween.
   This command must be distinguished from the preprocessor construction
`##' (paste tokens together).  In a macro definition, `a##bc' creates
the single identifier `abc'.  If one said `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
`abc' were itself a WEB macro.
File: fweb.info,  Node: ATe,  Next: AT;,  Prev: AT&,  Up: AT commands
Pseudo (invisible) operators
============================
`@e':  Pseudo-expression.
-------------------------
   `@e' is an invisible expression.  *Note Pseudo-operators::.
File: fweb.info,  Node: AT;,  Next: ATcolon,  Prev: ATe,  Up: AT commands
`@;':  Pseudo-semicolon.
------------------------
   `@;' is an invisible semicolon.  These are often used in C
programming to terminate a module name that expands to a compound
statement.  For example,
     @c
     @a
     if(flag)
             @<Compound statement@>@;
     else
             @<Simple statement@>;
     
     @
     @<Com...@>=
     {
     x;
     y;
     }
     
     @
     @<Sim...@>=
     z
   *Note Pseudo-operators::.
File: fweb.info,  Node: ATcolon,  Next: AT!,  Prev: AT;,  Up: AT commands
`@:':  Pseudo-colon.
--------------------
   `@:' is an invisible colon.  *Note Pseudo-operators::.  It can be
helpful in formatting certain C constructions correctly.  For example,
     @<Cases@>=
     case 1:
     case 2:
     case 3@:
File: fweb.info,  Node: AT!,  Prev: ATcolon,  Up: AT commands
Miscellaneous commands
======================
`@!':  Inhibit macro expansion
------------------------------
   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 `@!'.
File: fweb.info,  Node: Comments,  Next: Languages,  Prev: AT commands,  Up: Top
COMMENTING STYLES
*****************
   FWEB allows a variety of commenting styles. The visible comments are
in the font `\cmntfont', which defaults to `\tenrm'.
* Menu:
* Invisible comments::          Skipping input material.
* Visible comments::            Comments in code mode.
File: fweb.info,  Node: Invisible comments,  Next: Visible comments,  Prev: Comments,  Up: Comments
Invisible comments
==================
     @z...@x --- If a source or include file begins with `@z', then all
                 material is skipped until and including a line beginning in
                 column 1 with `@x'.
     
     @%       --- All material until and including the next newline is
                 completely ignored.
     
     @%%      --- As `@%', but also skip blank lines that immediately
                  follow the current line.
   For example,
     @z
     Author:  J. A. Krommes
     @x
     @c @% This sets the global language to C.
     @* EXAMPLE.
File: fweb.info,  Node: Visible comments,  Prev: Invisible comments,  Up: Comments
Visible comments
================
   `/* ... */' is a long comment (may extend over several lines).
   `// ...' is a short comment (terminated by next newline).
   `@(...@)' 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 `meta.top' and terminated by `meta.bottom'.  Each line
of the meta-comment is begun by `meta.prefix'.  Woven meta-comments are
begun by `meta_code.begin' and ended by `meta_code.end'.  *Note
Miscellaneous params::.
     @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
   The use of meta-comments is not recommended.  Use ordinary long
comments instead.  Inside of them, use the various powerful features of
TeX or LaTeX (such as `\halign') to format your comment appropriately.
File: fweb.info,  Node: Macros,  Next: Ratfor,  Prev: Languages,  Up: Top
MACROS and PREPROCESSING
************************
* Menu:
* Outer macros::        Macros copied to beginning of output file (@d).
* WEB macros::          Macros expanded by FWEB (@m).
* Preprocessing::       FWEB's preprocessing language (@#if etc.)
File: fweb.info,  Node: Outer macros,  Next: WEB macros,  Prev: Macros,  Up: Macros
   FWEB recognizes two kinds of macros:  "outer macros", and "WEB
macros" or "inner macros".  Control codes associated with either of
these kinds normally begin the definition part.  However, WEB macros
are sometimes allowed in the code part as well; *Note WEB macros::.
Outer macros
============
   Outer macros are defined by `@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 `#define' when the positioning of the `#define'
is unimportant.
   As an example,
     @c
     @
     @d YES 1
     @d NO 0
     @a
     main()
     {}
     
     @
     @d BUF_LEN 100
     @a
     ...
   The keyword into which the `@d' is translated is language-dependent;
it is controlled by the style-file parameter `outer_def'. *Note
Miscellaneous params::.
   Outer macros can be undefined by `@u'.  The translation is
controlled by the style-file parameter `outer_undef'.  *Note
Miscellaneous params::.
File: fweb.info,  Node: WEB macros,  Next: Preprocessing,  Prev: Outer macros,  Up: Macros
WEB macros
==========
   WEB macros are defined by `@m'.  These should normally be placed in
the definition section.  They are collected during 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 `-TD' is used, then 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.
   WEB macros are often used in conjunction with the 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 FWEB.
File: fweb.info,  Node: Macro features,  Next: Tokens,  Prev: WEB macros,  Up: WEB macros
Various features of WEB macros
------------------------------
   * WEB macros with a variable number of arguments are indicated by an
     ellipsis, as in
          @m VAR(x,y,z,...) text
   * Adjacent strings in macro text are automatically concatenated.
File: fweb.info,  Node: Tokens,  Next: Built-in functions,  Prev: Macro features,  Up: WEB macros
Special tokens
--------------
   The following special tokens may be used in the text of WEB macro
definitions:
ANSI C-compatible tokens
........................
      ##          --- Paste tokens on either side to form a new identifier.
      #parameter  --- Convert parameter to string (without expansion).
Extensions to ANSI C macro syntax
.................................
   (In the following list, the forms `#{n}' and `#[n]' may not work
correctly in complicated situations.  This is a design deficiency that
will be corrected someday.)
      #*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.
File: fweb.info,  Node: Built-in functions,  Next: $A,  Prev: Tokens,  Up: WEB macros
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 FWEB design, built-in functions began with an
underscore.  This usage conflicts with the conventions for reserved
words in ANSI C.  In fact, 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
     @#undef _A
   *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 `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 WEB module.
* $MODULES::            Total number of independent modules.
* $OUTPUT_LINE::        Current line number of tangled output.
* $P::                  The C preprocessor symbol `'#''.
* $PI::                 3.14159...
* $POW::                Raise to a power.
* $ROUTINE::            Current RATFOR program, function, or subroutine.
* $SECTION_NUM::        Number of current section.
* $SECTIONS::           Maximum number of sections.
* $SQRT::               Square root.
* $STRING::             Expand argument, then stringize.
* $STUB::
* $TIME::               The local time.
* $TRANSLIT::           Transliterate a string.
* $U::                  Change string to upper case.
* $UNDEF::              Undefine a WEB macro.
* $UNQUOTE::            Remove quotes from string.
* $VERBATIM::           (Obsolete.)
* $VERSION::            FWEB version number.
File: fweb.info,  Node: $A,  Next: $ABS,  Prev: Built-in functions,  Up: Built-in functions
`$A':  Convert to ASCII.
........................
   `$A'(string) is the built-in equivalent of `@'...'' or `@"..."'.
(See *note ATquote::. and *note AT"::..) Note the extra parentheses
required by the built-in.
File: fweb.info,  Node: $ABS,  Next: $ASSERT,  Prev: $A,  Up: Built-in functions
`$ABS':  Absolute value.
........................
   `$ABS'(expression) returns the absolute value of the macro
expression.
File: fweb.info,  Node: $ASSERT,  Next: $COMMENT,  Prev: $ABS,  Up: Built-in functions
`$ASSERT':  Assert a condition.
...............................
   `$ASSERT'(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 WEB macros required by the
code are properly initialized.  It must appear in the *code part* (not
the definition part).
File: fweb.info,  Node: $COMMENT,  Next: $DATE,  Prev: $ASSERT,  Up: Built-in functions
`$COMMENT':  Generate a comment.
................................
   `$COMMENT'(string) generates a comment in the output file.
   This built-in is sometimes useful in conjunction with the processing
of WEB macros, since ordinary comments are removed when macros are
processed.
File: fweb.info,  Node: $DATE,  Next: $DAY,  Prev: $COMMENT,  Up: Built-in functions
`$DATE':  Today's date.
.......................
   `$DATE' generates a string consisting of the date in the form
`"August 16, 2001"'.
File: fweb.info,  Node: $DAY,  Next: $DECR,  Prev: $DATE,  Up: Built-in functions
`$DAY':  The day.
.................
   `$DAY' generates a string consisting of the day of the week, such as
`"Monday"'.
File: fweb.info,  Node: $DECR,  Next: $DEFINE,  Prev: $DAY,  Up: Built-in functions
`$DECR':  Decrement a macro.
............................
   `$DECR'(N) redefines the numeric macro N to be one less than its
previous value.  (If N does not simplify to a number, an error
results.)  In other words, in the language of C the effect is to say
`N--'.
   The two-argument form `$DECR'(N,M) executes the equivalent of `N -=
File: fweb.info,  Node: $DEFINE,  Next: $DO,  Prev: $DECR,  Up: Built-in functions
`$DEFINE':  Deferred macro definition.
......................................
   `$DEFINE' (to be finished).
File: fweb.info,  Node: $DO,  Next: $DUMPDEF,  Prev: $DEFINE,  Up: Built-in functions
`$DO':  Macro do loop.
......................
   `$DO'(macro,imin,imax[,di]){...} repetitively defines macro as would
the FORTRAN statement `do macro = imin,imax,di'.  For example,
     $DO(I,0,2)
       {
       a[I] = I;
       }
generates the three statements
       a[0] = 0;
       a[1] = 1;
       a[2] = 2;
   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 FWEAVE format certain constructions correctly.
   Nested delimiters are handled correctly.  The delimiters are required
even only a single statement is to expanded.
File: fweb.info,  Node: $DUMPDEF,  Next: $E,  Prev: $DO,  Up: Built-in functions
`$DUMPDEF':  Dump macro definitions to the terminal.
....................................................
   In the call `$DUMPDEF'(m1,m2,...), m1, 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 FWEB's built-ins.
File: fweb.info,  Node: $E,  Next: $ERROR,  Prev: $DUMPDEF,  Up: Built-in functions
`$E': Base of natural logarithms.
.................................
   The expression `$E' returns E to the default machine precision.  The
expression `$E(iprec)' returns E to the decimal precision IPREC (which
must be less than 50).
File: fweb.info,  Node: $ERROR,  Next: $EVAL,  Prev: $E,  Up: Built-in functions
`$ERROR':  Send error message to output.
........................................
   `$ERROR'(string) prints an error message in FWEB's standard form.
File: fweb.info,  Node: $EVAL,  Next: $EXP,  Prev: $ERROR,  Up: Built-in functions
`$EVAL':  Evaluate a macro expression.
......................................
   `$EVAL'(expression) used 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.
File: fweb.info,  Node: $EXP,  Next: $GETENV,  Prev: $EVAL,  Up: Built-in functions
`$EXP':  Exponential function.
..............................
   `$EXP(x)' returns E to the power X.
File: fweb.info,  Node: $GETENV,  Next: $HOME,  Prev: $EXP,  Up: Built-in functions
`$GETENV':  Get value of environment variable.
..............................................
   `$GETENV'(name) returns a string consisting of the current value of
the environment variable name.  (Under VMS, logical names behave like
environment variables.)
File: fweb.info,  Node: $HOME,  Next: $IF,  Prev: $GETENV,  Up: Built-in functions
`$HOME':  The user's home directory.
....................................
   `$HOME' is equivalent to `$GETENV(HOME)'.
File: fweb.info,  Node: $IF,  Next: $IFCASE,  Prev: $HOME,  Up: Built-in functions
`$IF':  Two-way conditional.
............................
   (To be finished.)
File: fweb.info,  Node: $IFCASE,  Next: $IFDEF,  Prev: $IF,  Up: Built-in functions
`$IFCASE':  n-way conditional.
..............................
File: fweb.info,  Node: $IFDEF,  Next: $IFNDEF,  Prev: $IFCASE,  Up: Built-in functions
`$IFDEF':  Two-way conditional.
...............................
File: fweb.info,  Node: $IFNDEF,  Next: $IFELSE,  Prev: $IFDEF,  Up: Built-in functions
`$IFNDEF':  Two-way conditional.
................................
File: fweb.info,  Node: $IFELSE,  Next: $INCR,  Prev: $IFNDEF,  Up: Built-in functions
`$IFELSE':  Two-way conditional.
................................
File: fweb.info,  Node: $INCR,  Next: $INPUT_LINE,  Prev: $IFELSE,  Up: Built-in functions
`$INCR':  Increment a macro.
............................
   `$INCR'(N) redefines the numeric macro N to be one greater than its
previous value.  (If N does not simplify to a number, an error
results.)  In other words, in the language of C the effect is to say
`N++'.
   The two-argument form `$INCR'(N,M) executes the equivalent of `N +=
File: fweb.info,  Node: $INPUT_LINE,  Next: $L,  Prev: $INCR,  Up: Built-in functions
`$INPUT_LINE':  Line number that begins current section.
........................................................
   `$INPUT_LINE' is the number of the line in the WEB source file that
begins the current section.
File: fweb.info,  Node: $L,  Next: $LANGUAGE,  Prev: $INPUT_LINE,  Up: Built-in functions
`$L':  Change to lower case.
............................
   `$L'(string) changes string to lower case.
File: fweb.info,  Node: $LANGUAGE,  Next: $LANGUAGE_NUM,  Prev: $L,  Up: Built-in functions
`$LANGUAGE':  Identifier for current language.
..............................................
   This expands to an identifier that denotes the current language, as
follows:
     Language    $LANGUAGE
      C             $C
      C++           $CPP
      Fortran       $N
      Fortran-90    $N90
      Ratfor        $R
      Ratfor-90     $R90
      TeX           $X
      VERBATIM      $V
Note that these are identifiers, not WEB macros.  They are intended to
be used in `$IF' or `$IFELSE' statements such as
     $IF($LANGUAGE==$C, C-text, other-text)
   For multiway switches, the `$LANGUAGE_NUM' built-in is more useful;
*Note $LANGUAGE_NUM::.
File: fweb.info,  Node: $LANGUAGE_NUM,  Next: $LEN,  Prev: $LANGUAGE,  Up: Built-in functions
`$LANGUAGE_NUM':  Number of current language.
.............................................
   `$LANGUAGE_NUM' expands to an integer that uniquely defines the
current language, as follows:
     Language  $LANGUAGE_NUM
      C             0
      C++           1
      Fortran       2
      Fortran-90    3
      Ratfor        4
      Ratfor-90     5
      TeX           6
      VERBATIM      7
This built-in is useful in conjunction with an `$IFCASE' construction;
*Note $IFCASE::.
File: fweb.info,  Node: $LEN,  Next: $LOG,  Prev: $LANGUAGE_NUM,  Up: Built-in functions
`$LEN':  Length of string.
..........................
   `$LEN'(string) returns the length of string in bytes.  If 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
     @m SS string
     $LEN(SS)
the value returned is 2, not 5.
File: fweb.info,  Node: $LOG,  Next: $LOG10,  Prev: $LEN,  Up: Built-in functions
`$LOG':  Natural logarithm.
...........................
   `$LOG(x)' returns the natural logarithm of X.
File: fweb.info,  Node: $LOG10,  Next: $M,  Prev: $LOG,  Up: Built-in functions
`$LOG10':  Logarithm to the base 10.
....................................
   `$LOG10(x)' returns the logarithm to the base 10 of X.
File: fweb.info,  Node: $M,  Next: $MAX,  Prev: $LOG10,  Up: Built-in functions
`$M':  Define a macro.
......................
   `$M' is equivalent to `$DEFINE'.  *Note $DEFINE::.
File: fweb.info,  Node: $MAX,  Next: $MIN,  Prev: $M,  Up: Built-in functions
`$MAX':  Maximum of a list.
...........................
   `$MAX(x1,x2,...)' returns the minimum of the list of arguments.
(There must be at least one argument.)
File: fweb.info,  Node: $MIN,  Next: $MODULE_NAME,  Prev: $MAX,  Up: Built-in functions
   (To be finished.)
`$MIN':  Minimum.
.................
   `$MIN(x1,x2,...)' returns the minimum of the list of arguments.
(There must be at least one argument.)
File: fweb.info,  Node: $MODULE_NAME,  Next: $MODULES,  Prev: $MIN,  Up: Built-in functions
`$MODULE_NAME':  Name of present WEB module.
............................................
File: fweb.info,  Node: $MODULES,  Next: $OUTPUT_LINE,  Prev: $MODULE_NAME,  Up: Built-in functions
`$MODULES':  Total number of independent modules.
.................................................
   `$MODULES' gives the total number of independent modules--that is,
the number of independent module names, plus 1 for the unnamed module.
File: fweb.info,  Node: $OUTPUT_LINE,  Next: $P,  Prev: $MODULES,  Up: Built-in functions
`$OUTPUT_LINE':  Current line number of tangled output.
.......................................................
File: fweb.info,  Node: $P,  Next: $PI,  Prev: $OUTPUT_LINE,  Up: Built-in functions
`$P':  The C preprocessor symbol '#'.
.....................................
   `$P' is a synonym for `$UNQUOTE("#")'.  *Note $UNQUOTE::.  It is
useful for constructing WEB macro definitions that expand to C
preprocessor statements.  For example,
     @m CHECK(flag)
             $P if(flag)
                     special code;
             $P endif
File: fweb.info,  Node: $PI,  Next: $POW,  Prev: $P,  Up: Built-in functions
`$PI': Pi.
..........
   The expression `$PI' returns PI to the default machine precision.
The expression `$PI(iprec)' returns PI to the decimal precision IPREC
(which must be less than 50).
File: fweb.info,  Node: $POW,  Next: $ROUTINE,  Prev: $PI,  Up: Built-in functions
`$POW':  Exponentiation.
........................
   `$POW'(x,y) generates x raised to the power y.
File: fweb.info,  Node: $ROUTINE,  Next: $SECTION_NUM,  Prev: $POW,  Up: Built-in functions
`$ROUTINE':  Current function (RATFOR only).
............................................
   When RATFOR is the current language, `$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.
File: fweb.info,  Node: $SECTION_NUM,  Next: $SECTIONS,  Prev: $ROUTINE,  Up: Built-in functions
`$SECTION_NUM':  Number of current WEB section.
...............................................
   `$SECTION_NUM' returns an integer greater than 0 that is the number
of the current WEB section.  (This is not the LaTeX section number such
as 3.4.)
File: fweb.info,  Node: $SECTIONS,  Next: $SQRT,  Prev: $SECTION_NUM,  Up: Built-in functions
`$SECTIONS':  Maximum section number.
.....................................
   `$SECTIONS' is the maximum section number as understood by FWEAVE.
File: fweb.info,  Node: $SQRT,  Next: $STRING,  Prev: $SECTIONS,  Up: Built-in functions
`$SQRT':  Square root.
......................
   `$SQRT(x)' return the square root of x.
File: fweb.info,  Node: $STRING,  Next: $STUB,  Prev: $SQRT,  Up: Built-in functions
`$STRING':  Expand, then stringize.
...................................
   `$STRING'(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.
File: fweb.info,  Node: $STUB,  Next: $TIME,  Prev: $STRING,  Up: Built-in functions
`$STUB':
........
   (To be finished.)
File: fweb.info,  Node: $TIME,  Next: $TRANSLIT,  Prev: $STUB,  Up: Built-in functions
`$TIME':  The time.
...................
   `$TIME' returns a string consisting of the local time in the form
`"19:59"'.
File: fweb.info,  Node: $TRANSLIT,  Next: $U,  Prev: $TIME,  Up: Built-in functions
`$TRANSLIT':  Transliteration.
..............................
   (To be finished.)
File: fweb.info,  Node: $U,  Next: $UNDEF,  Prev: $TRANSLIT,  Up: Built-in functions
`$U':  Change to upper case.
............................
   `$U'(string) changes string to upper case.
File: fweb.info,  Node: $UNDEF,  Next: $UNQUOTE,  Prev: $U,  Up: Built-in functions
`$UNDEF':  Undefine a macro.
............................
   `$UNDEF'(macro) undefines a WEB macro.
File: fweb.info,  Node: $UNQUOTE,  Next: $VERBATIM,  Prev: $UNDEF,  Up: Built-in functions
`$UNQUOTE':  Remove quotes from string.
.......................................
   `$UNQUOTE'(string) returns string without its surrounded quotes.
File: fweb.info,  Node: $VERBATIM,  Next: $VERSION,  Prev: $UNQUOTE,  Up: Built-in functions
`$VERBATIM':  (Obsolete)
........................
   This was an old name for `$UNQUOTE'.  *Note $UNQUOTE::.
File: fweb.info,  Node: $VERSION,  Prev: $VERBATIM,  Up: Built-in functions
`$VERSION':  Present FWEB version number.
.........................................
   `$VERSION' returns a string built out of the FWEB version number,
such as `"1.32"'.
File: fweb.info,  Node: Preprocessing,  Prev: WEB macros,  Up: Macros
Preprocessing
=============
   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, *Note WEB macros::.
     @#define identifier --- Define a WEB macro; equivalent to `@m'.
     @#undef identifier  --- Undefine a WEB macro.
     
     @#ifdef identifier  --- Is WEB macro defined?  Equivalent to
                              `@#if defined identifier'.
     @#ifndef identifier --- Is WEB macro not defined?  Equivalent to
                              `@#if !defined identifier'.
     
     @#if expression
     @#elif expression
     @#else
     @#endif
   In the `@#if' statement, the 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 expression following constructions such as `@#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 `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 `defined' has the highest precedence; all the other
unary operators have the next highest (and equal) precedence; then come
the binary operators. When the operator exists in C, the action taken
by FWEB is precisely that that the C compiler would take.  Arithmetic
is done in either long or double variables, as implemented by the C
compiler that compiled FTANGLE.  (This was the easy choice, not
necessarily the most desirable one.)
   The operators, listed from  highest precedence  to lowest, are as
follows (printed documentation only):
File: fweb.info,  Node: Languages,  Next: Macros,  Prev: Comments,  Up: Top
LANGUAGES
*********
   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 *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 FWEAVE.  Pretty-printing
can be inhibited by turning on the N mode (globally, with the
command-line option `-N'; locally, with `@N') or by selecting the
VERBATIM `language'; in both of these cases, the input text is echoed
literally to the output of both FTANGLE and FWEAVE.
   `Language' is a stronger concept than `mode'.  For example, when a
language is selected, the extension of the tangled output file is
changed appropriately--for example, if `test.web' contains C code (that
is, contains the command `@c'), `test.web' tangles into `test.c'
(compressing blanks and otherwise making the tangled output relatively
unreadable) and FWEAVE pretty-prints using the C syntax.  Turning on
the N mode does not affect the language; FTANGLE copies the source code
literally into `test.c' (no blank compression or other modifications),
and 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 FTANGLE writes its output to a file
with a special default extension that can be customized in the style
file.  *Note 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.
File: fweb.info,  Node: Setting,  Next: C,  Prev: Languages,  Up: Languages
Setting the language
====================
   The most general form of a language command is
   @[L]ltext[options]
where l is a language symbol, text is converted into a hyphenated
option, and options have the same syntax as on the command line.  The
language symbols must be in lower case; they are
     C          --- c
     C++        --- c++
     Fortran-77 --- n
     Fortran-90 --- n9
     Ratfor-77  --- r
     Ratfor-90  --- r9
     TeX        --- x
     VERBATIM   --- v
Thus, for example,
     @n9[-n&]
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 `@c' language-changing command.
     @n
     @
     @a
             program main
             end
     
     @c
     @<C@>@;
     
     @
     @<C@>=
     int fcn()
     {}
FTANGLE will write two output files for this example.
File: fweb.info,  Node: C,  Next: Cpp,  Prev: Setting,  Up: Languages
Special hints and considerations for each language
==================================================
   Special remarks.  (To be completed.)
File: fweb.info,  Node: Cpp,  Next: Fortran,  Prev: C,  Up: Languages
   Special remarks.  (To be completed.)
File: fweb.info,  Node: Fortran,  Next: Ratfor_,  Prev: Cpp,  Up: Languages
Fortran
-------
   Special remarks.  (To be completed.)
File: fweb.info,  Node: Ratfor_,  Next: TeX,  Prev: Fortran,  Up: Languages
Ratfor
------
   Special remarks.  (To be completed.)
File: fweb.info,  Node: TeX,  Next: Verbatim,  Prev: Ratfor_,  Up: Languages
   Special remarks.  (To be completed.)
File: fweb.info,  Node: Verbatim,  Prev: TeX,  Up: Languages
Verbatim
--------
   Special remarks.
File: fweb.info,  Node: Ratfor,  Next: Formatting,  Prev: Macros,  Up: Top
RATFOR
******
   "Ratfor" stands for "RATional FORtran".  More...
* Menu:
* Commands::            Ratfor commands.
* Caviats::             Nuances about FWEB Ratfor.
File: fweb.info,  Node: Commands,  Next: Caviats,  Prev: Ratfor,  Up: Ratfor
Ratfor commands
===============
Ratfor-77 commands
------------------
      break;
      case i:
      default:
      do ...; {...}
      else {...}
      for(a;b;c) {...}
      if(condition) {...}
      next;
      repeat {...} until(condition);
      return expression;
      switch(expression) {...}
      while(condition) {...}
Additional Ratfor-90 commands
-----------------------------
      contains:
      interface name {...}
      interface operator(op) {...}
      interface assignment(assgnmnt) {...}
      module name {...}
      private:
      sequence:
      type name {...}
      where(expression) {...}
File: fweb.info,  Node: Caviats,  Prev: Commands,  Up: Ratfor
Caviats about Ratfor
====================
   The version of Ratfor built into FWEB differs slightly from its Unix
counterpart:
  1. Numeric statement labels must be followed by a colon; they should
     be first on their line.
  2. The quoting convention for characters and strings follows that of
     C:  Single-quote single characters, double-quote strings.
  3. In a switch, cases fall through to the next case unless terminated
     by break (just as in C).
  4. The 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.)
  5. Use && and || for the logical AND and OR.
  6. Do not use an end statement at the very end of a program unit; it
     is added automatically when the closing brace is sensed.
File: fweb.info,  Node: Formatting,  Next: Customization,  Prev: Ratfor,  Up: Top
FORMATTING
**********
   FWEB uses TeX to format its documentation.  Either Plain TeX or
LaTeX may be used.  FWEB's "new look" beginning with Version 1.40 is
very flexible, but works only with LaTeX.
* Menu:
* Typesetting::         Woven output; TeX vs. LaTeX, etc.
* Pretty-printing::     Turning ugly input into beautiful output.
File: fweb.info,  Node: Typesetting,  Next: Pretty-printing,  Prev: Formatting,  Up: Formatting
Typesetting
===========
   FWEAVE works in conjunction with either TeX or LaTeX.  It is always
possible to create an adequately typeset document by processing with
TeX.  However, FWEB's "new look" (beginning with version 1.40) is
designed to work with LaTeX; 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' `nuweb'.
   To inform FWEAVE you will be using TeX as the formatter, just say
`FWEAVE test' or `FWEAVE -PT test'.  To inform it you will be using
LaTeX, say `FWEAVE -PL test'.
   If you will always be using a particular processor, you should
probably put `+PL' into your `.FWEB' file (*note Initialization::.).
* Menu:
* Output::	Structure of the TeX output from FWEAVE.
* LaTeX::	Specifics of the LaTeX support.
File: fweb.info,  Node: Output,  Next: LaTeX,  Prev: Typesetting,  Up: Typesetting
FWEAVE's OUTPUT
---------------
   When one says `FWEAVE test', the file `test.tex' is created.  The
TeX commands contained in this file are organized into several
sequential groups.
  1. `\input' command to read in FWEAVE's macro package.
     By default, the initial input command is `\input fwebmac.sty'.  The
     name of the macro package can be changed with the `-w' command-line
     option.  *Note -w::.
  2. `\Wbegin' command (sets up the environment for TeX or LaTeX).
     The `\Wbegin' macro sets up certain defaults.  These can be
     overridden in the limbo section.
  3. Limbo text from the style-file parameter `limbo'.  *Note limbo::.
  4. Beginning of user's limbo section.
  5. TeX commands for individual WEB sections.
  6. `\input' command to read in the index data file.
  7. `\input' command to read in the module-list data file.
  8. `\Winfo' command (summarizes some status information).
  9. `\Wcon' command (generates the table of contents, and ends the
     run).
File: fweb.info,  Node: LaTeX,  Prev: Output,  Up: Typesetting
LaTeX support
-------------
   Original LaTeX support (through version 1.30) was substantially
incomplete in that LaTeX's `\output' routine was usurped by the
relatively simple one used for FWEB's TeX support.  However, beginning
with version 1.40, full LaTeX support is provided.  LaTeX's `\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.
File: fweb.info,  Node: Document style,  Next: Sections,  Prev: LaTeX,  Up: LaTeX
LaTeX's document style
......................
   FWEAVE uses `\documentstyle{article}'.  The document style can be
changed by the style-file option `LaTeX.style'.  *Note Fwebmac params::.
However, FWEAVE has not been tested with other document styles.
   To incorporate style options--i.e., to obtain the effect of
`\documentstyle[myoptions]{article}', use the style-file option
`LaTeX.options', as in
     LaTeX.options "myoptions"
   TeX commands in the user's limbo section will appear after the
`\documentstyle' and `\begin{document}' commands, so may be used to
redefine macro definitions in the style file.
File: fweb.info,  Node: Sections,  Next: Table of contents,  Prev: Document style,  Up: LaTeX
Sections in LaTeX
.................
   FWEB's sectioning commands (`@*', `@*'n, and `@ ') are converted into
LaTeX's section commands such as `\section' (n=0), `\subsection' (n=1),
and `\subsubsection' (n=2).  During LaTeX's processing of the tex file,
it keeps track of the maximum depth achieved by `@*n'.  This number is
written as the last item in the `.aux' file.  During the next LaTeX run,
that number is used to map the `@ ' commands to the next most
insignificant sectioning command.  That level of sectioning command is
slightly redefined from LaTeX's default, so don't try to redefine it.
   The `.aux' file is also used by both processors to generate
appropriate error messages that refer to the LaTeX section number
instead of the internal one.
File: fweb.info,  Node: Table of contents,  Next: Customizing LaTeX,  Prev: Sections,  Up: LaTeX
LaTeX's table of contents
.........................
   In essence, the table of contents is produced by the LaTeX commands
     \pagenumbering{roman}
     \topofcontents
     \maketitle
     \tableofcontents
     \botofcontents
     \newpage
By default, the FWEB hooks `\topofcontents' and `\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 LaTeX way, except that one is encouraged to use
FWEB's \Title macro instead of `\title':
     \Title{MYCODE.WEB}
     \author{My name}
     \date{January 1, 2001}
   By default, FWEAVE uses
     \title{}%
     \author{}%
     \date{\today\\[3pt]\Time}%
File: fweb.info,  Node: Customizing LaTeX,  Prev: Table of contents,  Up: LaTeX
Customizing LaTeX's output
..........................
   Several flags are provided to change the appearance of the final
LaTeX document.  These are
   * \ifpagerefs (index references by pages or section numbers).
   * \numberTeX (number the beginning of the TeX part).
   * \numberdefs (number the beginning of the definition part).
   * \numbercode (number the beginning of the code part).
The defaults for these flags are
     \pagerefsfalse
     \numberTeXfalse
     \numberdefstrue
     \numbercodetrue
* Menu:
* Page references::     Indexing by page numbers.
* Numbering::           Various section numbering schemes.
File: fweb.info,  Node: Page references,  Next: Numbering,  Prev: Customizing LaTeX,  Up: Customizing LaTeX
Page references
---------------
   When one says `\pagerefstrue' (LaTeX only), index references are
made by page numbers rather than module numbers or LaTeX section
numbers.  If there is more than one section per page, they are
identified by `a', `b', `c', etc., such as `section 17b'.
   The information necessary to process page references in this way is
written into the `.aux' file.  As usual with LaTeX, several runs may be
required for the references to be fully consistent with the source file.
File: fweb.info,  Node: Numbering,  Prev: Page references,  Up: Customizing LaTeX
   (To be finished.)
File: fweb.info,  Node: Pretty-printing,  Prev: Typesetting,  Up: Formatting
Pretty-printing
===============
   "Pretty-printing" refers to FWEAVE's attempt to typeset and
highlight the code in a readable way.  This is usually done
automatically for all of the compiler-like languages such as C.
However, it can be inhibited by turning on the N mode with `@N' or by
using the VERBATIM language (selected with `@Lv').
   (More...)
* Menu:
* Alternatives::        Alternatives for various input tokens.
* Pseudo-operators::    Invisible parts of speech.
* Overloading::         Changing the appearance of various quantities.
File: fweb.info,  Node: Pseudo-operators,  Next: Overloading,  Prev: Alternatives,  Up: Pretty-printing
Pseudo-operators
----------------
   Pseudo-operators behave like a particular part of speech for the
purposes of FWEAVE's formatting, but are invisible on output.  The
pseudo-operators are
     @e --- pseudo-expression.  *Note ATe::.
     @; --- pseudo-semicolon.  *Note AT;::.
     @: --- pseudo-colon.  *Note ATcolon::.
File: fweb.info,  Node: Alternatives,  Next: Pseudo-operators,  Prev: Pretty-printing,  Up: Pretty-printing
Alternatives for various input tokens
-------------------------------------
   FWEAVE translates various input constructions into allegedly more
readable symbols--for example, in FORTRAN it translates `.LT.' into `<'.
The printed documentation contains a table of what you can type on
input, and what FWEAVE will output.
File: fweb.info,  Node: Overloading,  Prev: Pseudo-operators,  Up: Pretty-printing
Overloading operators and identifiers
-------------------------------------
   For special effects in the woven output, there are commands to help
one change the appearance of operators and identifiers.
Overloading operators
.....................
   A feature common to both C++ and FORTRAN-90 is operator overloading,
the ability to extend or redefine the definition of an operator such as
`.FALSE.' or `='.  FORTRAN-90 even allows one to define new `dot'
operators--for example, one might define the operator `.IN.' to test
for inclusion in a set.  In a nontrivial extension of the original
design, FWEAVE allows one to define how overloaded operators should
appear on output.  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 `@v' control code is used to change the appearance of an
operator.  The format is
     @v new_operator_symbol_or_name "TeX material" old_operator
This means "Display the new operator according to the 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
     @v = "\\Leftarrow" =
Two \Fortran\ examples are
     @v .FALSE. "\.{.FALSE.}" .FALSE.
     @v .IN. "\\in" +
   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.
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 FWEAVE with a
macro-processing facility analogous to that of FTANGLE.  This has not
been done yet (probably it will be someday).  In the meantime, one has
the command `@W', which provides a restricted form of such a facility.
*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 `@W' command is
     @W identifier "replacement text"
This means:  Replace any references to identifier in the woven output
with the replacement text.
   A more restrictive form is
     @W identifier \newmacro
which replaces references to identifier with a call to `\newmacro'.
(Note that there are no quotes in this form.)
   The shortest form is
     @W identifier .
which replaces references to identifier with a call to `\identifier'.
For example, the identifier x normally appears in woven output as
`\.{\Wshort\{x\}}'.  If one says
     @W x .
one will instead get the macro reference `\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.
File: fweb.info,  Node: Info options,  Prev: -!,  Up: Options
Information options
-------------------
   Several of the command-line options can be used to elicit information
about the initial state of FWEB.
   `-@' displays information about the control codes. *Note -AT::.
   `-D' displays information about reserved words.  *Note -D_::.
   `-y' displays default dynamic memory allocations.  *Note -y::.
   `-Z' displays default values of style-file parameters.  *Note -Z_::.
File: fweb.info,  Node: Customization,  Next: Hints,  Prev: Formatting,  Up: Top
CUSTOMIZATION
*************
   The default behavior of FWEB can be changed in a variety of ways.
  1. Unix environment variables (logical variables in VMS) affect path
     or file names.
  2. An initialization file resides in the home directory.
  3. A style file resides in the current directory.
   The initialization file (usually called `.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 FWEB's defaults.  The `-p' option (*note -p::.) provides a
means of incorporating style-file entries into `.fweb'.
   The order of processing is:
  1. Evaluate environment variables.
  2. Read `.fweb'.
  3. Process `.fweb' options beginning with `+'.
  4. Read and process command-line options (except for `-p').
  5. Process remaining `.fweb' options.
  6. Process any `-p' options.
  7. Read and process the style file.
* Menu:
* Environment variables::       Environment or logical variables.
* Initialization::              Initialization file.
* Memory allocation::           Dynamic memory allocation.
* Style::                       Style file.