/usr/share/doc/fweb/html-info/Structure.html is in fweb-doc 1.62-13.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>FWEB: Structure</title>
<meta name="description" content="FWEB: Structure">
<meta name="keywords" content="FWEB: Structure">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-index.html#Concept-index" rel="index" title="Concept index">
<link href="Parameter-index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Concepts.html#Concepts" rel="up" title="Concepts">
<link href="Modules.html#Modules" rel="next" title="Modules">
<link href="Processors.html#Processors" rel="prev" title="Processors">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Structure"></a>
<div class="header">
<p>
Next: <a href="Modules.html#Modules" accesskey="n" rel="next">Modules</a>, Previous: <a href="Phases.html#Phases" accesskey="p" rel="prev">Phases</a>, Up: <a href="Concepts.html#Concepts" accesskey="u" rel="up">Concepts</a> [<a href="Parameter-index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-index.html#Concept-index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="The-structure-of-a-web"></a>
<h3 class="section">2.2 The structure of a web</h3>
<a name="index-Web_002c-structure"></a>
<p>An <small>FWEB</small> source file is structured into <em>sections</em>, which
correspond to logical subunits of the code (either a function or a
fragment of a function).
<a name="index-Sections"></a>
Each section consists of three <em>parts</em>, each of which is optional:
<a name="index-Parts"></a>
<a name="index-Part_002c-TeX"></a>
<a name="index-Part_002c-definition"></a>
<a name="index-Part_002c-code"></a>
the
</p>
<blockquote>
<ol>
<li> TeX part;
</li><li> definition part; and
</li><li> code part.
</li></ol>
</blockquote>
<p>When <small>FTANGLE</small> outputs code, it can combine
the code parts of (possibly noncontiguous) sections into
larger units called <em>modules</em>, as explained in <a href="Modules.html#Modules">Modules</a>.
</p>
<p>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.
</p>
<p>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.
</p>
<a name="A-simple-example"></a>
<h4 class="subsection">2.2.1 A simple example</h4>
<a name="index-Example_002c-of-FWEB-file"></a>
<p>A simple example of an <small>FWEB</small> source file consisting of three sections is as
follows:
</p>
<div class="example">
<pre class="example">@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.
</pre></div>
<p>Commands to <small>FWEB</small> are begun by the ‘<samp>@</samp>’ symbol (see <a href="AT-commands.html#AT-commands">AT commands</a>). In this example, the first command, ‘<samp>@n</samp>’, sets the
global language to <small>FORTRAN</small>-77. One should always begin one’s code
with a language-setting command.
</p>
<p>In this example, the language command is invoked with an optional
argument ‘<samp>/</samp>’. That is necessary in <small>FORTRAN</small> in order to tell
<small>FWEB</small> to use the short (single-line) comment form beginning with
‘<samp>//</samp>’, which otherwise conflicts with the concatenation operator.
See <a href="_002dn_002f.html#g_t_002dn_002f">-n/</a>.
</p>
<p>For more information about languages, see <a href="Languages.html#Languages">Languages</a>. For a fuller
discussion of optional arguments, see <a href="Setting-the-language.html#Setting-the-language">Setting the language</a>.
</p>
<a name="index-_0040_002a"></a>
<a name="index-Sections_002c-named"></a>
<a name="index-Sections_002c-unnamed"></a>
<p>The ‘<samp>@*</samp>’ command begins a <em>major</em> or <em>named section</em>
(corresponding to LaTeX’s <code>\section</code> 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
</p>
<div class="example">
<pre class="example">@* [INTRO]INTRODUCTION.
</pre></div>
<p>The command ‘<samp>@*<i>n</i></samp>’ (not illustrated in the above example)
begins a major (sub)section of level <i>n</i>, where ‘<samp>@*0</samp>’ is
equivalent to the simple ‘<samp>@*</samp>’, ‘<samp>@*1</samp>’ indicates a subsection,
and ‘<samp>@*2</samp>’ 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
<a href="Sections.html#Sections">Sections</a>.
</p>
<a name="index-_005cINDEX"></a>
<a name="index-Index"></a>
<p>As the example demonstrates, the name of the very last section, which
should be starred, should be ‘<samp>\INDEX</samp>’. Note the backslash;
‘<samp>\INDEX</samp>’ is a TeX macro. This command tells <small>FWEAVE</small> to
write out the index in a special two-column format. By default,
‘<samp>\INDEX</samp>’ expands to ‘<samp>INDEX</samp>’, but this name can be overridden
by the style-file parameter ‘<samp>index.name</samp>’ (see <a href="S_005findex.html#S_005findex">S_index</a>). For
more discussion of <small>FWEB</small>’s indexing facilities, see <a href="Index.html#Index">Index</a>.
</p>
<p>Minor (<em>unnamed</em>) sections are begun by ‘<samp>@ </samp>’<!-- /@w --> (“at-space”);
these have no associated names and are not entered into the Table of
Contents. A newline counts as a space.
</p>
<a name="The-TeX-part"></a>
<h4 class="subsection">2.2.2 The TeX part</h4>
<a name="index-Commentary_002c-optional"></a>
<a name="index-Part_002c-TeX-1"></a>
<p>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.
</p>
<p>Whenever <small>FWEB</small> is in TeX mode, one can temporarily shift into <em>code mode</em>
<a name="index-Code-mode"></a>
<a name="index-Vertical-bars"></a>
<a name="index-Code_002c-typesetting"></a>
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
</p>
<div class="example">
<pre class="example">Consider the C code fragment `|@c for(i=0; i<10; i++){}|', which ...
</pre></div>
<p>(If the global language were C instead of <small>FORTRAN</small>, the ‘<samp>@c</samp>’ 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.
</p>
<a name="The-definition-part"></a>
<h4 class="subsection">2.2.3 The definition part</h4>
<a name="index-Part_002c-definition-1"></a>
<p>The TeX part is followed by an
optional <em>definition part</em>. The beginning of the definition part is
signaled by the appearance of any one of the commands ‘<samp>@d</samp>’, ‘<samp>@f</samp>’,
‘<samp>@m</samp>’, ‘<samp>@v</samp>’, or ‘<samp>@W</samp>’ (explained later).
In the previous example, the first section has a
definition part consisting of one <small>FWEB</small> macro definition (‘<samp>@m</samp>’); the
second section has no definition part. For more information, see <a href="Macros.html#Macros">Macros</a>.
</p>
<p>(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
‘<samp>Consider the @m command</samp>’, because the ‘<samp>@m</samp>’ will inadvertently
terminate the documentation part and begin the definition part. What
one needs to do here is to use the literal ‘<samp>@</samp>’, as in
‘<samp>@@m</samp>’.)
<a name="index-_0040_002c-literal"></a>
</p>
<a name="The-code-part"></a>
<h4 class="subsection">2.2.4 The code part</h4>
<a name="index-Part_002c-code-1"></a>
<p>An unnamed <em>code part</em> is begun by ‘<samp>@a</samp>’. A named code part is begun
by the appearance of a module name, such as ‘<samp>@<Global
variables@></samp>’, followed by an equals sign; see <a href="Modules.html#Modules">Modules</a>. 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 <a href="Languages.html#Languages">Languages</a>.) The
code part is terminated by the next appearance of ‘<samp>@*</samp>’ or ‘<samp>@ </samp>’<!-- /@w -->
(which signal the beginning of a new section), or by the end of file.
</p>
<a name="The-limbo-section"></a>
<h4 class="subsection">2.2.5 The limbo section</h4>
<a name="index-Section_002c-limbo"></a>
<a name="index-Limbo-section"></a>
<p>The portion of the source file before the first section (i.e., before
the first ‘<samp>@*</samp>’ or ‘<samp>@ </samp>’<!-- /@w -->) is called <em>in limbo</em> or
<em>the limbo section</em>.
<a name="index-Limbo-section-1"></a>
The only ‘<samp>@</samp>’ commands that are allowed in limbo (in addition to
‘<samp>@@</samp>’, which stands for the character ‘<samp>@</samp>’ and is allowed
anywhere) are the language-changing commands, and one of those, such as
‘<samp>@c</samp>’, should appear. Other text in limbo is ignored by <small>FTANGLE</small>
and is copied by <small>FWEAVE</small> to the <code>tex</code> output file. Thus, one can make or
issue TeX macro definitions in limbo that override the defaults in
<small>FWEB</small>’s macro package <samp>fwebmac.sty</samp>. In the above example, see
the <code>\Title</code> command. This is defined in <samp>fwebmac.sty</samp>, and
basically issues LaTeX’s <code>\title</code> command.
</p>
<p>(Another way of getting TeX text into the limbo section is by means of
the ‘<samp>@l</samp>’ command; see <a href="ATl.html#ATl">ATl</a>.)
</p>
<p>LaTeX users may need to know that TeX commands in limbo are
executed <em>after</em> the ‘<samp>\begin{document}</samp>’ command (which is
issued automatically in <samp>fwebmac.sty</samp>). For more information, see
<a href="LaTeX.html#LaTeX">LaTeX</a>.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Modules.html#Modules" accesskey="n" rel="next">Modules</a>, Previous: <a href="Phases.html#Phases" accesskey="p" rel="prev">Phases</a>, Up: <a href="Concepts.html#Concepts" accesskey="u" rel="up">Concepts</a> [<a href="Parameter-index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-index.html#Concept-index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|