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