Re: [PATCH] docs: Fix numerous minor mistakes in grub.info

[Leif Lindholm]

On Thu, Apr 16, 2020 at 15:03:44 +0200, Hans Ulrich Niedermann wrote:
> Fix minor mistakes like spelling errors, missing articles
> like 'a' and 'the', wrong word order, unnecessary trailing
> spaces, missing periods, and similar things.
> 
> This patch does not change the intended meaning of the text
> and only touches about the first 1300 of about 7000 lines
> in docs/grub.texi.
> 
> Signed-off-by: Hans Ulrich Niedermann <address@hidden>

A couple of *additional* comments below (on text being changed), but
for all the changes:
Reviewed-by: Leif Lindholm <address@hidden>

> ---
>  docs/grub.texi | 66 +++++++++++++++++++++++++-------------------------
>  1 file changed, 33 insertions(+), 33 deletions(-)
> 
> diff --git a/docs/grub.texi b/docs/grub.texi
> index 8e6f9acec..409619fb2 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -376,10 +376,10 @@ Can decompress files which were compressed by 
> @command{gzip} or
>  is CRC64 so one should use --check=crc32 option). LZMA BCJ filters are
>  supported.}. This function is both automatic and transparent to the user
>  (i.e. all functions operate upon the uncompressed contents of the specified
> -files). This greatly reduces a file size and loading time, a
> +files). This greatly reduces file size and loading time, a
>  particularly great benefit for floppies.@footnote{There are a few
>  pathological cases where loading a very badly organized ELF kernel might
> -take longer, but in practice this never happen.}
> +take longer, but in practice this never happens.}
>  
>  It is conceivable that some kernel modules should be loaded in a
>  compressed state, so a different module-loading command can be specified
> @@ -539,7 +539,7 @@ This specifies the file named @samp{vmlinuz}, found on 
> the first
>  partition of the first hard disk drive. Note that the argument
>  completion works with file names, too.
>  
> -That was easy, admit it. Now read the next chapter, to find out how to
> +That was easy, admit it. Now read the next chapter to find out how to
>  actually install GRUB on your drive.
>  
>  @node OS-specific notes about grub tools
> @@ -827,7 +827,7 @@ The partition table format traditionally used on PC BIOS 
> platforms is called
>  the Master Boot Record (MBR) format; this is the format that allows up to
>  four primary partitions and additional logical partitions.  With this
>  partition table format, there are two ways to install GRUB: it can be
> -embedded in the area between the MBR and the first partition (called by
> +embedded in the area between the MBR and the first partition (known by
>  various names, such as the "boot track", "MBR gap", or "embedding area", and
>  which is usually at least 31 KiB), or the core image can be installed in a
>  file system and a list of the blocks that make it up can be stored in the
> @@ -904,7 +904,7 @@ magic.
>  
>  GRUB has two distinct boot methods. One of the two is to load an
>  operating system directly, and the other is to chain-load another boot
> -loader which then will load an operating system actually. Generally
> +loader which then will actually load an operating system. Generally

I might also swap then/will here.

>  speaking, the former is more desirable, because you don't need to
>  install or maintain other boot loaders and GRUB is flexible enough to
>  load an operating system from an arbitrary disk/partition. However,
> @@ -934,7 +934,7 @@ Run the command @command{boot} (@pxref{boot}).
>  @end enumerate
>  
>  However, DOS and Windows have some deficiencies, so you might have to
> -use more complicated instructions. @xref{DOS/Windows}, for more
> +use more complicated instructions. @xref{DOS/Windows} for more
>  information.
>  
>  
> @@ -980,17 +980,17 @@ by commands @command{kfreebsd_module}, 
> @command{knetbsd_module_elf},
>  @command{multiboot2_module} or @command{xnu_ramdisk}
>  depending on the loader. Note that for knetbsd the image must be put
>  inside miniroot.kmod and the whole miniroot.kmod has to be loaded. In
> -kopenbsd payload this is disabled by default. Aditionally behaviour of
> -initial ramdisk depends on command line options. Several distributors provide
> +kopenbsd payload, this is disabled by default. Additionally, the behaviour of
> +initial ramdisks depends on command line options. Several distributors 
> provide

I think the above text has more issues than what is being addressed
here and could do with some rework. (Passive voice is often
problematic in documentation.)

"behaviour" and "depends" both end up being quite ambiguous in this context.
Maybe something like:
"Additionally, command line options can affect both the use of initial
ramdisks and their runtime behaviour."
(If that is the message the original was trying to convey.)

>  the image for this purpose or it's integrated in their standard ramdisk and
>  activated by special option. Consult your kernel and distribution manual for
>  more details. Other loaders like appleloader, chainloader (BIOS, EFI, 
> coreboot),
>  freedos, ntldr and plan9 provide no possibility of loading initial ramdisk 
> and
> -as far as author is aware the payloads in question don't support either 
> initial
> -ramdisk or discovering loopback boot in other way and as such not bootable 
> this
> -way. Please consider alternative boot methods like copying all files
> -from the image to actual partition. Consult your OS documentation for
> -more details
> +as far as author is aware, the payloads in question don't support either 
> initial
> +ramdisk or discovering loopback boot in another way and as such are not 
> bootable
> +in this way. Please consider alternative boot methods like copying all files
> +from the image to the actual partition. Consult your OS documentation for
> +more details.
>  
>  @node LVM cache booting
>  @section Booting from LVM cache logical volume
> @@ -1002,20 +1002,20 @@ performance of the original volume can be improved by 
> storing the frequently
>  used data on the cache pool to utilize the greater performance of faster
>  device.
>  
> -GRUB boots from LVM cache logical volume merely by reading it's original
> +GRUB boots from LVM cache logical volume merely by reading its original
>  logical volume so that dirty data in cache pool volume is disregarded. This 
> is
>  not a problem for "writethrough" cache mode as it ensures that any data 
> written
>  will be stored both on the cache and the origin LV. For the other cache mode
>  "writeback", which delays writing from the cache pool back to the origin LV 
> to
>  boost performance, GRUB may fail to boot in the wake of accidental power 
> outage
> -due to it's inability to assemble the cache device for reading the required
> +due to its inability to assemble the cache device for reading the required
>  dirty data left behind. The situation will be improved after adding full
>  support to the LVM cache logical volume in the future.
>  
>  @node OS-specific notes
>  @section Some caveats on OS-specific issues
>  
> -Here, we describe some caveats on several operating systems.
> +Here we describe some caveats on several operating systems.
>  
>  @menu
>  * GNU/Hurd::
> @@ -1038,7 +1038,7 @@ Set GRUB's root device to the same drive as GNU/Hurd's. 
>  The command
>  @code{search --set=root --file /boot/gnumach.gz} or similar may help you
>  (@pxref{search}).
>  
> -@item 
> +@item
>  Load the kernel and the modules, like this:
>  
>  @example
> @@ -1063,7 +1063,7 @@ Finally, run the command @command{boot} (@pxref{boot}).
>  @subsection GNU/Linux
>  
>  It is relatively easy to boot GNU/Linux from GRUB, because it somewhat
> -resembles to boot a Multiboot-compliant OS.
> +resembles booting a Multiboot-compliant OS.
>  
>  @enumerate
>  @item
> @@ -1088,13 +1088,13 @@ grub> @kbd{linux /vmlinuz root=/dev/sda1 acpi=off}
>  See the documentation in the Linux source tree for complete information on
>  the available options.
>  
> -With @command{linux} GRUB uses 32-bit protocol. Some BIOS services like APM
> -or EDD aren't available with this protocol. In this case you need to use
> -@command{linux16}
> +With @command{linux}, GRUB uses 32-bit protocol. Some BIOS services like APM
> +or EDD aren't available with this protocol. In this case, you need to use
> +@command{linux16}.
>  
>  @example
>  grub> @kbd{linux16 /vmlinuz root=/dev/sda1 acpi=off}
> -@end example 
> +@end example
>  
>  @item
>  If you use an initrd, execute the command @command{initrd} (@pxref{initrd})
> @@ -1104,7 +1104,7 @@ after @command{linux}:
>  grub> @kbd{initrd /initrd}
>  @end example
>  
> -If you used @command{linux16} you need to use @command{initrd16}:
> +If you have used @command{linux16}, you need to use @command{initrd16}:
>  
>  @example
>  grub> @kbd{initrd16 /initrd}
> @@ -1118,7 +1118,7 @@ Finally, run the command @command{boot} (@pxref{boot}).
>  option to the kernel to let it use less than actual memory size, you
>  will also have to specify the same memory size to GRUB. To let GRUB know
>  the size, run the command @command{uppermem} @emph{before} loading the
> -kernel. @xref{uppermem}, for more information.
> +kernel. @xref{uppermem} for more information.
>  
>  
>  @node NetBSD
> @@ -1188,8 +1188,8 @@ the problems, GRUB provides you with two helper 
> functions.
>  
>  If you have installed DOS (or Windows) on a non-first hard disk, you
>  have to use the disk swapping technique, because that OS cannot boot
> -from any disks but the first one. The workaround used in GRUB is the
> -command @command{drivemap} (@pxref{drivemap}), like this:
> +from any disk but the first one. The workaround in GRUB is the
> +command @command{drivemap} (@pxref{drivemap}), used like this:
>  
>  @example
>  drivemap -s (hd0) (hd1)
> @@ -1205,7 +1205,7 @@ disks, this probably won't work.
>  Another problem arises if you installed more than one set of DOS/Windows
>  onto one disk, because they could be confused if there are more than one
>  primary partitions for DOS/Windows. Certainly you should avoid doing
> -this, but there is a solution if you do want to do so. Use the partition
> +this, but there is a solution if you do want to do so: Use the partition
>  hiding/unhiding technique.
>  
>  If GRUB @dfn{hides} a DOS (or Windows) partition (@pxref{parttool}), DOS (or
> @@ -1236,7 +1236,7 @@ need to write the whole thing by hand.
>  
>  @menu
>  * Simple configuration::            Recommended for most users
> -* Root Identifcation Heuristics::   Summary on how the root file system is 
> identified.
> +* Root Identification Heuristics::  Summary on how the root file system is 
> identified.
>  * Shell-like scripting::            For power users and developers
>  * Multi-boot manual config::        For non-standard multi-OS scenarios
>  * Embedded configuration::          Embedding a configuration file into GRUB
> @@ -1297,7 +1297,7 @@ GRUB_DEFAULT=example-gnu-linux
>  
>  Previously it was documented the way to use entry title. While this still
>  works it's not recommended since titles often contain unstable device names
> -and may be translated
> +and may be translated.
>  
>  If you set this to @samp{saved}, then the default menu entry will be that
>  saved by @samp{GRUB_SAVEDEFAULT} or @command{grub-set-default}.  This relies 
> on
> @@ -1598,8 +1598,8 @@ edit the scripts in @file{/etc/grub.d} directly.
>  menu entries; simply type the menu entries you want to add at the end of
>  that file, making sure to leave at least the first two lines intact.
>  
> -@node Root Identifcation Heuristics
> -@section Root Identifcation Heuristics
> +@node Root Identification Heuristics
> +@section Root Identification Heuristics
>  If the target operating system uses the Linux kernel, @command{grub-mkconfig}
>  attempts to identify the root file system via a heuristic algoirthm.  This
>  algorithm selects the identification method of the root file system by
> @@ -4736,7 +4736,7 @@ Known affected systems: old Solaris, SkyOS.
>  --quirk-modules-after-kernel is needed for kernels which load at relatively
>  high address e.g. 16MiB mark and can't cope with modules stuffed between
>  1MiB mark and beginning of the kernel.
> -Known afftected systems: VMWare.
> +Known affected systems: VMWare.
>  @end deffn
>  
>  @node nativedisk
> @@ -6151,7 +6151,7 @@ Advanced operations for power users:
>  @item x86: iorw (direct access to I/O ports)
>  @end itemize
>  
> -Miscelaneous:
> +Miscellaneous:
>  @itemize
>  @item cmos (x86-*, ieee1275, mips-qemu_mips, mips-loongson): cmostest
>      (used on some laptops to check for special power-on key), cmosclean
> -- 
> 2.25.2
> 
> 
> _______________________________________________
> Grub-devel mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/grub-devel