Fix documentation issues reported by Olaf
PATCH 1/2 docs: Use @pxref instead of @xref inside parenthesis
In reply to Glenn WashburnThe @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
@@ -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
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
PATCH 2/2 docs: Add menu to prevent older makeinfo versions from failing
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
@@ -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
Re: [PATCH 1/2] docs: Use @pxref instead of @xref inside parenthesis
In reply to Glenn WashburnQuoted 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
Reported-by Olaf Hering <[email protected]>Signed-off-by Glenn Washburn <[email protected]>--- docs/grub.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)docs/grub.texi +0
-0
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
Re: [PATCH 2/2] docs: Add menu to prevent older makeinfo versions from failing
In reply to Glenn WashburnQuoted 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.
Reported-by Olaf Hering <[email protected]>Signed-off-by Glenn Washburn <[email protected]>
- Oskari
_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel
Re: [PATCH 1/2] docs: Use @pxref instead of @xref inside parenthesis
In reply to Oskari PirhonenQuoted 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
Reported-by Olaf Hering <[email protected]>Signed-off-by Glenn Washburn <[email protected]>--- docs/grub.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)docs/grub.texi +0
-0docs/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{LoadingMaking 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