Type in the following file, and use FunnelWeb and TEX to generate the corresponding printed documentation.
@A@<Table of Contents@>
@t table_of_contents
@A@<Macros for Moral Support@>
The following macro contain comments that provide moral support in the
output code.
@$@<Programmer's Cheer@>@M==@{
-- Shift to the left!
-- Shift to the right!
-- Pop up, push down!
-- Byte! Byte! Byte!
-- (From "The New Hacker's Dictionary").
@}
The next macro is similar but is distributed throughout the program.
@$@<Hacker's Cheer@>+=@{@+-- Pointer to the left@+@}
@A@<An Extremely Imperative Stack Abstraction@>
@B@<Define the Stack@>
@$@<Hacker's Cheer@>+=@{-- Pointer to the right@+@}
@$@<Stack Type@>@Z==@{type stack = record ... end;@}
@B@<Push the Stack@>
@$@<Hacker's Cheer@>+=@{-- Hack that code@+@}
@$@<Push Procedure@>@Z==@{@-
procedure push(var b:stack; v:value); @<Programmer's Cheer@> {...}@}
@B@<Pop the Stack@>
@$@<Hacker's Cheer@>+=@{-- Tight! Tight! Tight!@+@}
@$@<Pop Procedure@>@Z==@{@-
procedure pop(var b:stack); @<Programmer's Cheer@> {...}@}
@B@<Rough the Stack Up a Bit@>
@$@<Hacker's Cheer@>+=@{-- (RNW, 04-Jan-1991).@+@}
@$@<Rough Procedure@>@Z==@{@-
procedure rough(var b:stack); @<Hacker's Cheer@> {...}@}
@O@<dummy.txt@>==@{dummy@+@}
An examination of the printed documentation reveals a lot about how FunnelWeb's presentation works.
First, notice how the @t typesetter directive at the top of the file has caused a table of contents to appear. This is one of FunnelWeb's typesetting features and is discussed in a later section. The table of contents shows that the sections have been numbered hierarchically.
Now take a look at the typeset macro definitions. Most important are the numbers in square brackets that follow each macro name. As well as numbering the headings hierarchically, FunnelWeb independently numbers the macro definitions sequentially. The first macro definition (for ``Programmer's Cheer'') is numbered 1. The second (for ``Hacker's Cheer'') is numbered 2 and so on. Note that it is not macros that are numbered, but macro definitions. The distinction is necessary because some macros (such as the ``Hacker's Cheer'' macro) are additive. It is important to realize that there is no relationship between the numbers of the headings and the numbers of the macro definitions.
Now take a look at the notes beneath the body of each macro definition. All macro definitions are followed by a note indicating the definitions in which the macro is called. Additive macros have an additional list, listing the definitions in which they are defined.
Finally, take a look at the macro call of ``Programmer's Cheer'' in section 3.2 of the printed documentation. Macro calls are set in slanted roman (so that they can be distinguished from the tt font code) and are followed by the number of the defining macro definition. In this case, the macro was defined in definition 1. Further down, the call to the ``Hacker's Cheer'' macro indicates that the macro was defined in definition 2. In fact the macro is additive and definition 2 is just the first of many definitions. To list all definitions in a call to an additive macro would be unnecessarily messy.