Re: [bugs #11700] rfe: diagnose references which produce wrong title in pronted output

[Eli Zaretskii]

> Date: Sat, 22 Jan 2005 16:00:22 +0000
> From: James Youngman <address@hidden>
> 
> If I use @ref{nodename} rather than using the three-argument form of
> cross-reference I will get in the DVI file a reference to a section
> entitled [nodename].

No, you will get a reference to the section _number_, with the
node name in brackets, like this:

   See Section 8.9 [nodename], page 123.

This uses "nodename" as the descriptive text that should tell the
reader what Section 8.9 is about.  But it is _not_ the reference
itself.  The reference part is "Section 8.9".

The assumption here is that "nodename" is a shortened section name, or
a phrase that describes the section contents as well as the section
name.  If you follow this convention, your cross-references will look
well in print even if the node name is different from the section
name, and even if you don't use the 3-argument xref.

Also note that "nodename" can actually be an anchor name, in which
case you certainly do _not_ want the printed xref to refer to the
section, but rather to the specific issue described by the referenced
text.

> To ensure that the manual is high-quality, the references should tie up, and
> checking for this manually is very time-consuming.

What do you mean by ``checking for this manually''?  If you mean that
the printed copy of the manual should be proofread, then generating
cross-references with section names will not save you that effort: a
section name can sometimes look very awkward in the printed-text
reference, but not in the on-line manual.  So you will still need to
proofread the DVI output.

As for tied-up references, they always do, since the real reference is
to a specific page, not necessarily to the beginning of the section.