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-3 (.txt) < prev next >

Wrap

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