Re: [PATCH 1/2] docs: Use @pxref instead of @xref inside parenthesis

[Oskari Pirhonen]

On Sat, Aug 19, 2023 at 01:25:16 -0500, Glenn Washburn wrote:
> The @xref command is meant to be used at the beginning of a sentence
> because its expansion creates a "See " prefix. The @pxref expands with
> a prefix of "see " and is meant to be used within parenthesis. This also
> fixes an issue where there was a repeated "see" in the output.

I'm not quite convinced this is correct.

The original looks like this when viewed in info(1):

    It will read all configuration scripts as if booting directly (see
    *Note Loading an operating system directly::).

With your patch applied it looks like this:

    It will read all configuration scripts as if booting directly (*note
    Loading an operating system directly::).

According to Texinfo docs on @pxref [1], it will expand out to "see
[...]" in a printed manual only. It even recommends using this to make
it clear (and visible in info) that "see" is part of the rendered text:

    see @ref{node-name}

> 
> Reported-by: Olaf Hering <olaf@aepfle.de>
> Signed-off-by: Glenn Washburn <development@efficientek.com>
> ---
>  docs/grub.texi | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/docs/grub.texi b/docs/grub.texi
> index 61e9a0e9ebf8..8da5c3f359c5 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -956,7 +956,7 @@ information.
>  @subsection Kexec with grub2-emu
>  
>  GRUB can be run in userspace by invoking the grub2-emu tool. It will
> -read all configuration scripts as if booting directly (see @xref{Loading
> +read all configuration scripts as if booting directly (@pxref{Loading

Making this "see @ref" instead of "@pxref" keeps the "see" when viewed
in info and hopefully also fixes Olaf's "@xref in parentheses" issue:

    It will read all configuration scripts as if booting directly (see
    *note Loading an operating system directly::).

- Oskari

[1]: https://www.gnu.org/software/texinfo/manual/texinfo-html/_0040pxref.html

signature.asc
Description: PGP signature