On Wed, Jul 22, 2026 at 11:18:46AM +0100, Gavin Smith wrote:
> On Wed, Jul 22, 2026 at 12:43:31AM +0200, Patrice Dumas wrote:
> > I think that from a user point of view, @xref{two} would not working
> > even though there is at least one "@section two" would be surprising.
> > To me it should work. We could avoid promising to which sectioning
> > command it would point to, but I think that it should lead to somewhere.
>
> Suppose there is a "@section two" (with no node line), and there is no node
> or anchor called "two". Then @xref{two} would reference that section.
>
> Then suppose the author adds another "@section two" line (with no node
> line) earlier in the document. If @xref{two} continued to reference one
> of the sections, from the author's point of view, the cross-reference
> would suddenly swing from one @section line to the other.
>
> It's possible the author wouldn't notice this swing, leading to an error
> in the manual. The part of the manual where they added the new @section
> line could have been far away from the @xref referencing the old section.
>
> The point is to avoid ambiguity in user's documents, which could lead to
> erroneous output. If user gets an error to say that no target "two" was
> defined after they add the new @section line, they will immediately know
> there is a problem to be fixed.
That is only one scenario, though, the user may also not care that much
if one or the other works, and having an error pop out while there are
targets could also be unexpected. Also it would prevent having two
sectioning commands with the same name, which could be ok in a manual
without nodes at all.
Overall, I would be in favour of a warning, but not an error.
> The problem is that the names wouldn't be stable. Somebody could put
> "@xref{two 1}" in their document and that target could move or disappear
> if the document is edited to add, remove or move sectioning commands around.
Indeed, it could be possible to use a postfix that is more "scary", but
without needing a translation, that conveys that it is not supposed to
be used for cross-references. For example [+1+].
--
Pat
