[PATCH] doc: booting-linux: improve Bootloader spec section

[PATCH] doc: booting-linux: improve Bootloader spec section

[Roland Hieber]

Improve language and clarity of the text, and add formatting.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 Documentation/user/booting-linux.rst | 36 ++++++++++++++--------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst
index 0ba6229797cd..76883862b938 100644
--- a/Documentation/user/booting-linux.rst
+++ b/Documentation/user/booting-linux.rst
@@ -172,13 +172,14 @@ https://uapi-group.org/specifications/specs/boot_loader_specification/
 
 It follows another philosophy than the :ref:`boot_entries`. With Boot Entries
 booting is completely configured in the bootloader. Bootloader Spec Entries
-on the other hand the boot entries are on a boot medium. This gives a boot medium
-the possibility to describe where a Kernel is and what parameters it needs.
+on the other hand are part of the boot medium. This gives a boot medium
+the possibility to describe where a kernel is located and which parameters are
+needed to boot it.
 
-All Bootloader Spec Entries are in a partition on the boot medium under ``/loader/entries/*.conf``.
-In the Bootloader Spec a boot medium has a dedicated partition to use for
-boot entries. barebox is less strict, it accepts Bootloader Spec Entries on
-every partition barebox can read.
+All Bootloader Spec Entries are located in a partition on the boot medium under
+``/loader/entries/*.conf``. According to the Bootloader Spec, a boot medium has
+to use a dedicated partition for boot entries. barebox is less strict, it
+accepts Bootloader Spec Entries on every partition that barebox can read.
 
 A Bootloader Spec Entry consists of key value pairs::
 
@@ -194,7 +195,7 @@ A Bootloader Spec Entry consists of key value pairs::
 All paths are absolute paths in the partition. Bootloader Spec Entries can
 be created manually, but there also is the ``scripts/kernel-install`` tool to
 create/list/modify entries directly on a MMC/SD card or other media. To use
-it create a SD card / USB memory stick with a /boot partition with type 0xea.
+it, create an SD card / USB memory stick with a ``/boot`` partition with type ``0xea``.
 The partition can be formatted with FAT or EXT4 filesystem. If you wish to write
 to it from barebox later you must use FAT. The following creates a Bootloader
 Spec Entry on a SD card:
@@ -206,7 +207,7 @@ Spec Entry on a SD card:
                 --kernel=/home/sha/linux/arch/arm/boot/zImage --add-root-option \
                 --root=/dev/mmcblk0p1 -o "console=ttymxc0,115200"
 
-The entry can be listed with the -l option:
+The entry can be listed with the ``-l`` option:
 
 .. code-block:: sh
 
@@ -219,23 +220,22 @@ The entry can be listed with the -l option:
         options:    console=ttymxc0,115200 root=PARTUUID=0007CB20-01
         linux:      11ab7c89d02c4f66a4e2474ea25b2b84.15/linux
 
-When on barebox the SD card shows up as ``mmc1`` then this entry can be booted with
-``boot mmc1`` or with setting ``global.boot.default`` to ``mmc1``.
+When the SD card shows up as ``mmc1`` in barebox, this entry can be booted with
+``boot mmc1`` or by setting ``global.boot.default`` to ``mmc1``.
 
-``machine-id`` is an optional key. If ``global.boot.machine_id`` variable is set to
-non-empty value, then barebox accepts only Bootloader Spec entries with ``machine-id``
-key. In case if value of global variable and Bootloader Spec key match each other,
-barebox will choose the boot entry for booting. All other Bootloader Spec entries will
-be ignored.
+``machine-id`` is an optional key. If the ``global.boot.machine_id`` variable
+is set to a non-empty value, barebox will only boot the Bootloader Spec Entry
+whose ``machine-id`` key matches the ``global.boot.machine_id`` variable.
+All other Bootloader Spec entries will be ignored.
 
-A bootloader spec entry can also reside on an NFS server in which case a RFC2224
-compatible NFS URI string must be passed to the boot command:
+A bootloader spec entry can also reside on an NFS server in which case an
+RFC2224-compatible NFS URI string must be passed to the boot command:
 
 .. code-block:: sh
 
   boot nfs://nfshost[:port]//path/
 
-Additionally to the options defined in the original spec barebox understands the
+In addition to the options defined in the original spec barebox understands the
 ``linux-appendroot`` option. This is a boolean value and if set to ``true`` barebox
 will automatically append a ``root=`` string to the Linux commandline based on the
 device where the entry is found on. This makes it possible to use the same rootfs
-- 
2.39.2

Re: [PATCH] doc: booting-linux: improve Bootloader spec section

[Sascha Hauer]

On Thu, Sep 14, 2023 at 03:20:28PM +0200, Roland Hieber wrote:
> Improve language and clarity of the text, and add formatting.
> 
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> ---
>  Documentation/user/booting-linux.rst | 36 ++++++++++++++--------------
>  1 file changed, 18 insertions(+), 18 deletions(-)

Applied, thanks

Sascha

> 
> diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst
> index 0ba6229797cd..76883862b938 100644
> --- a/Documentation/user/booting-linux.rst
> +++ b/Documentation/user/booting-linux.rst
> @@ -172,13 +172,14 @@ https://uapi-group.org/specifications/specs/boot_loader_specification/
>  
>  It follows another philosophy than the :ref:`boot_entries`. With Boot Entries
>  booting is completely configured in the bootloader. Bootloader Spec Entries
> -on the other hand the boot entries are on a boot medium. This gives a boot medium
> -the possibility to describe where a Kernel is and what parameters it needs.
> +on the other hand are part of the boot medium. This gives a boot medium
> +the possibility to describe where a kernel is located and which parameters are
> +needed to boot it.
>  
> -All Bootloader Spec Entries are in a partition on the boot medium under ``/loader/entries/*.conf``.
> -In the Bootloader Spec a boot medium has a dedicated partition to use for
> -boot entries. barebox is less strict, it accepts Bootloader Spec Entries on
> -every partition barebox can read.
> +All Bootloader Spec Entries are located in a partition on the boot medium under
> +``/loader/entries/*.conf``. According to the Bootloader Spec, a boot medium has
> +to use a dedicated partition for boot entries. barebox is less strict, it
> +accepts Bootloader Spec Entries on every partition that barebox can read.
>  
>  A Bootloader Spec Entry consists of key value pairs::
>  
> @@ -194,7 +195,7 @@ A Bootloader Spec Entry consists of key value pairs::
>  All paths are absolute paths in the partition. Bootloader Spec Entries can
>  be created manually, but there also is the ``scripts/kernel-install`` tool to
>  create/list/modify entries directly on a MMC/SD card or other media. To use
> -it create a SD card / USB memory stick with a /boot partition with type 0xea.
> +it, create an SD card / USB memory stick with a ``/boot`` partition with type ``0xea``.
>  The partition can be formatted with FAT or EXT4 filesystem. If you wish to write
>  to it from barebox later you must use FAT. The following creates a Bootloader
>  Spec Entry on a SD card:
> @@ -206,7 +207,7 @@ Spec Entry on a SD card:
>                  --kernel=/home/sha/linux/arch/arm/boot/zImage --add-root-option \
>                  --root=/dev/mmcblk0p1 -o "console=ttymxc0,115200"
>  
> -The entry can be listed with the -l option:
> +The entry can be listed with the ``-l`` option:
>  
>  .. code-block:: sh
>  
> @@ -219,23 +220,22 @@ The entry can be listed with the -l option:
>          options:    console=ttymxc0,115200 root=PARTUUID=0007CB20-01
>          linux:      11ab7c89d02c4f66a4e2474ea25b2b84.15/linux
>  
> -When on barebox the SD card shows up as ``mmc1`` then this entry can be booted with
> -``boot mmc1`` or with setting ``global.boot.default`` to ``mmc1``.
> +When the SD card shows up as ``mmc1`` in barebox, this entry can be booted with
> +``boot mmc1`` or by setting ``global.boot.default`` to ``mmc1``.
>  
> -``machine-id`` is an optional key. If ``global.boot.machine_id`` variable is set to
> -non-empty value, then barebox accepts only Bootloader Spec entries with ``machine-id``
> -key. In case if value of global variable and Bootloader Spec key match each other,
> -barebox will choose the boot entry for booting. All other Bootloader Spec entries will
> -be ignored.
> +``machine-id`` is an optional key. If the ``global.boot.machine_id`` variable
> +is set to a non-empty value, barebox will only boot the Bootloader Spec Entry
> +whose ``machine-id`` key matches the ``global.boot.machine_id`` variable.
> +All other Bootloader Spec entries will be ignored.
>  
> -A bootloader spec entry can also reside on an NFS server in which case a RFC2224
> -compatible NFS URI string must be passed to the boot command:
> +A bootloader spec entry can also reside on an NFS server in which case an
> +RFC2224-compatible NFS URI string must be passed to the boot command:
>  
>  .. code-block:: sh
>  
>    boot nfs://nfshost[:port]//path/
>  
> -Additionally to the options defined in the original spec barebox understands the
> +In addition to the options defined in the original spec barebox understands the
>  ``linux-appendroot`` option. This is a boolean value and if set to ``true`` barebox
>  will automatically append a ``root=`` string to the Linux commandline based on the
>  device where the entry is found on. This makes it possible to use the same rootfs
> -- 
> 2.39.2
> 
> 
> 

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |