Re: [docs] [PATCH] docs: make DISTRO_FEATURES examples more explicit

[Michael Opdenacker <michael.opdenacker@bootlin.com>]

Hi Aatir,

Many thanks for the patch!
Here are my comments...

On 6/23/22 15:15, aatir wrote:
> Make DISTRO_FEATURES example more explicit by specifying
> that DISTRO_FEATURES alone can't select build configurations,
> and need mechanisms like PACKAGECONFIG setup to take care of
> selecting build configurations.

I would talk about "DISTRO_FEATURES example" but instead 
"DISTRO_FEATURES description" here.

>
> Signed-off-by Aatir Manzur <aatrapps@gmail.com>
> ---
>   documentation/ref-manual/features.rst  | 4 +++-
>   documentation/ref-manual/variables.rst | 5 ++++-
>   2 files changed, 7 insertions(+), 2 deletions(-)
>
> diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
> index a8d0dac99..6f9edf1a1 100644
> --- a/documentation/ref-manual/features.rst
> +++ b/documentation/ref-manual/features.rst
> @@ -100,7 +100,9 @@ packages, and they can go beyond simply controlling the installation of
>   a package or packages. In most cases, the presence or absence of a
>   feature translates to the appropriate option supplied to the configure
>   script during the :ref:`ref-tasks-configure` task for
> -the recipes that optionally support the feature.
> +the recipes that optionally support the feature. Appropriate options
> +must be supplied, and enabling/disabling :term `PACKAGECONFIG` for the


Oops, there should be no space between ":term:" and "`PACKAGECONFIG`", 
otherwise Sphinx doesn't create a reference. You have multiple instances 
of this issue.

> +concerned packages is one way of supplying such options.
>   
>   Some distro features are also machine features. These select features
>   make sense to be controlled both at the machine and distribution
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 28267101d..48bdf3810 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -1873,7 +1873,10 @@ system and gives an overview of their function and contents.
>         optionally support the feature. For example, specifying "x11" in
>         :term:`DISTRO_FEATURES`, causes every piece of software built for the
>         target that can optionally support X11 to have its X11 support
> -      enabled.
> +      enabled. Note: just enabling :term: `DISTRO_FEATURES` alone doesn't
> +      enable feature support for packages, mechanisms such as making


Same issue here

> +      :term `PACKAGECONFIG` track :iterm: `DISTRO_FEATURES` are used
> +      to enable/disbale package features.

s/:iterm:/:term:/

Would you mind sending an updated patch, please?
Thanks again
Michael

-- 

Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com