[PATCH 0/2] Fix documentation issues reported by Olaf

[PATCH 0/2] Fix documentation issues reported by Olaf

[Glenn Washburn]

Olaf, would you see if these do indeed fix your issues?

Glenn

Glenn Washburn (2):
  docs: Use @pxref instead of @xref inside parenthesis
  docs: Add menu to prevent older makeinfo versions from failing

 docs/grub-dev.texi | 5 +++++
 docs/grub.texi     | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

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

[Glenn Washburn]

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.

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
 an operating system directly}). With the @code{--kexec} flag, and
 kexec(8) support from the operating system, the @command{linux} command
 will directly boot the target image. For systems that lack working
-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

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

[Oskari Pirhonen]

[-- Attachment #1.1: Type: text/plain, Size: 1995 bytes --]

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

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[-- Attachment #2: Type: text/plain, Size: 141 bytes --]

_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

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

[Glenn Washburn]

On Sat, 19 Aug 2023 20:57:45 -0500
Oskari Pirhonen <xxc3ncoredxx@gmail.com> wrote:

> 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::).

Yep, I agree. V2 coming.

Glenn

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

_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

[PATCH 2/2] docs: Add menu to prevent older makeinfo versions from failing

[Glenn Washburn]

It has been reported that makeinfo version 4.13a complains and returns
error when menus for chapter structuring commands are not present. It
is also known that newer makeinfos, such as version 6.7, will create
default menus when needed. Since the menu will be created regardless,
explicitly create it to support older makeinfo versions. This also
enables building to be successful when an older makeinfo is installed
because in that case info files are attempted to be generated with the
"all" target.

Reported-by: Olaf Hering <olaf@aepfle.de>
Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub-dev.texi | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
index a695b02f06df..1276c59302af 100644
--- a/docs/grub-dev.texi
+++ b/docs/grub-dev.texi
@@ -788,6 +788,11 @@ out of its way to avoid using hardware breakpoints internally and uses them as
 briefly as possible when needed, thus allowing the user to have a maximal
 number at their disposal.
 
+@menu
+* OVMF debug log::
+* Using the gdbinfo command::
+@end menu
+
 @node OVMF debug log
 @subsection OVMF debug log
 
-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

Re: [PATCH 2/2] docs: Add menu to prevent older makeinfo versions from failing

[Oskari Pirhonen]

[-- Attachment #1.1: Type: text/plain, Size: 770 bytes --]

On Sat, Aug 19, 2023 at 01:25:17 -0500, Glenn Washburn wrote:
> It has been reported that makeinfo version 4.13a complains and returns
> error when menus for chapter structuring commands are not present. It
> is also known that newer makeinfos, such as version 6.7, will create
> default menus when needed. Since the menu will be created regardless,
> explicitly create it to support older makeinfo versions. This also
> enables building to be successful when an older makeinfo is installed
> because in that case info files are attempted to be generated with the
> "all" target.
> 
> Reported-by: Olaf Hering <olaf@aepfle.de>
> Signed-off-by: Glenn Washburn <development@efficientek.com>

Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>

- Oskari

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[-- Attachment #2: Type: text/plain, Size: 141 bytes --]

_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel