2.10 Document Structure Vs Macro Structure

Once the decision was made to adopt five levels of headings as a document structure, the next issue was to decide how this document structure would relate to the macro structure. The issues to be addressed were as follows:

• How should the hierarchical structure connect to the macro structure?
• How can backwards compatibility be achieved? Should it?
• Should the macros be cross referenced by section or by definition?
• Should nameless sections inherit macro names as headings?
• Should TeX macros be used to structure the document?

This page contains some thoughts on these issues:

TeX File Document Basis

One idea is to make the FunnelWeb input file an actual TeX .tex file which is directly typesettable, and use FunnelWeb to extract code from the TeX file to generate the product files. This approach was rejected because it is too typesetter dependent. Instead, the separate FunnelWeb format was adopted.

Hierarchical Heading Numbering

WEB and FunnelWeb V1 used two levels of section headings, but numbered them all sequentially. This is unacceptable in a fully hierarchical document which should have hierarchical section numbers such as 3.2.4. So FunnelWeb V3 uses hierarchical numbering for its headings in the documentation file. While hierarchical numbering is good for headings, it is messy and confusing when applied to macro names. In FunnelWeb V1's typeset output, each macro call has appended in square brackets the number of the section in which the macro is defined. However, hierarchical numbering would be somewhat messy. For example, in the typeset documentation, a macro call might look like.

   Write out the output[6.7.4.3]

Similarly, cross reference lists would be messy:

   This macro is used in 3.4.5, 1.2, 7.8.9, 7.4, 2.2.1.1.

These problems were solved by numbering headings hierarchically and numbering the macros sequentially and independently.

Input Format Matters Most

In terms of legacy commitment, the critical issue is not how FunnelWeb formats programs for printing, but how the FunnelWeb .fw input file should be formatted. The typeset output can always be changed simply by fiddling with FunnelWeb's Weave module. However, as soon as the input syntax is defined, it will be used in dozens or hundreds of documents and it will be very difficult indeed to change it. Therefore, the important thing is to provide as sensible and expressive a .fw format as possible.

Thus, the issue of how to number headings and macros in the typeset documentation is not a serious architectural issue.

Naming Sections

How should sections be named? In many cases (especially in the case of high-level sections) the writer will provide an explicit name for a section. In other cases, provision of such a name will merely duplicate the name of the macro contained within the section. It therefore makes sense to allow the user to omit the name from a section, allowing Weave to name the section after the first macro definition in the section. If a macro is unnamed and there is no macro in the section, an error can be generated.

Summary

All these thoughts lead to the following scheme:

• Documents will be hierarchically structured using @A, @B etc.
• Each section can be given a name @<...>.
• Sections that do not have names inherit the name of their first macro.
• If a section does not have a name or a macro, it is erroneous.
• Sections will be numbered hierarchically either by FunnelWeb or by TeX.
• Macro body parts will be numbered sequentially by FunnelWeb and cross referenced by these numbers.

All this results in a system which:

• Provides a hierarchical document structuring capability.
• Is typesetter independent.
• Does not require duplication between heading and macro names.
• Separates the heading and macro systems so that Weave can be configured at a later date to cross reference in different ways without requiring input files to be reworked.