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
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
<HTML>
<!--
***********************************************************************
FUNNELWEB MANUAL WEB PAGE
=========================
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.
Permission is granted to redistribute and use this manual in
any medium, with or without modification, provided that all
notices (including, without limitation, the copyright
notice, this permission notice, any record of modification,
and all legal notices) are preserved on all copies, that all
modifications are clearly marked, and that modified versions
are not represented as the original version unless all the
modifications since the manual's original release by Ross N.
Williams (www.ross.net) consist of translations or other
transformations that alter only the manual's form, not its
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
LAW THERE IS ABSOLUTELY NO WARRANTY.
***********************************************************************
-->
<HEAD>
<TITLE>3.1 Overview</TITLE>
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
</HEAD>
<BODY BACKGROUND="binary/background.gif"
BGCOLOR="#FFFFFF"
TEXT="#000000"
VLINK="#660000"
LINK="#FF0000"
ALINK="#CC0000">
<TABLE WIDTH="490">
<TR>
<TD WIDTH="130" VALIGN="top">
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>
<FONT SIZE="2">
<BR>
<A HREF="http://www.ross.net/"
TARGET="rosshome"
onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
<IMG SRC="binary/rossnet_logo.gif"
WIDTH="64" HEIGHT="32"
BORDER="0" ALT="RossNet"
HSPACE="0" VSPACE="1"></A><BR>
<BR>
<A HREF="../index.shtml"
TARGET="funnelweb"
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
<IMG SRC="binary/linklogo.gif"
WIDTH="64" HEIGHT="32"
BORDER="0" ALT="FunnelWeb"
HSPACE="0" VSPACE="1"></A><BR>
<BR>
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
<A HREF="../reference/index.html"
TARGET="funnelwebreference"
onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
<BR>
<A HREF="../developer/index.html"
TARGET="funnelwebdeveloper"
onClick="window.open('','funnelwebdeveloper','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
<BR>
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
<A HREF="intro.html"><FONT COLOR="#FFFFFF">1 Introduction</FONT></A><BR>
<A HREF="macro.html"><FONT COLOR="#FFFFFF">2 Macros</FONT></A><BR>
<A HREF="type.html"><FONT COLOR="#FFFFFF">3 Typesetting</FONT></A><BR>
<A HREF="example.html"><FONT COLOR="#FFFFFF">4 Example</FONT></A><BR>
<A HREF="hints.html"><FONT COLOR="#FFFFFF">5 Hints</FONT></A><BR>
<A HREF="examples.html"><FONT COLOR="#FFFFFF">6 Examples</FONT></A><BR>
<A HREF="web.html"><FONT COLOR="#FFFFFF">7 Webmaking</FONT></A><BR>
<BR>
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
</FONT>
</TD></TR></TABLE>
</TD>
<TD WIDTH="360" VALIGN="top">
<FONT SIZE="3">
<A HREF="../reference/index.html"><IMG SRC="binary/title.gif"
WIDTH="302" HEIGHT="24"
BORDER="0" ALT="FunnelWeb Tutorial Manual"
HSPACE="0" VSPACE="0"></A>
<P><FONT SIZE="5">3.1 Overview</FONT><BR>
<P>The previous sections of this manual have focused solely on the
macro facilities of FunnelWeb (which are more or less covered
completely). As a result, the example documents you have
seen so far have been gross distortions of "normal"
FunnelWeb documents. Normal FunnelWeb documents
often contain as much
documentation as code. While there
are applications where FunnelWeb can be used solely as a
macro preprocessor, many applications will use its
typesetting facilities as well.
<P>The macro definitions discussed in the macro tutorial
completely define the contents of the product files that
FunnelWeb will generate. These macro definitions can be
arranged in any order, and nothing external to them can
affect the contents of the product files. The macros can be
thought of as a group of self-contained islands.
<P>Although FunnelWeb will can process the macros all on
their own, the full power of FunnelWeb is realized only when
the macros are surrounded by a sea of documentation. This
sea can take two forms: directives and free text. Some of
the directives control things such as the maximum input line
length. However, most of them are typesetting directives
that affect the printed documentation. Thus a FunnelWeb
document can be viewed as a sequence of <STRONG>macro
definitions</STRONG>, <STRONG>directives</STRONG>, and
<STRONG>free text</STRONG>.
<P>Unlike the product files which consist of unscrambled
macro calls, the documentation file is more or less a direct
representation of the input file. Each part of the input
file appears in the documentation file in the order in which
it appears in the input file. However, each different kind
of part is typeset [Note: Here the term "typeset"
is used loosely to refer to FunnelWeb's generation of
typesetter commands for each construct in the input file.
Strictly, the term should be used only to describe the
actions of a typesetter program (e.g. TeX).] in a
different manner. Macros are typeset in a particular style,
with the macro body appearing in <SAMP>tt font</SAMP> (see some
FunnelWeb printed documentation for an example). Typesetter
directives have specific defined effects (more later). Free
text is typeset exactly as it is, except that each block of
text between blank lines is filled and justified as a
paragraph.
<P>The following example demonstrates how all this works.
Type in the following as <SAMP>example.fw</SAMP> and run it
through FunnelWeb with the command "<TT>fw example +t</TT>".
The "<TT>+t</TT>" instructs FunnelWeb to generate a
documentation file called <SAMP>example.tex</SAMP>. Run the
file through TeX and print it. Examine the files
<SAMP>example.out</SAMP> and <SAMP>example.tex</SAMP>.
<P>
<PRE>
You are reading some free text before the
macro. Free text can consist of any text
(not containing the FunnelWeb special
character) including typesetter commands
such as $, %, #, and TeX which
will be typeset to appear exactly as
they do in the input file!
Look out! Here comes a macro!
@O@<example.out@>==@{@-
This text is part of
a macro definition.
@}
This is free text following the macro. This
sentence contains two @{inline@} typesetter
@/directives@/. Now here is a non-inline
typesetting directive.
@t new_page
This sentence will appear on the next page.
</PRE>
<P>At the top of the <SAMP>example.tex</SAMP> documentation
file will be a set of TeX macro definitions. The TeX code
corresponding to the input above appears at the end of the
file. It should look something like this.
<P>
<PRE>
You are reading some free text before the
macro. Free text can consist of any text
(not containing the FunnelWeb special
character) including typesetter commands
such as \$, \%, \#, and \TeX{} which
will be typeset to appear exactly as
they do in the input file!
Look out! Here comes a macro!
\fwbeginmacro
\fwfilename{example.out,1}\fwequals
\fwodef \fwbtx[This text is part of
a macro definition.
]fwetx=%
\fwcdef
\fwbeginmacronotes
\fwisafile{This macro is attached to an output file.}
\fwendmacronotes
\fwendmacro
This is free text following the macro. This sentence contains
two \fwlit{inline} typesetter \fwemp{directives}.
Now here is a non-inline typesetting directive.
\fwnewpage
This sentence will appear on the next page.
</PRE>
<P>The following points explain the <SAMP>example.tex</SAMP>
file.
<P><BLOCKQUOTE><B>You don't have to know TeX:</B> If you don't
know TeX, don't pay too much attention to this section. You
don't need to know TeX to use FunnelWeb.</BLOCKQUOTE>
<P><BLOCKQUOTE><B>In order:</B> FunnelWeb has merely transformed
the input. It hasn't rearranged it.</BLOCKQUOTE>
<P><BLOCKQUOTE><B>Free text:</B> Most of the free text has been
simply copied over. The TeX typesetter justifies and fills
all paragraphs fed to it by default, so most of the text has
just been copied verbatim.</BLOCKQUOTE>
<P><BLOCKQUOTE><B>TeX codes:</B> The characters and sequences
which TeX treats as special have been neutralized in the
documentation file. For example, "<TT>$</TT>" has become
"<TT>\$</TT>". By default, FunnelWeb allows the user to
write any text as free text and not have to worry about
accidentally invoking typesetter features.</BLOCKQUOTE>
<P><BLOCKQUOTE><B>fw sequences:</B> The <SAMP>fw</SAMP> sequences
(e.g. <SAMP>\fwbeginmacro</SAMP>) invoke TeX macros
defined earlier in the documentation file (and not shown
here).</BLOCKQUOTE>
<P><BLOCKQUOTE><B>The macro:</B> The macro is typeset using a
set of predefined TeX macros. See the printed documentation
to see what this looks like on paper.</BLOCKQUOTE>
<P><BLOCKQUOTE><B>Typesetter directives:</B> Unlike the TeX
command sequences (which were neutralized), the FunnelWeb
typesetter directives turn into TeX macro calls. For
example, "<TT>@{inline@}</TT>" became
"<TT>\fwlit{inline}</TT>".</BLOCKQUOTE>
<P>FunnelWeb can also generate documentation in HTML form.
Just replace the <SAMP>+t</SAMP> option with the <SAMP>+u</SAMP> option.
<P>In summary, FunnelWeb produces typeset documentation
that transforms, but does not reorder, the input file.
Macros are typeset in a specific style. FunnelWeb typesetter
directives have particular well-defined effects. Free text
is filled and justified, but will otherwise appear in the
printed documentation exactly as it appears in the input
file.
<P>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left" VALIGN="bottom"><A HREF="type.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
<TD ALIGN="center" VALIGN="bottom"><A HREF="type.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
<TD ALIGN="right" VALIGN="bottom"><A HREF="type_independence.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
</TR>
</TABLE>
<HR>
<FONT SIZE="2">
<A HREF="mailto:webmaster@ross.net">Webmaster</A>
<A HREF="copyright.html">Copyright © Ross N. Williams 1992,1999. All rights reserved.</A><BR>
</FONT>
</FONT>
</TD>
</TR>
</TABLE>
</BODY>
<!-- *********************************************************************** -->
<!-- End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/) -->
<!-- *********************************************************************** -->
</HTML>
|
