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) 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 `@', 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@; @ 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, `@' and `@' 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 @@; @@; @@; @@; 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 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 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.