[PATCH 0/3] doc improvements

[PATCH 0/3] doc improvements

[Glenn Washburn]

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(-)

-- 
2.25.1

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

[Glenn Washburn]

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub.texi | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/grub.texi b/docs/grub.texi
index caba8befb4..a5070cdd24 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -4448,6 +4448,8 @@ For example:
 @example
 drivemap -s (hd0) (hd1)
 @end example
+
+NOTE: Only available on i386-pc
 @end deffn
 
 
-- 
2.25.1

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

[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.

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub.texi | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index a5070cdd24..e4124dea88 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -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
-- 
2.25.1

[PATCH 3/3] docs: Use correct list format

[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.

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub.texi | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index e4124dea88..6fc8245f1c 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -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
-- 
2.25.1

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

[Daniel Kiper]

On Tue, Apr 12, 2022 at 04:56:19PM +0000, Glenn Washburn wrote:
> 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...

> true for the 'cond' parameter to the 'while' command.
>
> Signed-off-by: Glenn Washburn <development@efficientek.com>

Otherwise for all three patches Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>

Daniel