On Wed, Feb 12, 2025 at 10:52:35AM +0000, Werner LEMBERG wrote:
> > I get the reasoning, but it is not clear to me why one would want to
> > use something else than the @anchor argument for a link. There
> > aren't much constraints on anchor content, except that it should be
> > unique. I do not get what the second argument to anchor would
> > correspond to besides controlling directly the output of @ref in a
> > more centralized manner (but only inside a manual not for cross
> > references).
>
> 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.
I do not think that this is such a good reason to change the @anchor
command, first because it implies to hide the anchor name everywhere and
second it seems to me that falls short on allowing to do what you need.
My feeling is that another solution would be better, for example a macro
that separates the association to the english label from the output
itself, based on the document language. Something like
@macro translateanchor {en, name}
@anchor{\name\}
@end macro
@macro translateref {en, name}
\name\
@end macro
@translateanchor{in english, en français}
@ref{@translateref{in english, en français}, ...}.
What I propose allows to associate english and other language without
actual effect of english on the output, but if the maintainance requires
keeping the association and locating the ancors/refs, it could probably
be possible to do something using customization functions to get the
macro call arguments by using the source marks, that keep the macros
calls in the Texinfo tree and may (I have not checked, but it is likely
and the source marks are designed for such use) be obtained in Perl
code. Or use awk/sed.
> * It helps avoid issues with transliteration. All redirection file
> names are in a single language, namely English.
I do not get how this can work, the files need to be different? Anyway,
if for HTML, it is probably better done with more control over the
result by using Perl code than relying on the @anchor, and it would need
some control over references too.
> * 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.
But do you really want to get the old sectioning name back for printed
output? The anchor should be ok.
I imagine that a distinction between the anchor used only as a
placeholder and a label, which is my interpretation of what you want to
have, the anchor being the english node name, and the label being the
translated name and/or the section name may be relevant in some cases,
but it is not so obvious to me in based on your use cases.
--
Pat
