Skip to contentSkip to conversation

doc improvements

PATCH In review Glenn Washburn 2 participants 5 messages Apr 12, 2022 – Apr 14, 2022

lore
Share & tools
lore
#0 lore raw

cover doc improvements

The second patch tries to make more clear how one can use the conditional list for if and while statements. And the third patch fixes a formatting error which currently makes the online manual difficult to read in that section.

Glenn

Glenn Washburn (3):
docs: Add note that drivemap is only available on i386-pc
docs: Clarify meaning of 'list' and 'cond' for 'if' and 'while'
commands respectively
docs: Use correct list format

 docs/grub.texi | 41 ++++++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 15 deletions(-)
Signature · 1 line
2.25.1
#1 lore raw

PATCH 1/3 docs: Add note that drivemap is only available on i386-pc

---
 docs/grub.texi | 2 ++
 1 file changed, 2 insertions(+)
docs/grub.texi +2 -0
index caba8befb4..a5070cdd24 100644
@@ -4448,6 +4448,8 @@ For example:
 @example
 drivemap -s (hd0) (hd1)
 @end example
+
+NOTE: Only available on i386-pc
 @end deffn
 
 
Signature · 1 line
2.25.1
#2 lore raw

PATCH 2/3 docs: Clarify meaning of 'list' and 'cond' for 'if' and 'while' commands respectively

In reply to Glenn Washburn

It is not clear from the documentation what a 'list' is in the context of the 'if' command. Note that its a list of simple commands separated by a ';' and that only the exist status of the last command matters. The same is true for the 'cond' parameter to the 'while' command.

---
 docs/grub.texi | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)
docs/grub.texi +10 -8
index a5070cdd24..e4124dea88 100644
@@ -1781,18 +1781,20 @@ of the last command that executes.  If the expansion of the items following
 status is 0.
 
 @item if @var{list}; then @var{list}; [elif @var{list}; then @var{list};] @dots{} [else @var{list};] fi
-The @code{if} @var{list} is executed.  If its exit status is zero, the
-@code{then} @var{list} is executed.  Otherwise, each @code{elif} @var{list}
-is executed in turn, and if its exit status is zero, the corresponding
-@code{then} @var{list} is executed and the command completes.  Otherwise,
-the @code{else} @var{list} is executed, if present.  The exit status is the
-exit status of the last command executed, or zero if no condition tested
-true.
+The @code{if} @var{list} is executed, where @var{list} is a series of
+@dfn{simple command}s separated by a ';'.  If its exit status of the last
+command is zero, the @code{then} @var{list} is executed.  Otherwise, each
+@code{elif} @var{list} is executed in turn, and if its last command's exit
+status is zero, the corresponding @code{then} @var{list} is executed and the
+command completes. Otherwise, the @code{else} @var{list} is executed, if
+present.  The exit status is the exit status of the last command executed, or
+zero if no condition tested true.
 
 @item while @var{cond}; do @var{list}; done
 @itemx until @var{cond}; do @var{list}; done
 The @code{while} command continuously executes the @code{do} @var{list} as
-long as the last command in @var{cond} returns an exit status of zero.  The
+long as the last command in @var{cond} returns an exit status of zero, where
+@var{cond} is a list of @dfn{simple command}s separated by a ';'.  The
 @code{until} command is identical to the @code{while} command, except that
 the test is negated; the @code{do} @var{list} is executed as long as the
 last command in @var{cond} returns a non-zero exit status.  The exit status
Signature · 1 line
2.25.1
#3 lore raw

Re: [PATCH 2/3] docs: Clarify meaning of 'list' and 'cond' for 'if' and 'while' commands respectively

Quoted 3 lines · Glenn Washburn

It is not clear from the documentation what a 'list' is in the context of the 'if' command. Note that its a list of simple commands separated by a ';' and that only the exist status of the last command matters. The same is

s/exist/exit/ I can fix it before push...

Quoted 3 lines

true for the 'cond' parameter to the 'while' command.

Otherwise for all three patches Reviewed-by: Daniel Kiper <[email protected]>

Daniel

#4 lore raw

PATCH 3/3 docs: Use correct list format

In reply to Glenn Washburn

Using '*' to prefix list items leads to undesirable display output for at least the generation of the html documentation. Use the @itemize and @item directives to get itemized list output.

Also fix some wording and punctuation issues.

---
 docs/grub.texi | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
docs/grub.texi +14 -7
index e4124dea88..6fc8245f1c 100644
@@ -836,22 +836,29 @@ use difficult disk access methods like ahci. Hence GRUB will warn if attempted
 to install into small MBR gap except in a small number of configurations
 that were grandfathered. The grandfathered config must:
 
-* use biosdisk as disk access module for @file{/boot}
-* not use any additional partition maps to access @file{/boot}
-* @file{/boot} must be on one of following filesystems:
-   * AFFS, AFS, BFS, cpio, newc, odc, ext2/3/4, FAT, exFAT,
+@itemize @bullet
+@item
+use biosdisk as disk access module for @file{/boot}
+
+@item
+not use any additional partition maps to access @file{/boot}
+
+@item
+@file{/boot} must be on one of following filesystems:
+   AFFS, AFS, BFS, cpio, newc, odc, ext2/3/4, FAT, exFAT,
    F2FS, HFS, uncompressed HFS+, ISO9660, JFS, Minix, Minix2, Minix3, NILFS2,
    NTFS, ReiserFS, ROMFS, SFS, tar, UDF, UFS1, UFS2, XFS
+@end itemize
 
 MBR gap has few technical problems.  There is no way to reserve space in
 the embedding area with complete safety, and some proprietary software is
 known to use it to make it difficult for users to work around licensing
-restrictions. GRUB works it around by detecting sectors by other software and
+restrictions. GRUB works around it by detecting sectors by other software and
 avoiding them and protecting its own sectors using Reed-Solomon encoding.
 
-GRUB team recommends having MBR gap of at least 1000 KiB
+GRUB team recommends having MBR gap of at least 1000 KiB.
 
-Should it be not possible GRUB has support for a fallback solution which is
+Should it not be possible, GRUB has support for a fallback solution which is
 heavily recommended against. Installing to a filesystem means that GRUB is
 vulnerable to its blocks being moved around by filesystem features such as
 tail packing, or even by aggressive fsck implementations, so this approach
Signature · 1 line
2.25.1