| Message ID | 20250128075328.20912-1-simon.eu@gmail.com |
|---|---|
| State | Under Review |
| Headers | show |
| Series | [v2] ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE | expand |
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
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
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
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
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(+)