3.3 Hierarchical Structure

The tree structure is one of the most effective structuring tools that exists, deriving its power from the principal of divide and conquor. So effective is it that the internal organization of most technical books are tree structures which are concisely summarized in the table of contents. In contrast, computer programs are usually presented as flat sequences of text to be consumed by an anonymous compiler.

In order to bring program documentation up to the structural sophistication commonplace in technical books, FunnelWeb provides five levels of section headings implemented by the five special sequences @A, @B, @C, @D, and @E. These must always appear at the start of a line. @A is the highest level section (e.g. like LaTeX's \chapter) and @E is the lowest level section (e.g. like LaTeX's \subsubsubsection). Section headings can appear anywhere in the free text of a FunnelWeb input file (i.e. anywhere except inside a macro definition).

Each section heading in a FunnelWeb document has an associated name. The name of a section can be provided explicitly by supplying it delimited by @< and @> immediately after the section sequence (e.g. @A), or implicitly by not providing an explicit name, in which case the section takes the name of the first macro defined between the section header in question and the following section header. An error is generated if a section has not been given an explicit name and does not contain any macro definitions. Here are some example headings:

@A@<Feed the Penguins and Save the World@>
@B@<Feed the Penguins@>
@C@<Feed the little penguins@>
@C@<Feed the big penguins@>
@B@<Save the World@>
@C@<Save Europe@>
@C@<Save Africa@>

@C This heading hasn't been given an
explicit name, but will inherit the name
Save the rest of the world
from the macro definition below.

@$@<Save the rest of the world@>@Z==@{...@}

The feature of having unnamed sections inherit the name of the first macro defined within their scope is present because a common style of writing in FunnelWeb is to have one section per macro definition. Because, under this style, each section describes a single macro, it usually turns out that the macro name makes a good name for the section too. The inheritance mechanism prevents duplication of the name.

Apart from the requirement that each section have an explicit or implicit name and that its special sequence appear at the start of a line, the only other restriction on section headings is that a section heading at level n cannot appear immediately after a section heading at level n-1 or less. In other words, the hierarchy cannot be broken. For example, an @C cannot appear after an @A heading unless there is an intervening @B heading.

@A@<The Top Heading@>
@C@<Level C here is not allowed after an A@>

This rule extends to the start of the file; if there are any headings at all, the first one must be an @A heading. The following file, while short, is in error.

This FunnelWeb input file is in error
because its first section heading
is at level C rather than level A.
@C@<2@>