On Wed, Feb 12, 2025 at 10:52:35AM +0000, Werner LEMBERG wrote:
> At least for the LilyPond documentation, there are various reasons.
>
> * For translators, having the same anchor name as in the original
> document helps a lot in translation. And vice versa, it helps
> maintainers who don't speak the particular language to still do
> various maintenance tasks easier.
>
> * It helps avoid issues with transliteration. All redirection file
> names are in a single language, namely English.
I am aware that not translating node names and/or anchor names is
one possibility for translations of Texinfo manuals.
Having removed @anchor from the scope of "@xrefautomaticsectiontitle",
there is now a reason to add a new command that affects @anchor only.
Your proposal from a few days ago of using a @*heading command appears
relevant. We could use a command like "@xrefanchorlabelisheading" (hard
to get a descriptive, short name).
So with input like:
@heading Bögen
@anchor{Bows}
Then @ref{Bows} would produce "Bögen", etc.
If that is not enough, we could add a Texinfo command to be used thus:
@anchorlabel Bögen
@anchor{Bows}
This would work exactly the same way, except no heading would be printed.
The advantage of this, over adding a second argument to @anchor, would
be that it would be easy to add a stub for @anchor for old versions
of Texinfo:
@ifcommandnotdefined anchorlabel
@linemacro anchorlabel {args}
@end linemacro
@end ifcommandnotdefined
Also, there is a small chance someone could have used a comma in an anchor
name.
The only downside is that we would be adding a new command for what seems
like a fairly niche use case.
> * With my suggestion, if a `@node` gets converted to `@anchor` for
> whatever reason, all references from external files appear exactly
> the same if `@xrefautomaticsectiontitle` is active – and LilyPond
> has *a lot* of external references... Without it, the reference
> suddenly shows something else, and it would be necessary to modify
> the reference command by adding the old sectioning name as a third
> argument to get that back.
I'm confused what you mean by "external files". If this means references
from a different Texinfo manual, then "@xrefautomaticsectiontitle" cannot
have any effect. It will only work for references from other parts of
the same manual (which in split HTML output, may be other files, which
would work fine).
