On 7/15/24 12:13, Simon Glass wrote:
Before adding more files, move the bootstd docs into a new directory,
with an index.
Signed-off-by: Simon Glass <s...@chromium.org>
---
MAINTAINERS | 2 +-
doc/board/starfive/milk-v_mars_cm.rst | 2 +-
doc/develop/board_best_practices.rst | 2 +-
doc/develop/bootstd/index.rst | 9 +++++++++
doc/develop/{bootstd.rst => bootstd/overview.rst} | 14 +++++++-------
doc/develop/index.rst | 2 +-
doc/usage/cmd/bootdev.rst | 2 +-
doc/usage/cmd/bootflow.rst | 2 +-
doc/usage/cmd/bootmeth.rst | 2 +-
doc/usage/environment.rst | 2 +-
10 files changed, 24 insertions(+), 15 deletions(-)
create mode 100644 doc/develop/bootstd/index.rst
rename doc/develop/{bootstd.rst => bootstd/overview.rst} (99%)
diff --git a/MAINTAINERS b/MAINTAINERS
index 9bee9284cca..86b830aa997 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -927,7 +927,7 @@ F: boot/bootmeth*.c
F: boot/bootstd.c
F: cmd/bootdev.c
F: cmd/bootflow.c
-F: doc/develop/bootstd.rst
+F: doc/develop/bootstd/
F: doc/usage/bootdev.rst
F: doc/usage/bootflow.rst
F: doc/usage/bootmeth.rst
diff --git a/doc/board/starfive/milk-v_mars_cm.rst
b/doc/board/starfive/milk-v_mars_cm.rst
index b31de6043bb..52d4e5e9098 100644
--- a/doc/board/starfive/milk-v_mars_cm.rst
+++ b/doc/board/starfive/milk-v_mars_cm.rst
@@ -89,7 +89,7 @@ provide a default value.
The variable *$fdtfile* is used in the boot process to automatically load
a device-tree provided by the operating system. For details of the boot
-process refer to the :doc:`U-Boot Standard Boot <../../../develop/bootstd>`
+process refer to the :doc:`/develop/bootstd/index`
description.
Boot source selection
diff --git a/doc/develop/board_best_practices.rst
b/doc/develop/board_best_practices.rst
index f44401eab7d..09632c80ce7 100644
--- a/doc/develop/board_best_practices.rst
+++ b/doc/develop/board_best_practices.rst
@@ -7,7 +7,7 @@ In addition to the regular best practices such as using
:doc:`checkpatch` and
following the :doc:`docstyle` and the :doc:`codingstyle` there are some things
which are specific to creating a new board port.
-* Implement :doc:`bootstd` to ensure that most operating systems will be
+* Implement :doc:`bootstd/index` to ensure that most operating systems will be
supported by the platform.
* The platform defconfig file must be generated via `make savedefconfig`.
diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
new file mode 100644
index 00000000000..f4f87c7787c
--- /dev/null
+++ b/doc/develop/bootstd/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ overview
diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst
similarity index 99%
rename from doc/develop/bootstd.rst
rename to doc/develop/bootstd/overview.rst
index 34631089ae0..761f61a573b 100644
--- a/doc/develop/bootstd.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -1,7 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0+:
-U-Boot Standard Boot
-====================
+Standard Boot Overview
+======================
The text is not optimized for readability, e.g.
"- bootdev - a device which can hold or access a distro (e.g. MMC,
Ethernet)"
Please, consistently replace the non-words in the boot standard
documentation:
%s/bootdev/boot device/
%s/bootmeth/boot method/
%s/bootflow/boot flow/
"distro" isn't a dictionary word either. Do you mean operating system?
That term would still not catch what a boot device is:
The boot device is the device that holds the next boot stage.
This could for instance be GRUB which in turn will offer a menu allowing
to select one of multiple operating systems.
Or that next boot stage could be an operating system kernel together
with its initial ram disk and a device-tree.
Best regards
Heinrich
Introduction
------------
@@ -17,7 +17,7 @@ introduces the following concepts:
For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible
for creating a bootflow for each kernel combination that it wants to offer.
These bootflows are stored on media so they can be discovered by U-Boot. This
-feature is typically called `distro boot` (see :doc:`distro`) because it is
+feature is typically called `distro boot` (see :doc:`../distro`) because it is
a way for distributions to boot on any hardware.
Traditionally U-Boot has relied on scripts to implement this feature. See
@@ -32,7 +32,7 @@ way to boot with U-Boot. The feature is extensible to
different Operating
Systems (such as Chromium OS) and devices (beyond just block and network
devices). It supports EFI boot and EFI bootmgr too.
-Finally, standard boot supports the operation of :doc:`vbe`.
+Finally, standard boot supports the operation of :doc:`../vbe`.
Bootflow
--------
@@ -427,16 +427,16 @@ Three commands are available:
`bootdev`
Allows listing of available bootdevs, selecting a particular one and
- getting information about it. See :doc:`../usage/cmd/bootdev`
+ getting information about it. See :doc:`/usage/cmd/bootdev`
`bootflow`
Allows scanning one or more bootdevs for bootflows, listing available
bootflows, selecting one, obtaining information about it and booting it.
- See :doc:`../usage/cmd/bootflow`
+ See :doc:`/usage/cmd/bootflow`
`bootmeth`
Allow listing of available bootmethds and setting the order in which they
- are tried. See :doc:`../usage/cmd/bootmeth`
+ are tried. See :doc:`/usage/cmd/bootmeth`
.. _BootflowStates:
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index f9c4bf839ee..c0107a783fc 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -29,7 +29,7 @@ Implementation
directories
bloblist
- bootstd
+ bootstd/index
ci_testing
commands
config_binding
diff --git a/doc/usage/cmd/bootdev.rst b/doc/usage/cmd/bootdev.rst
index f759abab354..98a0f43c580 100644
--- a/doc/usage/cmd/bootdev.rst
+++ b/doc/usage/cmd/bootdev.rst
@@ -22,7 +22,7 @@ Description
The `bootdev` command is used to manage bootdevs. It can list available
bootdevs, select one and obtain information about it.
-See :doc:`../../develop/bootstd` for more information about bootdevs in
general.
+See :doc:`/develop/bootstd/index` for more information about bootdevs in
general.
bootdev list
diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst
index 6519e4880a9..5d41fe37a7a 100644
--- a/doc/usage/cmd/bootflow.rst
+++ b/doc/usage/cmd/bootflow.rst
@@ -26,7 +26,7 @@ Description
The `bootflow` command is used to manage bootflows. It can scan bootdevs to
locate bootflows, list them and boot them.
-See :doc:`../../develop/bootstd` for more information.
+See :doc:`/develop/bootstd/index` for more information.
Note that `CONFIG_BOOTSTD_FULL` (which enables `CONFIG_CMD_BOOTFLOW_FULL) must
be enabled to obtain full functionality with this command. Otherwise, it only
diff --git a/doc/usage/cmd/bootmeth.rst b/doc/usage/cmd/bootmeth.rst
index bac9fdf85cd..c3d2ec1574b 100644
--- a/doc/usage/cmd/bootmeth.rst
+++ b/doc/usage/cmd/bootmeth.rst
@@ -21,7 +21,7 @@ Description
The `bootmeth` command is used to manage bootmeths. It can list them and
change
the order in which they are used.
-See :doc:`../../develop/bootstd` for more information.
+See :doc:`/develop/bootstd/index` for more information.
.. _bootmeth_order:
diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
index 7d4b448cb30..cc33d3ec0f2 100644
--- a/doc/usage/environment.rst
+++ b/doc/usage/environment.rst
@@ -100,7 +100,7 @@ to add environment variables.
Board maintainers are encouraged to migrate to the text-based environment as
it
is easier to maintain. The distro-board script still requires the old-style
-environments, so use :doc:`../develop/bootstd` instead.
+environments, so use :doc:`/develop/bootstd/index` instead.
List of environment variables
