This is Info file fweb.info, produced by Makeinfo-1.55 from the input
file fweb.texinfo.

   This file documents FWEB...

   Copyright 1993 John A. Krommes

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

   Permission is granted to process this file through TeX      and
print the results, provided the printed document      carries a copying
permission notice identical to this      one except for the removal of
this paragraph (this      paragraph not being relevant to the printed
manual).

   Permission is granted to copy and distribute modified      versions
of this manual under the conditions for      verbatim copying, provided
also that the section      entitled "Copying" is included exactly as in
the original, and provided      that the entire resulting derived work
is distributed      under the terms of a permission notice identical to
this      one.

   Permission is granted to copy and distribute      translations of
this manual into another language,      under the above conditions for
modified versions,      except that this permission notice may be
stated in a      translation approved by the author.


File: fweb.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)

FWEB
****

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

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

   This Texinfo documentation describes FWEB Version 1.40, which
initiates a major upgrade project.  This version contains significant
improvements and new features, both visible and invisible to the user.
*THERE WILL BE BUGS.*  If you are involved in a large programming
project dependent on FWEB, it is not recommended that you upgrade this
version unless you have a need for specific bug fixes.  Versions 1.4?
are not intended for new users, but only for very patient friends.

* Menu:

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

 -- The Detailed Node Listing --

INTRODUCTION to FWEB

* History::             History of literate programming.
* Features::            Special features of FWEB.

WEB CONCEPTS

* Processors::          FTANGLE and FWEAVE.
* Phases::              Phases of operation of the FWEB processors.
* Structure::           The structure of a web.
* Modules::             Use of named and unnamed modules.

FILES

* Input files::         Input files.
* Output files::        Output files.
* Change files::        Change files.

Input files

* Completion::          Automatic file-name completion.

RUNNING FWEB

* Syntax::      Command-line syntax.
* Options::     Command-line options.

Command-line options

