On Thu, Jul 23, 2026 at 01:51:15PM +0200, Patrice Dumas wrote:
> 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.
To give a realistic example, there may two sections called "Invocation"
in a manual that describes several programs that the reader could run. The
author could write @xref{Invocation} intending to reference one of the
sections to describe the invocation of one program, while it actually references
the documentation of the invocation of another program. (For example, the
coreutils manual documents many programs.) It clearly matters if the
the wrong target is referenced in the output.
It could make sense for texi2any to print a warning or error if an
document tries to reference a shadow target that is ambiguous.
> Also it would prevent having two
> sectioning commands with the same name, which could be ok in a manual
> without nodes at all.
It's fine for two sectioning commands to have the same name, as long as the
manual doesn't try to reference them with @xref or similar.
> 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+].
I'd be happy with something like that (I hadn't considered the need for an
English word to be translated).
