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.