Node:Structure, Next:Modules, Previous:Phases, Up:Concepts
An FWEB source file is structured into sections, which correspond to logical subunits of the code (either a function or a fragment of a function). Each section consists of three parts, each of which is optional: the
- TeX part;
- definition part; and
- code part.
When FTANGLE outputs code, it can combine the code parts of (possibly noncontiguous) sections into larger units called modules, as explained in Modules.
With the aid of sections, one's possibly huge and logically complex code can be broken down into bite-sized pieces, each one easily comprehensible. Since sections may correspond to only a small part of a function or subroutine, 1000-line main programs (they still exist!) should become a thing of the past.
Since sections can be combined into modules, there is no need for sections that must be physically contiguous in the output file to be contiguous in the source file. This allows for great flexibility in structuring the documentation of the code.
A simple example of an FWEB source file consisting of three sections is as follows:
@n/ % Set FWEB language to Fortran, and recognize short // comments. \Title{example.web} % \Title is an FWEB TeX macro. \author{J. A. Krommes} % \author is a LaTeX macro. @* INTRODUCTION. This code is intended to illustrate the use of the |write| statement. It also provides a simple example of the \FWEB\ macro preprocessor. @m A_CONSTANT 1.2345 // \FWEB\ preprocessor macro definition. @a program main call compute end @ The computational routine is pretty boring. @a subroutine compute write(*,*) 'Macro value = ', A_CONSTANT end @* \INDEX.
Commands to FWEB are begun by the @
symbol (see AT commands). In this example, the first command, @n
, sets the
global language to FORTRAN-77. One should always begin one's code
with a language-setting command.
In this example, the language command is invoked with an optional
argument /
. That is necessary in FORTRAN in order to tell
FWEB to use the short (single-line) comment form beginning with
//
, which otherwise conflicts with the concatenation operator.
See -n/.
For more information about languages, see Languages. For a fuller discussion of optional arguments, see Setting the language.
The @*
command begins a major or named section
(corresponding to LaTeX's \section
command); this command is
followed by the section name, terminated by a period. (The period is
essential; if it is omitted, weird errors may result.) Major sections
are entered in an automatically generated Table of Contents. They are
also printed at the top of each output page. If the full section name
is too long to so print, one can shorten it with an optional argument,
as in
@* [INTRO]INTRODUCTION.
The command @*n
(not illustrated in the above example)
begins a major (sub)section of level n, where @*0
is
equivalent to the simple @*
, @*1
indicates a subsection,
and @*2
indicates a subsubsection. The highest
permissible major level is 2 (a subsubsection). Such subsections are
also entered in the Table of Contents. For more information, see
Sections.
As the example demonstrates, the name of the very last section, which
should be starred, should be \INDEX
. Note the backslash;
\INDEX
is a TeX macro. This command tells FWEAVE to
write out the index in a special two-column format. By default,
\INDEX
expands to INDEX
, but this name can be overridden
by the style-file parameter index.name
(see S_index). For
more discussion of FWEB's indexing facilities, see Index.
Minor (unnamed) sections are begun by ("at-space"); these have no associated names and are not entered into the Table of Contents. A newline counts as a space.
All sections begin with (optional) TeX commentary. That can just be straight text; to input that, no knowledge of TeX is required. It can also include mathematical exposition or any of the other advanced features offered by TeX.
Whenever FWEB is in TeX mode, one can temporarily shift into code mode by enclosing the code within vertical bars. That code is typeset just like code in the code part (see below), except that newlines are replaced by spaces. Thus, one can say things like
Consider the C code fragment `|@c for(i=0; i<10; i++){}|', which ...
(If the global language were C instead of FORTRAN, the @c
inside
the vertical bars would not be necessary.)
The ability to switch back and forth between text mode and code mode at
will allows for a very convenient and flexible style of exposition.
The TeX part is followed by an
optional definition part. The beginning of the definition part is
signaled by the appearance of any one of the commands @d
, @f
,
@m
, @v
, or @W
(explained later).
In the previous example, the first section has a
definition part consisting of one FWEB macro definition (@m
); the
second section has no definition part. For more information, see Macros.
(Failure to appreciate how easy it is to shift from part to part can get
one into trouble. For example, don't write documentation such as
Consider the @m command
, because the @m
will inadvertently
terminate the documentation part and begin the definition part. What
one needs to do here is to use the literal @
, as in
@@m
.)
An unnamed code part is begun by @a
. A named code part is begun
by the appearance of a module name, such as @<Global
variables@>
, followed by an equals sign; see Modules. Within
the code part, one can place any sequence of code or code fragments
(they need not be complete subroutines) that are valid for the current
language. (Setting the language is described in Languages.) The
code part is terminated by the next appearance of @*
or
(which signal the beginning of a new section), or by the end of file.
The portion of the source file before the first section (i.e., before
the first @*
or ) is called in limbo or
the limbo section.
The only @
commands that are allowed in limbo (in addition to
@@
, which stands for the character @
and is allowed
anywhere) are the language-changing commands, and one of those, such as
@c
, should appear. Other text in limbo is ignored by FTANGLE
and is copied by FWEAVE to the tex
output file. Thus, one can make or
issue TeX macro definitions in limbo that override the defaults in
FWEB's macro package fwebmac.sty
. In the above example, see
the \Title
command. This is defined in fwebmac.sty
, and
basically issues LaTeX's \title
command.
(Another way of getting TeX text into the limbo section is by means of
the @l
command; see ATl.)
LaTeX users may need to know that TeX commands in limbo are
executed after the \begin{document}
command (which is
issued automatically in fwebmac.sty
). For more information, see
LaTeX.