ifhtml

     START-INFO-DIR-ENTRY
     * Fweb: (fweb).            The Fweb literate programming tool.
     END-INFO-DIR-ENTRY

This file documents FWEB...

Copyright 1993--1998 John A. Krommes

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

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.

Fweb
****

This Texinfo documentation describes Fweb Version 1.61.

       * To learn about new features of this version, see V1.61.

       * For a quick introduction to, and review of the structure of an Fweb source file, see Structure.

       * If you used to receive e-mail information about Fweb but don't any longer, it's probably because you need to update your e-mail address in the fweb-users mailing list.  Subscription instructions can be found in Support.

       * Bug reports and suggestions are much appreciated, but are no longer acknowledged individually.  See Support.

       * The next major release, Fweb Version 2.00, is planned for no earlier than January 1, 2000.

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

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

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

     http://w3.pppl.gov/~krommes/fweb_toc.html.

Other sources of information about Fweb are the archival files of the fweb-users and fweb-installers mailing lists.  To learn how to obtain those, see Support.

If you are learning Fweb for the first time, you will probably find that this (unfinished) manual is not sufficiently pedagogical.  For background, please refer to Knuth's book cited in Intro.  You should also browse through Concepts, in particular Structure.

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

Fweb Copying Permissions
************************

Fweb is ``free.''  This means that everyone is free to use them and free to redistribute them on a free basis.  Fweb operates under the terms of the GNU General Public License; see, for example, Distribution (The GNU Emacs Manual).

Although it is hoped that Fweb will be useful, there is ABSOLUTELY NO WARRANTY.

INTRODUCTION to Fweb
********************

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

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

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

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

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

History of WEB and literate programming
=======================================

(To be completed; see Knuth's book, cited in Intro.)

Features of Fweb
================

Fweb is distinguished from its relatives in several respects:

       * Fweb introduces the concept of a current language (see Languages), so more than one compiler language can be processed in a single Fweb run.  For example, mixtures of C++ and FORTRAN are common in modern scientific programming.

       * Fweb understands the syntaxes of several of the more important compiler languages: C, C++, FORTRAN (both F77 and F90), RATFOR, and TeX.  For other languages, Fweb can work in a language-independent mode that essentially weaves and tangles the source code verbatim, but still provides the user with the powerful WEB features related to TEX documentation, module names, macro processing, etc.

       * Fweb contains a built-in RATFOR (RATIONAL FORTRAN) translator.  See Ratfor.

       * Fweb has a built-in C-like macro preprocessor.  This is especially useful for FORTRAN and RATFOR, which have no predefined preprocessor.  However, certain extensions such as variable numbers of arguments make the Fweb preprocessor sometimes useful even for C and C++. See Macros and Preprocessing.

       * Many aspects of Fweb's behavior, default strings, etc. can be customized by means of setting parameters in a makeindex-like style file (by default, fweb.sty).  See Style.

WEB CONCEPTS
************

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

The Fweb processors: Fweave and Ftangle
=======================================

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

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

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

     test.c: test.web
             ftangle test

     test.o: test.c
             gcc -c test test.c

With this approach, one is not so tempted to edit test.c.

Fweb development is now based on LaTeX; Plain TeX is no longer supported.  For detailed descriptions of the LaTeX support, see LaTeX.

The structure of a web
======================

An Fweb source file is structured into sections, which correspond to logical subunits of the code (either a function or a fragment of a function). Each section consists of three parts, each of which is optional: the

      1. TeX part;

      2. definition part; and

      3. code part.

When Ftangle outputs code, it can combine the code parts of (possibly noncontiguous) sections into larger units called modules, as explained in Modules.

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

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

A simple example
................

A simple example of an Fweb source file consisting of three sections is as follows:

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

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

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

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

     @a
             program main
             call compute
             end

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

     @* \INDEX.

Commands to Fweb are begun by the @ symbol (see AT commands).  In this example, the first command, @n, sets the global language to FORTRAN-77.  One should always begin one's code with a language-setting command.

In this example, the language command is invoked with an optional argument /.  That is necessary in FORTRAN in order to tell Fweb to use the short (single-line) comment form beginning with //, which otherwise conflicts with the concatenation operator. See -n/.

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

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

     @* [INTRO]INTRODUCTION.

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

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

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

The TeX part
............

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

Whenever Fweb is in TeX mode, one can temporarily shift into code mode by enclosing the code within vertical bars.  That code is typeset just like code in the code part (see below), except that newlines are replaced by spaces. Thus, one can say things like

     Consider the C code fragment `|@c for(i=0; i<10; i++){}|', which ...

(If the global language were C instead of FORTRAN, the @c inside the vertical bars would not be necessary.) The ability to switch back and forth between text mode and code mode at will allows for a very convenient and flexible style of exposition.

The definition part
...................

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

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

The code part
.............

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

The limbo section
.................

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

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

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

Modules
=======

The code parts of (possibly noncontiguous) sections can be combined into modules.   For Fweave, this is a logical combination, for purposes of cross-referencing different pieces of the code.  But for Ftangle, the combination is physical; Ftangle's output proceeds module by module.

Modules can be named or unnamed. There is exactly one unnamed module. The fundamental operation of Ftangle is that

     Ftangle outputs the unnamed module.

That output goes to a compilable file with an extension appropriate to the current language.

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

The unnamed module
------------------

The unnamed code module is introduced by the command @a.  Subsequent uses of @a accrete code to the unnamed module. To repeat, the fundamental operation of Ftangle is that

     Ftangle outputs the unnamed module.

Thus, there must be at least one @a in the source file or Ftangle will output nothing.

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

Named modules
-------------

Named modules represent logically-connected fragments of code.

A module name is specified by the construction

     @< Arbitrary TeX text @>

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

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

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

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

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

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

Second, after a name has appeared once in full, it may be abbreviated by a unique prefix followed by three periods, as demonstrated in the above example.  By convention, a complete module name cannot be a subset of another.  For example, @<Test@> and @<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

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

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

Very rarely, one might try the following construction:

     @
     @a
     @< Left side @> = @< Right side @>@;

Here the intent is to construct an assignment statement.  However, this will be flagged as an error because Fweb thinks one is trying to define the named module @<Left side@>, which one shouldn't be doing while in code mode.  To make it work, just put the invisible expression @e (see ATe) before the equals sign.

Phases of processing
====================

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

The phases of Ftangle
---------------------

Ftangle has two phases.  In phase 1, the source file is read; in phase 2, compilable code is written out in the order specified by the web.

More specifically, phase 1

       * discards TeX documentation;

       * tokenizes the source;

       * expands Fweb preprocessor commands such as @#if (see Preprocessing);

       * expands @'...' (see ATquote), @"..." (see ATdquote), and the binary notation 0b... (see C) [in FORTRAN, also the octal notation 0... and the hexadecimal notation 0x...];

       * stores code text in appropriate modules;

       * memorizes macro definitions (@d and @m) (see ATd and ATm).

Phase 2

       * outputs outer macro definitions (@d);

       * outputs the unnamed module (@a);

       * expands Fweb macros (@m);

       * expands built-in macros such as $IF or $PI (see Built-in functions);

       * translates RATFOR statements (see Ratfor).

The phases of Fweave
--------------------

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

More specifically, phase 1

       * tokenizes and stores identifiers and module names;

       * collects cross-reference information (including, in C and C++, the scanning of #include files for typedef and/or class declarations (see -H_);

       * stores limbo text definitions made with @l (see ATl);

       * collects information about overloaded operators (@v) and identifiers (@W).  See ATv and ATW_.

Phase 2

       * outputs limbo text;

       * outputs special TeX macros for overloaded operators;

       * copies TeX material directly to output;

       * treats material between vertical bars (|...|) as code to be typeset;

       * tokenizes and stores contents of each code section;

       * analyzes code syntax and converts it to appropriate TeX macros.

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

       * writes out the Index (INDEX.tex by default, but see Output files and Index params);

       * writes out a list of named modules (MODULES.tex by default, but see Output files and Module params);

       * writes out macros to generate the Table of Contents.  (Table of Contents information is actually processed by LaTeX, not Fweave.  The information is written to the aux file.)

FILES
*****

Fweb works with a variety of files.  File names have the form [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 by system installers in custom.h (see Customization). The character that initiates the file-name extension (normally a period) can be changed with the -E command-line option (see -E_).

Input files
===========

Fweb reads files with a variety of default extensions.

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

     fweb.sty --- Style file (optional; for customizing the behavior of a particular web file or group of files).  See Style.  This file is always in the directory of the web file that is being tangled unless that is changed by environment variable FWEB_STYLE_DIR.  The basic name can be changed by the -z option (see -z). A sample fweb.sty file is provided with the Fweb distribution.

     name.web --- Source file.

     name.ch --- Change file (optional; for making incremental changes to a web source file).  See Change files.

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

     name.hch --- Optional change file for include file.

Automatic file-name completion
------------------------------

Automatic completion of input file names is turned on by the -e command-line option (see -e). When this option is in effect, input file names that include no period (have no extension) are completed automatically according to the contents of the following style-file entries:

     Type of file      Style-file entry        Default

     WEB file             ext.web           web

     Change file         ext.ch            ch

     Include file        ext.hweb          hweb

     Change file for include file   ext.hch           hch

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

Output files
============

Fweave writes a variety of output files.

     name.tex --- Woven output to be processed with LaTeX.

     CONTENTS.tex --- Temporary file that accumulates Table-of-Contents information.  (For LaTeX, the aux file is used instead.)

     INDEX.tex --- Temporary file that stores indexing information.

     MODULES.tex --- Temporary files that stores module list.

The names of the three temporary files can be changed with style-file parameters (see Style).  Commonly, one may put into the style file fweb.sty commands such as

     index.tex "#.ndx"
     modules.tex "#.mds"
     contents.tex "#.cts"

The # is replaced by the root name of the web file.

Ftangle writes files of the form

     name.ext --- Compilable output 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:

     Language   Style-file entry   UNIX default   non-UNIX default

     C             suffix.C      c      c

     C++           suffix.Cpp    C      C

     Fortran--77   suffix.N      f      for

     Fortran--90   suffix.N90    f90    for90

     Ratfor--77    suffix.R      r       rat

     Ratfor--90    suffix.R90    r90   rat90

     TeX           suffix.X      sty     sty

     VERBATIM      suffix.V      mk     mk

For example, to change the default extension for a C++ file from C to c++, put into fweb.sty the line

     suffix.C = "c++"

Change files
============

The primary input to the Fweb processors is the test.web source file. However, a change file test.ch can also be specified.  A change file consists of instances of the following structure:

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

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 .ch is assumed by default.  For example,

     ftangle test test

processes test.web with the change file test.ch.

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

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

RUNNING Fweb
************

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

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

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

Command-line syntax
===================

The command-line syntax is

     {ftangle | fweave} [-option...] webfile[.web] [changefile[.ch]]

A file name is anything that doesn't begin with a -, except that a lone hyphen stands for the special file name stdin, which means `read from the standard input.'  (This should not be used except for very special effects.)

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

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

Command-line options
====================

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

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

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

Negating options
----------------

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

-1: Turn on brief debugging mode (Fweave)
-----------------------------------------

This option tells Fweave to display irreducible scrap sequences.

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

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

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

This brief debugging mode can be turned on more locally by means of the @1 command.  See AT1.

-2: Turn on verbose debugging mode (Fweave)
-------------------------------------------

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

This feature can be turned on more locally by means of the @2 command.  See AT2.

-@: Display the control-code mappings
-------------------------------------

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

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

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

-A: Turn on ASCII translations
------------------------------

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

-B: Turn off audible beeps
--------------------------

Fweb sometimes beeps the terminal when it encounters certain errors.  The -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.)

-b: Number blocks (Fweave)
--------------------------

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

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

The precise form of the block comment that is emitted can be changed by redefining the macro \Wblock in fwebmac.sty.

-C: Set the color mode
----------------------

The option -CN sets the color mode to N, where the color modes are, briefly,

     0
          No color

     1
          ANSI color

     2
          Bilevel

     3
          Trilevel

     4
          User-defined

These modes, and color output in general, are described more thoroughly in Color.

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

-c: Set global language to C
----------------------------

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

-c++: Set global language to C++
--------------------------------

For more information, see the discussion of -c in -c.

-D: Display reserved words
--------------------------

