Skip to contentSkip to conversation

Fix documentation issues reported by Olaf

PATCH Superseded Glenn Washburn 2 participants 6 messages Aug 19, 2023 – Aug 21, 2023

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover Fix documentation issues reported by Olaf

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(-)
Signature · 7 lines
2.34.1


_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel
#1 lore raw

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

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.

---
 docs/grub.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
docs/grub.texi +1 -1
index 61e9a0e9ebf8..8da5c3f359c5 100644
@@ -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
Signature · 7 lines
2.34.1


_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel
#2 lore raw

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

Quoted 4 lines · 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.

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}
Quoted 12 lines
---
 docs/grub.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
docs/grub.texi +0 -0
index 61e9a0e9ebf8..8da5c3f359c5 100644

docs/grub.texi information. · line 959

Quoted 5 lines
docs/grub.texi +1 -1
@@ -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

_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel

#3 lore raw

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

Quoted 44 lines · On Sat, 19 Aug 2023 20:57:45 -0500 Oskari Pirhonen <[email protected]>…
Quoted 4 lines · 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.

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}
Quoted 12 lines
---
 docs/grub.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
docs/grub.texi +0 -0
index 61e9a0e9ebf8..8da5c3f359c5 100644

docs/grub.texi information. · line 959

Quoted 5 lines
docs/grub.texi +1 -1
@@ -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:

Quoted 2 lines

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

Yep, I agree. V2 coming.

Glenn

Quoted 4 lines

- Oskari

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

_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel

#4 lore raw

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

In reply to 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.

---
 docs/grub-dev.texi | 5 +++++
 1 file changed, 5 insertions(+)
docs/grub-dev.texi +5 -0
index a695b02f06df..1276c59302af 100644
@@ -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
 
Signature · 7 lines
2.34.1


_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel
Reviewed-by on v1 2/2
#5 lore raw

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

Quoted 11 lines · 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.

- Oskari

_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel