1.5 A Hello World Document

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 hello.fw and put the following text in it. (Note: The second character is the letter "Oh", not the digit "Zero").

@O@<hello.txt@>@{Hello World@+@}

To "run" this "program", invoke FunnelWeb using the "fw" command as follows.

fw hello

If this command doesn't work, then chances are that FunnelWeb has not been installed on your machine. Refer to the main FunnelWeb web for full details on how to obtain and install a copy of FunnelWeb. 

There should be no errors. If there are, have a look at the listing file hello.lis, 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.

hello.lis   - The LISTING file.
hello.txt   - The PRODUCT file.

Take a look at hello.txt. It should contain a single line with the text Hello World. Let's take another look at the input file.

@O@<hello.txt@>@{Hello World@+@}

The whole structure of the input file is controlled by "@", called the special character, which introduces special sequences. A scanner's-eye view of the command line looks like this:

@O  @<  "hello.txt"  @>
@{  "Hello World"  @+  @}

The @ character controls everything. In this file we have six different special sequences that together form a single macro definition. The @< and @> delimit the name of the macro. The @O 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 @{ and @} delimit the body of the macro. Finally, the @+ instructs that an end of line sequence should be inserted at that point in the product file.

If you think this syntax looks messy, then you're right. It is  messy. FunnelWeb could  have employed a "simpler" notation in which more of the @ sequences were eliminated. For example:

Warning: This example is NOT legal FunnelWeb.

#hello.txt{Hello World+}

However, if such a syntax were used, the user (you!) would have to remember that # starts a new macro. You would also have to remember that the characters } and + cannot be used in a macro body without a fuss. And so on. FunnelWeb is messier, but provides one simple rule: Nothing special happens unless the special character @ appears. 

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 @ character! (The only exception to this rule occurs where the user has explicitly changed the special character using the @= special sequence).

Let's take another look at the hello world program.

@O@<hello.txt@>@{Hello World@+@}

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.

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:

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''.

Now run it through FunnelWeb, but this time, add a +t to the command line.

fw hello +t

If all goes well, you should find that you now have

hello.lis   - A LISTING       file.
hello.tex   - A DOCUMENTATION file (in TeX format).
hello.txt   - A PRODUCT       file.

Take a look at hello.txt. You will find that it is identical to the hello.txt of the previous run. Only macro definitions affect the product files that FunnelWeb produces (as a result of @O macro definitions). The surrounding documentation has no  effect. In contrast, the new file, hello.tex (have a look at it now) which was created as a result of your adding the +t option contains a fairly full representation of the input file. Whereas hello.txt is the product file  of FunnelWeb, hello.tex is the documentation file .

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.

tex hello               ! Typeset the doc.
lpr -Pcslw -d hello.dvi ! Print the typeset doc.

If you don't have TeX, you can generate an HTML documentation file instead. Here's how:

fw hello +u

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.

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 Tangling, and the generation of typeset documentation is called Weaving. 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".