OS/2 Shareware BBS: 22 gnu

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / fweb140x.zip / fweb.info-2 (.txt) < prev next >

Wrap

GNU Info File | 1996-02-27 | 51KB | 1,044 lines

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: -F_, Next: -f, Prev: -e, Up: Options `-F': Compare output files with old versions. ---------------------------------------------- When the `-F' option is in effect, FTANGLE writes its output to a temporary file (or files) instead of to its ultimate destination--e.g., `test.c' and/or `test.f'. After all output is written, the temporary files are compared with the old version of the files, if they exist. If the files are identical, the appropriate temporary file is deleted; otherwise, the temporary file is renamed, effectively overwriting the old version. This feature avoids updating the time stamp on the file unnecessarily, so `make' files won't recompile the output unless it really has to. (Note that with this option in effect, if one used the Unix utility `touch' to force processing of a group of files, but the WEB sources are never changed, the `make' file will continue to tangle the sources no matter how many times it is run, since FTANGLE will never update the time stamp on the files.) The location of the temporary file as well as details of the renaming procedure are determined by the automatic configuration script during installation of the processors. The script `./configure' first looks for the (non-ANSI) function `tempnam'. If it finds it, it uses it to place the temporary file in the directory that FWEB would normally use for output in the absence of the `-F' option. (That is usually the current directory.) If `tempnam' is not available, the ANSI routine `tmpnam' is used. That places the temporary file in a directory determined by the system. To implement the renaming, the `rename' function is used. This may fail if `tmpnam' placed the temporary file on a different device. If so, an attempt is made to force the rename by using the |system| routine to issue a `mv' command. Terminal output indicates the progress of the renaming. An asterisk following an output file name indicates that `rename' did not succeed, but the `mv' command did. File: fweb.info, Node: -f, Next: -h, Prev: -F_, Up: Options `-f': Turn off module references for identifiers. -------------------------------------------------- By default, FWEAVE gives certain entities such as function names a section-number subscript to indicate where that function was defined. The `-f' command turns off the subscripting operation. The subscript operations are further controlled by the settings of the style-file parameters `mark_defined'. *Note S_mark_defined::. File: fweb.info, Node: -h, Next: -I_, Prev: -f, Up: Options `-h': Get help. ---------------- This just prints a message saying where further help is available. File: fweb.info, Node: -I_, Next: -i, Prev: -h, Up: Options `-I': Append to search list for include files. ----------------------------------------------- The fundamental search list for include files is defined by the environment variable `FWEB_INCLUDES', which is a colon-delimited list such as setenv FWEB_INCLUDES .:/usr/fweb:/other/stuff The `-I' option appends to this list. File: fweb.info, Node: -i, Next: -i!, Prev: -I_, Up: Options `-i': Don't print `@I' include files. -------------------------------------- If a web file is included via `@I' (*note ATI_::.), for example @I formats.hweb then the `-i' option means to read and process the web file, but don't print its contents. This option is often used for large files of macro definitions, formats, or typedef statements that must be included at the beginning of even very short web files; it clutters things up to print such header files all the time. Note that files included via `@i' do not respond to `-i' or `-i!'. File: fweb.info, Node: -i!, Next: -L_, Prev: -i, Up: Options `-i!': Don't read `@I' include files. -------------------------------------- If a web file is included via `@I', for example @I formats.hweb then the `-i!' option means to ignore such files completely. This option is seldom useful; the `-i' option (*note -i::.) is more often used. File: fweb.info, Node: -L_, Next: -l, Prev: -i!, Up: Options `-L': Select global language. ------------------------------ To select a global language from the command line, say `-Ll', where l is one of `{c,c++,n,n9,r,r9,x}'. *Note Languages::. File: fweb.info, Node: -l, Next: -m, Prev: -L_, Up: Options `-l': Echo input line. ----------------------- The option `-l[mmm[:nnn]]' echoes the input line constructed by the input driver between lines mmm and nnn. Missing nnn means echo to the end of file. Missing mmm means echo from the beginning. This option is useful as a debugging tool. It is often used to verify that the input driver is inserting semicolons correctly. For Fortran-77, it is also useful to verify that comments are being processed correctly. File: fweb.info, Node: -m, Next: -m4, Prev: -l, Up: Options `-m': Define WEB macro. ------------------------ The command-line construction -mA(x)=x defines the WEB macro `A' as though the definition @m A(x) x had appeared at the beginning of the web file. File: fweb.info, Node: -m4, Next: -m;, Prev: -m, Up: Options `-m4': Understand `m4' built-in commands. ------------------------------------------ This tells FWEAVE to properly format the reserved words of the `m4' preprocessor. The use of this preprocessor is *not recommended*; use FWEB's built-in preprocessor instead. File: fweb.info, Node: -m;, Next: -n, Prev: -m4, Up: Options `-m;': Append pseudo-semicolons. --------------------------------- When `-m;' is in effect, the construction `@;' is appended automatically to all WEB macro definitions. *This option is not recommended.* Insert the `@;' by hand when necessary, as in @m SET(x,y) x=1; y=2@; File: fweb.info, Node: -n, Next: -n9, Prev: -m;, Up: Options `-n': Set global language to Fortran-77. ----------------------------------------- *Note Languages::, *Note Fortran::. File: fweb.info, Node: -n9, Next: -n;, Prev: -n, Up: Options `-n9': Set global language to Fortran-90. ------------------------------------------ *Note Languages::, *Note Fortran::. File: fweb.info, Node: -n;, Next: -nb, Prev: -n9, Up: Options `-n;': Supply automatic semicolons (Fortran). ---------------------------------------------- This is the default mode of operation in Fortran-77; the input driver automatically appends a semicolon to each logical line of source code. Since it's the default, you don't have to use it unless you wish to negate it. *Note Negating options::. File: fweb.info, Node: -nb, Next: -np, Prev: -n;, Up: Options `-nb': Number `if's and `do's (Fortran). ----------------------------------------- In the woven output, extra comments are added to help one correlate the block structure of the code. File: fweb.info, Node: -np, Next: -n\, Prev: -nb, Up: Options `-np': Print semicolons (Fortran). ----------------------------------- Although the Fortran input driver automatically terminates logical lines with semicolons so that the innards of FWEAVE can process them correctly, the semicolons are by default not printed. To make them be printed, use the `-np' option. File: fweb.info, Node: -n\, Next: -n&, Prev: -np, Up: Options `-n\': Free-form syntax continued by backslash. ------------------------------------------------ In Fortran-90, this turns on free-form syntax and sets the continuation character to be the backslash. For example, -n9[-n\] @ @a program main; x = \ y; end; In the tangled output the backslash is converted into Fortran-90's standard continuation character, the ampersand. File: fweb.info, Node: -n&, Next: -n/, Prev: -n\, Up: Options `-n&': Free-form syntax continued by ampersand. ------------------------------------------------ In Fortran-90, this turns on free-form syntax and sets the continuation character to be the backslash. For example, -n9[-n\] @ @a program main; x = & y; end; File: fweb.info, Node: -n/, Next: -n!, Prev: -n&, Up: Options `-n/': Recognize short comments (Fortran). ------------------------------------------- The standard FWEB notation for a short comment is `// ...'. However, in Fortran the `//' denotes concatenation by default. To make it denote a short comment, use the `-n/' option. For concatenation, use `\/'. File: fweb.info, Node: -n!, Next: -n), Prev: -n/, Up: Options `-n!': Make `!' denote short comment (Fortran). ------------------------------------------------ File: fweb.info, Node: -n), Next: -o, Prev: -n!, Up: Options `-n)': Reverse array indices (Fortran) --------------------------------------- This flag permits Fortran programmers to use C-style array indices. Conversions such as the following are made: a(k)(i) => a(i,k) a(k)(i,j) => a(i,j,k) a(k)(j)(i) => a(i,j,k) This feature permits convenient definitions of macros to deal with multi-dimensional vectors. File: fweb.info, Node: -o, Next: -q, Prev: -n), Up: Options `-o': Don't overload operators. -------------------------------- (To be finished.) File: fweb.info, Node: -q, Next: -P_, Prev: -o, Up: Options `-q': Don't translate Ratfor. ------------------------------ *(Obsolete.)* File: fweb.info, Node: -P_, Next: -p, Prev: -q, Up: Options `-P': Select TeX processor. ---------------------------- Say `-PT' or `-PL' to inform FWEAVE that its output will be processed by TeX or LaTeX, respectively. If you always use LaTeX, it's easiest to put `+PL' into the `.fweb' initialization file. File: fweb.info, Node: -p, Next: -r, Prev: -P_, Up: Options `-p': Buffer up a style-file entry. ------------------------------------ This option can be used in the `.fweb' initialization file to record style-file entries that are common to all runs. This command buffers up the entries. They are effectively placed at the beginning of the local style file, which is read after the command line is processed. *Note Style::. File: fweb.info, Node: -r, Next: -r9, Prev: -p, Up: Options `-r': Set global language to Ratfor-77. ---------------------------------------- *Note Languages::, *Note Ratfor::. File: fweb.info, Node: -r9, Next: -rg, Prev: -r, Up: Options `-r9': Set global language to Ratfor-90. ----------------------------------------- *Note Languages::, *Note Ratfor::. File: fweb.info, Node: -rg, Next: -rk, Prev: -r9, Up: Options `-rg': Set `goto' parameters. ------------------------------ This obscure parameter is used for Ratfor (and really should be a style-file parameter). Please see the manual. File: fweb.info, Node: -rk, Next: -rK_, Prev: -rg, Up: Options `-k': Suppress comments about Ratfor translation. --------------------------------------------------- By default, the Ratfor translator writes comments about what command it is translating. The `-k' option suppresses those comments. Arguments to this command allows one to suppress comments about only particular commands; please see the reference guide. File: fweb.info, Node: -rK_, Next: -r;, Prev: -rk, Up: Options `-K': Write comments about Ratfor translation. ------------------------------------------------ This is the negative of `-k'; it forces comments about particular Ratfor commands. File: fweb.info, Node: -r;, Next: -rb, Prev: -rK_, Up: Options `-r;': Turn on auto-semi mode (Ratfor). ---------------------------------------- Please don't use this command. Insert semicolons by hand in your Ratfor code. File: fweb.info, Node: -rb, Next: -r/, Prev: -r;, Up: Options `-rb': Number `if's and `do's (Ratfor). ---------------------------------------- In the woven output, extra comments are added to help one correlate the block structure of the code. File: fweb.info, Node: -r/, Next: -r!, Prev: -rb, Up: Options `-r/': Recognize short comments (Ratfor). ------------------------------------------ The standard FWEB notation for a short comment is `// ...'. However, in Ratfor the `//' denotes concatenation by default. To make it denote a short comment, use the `-r/' option. For concatenation, use `\/'. File: fweb.info, Node: -r!, Next: -r), Prev: -r/, Up: Options `-r!': Make `!' denote short comment (Ratfor). ----------------------------------------------- File: fweb.info, Node: -r), Next: -s, Prev: -r!, Up: Options `-r)': Reverse array indices (Ratfor) -------------------------------------- File: fweb.info, Node: -s, Next: -T_, Prev: -r), Up: Options `-s': Print statistics. ------------------------ `-s' prints statistics about memory usage at the end of the run. `-sm' prints statistics about memory usage at the end of the run, just as does `-s'; it also prints information about dynamic memory allocations as they occur. `-smnnn' displays allocations of nnn bytes or more; if nnn is missing, 10000 is assumed. File: fweb.info, Node: -T_, Next: -t, Prev: -s, Up: Options `-T': Flag-setting commands for FTANGLE. ----------------------------------------- This is a family of commands that set flags appropriate only for FTANGLE. * Menu: * -TD:: Permit processing of deferred macro definitions. * -Tv:: Don't print header info at top of output. * -T%:: Don't retain trailing comments. File: fweb.info, Node: -TD, Next: -Tv, Prev: -T_, Up: -T_ `-TD': Permit processing of deferred macro definitions ....................................................... Deferred macro definitions are `@m' (or, equivalently, `@#define') commands that appear in the code part rather than the usual definition part. These definitions are evaluated during the output (phase 2), and can cause confusion when used with the preprocessor commands, which are evaluated during the input (phase 1). Because of this confusion, deferred macro definitions are prohibited by default. To permit them, use the `-TD' option. File: fweb.info, Node: -Tv, Next: -T%, Prev: -TD, Up: -T_ `-Tv': Don't print header info .............................. By default, FTANGLE attempts to be helpful and prints some information about the command line, input and change files, etc. at the beginning of the output file. This information can be deleted by means of the `-Tv' flag. (This is done automatically when the `-F' flag is in effect, since the header information includes a time stamp that would defeat a successful file comparison.) File: fweb.info, Node: -T%, Prev: -Tv, Up: -T_ `-T%': Don't retain trailing comments ...................................... Unless the `-v' option is used, comments are generally deleted by FTANGLE as it writes the output file. However, in the TeX language such deletions can change the behavior of the output (by introducing extra spaces). Therefore, for TeX comments that do not begin a line are always retained unless the `-T%' command is used. This command has no effect for languages other than TeX. File: fweb.info, Node: -t, Next: -U_, Prev: -T_, Up: Options `-t': Truncate identifiers. ---------------------------- The truncation option enables one to use a wider character set for identifiers than the language compiler will accept. The standard example is vanilla-flavored Fortran, which doesn't allow the underscore. If one says ``-tn6{_}'', underscores will be removed from all identifiers, then the result will be truncated to length 6. If the truncation procedure results in non-unique identifiers, these are listed. File: fweb.info, Node: -U_, Next: -u, Prev: -t, Up: Options `-U': Convert reserved output tokens to lower case. ---------------------------------------------------- Particularly during RATFOR expansion, certain output tokens such as `DO' are produced in upper case. The `-U' option forces such tokens to be produced in lower case. File: fweb.info, Node: -u, Next: -v, Prev: -U_, Up: Options `-u': Undefine macro. ---------------------- `-uA' undefines the WEB macro previously defined on the command line (or in `.fweb') via `-m'. *CAUTION*: This command can also undefine built-in functions such as `$IF'. Don't do that, since built-ins can use other built-ins behind the scenes; undefining one can cause very strange behavior. File: fweb.info, Node: -v, Next: -W_, Prev: -u, Up: Options `-v': Make all comments verbatim. ---------------------------------- By default, comments are not passed to the tangled output. With `-v', all comments are included verbatim in the tangled output. File: fweb.info, Node: -W_, Next: -w, Prev: -v, Up: Options `-W': Flag-setting commands for FWEAVE. ---------------------------------------- This is a family of commands that set flags appropriate only for FWEAVE. Commands such as `-W[' and `-Wf' can be combined as `-W[f'. * Menu: * -W[:: Turn on processing of bracketed array indices. * -Wdflmvw:: Don't print various things in woven output. File: fweb.info, Node: -W[, Next: -Wdflmvw, Prev: -W_, Up: -W_ `-W[': Process bracketed array indices ....................................... File: fweb.info, Node: -Wdflmvw, Prev: -W[, Up: -W_ `-Wdflmvw': Don't print various things in woven output ....................................................... The printing of selected definition-part commands can be suppressed as follows: -Wd --- outer definitions -Wf --- format statements -Wl --- limbo text definitions -Wm --- WEB macro definitions -Wv --- operator overloads -Ww --- identifier overloads When these commands are used, associated cross-referencing is suppressed as well. File: fweb.info, Node: -w, Next: -x, Prev: -W_, Up: Options `-w': Change name of macro package ----------------------------------- The command `-w' means "Don't print `\input fwebmac.sty' as the first line of the `.tex' output file." The command `-wfname' means "Print `\input fname' as the first line." File: fweb.info, Node: -x, Next: -X_, Prev: -w, Up: Options `-x': Reduce cross-reference information. ------------------------------------------ Cross-reference information (for FWEAVE) includes the table of contents ('c'), the index ('i'), and the module list ('m'). The command `-x' eliminates all of that information. The command `-xletters' eliminates the piece of information corresponding to each letter in the list. For example, `-xim' eliminates the index and the module list. File: fweb.info, Node: -X_, Next: -y, Prev: -x, Up: Options `-X': Print selected cross-reference information. -------------------------------------------------- This command is the opposite of `-x'. *Note -x::. File: fweb.info, Node: -y, Next: -Z_, Prev: -X_, Up: Options `-y': Allocate dynamic memory. ------------------------------- This command changes the default size for a dynamically allocated memory buffer. The buffers are indicated by a one- or two-character abbreviation such as "op". The command `-yop200' allocates 200 units for the "op" buffer. To query the default allocations, just say `-y'. For a more detailed discussion of memory allocation and a menu of the various dynamic arrays, see *Note Memory allocation::. File: fweb.info, Node: -Z_, Next: -z, Prev: -y, Up: Options `-Z': Display default style-file parameters. --------------------------------------------- The command `-Zabc' prints to the screen the default contents of the style-file parameters beginning with "abc". Just `-Z' prints everything. File: fweb.info, Node: -z, Next: -., Prev: -Z_, Up: Options `-z': Change name of style file. --------------------------------- The command `-znew.sty' changes the default style-file name `fweb.sty' to `new.sty'. The command `-z' means "Don't read any style file." Normally the style file is read from the same directory in which the WEB file resides. To force `fweb.sty' to be read from the current directory, say `-z.'. File: fweb.info, Node: -., Next: -\, Prev: -z, Up: Options `-.': Don't recognize dot constants. ------------------------------------- If this command is used, the processors will not understand that constructions such as `.LT.' are operators in Fortran or Ratfor. This command is useful if one is trying to modernize the source code to deal with symbols such as `<' instead of `.LT.'. File: fweb.info, Node: -\, Next: -lp, Prev: -., Up: Options `-\': Explicitly escape continued strings. ------------------------------------------- (To be finished.) File: fweb.info, Node: -lp, Next: -colon, Prev: -\, Up: Options `-(': Continue parenthesized strings with backslashes. ------------------------------------------------------- File: fweb.info, Node: -colon, Next: ->, Prev: -lp, Up: Options `-:': Set starting automatic statement number. ----------------------------------------------- Useful for Fortran and Ratfor. Symbolic statement labels that are defined with the `#:0' macro command are incremented starting with the default of 90000. To change this to 789, say `-:789'. File: fweb.info, Node: ->, Next: -=, Prev: -colon, Up: Options `->': Redirect output. ----------------------- This changes the name of the output file. If no name is given, output is redirected to the terminal. File: fweb.info, Node: -=, Next: -#, Prev: ->, Up: Options `-=': Redirect output. ----------------------- Equivalent to `->'. File: fweb.info, Node: -#, Next: -plus, Prev: -=, Up: Options `-#': Turn off comments about line and module numbers. ------------------------------------------------------- By default, tangled output includes comments about the line and module numbers corresponding to the current piece of code. To eliminate this clutter, say `-#'. In some cases, bugs in tangled output, particularly Fortran, can be eliminated by using `-#'. (But please report the bug anyway; *Note Support::.) File: fweb.info, Node: -plus, Next: -/, Prev: -#, Up: Options `-+': Don't interpret compound assignment operators. ----------------------------------------------------- Both Ratfor and Fortran attempt to translate the commands `++', `+=', `--', `-=', `*=', and `/=' into code that behaves as its C counterpart. To turn this feature off, use `-+'. File: fweb.info, Node: -/, Next: -!, Prev: -plus, Up: Options `-/': Recognize short comments (Fortran & Ratfor). --------------------------------------------------- If this command is not used, the `//' construction will be interpreted as concatenation. One way of invoking this option is with the global language command, such as `@n/'. Another is to put the command into the initialization file `.fweb'. File: fweb.info, Node: -!, Next: Info options, Prev: -/, Up: Options `-!': Make `!' denote short comment (Fortran & Ratfor). -------------------------------------------------------- File: fweb.info, Node: AT commands, Next: Comments, Prev: Starting, Up: Top WEB COMMANDS ************ All WEB commands begin with the character `@'. It is recommended that these begin in column 1 if possible. This is required in some cases [e.g., the `@x', `@y', and `@z' in change files (*note Change files::.), or column-oriented Fortran processing]. Some of these control codes may be used anywhere; others begin a new part. For a quick summary of the control-code mappings and to see which codes begin new parts, use the `-@' option. *Note -AT::. * Menu: Debugging commands: * @0: AT0. Turn off debugging. * @1: AT1. Display irreducible scraps. * @2: AT2. Display detailed scrap reductions. Literal control characters: * @@: ATAT. Insert an '@'. * @|: AT|. Vertical bar/optional line break. Beginning of section: * @ : ATspace. Begin minor section. * @*: AT*. Begin major section. Beginning of code part: * @<: AT<. Begin module name. * @>: AT>. End module name. * @A: ATA_. Begin code part. * @a: ATa. Begin code part and mark next identifier. Control codes b-z: * @b: ATb. Insert breakpoint command. * @c: ATc. Set language to C. * @c++: ATcpp. Set language to C++. * @D: ATD_. Define outer macro. * @d: ATd. Define outer macro and mark it. * @f: ATf. Format identifier or module name. * @I: ATI_. Include a WEB file, but don't print it. * @i: ATi. Include a WEB file. * @L: ATL_. Set language. * @l: ATl. Specify limbo text. * @M: ATM_. Define a WEB macro. * @m: ATm. Define a WEB macro and mark it. * @N: ATN_. Turn on language-independent mode. * @n: ATn. Set language to Fortran-77. * @n9:ATn9. Set language to Fortran-90. * @O: ATO_. Open new output file (global scope). * @o: ATo. Open new output file (local scope). * @r: ATr. Set language to Ratfor-77. * @r9: ATr9. Set language to Ratfor-90. * @u: ATu. Undefine an outer macro. * @v: ATv. Overload an operator. * @W: ATW_. Overload an identifier. * @x: ATx. Terminate ignorable material. * @y: ATy. End first part of change. * @z: ATz. Begin ignorable material. Conversion to ASCII: * @': ATquote. Convert single character to ASCII. * @": AT". Convert string to ASCII. Forward referencing: * @[: AT[. Mark next identifier as defined in this section. Comments: * @/*: AT/*. Begin a long verbatim comment. * @//: AT//. Begin a short verbatim comment. * @%: AT%. Ignore everything to next newline. * @?: AT?. Begin a compiler directive. * @(: ATlp. Begin a meta-comment. * @): AT). End a meta-comment. Special brace: * @{: ATlb. Suppress default insertion of breakpoint command. Index entries: * @_: AT_. Force an index entry to be underlined (marked as defined). * @-: AT-. Delete index entry for following identifier. * @+: ATplus. Force index entry for following identifier. * @^: AT^. Make index entry in Roman type. * @.: ATdot. Make index entry in typewriter type. * @9: AT9. Make index entry in format controlled by `\9'. Control text: * @t: ATt. Put control text into TeX \hbox. * @=: AT=. Pass control text verbatim to the output. Spacing: * @comma: ATcomma. Insert a thin space. * @/: AT/. Insert a line break. * @|: AT|_. Insert optional line break in an expression. * @#: AT#. Force line break with blank line. * @~: AT~. Cancel a line break (tie adjacent lines together). * @&: AT&. Join left and right items. Pseudo (invisible) operators: * @e: ATe. Invisible expression. * @;: AT;. Invisible semicolon. * @colon: ATcolon. Invisible colon. Miscellaneous: * @!: AT!. Inhibit expansion for next macro. File: fweb.info, Node: AT0, Next: AT1, Prev: AT commands, Up: AT commands Debugging commands ================== Several commands provide localized versions of the `-1' and `-2' options related to debugging of pretty-printing. `@0': Turn off debugging ------------------------- This cancels the effect of a previous `@1' or `@2'. *Note AT1::, *Note AT2::. The `@0' command should appear in a different section from the `@1' or `@2' commands. File: fweb.info, Node: AT1, Next: AT2, Prev: AT0, Up: AT commands `@1': Display irreducible scraps --------------------------------- File: fweb.info, Node: AT2, Next: ATAT, Prev: AT1, Up: AT commands `@2': Display detailed reductions of the scraps ------------------------------------------------ File: fweb.info, Node: ATAT, Next: AT|, Prev: AT2, Up: AT commands Literal control characters ========================== `@@': The character `@'. ------------------------- `@@' inserts the single character `@'. Don't forget to double the `@' even inside strings. For example, puts("'@@' is represented by `@@@@'"); File: fweb.info, Node: AT|, Next: ATspace, Prev: ATAT, Up: AT commands `@|': Literal vertical bar, or optional line break. ---------------------------------------------------- In TeX mode, `@|' inserts a vertical bar. This is useful inside LaTeX verbatim environments. (A simple bar would signal a shift into code mode, which is probably not what you want.) In code mode, `@|' inserts an optional line break in an expression. File: fweb.info, Node: ATspace, Next: AT*, Prev: AT|, Up: AT commands Beginning of section ==================== `@ ': Begin minor section. --------------------------- `@ ' begins a new minor (unstarred) section. For example, @ This is an example of a minor section. (No entry is made in the table of contents.) @a main() {} File: fweb.info, Node: AT*, Next: AT<, Prev: ATspace, Up: AT commands `@*', `@*n': Begin major section. ---------------------------------- `@*' begins a new major (starred) section (of level 0). The command must be followed by the name of the section (entry in the table of contents), followed by a period. If `@*' is followed by a digit n, it begins a new major section of level n. For example, @* MAIN PROGRAM. This begins a major section (of level 0). @a main() {} @*1 Input routines. Now follow some subroutines. @a get_input() {} File: fweb.info, Node: AT<, Next: AT>, Prev: AT*, Up: AT commands Beginning of code part ====================== The code part is begun by the appearance of either `@a' or `@< Module name @>='. `@<': Begin module name. ------------------------- `@<' begins a module name, which has the form `@< TeX text @>'. Module names inside WEB macro definitions begin with `@#', not `@<'. File: fweb.info, Node: AT>, Next: ATA_, Prev: AT<, Up: AT commands `@>': End module name. ----------------------- `@>' ends a module name, of the form `@< TeX text @>'. File: fweb.info, Node: ATA_, Next: ATa, Prev: AT>, Up: AT commands `@A': Begin code part of unnamed section. ------------------------------------------ `@A' begins the code part of an unnamed section. For example, @ In an unnamed section, the code part begins with `@a'. @a main() {} File: fweb.info, Node: ATa, Next: ATb, Prev: ATA_, Up: AT commands `@a': Begin code part of unnamed section, and mark. ---------------------------------------------------- `@a' begins the code part of an unnamed section (just as does `@A'), and in addition marks the next unreserved identifier it finds as defined in this section. Precisely, `@a' == `@A@[' File: fweb.info, Node: ATb, Next: ATc, Prev: ATa, Up: AT commands Control codes b-z ================= `@b': Insert a breakpoint command. ----------------------------------- (To be finished. Useful only for very intimate debugging of WEB codes.) File: fweb.info, Node: ATc, Next: ATcpp, Prev: ATb, Up: AT commands `@c': Set language to C. ------------------------- *Note Languages::, *Note C::. File: fweb.info, Node: ATcpp, Next: ATD_, Prev: ATc, Up: AT commands `@c++': Set language to C++. ----------------------------- *Note Languages::, *Note Cpp::. File: fweb.info, Node: ATD_, Next: ATd, Prev: ATcpp, Up: AT commands `@D': Define outer macro. -------------------------- *This command begins the definition part.* `@D' defines an outer macro. For more discussion, *Note Outer macros::. For example, @D A 1 File: fweb.info, Node: ATd, Next: ATf, Prev: ATD_, Up: AT commands `@d': Define outer macro, and mark. ------------------------------------ *This command begins the definition part.* `@d' defines an outer macro (just as `@D' does), and also marks the next identifiers as defined here. It is equivalent to `@d' == `@D@[' File: fweb.info, Node: ATf, Next: ATi, Prev: ATd, Up: AT commands `@f': Format identifier or module name. ---------------------------------------- *This command begins the definition part.* The construction @f identifier old_identifier makes FWEAVE treat identifier like old_identifier. For example, @f mytype int says to treat the variable `mytype' just as `int' is treated (e.g., as a reserved word in C or C++). The old_identifier may be one of the following special names, which insert extra spaces according to the positions of the underscores and behave as the part of speech indicated by the base names. These are useful for dealing with macro constructions. $_BINOP_ $_COMMA_ $_EXPR $_EXPR_ $EXPR_ $UNOP_ When the current language is TeX, the format command can be used to change a category code according to the format @f `TeXchar new_cat_code File: fweb.info, Node: ATi, Next: ATI_, Prev: ATf, Up: AT commands `@i': Include file (unconditional). ------------------------------------ If one says @i test.hweb the file `test.hweb' is inserted at the present point of the web file. By default, the current directory is searched. Files can be included from other directories by means of the `FWEB_INCLUDES' environment variable and/or the `-I' command-line option. *Note Environment variables::, *Note -I_::. File: fweb.info, Node: ATI_, Next: ATL_, Prev: ATi, Up: AT commands `@I': Include file (conditional). ---------------------------------- This commands behaves like `@i' if the command-line option `-i' is not used. If it is used, then the contents of the included file is not printed in the woven output. *Note -i::, *Note -i!::. File: fweb.info, Node: ATL_, Next: ATl, Prev: ATI_, Up: AT commands `@L': Set language. -------------------- `@Ll' sets the language to l, where l is one of `{c,c++,n,n9,r,r9,x,v}'. *Note Languages::. File: fweb.info, Node: ATl, Next: ATM_, Prev: ATL_, Up: AT commands `@l': Specify limbo text. -------------------------- (This command begins the definition part.) Limbo text is material that FWEAVE should output before the start of the first section. For example, @l "\\def\\A{abc}" Note that `\\' stands for a backslash. In general, characters must be escaped just as in C (so that one can include things like newlines in the definitions). Limbo text may also be typed directly into the limbo section; in that case, no escapes are necessary since one is typing ordinary TeX text. Sometime, however, the `@l' command is useful for pedagogical purposes, as the limbo material can then be defined near the point where the logical discussion is made. File: fweb.info, Node: ATM_, Next: ATm, Prev: ATl, Up: AT commands `@M': Define WEB macro. ------------------------ *This command begins the definition part.* For a detailed discussion of WEB macros, see *Note Macros::. File: fweb.info, Node: ATm, Next: ATN_, Prev: ATM_, Up: AT commands `@m': Define WEB macro, and mark. ---------------------------------- *This command begins the definition part.* For a detailed discussion of WEB macros, see *Note Macros::. File: fweb.info, Node: ATN_, Next: ATn, Prev: ATm, Up: AT commands `@N': Turn on N mode --------------------- *This command must appear before the code part.* The N mode invokes language-independent behavior within the scope of a particular language. The scoping rules are the same as for language changes; i.e., using `@N' within a given section produces language-independent behavior for that section and for any modules first referenced in that section. Fundamentally, "language-independent" behavior essentially means a literal transcription of the input to the output. For example, it inhibits blank compression by FTANGLE and tells FWEAVE to turn off "pretty-printing" (instead, the output is printed in typewriter type within a `\begin{verbatim}...\end{verbatim}' environment. There are some subtleties with this mode (not to mention the likelihood of bugs): 1. WEB macros and built-in functions will normally be expanded even in the N mode. To inhibit expansion of a particular identifier, place `@!' before the identifier. For example, @ @m A 1 @N @a @!A = A; expands to `A = 1'. 2. Blank lines are significant. The N mode is ended by the appearance of the `@*' or `@ ' denoting the start of the next section. If that were preceded by one or more blank lines, those would show up in both the tangled and woven output. They might or might not be significant in the tangled output, but they almost certainly will look ugly in the woven output. To avoid this, use the command `@%%', which deletes the remainder of the current line and all immediately following empty lines. For example, @ @N @a x;@%% @ Next section. 3. If the N mode is invoked from a compiler-like language such as Fortran, cross-referencing of variables is done as usual. However, if the language is VERBATIM (which turns on the N mode automatically), no cross-referencing is done. (Identifiers are still recognized according to FWEB's rules. Those rules as currently implemented may be essentially meaningless for some languages; in the future, provision may be made for generalizing these rules by the user.) To force an identifier to be placed into the index, precede it by `@+'. File: fweb.info, Node: ATn, Next: ATn9, Prev: ATN_, Up: AT commands `@n': Set language to Fortran-77. ---------------------------------- *Note Languages::. File: fweb.info, Node: ATn9, Next: ATO_, Prev: ATn, Up: AT commands `@n9': Set language to Fortran-90. ----------------------------------- *Note Languages::. File: fweb.info, Node: ATO_, Next: ATo, Prev: ATn9, Up: AT commands `@O': Open output file (global scope). --------------------------------------- A statement of the form @O newfile.c changes the name of the FTANGLE's output file. This change remains in effect for the duration of the file, or until another `@O' is encountered. (If that occurs, the previously open file is closed.) This command is expanded during output, so it must appear in the code part. File: fweb.info, Node: ATo, Next: ATr, Prev: ATO_, Up: AT commands `@o': Open output file (local scope). -------------------------------------- This behaves like `@O', except the new file name is in effect only for the current section. File: fweb.info, Node: ATr, Next: ATr9, Prev: ATo, Up: AT commands `@r': Set language to Ratfor-77. --------------------------------- *Note Languages::. File: fweb.info, Node: ATr9, Next: ATu, Prev: ATr, Up: AT commands `@r9': Set language to Ratfor-90. ---------------------------------- *Note Languages::. File: fweb.info, Node: ATu, Next: ATv, Prev: ATr9, Up: AT commands `@u': Undefine outer macro. ---------------------------- *This command begins the definition part.* `@u' is the inverse of `@d'. For example, in C it expands to `#undef'. File: fweb.info, Node: ATv, Next: ATW_, Prev: ATu, Up: AT commands `@v': Overload operator. ------------------------- *This command begins the definition part.* For a detailed discussion of overloading operators, see *Note Overloading::. File: fweb.info, Node: ATW_, Next: ATx, Prev: ATv, Up: AT commands `@W': Overload identifier. --------------------------- *This command begins the definition part.* For a detailed discussion of overloading identifiers, see *Note Overloading::. File: fweb.info, Node: ATx, Next: ATy, Prev: ATW_, Up: AT commands `@x': Terminate ignorable material, or begin material to be changed -------------------------------------------------------------------- Please see the discussion of the `@z' command. *Note ATz::. File: fweb.info, Node: ATy, Next: ATz, Prev: ATx, Up: AT commands `@y': Begin change material ---------------------------- The `@y' command is permitted only in change files. *Note Change files::. File: fweb.info, Node: ATz, Next: ATquote, Prev: ATy, Up: AT commands `@z': Begin ignorable material, or terminate change ---------------------------------------------------- FWEB files may begin with the construction @z . . @x where the `@z' and `@x' must begin in column 1. Material between the `@z' and `@x' is "pure commentary" and is ignored by both processors. `@z' is also used in change files to end a change. *Note Change files::. File: fweb.info, Node: ATquote, Next: AT", Prev: ATz, Up: AT commands Conversion to ASCII =================== Several commands are useful for generating machine-independent code. For example, FWEB works internally with the ASCII character set, so uses these commands heavily to convert from the possibly non-ASCII native character set of the machine on which FWEB is running. `@'': Convert character to ASCII. ---------------------------------- The construction `@'c'' converts `c' to its ASCII value. In C and C++, it is converted to octal; for example, `@'A'' is output as `0101'. In Fortran and Ratfor, it is converted to decimal; the previous example would be output as `65'. If the native character set of your machine is ASCII, the conversion will not be done unless the `-A' command-line option is used. *Note -A_::. File: fweb.info, Node: AT", Next: AT[, Prev: ATquote, Up: AT commands `@"': Convert string to ASCII. ------------------------------- The construction `@"abc"' converts the enclosed string to its ASCII representation. For example, in C and C++ `@"abc"' will be output as `"\141\142\143"'. In Fortran and Ratfor, no such simple mechanism exists in the language, so a function call is issued. For example, the previous example would be output as `ASCIIstr('abc')'. The user is responsible for defining the function `ASCIIstr'. The name of this function can be changed by the style-file entry `ASCII_fcn'. *Note ASCII_fcn::. If the native character set of your machine is ASCII, the conversion will not be done unless the `-A' command-line option is used. *Note -A_::. File: fweb.info, Node: AT[, Next: AT/*, Prev: AT", Up: AT commands Forward referencing =================== `@[': Mark as defined. ----------------------- This command marks the next (non-reserved) identifier that appears after the `@[' as being defined in the current section. It is usually issued automatically; for example, `@a' is equivalent to `@A@['. File: fweb.info, Node: AT/*, Next: AT//, Prev: AT[, Up: AT commands Comments ======== `@/*': Begin long verbatim comment. ------------------------------------ The following comment is copied to the tangled output. If you desire all comments to be so copied, use `-v'. *Note -v::. File: fweb.info, Node: AT//, Next: AT%, Prev: AT/*, Up: AT commands `@//': Begin short verbatim comment. ------------------------------------- See the discussion of `@/*', above. File: fweb.info, Node: AT%, Next: AT?, Prev: AT//, Up: AT commands `@%': Ignorable comment. ------------------------- If any line in a web source code contains the command `@%', all remaining material on that line (to and including the newline character) is ignored by the input driver and never processed at all. A stronger form of this command is `@%%'. This deletes the current line as well any empty lines that immediately follow. This command is particularly useful when the N mode is in effect. *Note ATN_::. File: fweb.info, Node: AT?, Next: ATlp, Prev: AT%, Up: AT commands `@?': Begin compiler directive. -------------------------------- The remainder of the line is processed as a compiler directive. Optional material may be inserted automatically at the beginning of the tangled output line by means of the style-file option `cdir_start'. *Note Miscellaneous params::. File: fweb.info, Node: ATlp, Next: AT), Prev: AT?, Up: AT commands `@(': Begin meta-comment. -------------------------- Material between `@(' and `@)' is treated in the N mode. For example, @( Comment 1 Comment 2 @) Style-file parameters allow optional material to be insert at the beginning and end of the meta-comment, and at the beginning of each line of output. For more information, see the style-file parameters beginning with `meta' (*note Miscellaneous params::.). File: fweb.info, Node: AT), Next: ATlb, Prev: ATlp, Up: AT commands `@)': End meta-comment. ------------------------ See the discussion of `@(', *Note ATlp::. File: fweb.info, Node: ATlb, Next: AT_, Prev: AT), Up: AT commands Special brace ============= `@{': Suppress insertion of breakpoint command. ------------------------------------------------ This is for detailed debugging of FWEB codes. It inserts a left brace and suppresses the insertion of a breakpoint command. *Note ATb::. File: fweb.info, Node: AT_, Next: AT-, Prev: ATlb, Up: AT commands Index entries ============= `@_': Force index entry to be underlined. ------------------------------------------ This command applies to the next identifier that appears after the `@_'. The index entry for that identifier will be underlined. This command is usually issued automatically. For example, the index entries for the variables `i' and `j' in the C statement `int i,j;' will be underlined. File: fweb.info, Node: AT-, Next: ATplus, Prev: AT_, Up: AT commands `@-': Delete index entry. -------------------------- This command applies to the next identifier that appears after the `@-'; it prevents the index entry associated with that identifier from being underlined. This might be useful when the N mode is in effect. File: fweb.info, Node: ATplus, Next: AT^, Prev: AT-, Up: AT commands `@+': Force index entry. ------------------------- This command applies to the next identifier that appears after the `@+'; it forces an index entry for that identifier. It is particularly useful when the language is VERBATIM, since cross-referencing is turned off in that case. File: fweb.info, Node: AT^, Next: ATdot, Prev: ATplus, Up: AT commands `@^': Make index entry (Roman type). ------------------------------------- To insert one's own index entry in Roman type, say `@^My entry@>'. File: fweb.info, Node: ATdot, Next: AT9, Prev: AT^, Up: AT commands `@.': Make index entry (typewriter type). ------------------------------------------ To insert one's own index entry in typewriter type, say `@^My entry@>'. File: fweb.info, Node: AT9, Next: ATt, Prev: ATdot, Up: AT commands `@9': Make index entry (\9 format). ------------------------------------ The construction `@9text@>' is used to create an index entry in a format defined by the user. It is associated with the macro `\9', which would be called during TeX's processing of the index as `\9{text}'. The user must define `\9' according to the format \def\9#1{...} File: fweb.info, Node: ATt, Next: AT=, Prev: AT9, Up: AT commands Control text ============ `@t': Put control text into a TeX \hbox. ----------------------------------------- Control text is material terminated by `@>'; it must be all on one line and must not contain any `@'s. When FWEAVE sees the command `@tcontroltext@>', it packages the control text into an `\hbox' and ships it to the output. This command is ignored by FTANGLE. File: fweb.info, Node: AT=, Next: ATcomma, Prev: ATt, Up: AT commands `@=': Pass control text verbatim to the output. ------------------------------------------------ For FTANGLE, the command `@=controltext@>' sends the control text to the output exactly as input. (`Control text' is defined in the discussion of the `@t' command, *Note ATt::.) FWEAVE highlights the control text by drawing a box around it. File: fweb.info, Node: ATcomma, Next: AT/, Prev: AT=, Up: AT commands Spacing ======= The spacing commands are used to refine FWEAVE's pretty-printed output. Generally it's not necessary to bother with these until you're putting the final touches on a code. `@,': Insert a thin space. --------------------------- Extra spacings are sometimes necessary when working with unusual macro constructions. (Need an example here.) File: fweb.info, Node: AT/, Next: AT|_, Prev: ATcomma, Up: AT commands `@/': Force a line break. -------------------------- For example, int@/ i,@/ j,@/ k; File: fweb.info, Node: AT|_, Next: AT#, Prev: AT/, Up: AT commands `@|': Literal vertical bar, or optional line break. ---------------------------------------------------- In TeX mode, `@|' inserts a vertical bar. Here's a LaTeX example: \begin{verbatim} The constructions @|x@| and |x| are very different. \end{verbatim} You might wish to try this out to see what FWEAVE produces. In code mode, `@|' inserts an optional line break in an expression. File: fweb.info, Node: AT#, Next: AT~, Prev: AT|_, Up: AT commands `@#': Blank line. ------------------ `@#' forces a line break with some extra vertical white space. Note that blank lines in the source are significant, so this command should seldom be necessary. if `@#' is immediately followed by a letter, it is assumed that a preprocessor command is beginning. *Note Preprocessing::.