@|
: 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.]
@*
, @*
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.
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).
@[
: 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.
@%
: 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#.
@?
: 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.
@)
: End meta-comment
See the discussion of @(
, ATlp.
@-
: 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.
@^
: Make index entry (Roman type)
To insert one's own index entry in Roman type, say @^
My entry@>
.
@=
: 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.
@/
: 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.
@#
: 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.
@~
: 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-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;).
@!
: 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 @!
.