Re: Is it ok to use @ref in cases where @xref/@pxref can be used?

Denis 'GNUtoo' Carikli <[email protected]> Sat, 23 Nov 2024 15:26:06 +0100

Newsgroups	gmane.comp.tex.texinfo.general
Message-ID	<20241123152606.7a0d2bca@primary_laptop>

On Sat, 23 Nov 2024 14:30:52 +0100
Patrice Dumas <[email protected]> wrote:

> On Sat, Nov 23, 2024 at 01:12:11AM +0100, Denis 'GNUtoo' Carikli
> wrote:
> > Hi,
> > 
> > Are there project that avoided things like xref/pxref in favor of
> > ref? Did that create issues (with translations to other formats or
> > languages for instance)?
> 
> I am not part of the Lilypond project, but my understanding is that
> they use @ref{} only.

I indeed found a lot of @ref{} inside lilypond, however they also have
@xref{} and I found this commit that looks relatively recent:

> f34f86e83e97056a8b176e179669c27a3b554ad5
> Author: Werner Lemberg <[email protected]>
> Date:   Fri Mar 31 10:43:33 2023 +0200
> 
>     running.itely: Use `@xref` and `@pxref` where appropriate
> 
> diff --git a/Documentation/en/usage/running.itely
> b/Documentation/en/usage/running.itely index a70ae80add..c5397067ae
> 100644 --- a/Documentation/en/usage/running.itely
> +++ b/Documentation/en/usage/running.itely
> @@ -226,7 +226,7 @@ The following options are supported.
>  @table @asis
>  
>  @item @code{-d}, @code{--define-default=}@var{var}[@code{=}@var{val}]
> -See @ref{Advanced command-line options for LilyPond}.
> +@xref{Advanced command-line options for LilyPond}.

So maybe they do accept @ref to lower the bar required to contribute and
then convert them to @xref/@pxref afterward as there are still a lot of
'See @ref'.

> They have a system for the translation of manuals that seems to be
> quite elaborate, so I guesss that they do not miss the in-built
> translation of See in @xref{} based on @documentlanguage.
That looks very interesting indeed, especially given the amount of
language they have and the size of the documentation.

Denis.

signature.asc (application/pgp-signature, 833 B)