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
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
|
<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>1.5 A Hello World Document</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">1.5 A Hello World Document</FONT><BR>
<P>Just as one starts the process of learning a new
programming language with a "Hello World" program,
when learning FunnelWeb, you can start with a "Hello
World" document. And here it is! Edit a text file called
<SAMP>hello.fw</SAMP> and put the following text in it. (Note:
The second character is the letter "Oh", not the
digit "Zero").
<P>
<PRE>
@O@<hello.txt@>@{Hello World@+@}
</PRE>
<P>To "run" this "program", invoke
FunnelWeb using the "<TT>fw</TT>" command as
follows.
<P>
<PRE>
fw hello
</PRE>
<P><I>If this command doesn't work, then chances are
that FunnelWeb has not been installed on your machine. Refer
to the main <A HREF="../"
TARGET="funnelweb"
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>FunnelWeb</A> web for full details on how to
obtain and install a copy of FunnelWeb.</I>
<P>There should be no errors. If there are, have a look at
the listing file <SAMP>hello.lis</SAMP>, which should contain
an explanation of the error, and compare the area in the
file where the error occurred with the text above. If there
are no errors, you will find that the following two files
have been created.
<P>
<PRE>
hello.lis - The LISTING file.
hello.txt - The PRODUCT file.
</PRE>
<P>Take a look at <SAMP>hello.txt</SAMP>. It should contain a
single line with the text <SAMP>Hello World</SAMP>. Let's take
another look at the input file.
<P>
<PRE>
@O@<hello.txt@>@{Hello World@+@}
</PRE>
<P>The whole structure of the input file is controlled by
"<TT>@</TT>", called the <STRONG>special character</STRONG>,
which introduces <STRONG>special sequence</STRONG>s. A
scanner's-eye view of the command line looks like this:
<P>
<PRE>
@O @< "hello.txt" @>
@{ "Hello World" @+ @}
</PRE>
<P>The <SAMP>@</SAMP> character controls everything. In this
file we have six different special sequences that together
form a single macro definition. The
<SAMP>@<</SAMP> and
<SAMP>@></SAMP> delimit the name of the
macro. The <SAMP>@O</SAMP> signals the start of
the macro definition and indicates that the macro is to be
connected to a product file with the same name as the macro
(This is is why we got a product file when we ran
FunnelWeb). The <SAMP>@{</SAMP> and
<SAMP>@}</SAMP> delimit the body of the
macro. Finally, the <SAMP>@+</SAMP> instructs that
an end of line sequence should be inserted at that point in
the product file.
<P>If you think this syntax looks messy, then you're
right. It <I>is</I> messy. FunnelWeb <I>could</I> have
employed a "simpler" notation in which more of the
<SAMP>@</SAMP> sequences were eliminated. For example:
<P>
<PRE>
Warning: This example is NOT legal FunnelWeb.
#hello.txt{Hello World+}
</PRE>
<P>However, if such a syntax were used, the user (you!)
would have to remember that <SAMP>#</SAMP> starts a new macro.
You would also have to remember that the characters
<SAMP>}</SAMP> and <SAMP>+</SAMP> cannot be used in a macro body
without a fuss. And so on. FunnelWeb is messier, but
provides one simple rule:
<I>Nothing special happens unless the special character
<SAMP>@</SAMP> appears.</I>
<P>This means that in FunnelWeb, you can look at large
blocks of text in the confidence that (unlike for the C
pre-processor) there are no macro
calls hidden in there. If there were, there would be an
<SAMP>@</SAMP> character! (The only exception to this
rule occurs where the user has explicitly changed the
special character using the <SAMP>@=</SAMP>
special sequence).
<P>Let's take another look at the hello world program.
<P>
<PRE>
@O@<hello.txt@>@{Hello World@+@}
</PRE>
<P>In its current form, it consists of a single macro
definition. This definition, while completely valid on its
own, only represents half the power of FunnelWeb. In fact
you could say that it is a "Hello Northern Hemisphere
Program". To turn
it into a proper FunnelWeb "Hello World" program, we
need to add some documentation.
<P>A FunnelWeb input file consists of a sequence of macro
definitions surrounded by a sea of documentation which is
just ordinary text. Modify your hello world document so that
it looks like this:
<P>
<PRE>
This hello world document was
created by -insert your name here-.
@O@<hello.txt@>@{Hello World@+@}
It writes out a file called hello.txt
containing the string ``Hello World''.
</PRE>
<P>Now run it through FunnelWeb, but this time, add a
<SAMP>+t</SAMP> to the command line.
<P>
<PRE>
fw hello +t
</PRE>
<P>If all goes well, you should find that you now have
<P>
<PRE>
hello.lis - A LISTING file.
hello.tex - A DOCUMENTATION file (in TeX format).
hello.txt - A PRODUCT file.
</PRE>
<P>Take a look at <SAMP>hello.txt</SAMP>. You will find that
it is identical to the <SAMP>hello.txt</SAMP> of the previous
run. Only macro definitions affect the product files that
FunnelWeb produces (as a result of <SAMP>@O</SAMP> macro
definitions). The surrounding documentation has <I>no</I>
effect. In contrast, the new file, <SAMP>hello.tex</SAMP> (have
a look at it now) which was created as a result of your
adding the <SAMP>+t</SAMP> option contains a fairly full
representation of the input file. Whereas
<SAMP>hello.txt</SAMP> is the <I>product file</I> of
FunnelWeb, <SAMP>hello.tex</SAMP> is the <I>documentation
file</I> .
<P>Try typesetting the documentation file now using the
TeX typesetting program. Then print it. The following
commands are an example of the sort of commands you will
have to give to do this.
<P>
<PRE>
tex hello ! Typeset the doc.
lpr -Pcslw -d hello.dvi ! Print the typeset doc.
</PRE>
<P>If you don't have TeX, you can generate an
HTML documentation file instead. Here's how:
<P>
<PRE>
fw hello +u
</PRE>
<P>The documentation should consist of single page containing
the two lines of documentation along with a typeset representation
of the macro. At this point, you have exercised the two main
aspects of FunnelWeb.
Starting with an input file containing macros (or in this
case macro) and documentation, you have successfully
generated a product file based on the macros, and a
documentation file, based on the entire document.
<P>The next two sections focus on FunnelWeb's macro
facilities and its typesetting facilities. By tradition, the
generation of program files from a literate text is called
<STRONG>Tangling</STRONG>, and the generation of typeset
documentation is called <STRONG>Weaving</STRONG>. In
FunnelWeb, these two functions are aspects of a single
computer program. However, in Knuth's WEB
system, the two functions are embodied in two separate
computer programs called Tangle and Weave, presumably
because, as everyone knows, "it takes two to
Tangle".
<P>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left" VALIGN="bottom"><A HREF="intro_tutorial.html"><IMG SRC="binary/fw_left.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Prev"></A></TD>
<TD ALIGN="center" VALIGN="bottom"><A HREF="intro.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
<TD ALIGN="right" VALIGN="bottom"><A HREF="intro.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></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>
|
