Hi Tom,
On Tue, 16 Jul 2024 at 17:18, Tom Rini <tr...@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.g...@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 <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/
> >
> > 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
