Skip to contentSkip to conversation

Fix documentation issues reported by Olaf

PATCH In review Glenn Washburn 4 participants 8 messages Aug 22, 2023 – Aug 30, 2023

lore
Share & tools
lore
#0 lore raw

v2 cover Fix documentation issues reported by Olaf

Updates from v1:
* Use @ref instead of @pxref as suggested by Oskari

Olaf, would you see if this updated patch series fixes your issues?

Glenn

Glenn Washburn (2):
docs: Use @ref instead of @xref
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(-)

Range-diff against v1:
1: d85c7efc5681 ! 1: 9b49f9ab7319 docs: Use @pxref instead of @xref inside parenthesis
@@ Metadata
Author: Glenn Washburn <[email protected]>

## Commit message ##
- docs: Use @pxref instead of @xref inside parenthesis
+ docs: Use @ref instead of @xref

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.
+ because its expansion creates a "See " prefix on all output formats, and
+ on older makeinfo versions is strict about enforcing a '.' or ',' after
+ the command. The @ref command has no such restriction and is just the
+ link, which allows more control over output. This also fixes an issue
+ where there was a repeated "see" in the output.

@@ docs/grub.texi: information.

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
++read all configuration scripts as if booting directly (see @ref{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: bb2ddd029460 = 2: de20b4cddba8 docs: Add menu to prevent older makeinfo versions from failing

Signature · 7 lines
2.34.1


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

PATCH v2 1/2 docs: Use @ref instead of @xref

The @xref command is meant to be used at the beginning of a sentence because its expansion creates a "See " prefix on all output formats, and on older makeinfo versions is strict about enforcing a '.' or ',' after the command. The @ref command has no such restriction and is just the link, which allows more control over output. 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..c56d9a0afc3b 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 (see @ref{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

PATCH v2 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 the v2 series
#3 lore raw
In reply to Glenn Washburn
Quoted 11 lines · Glenn Washburn

Updates from v1:
* Use @ref instead of @pxref as suggested by Oskari

Olaf, would you see if this updated patch series fixes your issues?

Glenn

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

Both patches LGTM at least.

- Oskari

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

Reviewed-by
#5 lore raw
Quoted 5 lines · Olaf Hering

Tue, 22 Aug 2023 13:26:27 -0500 Glenn Washburn <[email protected]>:

Quoted 1 line

Olaf, would you see if this updated patch series fixes your issues?

Yes, this fixes building the documentation in SLE12SP5. Thanks.

Olaf, may I add "Tested-by" on your behalf?

Daniel

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