Having already decided upon a fully hierarchical document structure, I determined to refine the details. The issues to be addressed were as follows:
After some thought, I arrived at the following thoughts:
Basically a TEX file: One option is simply to treat each .fw file as a TEXTeX file laced with macros. That is, a .fw file could be structured as a real TEX file from which FunnelWeb could extract macro definitions. This approach is feasible because TEX could be programmed to respond to the @ sequences in the same way that FunnelWeb responds to them. Thus, there would be no need for Weave.
I rejected this approach, first because it is too typesetter-dependent, and second because it complicates the inclusion of any sort of complicated post-processing in the documentation file. This would have to be implemented in TEX.
A better approach is to use an invented section notation (e.g. @A @B @C). This maintains FunnelWeb's typesetter independence and can easily be converted into TEX sectioning macros by Weave.
In the same spirit, it might be worth introducing a few @ sequences for certain general typesetting operations such as italics and program code.
Confusion in FunnelWeb V1 Heading Numbering: FunnelWeb V1 uses two levels of section headings, but numbers all the headings sequentially. In this, it is a little confused. Clearly with a fully hierarchical document structure, the headings cannot be numbered sequentially — the numbering must reflect the structure (3.2.1).
Hierarchical numbering is messy for macros: Unfortunately, hierarchical numberingsectionnumbering 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. Use of hierarchical numbering would be somewhat messy. For example, 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.
Separate numbering for macros and headings: One idea is to use hierarchical numbering for the sections, but to number the macros sequentially. This could be a little confusing in documents without much structure, but would be very much less messy than cross referencing using hierarchical numbering. Also, it will be easier to find macros indexed by a sequential number than by section, which has a less direct relationship with page bulk and number. By macro numbering is meant the sequential numbering of each macro body part through the whole document.
Input format matters more than output format: At this point we realize that a distinction should be made between the ıinput format and the ıtypeset output. The critical issue here is not how the program should be formatted for printing, but rather the format of its .fw file. The typeset output can always be changed simply by fiddling with Weave. However, as soon as the document structuring features of FunnelWeb are fixed, they will be used in dozens or hundreds of documents and it will be very difficult indeed to change them. Therefore, the important thing is to provide as sensible and expressive a .fw format as possible.
It is therefore a separate decision as to whether we should number macros by section or by sequence number. The important thing is to address the format and rules for the expression of structure.
Naming sections: The naming of sections requires some thought. 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, with Weave naming 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: