FWEB allows a variety of commenting styles. The visible comments are in
the font \cmntfont
, which defaults to \mainfont
, a
ten-point Roman font.
@z...@x -- If a source or include file begins with `@z' (in the very first two characters of the file), then all material is skipped until and including a line beginning in column 1 with `@x' (except that lines of the form$Keyword: text of keyword $
are processed; see section$KEYWORD
: Value of RCS-like keyword). @% -- All material until and including the next newline is completely ignored. @%% -- As `@%', but also skip blank lines that immediately follow the current line.
For example,
@z Author: J. A. Krommes @x @c @% This sets the global language to C. @* EXAMPLE.
`/* ... */' is a long comment (may extend over several lines).
`// ...' is a short comment (terminated by the next newline).
`@(...@)' is a meta-comment. Meta-comments are a localized form of the N mode (see section LANGUAGES). Tangled meta-comments are begun by the contents of the style-file entry `meta.top' and terminated by `meta.bottom'. Each line of the meta-comment is begun by `meta.prefix'. Woven meta-comments are begun by `meta_code.begin' and ended by `meta_code.end'. See section Miscellaneous style-file parameters.
@n @a program main /* Get input. */ call get_input // Read the parameter file. /* Process information. Comments like this can be split over several lines. */ @( Meta-comments provide a poor-man's alignment feature i -- counter x -- data value @) i = 1 x = 2.0 call exec(i,x) end
The use of meta-comments is not recommended. Use ordinary long comments
instead. Inside of them, use the various powerful features of TeX or
LaTeX (such as \halign
or
\begin{verbatim}
...
\end{verbatim}
) to format
your comment appropriately.
During development, one frequently desires to temporarily comment out a
section of code. C programmers sometimes try to do this by enclosing the
code in /*...*/
, but this is not good
style for several reasons. First, it is impossible if the code itself
includes comments, since comments do not nest in C. Second, FWEAVE
will treat the commented code as TeX rather than C code and will
format it very poorly.
The proper way of commenting out sections of code is to use preprocessor
constructions: #if 0...#endif
in C, or more generally @#if
0...@#endif
(usable in all languages). (The FWEB preprocessor is
described in section Preprocessing.) With this method, there is no
trouble with nested comments, and FWEAVE will continue to format
the code as code, so the documentation will make sense.
Go to the first, previous, next, last section, table of contents.