* Negating options:: How to invert the meaning of an option.
* -1::          Brief debugging mode.
* -2::          Verbose debugging mode.
* -@: -AT.      Display information about control codes.
* -A: -A_.      Turn on ASCII translations.
* -B: -B_.      Turn off audible beeps.
* -b::          Number blocks.
* -c::          Set global language to C.
* -c++: -cpp.   Set global language to C++.
* -D: -D_.      Display information about FWEB's reserved words.
* -d::          Convert unnumbered `do...enddo's to Fortran-77.
* -E: -E_.      Change the delimiter of a file-name extension.
* -e::          Turn on automatic file-name completion.
* -F: -F_.	Compare output files with old versions.
* -f::          Turn off module references for identifiers.
* -h::          Where to get help.
* -I: -I_.      Append a directory to search list for include files.
* -i::          Don't print contents of @I include files.
* -i!::         Don't even read @I include files.
* -L: -L_.      Select global language.
* -l::          Echo the input line.
* -m::          Define a WEB macro.
* -m4::         Understand the m4 built-in commands.
* -m;::         Append pseudo-semicolons to WEB macro definitions.
* -n::          Set global language to Fortran-77.
* -n9::         Set global language to Fortran-90.
* -n;::         For Fortran-77, supply semicolons automatically (default).
* -nb::         In Fortran, number the ifs and dos.
* -np::         Print semicolons in woven Fortran output.
* -n\::         In Fortran-90, free-form syntax continued with '\\'.
* -n&::         In Fortran-90, free-form syntax continued with '&'.
* -n/::         In Fortran, recognize '//' as the start of a short comment.
* -n!::         In Fortran, make '!' denote the start of a short comment.
* -n)::         In Fortran, reverse array indices.
* -o::          Turn off FWEAVE's mechanisms for overloading operators.
* -q::          Don't translate Ratfor.
* -P: -P_.      Select TeX processor.
* -p::          Set style parameter.
* -r::          Set the global language to Ratfor-77.
* -r9::         Set the global language to Ratfor-90.
* -rb::         In Ratfor, number the ifs and dos.
* -rg::         Set |goto| parameters.
* -rk::         Suppress comments about Ratfor statement translation.
* -rK: -rK_.    Write out comments about Ratfor statement translation.
* -r;::         Turn on Ratfor's auto-semi mode.
* -r/::         In Ratfor, recognize '//' as the start of a short comment.
* -r!::         In Ratfor, make '!' denote the start of a short comment.
* -r)::         In Ratfor, reverse, array indices.
* -s::          Print statistics about memory usage.
* -T: -T_.      Flag-setting commands for FTANGLE.
* -t::          Truncate identifiers.
* -U: -U_.      Convert reserved output tokens to lower case.
* -u::          Undefined a predefined or command-line macro.
* -v::          Make all comments verbatim.
* -W: -W_.      Flag-setting commands for FWEAVE.
* -w::          Modify processing of `fwebmac.sty'.
* -X: -X_.      Print selected cross-reference information.
* -x::          Reduce or eliminate cross-reference information.
* -y::          Allocate dynamic memory.
* -Z: -Z_.      Display default values of style-file parameters.
* -z::          Change name of style file.
* -.::          Don't recognize dot constants.
* -\::          Explicitly escape continued strings.
* -(: -lp.      Continue parenthesized strings with backslashes.
* -: -colon.    Set starting automatic statement number.
* ->::          Redirect tangled output.
* -=::          Redirect tangled output.
* -#::          Don't print comments about line numbers and module names
                in tangled output.
* -+: -plus.    Don't interpret compound assignment operators.
* -/::          Recognize '//' as the start of a short comment.
* -!::          Make '!' denoted the start of a short comment.

* Info options:: Information options.

`-T':  Flag-setting commands for FTANGLE.

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

`-W':  Flag-setting commands for FWEAVE.

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

WEB COMMANDS

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

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

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

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

Control codes b-z:
* @b: ATb.      Insert breakpoint command.
* @c: ATc.      Set language to C.
* @c++: ATcpp.  Set language to C++.
* @D: ATD_.     Define outer macro.
* @d: ATd.      Define outer macro and mark it.
* @f: ATf.      Format identifier or module name.
* @I: ATI_.     Include a WEB file, but don't print it.
* @i: ATi.      Include a WEB file.
* @L: ATL_.     Set language.
* @l: ATl.      Specify limbo text.
* @M: ATM_.     Define a WEB macro.
* @m: ATm.      Define a WEB macro and mark it.
* @N: ATN_.     Turn on language-independent mode.
* @n: ATn.      Set language to Fortran-77.
* @n9:ATn9.     Set language to Fortran-90.
* @O: ATO_.     Open new output file (global scope).
* @o: ATo.      Open new output file (local scope).
* @r: ATr.      Set language to Ratfor-77.
* @r9: ATr9.    Set language to Ratfor-90.
* @u: ATu.      Undefine an outer macro.
* @v: ATv.      Overload an operator.
* @W: ATW_.     Overload an identifier.
* @x: ATx.      Terminate ignorable material.
* @y: ATy.	 End first part of change.
* @z: ATz.      Begin ignorable material.

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

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

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

Special brace:
* @{: ATlb.        Suppress default insertion of breakpoint command.

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

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

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

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

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

COMMENTING STYLES

* Invisible comments::          Skipping input material.
* Visible comments::            Comments in code mode.

MACROS and PREPROCESSING

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

WEB macros

* Macro features::      Various points about WEB macros.
* Tokens::              Special tokens used in WEB macros.
* Built-in functions::  Macro functions built into FWEB.

Built-in functions

* $A::                  Convert to ASCII.
* $ABS::                Absolute value.
* $ASSERT::             Assert a condition.
* $COMMENT::            Generate a comment.
* $DATE::               Today's date.
* $DAY::                Today.
* $DECR::               Decrement a macro.
* $DEFINE::             Define a macro.
* $DO::                 Macro `DO' loop.
* $DUMPDEF::            Dump macro definitions to the terminal.
* $E::                  2.71828...
* $ERROR::              Send error message to output.
* $EVAL::               Evaluate an expression.
* $EXP::                Exponential function.
* $GETENV::             Get value of environment variable.
* $HOME::               The user's home directory.
* $IF::                 Two-way conditional:  "If expression is true"
* $IFCASE::             n-way conditional.
* $IFDEF::              Two-way conditional:  "If macro is defined"
* $IFNDEF::             Two-way conditional:  "If macro is not defined"
* $IFELSE::             Two-way conditional:  "If macro1 equals macro2"
* $INCR::               Increment a macro.
* $INPUT_LINE::         Line number that begins current section.
* $L::                  Change string to lower case.
* $LANGUAGE::           Identifier for current language.
* $LANGUAGE_NUM::       Number of current language.
* $LEN::                Length of string.
* $LOG::                Natural logarithm.
* $LOG10::              Logarithm to the base 10.
* $M::                  Define a macro.
* $MAX::                Maximum of one or more elements.
* $MIN::                Minimum of one or more elements.
* $MODULE_NAME::        Name of present WEB module.
* $MODULES::            Total number of independent modules.
* $OUTPUT_LINE::        Current line number of tangled output.
* $P::                  The C preprocessor symbol `'#''.
* $PI::                 3.14159...
* $POW::                Raise to a power.
* $ROUTINE::            Current RATFOR program, function, or subroutine.
* $SECTION_NUM::        Number of current section.
* $SECTIONS::           Maximum number of sections.
* $SQRT::               Square root.
* $STRING::             Expand argument, then stringize.
* $STUB::
* $TIME::               The local time.
* $TRANSLIT::           Transliterate a string.
* $U::                  Change string to upper case.
* $UNDEF::              Undefine a WEB macro.
* $UNQUOTE::            Remove quotes from string.
* $VERBATIM::           (Obsolete.)
* $VERSION::            FWEB version number.

LANGUAGES

* Setting::             Setting the language.

Special hints and considerations for each language.
* C::                   C
* C++: Cpp.             C++.
* Fortran::             Fortran-77 and Fortran-90.
* Ratfor: Ratfor_.      RATional FORtran.
* TeX::                 TeX.
* Verbatim::            Literal mode.

RATFOR

* Commands::            Ratfor commands.
* Caviats::             Nuances about FWEB Ratfor.

FORMATTING

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

Typesetting

* Output::	Structure of the TeX output from FWEAVE.
* LaTeX::	Specifics of the LaTeX support.

LaTeX support

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

Customizing LaTeX's output

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

Pretty-printing

* Alternatives::        Alternatives for various input tokens.
* Pseudo-operators::    Invisible parts of speech.
* Overloading::         Changing the appearance of various quantities.

CUSTOMIZATION

* Environment variables::       Environment or logical variables.
* Initialization::              Initialization file.
* Memory allocation::           Dynamic memory allocation.
* Style::                       Style file.

Memory allocation

* -yb::         Maximum bytes for identifiers, index entries, and module names.
* -ybs::        Size of the change buffer.
* -ycb::        Size of line buffer for C output.
* -ycf::        A Ratfor buffer.
* -ycg::        Another Ratfor buffer.
* -yd::         Increment for expanding the dots table.
* -ydt::        Maximum number of deferred macro tokens.
* -ydx::        Maximum Number of deferred macro texts.
* -ykt::        Stack size for FTANGLE.
* -ykw::        Stack size for FWEAVE.
* -yll::        Line length for FWEAVE's output.
* -yln::        Maximum length of module names or strings.
* -ylb::        Maximum number of nested loops in Ratfor.
* -ylx::        Maximum length of expressions that can be expanded with
                        the post-increment operators of Fortran or Ratfor.
* -ym::         Maximum number of sections.
* -yma::        Maximum number of arguments to WEB macros.
* -ymb::        Size of the buffer for expanding WEB macros.
* -yn::         Maximum number of identifiers, strings, and module names.
* -ynf::        Maximum number of open input files.
* -yop::        Maximum number of entries in the table for operator
                        overloading.
* -yr::         Maximum number of cross-references.
* -ys::         Maximum number of scraps.
* -ysb::        Size of style-file buffer.
* -ytt::        Maximum number of tokens that FTANGLE can process.
* -ytw::        Maximum number of tokens in the current section being
                        processed by FWEAVE.
* -yx::         Maximum number of texts.
* -yxb::        Size of line buffer for TeX output.

The Style file

* Index params::                Customizing the index.
* Module params::               Customizing the list of sections.
* Contents params::             Customizing the table of contents.
* Subscript params::            Customizing subscripting for cross-references.
* Fwebmac params::              Customizing behavior of FWEB's macros.
* Completion params::           Automatic selection of file extensions, etc.
* Control-code mappings::       Remapping FWEB's control codes (danger)!
* Miscellaneous params::        Other customizations.

Customizing FWEAVE's index

* delim_0: S_delim.             Insert after identifier in index entry.
* delim_n: S_delim.             Insert between section numbers in index entry.

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

* group_skip::

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

* item_0::                      TeX command to begin an index entry.

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

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

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

Customizing the module list

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

Customizing the table of contents

* contents.postamble: S_contents. TeX commands to end table of contents.
* contents.preamble: S_contents.  TeX commands to begin table of contents.
* contents.tex: S_contents.       Name of contents file.

Customizing cross-reference subscripts

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

Customizing the behavior of `fwebmac.sty' macros

* format.reserved: S_format.
* format.short_identifier: S_format.
* format.outer_macro: S_format.
* format.WEB_macro: S_format.
* format.intrinsic: S_format.
* format.keyword: S_format.
* format.typewriter: S_format.
* format.wildcard: S_format.

* indent.TeX: S_indent.         Paragraph indentation for TeX part.
* indent.code: S_indent.        Paragraph indentation for code part.

* LaTeX.options: S_LaTeX.       Set options for document style.
* LaTeX.style: S_LaTeX.         Specify document style.

Miscellaneous style-file parameters

* ASCII_fcn::                   Routine for converting strings to ASCII.
* cchar::                       Continuation character for Fortran.
* cdir_start::                  `?' translates to this.
* line_length: S_line_length.

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

* outer.def: S_outer.           FTANGLE converts `@d' to this.
* outer.undef: S_outer.         FTANGLE converts `@u' to this.

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

For FWEAVE:

* macros::                      Default name of the macro package to be
                                        read in by FWEAVE.
* limbo::                       Default material to begin the limbo part

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

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

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

For both processors:

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

* null_file::                   Name of the null file.

Automatic file name completion:

* ext.web: S_ext.        Extensions for the web file.
* ext.change: S_ext.     Extensions for the change file.
* ext.hweb: S_ext.       Extensions for include files.
* ext.hchange: S_ext.    Extensions for change files associated with
                                include files.


File: fweb.info,  Node: Copying,  Next: Intro,  Prev: Top,  Up: Top

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, *Note
Distribution: (emacs)Distrib.

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


File: fweb.info,  Node: Intro,  Next: Concepts,  Prev: Copying,  Up: Top

INTRODUCTION to FWEB
********************

   FWEB is a system for "literate programming".  It was originally
intended for scientific programming, and is in wide use in that arena;
however, it has much broader applicability.  It is an extension of
Knuth's WEB system that handles the specific languages C, C++, Fortran,
Ratfor, and TeX.  It also supports a WYSIWYG language-independent mode
as well as a (closely-related but not identical) verbatim `language'.

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

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

* Menu:

* History::             History of literate programming.
* Features::            Special features of FWEB.


File: fweb.info,  Node: History,  Next: Features,  Prev: Intro,  Up: Intro

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

   (To be completed; see Knuth's book.)


File: fweb.info,  Node: Features,  Prev: History,  Up: Intro

FWEB features
=============

   FWEB is distinguished from its relatives in several respects:

   * FWEB introduces the concept of a current language (*note
     Languages::.), so more than one compiler language can be processed
     in a single WEB run.

   * FWEB understands the syntaxes of several of the more important
     compiler languages:  C, C++, Fortran, 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.
     *Note Ratfor::.

   * FWEB has a built-in C-like macro preprocessor, which should be
     especially useful for Fortran and Ratfor.  *Note Macros::, *Note
     Preprocessing::.

   * Many aspects of FWEB's behavior can be customized by means of
     setting parameters in a style file.


File: fweb.info,  Node: Concepts,  Next: Files,  Prev: Intro,  Up: Top

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

   The principle concepts of WEB programming are laid out in Knuth's
book, the reference to which is given in *Note 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.

* Menu:

* Processors::          FTANGLE and FWEAVE.
* Phases::              Phases of operation of the FWEB processors.
* Structure::           The structure of a web.
* Modules::             Use of named and unnamed modules.


File: fweb.info,  Node: Processors,  Next: Phases,  Prev: Concepts,  Up: Concepts

The FWEB processors
===================

   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 be processed with TeX
or LaTeX.  For detailed descriptions of the LaTeX support, see *Note
LaTeX::.


File: fweb.info,  Node: Structure,  Next: Modules,  Prev: Phases,  Up: Concepts

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

   An FWEB source file is structured into sections.  Each section
consists of three (optional) parts: the

  1. TeX part;

  2. definition part; and

  3. code part.

Sections can be combined into larger units called "modules", as
explained in *Note Modules::.

   A simple example of an FWEB source file consisting of two sections
is as follows:

     @n
     
     @* INTRODUCTION.
     This code is intended...
     
     @m PI 3.14159
     
     @a
             program main
             call compute
             end
     
     @ The computational routine is pretty boring.
     @a
             subroutine compute
             write(*,*) 'pi = ', PI
             end

   Commands to FWEB are begun by the `@' symbol (*note AT commands::.).
In this example, the first command, `@n', sets the global language to
Fortran-77.  For more information about languages, see *Note
Languages::.

   The `@*' command begins a major section (corresponding to LaTeX's
`\section' command); this command is followed by the section name,
terminated by a period.  Major sections are entered in the table of
contents.  The command `@*n' begins a major (sub)section of level n,
where `@*0' is equivalent to the simple `@*', `@*1' indicates a
subsection, `@*2' indicates a subsubsection, and so on.

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

   All sections begin with TeX commentary.  This is followed by an
optional definition part.  The beginning of the definition part is
signaled by the appearance of any one of the commands `@d', `@f', `@m',
`@v', `@W'.  In the example, the first section has a definition part
consisting of one macro definition (`@m'); the second section has no
definition 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 *Note Modules::.

   The portion of the source file before the first section (i.e., before
the first `@*' or `@ ') is called `in limbo' or `the limbo part'.  The
only `@' commands that are allowed in limbo (in addition to `@@', which
is allowed anywhere) are the language-changing commands, and one of
those should appear.  Other text in limbo is ignored by FTANGLE and is
copied by FWEAVE to the output file.  Thus, one can make TeX macro
definitions in limbo that override the defaults in FWEB's style file
`fwebmac.sty'.  (Another way of getting TeX text into the limbo part is
by means of the `@l' command; see *Note ATl::.)


File: fweb.info,  Node: Modules,  Prev: Structure,  Up: Concepts

Modules
=======

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

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

   The unnamed module is introduced by the command `@a'.  Subsequent
uses of `@a' accrete code to the unnamed module.  *FTANGLE outputs the
unnamed module.*

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

   A module name is specified by

     @< Arbitrary TeX text @>

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

   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 original section.  Thus, a named module
might ultimately consists of the code from sections 2, 5, and 8, for
example.

   To use a named module, simply use the name anywhere in a code part;
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;
     }

