[PATCH v2] ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE

[PATCH v2] ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE

[Simon A. Eugster]

This patch describes how to use overrides for grub-efi-cfg because that
is otherwise only clear after reading the .bbclass file. It also adds
a description for GRUB_TITLE.

Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
---
 documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
 documentation/ref-manual/variables.rst |  5 +++++
 2 files changed, 21 insertions(+)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 761be7b545..1de362e864 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -991,6 +991,7 @@ This class supports several variables:
 
 -  :term:`INITRD`: Indicates list of filesystem images to
    concatenate and use as an initial RAM disk (initrd) (optional).
+   Can be specified for each ``LABEL``.
 
 -  :term:`ROOTFS`: Indicates a filesystem image to include
    as the root filesystem (optional).
@@ -1004,6 +1005,9 @@ This class supports several variables:
 -  :term:`APPEND`: An override list of append strings for
    each ``LABEL``.
 
+-  :term:`GRUB_TITLE`: A custom title for each ```LABEL``.
+   Defaults to ``LABEL`` if it is not defined.
+
 -  :term:`GRUB_OPTS`: Additional options to add to the
    configuration (optional). Options are delimited using semi-colon
    characters (``;``).
@@ -1011,6 +1015,18 @@ This class supports several variables:
 -  :term:`GRUB_TIMEOUT`: Timeout before executing
    the default ``LABEL`` (optional).
 
+Each ``LABEL`` defined in the ``LABELS`` variable creates a GRUB boot entry,
+and some variables can be defined individually per ``LABEL``. The label
+specific override names are defined as ``grub_LABEL``.
+
+For example, for a label ``factory``, the override name would be
+``grub_factory``. A custom GRUB menu entry titled "Factory Install" with the
+additional parameter ``factory=yes`` can be achieved as follows::
+
+   LABELS:append = " factory"
+   APPEND:grub_factory = "factory=yes"
+   GRUB_TITLE:grub_factory = "Factory Install"
+
 .. _ref-classes-gsettings:
 
 ``gsettings``
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 0c5c7aab97..16ffbf0e85 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3320,6 +3320,11 @@ system and gives an overview of their function and contents.
       :ref:`ref-classes-grub-efi` class for more information
       on how this variable is used.
 
+   :term:`GRUB_TITLE`
+      Specifies custom titles for GRUB labels defined in  :ref:`LABELS`. See
+      the :ref:`ref-classes-grub-efi` class for more information on how this
+      variable is used.
+
    :term:`GTKIMMODULES_PACKAGES`
       When inheriting the :ref:`ref-classes-gtk-immodules-cache` class,
       this variable specifies the packages that contain the GTK+ input
-- 
2.43.0

Re: [PATCH v2] ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE

[Antonin Godard]

Hi Simon,

On Tue Jan 28, 2025 at 8:53 AM CET, Simon A. Eugster wrote:
> This patch describes how to use overrides for grub-efi-cfg because that
> is otherwise only clear after reading the .bbclass file. It also adds
> a description for GRUB_TITLE.
>
> Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> ---
>  documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
>  documentation/ref-manual/variables.rst |  5 +++++
>  2 files changed, 21 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 761be7b545..1de362e864 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -991,6 +991,7 @@ This class supports several variables:
>  
>  -  :term:`INITRD`: Indicates list of filesystem images to
>     concatenate and use as an initial RAM disk (initrd) (optional).
> +   Can be specified for each ``LABEL``.
>  
>  -  :term:`ROOTFS`: Indicates a filesystem image to include
>     as the root filesystem (optional).
> @@ -1004,6 +1005,9 @@ This class supports several variables:
>  -  :term:`APPEND`: An override list of append strings for
>     each ``LABEL``.
>  
> +-  :term:`GRUB_TITLE`: A custom title for each ```LABEL``.
> +   Defaults to ``LABEL`` if it is not defined.
> +
>  -  :term:`GRUB_OPTS`: Additional options to add to the
>     configuration (optional). Options are delimited using semi-colon
>     characters (``;``).
> @@ -1011,6 +1015,18 @@ This class supports several variables:
>  -  :term:`GRUB_TIMEOUT`: Timeout before executing
>     the default ``LABEL`` (optional).
>  
> +Each ``LABEL`` defined in the ``LABELS`` variable creates a GRUB boot entry,
> +and some variables can be defined individually per ``LABEL``. The label
> +specific override names are defined as ``grub_LABEL``.
> +
> +For example, for a label ``factory``, the override name would be
> +``grub_factory``. A custom GRUB menu entry titled "Factory Install" with the
> +additional parameter ``factory=yes`` can be achieved as follows::
> +
> +   LABELS:append = " factory"
> +   APPEND:grub_factory = "factory=yes"
> +   GRUB_TITLE:grub_factory = "Factory Install"
> +
>  .. _ref-classes-gsettings:
>  
>  ``gsettings``
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 0c5c7aab97..16ffbf0e85 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3320,6 +3320,11 @@ system and gives an overview of their function and contents.
>        :ref:`ref-classes-grub-efi` class for more information
>        on how this variable is used.
>  
> +   :term:`GRUB_TITLE`
> +      Specifies custom titles for GRUB labels defined in  :ref:`LABELS`. See