This information option displays the list of reserved words for the language currently in force.  (For the purposes of this option, `reserved words' include ``true'' reserved words such as int; they also include the names of intrinsic functions such as sin and, for FORTRAN and RATFOR, I/O keywords such as IOSTAT.)  Thus, to see the reserved words for RATFOR--90, say

     ftangle -Lr9 -D

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

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

If one says -D*, one will get all reserved words for all languages.

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

-d: Convert do...enddo
----------------------

(This option is obsolete.)

-E: Change the delimiter of a file-name extension
-------------------------------------------------

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

-e: Turn on automatic file-name completion
------------------------------------------

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

             Type of file      Style-file entry        Default
             WEB file            ext.web        web
             Change file         ext.ch         ch
             Include file        ext.hweb       hweb
             Change file
              for include file   ext.hch        hch

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

-F: Compare output files with old versions (Ftangle)
----------------------------------------------------

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

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

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

To implement the renaming, the rename function is used.  That may fail if 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 mv command.  Terminal output indicates the progress of the renaming.  An asterisk following an output file name indicates that rename did not succeed, but the mv command did.

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

-f: Turn off module references for identifiers (Fweave)
-------------------------------------------------------

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

-H: Scan C/C++ include files (Fweave)
-------------------------------------

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

     @c++
     @
     #include <Complex.h>
     Complex z;

the identifier Complex will be properly formatted as a reserved word (in boldface), as though one had said @f Complex int.

In addition to the basic -H, there are several more detailed options:

     -Hx
          Make index entries only for double-quoted include files.

     -HX
          Make index entries for all include files.

     -Hr
          Retain temporary files generated by the preprocessor.

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

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

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

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

To send arguments to the C preprocessor, see -WH_.

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

-h: Get help
------------

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

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

-I: Append to search list for include files
-------------------------------------------

The fundamental search list for include files (read in via @i or @I) is defined by the environment variable FWEB_INCLUDES, which is a colon-delimited list such as

     setenv FWEB_INCLUDES .:/usr/fweb:/other/stuff

The -I option appends to this list.

For information about include files, see ATi.

-i: Don't print @I include files (Fweave)
-----------------------------------------

If a web file is included via @I (see ATI_), for example

     @I formats.hweb

then the -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 of the time.  (C and C++ programmers will find that the -H option substantially reduces the need to include such header files; see -H_.)

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

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

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

-i!: Don't read @I include files
--------------------------------

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

     @I formats.hweb

then the -i! option means to ignore such files completely.  This option is seldom useful; the -i option (see -i) is more often used.

-j: Inhibit multiple includes
-----------------------------

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

-k: Don't recognize lower-case forms of keywords
------------------------------------------------

By definition, in FORTRAN and RATFOR, a keyword is one of the parameters such as IOSTAT used in the parameter list of an I/O statement.  For example,

     open(21, FILE=file_name, STATUS='old', IOSTAT=io_flag)

Such keywords are typeset in typewriter type to better highlight them. In FORTRAN, these keywords are case-insensitive.  However, note that certain of the lower-case forms---in particular, end, read, and write---have other special meanings, and one can in principle use any of these keywords as ordinary variables in other parts of the code; however, Fweb identifiers can have just one meaning throughout the code.  By default, the lower-case forms are also recognized as keywords (except for the three special identifiers just mentioned), so one shouldn't use those as regular variables.  To cause only the upper-case forms to be recognized, use the -k option.

-L: Select global language
--------------------------

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

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

-l: Echo input line
-------------------

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

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

-M: Set output message level
----------------------------

By default, Fweb is relatively verbose; as it proceeds, it prints messages about what files it is reading and writing, numbers of the starred sections, line numbers, etc.  However, different levels of verbosity can be set by the command -Mlevel, where the level may be 0 (least verbose) through 4 (most verbose; the default), as described in the following table:

     0
          Like level 1, but the start-up banner is not printed.  If Fweb runs to completion with no errors, nothing at all will be printed.

     1
          Print only error messages.

     2
          Print error and warning messages.

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

     4
          Print everything.

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

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

Another way of discriminating message types is via color output. See Color.

-m: Define Fweb macro (Ftangle)
-------------------------------

The command-line construction

     -mA(x)=x

defines the Fweb macro A as though the definition

     @m A(x) x

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

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

     -m'A(x)=x'   // A(x) expands to x
     -m'A(x) =x'  // A(x) expands to =x
     -m'A(x)==x'  // Precisely equivalent to the previous example.

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

-m4: Understand m4 built-in commands
------------------------------------

This tells Fweave to properly format the reserved words of the m4 preprocessor.  The use of that preprocessor is not recommended in conjunction with Fweb; use Fweb's built-in C-like preprocessor instead.

-m;: Append pseudo-semicolons
-----------------------------

When -m; is in effect, the construction @; is appended automatically to all Fweb macro definitions.

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

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

-n: Set global language to FORTRAN--77
--------------------------------------

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

See also Languages and Fortran.

-n9: Set global language to FORTRAN--90
---------------------------------------

See Languages and Fortran; see also the discussion of -L in -L_.

-n@;: Supply automatic pseudo-semicolons [FORTRAN]
--------------------------------------------------

(Don't forget that a semicolon has special meaning to UNIX shells, so you'll probably have to quote this command:  -n'@;'.)

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

For free-format FORTRAN-90, when -n@; is in effect (the default), -np is also turned on.  See -np.

For further discussion, see the companion command -n;.

-n;: Supply automatic semicolons [FORTRAN]
------------------------------------------

(Don't forget that a semicolon has special meaning to UNIX shells, so you'll probably have to quote this command:  -n';'.)

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

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

     a = b; c = d

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

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

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

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

       Fixed   Free
     F77   -n;   N/A
     F90   -n;   -n@; -np

-n:: Put statement label on separate line [FORTRAN]
---------------------------------------------------

By default, in FORTRAN statement labels are placed on the same line, and backspaced from, the command that is being labeled, as in

     EXIT: continue

This can look ugly if the label is very long.  The command -n: places the label on a separate line, as is done automatically for RATFOR---e.g.,

     EXIT:
       continue

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

-nb: Number ifs and dos [FORTRAN] (Fweave)
------------------------------------------

In the woven output, extra comments are added to help one correlate the block structure of the code.  For more discussion, see -b.

-nC: Ignore single-line comments [FORTRAN]
------------------------------------------

Ignore, at the input-driver stage, comment lines beginning with C, c, or *.

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

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

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

       * In Fweb, blocks of code should be commented out with the preprocessor commands @#if 0...@#endif; see Temporary comments.

       * Textual comments for documentation should be converted to the standard Fweb commenting style.

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

-np: Print semicolons [FORTRAN] (Fweave)
----------------------------------------

Although the FORTRAN input driver automatically terminates logical lines with semicolons (FORTRAN-77; see -n;) or pseudo-semicolons (FORTRAN-90; see -nAT;) so that the innards of Fweave can process them correctly, the semicolons are not printed by default. To make actual semicolons be printed, use the -np option.

-np is turned on automatically  for free-format FORTRAN-90 when -n@; is in effect (the default).  For more discussion, see -n;.

-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 (as it would be in C).  For example,

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

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

See also -n&.

-n&: Free-form syntax continued by ampersand
--------------------------------------------

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

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

For FORTRAN-90, free-form syntax continued by the ampersand is Fweb's default, so one probably will not need to use -n& explicitly.

See also -n\.

-n/: Recognize short comments [FORTRAN]
---------------------------------------

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

In Fweb, one may always use \/ for concatenation, so there's no penalty for using -n/.

-n!: Make ! denote short comment [FORTRAN]
------------------------------------------

In FORTRAN-90, ! starts a short comment.  However, by default Fweb usurps ! for the logical not, as in if(x != y).  To force it to recognize ! as a comment, use -n!.  However, the recommended style is to use Fweb's standard convention that // denotes the start of a short comment (see -n/).  See also -! and -r!.

In FORTRAN-77, to include the exclamation point inside a string, escape it with a backslash, as in

             s = "A \! inside a string"

This possibly annoying restriction arises because the unduly complicated FORTRAN input driver does some preprocessing of the FORTRAN source before it feeds it to the cores of the processors.

-n): Reverse array indices [FORTRAN] (Ftangle)
----------------------------------------------

This somewhat experimental flag permits FORTRAN programmers to use C-style array indices. Conversions such as the following are made (during the output phase of Ftangle):

     a(k)(i) => a(i,k)
     a(k)(i,j) => a(i,j,k)
     a(k)(j)(i) => a(i,j,k)

[No spaces may intervene between ) and (; effectively, )( is treated as one token for the purposes of -n).] This feature permits convenient definitions of macros that deal with multi-dimensional vectors.

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

     dimension x(0:4)(1:2) // OK
     character*90 ch(4) // OK
     write(6,*) ((x(i)(j),i=1,2), j=3,4) // Will reverse incorrectly.
     c = ch(4)(3:4) // Shouldn't reverse, but will.

One solution, due to Charles Karney, is to insert a space to prevent )( from being recognized as a single token.  However, since ordinary white space is eaten on input, one must resort to something like the following ($UNQUOTE is a built-in Fweb function; see $UNQUOTE):

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

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

-o: Don't overload operators
----------------------------

This option inhibits the operator-overloading feature invoked by the command @v (see Overloading).

-q: Don't translate RATFOR
--------------------------

(This option is obsolete.)

-P: Select TeX processor
------------------------

Say -PT or -PL to inform Fweave that its output will be processed by TeX or LaTeX, respectively.  Beginning with Version 1.50, the default processor is LaTeX (-PL).  If you always use TeX, it's easiest to put -PT into the .fweb initialization file.

Please note that -PT is no longer supported;  Fweb
development is now based exclusively on LaTeX.

-p: Buffer up a style-file entry
--------------------------------

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

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

      1. -p options in .fweb;

      2. entries in the local style file fweb.sty;

      3. -p options on the command line.

-r: Set global language to RATFOR--77
-------------------------------------

See Languages and Ratfor.  See also -L_.

-r9: Set global language to RATFOR--90
--------------------------------------

See Languages and Ratfor.  See also -L_.

-rg: Set goto parameters
------------------------

This obscure option is used for configuring RATFOR (and really should be a style-file parameter).  (Discussion not finished.)

-rk: Suppress comments about RATFOR translation (Ftangle)
---------------------------------------------------------

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

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

For example, one can say -rkrb to suppress comments about the return and break statements.

-rK: Write comments about RATFOR translation (Ftangle)
------------------------------------------------------

This is the negative of -rk (see -rk); it forces comments about particular RATFOR commands.

-r@;: Turn on auto-semi mode using pseudo-semis [RATFOR]
--------------------------------------------------------

Please don't use this option (it may not work).  Insert semicolons by hand in your RATFOR code, just as one does in C.

-r;: Turn on auto-semi mode using actual semis [RATFOR]
-------------------------------------------------------

Please don't use this option (it may not work).  Insert semicolons by hand in your RATFOR code, just as one does in C.

-rb: Number ifs and dos [RATFOR]
--------------------------------

In the woven output, extra comments are added to help one correlate the block structure of the code.  For more discussion, see -b.

-r/: Recognize short comments [RATFOR]
--------------------------------------

The standard Fweb notation for a short comment is // .... However, in RATFOR the // denotes concatenation by default. To make it denote a short comment, use the -r/ option.  For concatenation, use \/.

For an example, see -n/.

-r!: Make ! denote short comment [RATFOR]
-----------------------------------------

See the corresponding discussion of -! in -! and -n!.

In FORTRAN-77, to include the exclamation point inside a string, escape it with a backslash, as in

             s = "A \! inside a string"

-r): Reverse array indices [RATFOR] (Ftangle)
---------------------------------------------

See the corresponding discussion of -n) in -n).

-s: Print statistics
--------------------

-s prints statistics about memory usage at the end of the run.

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

-T: Flag-setting options for Ftangle
------------------------------------

This is a family of options that set miscellaneous flags appropriate only for Ftangle.

-TD: Permit processing of deferred macro definitions
....................................................

Deferred macro definitions are @m (or, equivalently, @#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 -TD option (then be prepared to make some obscure programming errors).

-Tb: Permit built-functions to be redefined
...........................................

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

-Tm: Permit user macros to be redefined
.......................................

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

-Tv: Don't print header info
............................

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

-T%: Don't retain trailing comments (TeX)
.........................................

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

-T#: Don't insert #line command after @%
........................................

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

-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-77, which doesn't allow the underscore. If one says `-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.

-U: Convert reserved output tokens to lower case (Ftangle)
----------------------------------------------------------

Particularly during RATFOR expansion, certain tokens such as DO are output by Ftangle in upper case.  The -U option forces such tokens to be produced in lower case.

-u: Undefine Fweb macro (Ftangle)
---------------------------------

-uA undefines the Fweb macro A previously defined on the command line (or in .fweb) via -m.

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

-V: Print Fweb version number
-----------------------------

This flag requests the startup banner, which includes the Fweb version number, to be printed.  This is usually done anyway, so it is only relevant when the message level is 0 (see -M_).

-v: Make all comments verbatim (Ftangle)
----------------------------------------

By default, comments are not passed to the tangled output.  With -v, all comments are included verbatim in the tangled output.  Since there's generally no harm in this, one might want to put this option into .fweb (see Initialization).

-W: Flag-setting options for Fweave
-----------------------------------

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

-W@: Set module warning flag.
.............................

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

 1. Never used.

 2. Multiple uses.

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

Fweave will always complain about module names that are never defined.

-W1: Cross-reference single-character identifiers
.................................................

By default, Fweb does not index uses of single-character identifiers (following Knuth's original design).  (It does index their definitions.)  To get complete cross-reference information for single-character identifiers, use the -W1 option.

-W[: Process bracketed array indices
....................................

This experimental option makes square brackets behave like parentheses in the context of array indices.

In FORTRAN, Ftangle will just replace the brackets by parentheses. In C, the brackets will be left alone.

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

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

For more information, experts can see fwebmac.web, command \WXA.

-WH: Send additional arguments to the C preprocessor
....................................................

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

     -WH-Dtest1=1 -WH-Dtest2=2
     -WH"-Dtest1=1 -Dtest2=2"

The first form shows that -WH accretes to earlier uses.  The second form shows how to handle embedded blanks (in a UNIX shell). Then, if one were programming in C, use of -H would issue the system command

     gcc -E -P -Dtest1=1 -Dtest2=2

-WdfFlmvw: Don't print various things in woven output
.....................................................

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

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

When these options used, associated cross-referencing is suppressed as well.

-w: Change name of macro package (Fweave)
-----------------------------------------

The option -w means ``Don't print \input fwebmac.sty as the first line of the .tex output file.''  The option -wfname means ``Print \input fname as the first line.'' For example, when working with REVTeX (see REVTeX), one needs to say -wrwebmac.sty.

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

-x: Eliminate or reduce cross-reference information (Fweave).
-------------------------------------------------------------

Cross-reference information (for Fweave) includes the Table of Contents ('c'), the Index ('i'), and the Module List ('m').  The option -x eliminates all of that information.  The option -xletters eliminates the piece of information corresponding to each letter in the list.  For example, -xim eliminates the Index and the Module List.

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

-X: Print selected cross-reference information (Fweave)
-------------------------------------------------------

When used with any of the arguments cim, this option is the opposite of -x.  See -x.

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

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

-y: Allocate dynamic memory
---------------------------

This option changes the default size for a dynamically allocated memory buffer.  The buffers are indicated by a one- or two-character abbreviation such as op.  For example, the option -yop200 allocates 200 units for the op buffer.

To query the default allocations, just say -y.

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

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

-Z: Display default style-file parameters
-----------------------------------------

The information option -Zabc prints to the screen the default contents of the style-file parameters beginning with abc.  Just -Z prints everything.

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

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

The -Z option behaves slightly differently for color escape sequences than for other parameters; see Color.

-z: Change name of style file
-----------------------------

The command -znew.sty changes the default style-file name fweb.sty to new.sty.  The command -z (with no argument) means ``Don't read any style file.''

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

-.: Don't recognize dot constants
---------------------------------

If this command is used, the processors will not understand that constructions such as .LT. are operators in FORTRAN or RATFOR.  This command is useful if one is trying to modernize the source code to use Fweb conventions such as < instead of .LT..

-\: Explicitly escape continued strings
---------------------------------------

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

     "This is \
           \continued";

the effective string is "This is continued" when -\ is in effect.

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

-(: Continue parenthesized strings with backslashes
---------------------------------------------------

This option is like -\ (see -\), but it refers to certain strings that are not normally quoted, such as the arguments of ifelse commands in m4.

-:: Set starting automatic statement number
-------------------------------------------

This option is useful for FORTRAN and RATFOR.  Symbolic statement labels that are defined with the #:0 macro command (Tokens; Fortran), as in @m EXIT #:0, are incremented starting with the default of 90000.  To change this to, e.g., 789, say -:789.

->: Redirect output (Ftangle)
-----------------------------

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

This command has no effect for Fweave.

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

-=: Redirect output (Ftangle)
-----------------------------

Equivalent to -> (see ->), and faster to type on many keyboards.

-#: Turn off comments about line and section numbers (Ftangle)
--------------------------------------------------------------

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

In some cases, bugs in tangled output, particularly from FORTRAN, can be eliminated by using -#.  (But please report the bug anyway; Support.)

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

-+: Don't interpret compound assignment operators
-------------------------------------------------

Both RATFOR and FORTRAN attempt to translate the commands ++, --, +=, -=, *=, and /= into code that behaves as their C/C++ counterparts.  To turn this feature off, use -+.

Notice that in FORTRAN-90 /= is a token for ``not equal,'' so if you want to use that you must turn off the compound assignment operators with use -+.  However, a better solution is to leave them turned on and use Fweb's standard != token for ``not equal.''

See also -ylx.

-/: Recognize short comments (FORTRAN & RATFOR)
-----------------------------------------------

If this command is not used with the FORTRAN-like languages, the // construction will be interpreted as concatenation rather than as the beginning of a short comment.

Concatenation can be signified with Fweb's token\/, so no penalty is incurred for using -/.

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

See also -n/ and -r/.

-!: Make ! denote short comment (FORTRAN & RATFOR)
--------------------------------------------------

This option is not recommended; use Fweb's standard // to begin short comments.

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

             s = "A \! inside a string"

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

     -D displays information about reserved words.  See -D_.

     -y displays default dynamic memory allocations.  See -y.

     -Z displays default values of style-file parameters.  See -Z_.

The -h option reminds one about these information options; it also provides convenient access to the GNU info browser. See -h.

Fweb COMMANDS
*************

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

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

Debugging commands
==================

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

@0: Turn off debugging
----------------------

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

@1: Display irreducible scraps
------------------------------

This is a local version of the command-line option -1 (see -1); refer to that discussion for more information.

@2: Display detailed reductions of the scraps
---------------------------------------------

This is a local version of the command-line option -2 (see -2); refer to that discussion for more information.

Literal control characters
==========================

Several commands insert specific characters.

@@: The character @
-------------------

@@ inserts the single character @.

Don't forget to double the @ even inside strings.  For example, the Fweb source line

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

will be tangled to

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

@|: Literal vertical bar, or optional line break
------------------------------------------------

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

In a code part, @| inserts an optional line break in an expression---e.g.,

     f(a,b,@|c+d,...).

This helps TeX to break the line at an appropriate place.  If the line does not need to be broken, the command does nothing.  [Compare @| with @\ (see ATbs) and @/ (see AT/), which always break the line.]

Beginning of section
====================

Sections are begun by either @* or @.

@ : Begin minor section
-----------------------

@ begins a new minor (unstarred or unnamed) section that is not entered into the Table of Contents.  For example,

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

     @a
     main()
     {}

@*, @*n: Begin major section
----------------------------

@* begins a new major (starred) section (of level 0).  The command must be followed by the name of the section (entry in the Table of Contents), followed by a period.  (If a period appears in the name itself, it must be protected by braces.)

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

If @* is followed by a digit n, it begins a new major (sub)section of level n.  This is also entered into the Table of Contents. Thus, the complete syntax to begin a major section is

     @*n [Short name]Full name.

For example,

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

     @a
     main()
     {}

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

     @a
     get_input()
     {}

For LaTeX, the highest permissible major level is 2 (a subsubsection).

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

Fweave converts @* commands to section numbers.  For a discussion of section numbering, see Numbering.

Beginning of code part
======================

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

@<: Begin module name
---------------------

@< begins a module name, which has the form @< TeX text @>.  (Module names inside Fweb macro definitions begin with @#, not @<.)

@>: End module name
-------------------

@> ends a module name, of the form @< TeX text @>.

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

@A: Begin code part of unnamed section
--------------------------------------

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

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

For more discussion of the distinction between @A and @a, see ATa.

@a: Begin code part of unnamed section, and mark
------------------------------------------------

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

     @a == @A@[

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

     @c
     @
     @a
     int
     subrtn()
     {}

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

     @c
     @
     @A
     x = y;

If one had used @a here, the x would have been marked as defined here, which is not what one wants.

Control codes b--z
==================

@B: Suppress insertion of breakpoint command
--------------------------------------------

This is for detailed debugging of Fweb codes.  It inserts a left brace and suppresses the insertion of a breakpoint command.  See the discussion of @b in ATb.

@b: Insert a breakpoint command
-------------------------------

(Discussion to be finished.  Useful only for very intimate debugging of Fweb codes.  In these days of safe sex, such intimacy may not be desirable.)

See also ATB_.

@c: Set language to C
---------------------

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

See Languages and C.

@c++: Set language to C++
-------------------------

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

See Languages and Cpp.

@D: Define outer macro
----------------------

This command begins the definition part.

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

     @D A 1

will be tangled to the beginning of the output file as #define A 1.

@d: Define outer macro, and mark
--------------------------------

This command begins the definition part.

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

     @d == @D@[

(see AT[).

The distinction between @d and @D is analagous to the distinction between @a and @A.  See ATa.

@E: Treat next identifier as ordinary expression (Fweave)
---------------------------------------------------------

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

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

@f: Format identifier or module name
------------------------------------

This command begins the definition part.

The construction

     @f identifier old_identifier

makes Fweave treat identifier like old_identifier.  For example,

     @f mytype int

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

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

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

     $_BINOP_
     $_COMMA_
     $_EXPR
     $_EXPR_
     $EXPR_
     $UNOP_

These are useful for dealing with certain macro constructions.  For example,

     @f PLUS $_BINOP_
     @m PLUS +
     @m ADD(x, y) ((x) PLUS (y))

Without the format command, the ADD macro will pretty-print without spaces before and after the PLUS.

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

     @f `TeXchar new_cat_code

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

@i: Include file (unconditional)
--------------------------------

If one says

     @i test.hweb

the 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 FWEB_INCLUDES environment variable and/or the -I command-line option. See Environment variables and -I_.

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

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

Include commands may be nested to a depth set by the option -yid.  See -yid.

In the woven output, if a section comes from an include file, the name of the include file is printed in square brackets as the first text of the TeX part.  To inhibit printing of that name, say

     \def\WIF#1{}

in the limbo section.  To change the way that name is formatted, redefine the macro \WIFfmt, whose single argument is the name of the include file.  (It is not called when there is no current include file.)  The default definition is

     \def\WIFfmt#1{[{\tt#1}]}

@I: Include file (conditional)
------------------------------

This command behaves like @i if the command-line option -i is not used.  If it is used, then the contents of the included file is not printed in the woven output. See -i and -i!.

@K: Extract global RCS-like keyword
-----------------------------------

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

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

     @z
     $Id:  test $
     @x

     @c

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

     @ \ID.  This is a @K Id @>.

will expand into

     @c

     @ \ID.  This is a test.

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

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

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

For Ftangle, the built-in function $KEYWORD (see $KEYWORD) behaves essentially as does @K, except that it is expanded during output, not input.  Fweave does not expand $KEYWORD.

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

@k: Access local RCS-like keyword
---------------------------------

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

@L: Set language
----------------

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

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

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

@l: Specify limbo text
----------------------

This command begins the definition part.

Limbo text is material that Fweave should output before the start of the first section. For example,

     @l "\\def\\A{abc}"

Note that \\ stands for a backslash.  In general, characters must be escaped just as in C [so that one can include things like \n (newline) in the definitions].

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

@M: Define Fweb macro
---------------------

This command begins the definition part.

For a detailed discussion of Fweb macros, see Macros.

@m: Define Fweb macro, and mark
-------------------------------

This command begins the definition part.

@m defines an Fweb macro, and also marks the next identifier as defined here.  It is equivalent to

     @m == @M@[

(see AT[).

For a detailed discussion of Fweb macros, see Macros.

The distinction between @m and @M is analagous to the distinction between @a and @A.  See ATa.

@N: Turn on N mode
------------------

This command must appear before the code part.  Generally, this means immediately before @a.  Do not use this command in limbo; use @Lv instead.

The N mode invokes language-independent behavior within the scope of a particular language.  The scoping rules are the same as for language changes; i.e., using @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 Ftangle and tells Fweave to turn off ``pretty-printing'' (instead, the output is printed in typewriter type within a \begin{verbatim}...\end{verbatim} environment).

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

 1. Fweb macros and built-in functions will normally be expanded even in the N mode.  To inhibit expansion of a particular identifier, place @! before the identifier.  For example,

          @
          @m A 1
          @N
          @a
          @!A = A;

     expands to A = 1.

 2. Blank lines are significant.  The N mode is ended by the appearance of the @* or @ 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 @%%, which deletes the remainder of the current line and all immediately following empty lines.  For example,

          @
          @N
          @a
          x;@%%

          @ Next section.

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

 4. A  module name must be within the scope of an @N the first time the name is seen, if it is ever to be within such scope.  Thus, the following does not work properly:

          @ Consider the module @<Test@>.  (Not yet within scope of \.{@N}.)
          @N
          @a
          x;
          @<Test@>@;
          y;

     What happens is that the N mode is not restored after the code-part use of @<Test@>.  This is a bug.  There are very tricky design issues to be dealt with here.

@n: Set language to FORTRAN--77
-------------------------------

FORTRAN-77 is Fweb's default language, so this command is usually not strictly necessary.  However, it is good practice to include it, so a user looking at the web file can tell immediately what language it is supposed to process.

For more discussion of languages, see ATL_ and Languages.

@n9: Set language to FORTRAN--90
--------------------------------

For more discussion of languages, see ATL_ and Languages.

For hints about Fweb programming in FORTRAN, see Fortran.

@O: Open output file (global scope)
-----------------------------------

A statement of the form

     @O new_output_file_name

changes the name of Ftangle's output file.  This change remains in effect for the duration of the file, or until another @O is encountered.  (If that occurs, the previously open file is closed.)

This command is expanded during output, so it must appear in the code part.

For an example of using the @O command to produce both C header files (.h) and source files (.c), see the discussion in Outer macros.

To change the name of the output file locally (for just the present section), see ATo.

@o: Open output file (local scope)
----------------------------------

This behaves like @O, except that the new file name is in effect only for the current section.  A subsequent @o issued in a different section but for the same file name accretes material to the file.

An annoying problem arises in C programming when @os are used to create multiple source files that are subsequently compiled under the control of a Makefile.  Remember that by default line-number information is written into the C files.  This means that a change in the web file code for one source file can affect all of the others, because the line numbering in the web file changes.  Therefore, a trivial change to the code for just one source file can cause all of the others to be recompiled.

As long as one desires debugging information relative to the original web file, there is really no solution to this problem; one needs the proper line information in each file in order to work with the debugger, so if line numbers change the sources must be recompiled.  One can, of course, turn off the line numbering with the command-line option -# (see -#), but then debugger statements will refer to the tangled C code, which is undesirable.  A better partial solution is to use @q (see ATq) to turn off the line numbering for output code that is currently stable.  In the following example, the code for each file is put into a module, then the modules are output in the unnamed section; it is assumed that the programmer is currently making changes to the code for file2.c:

     @
     @a
     @q0
     @o file1.c
             @<File 1@>@;
     @q1
     @o file2.c
             @<File 2@>@;
     @q0
     @o file3.c
             @<File 3@>@;

For very large projects, another solution is to maintain multiple web source files.  To avoid losing the substantial benefits of the automatic index, refer to the discussion in Merging indexes to learn how to create a master index that contains information about several web files.

@q: Turn off module and line info locally
-----------------------------------------

The command-line option -# (see -#) turns off comments about module and line numbers globally, for the entire code.  However, in some cases one wants to turn that off in just a small block of code.  One important example arises in FORTRAN.  Consider

     @
     @a
           x = @<Some action@>

     @
     @<Some action@>=
     y + z

This example will tangle to something like

           x =
     C* 1: *
     *line 20 "test.web"
           y + z
     C* :1 *
     *line 5 "test.web"

Unfortunately, the information comments have created invalid code that will not compile.

The @q command solves this problem by turning off or on the information comments locally.  @q0 turns them off; @q1 turns them on.  Thus, if one rewrites the above example as

     @
     @a
     @q0
           x = @<Some action@>
     @q1

it will tangle to

           x = y + z

as one desires.

For another use of the @q command, see ATo.

@R: Treat next identifier as integer-like reserved
--------------------------------------------------

word (Fweave)

For formatting purposes, treat the next identifier as an integer-like reserved word.

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

@r: Set language to RATFOR--77
------------------------------

See ATL_ and Languages.

@r9: Set language to RATFOR--90
-------------------------------

See ATL_ and Languages.

@u: Undefine outer macro
------------------------

This command begins the definition part.

@u is the inverse of @d.  For example, in C the command @u A tangles to #undef A.

@v: Overload operator
---------------------

This command begins the definition part.

@v is used to change the woven appearance of an operator.  If one defines a new operator, for example by a statement such as

     interface operator(.BETA.)

in FORTRAN-90, one should also use an @v in the definition part---for example,

     @v .BETA. "\\beta" +

For a detailed discussion of overloading (the output appearance of) operators, see Overloading.

@W: Overload identifier
-----------------------

This command begins the definition part.

For a detailed discussion of overloading (the output appearance of) identifiers, see Overloading.

@x: Terminate ignorable material, or begin material to be changed
-----------------------------------------------------------------

In a change file, this command begins material to be changes; see Change files.

In web source files, this command has a different use; see the discussion of the @z command (see ATz).

@y: Begin change material
-------------------------

The @y command is permitted only in change files.  See Change files.

@z: Begin ignorable material, or terminate change
-------------------------------------------------

Fweb files may begin with the construction

     @z
     .
     .
     @x

where the @z occupies the very first two characters of the file, and where the @z and @x must begin in column 1. Material between the @z and @x is pure commentary and is ignored by both processors, with one exception.

The exception is that an RCS-like line (RCS stands for ``revision-control system'') with syntax

     $Keyword: Text of Keyword $

(at least one blank after the colon, and at least one before the last dollar sign; UNIX users, see man ident) is parsed, and the text of the Keyword is made available to the control codes @K (see ATK_) and @k (see ATk) as well as to Ftangle's built-in function $KEYWORD (see $KEYWORD.

A distinction is made between keywords that are found in the ignorable commentary at the beginning of the master web file, which are called global keywords, and ones that are found at the beginning of files included via @i, which are called local keywords.

The commands that access RCS-like keywords function as follows:

       * $KEYWORD(Keyword) accesses a global keyword.  It is a built-in function that is expanded by Ftangle (during output) into the quoted character string "Text of Keyword".

       * @K and @k are expanded during input.  @K accesses a global keyword, whereas @k accesses a local keyword.

       * In the limbo section or a TeX part, Fweave will expand @K
          Keyword @> into Text of Keyword (without the surrounding quotes), and similarly for @k.  (The intention is that the expanded text can be used as bodies of TeX macros.) Fweave will also print the values of global keywords at the end of its output, whether or not they are referenced by @K.

       * Elsewhere Fweave will just print the keyword name itself, surrounded by double angle brackets.  If the keyword was local (@k), the brackets will carry the subscript 0.

       * Ftangle treats the global command @K Keyword @> essentially like it does $Keyword, except that the construction is expanded on input rather than output.

       * Ftangle expands the command @k keyword @> on input, generating a quoted string containing the value of the local keyword.

The command @z is also used in change files to end a change. See Change files.

Conversion to ASCII
===================

Several commands are useful for generating machine-independent code. For example, Fweb works internally with the ASCII character set, so uses these commands heavily to convert from the possibly non-ASCII native character set of the machine on which Fweb is running.

@': Convert character to ASCII
------------------------------

The construction @'c' converts c to its ASCII value.  In C and C++, it is converted to octal; for example, @'A' is output as 0101. In FORTRAN and RATFOR, it is converted to decimal; the previous example would be output as 65.

If the native character set of one's machine is ASCII, the conversion will not be done unless the -A command-line option is used. See -A_.

@": Convert string to ASCII
---------------------------

The construction @"abc" converts the enclosed string to its ASCII representation.  For example, in C and C++ @"abc" will be output as "\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 ASCIIstr('abc').  The user is responsible for defining the function ASCIIstr.  The name of this function can be changed by the style-file entry ASCII_fcn. See ASCII_fcn.

If the native character set of one's machine is ASCII, the conversion will not be done unless the -A command-line option is used. See -A_.

Forward referencing
===================

@[: Mark as defined
-------------------

This command marks the next (non-reserved) identifier that appears after the @[ as being defined in the current section.  It is usually issued automatically; for example, @a is equivalent to @A@[, @d is equivalent to @D@[, and @m is equivalent to @M@[.

If the appropriate style-file parameter mark_defined.??? is 1, this command causes any appearance of the identifier to be subscripted with a section number.  For more information, see Subscript params.

The utility of this command can be seen from the characteristic construction

     @ This is section 5.
     @a @% Issues an implicit @[, which marks |test| as defined in section 5.
             subroutine test
             ...
             end

     @ This is section 6.
     @a
             program main
             call test // This will print as $|test|_5$.
             end

The @[ command should be distinguished from @_ (see AT_).  The latter causes the index entry for the identifier to be underlined; the former possibly causes the identifier to be subscripted by a section number.  One may wish to turn off the subscripts because they become too cluttered; however, the underlined index entries remain useful and unobtrusive.

Comments
========

Fweb supports a variety of commenting styles borrowed from C, C++, and TeX.  For more discussion, see Comments.

@/*: Begin long verbatim comment
--------------------------------

The following comment is copied to the tangled output.  (By default, comments are not copied.)  If you desire all comments to be so copied, use -v.  See -v.

@//: Begin short verbatim comment
---------------------------------

See the discussion of @/* in AT//.

@%: Ignorable comment
---------------------

If any line in a web source code contains the command @%, 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 @%%.  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.  See ATN_.

Line-numbering problems can arise when these commands are used.  For a discussion, see -T#.

@?: 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 cdir_start. See Miscellaneous params.

@(: Begin meta-comment
----------------------

Material between @( and @) is treated in the N mode. For example,

     @(
     Comment 1
     Comment 2
     @)

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 meta (see Miscellaneous params).

@): End meta-comment
--------------------

See the discussion of @(, ATlp.

Special left brace
==================

The command @{ is useful in C/C++ programming to beautify some of the pretty-printing.  It translates into a left brace, but also suppresses the automatic insertion of newlines into the subsequent function body or block.  This is desirable for very short functions, such as simple constructors in C++.  For example,

     class C
     {
     private:
             int i;

     public:
             C(int i0) @{i = i0;}
     }

Here the function will be typeset as

     C(int i0)
       { i = i0; }

rather than the default

     C(int i0)
       {
       i = i0;
       }

Index entries
=============

Although most information for the Index is gathered automatically, in some situations it must be done by hand.

@_: Force index entry to be underlined
--------------------------------------

This command applies to the next identifier that appears after the @_.  The index entry for that identifier will be underlined. (By convention, this means `defined' or `declared'.)

This command is usually issued automatically.  For example, the index entries for the variables i and j in the C statement int i, j; will be underlined, since Fweave understands enough of the syntax to know that variables are being defined.  Macro definitions (begun by @D or @M) will also be underlined automatically.

@-: Delete index entry
----------------------

This command applies to the next identifier that appears after the @-; it prevents an index entry associated with that identifier from being made.  This might be useful when the N mode is in effect.

@+: Force index entry
---------------------

This command applies to the next identifier that appears after the @+; 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.

@^: Make index entry (Roman type)
---------------------------------

To insert one's own index entry in Roman type, say  @^My entry@>.

@.: Make index entry (typewriter type)
--------------------------------------

To insert one's own index entry in typewriter type, say  @.My entry@>.

@9: Make index entry (user-defined format)
------------------------------------------

The construction @9Text@> is used to create an index entry in a format defined by the user.  It is associated with the macro \9, which will be called during TeX's processing of the Index as \9{Text}.  The user must define \9 according to the format

     \def\9#1{...}

where argument #1 is the text between @9 and @>. For example, to print that text in a sans serif font, say

     \def\9#1{{\sf #1}}

(Note the extra level of braces to prevent the font command from propagating.)

Control text
============

Control text is material terminated by @>; it must be all on one line and must not contain any @s.

@t: Put control text into a TeX \hbox (Fweave)
----------------------------------------------

When Fweave sees the command @tcontrol text@>, it packages the control text into an \hbox and ships it to the output.  This command is ignored by Ftangle.

@=: Pass control text verbatim to the output
--------------------------------------------

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

Spacing
=======

The spacing commands are used to refine Fweave's pretty-printed output.  Generally it's not necessary to bother with these until one is putting the final touches on a code.

@,: Insert a thin space
-----------------------

Extra spacings are sometimes necessary when working with unusual macro constructions.  @, inserts a thin space, analogous to TeX's \,.

An example where explicit spacing would be necessary is as follows:

     @c
     @
     @m OP +
     @m A(x,y) x @, OP @, y

     @a
     z = A(a, b);

Without the @,'s, the body of the A macro will weave as the unappealing xOPy.  This occurs because although OP is defined to be a binary operator, Fweave thinks of it as just a mere expression, and one of its fundamental production rules is to concatenate expressions with no intervening expressions.

This demonstrates that situations arise in which one needs to override Fweave's default processing.  But for the above example, there is actually a better solution.  Instead of using the @,'s, include the format command @f OP $_BINOP_.  See ATf.

@/: Force a line break, preserving indentation.
-----------------------------------------------

This command is used to override Fweave's natural inclinations. For example, if one wants each piece of a declaration to appear on a separate line, one can say

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

This command preserves the natural indentation that would have happened if Fweave or LaTeX had broken a long line spontaneously.  Thus, the declared variables are indented in the above example.  To remove that indent, use @\ instead.  See ATbs.

Try to use the line-break commands sparingly---i.e., let Fweave do the work. Often, if lines run together in an unexpected or unreadable way, it's because Fweave wasn't able to parse the relevant block of code, perhaps because it didn't understand that some variable in an include file has a special meaning.  In such cases, trying to fix things with @/ is the wrong solution.  Either use @f (see ATf) or -H (see -H_).

Distinguish the @/ command from @| (see AT|), which inserts an optional breakpoint into an expression.

@\: Force a line break, then indent
-----------------------------------

The @\ command behaves like @/ (see AT/), except that it backspaces one notch after the line break.  This usually has the effect of undoing the natural indentation that would have been inserted had a long line been spontaneously broken.  One common case where the @\ command might be used would be to put the return type of a C function on a separate line:

     int @\
     main()
     {}

It would be nice to have Fweave do that automatically. Unfortunately, the syntax of a function isn't recognized until the opening braces are sensed; by that time, the declaration part of the statement has already been processed.  This is one example of the fact that the Fweb processors are much less intelligent and sophisticated than language compilers.  A clever (and simple) idea for getting around this kind of problem is lacking at this point.

@|: Literal vertical bar, or optional line break
------------------------------------------------

In the TeX (documentation) part of a section, @| inserts a vertical bar.  Here's a LaTeX example:

     \begin{verbatim}
       The constructions @|x@| and |x| are very different.
     \end{verbatim}

You might wish to try this out to see what Fweave produces.

In a code part, @| inserts an optional line break in an expression.

@#: Blank line
--------------

@# forces a line break with some extra vertical white space. However, note that blank lines in the source are significant, so this command should seldom if ever be necessary.

if @# is immediately followed by a letter (e.g., @#if), it is assumed that a preprocessor command is beginning.  See Preprocessing.

@~: Cancel line break
---------------------

@~ is analogous to TeX's ~ (tie); it prevents a line break, which Fweave usually inserts after each complete statement it recognizes.  For example,

     printf("Working..."); @~ fflush(stdout);
     x = y; @~ break;

@&: 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 an Fweb macro that should itself be expanded.

Pseudo (invisible) operators
============================

Pseudo- or invisible operators are ignored by Ftangle and not printed by Fweave; however, they retain grammatical significance that helps out Fweave in its attempts to understand the syntax.

@e: Pseudo-expression
---------------------

@e is an invisible expression (`pseudo-expression') (see Pseudo-operators).  It is sometimes useful in situations where Fweave's pretty-printing has broken down because it didn't properly understand the language syntax. If, for example, Fweave failed to properly parse the C statement

     p = (int (*))q;

one might get things to work properly by saying

     p = (int (*@e))q;

In this particular case, one is patching up a deficiency (all right, a bug) in Fweave's ``production rules.''  (This particular bug may no longer exist.) However, there are other situations in which the use of @e might be necessary.  Consider, for example, the C macro definition

     #define A(x) = x

Here the replacement text of the macro is = x, which by itself is not a valid construction in C.  When the -1 or -2 options are used, Fweave will report an ``irreducible scrap sequence'' in this situation (although it may typeset it correctly anyway).  To eliminate the warning message, say instead

     #define A(x) @e = x

Now the fragment @e = x is interpreted as a valid expression.

@;: Pseudo-semicolon
--------------------

@; is an invisible semicolon.  These are often used in C programming to terminate a module name that expands to a compound statement.  Carefully compare the uses of @; and ; in the following example:

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

     @ This compound statement ends with a brace, but is used as an
     expression above.
     @<Com...@>=

     {
     x;
     y;
     }

     @ This fragment does not end with a semicolon, so one must be
     supplied above.

     @<Sim...@>=
     z

Here is a case for which the pseudo-semicolon is not necessary.  Consider

     @c
     @ The code fragment |x = y| ...

If the -1 is turned on, one might think that Fweave would report an ``irreducible scrap sequence'' because x = y is an expression but not a complete statement.  (Turning on -2 demonstrates this.)  However, it is not necessary to say |x = y@;| because the warning message is not issued if the parsing reduces to just one unresolved scrap.

On the other hand, |goto done| does not reduce to just one
unresolved scrap, so say |goto done@;| in cases such as this.
See Pseudo-operators.

In some situations, pseudo-semicolons are inserted automatically.  An important case is free-format FORTRAN-90.  There the language syntax says that newlines terminate statements (except when there's a trailing ampersand).  However, newlines are thrown away before tokenized text is seen by Fweave's parser (and in any event would just be interpreted as white space).  Therefore, by default newlines that terminate statements are replaced by pseudo-semicolons, so the parsing proceeds correctly.

In the FORTRAN-90 case, one could also insert pseudo-semicolons or actual semicolons by hand, and some users prefer that.  The possibilities are controlled by the options -n@; (see -nAT;) and -n; (see -n;).

@:: Pseudo-colon
----------------

@: is an invisible colon (see Pseudo-operators). It can be helpful in formatting certain C constructions correctly.  For example, if one has a named module defined as

     @<Cases@>=
     case 1:
     case 2:
     case 3@: @;

then one can use it as a case construction followed by the usual colon, as in

     switch(c)
             {
        @<Cases@>:
             stuff;
             break;
             }

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

COMMENTING STYLES
*****************

Fweb allows a variety of commenting styles. The visible comments are in the font \cmntfont, which defaults to \mainfont, a ten-point Roman font.

Invisible comments
==================

@z...@x
     If a source or include file begins with @z (in the very first two characters of the file), then all material is skipped until and including a line beginning in column 1 with @x [except that lines of the form $Keyword: text of keyword $ are processed; see $KEYWORD, ATK_ (source files), or ATk (include files)].

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

Visible comments
================

/* ... */ is a long comment (it may extend over several lines).

// ... is a short comment (terminated by the next newline).

@(...@) is a meta-comment.  Meta-comments are a localized form of the N mode (see Languages).  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. See 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-person'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; they are only marginally supported.  Use ordinary long comments instead.  Inside of them, use the various powerful features of TeX or LaTeX (such as \halign or \begin{verbatim} ... \end{verbatim}) to format your comment appropriately.

Temporary comments
==================

During development, one frequently desires to temporarily comment out a section of code.  C programmers sometimes try to do this by enclosing the code in /*...*/, but this is not good style for several reasons.  First, it is impossible if the code itself includes comments, since comments do not nest in C.  Second, Fweave will treat the commented code as TeX rather than C code and will (at best) format it very poorly.  In fact, LaTeX will frequently complain, because the commented code might contain characters such as underscores that TeX expects to be in math mode.  (Those are dealt with automatically when Fweave is in code mode.)  The trivial example /* a_b; */ is sufficient to illustrate this point.

The proper way of commenting out sections of code is to use preprocessor constructions: #if 0...#endif in C, or more generally @#if
0...@#endif (usable in all languages).  (The Fweb preprocessor is described in Preprocessing.)  With this method, there is no trouble with nested comments, and Fweave will continue to format the code as code, so the documentation will make sense.

For FORTRAN programmers converting an existing code to Fweb, the -nC option (see -nC) may be helpful.

MACROS and PREPROCESSING
************************

Fweb offers a built-in preprocessor facility, especially useful for FORTRAN programmers.  It is closely patterned after the C/C++ preprocessor, but with some extensions such as variable numbers of arguments.  In addition, there are some built-in functions that provide functionality that cannot be emulated by user-defined macros.

When working with a language such as C that has its own preprocessor, the question arises when to use that and when to use Fweb's facilities.  The answer generally comes with experience.  Remember that Fweb's macros have been expanded by the time the tangled output file is produced, whereas language-specific preprocessor commands are just passed through to that file.

If you're a FORTRAN programmer, strongly consider the use of Fweb's macro facilities; they will simplify your present and future life by creating more legible codes and reducing programming errors by eliminating redundant pieces of code.  C/C++ programmers may also appreciate the preprocessor extensions.

In addition to conventional macro processing, Fweb also offers the convenience of certain built-in functions that behave in many ways like macros.  As a trivial example, the value of PI is available through the built-in function $PI. Built-in functions are described in Built-in functions.  They can be useful to programmers in all languages.

Fweb recognizes two kinds of macros:  outer macros, and WEB
macros (inner macros).  Control codes associated with either of these kinds normally begin the definition part.  However, Fweb macros are sometimes allowed in the code part as well; see FWEB macros.

Macros are expanded by Ftangle only; Fweave merely prints them as they occur in the source file.

Outer macros
============

Outer macros provide a shorthand way of invoking macro definitions in the source language; they are not expanded by Fweb.  Outer macros are defined by @d (see ATd) or @D (see ATD_).  They may be placed in any definition part.  Ftangle collects them during phase 1; during phase 2, they are simply copied in order of their appearance to the beginning of the output file.  This is most useful for C or C++ codes; it's a quick way of typing #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. See Miscellaneous params.

Outer macros can be undefined by @u.  The translation is controlled by the style-file parameter outer_undef. See Miscellaneous params.

The default behavior, in which the outer macro definitions are just copied to the top of the output file, is fine for simple applications. However, often C programmers prefer to maintain their macro definitions in a header file such as test.h.  One way of accomplishing this is to redirect Ftangle's output from the command line, as in ftangle test -=test.h, then use an @O command immediately after the first @a in the web file to open up test.c.  A more complicated variant of this allows additional information to be placed into the header file, as in the following example:

     @c
     @* INTRO.
     We assume command-line redirection into \.{test.h} (`\.{-=test.h}').

     @d A 1 // This will go into \.{test.h}.

     @a
     @<Header material@>@; // Also goes into \.{test.h}.
     @O test.c // Remaining unnamed sections go into \.{test.c}.

     @ Header material may be defined as needed throughout the code, but
     with this design it will all go into \.{test.h}.

     @<Header material@>=

     @<Includes@>@;
     @<Typedefs@>@;
     @<Global variables@>@;

Fweb macros
===========

Fweb macros (sometimes called inner macros) are defined by @m (see ATm) or @M (see ATM_).  These should normally be placed in the definition part, as in

     @n
     @ Documentation...

     @m CUBE(x) (x)**3

     @a
             z3 = CUBE(x) + CUBE(y)

(the appearance of an @m in the documentation part begins the definition part).  They are collected during Ftangle's phase 1 and effectively placed at the top of the unnamed section, so they are all known during the output in phase 2.

In unusual situations when macros are being conditionally defined and/or undefined, the order of processing a macro definition becomes significant.  If the command-line option -TD is used, then Fweb 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.

The use of deferred macros is highly discouraged, for the following reason.  Fweb macros are often used in conjunction with the Fweb 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.

Various features of Fweb macros
-------------------------------

       * Fundamentally, Fweb macros follow the syntax for ANSI C.  There are also a few extensions, notably the possibility of variable (optional) arguments (see Variable arguments) and some additional preprocessing tokens (see Tokens).

       * Adjacent strings in macro text are automatically concatenated.

Fweb macros with variable arguments
...................................

An important extension to the ANSI-C syntax is to allow macros with variable (optional) arguments. Fweb macros with a variable number of arguments are indicated by an ellipsis, as in

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

The tokens #0 (number of variable arguments), #n (value of the nth optional argument), and #. (comma-delimited list of the optional arguments) are useful in this context.

Recursion
.........

ANSI C does not permit recursive macros (for good reason).  Thus, in the example

     @m recurse recurse

the identifier recurse simply expands as `recurse', not as an infinite loop.  However, in Fweb recursion may be useful in conjunction with some of the built-in functions (see Built-in functions).  To permit a macro to be recursive, say @m*.

No formal support is provided for recursive macros!  If they don't work, or suddenly stop working in a new release, you're on your own!

Protecting macros against redefinition
......................................

Normally an Fweb macro can be redefined at will.  The example

     @m PI 3.14159
     @m PI (-3)

is permissible, but probably not a good idea.  If you want to ensure that a crucial macro definition is never redefined inadvertently, say @m!, as in

     @m! PI 3.14159

That is called protecting the macro.

Fweb's built-in functions and macros (beginning with $) are protected by default; see Protection.  To override that protection, use the command-line options -Tb (-Tb; for built-in functions) or -Tm (-Tm; for macros).

Special tokens
--------------

The following special tokens may be used in the text of Fweb macro definitions:

ANSI C-compatible tokens
........................

      ##          --- Paste tokens on either side to form a new identifier.
      #parameter  --- Convert parameter to string (without expansion).

For example,

     @m FORTRAN(type, name) type _##name()
     @m TRACE(where) puts("At " #where)
     @a
     FORTRAN(int, fcalc); // Expands to int _fcalc();
     TRACE(predictor); // Expands to puts("At " "predictor");

Extensions to ANSI C macro syntax
.................................

The most frequently used extensions are the following ones associated with variable arguments: #0, #n, and #.. FORTRAN-77 users should also employ #:0 to allow symbolic rather than numeric statement labels.  Try not to use the other extensions; they are experimental, complicated, and unlikely to work in all situations.

In the following list, the forms #{n} and #[n] may not work correctly in complicated situations.  This is a design deficiency that may be corrected someday.

     #*param
          Like #parameter, but pass a quoted string through unchanged.

     #!param
          Don't expand argument.

     #'param
          Convert parameter to a single-quoted string (no expansion).

     #"param
          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 nth argument (including the fixed ones), counting from 1.  (The argument inside the brackets may be a macro expressions.

     #.
          Comma-separated list of all variable arguments.

     #:0
          Unique statement number (expanded in phase 1).

     #:nnn
          Unique statement number for each invocation of this macro (expanded in phase 2).

     #<
          Begin a module name.

     #,
          Internal comma; doesn't delimit macro argument.

A few examples of the more important of these tokens are as follows:

     @c
     @m FPRINTF(fmt,...) fprintf(fp,fmt,#.)
             // Use the whole list of variable args.
     @m B(...) printf("There were %i arguments\n", #0)
             // Use the number of var args.

     @n
     @
     @m DONE #:0 // Symbolic statement label in FORTRAN.
     @a
             goto DONE
             ...
     DONE:
             call endup

Built-in functions
------------------

Built-in functions behave in most ways like macros.  In some cases they actually are macros, but other times they implement functions that a user could not define.  They all begin with a dollar sign and are in upper case.

In using these built-ins, confusion may arise regarding the order of expansion of various arguments.  When they are implemented as macros, they are subject to the same ANSI-C preprocessor rules as other Fweb macros, which is that all arguments are fully expanded before generating the replacement text of the macro.  When they are directly implemented as a primitive function, however, that rule may not apply. For example, $IF expands only its first argument during its first pass of processing; depending on the results of that expansion, it then expands either its second or third argument, but not both.

The built-in function $DUMPDEF can be used to understand and debug the action of the built-in functions.  See $DUMPDEF.

In the original Fweb design, built-in functions began with an underscore.  This usage conflicts with the conventions for reserved words in ANSI C, and has been eliminated.  All Fweb built-ins
now begin with a dollar sign.

No user-defined macro should begin with a dollar sign!  It might interfere with the functioning of some internal built-in function.

Strings and quotes
..................

Several of the built-in functions expect or return a string argument. Examples include $STRING (see $STRING), $UNQUOTE (see $UNQUOTE), and $UNSTRING (see $UNSTRING). In understanding the operation of those functions, it is important to understand just what a string means in the Fweb context.  As usual, it is a vector of characters.  However, those need not be delimited by quotes, although they may be.  Internally, a string is represented by the construction sqc...cqs, where s is a special string delimiter never seen by the user, q is an optional quote character (either single or double quote depending on the language), and c is an ordinary character.  Whether or not the quotes are present, the string delimiters inhibit macro expansion.

The difference between $UNQUOTE and $UNSTRING can now be stated as follows.  Given a quoted string such as "abc" (in C),

  * $UNQUOTE removes the quote characters q, leaving sabcs (still a string).

  * $UNSTRING removes both the quote characters q and the string delimiters s, leaving abc (a collection of three characters).  This collection is not tokenized; it does not represent the single identifier name abc (and therefore is not very useful). $UNSTRING is primarily used internally.

The built-ins $P (see $P) and $PP (see $PP), which both generate the preprocessor character #, provide a good illustration of the differences between $UNQUOTE and $UNSTRING.  Consider FORTRAN as an example.  Essentially, $P is defined as $UNQUOTE('#'), which is internally s#s.  When this single-character string is sent to the output, it is treated like any other expression and therefore would appear in column 7 or greater even if the construction appeared at the very beginning of the line.  On the other hand, $PP is (essentially) defined as $UNSTRING('#'), which is internally the single character #. Because this character is not a string, the FORTRAN output driver treats it as a special control character, defined in this case to force the character into the first column.

Redefining built-in functions
.............................

By default, built-in functions are protected---that is, they may not be redefined by an @m command.  (To do so cavalierly invites many kinds of weird disasters.)  If it is absolutely necessary to redefine a built-in function, use the command-line option -Tb (see -Tb).

Many of Fweb's ``built-in functions'' are in fact ordinary macros that are implemented in terms of lower-level built-ins.  An example is $POW (see $POW), which is constructed from the built-in function $EVAL (see $EVAL).  By default, such macros are also protected against redefinition; to override, use the option -Tm (see -Tm).

$A: Convert to ASCII
....................

$A(string) is the built-in equivalent of @'...' or @"...".  (See ATquote and ATdquote.) Note the extra parentheses required by the built-in.

$A first expands its argument, in case it is a macro defined as a string.

$ABS: Absolute value
....................

$ABS(expression) returns the absolute value of the macro expression.  It is a macro implemented in terms of $IF and $EVAL.

$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 Fweb macros required by the code are properly initialized.  Because it is expanded during the output phase, it must appear in the code part (not in the definition part).

$AUTHOR: Value of RCS global keyword Author
...........................................

Equivalent to $KEYWORD(Author).  See $KEYWORD.

$COMMENT: Generate a comment
............................

$COMMENT(string) generates a comment in the output file.

This function is sometimes useful in conjunction with the processing of Fweb macros, since ordinary comments are removed when macros are processed.  For example, if one says

     @c
     @
     @m M "abc" $COMMENT("Test")
     @a
     m = M

the tangled output will be m= "abc"/* Test */

$DATE: Today's date
...................

$DATE generates a string consisting of the date in the form "August 16, 2001".  It is implemented as a macro that calls other macros and primitive functions.

$DATE_TIME: Value of RCS global keyword Date
............................................

Equivalent to $KEYWORD(Date).  See $KEYWORD.

$DAY: The day
.............

$DAY generates a string consisting of the day of the week, such as "Monday".  It is implemented as a macro that calls other macros and primitive 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 -= m.

$DEFINE: Deferred macro definition
..................................

$DEFINE behaves like the Fweb macro command @m, but it is intended to appear in the code part, not the definition part (so it is processed during output, not input).  Thus, the code fragment

     a = A;
     $DEFINE(A 1)@%
     a = A;

tangles to

     a= A;
     a= 1;

(Notice how the @% command was used to kill an unwanted newline, analogous to the dnl macro in m4.)

In the above example, one could also say $DEFINE(A=1). To define a macro with arguments, say something like $DEFINE(A(x)x*x).  Do not say $DEFINE(A(x)=x*x), as in this case the equals sign will be included in the macro expansion. One must use the equals sign as a means of preventing parentheses from being interpreted as an argument in examples like

     $DEFINE(A=(x))

This expands to (x).

A completely equivalent shorthand notation for $DEFINE is $M.

$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;

In general, the macro name used as loop counter should not be explicitly defined as a macro prior to the $DO.  If it is not, it will remain undefined after the end of the iteration.

Instead of the delimiting braces, parentheses may be used.  These may be useful to help Fweave format certain constructions correctly.

Nested delimiters are handled correctly.  The delimiters are required even if only a single statement is to expanded.

$DO is implemented in terms of a command $UNROLL. However, if one says something like $DUMPDEF($UNROLL(0,5,1)), Fweb will respond that $UNROLL is not an Fweb macro. Rather, $UNROLL is processed like expandable commands in RATFOR such as while.  This implies that it cannot be redefined as ordinary macros or built-in functions can be.

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

One can use this built-in to debug one's own macros, or to find out the secrets of Fweb's built-ins.  As an example, if one says

     $DUMPDEF($EVAL(2^^4))@%

it responds with the two lines

     $EVAL($0) = $$EVAL($0)
     $EVAL(2**4) = 16

(The $n notation indicates the n-th argument of the macro.) If one replaces $EVAL with $$EVAL in the above $DUMPDEF, it will respond

     $$EVAL($0) = <built-in>
     $$EVAL(2**4) = 16

The purpose of code such as $EVAL($0) = $$EVAL($0) is to ensure that the argument of $EVAL is expanded if it contains macros; the primitive function $$EVAL does not do that expansion automatically.

Names indicated as <built-in> by $DUMPDEF may be redefined as ordinary macros, but this is in general a very bad idea; other parts of Fweb may mysteriously stop working.

$E: Base of the natural logarithms
..................................

The expression $E returns E, the base of the natural logarithms, to the default machine precision. The expression $E(iprec) returns E to the decimal precision IPREC (which must be less than 50).

$ERROR: Send error message to output
....................................

$ERROR(string) prints an error message in Fweb's standard form.

$EVAL: Evaluate a macro expression
..................................

$EVAL(expression) uses Fweb's macro-expression evaluator (see Preprocessing) to reduce the macro expression to its simplest form.  An attempt to perform arithmetic on combinations of non-macro identifiers and numbers generates a warning message.

$EXP: Exponential function
..........................

$EXP(x) returns E to the power X.

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

The argument to $GETENV need not be a string (double-quoted), but it may be if necessary to avoid the expansion of a macro.

$HEADER: Value of RCS global keyword Header
...........................................

Equivalent to $KEYWORD(Header).  See $KEYWORD.

$HOME: The user's home directory
................................

$HOME is a convenience macro equivalent to $GETENV(HOME).

$ID: Value of RCS global keyword Id
...................................

Equivalent to $KEYWORD(Id).  See $KEYWORD.

$IF: Two-way conditional
........................

$IF is a primitive function (not a macro) that is the code-part version of @#if. The syntax is

     $IF(expr, action-if-true, action-if-false)

The expr is an Fweb macro expression that must reduce to 0 (false) or 1 (true).  First that argument is expanded.  If it is true, action-if-true is expanded; otherwise action-if-false is expanded.

There may be peculiarities with this and the other built-in $IF function having to do with the order of expansion when the actions contain macros whose arguments themselves are macros.  Therefore, do not use them unless absolutely necessary.

Do not redefine $IF or any other built-in conditionals, as they are used internally to Fweb.

$IFCASE: n-way conditional
..........................

This primitive built-in behaves like TeX's \ifcase command. The syntax is

     $IFCASE(expr, case-0, case-1, ...,case-n-1, default)

If expr reduces to an integer between 0 and n-1, inclusively, the appropriate case is selected; otherwise, the default case is selected.

As examples,

     $IFCASE(2, zero, one, two, default) => `two'
     $IFCASE(2, zero, one, three) => `three'
     $IFCASE(2, zero, one) => `one'

$IFDEF: Two-way conditional
...........................

This built-in primitive is the code-part version of @#ifdef. The syntax is

     $IFDEF(MACRO, action-if-defined,action-if-not-defined)

$IFNDEF: Two-way conditional
............................

This built-in primitive is the code-part version of @#ifndef. The syntax is $IFNDEF(MACRO, action-if-not-defined, action-if-defined).

$IFELSE: Two-way conditional
............................

The syntax of this built-in primitive is $IFELSE(expr1, expr2, action-if-equal, action-if-not-equal).  The expansions of expr1 and expr2 are compared on a byte-by-byte basis.  If they are equal, the first action is taken, otherwise the second action is taken.

For example,

     $M(S="abc")@%
     $IFELSE("abc", S, yes, no)

evaluates to yes.

$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 += M.

$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 (not the source line in which the $INPUT_LINE command appears).  Compare $OUTPUT_LINE, $OUTPUT_LINE.

$KEYWORD: Value of global RCS-like keyword
..........................................

$KEYWORD provides a built-in function alternative to the use of @K in a code part.  (see ATK_).

$KEYWORD(Keyword) extracts (as a character string) the text of an RCS-like keyword defined in the ignorable commentary between @z and @x at the beginning of the web source file (see ATz). (RCS stands for ``revision-control system.'')  The general syntax is (UNIX users, see man ident)

     $Keyword: text of keyword $

For example,

     @z
     $Author: krommes $
     @x

     @c
     @
     @a
     char author[] = $KEYWORD(Author);

This tangles to

     char author[] = "krommes";

In this example, $Author is one of the standard RCS keywords. However, any keyword that fits the syntax $keyword: contents $ can be accessed by $KEYWORD. (At least one blank is necessary before and after contents.) The argument of $KEYWORD need not be quoted, but it may be.  In either event, the output is a quoted string.

Keywords extracted from ignorable commentary at the beginning of a web file are called global and are known throughout the code. Distinguish these from local keywords extracted from ignorable commentary at the beginning of an include (@i) file.  Such keywords are known only during the time that file is being read and are accessible via @k (see ATk).

For convenience, built-ins are defined for some standard RCS global keywords. These are

     $AUTHOR    => $KEYWORD(Author)
     $DATE_TIME => $KEYWORD(Date)
     $HEADER    => $KEYWORD(Header)
     $ID        => $KEYWORD(Id)
     $LOCKER    => $KEYWORD(Locker)
     $NAME      => $KEYWORD(Name)
     $RCSFILE   => $KEYWORD(RCSfile)
     $REVISION  => $KEYWORD(Revision)
     $SOURCE    => $KEYWORD(Source)
     $STATE     => $KEYWORD(State)

There are no such abbreviations for local keywords, because such abbreviations would be expanded during output whereas it is necessary to recognize and expand the local keywords during input.  Presumably such local keywords will be used rarely, if at all.

$L: Change to lower case
........................

$L(STRING) changes STRING to lower case.  The argument is first expanded in case it is a macro.

$L_KEYWORD: Value of local RCS-like keyword
...........................................

For most purposes, $L_KEYWORD behaves as @k (see ATk).  It is still under development and should not be used yet.

$L_KEYWORD("Keyword") extracts (as a character string) the text of an RCS-like keyword defined in the ignorable commentary between @z and @x at the beginning of a file included via @i.  $L_KEYWORD("local keyword") is expanded during input, and the results are known only during the time the include file is being read.

Note that the argument of $L_KEYWORD must be a quoted string. For more discussion of the distinction between local and global keywords, please see ATz and $KEYWORD.

It is expected that local keywords will rarely be used, as fundamental revision-control information should presumably be extracted from the top of the master web file.

$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 this outputs identifiers, not Fweb 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; see $LANGUAGE_NUM.

$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; see $IFCASE.

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

To expand the argument before taking the length, one can say something like

     @m $XLEN(s) $LEN(s)

$LOCKER: Value of RCS global keyword Locker
...........................................

Equivalent to $KEYWORD(Locker).  See $KEYWORD.

$LOG: Natural logarithm
.......................

$LOG(x) returns the natural logarithm of x.

$LOG10: Logarithm to the base 10
................................

$LOG10(x) returns the logarithm to the base 10 of x.

$M: Define a deferred macro
...........................

$M is equivalent to $DEFINE.  See $DEFINE.

$MAX: Maximum of a list
.......................

$MAX(x1,x2,...) returns the maximum of the list of arguments. (There must be at least one argument.)

$MIN: Minimum
.............

$MIN(x1,x2,...) returns the minimum of the list of arguments. (There must be at least one argument.)

$MODULE_NAME: Name of present web module
........................................

$MODULE_NAME returns the name of the present web module.  If the present module is unnamed, it returns the string "unnamed".

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

$NAME: Value of RCS global keyword Name
.......................................

Equivalent to $KEYWORD(Name).  See $KEYWORD.

$OUTPUT_LINE: Current line number of tangled output
...................................................

This returns the current line number of the tangled output.  Contrast this with $INPUT_LINE, $INPUT_LINE.

$P: The C preprocessor symbol
.............................

$P is (essentially) a synonym for $UNQUOTE("#") (see $UNQUOTE).  It is useful for constructing Fweb macro definitions that expand to C preprocessor statements.  For example,

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

Another version of the preprocessor symbol is $PP (see $PP). For most purposes, $P and $PP will behave in exactly the same way.  The difference between them is that $P is treated as a string (without surrounding quotes), whereas $PP is treated as a character.  The character nature of $PP is used by FORTRAN to reset the column number to 1, so C-like preprocessor commands appear there rather than in column 7.

For further discussion of strings and the differences between $P and $PP, see Strings and quotes.

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

$POW: Exponentiation
....................

$POW(x,y) generates x raised to the power y. (It is a macro defined in terms of $EVAL (see $EVAL) and the exponentiation operator.)

$PP: The C preprocessor symbol
..............................

$PP is shorthand for $UNSTRING($P) (see $P), or (essentially) a synonym for $UNSTRING("#") (see $UNSTRING). It is useful, particularly in FORTRAN, for constructing Fweb macro definitions that expand to C preprocessor statements.  For an example, see $P.  For a detailed discussion of the difference between $P and $PP, see Strings and quotes.

$RCSFILE: Value of RCS global keyword $RCSfile
..............................................

Equivalent to $KEYWORD(RCSfile).  See $KEYWORD.

$REVISION: Value of RCS global keyword Revision
...............................................

Equivalent to $KEYWORD(Revision).  See $KEYWORD.

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

$SECTION_NUM: Number of current Fweb section
............................................

$SECTION_NUM returns an integer greater than 0 that is the integer number of the current web section.  (This is not the LaTeX section number such as 3.4.)

$SECTIONS: Maximum section number
.................................

$SECTIONS is the maximum section number as understood by Fweave.

$SOURCE: Value of RCS global keyword Source
...........................................

Equivalent to $KEYWORD(Source).  See $KEYWORD.

$SQRT: Square root
..................

$SQRT(x) returns the square root of x. It is a convenience macro defined in terms of $POW.  See $POW.

$STATE: Value of RCS global keyword State
.........................................

Equivalent to $KEYWORD(State).  See $KEYWORD.

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

$STUB: Trap for missing module
..............................

When a missing module is detected, Ftangle inserts the command $STUB(module_name) into the output code.  The built-in $STUB expands to a function call appropriate to the current language.  For example, in C it expands to missing_mod, in FORTRAN it expands to call nomod.

$TIME: The time
...............

$TIME returns a string consisting of the local time in the form "19:59".

$TRANSLIT: Transliteration
..........................

The macro $TRANSLIT(S, FROM, TO) interprets each of its arguments as strings (without expanding anything). Then S is modified by replacing any of the characters found in FROM by the corresponding characters in TO. If TO is shorter than FROM, then the excess characters in FROM are deleted from S. As a limiting case, if TO is empty, then all the characters in FROM are deleted from S. For example, $TRANSLIT(s, aeiou, 12345) replaces the vowels in S by the corresponding digits, and $TRANSLIT(s, aeiou, ) deletes all the vowels.  The backslash may be used to escape a character, as in ANSI C. For example, $TRANSLIT("a\\"\\\\d", "d\\\\a\\"", "D,A'") translates into A',D.  Here one had to explicitly enclose strings involving \\" in double quotes in order to avoid a complaint about an unterminated string.

$U: Change to upper case
........................

$U(string) changes string to upper case.

$UNDEF: Undefine a macro
........................

$UNDEF(macro) undefines an Fweb macro.

$UNQUOTE: Remove quotes from string
...................................

$UNQUOTE(STRING) returns STRING without its surrounding quotes.  (However, the resulting construction is still treated as a string; no macro expansion is done.)

For a more detailed discussion and a comparison with $UNSTRING (see $UNSTRING), see Strings and quotes.

$UNSTRING: Convert string into characters
.........................................

$UNSTRING(STRING) removes quotes from the string, if they are present, and treats the result as a collection of characters.  No tokenization is done, so macro expansion does not operate on those characters.

For a more detailed discussion and a comparison with $UNQUOTE (see $UNQUOTE), see Strings and quotes.

$VERBATIM: (Obsolete)
.....................

This was an old name for $UNQUOTE (see $UNQUOTE).  Please remove all references to this macro from existing codes.

$VERSION: Present Fweb version number
.....................................

$VERSION returns a string built out of the Fweb version number, such as "1.61".

Debugging with macros
---------------------

If an Fweb macro expands to more than one output line, debugging can be a bit confusing if the debugger (e.g., gdb) displays lines in the web source file instead of the output file (as it normally does for C and C++).  While single-stepping through the code, the debugger will incorrectly step the screen display for each output line even if the macro call occupies just one line in the source file.  To localize the debugger's confusion, insert a @#line command after the macro call.  For example,

     @c
     @ Example of a macro that expands to several output lines.
     @m UPDATE(i, delta_i)
          i += delta_i;
          store(i)@;
     @a
     main()
     {
     UPDATE(j, 5);
     @#line
     // More code.  The debugger will be in sync from here on.
     }

An alternative for highly confusing situations is to use the -# option (see -#).

Another potentially confusing situation occurs when @% is used to comment out a line.  Fweb deals with the line-number problem that arises here automatically; see -T#.

Fweave makes a valiant attempt to pretty-print (see Pretty-printing) the definitions of both outer macros and Fweb macros in a reasonable way. However, this can be a formidable task, because macro syntax can be essentially arbitrary.  Consider, for example, the following definition:

     @c
     @d GET(type) type get_##type()
     @a
     GET(int){}@; // Expands into int get_int(){}.

The problem is that the identifier type is used in two different ways:  as the type of a reserved word (the second type), and as an ordinary expression (the third type).  The first type has both meanings simultaneously.  Unfortunately, within any particular language Fweave associates one unique type or ilk with each identifier.

One solution to this problem is to use the @R command (see ATR_), which changes the ilk of the very next identifier to integer-like.  Thus,

     @d GET(type) @R type get_##type()@;

will format correctly.  An alternative solution uses the related command @E, which changes the ilk of the very next identifier to an ordinary expression. Thus,

     @f type int
     @d GET(type) type get_##@Etype()@;

Other types of troublesome situations involve spaces.  When Fweb understands the syntax, it inserts spaces automatically to make the output pleasing.  Consider, however, the (somewhat contrived) example

     @c
     @d A(x, y) x y
     @d B s1;
     @d C s2;
     @a
     A(B, C)@;

Here Fweave will consider x and y to be ordinary identifiers (simple expressions), and will abut them with no intervening spaces, which is confusing to read.  The solution is to insert a space manually with @,:

     @d A(x, y) x @, y

(Whether one should write macros like this at all is a separate issue.) For a related example, see the discussion of ATcomma.

Preprocessing
=============

Generally, the Fweb preprocessor commands follow a syntax identical to their C/C++ counterparts.  The one exception is the @#line command.  Whereas the C command takes a line number and file name as arguments, the Fweb command takes no arguments; its expansion automatically inserts the current line number and file name.  This command should be necessary only in rare circumstances.  One of those involves situations in which an Fweb macro expands to more than one output line; see Debugging with macros.

The 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, see FWEB macros.

The syntax of each command is as follows:

     @#line
          --- Insert a #line command.

     @#define IDENTIFIER
          --- Define an FWEB macro; equivalent to @m.

     @#undef IDENTIFIER
          --- Undefine an FWEB macro.

     @#ifdef IDENTIFIER
          --- Is FWEB macro defined?  Equivalent to @#if defined identifier.

     @#ifndef IDENTIFIER
          --- Is FWEB macro not defined?  Equivalent to @#if !defined identifier.

     @#if expression

     @#elif expression

     @#else

     @#endif

In the @#if statement, the expression may contain Fweb macros, but must ultimately evaluate to a number.  If that number is zero, the expression is false; otherwise, it is true.

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

LANGUAGES
*********

Fweb has the ability to work with more than one source language during a single run.  The language in effect at the beginning of the first section defines the 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 (deliberately) making the tangled output relatively unreadable) and Fweave pretty-prints using the C syntax.  Turning on the N mode does not affect the language; Ftangle copies the source code literally into 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. See Miscellaneous params.

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 the option -ltext, and options have the same syntax as on the command line.

The language symbols must be in lower case; they are

     ..VERBATIM..cpp
     C             c
     C++           c++
     Fortran-77    n
     Fortran-90    n9
     Ratfor-77     r
     Ratfor-90     r9
     TeX           x
     VERBATIM      v

An example of a command with the optional text field is @n/. By definition, this is equivalent to @n[-n/].  Thus, it both sets the language and invokes a command-line option.

As another example, @n9 really means @n[-n9].  Thus the language is first set to FORTRAN, then reset to FORTRAN-90. One doesn't need to worry about this detail.

     @n9[-n&]

means set the language to FORTRAN--90 and use free-form syntax with the ampersand as the continuation character.  (This construction is now Fweb's default.)

The brackets may contain more than one space-delimited option.

A language command should appear somewhere in limbo, before the start of the first section.  The language in effect at the beginning of the first section defines the global language.  For historical reasons, the default language is FORTRAN-77, but do not rely on this; always include a language command.

Language commands may be used within sections, but the new language remains in force only for that section.  The language of a named module is inherited from the language in effect at the time the name is first used.  Thus, in the following example, the global language is 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---e.g., test.f and test.c.  Particularly note that one did not need an @c command in the last section because the language was C when @<C@> was first encountered.

Special hints and considerations for each language
==================================================

One important thing to keep in mind is that in Fweb an identifier may have, for each language, precisely one meaning throughout the document.  This restriction is not necessarily in accord with the syntaxes of the various source languages.  See, for example, the discussions in Cpp and Fortran.

Special considerations for C
----------------------------

  * Ftangle treats the construction 0b... as a binary notation that it expands to an unsigned decimal number.  Thus, 0b101 expands to 5 and 0b1111111111111111 expands to 65535.

  * Fweave processes typedef statements during phase one, so they will format properly even if they are used in a documentation part before they are defined in a code part.

  * The -H option helps one to deal with identifiers defined in header files.  See -H_.

  * Note that in C structure and enum tags do not define a new type, so the tag name does not get highlighted in boldface, underlined in the index, etc.  (That is, if one says struct S {...};, one can't say S s;, one must say struct S s;.)  This is a good reason for using C++, where such tags do define a new type.

(To be completed.)

Special considerations for C++
------------------------------

  * All of the items in the previous section (see C) still apply.

  * The @{ command is very useful for beautifying very short definitions of member functions such as constructors.  See ATlb

  * Essentially, Fweave has only one name space, global to the entire code; those names do not obey any concept of scope.  In various situations in C and C++, however, multiple namespaces are used, or the interpretation of a name changes according to its scope.  Thus, the design of Fweave imposes a few restrictions on one's programming style.  (Remember, Fweave doesn't know nearly as much as a language compiler.)

     One example in C++ has to do with formal types in templates.  Consider the following example:

          template <class Type>
          class A
          {
          private:
                  Type *p;
          }

     In order that the class definition be typeset correctly, Type must be understood to be a reserved word like int, and that is correctly figured out by the first class command.  However, according to C++, the scope of Type is local to the class definition; unfortunately, Fweave does not respect that locality and will always treat Type as an int from the point of the class Type construction to the end of the source code.  Thus, one should use such dummy variables as Type only as formal template parameters, never as ordinary variables.

Special considerations for FORTRAN
----------------------------------

Items for both FORTRAN-77 and FORTRAN-90
........................................

  * Ftangle will translate into unsigned decimal numbers the binary notation 0b..., the octal notation 0..., and the hexadecimal notation 0x....  Thus, 0b101 expands to 5, 0101 expands to 65, and 0x101 expands to 257.

  * Don't use the column 1 C commenting convention.  Use /* ... */ or // ....

  * For compiler directives, use @? (see AT?), not a C in column 1.

  * If you are going to use the recommended // ... convention for short comments, you must say @n/ (see -n/) or @n9[-n/] as your language command.  Otherwise, \FWEB\ will treat the // as \FORTRAN'S standard token for concatenation.  (You may always use \/ for concatenation.)

  * If you want to completely comment out a whole block of code, use the preprocessor construction @#if 0...@#endif (see Preprocessing).  Don't put a comment character at the beginning of each line; that prevents Fweave from formatting the code sensibly and can be annoying to undo.  With the preprocessor form, one can also implement conditional comments by using Fweb preprocessor macros:  e.g., @#if(DEBUG)...@#endif.

     Pre-Fweb codes may have such blocks commented out with a C in column 1.  Those should be converted to the preprocessor construction.  However, if you're in a real hurry, temporarily use the -nC option (see -nC) to kill those lines very early in the processing, before they can give you all kinds of trouble.

  * An unfortunate byproduct of using // for short comments is that, in general, format constructions like format(//) won't work.  (It will work if one uses -nC; see -nC.)  Alternatively, one can say format(/ /).

  * Consecutive lines commented out with a C, c, *, or ! in column 1 are converted into a single comment before processing by Fweb.  Large blocks of such lines (common in pre-Fweb code) may overflow Fweb's tables.  To avoid that, insert blank lines between some of the comments.  Better, however, is to move most such blocks out of the code part to the TeX part of the section.  It's most readable to have only a few very short comments interspersed in the code.

     To help with conversion of existing codes, the command-line option -nC can be used to completely ignore comment lines.

  * @ commands should, by and large, start in column 1.  That's not necessary for short module names that fit on one line.  However, a long module name that must be broken across lines must begin in column 1, as in

          @n
          @
          @a
          @<This is a module name
          broken across lines@>@;

     Failure to do this results in a spurious semicolon being inserted in the middle of the name.  This happens because the FORTRAN-77 input driver does various low-level manipulations of the source before it presents it to the innards of Fweb; it's not tokenizing the source at that time and doesn't understand all of the Fweb syntax such as module names.

  * Define symbolic statement labels with #:0 (see Tokens).  Such names should be followed by a colon.  Thus,

          @n
          @
          @m EXIT #:0
          @m ABORT #:0
          @a
          .
          .
          ABORT: continue
          .
          .
          EXIT: continue
          .
          .

  * By default, statement labels are \llap'd from the body of the statement.  With this convention, long labels can extend too far into the left margin.  Instead, try the command-line option -n: (see -ncolon), which puts them on a separate line.  Alternatively, one can redefine the macro \Wlbl, found with some discussion in fwebmac.sty.

  * As a suggestion, use upper case for I/O keywords such as IOSTAT. However, by default the lower-case forms are also recognized.  To permit only upper case, use -k (see -k).  Note that although there is a command -nk, it is unfortunately not related to -k.

  * One may use ^ as an alternative for the exponentiation operator **.

  * Fweb attempts to be helpful and tries to expand the operators ++, --, +=, -=, *=, and /= in a way compatible with the usage in C and C++.  For example, it expands x += y into x = x + (y).  This feature can be a great time-saver and also makes the code substantially more legible; it is strongly recommended.  To turn off this feature, use the option -+.  See -plus.

     Notice that in FORTRAN-90 /= is a token for ``not equal,'' so if you want to use that you must use the -+ option.  However, a better solution is to use !=, Fweb's preferred operator for ``not equal.''

  * By default, the operators .true. and .false. will weave as caligraphic T and F.  That appearance be changed by redefining the macros \WTRUE and \WFALSE in fwebmac.sty or in the limbo section of your source file.

  * If Ftangle messes up and outputs incorrect FORTRAN code, try tangling with the command-line option -# (see -#) (and then report the problem.)

Items specific to FORTRAN-77 and fixed-form FORTRAN-90
......................................................

  * By default, when processing the code part the FORTRAN driver inserts semicolons automatically at the end of each logical statement.  Thus, the core of Fweb is presented with a uniform syntax.  However, when one escapes into code mode by using vertical bars, those semicolons aren't inserted, so something that appears a first glance to be complete statement may not be formatted as one might expect.  Thus, the construction |5: continue| doesn't format quite properly (the colon disappears); this problem is solved by putting a semicolon after the continue.  Also, if one is talking about multiple statements (for example, with a shift into code mode during TeX documentation), there's no choice but to insert the semicolon between statements.  For example, |a = b; c = d;|.

Items specific to FORTRAN-90
............................

  * If FORTRAN-90 is selected (see -n9), the default is free-form syntax (lines are continued by a trailing ampersand). However, automatic line breaking is done in a way compatible with fixed-form syntax as well.

  * With free-form syntax, comment lines in the tangled output file begin with !.  But such lines are not recognized on input unless -n! is used.  See -n!.

  * Beginning with Version 1.61, by default (pseudo-)semicolons are automatically inserted in free-form \Fortran-90 code, as one would expect.  For more discussion, see -nAT; and -n;.

(To be completed.)

Special considerations for RATFOR
---------------------------------

For some warnings about RATFOR, see Caveats.

Special considerations for TeX
------------------------------

@Lx is supported only to the extent that fwebmac.sty can be generated correctly from fwebmac.web.  You are welcome to experiment, but you may encounter difficulties (which you should report; see Support).

(To be completed.)

Special considerations for the VERBATIM language
------------------------------------------------

Unfortunately, the VERBATIM language is not fully debugged. Therefore, it is not recommended for general use. (To be completed.)

RATFOR
******

``RATFOR'' stands for ``RATIONAL FORTRAN.''  It endows FORTRAN with a C-like syntax.  Certain loop and other constructions (such as switch or i++) that are not allowed in FORTRAN are allowed in RATFOR; Fweb translates those into proper FORTRAN.

Although RATFOR is a definite improvement over FORTRAN, it certainly does not have the power of C (e.g., elegant pointer notation) or C++ (e.g., classes).  Many advantages accrue by taking the time to learn C. RATFOR offers a gentle transition.  (It is not supported very actively any more.)

RATFOR syntax
=============

A sample RATFOR program is

     @r
     @
     @a
     program main
     {
     integer k;
     real fcn, x;

     for(k=0; k<10; k++)
             {
             x = fcn(k);

             if(x < 0.0)
                     {
                     x = 0.0;
                     break;
                     }
             }
     }

The concluding brace of a function is translated into an END statement.  Note the use of semicolons to terminate statements, braces to delimit compound statements, < instead of .LT., the C-like for construction, and the k++ expression.

Constructions like k++ or k -= l + 1 must be used with great care.  They translate to statements involving = signs, so they can be used only where simple statements are allowed, not essentially anywhere as in C (for example, they cannot be used as function arguments).

RATFOR commands
===============

RATFOR--77 commands
-------------------

      break; // Used with case or to break out of loops, as in C.
      case i: // Used with switch.
      default: // Used with case, as in C.
      do ...; {...} // Note the semicolon (unnecessary if followed by a compound stmt).
      else {...} // Used after if as in C.
      for(a;b;c) {...} // As in C.
      if(condition) {...}
      next; // Equivalent to C's |continue| statement; go to bottom of loop.
      repeat {...} until(condition); // Equivalent to C's do {...} while();
      return expression; // As in C.
      switch(expression) {...} // As in C.
      while(condition) {...} // Like C's while.

Additional RATFOR--90 commands
------------------------------

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

Caveats 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.  (Use symbolic statement labels instead; see the discussion of #:0 in Tokens.)

      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 RATFOR program unit; it is added automatically by Fweb when the closing brace is sensed.

DOCUMENTATION
*************

Fweb uses LaTeX to produce its documentation.  Plain TeX is no longer supported.

It is not necessary to be very familiar with LaTeX in order to use Fweb effectively.  Fweb does complicated things behind the scenes, relieving the programmer of many burdens.  If you don't need complicated mathematics, one needs to know virtually no LaTeX at all in order to document a section of code.  And if you do need to typeset math, consider that LaTeX makes this daunting task about as simple as one could hope.

If you're an Fweb beginner, don't bother diving into the details of this section until you really need to.

Typesetting
===========

Fweb's ``new look'' (beginning with version 1.40) is designed to work only with LaTeX.  The new look is more book-like, following ideas from Briggs' nuweb.  By default, it uses default LaTeX section numbers such as 1.5.32; however, sections may be numbered with consecutive integers by specifying the LaTeX2e package fwebnum; see Numbering.

Fweave's OUTPUT
---------------

When one says fweave test, the file test.tex is created. Some TeX commands contained in this file are created automatically; others are copied from the web source file.  They are organized into several sequential groups, as follows.

      1. \input command to read in Fweave's macro package.

          By default, the initial input command is \input fwebmac.sty (see fwebmac.sty).  The name of the macro package can be changed with the -w command-line option, but that is dangerous and useful only for very special effects.  See -w.

      2. \Wbegin command.

          The \Wbegin macro sets up certain defaults (which can be overridden in the limbo section).  In LaTeX, it also issues the \documentclass{article} and \begin{document} commands.

      3. Limbo text from the style-file parameter limbo.begin.  See S_limbo.

      4. Limbo text from @l commands. See ATl.

      5. User's limbo section.

      6. Limbo text from the style-file parameter limbo.end. See S_limbo.

      7. TeX commands for individual WEB sections.

      8. \input command to read in the index data file.

      9. \input command to read in the module-list data file.

      10. \Winfo command (summarizes some status information).

      11. \Wcon command (generates the Table of Contents, and ends the run).

The macro package fwebmac.sty
-----------------------------

Fweave works in conjunction with the macro package fwebmac.sty, which is always read into the .tex file by default.  This file is (overly) complicated, so one should not mess with it unless in dire emergency.  Most of its commands are intended for behind-the-scenes  processing.  However, some features may be of general interest; these are described in the items below.

For the most part, macros used internally by fwebmac.sty begin with an uppercase W.  If you are worried about macro conflicts, a complete list of the macros appearing in fwebmac.sty can be found in the Index produced by weaving fwebmac.web.

User macros
...........

For the user's convenience, fwebmac.sty defines a variety of macros such as \FWEB, \Fortran, etc.  Refer to fwebmac.web for a complete list.

Fweave usurps various common single-character macros such as \. for its own purposes.  So the user can still access their original definitions, those are \let equal to alternative commands such as \period.  For example, commands such as the following are executed in fwebmac.sty:

     \let\amp\&
     \let\at\@@
     \let\bslash\\
     \let\caret\^
     \let\dollar\$
     \let\dstar\*
     \let\equals\=
     \let\leftbrace\{
     \let\period\.
     \let\rightbrace\}
     \let\vertbar|
     \let\PM\#
     \let\PC\%

(Some of the more inscrutable synonyms are for historical reasons.)

For the most up-to-date and detailed information, refer to fwebmac.web.

Fonts
.....

Several fonts have been declared. Those include

       * \titlefont (large sans serif),

       * \ttitlefont (large typewriter),

       * \SC (small caps),

       * \Csc (Caps/small caps), and

       * \tentex (TeX's extended character set).

For illustrations and further details, see fwebmac.web.

To typeset a string of characters in typewriter type, one may use the \. macro.  (More precisely, the name of this macro is the value of the style-file parameter format.typewriter.  For more information, see S_format.) When using this, one must escape the special characters  \#%$^_{}~&, as in \.{\\alpha}.  (Fweave does that escaping automatically when typesetting strings in code mode.) You may wish to surround \.{...} with an \hbox; that is not done by default because Fweave uses special trickery to break long strings in code mode automatically, and that breaking would be inhibited by an \hbox.

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 (and Plain TeX is not supported); version 1.50 supports LaTeX2e. LaTeX's \output routine is used, as are its sectioning commands (with minor changes), Table-of-Contents facilities, etc.

The following discussion is based on LaTeX2e.  If LaTeX2e is not installed, Fweave recognizes that fact and issues the \documentstyle command instead of \documentclass.

Users are strongly encouraged to upgrade to LaTeX2e.  A useful book that describes the present state of LaTeX is Goossens, Mittelbach, and Samarin, The LaTeX Companion (Addison--Wesley, Reading, MA, 1994).

LaTeX's document class
......................

An Fweb/LaTeX document is set up with the \Wbegin command, issued automatically by Fweave.  See the summary at the end of this section for the essence of what the \Wbegin command accomplishes.

Fweave uses \documentclass{article} by default.  In principle, the document class can be changed by the Fweb style-file option LaTeX.class; see Fwebmac params.  However, Fweave has not been tested with most other document classes. It will probably not work with most document classes that redefine the sectioning commands from those of \documentclass{article}. However, it may work with the revtex scientific macro package.  See REVTeX.

To incorporate class options---i.e., to obtain the effect of \documentclass[myoptions]{article}---use the style-file parameter LaTeX.class.options, as in

     LaTeX.class.options "myoptions"

To get two-sided printing, for example, one would say

     LaTeX.class.options "twoside"

To specify user packages---i.e., to obtain the effect of \usepackage[pkgoptions]{pkgname}---use the style-file parameters LaTeX.package and LaTeX.package.options, as in

     LaTeX.package "pkgname"
     LaTeX.package.options "pkgoptions"

For example, to indent the first line of every section and to permit the use of the multicol package (the latter is a useful way of substantially cutting down on white space), say

     LaTeX.package "indentfirst,multicol"

Note that specifying LaTeX.package and LaTeX.package.options results in the execution (by the \Wbegin macro) of precisely one line of the form

     \usepackage[myoptions]{mypackages}

Sometimes one instead needs to have multiple \usepackage lines, such as

     \usepackage[option1]{package1}
     \usepackage[option2]{package2}

To get this effect, one can put these commands explicitly into the style-file parameter doc.preamble (see discussion two paragraphs below), as in

     doc.preamble = "\\usepackage[option1]{package1}\
                     \\usepackage[option2]{package2}"

TeX commands in the user's limbo section of the web source file will be processed after the \begin{document} command.  Limbo commands from the style file can be inserted before and/or after those in the limbo section with the aid of the style-file parameters limbo.begin and limbo.end; see S_limbo.

If there is a compelling reason to insert one's own LaTeX commands between the \usepackage and \begin{document} commands, one may use the style-file parameter doc.preamble, whose value is a string consisting of LaTeX commands (empty by default).  Those commands are processed immediately before \begin{document}.  One use of doc.preamble is to inhibit Fweb's tendency to keep a section together on one page.  To make it break more readily in the middle of sections (particularly useful for multicolumn output), say

     doc.preamble "\\secpenalty=0"

In summary, the beginning of the file output by Fweave looks like the following, where <parameter> means the contents of the style-file string called parameter:

     \input fwebmac.sty
     \Wbegin{many obscure arguments}
     <limbo.begin>
     Optional TeX commands copied from user's limbo section
     <limbo.end>

The \Wbegin command essentially does the following:

     \documentclass[<LaTeX.class.options>]{<LaTeX.class>}
     \usepackage[<LaTeX.package.options>]{<LaTeX.package>}
     <doc.preamble>
     \begin{document}

For precise information about how \Wbegin works, see fwebmac.web.  If you feel that macro absolutely needs to be changed, please inform the developer (see Support).

Using REVTeX
............

REVTeX is the standard macro package used for formatting scientific papers submitted to the American Physical Society, the American Institute of Physics, and some European journals.  It modifies the sectioning commands of \documentclass{article} and provides various other useful macros.

Unfortunately, as of August, 1998, REVTeX is not fully compatible with LaTeX2e; it must be invoked with \documentstyle{revtex}, not \documentclass.  This is annoying, because Fweb's macros in fwebmac.sty default to \documentclass if they recognize that LaTeX2e is loaded.

To use REVTeX, uncomment the line in fwebmac.sty that says \useREVTeXtrue.  (One cannot say \useREVTeXtrue in the limbo section of one's web source, because the document class has already been selected by that time.)  You may wish to rename the resulting file, say to rwebmac.sty, so it can be loaded in place of the standard fwebmac.sty.  To do that, one would use the command-line option -wrwebmac.sty (see -w).

Saying \useREVTeXtrue selects \documentstyle rather than \documentclass.  To implement a standard command such as \documentstyle[aps,my_macros]{revtex}, use the style-file (fweb.sty) parameters LaTeX.style and LaTeX.options, as in

     LaTeX.style "revtex"
     LaTeX.options "aps,my_macros"

Here my_macros.sty would be a user's macro package loaded in addition to those of REVTeX and Fweb.

REVTeX support is extremely recent.  There may be glitches; please report those.  In a pinch, if LaTeX stops while processing a REVTeX file produced by Fweave, try typing `s' (scroll mode) to force it to continue; you might get usable output.

LaTeX packages related to Fweb
..............................

The following packages are supplied with the Fweb distribution and can be used to achieve special effects.  Packages are invoked by giving their names as arguments to the LaTeX.package command; see S_LaTeX.

Sections in LaTeX
.................

Fweb's sectioning commands @* and @*n 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 untitled @ 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 previous scheme means that it may be necessary to run LaTeX as many as three times in order to resolve all sectioning and cross-reference information correctly.  You should be warned in such cases.  If not, you will recognize difficulties by noting that the Table of Contents or section numbering is incomplete.

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

A discussion of alternative section-numbering schemes is given in Numbering.

LaTeX's index.
..............

The Index should be the last section of the code, and should be begun by the command @* \INDEX..  For more information, see S_index.

The challenge of typesetting the Index is to get it into two-column mode in the best possible way.  In the original Plain-TeX Fweb, special code was provided for this.  With LaTeX, however, one wants to use standard features.

The best solution is to use the user package multicol.  If that is loaded by means of the style-file statement LaTeX.package
"multicol", then any text typed by the user following the @*
\INDEX. command will be typeset in single-column mode, after which two-column mode is entered.  If it is not loaded, a \twocolumn command is issued before the index section is begun (in order to get the Index started on a new page).

More precisely, what happens is the following.  When the @*
\INDEX. command is recognized, essentially the following operations are performed, where the results are bracketed in the form [multicol : nomulticol]:

     \beforeindex [\newpage : \twocolumn]
     [print INDEX section heading]
     \startindex  [\begin{multicols}{2} : \medskip]
     \Wfin        [\end{multicols} : \relax]

(Use of the asymmetrical name \Wfin is for historical reasons.)

The positioning of \beforeindex suggests a way of printing the entire document in two-column mode.  If one enters multi-column mode in the limbo section, then \beforeindex can be used to terminate it. It is best to do this at the end of the limbo section; otherwise user macro definitions in the limbo section must be made \global in order that they remain defined in the Index.  The relevant commands can be placed in the style file:

     LaTeX.package "multicol"

     doc.preamble "\\secpenalty=0"

     limbo.end "\\def\\beforeindex{\\end{multicols}\\newpage}\n\
     \\begin{multicols}{2}\n\
     \\raggedcolumns"

Just to repeat, use only the first command to get just the Index printed in two-column format; use the second and third ones to make the entire document two-column.

LaTeX's Table of Contents
.........................

LaTeX uses the aux file to accumulate the information for the Table of Contents.

When LaTeX is used, the Table of Contents appears at the front of the document by default (beginning with version 1.61).  This is accomplished by setting the default value of the style-file parameter limbo.end to "\\FWEBtoc", where \FWEBtoc is defined in fwebmac.sty.  If you initialize limbo.end yourself in fweb.sty, you should include "\\FWEBtoc" at the end of that initialization if you want the Table of Contents to appear in the beginning.  Otherwise, it will appear at the end.

In essence, the Table of Contents is produced by the LaTeX commands

     \pagenumbering{roman}
     \maketitle
     \topofcontents
     \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 it is better to use Fweb's \Title macro instead of \title:

     \Title{MYCODE.WEB}
     \author{My name}
     \date{January 1, 2001}

By default, the argument of the \Title macro is printed both on the title page and as a running headline in the document.  The default font for the title is \ttitlefont; that for the running headline is \large\tt.  However, \Title has one optional argument that allows one to override the running headline, perhaps by specifying a shorter form.  Say

     \Title[Short title]{Long title}

to make the running headline be \large\tt Short title and the title-page title be \ttitlefont Long title.

The \Fweb \Title macro calls LaTeX's \title macro with the long title as its argument. By default, Fweave uses (in the \Wbegin macro)

     \title{}%
     \author{}%
     \date{\today\\[3pt]\Time}%

Section numbers in the Table of Contents are produced by the LaTeX macro \numberline.  LaTeX's default definition is inadequate when section numbers are very large; they extend to the right and can overwrite the section name.  The macro is redefined more appropriately when the package fwebnum (see Numbering) is used.

Customizing LaTeX's output
..........................

Several (TeX) flags are provided to change the appearance of the final LaTeX document.  (This appearance is a bit experimental, and it is fair to say that not everything may be fully debugged; please report problems.)  These are (... means either true or false)

       * \pagerefs... (index references by pages or section numbers);

       * \numberTeX... (number the beginning of unnamed TeX parts);

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

If desired, one may override these in the limbo section. (They are defined using Plain TeX's \newif rather than the equivalent LaTeX command because they may also be used when LaTeX is not present.)

\numberTeX is on the verge of obsolescence.  Try to not use it; never use it in conjunction with the package fwebnum. See Numbering

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.  (Presently, this will not work correctly when multicol is used for the body of the document.)

The information necessary to process page references in this way is written into the aux file.  As is usual with LaTeX, several runs may be required for the references to be fully consistent with the source file.

Page headers
------------

The very top (header) line on each page of Fweave's output contains several pieces of information:

  * the current section name or document title;

  * the page number;

  * the range of LaTeX section numbers on the page (these are preceded by the \S symbol); and

  * the range of integer section numbers as understood internally by Fweave (those are in square brackets and preceded by the # sign).

Section numbering schemes
-------------------------

The Fweb commands @* and @ are translated by complicated magic into LaTeX commands such as \section, \subsection, etc.  By default, use of \documentclass{article} then produces Dewey-decimal section numbers such as 2.13.4 (subsubsection 4 of subsection 13 of section 2). When the section tree is very deep, these numbers can look somewhat obtrusive.

An alternative scheme (that of the original WEB) is to merely number each section in ascending integer order, beginning with 1.  This can be done by specifying the package fwebnum, as in

     LaTeX.package = "fwebnum"

This package is supplied with the Fweb distribution; it is still somewhat experimental.

By default, fwebnum numbers all sections, including unnamed ones.  To prohibit numbering of unnamed sections, use the package option dontnumberunnamed, as in

     LaTeX.package.options = "dontnumberunnamed"

This option will eventually make \numberTeX obsolete; do not use \numberTeX in conjunction with fwebnum.

Package fwebinsert: Inserting Fweave's output into a LaTeX document
...................................................................

Beginning with version 1.61, it is (barely) possible to insert the TeX output woven by Fweave into a LaTeX document.  For example, a code listing could be an appendix to a dissertation, or a handbook on numerical methods could insert fragments of code formatted by Fweave.

Suppose one has the file test.web and used Fweave to create test.tex.  Unfortunately, it does not work to simply \input test.tex into a LaTeX document, because by default test.tex operates in a ``stand-alone'' mode and tries to issue a \begin{document} command.

Instead, one must use the package fwebinsert and the special input command \FWEBinput, as in the following example.  There are two important steps.

      1. Use Fweave to create test.tex. [You may wish to use the -x flag (see -x) to prevent some of the lists at the end, such as the index or module list, from being printed.]

      2. Now latex test until all of the section numbering is up-to-date. (This step is necessary because information in the aux file is used in processing the section headings.)

Now test.tex is ready to be inserted in a code like the following:

     \documentclass{article}
     \usepackage{fwebinsert}

     \begin{document}

     \section{Body}

     The body of the document.

     \appendix

     \FWEBinput{test}

     \end{document}

Note that the @* commands in test.web are converted into LaTeX sectioning commands such as \section.  The above example works correctly because the first @* in test.web is equivalent to a \section (level 0) command, which should indeed immediately follow an \appendix command.  Suppose, however, that you wanted to input test.web as part of the body of the above example, and wanted the @*s to be treated as subsections (level 1) rather than sections.  To tell fwebinsert what level number to assign to the @*s, provide that number as an optional argument to \FWEBinput, as in the following example:

     \documentclass{article}
     \usepackage{fwebinsert}

     \begin{document}

     \section{Body}

     The body of the document.

     \FWEBinput[1]{test}

     \end{document}

Alternatively, say \FWEBlevel{1} before the \FWEBinput. (The optional argument construction merely calls \FWEBlevel.)

Here are some caveats about fwebinsert:

  * Implementing this package was tricky.  It may work in simple circumstances, but it is not fully debugged.

  * The \FWEBinput command surrounds the included TeX code with \begingroup...\endgroup, in an attempt to prevent various macro conflicts.  As it stands, the command \fwebinput is \let equal to \FWEBinput.  If necessary, one could redefine \fwebinput to not include the enclosing \begingroup...\endgroup.

  * For anything except level-0 inclusions, one should have just one \FWEBinput command following each sectioning command.  (This is a bug.)

  * One is supposed to be able to use the package fwebnum (see Numbering) in conjunction with fwebinsert.  One can apply that to either the included file (via a LaTeX.package entry in fweb.sty), the including file (via a \usepackage command), or both.  Try out these various combinations to see what emerges.

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

Pretty-printing is one of those topics that can arouse strong passions: your idea of what's esthetic may not be mine.  Unfortunately, Fweb's formatting rules are mostly hard-coded, so if, for example, you don't like the way braces are arranged in typeset C code, you're mostly stuck. Most directly, this possibly undesirable choice comes from design decisions made by previous authors.  It also makes Fweave very fast, and enables certain complicated tricks that seem difficult or impossible to accomplish with a completely customizable approach.  The latter seems quite formidable, and has not been attempted---a good thesis project for the 21st century.

Pseudo-operators
----------------

Pseudo-operators behave like a particular part of speech for the purposes of Fweave's formatting, but are invisible on output; they are ignored by Ftangle.  The pseudo-operators are

     @e --- pseudo-expression.  See ATe.
     @; --- pseudo-semicolon.  See AT;.
     @: --- pseudo-colon.  See ATcolon.

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 one can type on input, and what Fweave will output.

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 compiler language itself 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 if one wants to include a backslash one must escape it with another backslash. For example, one can make an equals sign display on output as a large left arrow by saying

     @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 (maybe it will be someday).  In the meantime, one has the command @W, which provides a restricted form of such a facility.  This command is experimental, and not firmly established.  Changes in usage and/or syntax may be made in future versions.

The most general form of the @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.  (However, one may need some rather intimate understanding of Fweave's output in order to ensure that things always work correctly.)

One of the important uses of this facility is to expedite special formatting of array references.  This subject is discussed separately below in the section on ``Special array formatting'' (sorry, that isn't here yet), where an example is given.

Fweb's INDEX.
*************

Fweb has several powerful indexing facilities:

      1. It sorts and writes its own self-contained (internal) index, including cross-references to all the variables as well as items inserted by the user.

      2. It can write its cross-reference information to a file formatted for use by the makeindex utility.  This feature facilitates creation of a master index that contains information about several web files.

Fweb's self-generated index
===========================

One of the most useful features of Fweb is that it automatically generates an Index of all variable usage.   One can also insert one's own index entries by using the commands

  * @^ (entry in Roman type; see AT^),

  * @. (entry in typewriter type; see ATdot), and

  * @9 (user-defined format; see AT9).

(More discussion to be completed.)

Creating a stand-alone index with makeindex
===========================================

In addition to the internal index described in the previous section (see Internal index), Fweave can write the index data to a file formatted for later, stand-alone processing by the makeindex utility.  (Several such indexes can be merged together; see Merging indexes.)  The procedure is simple, although the following discussion goes into some rather arcane details.

Creating a stand-alone index: Summary
-------------------------------------

As a quick reference for those who have already read the details in the next subsection, the procedure to print a stand-alone index with makeindex is as follows.  First, create, if necessary, a file index.tex that \inputs index.ind.  (A skeleton is illustrated in the next subsection.)  Then:

     fweave -XI test.web % Creates test.idx and test.sty.
     makeindex -s test.sty -o index.ind test.idx % Creates index.ind.
     latex index

If you're not happy with the \pg macro supplied in fwebmac.sty, define it yourself in index.tex.

In this procedure, note the use of the -XI option and the use of a different root name (index here) for the output file.

Creating a stand-alone index: Details
-------------------------------------

To create an index file in a form suitable for later stand-alone processing by makeindex, use the -XI option to Fweave.  If the web file is test.web, the default name of the makeindex output file is test.idx.  (This name can be overridden by the style-file parameter makeindex.out.)  Run makeindex on test.idx to create the LaTeX file index.ind (see following discussion for details).  A stand-alone index can then be produced by saying latex index, where a skeleton version of index.tex would be

     % index.tex --- skeleton for printing a stand-alone index.
     \documentclass{article}
     \usepackage{fwebmac}

     \begin{document}

     \input{\jobname.ind}

     \end{document}

(In practice, a more involved procedure will probably be followed; see below.)

Usually makeindex works in conjunction with a style file.  [In fact, the syntax of Fweb's style file (see Style) was motivated by that of makeindex.]  When the -XI option (see -X_) is used, Fweave will create an appropriate style file for makeindex.  (The default name of test.sty can be overridden by the style-file parameter makeindex.sty.)  To run makeindex on the index data for test.web and create the output file index.ind, one would thus say

     makeindex -s test.sty -o index.ind test[.idx]

It's important to use the -o option with a name different than the original file name, because it simplifies the construction of the skeleton file index.tex that prints the stand-alone index.

Fweave writes test.sty because the contents of that file may depend on parameter settings in Fweb's style file fweb.sty. Fweb's style vocabulary includes all parameters understood by makeindex.  If a makeindex parameter is called param, one references it in fweb.sty by makeindex.param.  Thus, to change the headings_flag of makeindex, one would put into fweb.sty a line like makeindex.headings_flag = 1.  To see a list of all makeindex-related parameters, say fweave -Zmakeindex (see -Z_).  Remember, do all makeindex customizations
in fweb.sty; the actual style file test.sty that will be
read by makeindex is written automatically by Fweave.

The .idx file will contain a list of entries that begin with \indexentry (more precisely, the value of the parameter makeindex.keyword).  The general form is

     \indexentry{sort key:identifier expression|macro}{page number}

Typical entries are

     \indexentry{istream:"\>{istream}|pg{}{}}{1}
     \indexentry{main:"\>{main}|pg{}\underline}{1}
     \indexentry{pow:"\@{pow}|pg{}{}}{2}
     \indexentry{z:"\"|z|pg{}\underline}{2}

Here the colon is the value of makeindex.actual; it separates the sort key (before the colon) from the actual expression to be printed. The macros such as \> typeset the identifiers in the appropriate way, depending on their use in the code.  Note that the backslashes are quoted with the value of makeindex.quote, which is by default the double quote.

Although one might guess that the typesetting macros such as \> would be defined in fwebmac.sty, that is not true.  Rather, for various technical reasons they are equated to macros in fwebmac.sty as one of the operations of the \Wbegin macro that is executed at the beginning of every tex file output by Fweave.  For example, \Wbegin does the equivalent of \let\>\Wid.  Unfortunately, without further action that equating would be forgotten by a LaTeX run made on the output index.ind of makeindex.  For that reason, Fweave appends the appropriate \Wequate macro to the end of makeindex.preamble.  This is one specific instance that necessitates that Fweave write the makeindex style file.

Each of the \indexentrys contains the encapsulation character | (the value of makeindex.encap).  By the conventions of makeindex, everything between the encapsulation character and the closing right brace defines a macro expression that acts on the page number.  E.g., the general form above generates the command \macro{page number}.  The specific macro construction output by Fweave is

     \pg{}{possible action macro}{page number}

Here the name pg is the value of makeindex.page.  The action macro is something like \underline, which would be used by Fweave to underline the page number to indicate where a variable is defined.  A default definition of \pg is given is fwebmac.sty.  It is a three-argument macro, \def\pg#1#2#3{...}, where the arguments are as follows:

     #1 --- Integer file identification number
     #2 --- Action macro.
     #3 --- Page number.

The definition should contain the construction #2{#3}---i.e., the page number must be the argument of the action macro.  The first argument is left empty in the .idx file written by Fweave. This can be filled in later by the utility idxmerge (see Merging indexes) that merges the indices from several web files.  For example, in a master index one might ultimately print page numbers like II.5, where II refers to a file such as test2.web.  To aid this merging process, the root name of the web file is written as a comment at the top of the .idx file output by Fweave.

Using the idxmerge utility to merge indexes
===========================================

In a large project, one may maintain and work with several Fweb files.  It may be useful to produce a global index that spans all of those files.  To this end, the utility idxmerge and associated LaTeX package idxmerge are supplied with the Fweb distribution.

Using idxmerge: Summary
-----------------------

As quick reference for those who have already plowed through the following details, here is a summary of the procedure.  To print a stand-alone index by merging the indexes from several web sources, do the following.  First, create, if necessary, a file index.tex that \inputs index.ind.  Then:

     fweave -XI test1.web
     fweave -XI test2.web
     fweave -XI test3.web

     idxmerge -oindex test1.idx test2.idx test3.idx
             % Creates index.ind and index-names.tex.
     makeindex -s test1.sty index
     latex index

Note the use of the -XI option.  For further background, see the previous section, Using makeindex.

Using idxmerge: Details
-----------------------

Suppose one has three files, test1.web, test2.web, and test3.web.  To use idxmerge, weave each of the files separately, using the -XI option to create test*.idx and test*.sty.  Then say

     idxmerge -oindex test1.idx test2.idx test3.idx

This creates two output files:  index.idx, and index-names.tex.  idxmerge first sorts the list of file names.  It then writes one entry into index-names.tex for each file, of the form

     \idxname{N}{file_nameN}

This file can be \input by the \topofindex command (for an example, see the LaTeX2e package idxmerge) (supplied with the Fweb distribution) and used to create a list of the merged files.

Then it merges the \indexentry commands from each of the input files into index.idx, filling in the integer file identifier N (the position of the file in the sorted list) into the first argument of the \pg macro.  One can now say

     makeindex -s test1.sty index

This creates index.ind, which can be processed by, for example, a simple modification of the simple LaTeX template given above in Using makeindex.  The only difference is that the package idxmerge was used; in that file, the macros \topofindex and \idxname are appropriately defined to print out a numbered list of the merged files to cross-reference into the numerical file- and page-number entries in the body of the index.  Here is an example (provided in the Fweb distribution):

     % index.tex --- skeleton for printing a stand-alone index.
     \documentclass{article}
     \usepackage{fwebmac,idxmerge}

     \begin{document}

     \input{\jobname.ind}

     \end{document}

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

The style file (called fweb.sty by default; see -z) is intended to provide more local customization, perhaps differing for each source file and group of source files.  The style file does not contain command-line options; rather, it contains parameter settings that override Fweb's defaults.  The -p option (see -p) may be used to specify a style-file entry in .fweb (i.e., a global value for all source files) or on the command line (i.e., a value used for a single run).

The order of processing is:

      1. Evaluate environment variables.  See Environment variables.

      2. Read .fweb and remember its contents; sort those into three groups:  options beginning with -, beginning with &, and beginning with a letter (file names) .  See Initialization.

      3. Process .fweb options beginning with - (or +, for backward compatibility), except for -p.

      4. Read and process command-line options, except for -p.  See Options.

      5. Process remaining .fweb options (either file names, or options beginning with &).

      6. Process any -p options from .fweb.  See -p.

      7. Process the style file.  See Style.

      8. Process any -p options from the command line.

Unfortunately, because not all options are processed immediately when they are read, errors may not show up when one expects.  For example, nothing is actually processed while .fweb is being read; its contents are just being stored.  It could therefore happen that a syntax error in entering a -p option in .fweb may not be reported until after the style file has been read, possibly confusing the user as to the source of the error.

Environment variables
=====================

FWEB_HDR_INCLUDES --- Colon-delimited list of directories for the C preprocessor (in the form of gcc) to search for #include header files.  This is used in conjunction with the -H option; see -H_.  (One can append to this list by means of the -I option, provided that option comes after the -H; see -I_.)

FWEB_INCLUDES --- Colon-delimited list of directories to search for @i include files.  (One can append to this list by means of the -I option, provided that option comes before any use of -H; see -I_.)

FWEB_INI --- Name of the initialization file. If not defined, either .fweb or fweb.ini is chosen, depending on the machine.  The initialization file always resides in $HOME.

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

Initialization
==============

Although some aspects of Fweb's behavior are hard-coded, many can be changed and/or initialized by the user.

The initialization file
-----------------------

On startup, Fweb attempts to read an initialization file.  This always resides in the user's home directory.  It is usually called .fweb (fweb.ini on personal computers).  The default file name can be overridden by the environment variable FWEB_INI.

One may put into .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 - (or a + for backward compatibility), it is processed before the actual command-line options; if it begins with & or is a file name, it is processed after.  Generally, .fweb options should begin with - so that one may override them from the command line.  The % sign begins a comment terminated by the end-of-line.

Memory allocation
-----------------

The command-line option -y (see -y) is used to change the default allocation for a dynamic array.  The arrays have a one- or two-character abbreviation denoted by aa.  Some error messages will use this abbreviation when suggesting that one increase a default allocation.  To query the present allocations of variable aa, just say -yaa.  To query everything, say -y.

This whole scheme is somewhat annoying.  In most cases, dynamic arrays should be reallocated automatically.  That can be done without too much difficulty, but I was reluctant to try it for Version 1.61 in fear of breaking something.  Please wait for the year 2000.

If one uses -y to examine the maximum permitted values of these parameters, one will note the magic number 10239 appearing occasionally.  This number is a bit less than 64K/5; it is a signature of an inherently 32-bit design that goes back to Knuth.  Unfortunately, this number can't be increased without some radical redesign.  Wait for the year 2100.

-yb: Maximum bytes for identifiers, index entries, and module names
...................................................................

Unique identifiers, index entries, and module names are stored contiguously in a large memory area, the size of which is controlled by -yb.  The default may need to be increased for very large source files, or decreased to squeeze things into a personal computer.  See also -yn.

-ybs: Size of the change buffer, in bytes
.........................................

Information from change files is read into the change buffer, whose size is controlled by -ybs.  It should not be necessary to change this unless an error message specifically tells one to do so.

-ycb: Size of line buffer for C output, in bytes
................................................

Ftangle outputs lines of a fixed maximum length.  It attempts to split them in a reasonable way, dependent on the language.  When it absolutely can't figure out how to split the line, it will issue a warning message and split it anyway.  The -ycb option controls the maximum output line length for C and C++.

The analogous command -yxb controls the output line length for TeX and the verbatim mode.  See -yxb.

-ycf: Size of a Ratfor buffer, in bytes
.......................................

The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by -ycf and -ycg.

-ycg: Size of another Ratfor buffer, in bytes
.............................................

The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by -ycf and -ycg.

-yd: Increment for expanding the dots table
...........................................

The ``dots'' table is used for FORTRAN to hold information relating to ``dot'' operators such as .NE..  In FORTRAN--90, additional such operators can be added by the program, so the table can grow dynamically.  The -yd option controls how many additional entries are made available each time the table size needs to be reallocated.

-ydt: Maximum number of deferred macro tokens
.............................................

Deferred Fweb macros are ones defined in the code part rather in the definition part.  (Their use is normally prohibited; see -TD.) -ydt controls how many bytes are set aside for the storage of these replacement text of those macros.  See also -ydx.

-ydx: Maximum number of deferred macro texts
............................................

-ydx controls how many deferred macros are permitted.  See also -ydt.

-yid: Maximum depth of file inclusion
.....................................

Files included by @i can themselves contain @i commands, to a nesting level controlled by -yid.

-yif: Maximum number of unique include-file names
.................................................

The number of unique file names appearing in @i commands is controlled by -yif.

-ykt: Stack size for Ftangle
............................

Ftangle uses a stack to deal with the web of module names---i.e., a named section can refer to another module name.  The size of this stack is controlled by -ykt.

-ykw: Stack size for Fweave
...........................

Fweave's stack handles the possibilities that code mode can be embedded in a module name, or vice versa.  The maximum nesting level for such mode changes is controlled by -ykw.

-yll: Line length for Fweave's output, in bytes
...............................................

-yll controls the length of each line in the .tex file output by Fweave.

-yln: Maximum length of module names or strings, in bytes
.........................................................

When each module name or string is parsed, it is stored temporarily in a buffer whose length is controlled by -yln.

-ylb: Maximum number of nested loops in RATFOR
..............................................

In RATFOR, various loops such as while are translated into their FORTRAN equivalents.  -ylb controls the maximum nesting level of such expandable constructions.

-ylx: Maximum length of expressions that can be expanded with the post-increment operators of FORTRAN or RATFOR
...............................................................................................................

FORTRAN and RATFOR can expand expressions such as x(i) += dx into their FORTRAN counterparts such as x(i) = x(i) + dx. It does so in a very straightforward way, by copying the expression to the left of the equals sign.  -ylx controls the maximum size of that expression.

-ym: Maximum number of sections
...............................

-ym limits the maximum number of sections, both named and unnamed.  (Each unnamed section is counted separately.)  The absolute maximum number of sections is 10239, probably one of the most stringent restrictions in Fweb's design.  (This number is a bit less than 1/5 of 64K.)

-yma: Maximum number of arguments to Fweb macros
................................................

The maximum number of arguments to Fweb macros (defined by @m) is limited by -yma.

-ymb: Size of the buffer for expanding Fweb macros
..................................................

The expansion of each Fweb macro is done in a buffer whose size is controlled by -ymb.  (In some situations, particularly in RATFOR, more than one such buffer can be open at once.)

-yn: Maximum number of identifiers and module names
...................................................

A structure is associated with each unique identifier and module name. The maximum number of such structures is controlled by -yn.  See also -yb.

-ynf: Maximum number of open output files
.........................................

In addition to Ftangle's usual output file---e.g., test.c---additional files may be opened by means of the @O (see ATO_) or @o (see ATo) commands. Depending on the situation, some of these files may remain open simultaneously.  The maximum number of such files is controlled by -ynf.

-yop: Maximum number of entries in the table for operator overloading.
......................................................................

In Fweave, the appearance of an operator can be changed (overloaded) by means of the @v command (see ATv).  Each such operator is entered into a table, the maximum size of which is controlled by -yop.

-yr: Maximum number of cross-references
.......................................

The Index cross-reference information (in which sections each identifier is used or defined) is maintained in a large array of structures, one structure for each cross-reference.  The maximum number of cross-references is controlled by -yr.

-ys: Maximum number of scraps
.............................

The maximum number of scraps is controlled by -ys.  For a discussion of scraps, see -1.

-ysb: Size of style-file input-line buffer
..........................................

The maximum length of each input line of the style file (fweb.sty by default) is controlled by -ysb.

-ytt: Maximum number of tokens that Ftangle can process
.......................................................

A token is an identifier, numerical constant, operator, etc. Ftangle must read in and store all tokens in the entire source file, because they can be output in a different order than they are input.  The maximum number of tokens is controlled by -ytt.

-ytw: Maximum tokens in the current section being processed by Fweave.
......................................................................

Unlike Ftangle, Fweave need only read in one section at a time.  The maximum number of tokens in any section is controlled by -ytw.

-yx: Maximum number of texts
............................

For Ftangle, a text is either the replacement text of a macro, or the contents of a named section.  The maximum number of such texts is controlled by -yx.

For Fweave, a text is a phrase that arises from combining primitive scraps during the translation stage of phase 2.

For both processors, the absolute maximum number of texts is 10239.

-yxb: Size of line buffer for TeX and verbatim output
.....................................................

This option is like -ycb (see -ycb), but controls the size of the output line for the TeX (@Lx) and verbatim (@Lv) languages.

The Style file
==============

A style file (default name fweb.sty) may reside in the user's current directory (or the directory specified by the environment variable FWEB_STYLE_DIR).  The default name can be changed by the command-line option -z (see -z).

The style file is processed after all command-line options have been processed, except that the command-line option -p (see -p) gets special treatment.  Note that that option buffers up style-file entries (i.e., one may use more than one -p option).  -p options placed in .fweb are treated as residing in a temporary file that is read just before the local style file; thus, those behave as `global' style-file entries that will be overridden by a matching entry in the local style file.  -p options on the command line will be processed after the local style file, thus override corresponding options in either .fweb or the local style file.

To summarize the previous discussion, the local style file is intended to contain settings that are common to a particular source file. Settings common to all source files can be put into .fweb by means of the -p option.  To override a setting for a single run, use a -p option on the command line.

Style-file entries have the form

             KEYWORD [=] VALUE

The equals sign is always optional.  The value is usually a double-quoted string, but may sometimes be an integer or a single-quoted character.  For example,

             LaTeX.class.options = "twoside"
             LaTeX.package "indentfirst,multicol"
             mark_defined.fcn_name 0
             line_char.N 'C'
             color.error = "red"
             Color.red = "\e[01;31m"

The syntax is completely free-form.  Periods within keywords are precisely equivalent to underscores, but are useful heuristically for associating a structure-like hierarchy to some of the commands. Non-printable characters in strings can be specified as octal constants (e.g., \033), hexadecimal constants (e.g., \x1B), or one of the ANSI escape sequences \a, \b, \f, \n, \r, \t, and \v.  The non-ANSI escape sequence \e (escape) is also supported; that is particularly useful for color processing (see Color).

Various of the style-file parameters take a language subscript.  Those are

     C
          C

     Cpp
          C++

     N
          FORTRAN-77

     N90
          FORTRAN-90

     R
          RATFOR-77

     R90
          RATFOR-90

     V
          Verbatim

     X
          TeX

Thus, line_char.N is the comment character for Ftangle's line commands (see line_char), for FORTRAN-77 code.

Unfortunately, the descriptions of the parameters aren't all completed yet.  To query the default values, say ftangle -Z (see -Z_).

Customizing Fweave's index
--------------------------

In the following, ??? denotes the name of various subparameters.

index.???
.........

index.name is the name of the index section.  This string is used in \Wbegin to initialize the TeX macro \INDEX.  The index section is recognized by matching, for a starred section, the actual section name against the contents of \INDEX.  When they match, a new page and two-column mode are begun.  These rules imply that the last section of one's source file can be titled \INDEX, as in

     @* \INDEX.

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, as for example #.ndx.

index.preamble are TeX commands that begin the Index.

index.postamble are TeX commands that end the Index.

index.collate specifies the collating sequence for the Index.

delim_?
.......

delim_0 is the string to insert after the identifier in an index entry.

delim_n is the string to insert between two section numbers in an index entry.

group_skip
..........

group_skip is a string of TeX commands to insert between letter groups.

item_0
......

item_0 is the TeX command to begin an index entry.

language.???
............

language.prefix begins a language entry.; language.suffix ends one.

lethead.???
...........

lethead.prefix begins a letter group; lethead.suffix ends one.  The flag 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.

underline.???
.............

underline.prefix is the TeX command to begin an underlined index entry.

underline.suffix is the TeX command to end an underlined index entry.

Customizing the module list
---------------------------

modules.tex is the name of the file into which the module names are written.

modules.preamble is a string of TeX commands to begin the list of modules.

modules.postamble is a string of TeX commands to end the list of modules.

modules.info is the name of the TeX macro that formats the command line and related information.

Customizing the Table of Contents
---------------------------------

contents.tex is the name of the file into which the Table of Contents is written.

contents.preamble is the TeX string that begins printing the Table of Contents.

contents.postamble is the TeX string that ends the Table of Contents.

Customizing cross-reference subscripts
--------------------------------------

When Fweave pretty-prints code, it can attach cross-reference subscripts to various kinds of identifiers such as function or macro names.  [A bullet for a subscript indicates that the name was defined in the current section.] The actual marking of the cross reference is done by the command @[ (see AT[).  This is usually done implicitly; for example, the commands @a, @d, and @m issue an implicit @[.  (See the discussion of @a in ATa.)  In C, various declarations of variables also result in such an implicit mark.

Various nuances in the type (possibly underlined) used for the subscript give a hint about what kind of identifier Fweave thinks it's working with.  For more information about the typesetting conventions, see the definition of the primitive macro \W@IN in fwebmac.web.] The following flags select which identifiers are so subscripted.

To see the default values of these parameters, say ftangle -Zmark_defined.  To turn off the subscripting operations completely, use the -f option (see -f).

(Discussion to be completed.)

Customizing the behavior of fwebmac.sty macros
----------------------------------------------

To some extent, the behavior of Fweb's macro package fwebmac.sty can be changed by means of the following parameters. (Please try not to actually edit fwebmac.sty itself; it is produced automatically from fwebmac.web.  And please don't edit that file either!)

format.???
..........

The format parameters are strings that specify the macro to be used to pretty-print various kinds of identifiers.  These macro names are usually written automatically by Fweave, but they may also be used directly by the user in the TeX documentation.  One can see their default values by typing ftangle -Zformat..  For example, the default value for format.typewriter is "\\.".

The macro names defined by the format fields are not defined in fwebmac.sty.  They are dummy names, and can be changed to any other name not already in use without affecting the operation of Fweb.  This ability is necessary because other packages might usurp macros like \. for their own purposes.

Thus, Fweave normally writes out the macro \. to typeset a string.  Suppose, however, that some user package uses \. for something else.  (One might realize this when LATEX crashes when it encounteres a \. that was written automatically by Fweave.)  To fix this problem, put into fweb.sty the lines

     format_KEYWORD = "\\WTT"
     format_keyword = "\\WTT"
     format_typewriter = "\\WTT"

Here \WTT can be any name not already in use; you need not (and should not) give a definition for \WTT.

Macros like \. or \WTT are given their values during the execution of the \Wbegin macro that begins the output from Fweave.  The style-file values are written as arguments to that macro, and essentially a command like \let\.\Wtypewriter is executed, where the internal macro \Wtypewriter is defined in fwebmac.sty.  If you want to change the way Fweb typesets a particular kind of identifier, you must redefine the internal macro name, not the one used in the format parameters.

Here are the internal macros used by fwebmac.sty to typeset the various kinds of identifiers.  The associated style-file parameters are shown in parentheses.

     \Wid
          ordinary identifiers (format.id)

     \WID
          completely upper-case ordinary identifiers (format.ID)

     \Wshort
          single-character ordinary identifiers (format.short_id)

     \WidD
          outer macros (format.outer_macro)

     \WIDD
          completely upper-case outer macros (format.outer_macro)

     \WidM
          FWEB macros (format.WEB_macro)

     \WIDM
          completely upper-case FWEB macros (format.WEB_macro)

     \Wreserved
          reserved words (format.reserved)

     \WRESERVED
          completely upper-case reserved words (format.RESERVED)

     \Wintrinsic
          library/intrinsic function names (format.intrinsic)

     \Wkeyword
          certain Fortran keywords (format.keyword)

     \WKEYWORD
          completely upper-case keywords (format.KEYWORD)

     \Wtypewriter
          character strings (format.typewriter)

indent.???
..........

indent.TeX specifies paragraph indentation for the TeX part.

indent.code specifies similar indentation for the code part.

LaTeX.???
.........

For LaTeX2e, the default document class can be overridden by LaTeX.class.  The default class is article, and Fweb has not been tested with other document classes, except minimally with revtex (see REVTeX).

Options to the document class can be specified by LaTeX.class.options.

User packages can be given by LaTeX.package.

Options to user packages can be specified by LaTeX.package.options.  There may be just one LaTeX.package command and just one LaTeX.package.options command.  If it is necessary to issue multiple such commands, then put them into doc.preamble.  See the discussion in Document class.

When running under LaTeX prior to LaTeX2e (or with REVTeX; see REVTeX), the document is (effectively) begun by the command \documentstyle[options]{style}.  The options field can be specified by LaTeX.options; the style field by LaTeX.style.

Remapping control codes
-----------------------

Control-code remappings are sophisticated and unwise.  They are mostly intended for the developer, so are not explained here.

Color output
------------

In the design of Fweb, provision has been made for writing various messages to the terminal in color---e.g., serious error messages might appear in red.  This feature was motivated by the color ls of Linux. It is installed automatically if the termcap library is present.

Messages output from Fweb are ranked according to an internal message-type table; each type can be associated with a color that can be changed in the style file.  Presently, the message types (hopefully self-explanatory) are

          ordinary
          program_name
          mod_name
          info
          warning
          error
          fatal
          mod_num
          line_num
          in_file
          include_file
          out_file
          timing

The associated style-file parameters are the above names prefaced by color.---e.g., color.warning.  Each of those has a default value, such as color.error = "red".  Those defaults can be displayed by saying ftangle -Zcolor.

What the color actually means in practice depends on the color mode, set by the -C option (see -C_).  That selects one of several primitive palettes, as follows:

     0
          No color; ordinary black-and-white output.  This is the default (and the mode used when the termcap library is not present).

     1
          ANSI color.  With a color terminal that supports ANSI color escape sequences, one has available the following colors:  "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", and "default". These are displayed with bold attribute (that is, bright, not dim). "default" stands for the usual black on white background, or vice versa.

     2
          Bilevel.  This is for terminals that don't support true color, but do support a double-bright mode and reverse video.  Colors are mapped onto various combinations of those two display attributes, according to an internally defined scheme.  For example, "red" is mapped onto the pair of escape sequences md, mr (double-bright mode in reverse video).

     3
          Trilevel.  As above, but adds underlining capability.

     4
          User-defined colors.  This implements a minimal set of defaults.  It is intended that the user add definitions in the style file to override those defaults.

The mechanism is intended to work with systems that support the termcap library.  The terminal is controlled by writing appropriate escape sequences to it.  The style-file parameters that store the escape sequences are the color name preceded by Color. (note the upper case C)---e.g., Color.red.  For cases like reverse video (standard termcap abbreviation mr), the escape sequences are determined by querying the termcap database (usually /etc/termcap) through the termcap library functions.  For ANSI color (color mode = 1), ANSI escape sequences are hard-coded into Fweb.  One can see the escape sequences Fweb assigns to colors by saying ftangle -ZColor.

For any non-zero color mode, one can override Fweb's default choices for color mappings and escape sequences by redefining one or more of the Color parameters in the style file.  The escape sequences can either be specified in raw form---e.g., for color mode = 1, a default is Color.red = "\e[01;31m"---or in the form of a sequence of two-character abbreviations that are defined in the termcap documentation---e.g., for modes 2 and 3, the default is Color.red
= "mdmr".  (When one displays that with the -Z option, Fweb will display the actual escape sequences that it determines from the termcap database, not the abbreviations.  For both input and output, note that one may use the non-ANSI escape sequence \e to represent the escape character \033.)

When one says -ZColor, for color modes 1--3 all of the parameters are listed as modified, even if the user redefines none. That occurs because the defaults are overwritten internally when the color mode is set.

Fweb's configuration script attempts to determine whether the termcap library is present; if not, they link in dummy termcap routines (termcap0.web).  To override this behavior, change the appropriate lines in defaults.mk, produced by the command ./configure.

Color message output is not fully debugged (it's a frill, after all), so some messages that should reasonably be colored may not be so in the present release.

Miscellaneous style-file parameters
-----------------------------------

There are a variety of miscellaneous parameters.

ASCII_Fcn
.........

See ATdquote.

cchar
.....

Continuation character for FORTRAN code output.

cdir_start
..........

This parameter has the form cdir_start.l, where l is one of C, Cpp, N, N90, R, R90, X, or V.  The contents of this parameter is written immediately after the @? that begins a compiler directive.

line_char.l (Ftangle)
.....................

By default, Ftangle outputs comments indicating line numbers in the web file from which the tangled output comes.  (This information can be used by debuggers, especially those for C and C++, to correlate error messages to the web source.)  The line_char parameter sets the comment character that begins the line comment.

line_length.l (Ftangle)
.......................

This parameter is used by the FORTRAN-like languages to control the length of the output line in the .f file produced by Ftangle.  For FORTRAN-77, its default value is the venerable 72.  For FORTRAN-90, its default is 73.  Using that value makes it possible to generate code that is compatible with both fixed- and free-form format (by continuing lines with an trailing ampersand in column 73 and another ampersand in column 6 of the next line).

meta.???.?, meta.???.hdr.? (Ftangle)
....................................

These parameters customize the treatment of meta-comments. Fundamentally, meta-comments consist of material enclosed by @(...@).  The header information usually written at the top of the file output by Ftangle (see -Tv) is also treated as a meta-comment.  For that header material, a separate set of parameters is provided, such as meta.top.hdr.

meta.top.L specifies text that precedes material enclosed by @(...@).  Here L is one of the standard language subscripts (see Style) such as N90.

meta.prefix.L begins each line of the meta-comment.

meta.bottom.L specifies text that follows the meta-comment.

outer.???
.........

Ftangle converts @d (see ATd) to outer.def, and @u (see ATu) to outer.undef.

protect.?
.........

The strings protect.L specify the protection character(s) to end a continued line.

suffix.?
........

The extension for the files output by Ftangle is specified by suffix.L.

macros
......

The default name of the macro package to be read in.  [This is usually fwebmac.sty (see fwebmac.sty), but can be overridden by the command-line option -w; see -w.]

limbo.begin, limbo.end
......................

limbo.begin is TeX material to be printed at the beginning of the limbo section, just before the text from @l commands.  See ATl. (This command was previous called just limbo, and that still works.)

Similarly, limbo.end is printed at the end of the limbo section.

Thus, the beginning of the file output by Fweave looks like this:

     \input fwebmac.sty

     \Wbegin{...}
        [contains \documentclass, \usepackage, <doc.preamble>, \begin{document}]

     <limbo.begin>
     [contents of any @l commands]
     [user's TeX commands from the limbo section]
     <limbo.end>

The limbo.end command is useful for printing the entire document in two-column format.  For more discussion, see LIndex.

meta.??? (Fweave)
.................

(To be finished.)

preamble.???
............

Additional TeX material can be inserted at the beginning of a named section with preamble.named and at the beginning of an unnamed one with preamble.unnamed.

dot_constant.???.?
..................

In FORTRAN, `dot' constants such as .LT. are begun and ended by periods.  In special circumstances, the beginning and ending characters may be modified by dot_constant.begin.L and dot_constant.end.L.

null_file
.........

The name of the null file or device.  For more discussion, see Change files.

Automatic file name completion
------------------------------

For more information, see -e.

USAGE TIPS and SUGGESTIONS
**************************

In this section are collected various tips and suggestions to help one make full use of Fweb.  Additional hints broken down by each supported source language can be found in Languages.

Converting an existing code to Fweb
===================================

To convert an existing code to Fweb, one should do the following. (The following simple procedure assumes that one puts all the subroutines into the unnamed module. However, other more elaborate schemes are possible.)

 1. Place invisible commentary about the author, version, etc. at the beginning of the source file by bracketing it with @z...@x.  The @z must be the first two characters of the file.

 2. Next, set the language by including a command such as @n or @c++.

 3. Place an @a command (switch into unnamed code) before each program unit (e.g., main program, subroutine, or function).

 4. Before each @a, place an @* or @ command, followed by TeX documentation about that particular section of code.

 5. 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 @<Name of module@> in place of the fragment you're replacing, then put that fragment somewhere else, prefaced by @ and @<Name of module@>=.

 6. Make sure your comments are valid TeX. (One can't have things like raw underscores or dollar signs in comments, since those cause TeX to take special actions.)

 7. Beautify and clarify your documentation by using code mode (enclosing stuff between vertical bars) liberally within your TeX.

 8. After you've seen the woven output, you may need to go back and format a few identifiers or section names so that Fweave understands them properly, or you may need to insert some pseudo-semicolons (@;), pseudo-expressions (@e), or pseudo-colons (@:) (see Pseudo-operators).

 9. Consider using Fweb's built-in macro preprocessor (see Macros) to make your code more readable---for example, replace raw numerical constants by symbolic names.

 10. Scientific programmers may benefit from built-in macro-like functions like $PI; see Built-in functions.

 11. If you are a FORTRAN user,  for ultimate readability consider converting to 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 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]:

          M-x replace-regexp RET
          C-q C-j \.{\ \ \ \ \ }[\^\.\ tab 0]RET
          \\\\ C-q C-j \.{\ \ \ \ \ \ }RET

     Get rid of the keywords such as then or end if in favor of braces. Change singly-quoted character strings to doubly-quoted ones.  The -nC option (see -nC) may be helpful.

Programming tips and other suggestions
======================================

 1. Learn how to use the GNU info browser to access the on-line documentation.

 2. Read the list of new features and changes for the last several releases.  See New features.

 3. Periodically check ftp.pppl.gov:/pub/fweb/READ_ME for bug reports and other news.  Make bug reports!  See Support.

 4. If you have a color terminal, try the option -C1 (see -C_, see Color).

 5. Any option in .fweb that is intended to be processed after the command-line options should begin with & rather than -.  (This is rarely necessary.) See Initialization

 6. Put standard command-line options into .fweb.  Also put there standard style parameters---e.g.,

          -pindex.tex "#.ndx"
          -pmodules.tex "#.mds"
          -pcontents.tex "#.cts"

 7. Learn how to use the style file. See Style.

 8. Use the info options -@, -D, -y, and -Z to find out about various internal Fweb tables (control codes, reserved words, memory allocations, and style-file parameters). See Info options.

 9. Begin all Fweb sources with invisible commentary bracketed by @z...@x. See ATz.

 10. Always include an explicit language-setting command in the limbo section.  Under normal circumstances, do not set the language from the command line. See Languages.

 11. Keep sections quite short. Knuth suggests a dozen lines.  That's quite hard to achieve sometimes, but almost never should a section be more than a page long.  If a block of code is longer than that, split it up using named modules.

 12. It's easy to define macros from the command line to expedite conditional preprocessing. See -m.

 13. Use the preprocessor construction @#if 0...@#endif to comment out unwanted code. See Preprocessing.

 14. For logical operations with the preprocessor, use ||, not |.

 15. It's conventional to identify the ends of long preprocessor constructions as follows:

          @#if A
          .
          .
          @#endif // |A|

 16. To debug an errant Fweb macro, use the built-in function $DUMPDEF. See $DUMPDEF.

 17. Use @? for compiler directives.  See AT?. Use the style-file parameters cdir_start to specify information that will be written out at the beginning of the line. See cdir_start.

 18. Stick to the standard Fweb commenting style /*...*/ or //....  Don't use alternatives such as FORTRAN's column 1 convention; these may not work or may not be supported someday. See Comments.

 19. The meta-comment feature @(...@) provides a poor-person's alignment feature.  But it doesn't work very well, and it's not in the spirit of TeX; learn to use \halign or the LaTeX alternatives.

 20. In FORTRAN, use #:0 to declare readable alphabetic statement labels.  See Tokens and -colon.

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

 22. Use LaTeX.  Plain TeX is no longer supported.   Upgrade to LaTeX2e.  See LaTeX.

 23. If you are reading this documentation from printed pages, make sure it's also installed as an Info package on your system so it can be read interactively with emacs.  You can also read it through a World-Wide Web browser such as Netscape.  For the address, see Support.

Features for scientific programming
===================================

Fweb contains a few features particularly intended for scientific programming.

 1. Several built-in functions generate numerical constants.  See $PI ($PI) and $E ($E).

 2. Several built-in functions perform mathematical manipulations.  See $EXP ($EXP), $POW ($POW), $SQRT ($SQRT), $LOG ($LOG), $LOG10 ($LOG10), $MAX ($MAX), and $MIN ($MIN).

 3. The do-loop macro $DO may be useful.  See $DO.

 4. C-style array indices can be used by means of the -n) option. See -n).

 5. An active bracket feature helps improve the appearance of woven code that uses subscripts and/or superscripts heavily.  See -W[.

NEW FEATURES
************

This info documentation is now accessible on the World-Wide Web; see Support.

Some things that have been added or changed in recent releases are described in the following.

Version 1.61
============

Updates to documentation (v1.61)
--------------------------------

      1. Fweb supports color modes in which messages to the terminal can appear in colors chosen by the user; see Color.  The color mode is set by the new command-line option -C (see -C_).

      2. A previously undocumented feature is that for the C-like and Fortran-like languages, Ftangle expands the binary notation 0b... to an unsigned decimal number. See Phases.

Redefined commands (v1.61)
--------------------------

A few obscure commands have been slightly redefined.  Sorry about that, but it makes for more symmetry and ease of recall, and/or solves some technical problems.

      1. Although it was never documented, previous versions permitted either lower or upper case for the @ commands that set the language---e.g., both @c and @C worked.  Now only the lower-case forms work.  (The upper-case forms may have other meanings.)

      2. The style-file parameter Ext_delimiter now begins with an upper-case E; formerly it was lower-case.

      3. The behavior of the optional argument of the \Title macro has been slightly redefined.  The new, more symmetrical form is

               \Title[Short title]{Long title}

          where Long title is printed on the title page and Short title is used for the running header within the document.  See Table of Contents.

      4. The line-break commands @/ and @\ (formerly identical) now behave slightly differently.  @/ breaks the line just as it would if the line had been too long and been spontaneously broken. See AT/.  @\ backspaces one unit of indentation after breaking the line.  See ATbs.  Usually, one should use @/ (sorry; I was previously recommending @\.  For an example in which it is natural to use @\, see ATbs.

      5. The names of some of the code-typesetting macros in fwebmac.sty have been changed to conform to the convention that they should all start with W.  This change will be invisible to you unless you happen to have user macros of your own that start that way or (perish the thought) you have redefined low-level and obscure code in fwebmac.sty.

New features (v1.61)
--------------------

This release adds some features for managing large projects, including (i) the idxmerge utility that merges indexes produced by several Fweb files, (ii) a mechanism for accessing RCS-like information in the ignorable commentary at the beginning of the file, and (iii) the ability to include Fweave-formatted code into a standard LaTeX document.  It also fixes a variety of miscellaneous bugs.

      1. A stand-alone index file suitable for processing by makeindex can be produced by the -XI option.  See Using makeindex.

      2. Stand-alone indexes produced by -XI can be merged with the idxmerge utility.  See Merging indexes.

      3. Fweave-formatted code can be included in a standard LaTeX2e document by means of the fwebinsert package. See Inserting woven code.

      4. Revision-control-system (RCS) information that appears in the ignorable commentary between the optional @z and @x that begin an Fweb file (see ATz) is accessible in the body of the file through the built-in function $KEYWORD (see $KEYWORD) and the new commands @K (see ATK_) and @k (see ATk). These features can access RCS-like keywords that are not known to RCS itself, as long as they fit the proper syntax (see ATz).

      5. The -h option now permits easy access to the GNU info browser if it is installed.  See -h.

      6. Underscored versions of built-in functions have been removed!!!  E.g., use $IF, not _IF.  This change was warned about in the last release.

      7. Single-character identifiers can now be completely cross-referenced via the -W1 option.  See -W1.

      8. Some module warning messages can be eliminated with the -W@ option.  See -WAT.

      9. The @q command (still experimental) has been added to locally turn on or off the the line and module comments in the tangled output. See ATq.

      10. The level of verbosity of Fweb's informational messages can be controlled with the -M option. See -M_.

      11. C/C++ programmers may find the command @{ useful.  See ATlb.

      12. The -nC option has been added for FORTRAN users; it kills commented lines at a very early stage in the processing.  This can be useful when converting existing codes to Fweb. See -nC

      13. FORTRAN-90 (see -n9) now defaults to free-form syntax.

      14. As of the non-beta Version 1.61, free-form FORTRAN-90 now inserts semicolons automatically in the code part.  Thus, textbook FORTRAN-90 examples will weave correctly without the annoyance of explicitly terminating each statement with a semicolon.  (If you prefer to put in the semicolons explicitly, use --n; to turn off the auto-insertion.) See -n;

      15. The default meaning of the -k option was changed; now both lower- and upper-case forms of FORTRAN I/O keywords are recognized. See -k.

      16. Various changes were made to internal code in fwebmac.sty.  This should not affect anyone unless you have redefined fwebmac macros.  If so, you'll have to compare your versions with the present ones.  For example, colons as argument delimiters in \defs have been removed.

      17. It is now (barely) possible to use \documentstyle{revtex} instead of the default \documentclass{article}.  See REVTeX.

Significant bugs (v1.61)
------------------------

      1. Perhaps the most significant bug is that some high-order (>= 128) characters in strings may not typeset or be processed correctly.  This may be an issue for some users of foreign-language packages.  The difficulty arises from a design decision made by a previous author. This has at least partly been fixed, but I eschewed a substantial overhaul for fear of breaking other things.

Version 1.53
============

This release fixes a relatively small number of obscure bugs in fweb-1.52-beta.  A few minor enhancements were also made.  They include

      1. Sections can be numbered by consecutive integers rather than LaTeX's default Dewey-decimal form by saying

               LaTeX.package = "fwebnum"

          See Sections.

      2. The -H option (experimental and incomplete) was added. For C and C++, this option tells Fweave to scan #include files for typedef and/or class definitions.  See -H_.

      3. The -k option was added.  This tells FORTRAN and RATFOR to understand the lower-case forms of I/O keywords such as iostat (with the exception of read, write, and end).  See -k.

      4. The -n: option was added.  This tells FORTRAN to place statement labels on a separate line, which is useful when the labels are relatively long.  (By default, FORTRAN labels are placed on the same line as the thing they are labeling, which looks good for short labels.)  See -ncolon

      5. The preprocessor command @#line was added.  For C code, this adds an explicit #line command to the tangled output file.  This helps to keep the line numbers between debugger and source file in sync when an Fweb preprocessor statement expands to several lines. See Debugging with macros.

          An implicit @#line command is added after each @% (see AT%) that begins a line (this keeps line numbering correct). To override this, use the option -T#.  See -T#.

      6. -p (style-file) options (see -p) on the command line are now processed after the local style file.  See Style.

      7. The functionality of the -D command was enhanced to include optional arguments that limit the information that will be listed.  See -D_.

Version 1.52
============

This release was issued only as a beta version.  It consists mostly of bug fixes.  However, there are a few other interesting points.

      1. fwebmac.sty was enhanced to warn the user to run LaTeX again when the section numbering hasn't yet been brought up to date.  I'm not sure I've covered all the bases, but before it didn't complain at all.

      2. C++ classes are now formatted (identified as reserved words) on the first pass, so forward references such as

               @ The class |C|...
               @a
               class C
                 {}

          will now work.  Note that typedef has done this for a while, although there are still a few glitches.

      3. For two years, the documentation has described two control codes as follows:

               @~ --- inhibit line break.
               @+ --- force an index entry.

          Apparently the code had these definitions inverted; it has now been brought up to date with the documentation.  Fortunately these commands are evidently not heavily used, since no one complained.

      4. fwebmac.sty was further reworked to interact properly with the user package multicol.  If in fweb.sty one says LaTeX.package "multicol", then the two-column index is done with multicol; this gives various improvements over the \twocolumn format that was used previously.  Furthermore, it's possible to use multicol to do one's entire document in two-column format.  This turned out to be relatively simple, but one needs to get the commands in the proper order.  See LIndex for more details.  Two-column format substantially cuts down the white space; I saved about 50% on a 200-page code.

          One known glitch with Fweb/multicol is that if one selects page-number cross-references instead of LaTeX section numbers, page references such as 98c don't get the 'c' correct.  This is presumably not a big deal.  At this point, assume that the use of multicol is highly experimental.

      5. Further bugs in the C and C++ production rules were fixed.

Version 1.50
============

      1. The syntax for entries in the initialization file .fweb (see Initialization) has been modified (in a way that is as backward-compatible as possible). Previously, + meant process the option before the command-line options, - meant process it after.  This convention was somewhat hard to remember, given the statement that any command-line option could be put into .fweb; furthermore, just about everything in .fweb should, in fact, be processed before the command-line options.  So now both + and - mean the same thing, namely process before (and the + notation should fade away as time goes on).  If you explicitly want something to be processed after all command-line options for some tricky reason, begin it with &. I.e., scan your .fweb file for any line beginning with - and replace that with &.

      2. The LaTeX processor (-PL) is now the default.

      3. The experimental fwebmacL.sty macro package supplied with version 1.40 has been substantially reworked and is now the default fwebmac.sty.  Remove any reference to fwebmacL.sty from your .fweb file.

      4. Support for LaTeX2e is now provided.  See LaTeX.

      5. The style-file parameter index.name was added.  This is the section name to be given to the Index (see Index), which should be the last major (starred) section.  It becomes the contents of the macro \INDEX.  Therefore, one can end one's source file by saying

               @* \INDEX.

      6. The $IF... class of built-in functions was reworked.  They should now be more robust, recursive, and intuitive.  Simple uses of these functions should work as before.  However, complicated uses that depended on tricky things about the order of expansion of arguments may require revision.  Carefully compare the descriptions of these functions in the documentation (e.g., see $IF) with your usage of them in any pre-existing code.

          In some cases, if a previous constructions using $IF no longer works, it might work if you say

               @m $IF(a,b,c) $$IF(a,b,c)

          and then use $$IF in your code.  (This forces an extra level of macro expansion.)  The same remark goes for $DEFINE.

          The old forms _IF etc. no longer work; convert to $IF.

      7. The option -j was added.  This inhibits multiple inclusions via @i of the same include file. See -j.

      8. One now has the ability to change the comment character that begins Ftangle's line command.  In the style file, say, e.g.,

               line_char.N '#'

          to change the default *line output by Ftangle in FORTRAN mode to #line.  This could be useful if one runs the C preprocessor on the tangled FORTRAN output.

      9. Fweave's processing of typedef statements in C and C++ was improved.

      10. Fweb should now be able to process C++ templates and exception handling, at least in simple situations.  The typesetting of C++ references (e.g., int&) was also improved.  Please report any difficulties.

      11. There were various miscellaneous obscure bug fixes.

Version 1.40
============

      1. The meaning of @+ has changed.  (SORRY!)  Formerly, this inhibited a line break; that function is now performed by @~. The new meaning of @+ is to force an index entry (the opposite of @-, which inhibits an index entry).

          If you have large codes using the old @+ that you do not wish to convert, you can recover the old mappings by placing the following commands into fweb.sty:

               yes_index = "~"
               no_line_break = "+"

          However, please try to make the conversion; the new codes are intended to be more symmetrical and easier to remember.

      2. Built-in functions now begin with $, not _.  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 $EVAL and _EVAL interchangably.  However, do not use the underscore forms; they will be deleted in future releases.

      3. Full LaTeX support.  Fweb no longer usurps LaTeX's \output routine, and LaTeX'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.)

      4. Verbatim language.  @Lv selects a language-independent format. See Verbatim

      5. 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 -N or the local command @N. See ATN_.

      6. Writing of temporary files.  When the -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.  See -F_.

      7. Converting output tokens to lower case.  See -U_.

      8. The built-in functions $E and $PI.  See $E, $PI.

      9. The built-in functions $EXP, $LOG, and $LOG10.  See $EXP, $LOG, and $LOG10.

      10. $MAX and $MIN generalized to take arbitrary list of arguments.  See $MAX, $MIN.

      11. The marriage-saver option.  In response to a serious user request, see -B_.

SUPPORT
*******

Fweb is supported by John Krommes, krommes@princeton.edu. This project is a definitively spare-time activity!!!  Bug reports submitted with very short test files will be verified, although not necessarily in real time.  For very simple fixes, a change file may be provided.  Generally, however, bugs are not fixed until the next release.  Releases occur intermittently, depending on my many other professional obligations.

Suggestions are very welcome.  Many of Fweb's current features were incorporated in response to users' requests.  However, the queue for future improvements is long; nothing may happen immediately.  The next major release of Fweb, Version 2.00, is planned for approximately the year 2000.  (You may be relieved to know that, to the best of my knowledge, Fweb does not suffer from the Y2K bug.)

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

     http://w3.pppl.gov/~krommes/fweb_toc.html.

You can subscribe to one or both of two Fweb mailing lists, fweb-users and fweb-installers.  To subscribe, send e-mail to majordomo@pppl.gov.  In the body of the message, say, e.g.,

     subscribe fweb-users

You will receive introductory information describing how these lists are intended to be used.  To unsubscribe at any time, substitute unsubscribe for subscribe in the above instructions.

Archive files containing the messages sent to the Fweb mailing lists are kept in

     ftp.pppl.gov:/pub/fweb/archive/fweb-{users,installers}.archive.

In addition to anonymous ftp, these files may be obtained by sending a message to majordomo@pppl.gov of the form

     get fweb-users fweb-users.archive.

Installing Fweb
***************

Here is the bare-bones installation procedure for UNIX users:

 1. Download the zgip-compressed tar file from ftp.pppl.gov:/pub/fweb. The name of the file contains the version number---e.g., fweb-1.61.tar.gz.

          ftp ftp.pppl.gov
          bin
          get fweb-1.61.tar.gz
          quit

 2. Uncompress and unpack the tar file:

          gunzip fweb-1.61.tar.gz
          tar -xf fweb-1.61.tar

     If the GNU tar is installed, these two steps can be combined into

          gtar -xzf fweb-1.61.tar.gz

     Unpacking creates the directory fweb-1.61, with at least the two subdirectories Web and Manual.

 3. Change to the new Web subdirectory and run the configuration script.

          cd fweb-1.61/Web
          ./configure

     ./configure is an sh script.  It attempts to figure out various local system features automatically, then generates the three files defaults.mk, config.h, and custom.h; those are used in the make.  For further information about the operation of ./configure, see fweb-1.61/READ_ME.FWEB.

 4. Make and install the release:

          make [CFLAGS='special compiler flags']
          make install

     If gcc is available, it will be used in the make; in that case, the default CFLAGS should be sufficient.  If another compiler is used, ensure that it is run in ANSI-compatible mode, not the old-style Kernighan and Ritchie.

     Fweb compiles on my system without any warnings with gcc -ansi -pedantic.  Please report any compiler warnings from an allegedly ANSI-C environment.