Re: Anchors preceding @node end up on the wrong side of a split

Arsen Arsenović <[email protected]> Fri, 19 Jun 2026 10:35:10 +0200
Newsgroups	gmane.comp.tex.texinfo.bugs
Organization	BayLibre
Message-ID	<[email protected]>
Hi Gavin,

Gavin Smith <[email protected]> writes:

> On Thu, Jun 18, 2026 at 04:22:42PM +0200, Arsen Arsenović wrote:
>> Per (texinfo) @anchor:
>> 
>>    You may wish to create cross-references to arbitrary positions in a
>>    document, not just to the beginning of nodes.  The ‘@anchor’ command
>>    marks such a position in your document, called an “anchor”.  Put an
>>    ‘@anchor’ command just before the position you wish to refer to.  For
>>    example:
>> 
>>    ...
>> 
>>       When you delete or rename a node, it is usually a good idea to define
>>    an ‘@anchor’ with the old name.  That way, any links to the old node,
>>    whether from other Texinfo manuals or general web pages, keep working.
>> 
>> Indeed, we did just that.  And placed @anchor above the new node into
>> which old node contents were merged.  But, the enchors ended up
>> generating redirects to the wrong node!
>
> They should be placed after the @node, not before it.  We could update
> the manual to state this.
>
> The node only starts after the @node line, so an @anchor before @node
> is in the previous node.
>
> This is the simplest rule to implement, and I believe that changing
> this would be difficult with texi2any, and practically impossible with
> texinfo.tex.
>
> I don't think there is any downside to placing the anchor after the
> @node line rather than before.

Ah!  Yes, clarifying this in the manual would be nice.  If we understand
the "position [we] wish to refer to" to be "the node", then one can
easily deduce that @anchor should precede it (and, this, it seems, is
what happened).

This rule is OK with me, as long as we clarify it.

>> This is currently presenting a problem for GCC, where we merged a ton of
>> nodes to make the manual more navigable, and set up redirects via
>> anchors, but those redirects now go into an unrelated node.
>> 
>> Note that a node may have arbitrarily many anchors (indeed, we have
>> between two and six in various cases).
>> 
>> I recall that a similar issue once happened with @*index commands, which
>> lead to people developing a habit of placing @*index after whatever they
>> were indexing (e.g. @item ... @*index) - I worry there may be similar
>> code "in the wild" for @anchor, which "fixes" this issue in their .texi
>> even though the actual issue is in texi2any, so it may be worth also
>> adding a warning.
>
> I remember the issue with @*index after/before @item was quite confusing,
> but I believe it was fixed.
>
> The index commands are not exactly the same as they occupy an entire line
> in the input.   The argument to @anchor{..} commands is brace-delimited.

Yep, that issue was fixed, it just looked similar, so I thought it may
be another instance of the same problem.  But apparently not!
Apologies.

FWIW, I'm glad that this turned out not to be a bug, it makes it easier
to fix.  :-)

Thanks for the quick response!
Have a lovely day.
-- 
Arsen Arsenović
signature.asc (application/pgp-signature, 430 B)