4.5 Section Directive

The section directive provides a way for the user to structure the program and documentation into a hierarchical tree structure, just as in most large documents. A section construct consists of a case-insensitive identifying letter, which determines the absolute level of the section in the document, and an optional section name, which has exactly the same syntax as a macro name.

section   = "@" levelchar [name]
levelchar = "A" | "B" | "C" | "D" | "E" |
            "a" | "b" | "c" | "d" | "e"

The section construct is not quite "inline", as it must appear only at the start of a line. However, unlike the "@i", "@p", and "@t" constructs, it does not consume the remainder of the line (although it would be silly to place anything on the same line anyway).

FunnelWeb provides five levels of sections, ranging from the highest level of A (like a LaTeX chapter) to the lowest level of E (like a LaTeX subsubsubsection). FunnelWeb input files need not contain any sections at all, but if they do, the first section must be at level A, and following sections must not skip hierarchical levels (e.g. an @E cannot follow an @C). FunnelWeb generates an error if a level is skipped.

All section must  have names associated with them, but for convenience, the section name is optional if the section contains one or more macro definitions (i.e. at least one macro definition appears between the section construct in question and the next section construct in the input file.). In this case, the section inherits  the name of the first macro defined in the section. This feature streamlines the input file, avoiding duplicate name inconsistencies.

Any sequence of printable characters can be used in the section name, even the target typesetter's escape sequence (e.g. in TeX, "\").

The following example demonstrates the section construct.

@A@<Life Simulation@>

This is the main simulation module for planet
earth, simulated down to the molecular level. This
is a REALLY big program. I mean really big. I
mean, if you thought the X-Windows source code was
big, you're in for a shock...

@B We start by looking at the code for six legged
stick insects as they form a good example of a
typical object-oriented animal implementation.

@$@<Six Legged Stick Insects@>@{@-
slsi.creep; slsi.crawl; slsi.creep;@}

In the above example, the name for the level A section is provided explicitly, while the name for the level B section will be inherited from the macro name.