Go to the first, previous, next, last section, table of contents.
All @FWEB{} commands begin with the character `@'. It is recommended that these begin in column 1 if possible. This is required in some cases [e.g., the `@x', `@y', and `@z' in change files (see section Change files), or column-oriented FORTRAN-77 processing].
Some of these control codes may be used anywhere; others begin a new part of the current section. (For a discussion of sections and parts, see section The structure of a web.) For a quick summary of the control-code mappings and to see which codes begin new parts, say `ftangle -@'. See section `-@': Display the control-code mappings.
Several commands provide localized versions of the `-1' and `-2' options related to debugging of pretty-printing.
This cancels the effect of a previous `@1' or `@2' (see section `@1': Display irreducible scraps and section `@2': Display detailed reductions of the scraps). The `@0' command should appear in a different section from the `@1' or `@2' commands.
This is a local version of the command-line option `-1' (see section `-1': Turn on brief debugging mode (@FWEAVE{})); refer to that discussion for more information.
This is a local version of the command-line option `-2' (see section `-2': Turn on verbose debugging mode (@FWEAVE{})); refer to that discussion for more information.
Several commands insert specific characters.
`@@' inserts the single character `@'.
Don't forget to double the `@' even inside strings. For example, the @FWEB{} source line
puts("'@@' is represented by `@@@@'");
will be tangled to
puts("'@' is represented by `@@'");
In the TeX (documentation) part of a section, `@|' inserts a vertical bar. This is useful inside LaTeX verbatim environments. (A simple bar would signal a shift into code mode, which is probably not what one wants.) For an example, see section `@|': Literal vertical bar, or optional line break.
In a code part, `@|' inserts an optional line break in an expression--e.g.,
`f(a,b,@|c+d,...)'.
This helps TeX to break the line at an appropriate place. If the line does not need to be broken, the command does nothing. [Compare `@|' with `@\' (see section `@\': Force a line break, then indent) and `@/' (see section `@/': Force a line break, preserving indentation.), which always break the line.]
Sections are begun by either `@*' or @ASP{}.
@ASP{} begins a new minor (unstarred or unnamed) section that is not entered into the Table of Contents. For example,
@ This is an example of a minor (unnamed) section. (No entry is made in the Table of Contents.) @a main() {}
`@*' begins a new major (starred) section (of level 0). The command must be followed by the name of the section (entry in the Table of Contents), followed by a period. (If a period appears in the name itself, it must be protected by braces.)
The section name is also used as a running head on the output pages. To deal with the possibility that the full name may be too long, the section name may be preceded by an optional argument enclosed in brackets. If it is present, the optional argument is used as the running head. (If a period appears as part of the optional argument, it must be protected by braces.)
If `@*' is followed by a digit n, it begins a new major (sub)section of level n. This is also entered into the Table of Contents. Thus, the complete syntax to begin a major section is
@*n [Short name]Full name.
For example,
@* MAIN PROGRAM. This begins a major section (of level 0). @a main() {} @*1 [Input routines\dots]A very long section name that essentially means "input routines." Now follow some subroutines. @a get_input() {}
For LaTeX, the highest permissible major level is 2 (a subsubsection).
Section names can contain reasonably arbitrary TeX text, including font-changing commands and other macros. However, it is necessary to understand that fragile commands (in the sense of LaTeX) may not work because the section name is used in various contexts (e.g., as a page header). If a macro in a section name doesn't work properly, try preceding it with `\protect'.
@FWEAVE{} converts `@*' commands to section numbers. For a discussion of section numbering, see section Section numbering schemes.
The code part is begun by the appearance of either `@a' or `@< Module name @>='.
`@<' begins a module name, which has the form `@< TeX text @>'. (Module names inside @FWEB{} macro definitions begin with `@#', not `@<'.)
`@>' ends a module name, of the form `@< TeX text @>'.
Technically, `@>' is not a command; rather, it is a delimiter that terminates `@<'. An unmatched `@>' is simply ignored (after a warning message is issued).
`@A' begins the code part of an unnamed section. For example,
@ In an unnamed section, the code part begins with `@a' or `@A'. @A main() {}
For more discussion of the distinction between `@A' and `@a', see section `@a': Begin code part of unnamed section, and mark.
`@a' begins the code part of an unnamed section (just as does `@A'), and in addition marks the next unreserved identifier it finds as defined in this section. Precisely,
`@a' == `@A@['
Originally, @FWEB{} did not contain the `@A' command, so when the functionality of automatically marking the next unreserved identifier (see section Forward referencing) was added, it was natural to add it to `@a'. A reasonable style of coding is to always use `@a' if you don't know any better; if you sometime run into trouble, you can then change selected `@a's to `@A's. For example, it is appropriate to use `@a' if one codes one function per section. E.g.,
@c @ @a int subrtn() {}
Here the `@a' marks `subrtn' as defined in this section; if that identifier is used elsewhere, it will be subscripted with the section number. (To turn this feature off, use `-f'; see section `-f': Turn off module references for identifiers (@FWEAVE{}).) However, if a section contains an arbitrary code fragment, the code part should probably begin with `@A'. E.g.,
@c @ @A x = y;
If one had used `@a' here, the x
would have been marked as
defined here, which is not what one wants.
This is for detailed debugging of @FWEB{} codes. It inserts a left brace and suppresses the insertion of a breakpoint command. See the discussion of `@b' in section `@b': Insert a breakpoint command.
(Discussion to be finished. Useful only for very intimate debugging of @FWEB{} codes. In these days of safe sex, such intimacy may not be desirable.)
See also section Control codes b--z.
The command `@c' is a shorthand for `@Lc'. For a discussion of language commands in limbo, see section `@L': Set language.
See section LANGUAGES and section Special considerations for C.
The command `@c++' is a shorthand for `@Lc++'. For a discussion of language commands in limbo, see section `@L': Set language.
See section LANGUAGES and section Special considerations for C++.
This command begins the definition part.
`@D' defines an outer macro. For more discussion, see section Outer macros. For example, in C
@D A 1
will be tangled to the beginning of the output file as `#define A 1'.
This command begins the definition part.
`@d' defines an outer macro (just as `@D' does), and also marks the next identifier as defined in the present section. It is equivalent to
`@d' == `@D@['
(see section Forward referencing).
The distinction between `@d' and `@D' is analagous to the distinction between `@a' and `@A'. See section `@a': Begin code part of unnamed section, and mark.
For formatting purposes, treat the next identifier as an ordinary expression.
This command is useful in pretty-printing certain kinds of macro constructions. Further discussion is given in @xref{Macros and formatting}.
This command begins the definition part.
The construction
@f identifier old_identifier
makes @FWEAVE{} treat identifier like old_identifier. For example,
@f mytype int
says to treat the variable mytype
just as int
is treated
(e.g., as a reserved word in C or C++).
Traditionally, C programmers needed to use this command to format
identifiers that were defined in #include
files. This annoying
redundancy has now been eliminated by means of the `-H' command,
which tells @FWEAVE{} to scan #include
files automatically.
See section `-H': Scan C/C++ include files (@FWEAVE{}).
The old_identifier may be one of the following special names, which insert extra spaces according to the positions of the underscores and behave as the part of speech indicated by the base names:
$_BINOP_ $_COMMA_ $_EXPR $_EXPR_ $EXPR_ $UNOP_
These are useful for dealing with certain macro constructions. For example,
@f PLUS $_BINOP_ @m PLUS + @m ADD(x, y) ((x) PLUS (y))
Without the format command, the `ADD' macro will pretty-print without spaces before and after the `PLUS'.
When the current language is TeX, the format command can be used to change a category code according to the format
@f `TeXchar new_cat_code
Difficulties may ensue if one try to change the category code of `@' in this way; a fully operational WEB for TeX is quite difficult and has been neither accomplished nor attempted.
@i test.hweb
the file `test.hweb' is inserted at the present point of the web file. By
default, the current directory is searched. Files can be included from
other directories by means of the FWEB_INCLUDES
environment variable
and/or the `-I' command-line option.
See section Environment variables and section `-I': Append to search list for include files.
In principle, the included file may contain any fragment of source text. However, it is best to make it a complete section (begun by `@*' or @ASP{}) if at all possible.
Unfortunately, the `@i' command cannot be commented out or conditionally included by use of an @FWEB{} preprocessor command. That is because `@i' is processed very early in the parsing process. (Consider: `@i' could include TeX text, but the preprocessor is only active in the definition and code parts.)
Include commands may be nested to a depth set by the option `-yid'. See section `-yid': Maximum depth of file inclusion.
In the woven output, if a section comes from an include file, the name of the include file is printed in square brackets as the first text of the TeX part. To inhibit printing of that name, say
\def\WIF#1{}
in the limbo section. To change the way that name is formatted, redefine the macro `\WIFfmt', whose single argument is the name of the include file. (It is not called when there is no current include file.) The default definition is
\def\WIFfmt#1{[{\tt#1}]}
This command behaves like `@i' if the command-line option `-i' is not used. If it is used, then the contents of the included file is not printed in the woven output. See section `-i': Don't print `@I' include files (@FWEAVE{}) and section @samp{-i!}: Don't read @samp{@I} include files.
The construction `@K Keyword @>' accesses the value of a global RCS-like keyword. (For more discussion of such keywords, see section `@z': Begin ignorable material, or terminate change.) The command is treated differently by @FTANGLE{} and @FWEAVE{} depending on its location in the source file.
@FWEAVE{} will expand the construction in the limbo section and TeX parts only. The value is not surrounded by quotes. For example,
@z $Id: test $ @x @c \def\ID{Id = \.{"@K Id @>"}} @ \ID. This is a @K Id @>.
will expand into
@c @ \ID. This is a test.
and when LaTeX is run the macro \ID
will expand to `Id =
\.{"Test"}'. The quotes are not necessary in the macro definition;
they are included only to emphasize that in this (limbo) context the
`@K' construction can effectively be put inside a string. This is
possible because the routine that copies the limbo section simply copies
characters; it does not tokenize anything.
@FWEAVE{} does not expand `@K' constructions in the definition or code parts; it merely gives them a symbolic representation.
@FTANGLE{}, on the other hand, expands `@K' constructions in the definition or code parts (during input). The values are surrounded by quotes. (As usual, @FTANGLE{} ignores material in the limbo section and TeX parts.)
For @FTANGLE{}, the built-in function `$KEYWORD'
(see section $KEYWORD
: Value of global RCS-like keyword) behaves essentially as does `@K', except that
it is expanded during output, not input. @FWEAVE{} does not expand
`$KEYWORD'.
The command `@k' behaves as does `@K' except that it accesses local keywords, not global ones. See section `@k': Access local RCS-like keyword.
The construction `@k keyword' behaves as `@K' does (see section `@K': Extract global RCS-like keyword), except it accesses local keywords (defined at the top of include files).
`@Ll' sets the language to l, where l is one of `{c,c++,n,n9,r,r9,v,x}'. See section LANGUAGES.
There are shorthand forms of this command for some languages; see `@c' (section `@c': Set language to C), `@c++' (section `@c++': Set language to C++), `@n' (section `@n': Set language to FORTRAN--77), `@n9' (section `@n9': Set language to FORTRAN--90), `@r' (section `@r': Set language to RATFOR--77), and `@r9' (section `@r9': Set language to RATFOR--90).
Generally, the global language should be set in the limbo section by means of `@L', `@c', etc. rather on the command line by options such as `-L' or `-c'.
This command begins the definition part.
Limbo text is material that @FWEAVE{} should output before the start of the first section. For example,
@l "\\def\\A{abc}"
Note that `\\' stands for a backslash. In general, characters must be escaped just as in C [so that one can include things like `\n' (newline) in the definitions].
Limbo text may also be typed directly into the limbo section; in that case, no escapes are necessary since one is typing ordinary TeX text. Sometimes, however, the `@l' command is useful for pedagogical purposes, as the limbo material can then be defined at the point where the logical discussion is made.
This command begins the definition part.
For a detailed discussion of @FWEB{} macros, see section MACROS and PREPROCESSING.
This command begins the definition part.
`@m' defines an @FWEB{} macro, and also marks the next identifier as defined here. It is equivalent to
`@m' == `@M@['
(see section Forward referencing).
For a detailed discussion of @FWEB{} macros, see section MACROS and PREPROCESSING.
The distinction between `@m' and `@M' is analagous to the distinction between `@a' and `@A'. See section `@a': Begin code part of unnamed section, and mark.
This command must appear before the code part. Generally, this means immediately before `@a'. Do not use this command in limbo; use `@Lv' instead.
The N mode invokes language-independent behavior within the scope of a particular language. The scoping rules are the same as for language changes; i.e., using `@N' within a given section produces language-independent behavior for that section and for any modules first referenced in that section.
Fundamentally, language-independent behavior essentially means a literal transcription of the input to the output. For example, it inhibits blank compression by @FTANGLE{} and tells @FWEAVE{} to turn off "pretty-printing" (instead, the output is printed in typewriter type within a `\begin{verbatim}...\end{verbatim}' environment).
There are some subtleties with this mode (not to mention the likelihood of bugs):
@ @m A 1 @N @a @!A = A;expands to `A = 1'.
@ @N @a x;@%% @ Next section.
@ Consider the module @<Test@>. (Not yet within scope of \.{@N}.) @N @a x; @<Test@>@; y;What happens is that the N mode is not restored after the code-part use of `@<Test@>'. This is a bug. There are very tricky design issues to be dealt with here.
FORTRAN-77 is @FWEB{}'s default language, so this command is usually not
strictly necessary. However, it is good practice to include it, so a
user looking at the web
file can tell immediately what language
it is supposed to process.
For more discussion of languages, see section `@L': Set language and section LANGUAGES.
For more discussion of languages, see section `@L': Set language and section LANGUAGES.
For hints about @FWEB{} programming in FORTRAN, see section Special considerations for @sc{Fortran}.
@O new_output_file_name
changes the name of @FTANGLE{}'s output file. This change remains in effect for the duration of the file, or until another `@O' is encountered. (If that occurs, the previously open file is closed.)
This command is expanded during output, so it must appear in the code part.
For an example of using the `@O' command to produce both C header files (`.h') and source files (`.c'), see the discussion in section Outer macros.
To change the name of the output file locally (for just the present section), see section `@o': Open output file (local scope).
This behaves like `@O', except that the new file name is in effect only for the current section. A subsequent `@o' issued in a different section but for the same file name accretes material to the file.
An annoying problem arises in C programming when `@o's are used to create
multiple source files that are subsequently compiled under the control
of a Makefile
. Remember that by default line-number information
is written into the C files. This means that a change in the web
file code for one source file can affect all of the others, because the
line numbering in the web
file changes. Therefore, a trivial change to
the code for just one source file can cause all of the others to be
recompiled.
As long as one desires debugging information relative to the original
web
file, there is really no solution to this problem; one needs
the proper line information in each file in order to work with the
debugger, so if line numbers change the sources must be recompiled. One
can, of course, turn off the line numbering with the command-line option
`-#' (see section `-#': Turn off comments about line and section numbers (@FTANGLE{})), but then debugger statements will refer to the
tangled C code, which is undesirable. A better partial solution is to
use `@q' (see section `@q': Turn off module and line info locally) to turn off the line numbering for output
code that is currently stable. In the following example, the code for
each file is put into a module, then the modules are output in the
unnamed section; it is assumed that the programmer is currently
making changes to the code for `file2.c':
@ @a @q0 @o file1.c @<File 1@>@; @q1 @o file2.c @<File 2@>@; @q0 @o file3.c @<File 3@>@;
For very large projects, another solution is to maintain multiple
web
source files. To avoid losing the substantial benefits of
the automatic index, refer to the discussion in section Using the idxmerge
utility to merge indexes to
learn how to create a master index that contains information about
several web
files.
The command-line option `-#' (see section `-#': Turn off comments about line and section numbers (@FTANGLE{})) turns off comments about module and line numbers globally, for the entire code. However, in some cases one wants to turn that off in just a small block of code. One important example arises in FORTRAN. Consider
@ @a x = @<Some action@> @ @<Some action@>= y + z
This example will tangle to something like
x = C* 1: * *line 20 "test.web" y + z C* :1 * *line 5 "test.web"
Unfortunately, the information comments have created invalid code that will not compile.
The `@q' command solves this problem by turning off or on the information comments locally. `@q0' turns them off; `@q1' turns them on. Thus, if one rewrites the above example as
@ @a @q0 x = @<Some action@> @q1
it will tangle to
x = y + z
as one desires.
For another use of the `@q' command, see section `@o': Open output file (local scope).
word (@FWEAVE{})
For formatting purposes, treat the next identifier as an integer-like reserved word.
This command is useful in pretty-printing certain kinds of macro constructions. Further discussion is given in @xref{Macros and formatting}.
See section `@L': Set language and section LANGUAGES.
See section `@L': Set language and section LANGUAGES.
This command begins the definition part.
`@u' is the inverse of `@d'. For example, in C the command `@u A' tangles to `#undef A'.
This command begins the definition part.
`@v' is used to change the woven appearance of an operator. If one defines a new operator, for example by a statement such as
interface operator(.BETA.)
in FORTRAN-90, one should also use an `@v' in the definition part--for example,
@v .BETA. "\\beta" +
For a detailed discussion of overloading (the output appearance of) operators, see section Overloading operators and identifiers.
This command begins the definition part.
For a detailed discussion of overloading (the output appearance of) identifiers, see section Overloading operators and identifiers.
In a change file, this command begins material to be changes; see section Change files.
In web
source files, this command has a different use;
see the discussion of the `@z' command (see section `@z': Begin ignorable material, or terminate change).
The `@y' command is permitted only in change files. See section Change files.
@FWEB{} files may begin with the construction
@z . . @x
where the `@z' occupies the very first two characters of the file, and where the `@z' and `@x' must begin in column 1. Material between the `@z' and `@x' is pure commentary and is ignored by both processors, with one exception.
The exception is that an RCS-like line (RCS stands for "revision-control system") with syntax
$Keyword: Text of Keyword $
(at least one blank after the colon, and at least one before the last
dollar sign; UNIX users, see `man ident') is parsed, and the
text of the Keyword
is made
available to the control codes `@K' (see section `@K': Extract global RCS-like keyword) and `@k'
(see section `@k': Access local RCS-like keyword) as well as to @FTANGLE{}'s built-in function $KEYWORD
(see section $KEYWORD
: Value of global RCS-like keyword.
A distinction is made between keywords that are found in the ignorable commentary at the beginning of the master web file, which are called global keywords, and ones that are found at the beginning of files included via `@i', which are called local keywords.
The commands that access RCS-like keywords function as follows:
- `$KEYWORD(Keyword)' accesses a global keyword. It is a built-in function that is expanded by @FTANGLE{} (during output) into the quoted character string
"Text of Keyword"
.- `@K' and `@k' are expanded during input. `@K' accesses a global keyword, whereas `@k' accesses a local keyword.
- In the limbo section or a TeX part, @FWEAVE{} will expand @samp{@K Keyword @>} into
Text of Keyword
(without the surrounding quotes), and similarly for `@k'. (The intention is that the expanded text can be used as bodies of TeX macros.) @FWEAVE{} will also print the values of global keywords at the end of its output, whether or not they are referenced by `@K'.- Elsewhere @FWEAVE{} will just print the keyword name itself, surrounded by double angle brackets. If the keyword was local (`@k'), the brackets will carry the subscript 0.
- @FTANGLE{} treats the global command `@K Keyword @>' essentially like it does `$Keyword', except that the construction is expanded on input rather than output.
- @FTANGLE{} expands the command `@k keyword @>' on input, generating a quoted string containing the value of the local keyword.
The command `@z' is also used in change files to end a change. See section Change files.
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.
The construction `@'c'' converts `c' to its ASCII value. In C and C++, it is converted to octal; for example, `@'A'' is output as `0101'. In FORTRAN and RATFOR, it is converted to decimal; the previous example would be output as `65'.
If the native character set of one's machine is ASCII, the conversion will not be done unless the `-A' command-line option is used. See section `-A': Turn on ASCII translations.
The construction `@"abc"' converts the enclosed string to its ASCII representation. For example, in C and C++ `@"abc"' will be output as `"\141\142\143"'.
In FORTRAN and RATFOR, no such simple mechanism exists in the
language, so a function call is issued. For example, the previous
example would be output as `ASCIIstr('abc')'. The user is
responsible for defining the function `ASCIIstr'. The name of this
function can be changed by the style-file entry `ASCII_fcn'.
See section ASCII_Fcn
.
If the native character set of one's machine is ASCII, the conversion will not be done unless the `-A' command-line option is used. See section `-A': Turn on ASCII translations.
This command marks the next (non-reserved) identifier that appears after the `@[' as being defined in the current section. It is usually issued automatically; for example, `@a' is equivalent to `@A@[', `@d' is equivalent to `@D@[', and `@m' is equivalent to `@M@['.
If the appropriate style-file parameter mark_defined.???
is 1,
this command causes any appearance of the identifier to be subscripted
with a section number. For more information, see section Customizing cross-reference subscripts.
The utility of this command can be seen from the characteristic construction
@ This is section 5. @a @% Issues an implicit @[, which marks |test| as defined in section 5. subroutine test ... end @ This is section 6. @a program main call test // This will print as $|test|_5$. end
The `@[' command should be distinguished from `@_' (see section Index entries). The latter causes the index entry for the identifier to be underlined; the former possibly causes the identifier to be subscripted by a section number. One may wish to turn off the subscripts because they become too cluttered; however, the underlined index entries remain useful and unobtrusive.
@FWEB{} supports a variety of commenting styles borrowed from C, C++, and TeX. For more discussion, see section COMMENTING STYLES.
The following comment is copied to the tangled output. (By default, comments are not copied.) If you desire all comments to be so copied, use `-v'. See section `-v': Make all comments verbatim (@FTANGLE{}).
See the discussion of `@/*' in section `@//': Begin short verbatim comment.
If any line in a web source code contains the command `@%', all remaining material on that line (to and including the newline character) is ignored by the input driver and never processed at all.
A stronger form of this command is `@%%'. This deletes the current line as well any empty lines that immediately follow. This command is particularly useful when the N mode is in effect. See section `@N': Turn on N mode.
Line-numbering problems can arise when these commands are used. For a discussion, see section `-T#': Don't insert `#line' command after `@%'.
The remainder of the line is processed as a compiler directive. Optional
material may be inserted automatically at the beginning of the tangled
output line by means of the style-file option cdir_start
.
See section Miscellaneous style-file parameters.
Material between `@(' and `@)' is treated in the N mode. For example,
@( Comment 1 Comment 2 @)
Style-file parameters allow optional material to be insert at the beginning and end of the meta-comment, and at the beginning of each line of output. For more information, see the style-file parameters beginning with `meta' (see section Miscellaneous style-file parameters).
See the discussion of `@(', section `@(': Begin meta-comment.
The command `@{' is useful in C/C++ programming to beautify some of the pretty-printing. It translates into a left brace, but also suppresses the automatic insertion of newlines into the subsequent function body or block. This is desirable for very short functions, such as simple constructors in C++. For example,
class C { private: int i; public: C(int i0) @{i = i0;} }
Here the function will be typeset as
C(int i0) { i = i0; }
rather than the default
C(int i0) { i = i0; }
Although most information for the Index is gathered automatically, in some situations it must be done by hand.
This command applies to the next identifier that appears after the `@_'. The index entry for that identifier will be underlined. (By convention, this means `defined' or `declared'.)
This command is usually issued automatically. For example, the index entries for the variables `i' and `j' in the C statement `int i, j;' will be underlined, since @FWEAVE{} understands enough of the syntax to know that variables are being defined. Macro definitions (begun by `@D' or `@M') will also be underlined automatically.
This command applies to the next identifier that appears after the `@-'; it prevents an index entry associated with that identifier from being made. This might be useful when the N mode is in effect.
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.
To insert one's own index entry in Roman type, say `@^My entry@>'.
To insert one's own index entry in typewriter type, say `@.My entry'@>.
The construction `@9Text@>' is used to create an index entry in a
format defined by the user. It is associated with the macro \9
, which
will be called during TeX's processing of the Index as
\9{Text}
. The user must define \9
according to the format
\def\9#1{...}
where argument `#1' is the text between `@9' and `@>'. For example, to print that text in a sans serif font, say
\def\9#1{{\sf #1}}
(Note the extra level of braces to prevent the font command from propagating.)
Control text is material terminated by `@>'; it must be all on one line and must not contain any `@'s.
When @FWEAVE{} sees the command `@tcontrol text@>', it packages
the control text into an \hbox
and ships it to the output. This
command is ignored by @FTANGLE{}.
For @FTANGLE{}, the command `@=control text@>' sends the control text to the output exactly as input. @FWEAVE{} highlights the control text by drawing a box around it.
The spacing commands are used to refine @FWEAVE{}'s pretty-printed output. Generally it's not necessary to bother with these until one is putting the final touches on a code.
Extra spacings are sometimes necessary when working with unusual macro
constructions. `@,' inserts a thin space, analogous to TeX's
\,
.
An example where explicit spacing would be necessary is as follows:
@c @ @m OP + @m A(x,y) x @, OP @, y @a z = A(a, b);
Without the `@,''s, the body of the A
macro will weave as
the unappealing `xOPy'. This occurs because although OP
is
defined to be a binary operator, @FWEAVE{} thinks of it as just a mere
expression, and one of its fundamental production rules is to
concatenate expressions with no intervening expressions.
This demonstrates that situations arise in which one needs to override @FWEAVE{}'s default processing. But for the above example, there is actually a better solution. Instead of using the `@,''s, include the format command `@f OP $_BINOP_'. See section `@f': Format identifier or module name.
This command is used to override @FWEAVE{}'s natural inclinations. For example, if one wants each piece of a declaration to appear on a separate line, one can say
int@/ i,@/ j,@/ k;
This command preserves the natural indentation that would have happened if @FWEAVE{} or LaTeX had broken a long line spontaneously. Thus, the declared variables are indented in the above example. To remove that indent, use `@\' instead. See section `@\': Force a line break, then indent.
Try to use the line-break commands sparingly--i.e., let @FWEAVE{} do the work. Often, if lines run together in an unexpected or unreadable way, it's because @FWEAVE{} wasn't able to parse the relevant block of code, perhaps because it didn't understand that some variable in an include file has a special meaning. In such cases, trying to fix things with `@/' is the wrong solution. Either use `@f' (see section `@f': Format identifier or module name) or `-H' (see section `-H': Scan C/C++ include files (@FWEAVE{})).
Distinguish the `@/' command from `@|' (see section `@|': Literal vertical bar, or optional line break), which inserts an optional breakpoint into an expression.
The `@\' command behaves like `@/' (see section `@/': Force a line break, preserving indentation.), except that it backspaces one notch after the line break. This usually has the effect of undoing the natural indentation that would have been inserted had a long line been spontaneously broken. One common case where the `@\' command might be used would be to put the return type of a C function on a separate line:
int @\ main() {}
It would be nice to have @FWEAVE{} do that automatically. Unfortunately, the syntax of a function isn't recognized until the opening braces are sensed; by that time, the declaration part of the statement has already been processed. This is one example of the fact that the @FWEB{} processors are much less intelligent and sophisticated than language compilers. A clever (and simple) idea for getting around this kind of problem is lacking at this point.
In the TeX (documentation) part of a section, `@|' inserts a vertical bar. Here's a LaTeX example:
\begin{verbatim} The constructions @|x@| and |x| are very different. \end{verbatim}
You might wish to try this out to see what @FWEAVE{} produces.
In a code part, `@|' inserts an optional line break in an expression.
`@#' forces a line break with some extra vertical white space. However, note that blank lines in the source are significant, so this command should seldom if ever be necessary.
if `@#' is immediately followed by a letter (e.g., `@#if'), it is assumed that a preprocessor command is beginning. See section Preprocessing.
`@~' is analogous to TeX's `~' (tie); it prevents a line break, which @FWEAVE{} usually inserts after each complete statement it recognizes. For example,
printf("Working..."); @~ fflush(stdout); x = y; @~ break;
During @FWEAVE{}'s output, `@&' joins the items to either side with no spaces or line breaks inbetween.
This command must be distinguished from the preprocessor construction
##
(paste tokens together). In a macro definition, `a##bc'
creates the single identifier `abc'. If one said `a@&bc',
two identifiers would be output with no spaces separating them. In
simple cases, the results may look identical, but consider how things
would differ if abc
were itself an @FWEB{} macro that should
itself be expanded.
Pseudo- or invisible operators are ignored by @FTANGLE{} and not printed by @FWEAVE{}; however, they retain grammatical significance that helps out @FWEAVE{} in its attempts to understand the syntax.
`@e' is an invisible expression (`pseudo-expression') (see section Pseudo-operators). It is sometimes useful in situations where @FWEAVE{}'s pretty-printing has broken down because it didn't properly understand the language syntax. If, for example, @FWEAVE{} failed to properly parse the C statement
p = (int (*))q;
one might get things to work properly by saying
p = (int (*@e))q;
In this particular case, one is patching up a deficiency (all right, a bug) in @FWEAVE{}'s "production rules." (This particular bug may no longer exist.) However, there are other situations in which the use of `@e' might be necessary. Consider, for example, the C macro definition
#define A(x) = x
Here the replacement text of the macro is `= x', which by itself is not a valid construction in C. When the `-1' or `-2' options are used, @FWEAVE{} will report an "irreducible scrap sequence" in this situation (although it may typeset it correctly anyway). To eliminate the warning message, say instead
#define A(x) @e = x
Now the fragment `@e = x' is interpreted as a valid expression.
`@;' is an invisible semicolon. These are often used in C programming to terminate a module name that expands to a compound statement. Carefully compare the uses of `@;' and `;' in the following example:
@c @a if(flag) @<Compound statement@>@; else @<Simple statement@>; @ This compound statement ends with a brace, but is used as an expression above. @<Com...@>= { x; y; } @ This fragment does not end with a semicolon, so one must be supplied above. @<Sim...@>= z
Here is a case for which the pseudo-semicolon is not necessary. Consider
@c @ The code fragment |x = y| ...
If the `-1' is turned on, one might think that @FWEAVE{} would report an "irreducible scrap sequence" because `x = y' is an expression but not a complete statement. (Turning on `-2' demonstrates this.) However, it is not necessary to say `|x = y@;|' because the warning message is not issued if the parsing reduces to just one unresolved scrap.
On the other hand, `|goto done|' does not reduce to just one unresolved scrap, so say `|goto done@;|' in cases such as this. See section Pseudo-operators.
In some situations, pseudo-semicolons are inserted automatically. An important case is free-format FORTRAN-90. There the language syntax says that newlines terminate statements (except when there's a trailing ampersand). However, newlines are thrown away before tokenized text is seen by @FWEAVE{}'s parser (and in any event would just be interpreted as white space). Therefore, by default newlines that terminate statements are replaced by pseudo-semicolons, so the parsing proceeds correctly.
In the FORTRAN-90 case, one could also insert pseudo-semicolons or actual semicolons by hand, and some users prefer that. The possibilities are controlled by the options `-n@;' (see section `-n@;': Supply automatic pseudo-semicolons [FORTRAN]) and `-n;' (see section `-n;': Supply automatic semicolons [FORTRAN]).
`@:' is an invisible colon (see section Pseudo-operators). It can be helpful in formatting certain C constructions correctly. For example, if one has a named module defined as
@<Cases@>= case 1: case 2: case 3@: @;
then one can use it as a case construction followed by the usual colon, as in
switch(c) { @<Cases@>: stuff; break; }
@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 `@!'.
Go to the first, previous, next, last section, table of contents.