docs: Fix numerous minor mistakes in grub.info
cover docs: Fix numerous minor mistakes in grub.info
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. If there is interest in picking up this patch, I intend to read through the rest of grub.texi as well to find more of these easy fixes while adding remarks for bigger issues which require actual text changes.
Then, I can start (with some help) addressing the issues pointed to by these remarks like undocumented commands, renamed commands, wrong and outdated instructions, remarks about a future which has become present a long time ago, etc.
Uli
PATCH 1/1 docs: Fix numerous minor mistakes in grub.info
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.
--- docs/grub.texi | 66 +++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 33 deletions(-)
docs/grub.texi +33 -33
@@ -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 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 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
Signature · 1 line
2.25.2
Quoted 9 lines · Hans Ulrich Niedermann
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 <[email protected]>
A couple of *additional* comments below (on text being changed), but for all the changes:
Quoted 40 lines
--- docs/grub.texi | 66 +++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 33 deletions(-)docs/grub.texi +4
-4@@ -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
docs/grub.texi magic. · line 907
Quoted 5 lines
docs/grub.texi +1
-1@@ -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.
Quoted 13 lines
docs/grub.texi +1
-1speaking, 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.
docs/grub.texi by commands @command{kfreebsd_module}, @command{knetbsd_module_elf}, · line 984
Quoted 7 lines
docs/grub.texi +2
-2@@ -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.)
Quoted 170 lines
docs/grub.texi +25
-25the 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), cmoscleanSignature · 7 lines
2.25.2 _______________________________________________ Grub-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/grub-devel
Hi Hans,
Quoted 11 lines · Hans Ulrich Niedermann
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. If there is interest in picking up this patch, I intend to read through the rest of grub.texi as well to find more of these easy fixes while adding remarks for bigger issues which require actual text changes.
Then, I can start (with some help) addressing the issues pointed to by these remarks like undocumented commands, renamed commands, wrong and outdated instructions, remarks about a future which has become present a long time ago, etc.
It sounds like very interesting project! Nice to hear that you are taking a stab at it. I have a few comments. First of all, I will ask a few native speakers to make a review of your work. Then I want to ask you to continue your work on docs/grub.texi. If you want to go deeper in this I would like to ask you to take a look at additional documents like docs/grub-dev.texi or Multiboot and Multiboot2 specifications (you can find both of them in multiboot and multiboot branches of the GRUB git repository). Of course I would prefer if you work on one document at a time. This should ease our cooperation.
Last but not least, some lines in these documents are very long. I would like to have them wrapped at around 80th column to ease reading. If you could do that in separate patch that would be perfect. I think that this should be last step in doing docs cleanups.
...and if you could finish this work, at least for docs/grub.texi and docs/grub-dev.texi, before the 2.06 release that would be fantastic...
Daniel
Quoted 14 lines · On Thu, 16 Apr 2020 16:27:02 +0200 Daniel Kiper <[email protected]> wrote:
Quoted 11 lines · Hans Ulrich Niedermann
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. If there is interest in picking up this patch, I intend to read through the rest of grub.texi as well to find more of these easy fixes while adding remarks for bigger issues which require actual text changes.
Then, I can start (with some help) addressing the issues pointed to by these remarks like undocumented commands, renamed commands, wrong and outdated instructions, remarks about a future which has become present a long time ago, etc.
Quoted 5 lines
It sounds like very interesting project! Nice to hear that you are taking a stab at it. I have a few comments.
First of all, I will ask
a few native speakers to make a review of your work.
While I have noticed and fixed a number of mistakes non-native speakers make relatively frequently (such as the missing articles). However, I am *not* a native speaker myself and will doubtlessly make some mistakes of my own. My goal is for the text to contain fewer mistakes after my changes, while hoping for zero.
Quoted 2 lines
Then I want to
ask you to continue your work on docs/grub.texi.
docs/grub.texi is what I want to start with.
Quoted 5 lines
If you want to go
deeper in this I would like to ask you to take a look at additional documents like docs/grub-dev.texi or Multiboot and Multiboot2 specifications (you can find both of them in multiboot and multiboot branches of the GRUB git repository).
I already have multiboot and multiboot2 in my sights, as writing a bit of an example kernel for multiboot and multiboot2 is what made me notice the current deficiencies in grub.texi (such as missing documentation for @command{module2}).
Regarding grub-dev.texi, I would not have the faintest idea about what to change there apart from simple language fixes.
grub-dev.texi looks to me to be very much something to be written by the core maintainers, describing what they want. I am really new to grub development, so I have no idea whatsoever about that. Being a grub user for a decade going on two does not help here at all.
Quoted 2 lines
Of course I would prefer if you
work on one document at a time. This should ease our cooperation.
It should also ease the load on my brain.
Quoted 4 lines
Last but not least, some lines in these documents are very long. I would like to have them wrapped at around 80th column to ease reading. If you could do that in separate patch that would be perfect. I think that this should be last step in doing docs cleanups.
I'll try to remember that for the last patch.
Quoted 2 lines
...and if you could finish this work, at least for docs/grub.texi and docs/grub-dev.texi, before the 2.06 release that would be fantastic...
I have no idea what the grub release schedule is, what "2.06 release" might mean when translated to a calendar date (2020-05-01? some time in autumn 2020? some time in 2021?), and when and what a next release might be. However, I am certain this will take a few weeks at the very least to finish.
Uli
Quoted 29 lines · Hans Ulrich Niedermann
Quoted 14 lines · On Thu, 16 Apr 2020 16:27:02 +0200 Daniel Kiper <[email protected]> wrote:
Quoted 11 lines · Hans Ulrich Niedermann
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. If there is interest in picking up this patch, I intend to read through the rest of grub.texi as well to find more of these easy fixes while adding remarks for bigger issues which require actual text changes.
Then, I can start (with some help) addressing the issues pointed to by these remarks like undocumented commands, renamed commands, wrong and outdated instructions, remarks about a future which has become present a long time ago, etc.
Quoted 5 lines
It sounds like very interesting project! Nice to hear that you are taking a stab at it. I have a few comments.
First of all, I will ask
a few native speakers to make a review of your work.While I have noticed and fixed a number of mistakes non-native speakers make relatively frequently (such as the missing articles). However, I am *not* a native speaker myself and will doubtlessly make some mistakes of my own. My goal is for the text to contain fewer mistakes after my changes, while hoping for zero.
Quoted 4 lines
Quoted 2 lines
Then I want to
ask you to continue your work on docs/grub.texi.docs/grub.texi is what I want to start with.
Great!
Quoted 10 lines
Quoted 5 lines
If you want to go
deeper in this I would like to ask you to take a look at additional documents like docs/grub-dev.texi or Multiboot and Multiboot2 specifications (you can find both of them in multiboot and multiboot branches of the GRUB git repository).I already have multiboot and multiboot2 in my sights, as writing a bit of an example kernel for multiboot and multiboot2 is what made me notice the current deficiencies in grub.texi (such as missing documentation for @command{module2}).
Nice!
By the way, I saw your patches for Multiboot and Multiboot2 specs. I will take closer look at them next week.
Quoted 7 lines
Regarding grub-dev.texi, I would not have the faintest idea about what to change there apart from simple language fixes.
grub-dev.texi looks to me to be very much something to be written by the core maintainers, describing what they want. I am really new to grub development, so I have no idea whatsoever about that. Being a grub user for a decade going on two does not help here at all.
If you do not feel fully comfortable with grub-dev.texi then simple language fixes are enough for me.
Quoted 12 lines
Quoted 2 lines
Of course I would prefer if you
work on one document at a time. This should ease our cooperation.It should also ease the load on my brain.
Quoted 4 lines
Last but not least, some lines in these documents are very long. I would like to have them wrapped at around 80th column to ease reading. If you could do that in separate patch that would be perfect. I think that this should be last step in doing docs cleanups.
I'll try to remember that for the last patch.
Quoted 8 lines
Quoted 2 lines
...and if you could finish this work, at least for docs/grub.texi and docs/grub-dev.texi, before the 2.06 release that would be fantastic...
I have no idea what the grub release schedule is, what "2.06 release" might mean when translated to a calendar date (2020-05-01? some time in autumn 2020? some time in 2021?), and when and what a next release might be. However, I am certain this will take a few weeks at the very least to finish.
I am planning the release no later than June. However, we have some delay. So, it may slip a few weeks. Anyway, at this point I think the most important are changes to the docs/grub.texi. So, please focus on them if you can.
Thank you for doing this work!
Daniel