Thu 10 Feb 2011 05:49:47 PM UTC, comment #2:
(James, if you have any comments or corrections, please say, of course.)
Patrice,
After thinking about this a little, I think there are two separate things that could be done:
1) warn about any existing third argument of an xref that doesn't match the corresponding first-argument node name. I.e., for manuals that don't always use the three-argument form but when they do, the names should match. (I believe the Texinfo manual itself falls into this category.) Example:
@xref{mynode,, My Nodr} @c typo in third arg
...
@node mynode
@section My Node
2) warn about xrefs lacking a third argument where the first-argument node has a nontrivially-different corresponding section name. Example, continuing the above:
@xref{mynode}
(As I understand it, that's what James is trying to achieve with his manuals.)
In the Texinfo manual, I don't always use the full section name in third args, because the full section name can get very long, so as to be descriptive in the main text. Example:
@section @code{@@anchor}: Defining Arbitrary Cross Reference Targets
I would use just @xref{anchor,,@code{@@anchor}} for this, since all that extra text would just get in the way (IMHO).
If an xref is to an anchor rather than a node, or a node outside the current manual, I think there are no warnings to give.
I expect that few manuals manage to follow either of these rules perfectly, and third-arg xrefs can in theory be entirely independent of section names, as shown in the examples in the Texinfo manual. (Whether it's ever actually useful for them to be so completely independent, I'm not so sure.)
So, I think maybe these should be enabled via a new command:
@warnings xrefthirdwrong,xrefthirdmissing
wdyt?
Thanks,
Karl
|