After a name has appeared once in full, it may be abbreviated by a
unique prefix followed by 3 dots, as demonstrated in the above example.
By convention, a complete module name cannot be a subset of another.
For example, `@<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@>@;

This way, global variable definitions can be introduced as needed, but
will be guaranteed to appear at the top of the code.  Function
prototypes could be handled this way as well; alternatively, they could
all be collected into one section, perhaps at the end of the source
file.  (The above organization still guarantees that they will appear at
the beginning of the output.)  Functions could be introduced one at a
time in unnamed sections.


File: fweb.info,  Node: Phases,  Next: Structure,  Prev: Processors,  Up: Concepts

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

   The FWEB processors perform their work in several distinct phases.

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 source;

   * expands `@'...'', `@"..."', and `0b...' (in Fortran, also `0...'
     and `0x...');

   * stores code text in appropriate modules;

   * memorizes macro definitions (`@d' and `@m').  *Note ATd::, *Note
     ATm::.

   Phase 2

   * outputs outer macro definitions (`@d');

   * outputs the unnamed module (`@a');

   * expands WEB macros (`@m');

   * expands built-in macros (*note Built-in functions::.);

   * translates Ratfor statements.  *Note Ratfor::

The phases of FWEAVE
--------------------

   FWEAVE has three phases.  In phase 1, the source file is read and
cross-reference information is collected.  In phase2, the source file is
read again, then pretty-printed including the cross-reference
information.  In phase 3, the index and table of contents are written.

   More specifically, phase 1

   * tokenizes and stores identifiers and module names;

   * collects cross-reference information;

   * stores limbo text definitions (`@l') (*note ATl::.);

   * collects information about overloaded operators (`@v') and
     identifiers (`@W').  *Note ATv::, *Note 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 to appropriate TeX macros.


File: fweb.info,  Node: Files,  Next: Starting,  Prev: Concepts,  Up: Top

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 in `custom.h' (*note
Customization::.).  The character that initiates the file-name
extension (normally a period) can be changed with the `-E' command-line
option (*note -E_::.).

* Menu:

* Input files::         Input files.
* Output files::        Output files.
* Change files::        Change files.


File: fweb.info,  Node: Input files,  Next: Output files,  Prev: Files,  Up: Files

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

   `.fweb' -- Initialization file; always in the home directory.

   `fweb.sty' -- Style file; in the directory of the WEB file    unless
changed by    environment variable `FWEB_STYLE_DIR'.  The basic name
can be    changed by the `-z' option (*note -z::.).

   `name.web' -- Source code.

   `name.ch' -- Change file.  *Note Change files::.

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

   `name.hch' -- Change file for include file.

* Menu:

* Completion::          Automatic file-name completion.


File: fweb.info,  Node: Completion,  Prev: Input files,  Up: Input files

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

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

     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., `"web wb"'; the first one that matches is used.


File: fweb.info,  Node: Output files,  Next: Change files,  Prev: Input files,  Up: Files

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

   `name.tex' -- Woven output to be processed with TeX or LaTeX.

   `CONTENTS.tex' -- Temporary file that accumulates table-of-contents
information.

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

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

   `name.ext' -- Compilable output file.

   The names of the three temporary files can be changed with style-file
options.  *Note Style::.  Commonly, one may put into the style file
`fweb.sty' commands such as

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

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

   The extensions for the compilable output file(s) have certain
defaults, but can be changed by style-file parameters according to the
following table:

     Language        Style-file entry    UNIX default   non-UNIX default
     
      C               suffix.C               .c              .c
      C++             suffix.Cpp             .c++            .cpp
      Fortran--77     suffix.N               .f              .for
      Fortran--90     suffix.N90             .f              .for
      Ratfor--77      suffix.R               .f              .for
      Ratfor--90      suffix.R90             .f              .for
      TeX             suffix.X               .sty            .sty
      VERBATIM        suffix.V               .mk             .mk


File: fweb.info,  Node: Change files,  Prev: Output files,  Up: Files

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

   The primary input to the FWEB processors is the `test.web' source.
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 the 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.


File: fweb.info,  Node: Starting,  Next: AT commands,  Prev: Files,  Up: Top

RUNNING FWEB
************

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

   Commonly-used command-line options can be placed into the
initialization file `.fweb'. *Note Options::.

* Menu:

* Syntax::      Command-line syntax.
* Options::     Command-line options.


File: fweb.info,  Node: Syntax,  Next: Options,  Prev: Starting,  Up: Starting

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

   The command-line syntax is

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

File names are anything that doesn't begin with a `-'.  Options begin
with a `-'.  File names and options can be intermixed, or the options
may appear before the file names.  The first file name encountered is
the web file (source file); the second, if it exists, is the change
file.  [When no change file is specified, FWEB attempts to read from
the null file (`/dev/null' on Unix systems).  This name should be
specified when FWEB is installed, or can be set in the style file.
*Note null_file::.]

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

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


File: fweb.info,  Node: Options,  Prev: Syntax,  Up: Starting

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

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

* Menu:

* Negating options:: How to invert the meaning of an option.
* -1::          Brief debugging mode.
* -2::          Verbose debugging mode.
* -@: -AT.      Display information about control codes.
* -A: -A_.      Turn on ASCII translations.
* -B: -B_.      Turn off audible beeps.
* -b::          Number blocks.
* -c::          Set global language to C.
* -c++: -cpp.   Set global language to C++.
* -D: -D_.      Display information about FWEB's reserved words.
* -d::          Convert unnumbered `do...enddo's to Fortran-77.
* -E: -E_.      Change the delimiter of a file-name extension.
* -e::          Turn on automatic file-name completion.
* -F: -F_.	Compare output files with old versions.
* -f::          Turn off module references for identifiers.
* -h::          Where to get help.
* -I: -I_.      Append a directory to search list for include files.
* -i::          Don't print contents of @I include files.
* -i!::         Don't even read @I include files.
* -L: -L_.      Select global language.
* -l::          Echo the input line.
* -m::          Define a WEB macro.
* -m4::         Understand the m4 built-in commands.
* -m;::         Append pseudo-semicolons to WEB macro definitions.
* -n::          Set global language to Fortran-77.
* -n9::         Set global language to Fortran-90.
* -n;::         For Fortran-77, supply semicolons automatically (default).
* -nb::         In Fortran, number the ifs and dos.
* -np::         Print semicolons in woven Fortran output.
* -n\::         In Fortran-90, free-form syntax continued with '\\'.
* -n&::         In Fortran-90, free-form syntax continued with '&'.
* -n/::         In Fortran, recognize '//' as the start of a short comment.
* -n!::         In Fortran, make '!' denote the start of a short comment.
* -n)::         In Fortran, reverse array indices.
* -o::          Turn off FWEAVE's mechanisms for overloading operators.
* -q::          Don't translate Ratfor.
* -P: -P_.      Select TeX processor.
* -p::          Set style parameter.
* -r::          Set the global language to Ratfor-77.
* -r9::         Set the global language to Ratfor-90.
* -rb::         In Ratfor, number the ifs and dos.
* -rg::         Set |goto| parameters.
* -rk::         Suppress comments about Ratfor statement translation.
* -rK: -rK_.    Write out comments about Ratfor statement translation.
* -r;::         Turn on Ratfor's auto-semi mode.
* -r/::         In Ratfor, recognize '//' as the start of a short comment.
* -r!::         In Ratfor, make '!' denote the start of a short comment.
* -r)::         In Ratfor, reverse, array indices.
* -s::          Print statistics about memory usage.
* -T: -T_.      Flag-setting commands for FTANGLE.
* -t::          Truncate identifiers.
* -U: -U_.      Convert reserved output tokens to lower case.
* -u::          Undefined a predefined or command-line macro.
* -v::          Make all comments verbatim.
* -W: -W_.      Flag-setting commands for FWEAVE.
* -w::          Modify processing of `fwebmac.sty'.
* -X: -X_.      Print selected cross-reference information.
* -x::          Reduce or eliminate cross-reference information.
* -y::          Allocate dynamic memory.
* -Z: -Z_.      Display default values of style-file parameters.
* -z::          Change name of style file.
* -.::          Don't recognize dot constants.
* -\::          Explicitly escape continued strings.
* -(: -lp.      Continue parenthesized strings with backslashes.
* -: -colon.    Set starting automatic statement number.
* ->::          Redirect tangled output.
* -=::          Redirect tangled output.
* -#::          Don't print comments about line numbers and module names
                in tangled output.
* -+: -plus.    Don't interpret compound assignment operators.
* -/::          Recognize '//' as the start of a short comment.
* -!::          Make '!' denoted the start of a short comment.

* Info options:: Information options.


File: fweb.info,  Node: Negating options,  Next: -1,  Prev: Options,  Up: Options

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 is useful if an option such as  `-v' is turned on in the
`.fweb' initialization file and you wish to turn it off for just one
run.


File: fweb.info,  Node: -1,  Next: -2,  Prev: Negating options,  Up: Options

`-1':  Turn on brief debugging mode (FWEAVE).
---------------------------------------------

   This option tells FWEAVE to display irreducible scraps.  (Need
discussion somewhere of scraps.)


File: fweb.info,  Node: -2,  Next: -AT,  Prev: -1,  Up: Options

`-2':  Turn on verbose debugging mode (FWEAVE).
-----------------------------------------------

   This commands tells FWEAVE to display detailed reductions of the
scraps as it does the pretty-printing.  Sometimes FWEAVE fails
spectacularly at printing-printing a section, either because of a syntax
error on the part of the user or because of a bug in FWEAVE's logic.
This option helps one to figure out why.

   This feature can be turned on more locally by means of the `@2'
command.  *Note AT2::.


File: fweb.info,  Node: -AT,  Next: -A_,  Prev: -2,  Up: Options

`-@':  Display the control-code mappings.
-----------------------------------------

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


File: fweb.info,  Node: -A_,  Next: -B_,  Prev: -AT,  Up: Options

`-A_':  Turn on ASCII translations.
-----------------------------------

   This command is used primarily for debugging.  FWEB works internally
with the ASCII character set.  If FWEB is run on a non-ASCII machine,
translations to and from the internal ASCII are done automatically; on
an ASCII machine, these translations are unnecessary and are not
performed unless the `-A' option is used.


File: fweb.info,  Node: -B_,  Next: -b,  Prev: -A_,  Up: Options

`-B':  Turn off audible beeps.
------------------------------

   FWEB sometimes beeps the terminal for 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.)


File: fweb.info,  Node: -b,  Next: -c,  Prev: -B_,  Up: Options

`-b':  Number blocks.
---------------------

   Number do and if blocks in woven Fortran and Ratfor output.


File: fweb.info,  Node: -c,  Next: -cpp,  Prev: -b,  Up: Options

`-c':  Set global language to C.
--------------------------------

   *Note Languages::, *Note C::.


File: fweb.info,  Node: -cpp,  Next: -D_,  Prev: -c,  Up: Options

`-c++':  Set global language to C++.
------------------------------------

   *Note Languages::, *Note Cpp::.


File: fweb.info,  Node: -D_,  Next: -d,  Prev: -cpp,  Up: Options

`-D':  Display reserved words.
------------------------------

   This option displays the list of reserved words for the language
currently in force.  Thus, to see the reserved words for Ratfor-90, say

     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 you say `-Dabc', you will get just the reserved words that begin
with "abc".


File: fweb.info,  Node: -d,  Next: -E_,  Prev: -D_,  Up: Options

`-d':  Convert do...enddo.
--------------------------

   Obsolete.


File: fweb.info,  Node: -E_,  Next: -e,  Prev: -d,  Up: Options

`-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,'.


File: fweb.info,  Node: -e,  Next: -F_,  Prev: -E_,  Up: Options

`-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 you intend.  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., `"web wb"'; the first one that matches is used.

