> Date: Sat, 23 Nov 2024 01:12:11 +0100
> From: Denis 'GNUtoo' Carikli <gnu...@cyberdimension.org>
>
> What we have below is very intuitive for someone not familiar with
> texinfo at all:
> > In some cases GNU Boot even runs nonfree software not provided by GNU
> > Boot like nonfree GPUs drivers provided by the removable GPU card.
> > See @ref{Supported computer parts and peripherals} for more details
> > about this issue and how to avoid running such nonfree software.
>
> But if we follow the texinfo manual, as I understand it we're supposed
> to do that instead:
> > In some cases GNU Boot even runs nonfree software not provided by GNU
> > Boot like nonfree GPUs drivers provided by the removable GPU card.
> > @xref{Supported computer parts and peripherals} for more details
> > about this issue and how to avoid running such nonfree software.
>
> Then this requires contributors to lookup what xref is just to
> contribute some small modification to the manual.
>
> So we end up with a dilemma here as I assume that xref do exist for a
> good reason and that we're supposed to use it in cases like the one
> above. Since we're looking for contributors it also raises the question
> of people used to know texinfo as using ref instead might look awkward
> to them.
>
> 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)?
>
> Are there ways to have things that are compatible with both the manual
> and people completely new to texinfo?
Caveat: I'm not the official Texinfo maintainer, but I happen to use
Texinfo a lot in my work on GNU software.
My view of this is that there's a definite, albeit small, advantage to
using @xref instead of "See @ref". The advantage is that @xref can be
converted differently than "See @ref" in formats other than Info, like
HTML, for example. In addition, if the manual is translated to other
languages, these Texinfo directives could have different conversions
even to Info.
@pxref has an additional advantage: it doesn't require you to type a
period after the closing brace before the right parenthesis.
I am not aware of any project which decided to use only @ref in its
Texinfo documentation. (That doesn't mean there's no such project,
though.) I also haven't met any contributors who had difficulties
with using the different cross-referencing directives in Texinfo,
after I explained the rules to them. So I'm not sure this is a
serious problem that is worth giving up the advantages of using the
correct directive in each case.
