[PATCH 02/13] doc: Move bootstd into its own directory

[Simon Glass]

Hi Tom,

On Tue, 16 Jul 2024 at 17:18, Tom Rini <trini at konsulko.com> wrote:
>
> On Tue, Jul 16, 2024 at 08:04:38AM +0100, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Mon, 15 Jul 2024 at 22:58, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
> > >
> > > 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 <sjg at 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/
> >
> > I do want to keep the terms, It is easy to search for bootdev or
> > bootmeth in the code and docs. Once people learn what they mean it is
> > pretty simple.
>
> I agree, this is the documentation for "bootdev" and "bootmeth" and
> "bootflow" not for "boot device" and so forth.
>
> > > "distro" isn't a dictionary word either. Do you mean operating system?
> >
> > I mean a linux distro, in the sense that 'distro boot' uses it.
>
> Maybe an initial statement early about starting your operating system
> distribution (distro), and then it's OK to say distro later on? This
> does also work on non-Linux distributions :)

I missed this comment...

There is this in the introduction: "For Linux, the distro (Linux
distribution, e.g. Debian, Fedora) is responsible"

In other places I call it an Operating System. I like the word
'distro' since it is widely used. It is also the name of the
script-based distro-boot feature. However it refers to Linux, which is
a bit limiting.

I'm open to any changes here to make things better / clearer.

Regards,
SImon