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
Description: PGP signature
