Go to the first, previous, next, last section, table of contents.


@FWEB{} COMMANDS

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.

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' (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.

`@1': Display irreducible scraps

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.

`@2': Display detailed reductions of the scraps

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.

Literal control characters

Several commands insert specific characters.

`@@': The character `@'

`@@' 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 `@@'");

`@|': Literal vertical bar, or optional line break

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.]

Beginning of section

Sections are begun by either `@*' or @ASP{}.

`@ ': Begin minor section

@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()
{}

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

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 @FWEB{} macro definitions begin with `@#', not `@<'.)

`@>': End module name

`@>' 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': 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' 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': 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.

Control codes b--z

`@B': 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. See the discussion of `@b' in section `@b': Insert a breakpoint command.

`@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.

`@c': Set language to 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.

`@c++': Set language to 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++.

`@D': Define outer macro

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

`@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 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.

`@E': Treat next identifier as ordinary expression (@FWEAVE{})

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}.

`@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++).

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': 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. 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}]}

`@I': Include file (conditional)

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.

`@K': Extract global RCS-like keyword

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.

`@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).

`@L': Set language

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

`@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 `\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.

`@M': Define @FWEB{} macro

This command begins the definition part.

For a detailed discussion of @FWEB{} macros, see section MACROS and PREPROCESSING.

`@m': Define @FWEB{} macro, and mark

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.

`@N': Turn on N mode

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):

  1. @FWEB{} 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 @ASP{} 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 `@+'.
  4. A module name must be within the scope of an `@N' the first time the name is seen, if it is ever to be within such scope. Thus, the following does not work properly:
    @ 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.

`@n': Set language to FORTRAN--77

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.

`@n9': Set language to FORTRAN--90

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': Open output file (global scope)

A statement of the form

@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).

`@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.

`@q': Turn off module and line info locally

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).

`@R': Treat next identifier as integer-like reserved

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}.

`@r': Set language to RATFOR--77

See section `@L': Set language and section LANGUAGES.

`@r9': Set language to RATFOR--90

See section `@L': Set language and section LANGUAGES.

`@u': Undefine outer macro

This command begins the definition part.

`@u' is the inverse of `@d'. For example, in C the command `@u A' tangles to `#undef A'.

`@v': Overload operator

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.

`@W': Overload identifier

This command begins the definition part.

For a detailed discussion of overloading (the output appearance of) identifiers, see section Overloading operators and identifiers.

`@x': Terminate ignorable material, or begin material to be changed

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).

`@y': Begin change material

The `@y' command is permitted only in change files. See section Change files.

`@z': Begin ignorable material, or terminate change

@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:

The command `@z' is also used in change files to end a change. See section Change files.

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 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.

`@"': 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'. 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.

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

Comments

@FWEB{} supports a variety of commenting styles borrowed from C, C++, and TeX. For more discussion, see section COMMENTING STYLES.

`@/*': Begin long verbatim comment

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{}).

`@//': Begin short verbatim comment

See the discussion of `@/*' in section `@//': Begin short verbatim comment.

`@%': 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. 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 `@%'.

`@?': 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. See section Miscellaneous style-file parameters.

`@(': 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' (see section Miscellaneous style-file parameters).

`@)': End meta-comment

See the discussion of `@(', section `@(': Begin meta-comment.

Special left brace

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

Index entries

Although most information for the Index is gathered automatically, in some situations it must be done by hand.

`@_': 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. (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.

`@-': Delete index entry

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.

`@+': 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.

`@^': Make index entry (Roman type)

To insert one's own index entry in Roman type, say `@^My entry@>'.

`@.': Make index entry (typewriter type)

To insert one's own index entry in typewriter type, say `@.My entry'@>.

`@9': Make index entry (user-defined 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 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

Control text is material terminated by `@>'; it must be all on one line and must not contain any `@'s.

`@t': Put control text into a TeX \hbox (@FWEAVE{})

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{}.

`@=': Pass control text verbatim to the output

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.

Spacing

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.

`@,': Insert a thin space

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.

`@/': Force a line break, preserving indentation.

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.

`@\': Force a line break, then indent

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.

`@|': Literal vertical bar, or optional line break

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.

`@#': Blank line

`@#' 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.

`@~': Cancel line break

`@~' 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;

`@&': 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 an @FWEB{} macro that should itself be expanded.

Pseudo (invisible) operators

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': Pseudo-expression

`@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.

`@;': Pseudo-semicolon

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

`@:': Pseudo-colon

`@:' 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;
        }

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 `@!'.


Go to the first, previous, next, last section, table of contents.