An Unexpected Wrinkle

[Paul S Person]

After getting c_readme and f_readme to build properly with our wgml, I
next turned to cguide, better known as "Open Watcom C/C++ User’s
Guide"

This document is currently built with two passes. However, when built
with the "nopasses" command line option omitted, it displays (in
addition to the normal heading-level violation warnings) a large
number of "More passes required for heading processing" warnings for
various reference names and a "More passes required for TOC or
FIGLIST" warning.

And, indeed, by increasing the number of passes to 3, an example can
be found: TOC item "2.2.7 80x86 Floating Point" is said, by wgml 4.0,
to be on page 13 but is, in fact, on page 12. Our wgml (with three
passes) shows it on page 12). Apparently, at some point, the document
was edited in such a way that a third pass is now needed.

Changing the docs themselves was certainly not part of the original
plan, and the build system was not contemplated as part of it either.
The 2150 diffs and 8 unfreed memory blocks awaiting my attention are
unlikely to be affected by this at all. On the other hand, copying the
lins that change the number of passed from "2" to "3" for cguide from
my test build structure (<ow>\bld\wgml\test\docstest\mif\onebook.mif)
to the actual build structure (<ow>\docs\mif\onebook.mif) would be
very easy.

And, of course, I suppose there could be some reason for not producing
an entirely accurate document. We have, after all, probably lived with
it for a long, long time.

So, is there any reason /not/ to change the number of passes in the
actual build for cguide?

[n***@efbe.prima.de]

Post by Paul S Person
And, of course, I suppose there could be some reason for not producing
an entirely accurate document. We have, after all, probably lived with
it for a long, long time.
So, is there any reason /not/ to change the number of passes in the
actual build for cguide?

No, I don't think so, especially if the correct(?) output can be
generated with little effort.
But the question remains, how this change influences the diffs.

CU/2
Frank

[Paul S Person]

Post by n***@efbe.prima.de

Post by Paul S Person
And, of course, I suppose there could be some reason for not producing
an entirely accurate document. We have, after all, probably lived with
it for a long, long time.
So, is there any reason /not/ to change the number of passes in the
actual build for cguide?

No, I don't think so, especially if the correct(?) output can be
generated with little effort.
But the question remains, how this change influences the diffs.

Done locally.

Comparing a 3-pass file by our wgml with the 2-pass file normally
produced increases the diffs to 2173 diffs and 12 lost memory blocks.
The 23 diffs appear to be the page numbers in the TOC that are
corrected on the 2nd pass (after the TOC has already been output);
this appears to be the whole point of doing a third pass. The 4 memory
blocks are simply the same 4 as on the first two passes.

The 3-pass file produced by the build system (wgml 4.0) corrects the
error noted above (the first of the 23) and, no doubt, the remaining
22. Comparing it with the 3-pass file produced by our wgml shows 1931
diffs, an unexpected but welcome reduction.

If no one objects, I will commit the change to both onebook.mif files
next Saturday (well, if I don't accidentally do so before then while
committing something else). If any other documents are discovered with
the same problem with PS, I plan to treat them the same way.

All files use two passes when processed with WHELP, as the
TOC/FIGLIST/INDEX as such are not produced and their replacements do
not use page numbers. The second pass is to allow forward references
to be resolved properly. I do not, at this point, plan to change this,
but may revisit the question when I look at producing cguide with
WHELP.