[2/2] ref-manual: classes: add new image-bootfiles class

Describe the newly introduced image-bootfiles class.

Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
---
 documentation/ref-manual/classes.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

Hi Markus,

On 5/21/24 7:33 PM, Marcus Folkesson via lists.openembedded.org wrote:
> [You don't often get email from marcus.folkesson=gmail.com@lists.openembedded.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> Describe the newly introduced image-bootfiles class.
> 
> Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
> ---
>   documentation/ref-manual/classes.rst | 14 ++++++++++++++
>   1 file changed, 14 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 9520d0bf7c..53b3697bee 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -1169,6 +1169,20 @@ Yocto Project Overview and Concepts Manual.
> 
>   .. _ref-classes-image-buildinfo:
> 

This isn't the appropriate name for the reflink, we should ave

.. _ref-classes-image-bootfiles:

instead, to match the actual name of the class.

> +``image-bootfiles``
> +===================
> +
> +The :ref:`ref-classes-image-buildinfo` class copies over files listed

That's not the appropriate name, it should be 
ref-classes-image-bootfiles (it currently renders properly because the 
reflink is incorrect).

> +in :ref:`IMAGE_BOOT_FILES` to the /boot directory of the root filesystem.
> +

Tick quote /boot:
`/boot`
it;'s not meant to be understood as an English word.

> +This can be useful if no separate boot partition is used but all boot files

Replace "all" with "some", it depends on the content of 
IMAGE_BOOT_FILES, so we cannot say "all" here, it is misleading.

> +should be included into the rootfs image.
> +
> +:ref:`IMAGE_BOOT_FILES` is the same space-separated list of files used
> +by the ``bootimg-partition`` source plugin to populate the boot partition.
> +

I would not mention this here, rather edit the variables glossary entry 
for IMAGE_BOOT_FILES to mention that this is also used by image-bootfiles.
Also, it seems bootimg-efi plugin uses it, according to the glossary entry.

> +.. _ref-classes-image_types:

This isn't the appropriate name for the reflink, we should have

.. _ref-classes-image-buildinfo:

instead.

Cheers,
Quentin

Hi Quentin,

On Thu, May 23, 2024 at 03:33:00PM +0200, Quentin Schulz wrote:
> Hi Markus,
> 
> On 5/21/24 7:33 PM, Marcus Folkesson via lists.openembedded.org wrote:
> > [You don't often get email from marcus.folkesson=gmail.com@lists.openembedded.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> > 
> > Describe the newly introduced image-bootfiles class.
> > 
> > Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
> > ---
> >   documentation/ref-manual/classes.rst | 14 ++++++++++++++
> >   1 file changed, 14 insertions(+)
> > 
> > diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> > index 9520d0bf7c..53b3697bee 100644
> > --- a/documentation/ref-manual/classes.rst
> > +++ b/documentation/ref-manual/classes.rst
> > @@ -1169,6 +1169,20 @@ Yocto Project Overview and Concepts Manual.
> > 
> >   .. _ref-classes-image-buildinfo:
> > 
> 
> This isn't the appropriate name for the reflink, we should ave
> 
> .. _ref-classes-image-bootfiles:
> 
> instead, to match the actual name of the class.
> 
> > +``image-bootfiles``
> > +===================
> > +
> > +The :ref:`ref-classes-image-buildinfo` class copies over files listed
> 
> That's not the appropriate name, it should be ref-classes-image-bootfiles
> (it currently renders properly because the reflink is incorrect).
> 
> > +in :ref:`IMAGE_BOOT_FILES` to the /boot directory of the root filesystem.
> > +
> 
> Tick quote /boot:
> `/boot`
> it;'s not meant to be understood as an English word.
> 
> > +This can be useful if no separate boot partition is used but all boot files
> 
> Replace "all" with "some", it depends on the content of IMAGE_BOOT_FILES, so
> we cannot say "all" here, it is misleading.
> 
> > +should be included into the rootfs image.
> > +
> > +:ref:`IMAGE_BOOT_FILES` is the same space-separated list of files used
> > +by the ``bootimg-partition`` source plugin to populate the boot partition.
> > +
> 
> I would not mention this here, rather edit the variables glossary entry for
> IMAGE_BOOT_FILES to mention that this is also used by image-bootfiles.
> Also, it seems bootimg-efi plugin uses it, according to the glossary entry.
> 
> > +.. _ref-classes-image_types:
> 
> This isn't the appropriate name for the reflink, we should have
> 
> .. _ref-classes-image-buildinfo:
> 
> instead.
> 
> Cheers,
> Quentin

Thank you for all the comments, I agree with them all and will update
the patch accordingly.

FYI, I will drop the documentation patch from this series and resend it
once the class is ready for merging.
It was suggested by the doc mailing list (had to resend it as I was not
subscribed, so it is not part of this thread).


Best regards,
Marcus Folkesson