Document Structuring

Experience with FunnelWeb V1, which provided only two levels of headings (major and minor) proved that there was a strong need for fully hierarchical multiple-level headings. The only question was how it should be done.

Here are some ideas that were considered.

@*@<Main Program@>
@**@<Read the Message@>
@***@<Encrypt the Buffer@>

@*@<Main Program@>
@*@*@<Read the Message@>
@*@*@*@<Encrypt the Buffer@>

@s@<Main Program@>
@ss@<Read the Message@>
@sss@<Encrypt the Buffer@>

@s@<Main Program@>
@s@s@<Read the Message@>
@s@s@s@<Encrypt the Buffer@>

@S@<Main Program@>
@SS@<Read the Message@>
@SSS@<Encrypt the Buffer@>

@S@<Main Program@>
@S@S@<Read the Message@>
@S@S@S@<Encrypt the Buffer@>

@A@<Main Program@>           -- The syntax finally chosen.
@B@<Read the Message@>
@C@<Encrypt the Buffer@>

@A Main Program
@B Read the Message
@C Encrypt the Buffer

@*A Main Program
@*B Read the Message
@*C Encrypt the Buffer

@1@<Main Program@>
@2@<Read the Message@>
@3@<Encrypt the Buffer@>
(using @A..@I@ as macro parameters or overload @1..@9)

@*@1@<Main Program@>
@*@2@<Read the Message@>
@*@3@<Encrypt the Buffer@>
(using @A..@I@ as macro parameters or overload @1..@9)

Choosing between these alternatives was not easy. The following thoughts contributed to the decision.

• Syntaxes that require visual counting are probably not a good idea.

• Syntaxes that do not delimit the heading name somehow are likely to cause problems where heading names are omitted. Users will be tempted to start paragraphs after the start of heading symbol and the result is that the first line of the paragraph will be sucked into the heading.

• Overloading the @1, …, @9 sequences is undesirable.

Decision: Use @A…@E with optional following macro name syntax for the section name. Note: We stop at @E because five levels is probably sufficient, and we may wish later to use @F for F̱ile (to augment or replace @O).