Node: AT|, Next: , Previous: ATAT, Up: AT commands



@|: 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 AT|_.

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 ATbs) and @/ (see AT/), which always break the line.]

Node: AT*, Next: , Previous: ATspace, Up: AT commands



@*, @*n: Begin major section

@* begins a new major (starred) section (of level 0). The command must be followed by the name of the section (entry in the Table of Contents), followed by a period. (If 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 Numbering.

Node: AT<, Next: , Previous: AT*, Up: AT commands



Beginning of code part

The code part is begun by the appearance of either @a or @< Module name @>=.

@<: Begin module name

@< begins a module name, which has the form @< TeX text @>. (Module names inside FWEB macro definitions begin with @#, not @<.)

Node: AT>, Next: , Previous: AT<, Up: AT commands



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

Node: AT[, Next: , Previous: ATdquote, Up: AT commands



Forward referencing

@[: Mark as defined

This command marks the next (non-reserved) identifier that appears after the @[ as being defined in the current section. It is usually issued automatically; for example, @a is equivalent to @A@[, @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 Subscript params.

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

Node: AT%, Next: , Previous: AT//, Up: AT commands



@%: Ignorable comment

If any line in a web source code contains the command @%, all remaining material on that line (to and including the newline character) is ignored by the input driver and never processed at all.

A stronger form of this command is @%%. This deletes the current line as well any empty lines that immediately follow. This command is particularly useful when the N mode is in effect. See ATN_.

Line-numbering problems can arise when these commands are used. For a discussion, see -T#.

Node: AT?, Next: , Previous: AT%, Up: AT commands



@?: Begin compiler directive

The remainder of the line is processed as a compiler directive. Optional material may be inserted automatically at the beginning of the tangled output line by means of the style-file option cdir_start. See Miscellaneous params.

Node: AT), Next: , Previous: ATlp, Up: AT commands



@): End meta-comment

See the discussion of @(, ATlp.

Node: AT-, Next: , Previous: AT_, Up: AT commands



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

Node: AT^, Next: , Previous: ATplus, Up: AT commands



@^: Make index entry (Roman type)

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

Node: AT=, Next: , Previous: ATt, Up: AT commands



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

Node: AT/, Next: , Previous: ATcomma, Up: AT commands



@/: 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 ATbs.

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 ATf) or -H (see -H_).

Distinguish the @/ command from @| (see AT|), which inserts an optional breakpoint into an expression.

Node: AT#, Next: , Previous: AT|_, Up: AT commands



@#: 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 Preprocessing.

Node: AT~, Next: , Previous: AT#, Up: AT commands



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

Node: AT&, Next: , Previous: 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 an FWEB macro that should itself be expanded.

Node: AT;, Next: , Previous: 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. 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 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 -nAT;) and -n; (see -n;).

Node: AT!, Previous: 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 @!.