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.invoking FunnelWeb

fw hello

ıIf this command doesn't work, then chances are that FunnelWeb has not been installed on your machine. Refer to Chapter  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@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 @}@braces 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:simplerule ı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-processorCpreprocessor) there are no macro calls hidden in there. If there were, there would be an @ character!

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.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 documentation.
lpr -Pcslw -d hello.dvi    ! Print the typeset documentation.

The result should be a 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.FunnelWebtwo main aspects 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. Congratulations!

The remainder of this tutorial is divided into two parts, which 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.