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:
This page contains some thoughts on these issues:
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.
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[18.104.22.168]
Similarly, cross reference lists would be messy:
This macro is used in 3.4.5, 1.2, 7.8.9, 7.4, 22.214.171.124.
These problems were solved by numbering headings hierarchically and numbering the macros sequentially and independently.
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.
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.
All these thoughts lead to the following scheme:
All this results in a system which:
Webmaster Copyright © Ross N. Williams 1992,1999. All rights reserved.