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

[Tom Rini <trini@konsulko.com>]

[-- Attachment #1: Type: text/plain, Size: 5119 bytes --]

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@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@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 :)

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]