docs: make DISTRO_FEATURES examples more explicit

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.

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(-)

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

Hi Aatir,

On 6/23/22 18:04, Michael Opdenacker via lists.yoctoproject.org wrote:
> 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
> 

I would use .. note:: directive here instead of Note:. This way it is 
properly highlighted by Sphinx and the user won't miss this important 
piece of information.

Cheers,
Quentin