/usr/share/doc/fweb/html-info/Modules.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 | <!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: Modules</title>
<meta name="description" content="FWEB: Modules">
<meta name="keywords" content="FWEB: Modules">
<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="Phases.html#Phases" rel="next" title="Phases">
<link href="Structure.html#Structure" rel="prev" title="Structure">
<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="Modules"></a>
<div class="header">
<p>
Previous: <a href="Structure.html#Structure" accesskey="p" rel="prev">Structure</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="Modules-1"></a>
<h3 class="section">2.3 Modules</h3>
<a name="index-Modules"></a>
<p>The code parts of (possibly noncontiguous) sections can be combined into
<em>modules</em>. For <small>FWEAVE</small>, this is a <em>logical</em> combination, for
purposes of cross-referencing different pieces of the code. But for
<small>FTANGLE</small>, the combination is physical; <small>FTANGLE</small>’s output proceeds module
by module.
</p>
<p>Modules can be <em>named</em> or <em>unnamed</em>. There is exactly one
unnamed module. The fundamental operation of <small>FTANGLE</small> is that
</p>
<blockquote>
<p><em><small>FTANGLE</small> outputs the unnamed module</em>.
</p></blockquote>
<p>That output goes to a compilable file with an extension appropriate to
the current language.
</p>
<p>The contents of a module, either unnamed or named, consists of a mixture
of code and comments. <small>FTANGLE</small> ignores the comments; <small>FWEAVE</small>
treats them as TeX text. Within any TeX text, including comments,
constructions delimited by ‘<samp>|...|</samp>’ signify a temporary shift into
code mode. (In the present design, one cannot enclose a comment within
the vertical bars.)
</p>
<a name="The-unnamed-module"></a>
<h4 class="subsection">2.3.1 The unnamed module</h4>
<p>The unnamed code module
<a name="index-Unnamed-module"></a>
<a name="index-Module_002c-unnamed"></a>
is introduced by the command ‘<samp>@a</samp>’. Subsequent
uses of ‘<samp>@a</samp>’ accrete code to the unnamed module.
To repeat, the fundamental operation of <small>FTANGLE</small> is that
</p>
<blockquote>
<p><em><small>FTANGLE</small> outputs the unnamed module</em>.
</p></blockquote>
<p>Thus, there must be at least one ‘<samp>@a</samp>’ in the source file or
<small>FTANGLE</small> will output nothing.
</p>
<p>(Why is the command called ‘<samp>@a</samp>’? Historically, it was the first
letter of the alphabet, as befits its prominent status. However, one
can also think of it as “accrete.”)
</p>
<a name="Named-modules"></a>
<h4 class="subsection">2.3.2 Named modules</h4>
<a name="index-Named-module"></a>
<a name="index-Module_002c-named"></a>
<p>Named modules represent logically-connected fragments of code.
</p>
<p>A module name is specified by the construction
</p>
<div class="example">
<pre class="example">@< <i>Arbitrary TeX text</i> @>
</pre></div>
<p>Leading and trailing white space around the name text is ignored. The
name text can include the ‘<samp>|...|</samp>’ construction, which tells
<small>FWEAVE</small> to typeset a code fragment. Thus, module names can be
highly explicit—for example,
</p>
<div class="example">
<pre class="example">@< Check that |x >= 0.0|; |abort| if not @>
</pre></div>
<p>To define a named module, replace the ‘<samp>@a</samp>’ that begins the unnamed code
part of a section by ‘<samp>@< <i>module name</i> @>=</samp>’. If one uses this
construction with the same name in a later section, the effect is to
<em>accrete</em> to the contents of the module. Thus, a named module
might ultimately consist of the code from sections 2, 5, and 9, for
example.
</p>
<p>To use a named module, simply use the name anywhere in a code part;
<small>FTANGLE</small> will insert the contents of the module at the point where the
name is used. For example,
</p>
<div class="example">
<pre class="example">@c
@ Here's how to use a named module.
@a
for(i=1; i<n; i++)
@< Inner loop @>@;
@ Here's how to define a named module. Definitions may occur after use.
@< Inner...@>=
{
a[i] = i;
}
</pre></div>
<p>There are several details to notice about the above example. First,
<small>FWEAVE</small> considers module names to be simple expressions (such as the
single identifier <var>x</var>). In C, expressions are made into complete
statements (as is required in the body of a <b>for</b> statement) by
appending a semicolon. In this case, a <em>pseudo-semicolon</em>
‘<samp>@;</samp>’ is appropriate; for more discussion of that,
see <a href="AT_003b.html#AT_003b">AT;</a>.
</p>
<p>Second, after a name has appeared once in full, it may be
abbreviated by a unique prefix followed by three periods, as demonstrated in
the above example. By convention, a complete module name cannot be a
subset of another. For example, ‘<samp>@<Test@></samp>’ and ‘<samp>@<Test of
graphics@></samp>’ will elicit an error message.
</p>
<p>Commonly, the first unnamed section in the code indicates its modular
structure. For example, a C code might begin with
</p>
<div class="example">
<pre class="example">@c
@* DEMO.
@a
@<Include files@>@;
@<Typedefs@>@;
@<Function prototypes@>@;
@<Global variables@>@;
</pre></div>
<p>Subsequently one can accrete to the above named sections, as often as
desired and in any order. This way, definitions of global variables can
be introduced anywhere in the <code>web</code> source file as logical and pedagogical
exposition dictates, but will
be guaranteed to appear at the top of the code. Function prototypes
could be handled this way as well; alternatively, they could all be
collected into one section, perhaps at the end of the source file. (The
above organization still guarantees that they will appear at the
beginning of the output.) Functions could be introduced one at a time
in subsequent unnamed sections.
</p>
<p>Very rarely, one might try the following construction:
</p>
<div class="example">
<pre class="example">@
@a
@< <i>Left side</i> @> = @< <i>Right side</i> @>@;
</pre></div>
<p>Here the intent is to construct an assignment statement. However, this
will be flagged as an error because <small>FWEB</small> thinks one is trying to
define the named module ‘<samp>@<<i>Left side</i>@></samp>’, which one shouldn’t be
doing while in code mode. To make it work, just put the invisible
expression ‘<samp>@e</samp>’ (see <a href="ATe.html#ATe">ATe</a>) before the equals sign.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="Structure.html#Structure" accesskey="p" rel="prev">Structure</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>
|