Here you make a :ref: to LABELS, but like GRUB_TITLE, it needs to be added to
variables.rst, otherwise it produces a compile error. You would also use :term:,
not :ref:.

Can you add documentation for it?

Since "LABELS" by its own does not refer to Grub, just make sure to start the
description with:

"""
When inheriting the :ref:`ref-classes-grub-efi` class, ...
"""

So someone reading the description knows in which context it's used.

If you do, please also use :term: in the class description above.

Thanks for the separate mail/Signed-off-by!

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [PATCH v2] ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE

[Simon Eugster]

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

Hi Antonin,

thanks again for your comments.

On Tue, Jan 28, 2025 at 9:20 AM Antonin Godard <antonin.godard@bootlin.com>
wrote:

> Hi Simon,
>
> On Tue Jan 28, 2025 at 8:53 AM CET, Simon A. Eugster wrote:
> > This patch describes how to use overrides for grub-efi-cfg because that
> > is otherwise only clear after reading the .bbclass file. It also adds
> > a description for GRUB_TITLE.
> >
> > Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> > ---
> >  documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
> >  documentation/ref-manual/variables.rst |  5 +++++
> >  2 files changed, 21 insertions(+)
> >
> > diff --git a/documentation/ref-manual/classes.rst
> b/documentation/ref-manual/classes.rst
> > index 761be7b545..1de362e864 100644
> > --- a/documentation/ref-manual/classes.rst
> > +++ b/documentation/ref-manual/classes.rst
> > @@ -991,6 +991,7 @@ This class supports several variables:
> >
> >  -  :term:`INITRD`: Indicates list of filesystem images to
> >     concatenate and use as an initial RAM disk (initrd) (optional).
> > +   Can be specified for each ``LABEL``.
> >
> >  -  :term:`ROOTFS`: Indicates a filesystem image to include
> >     as the root filesystem (optional).
> > @@ -1004,6 +1005,9 @@ This class supports several variables:
> >  -  :term:`APPEND`: An override list of append strings for
> >     each ``LABEL``.
> >
> > +-  :term:`GRUB_TITLE`: A custom title for each ```LABEL``.
> > +   Defaults to ``LABEL`` if it is not defined.
> > +
> >  -  :term:`GRUB_OPTS`: Additional options to add to the
> >     configuration (optional). Options are delimited using semi-colon
> >     characters (``;``).
> > @@ -1011,6 +1015,18 @@ This class supports several variables:
> >  -  :term:`GRUB_TIMEOUT`: Timeout before executing
> >     the default ``LABEL`` (optional).
> >
> > +Each ``LABEL`` defined in the ``LABELS`` variable creates a GRUB boot
> entry,
> > +and some variables can be defined individually per ``LABEL``. The label
> > +specific override names are defined as ``grub_LABEL``.
>
> +
> > +For example, for a label ``factory``, the override name would be
> > +``grub_factory``. A custom GRUB menu entry titled "Factory Install"
> with the
> > +additional parameter ``factory=yes`` can be achieved as follows::
> > +
> > +   LABELS:append = " factory"
> > +   APPEND:grub_factory = "factory=yes"
> > +   GRUB_TITLE:grub_factory = "Factory Install"
> > +
> >  .. _ref-classes-gsettings:
> >
> >  ``gsettings``
> > diff --git a/documentation/ref-manual/variables.rst
> b/documentation/ref-manual/variables.rst
> > index 0c5c7aab97..16ffbf0e85 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -3320,6 +3320,11 @@ system and gives an overview of their function
> and contents.
> >        :ref:`ref-classes-grub-efi` class for more information
> >        on how this variable is used.
> >
> > +   :term:`GRUB_TITLE`
> > +      Specifies custom titles for GRUB labels defined in
> :ref:`LABELS`. See
>
> Here you make a :ref: to LABELS, but like GRUB_TITLE, it needs to be added
> to
> variables.rst, otherwise it produces a compile error. You would also use
> :term:,
> not :ref:.
>
> Can you add documentation for it?
>

I will change it to :term:. The LABELS term already exists, right?

Also, is it okay if I fix a typo in standards.md in this same MR, or do you
need a separate patch for that?

Since "LABELS" by its own does not refer to Grub, just make sure to start
> the
> description with:
>
> """
> When inheriting the :ref:`ref-classes-grub-efi` class, ...
> """
>
> So someone reading the description knows in which context it's used.
>
> If you do, please also use :term: in the class description above.
>

Will do.


> Thanks for the separate mail/Signed-off-by!
>

Thanks for the reminder, I hardly have to sign off commits :)

Simon

[-- Attachment #2: Type: text/html, Size: 5434 bytes --]

Re: [PATCH v2] ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE

[Antonin Godard]

Hi Simon,

On Tue Jan 28, 2025 at 10:18 AM CET, Simon Eugster wrote:
> Hi Antonin,
>
> thanks again for your comments.
>
> On Tue, Jan 28, 2025 at 9:20 AM Antonin Godard <antonin.godard@bootlin.com>
> wrote:
>
>> Hi Simon,
>>
>> On Tue Jan 28, 2025 at 8:53 AM CET, Simon A. Eugster wrote:
>> > This patch describes how to use overrides for grub-efi-cfg because that
>> > is otherwise only clear after reading the .bbclass file. It also adds
>> > a description for GRUB_TITLE.
>> >
>> > Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
>> > ---
>> >  documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
>> >  documentation/ref-manual/variables.rst |  5 +++++
>> >  2 files changed, 21 insertions(+)
>> >
>> > diff --git a/documentation/ref-manual/classes.rst
>> b/documentation/ref-manual/classes.rst
>> > index 761be7b545..1de362e864 100644
>> > --- a/documentation/ref-manual/classes.rst
>> > +++ b/documentation/ref-manual/classes.rst
>> > @@ -991,6 +991,7 @@ This class supports several variables:
>> >
>> >  -  :term:`INITRD`: Indicates list of filesystem images to
>> >     concatenate and use as an initial RAM disk (initrd) (optional).
>> > +   Can be specified for each ``LABEL``.
>> >
>> >  -  :term:`ROOTFS`: Indicates a filesystem image to include
>> >     as the root filesystem (optional).
>> > @@ -1004,6 +1005,9 @@ This class supports several variables:
>> >  -  :term:`APPEND`: An override list of append strings for
>> >     each ``LABEL``.
>> >
>> > +-  :term:`GRUB_TITLE`: A custom title for each ```LABEL``.
>> > +   Defaults to ``LABEL`` if it is not defined.
>> > +
>> >  -  :term:`GRUB_OPTS`: Additional options to add to the
>> >     configuration (optional). Options are delimited using semi-colon
>> >     characters (``;``).
>> > @@ -1011,6 +1015,18 @@ This class supports several variables:
>> >  -  :term:`GRUB_TIMEOUT`: Timeout before executing
>> >     the default ``LABEL`` (optional).
>> >
>> > +Each ``LABEL`` defined in the ``LABELS`` variable creates a GRUB boot
>> entry,
>> > +and some variables can be defined individually per ``LABEL``. The label
>> > +specific override names are defined as ``grub_LABEL``.
>>
>> +
>> > +For example, for a label ``factory``, the override name would be
>> > +``grub_factory``. A custom GRUB menu entry titled "Factory Install"
>> with the
>> > +additional parameter ``factory=yes`` can be achieved as follows::
>> > +
>> > +   LABELS:append = " factory"
>> > +   APPEND:grub_factory = "factory=yes"
>> > +   GRUB_TITLE:grub_factory = "Factory Install"
>> > +
>> >  .. _ref-classes-gsettings:
>> >
>> >  ``gsettings``
>> > diff --git a/documentation/ref-manual/variables.rst
>> b/documentation/ref-manual/variables.rst
>> > index 0c5c7aab97..16ffbf0e85 100644
>> > --- a/documentation/ref-manual/variables.rst
>> > +++ b/documentation/ref-manual/variables.rst
>> > @@ -3320,6 +3320,11 @@ system and gives an overview of their function
>> and contents.
>> >        :ref:`ref-classes-grub-efi` class for more information
>> >        on how this variable is used.
>> >
>> > +   :term:`GRUB_TITLE`
>> > +      Specifies custom titles for GRUB labels defined in
>> :ref:`LABELS`. See
>>
>> Here you make a :ref: to LABELS, but like GRUB_TITLE, it needs to be added
>> to
>> variables.rst, otherwise it produces a compile error. You would also use
>> :term:,
>> not :ref:.
>>
>> Can you add documentation for it?
>>
>
> I will change it to :term:. The LABELS term already exists, right?

You're right, I should have double checked. Only change it to :term: then,
thanks!

> Also, is it okay if I fix a typo in standards.md in this same MR, or do you
> need a separate patch for that?

Please send a separated patch

Thanks,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com