[PATCH] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[PATCH] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

- Add COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables to the
  variable index.
- Clarify that these plugins are still open-source
- Improve line width

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/licenses.rst  | 30 +++++++++++++++-----------
 documentation/ref-manual/variables.rst | 20 +++++++++++++++++
 2 files changed, 37 insertions(+), 13 deletions(-)

diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst
index 65914e5efe..54d3a2e5f1 100644
--- a/documentation/dev-manual/licenses.rst
+++ b/documentation/dev-manual/licenses.rst
@@ -242,10 +242,8 @@ defined in the
    COMMERCIAL_AUDIO_PLUGINS ?= ""
    COMMERCIAL_VIDEO_PLUGINS ?= ""
 
-If you
-want to enable these components, you can do so by making sure you have
-statements similar to the following in your ``local.conf`` configuration
-file::
+If you want to enable these components, you can do so by making sure you have
+statements similar to the following in your ``local.conf`` configuration file::
 
    COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
        gst-plugins-ugly-mpegaudioparse"
@@ -253,20 +251,26 @@ file::
        gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
    LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
 
-
-Of course, you could also create a matching list for those
-components using the more general "commercial" in the
-:term:`LICENSE_FLAGS_ACCEPTED` variable, but that would also enable all
-the other packages with :term:`LICENSE_FLAGS`
+Of course, you could also create a matching list for those components using
+the more general "commercial" in the :term:`LICENSE_FLAGS_ACCEPTED` variable,
+but that would also enable all the other packages with :term:`LICENSE_FLAGS`
 containing "commercial", which you may or may not want::
 
    LICENSE_FLAGS_ACCEPTED = "commercial"
 
 Specifying audio and video plugins as part of the
-``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements
-(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the
-plugins or components into built images, thus adding support for media
-formats or components.
+:term:`COMMERCIAL_AUDIO_PLUGINS` and :term:`COMMERCIAL_VIDEO_PLUGINS` statements
+(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the plugins or
+components into built images, thus adding support for media formats or
+components.
+
+.. note::
+
+   GStreamer "ugly" and "bad" plugins are actually available through
+   open source licenses. However, the "ugly" ones can be subject to software
+   patents in some countries, making it necessary to pay licensing fees
+   to distribute them. The "bad" ones are just unreliable and therefore
+   should be used with care.
 
 Maintaining Open Source License Compliance During Your Product's Lifecycle
 ==========================================================================
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 760c608bde..26215f679f 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1313,6 +1313,26 @@ system and gives an overview of their function and contents.
       optional at the distribution level, in case the hardware supports
       Bluetooth but you do not ever intend to use it.
 
+   :term:`COMMERCIAL_AUDIO_PLUGINS`
+      This variable is specific to the :yocto_git:`GStreamer recipes
+      </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
+      It allows to build the GStreamer `"ugly"
+      <https://github.com/GStreamer/gst-plugins-ugly>`__  and
+      `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins.
+
+      See the ":ref:`dev-manual/licenses:other variables related to commercial licenses`"
+      section in the Development Tasks Manual for usage details.
+
+   :term:`COMMERCIAL_VIDEO_PLUGINS`
+      This variable is specific to the :yocto_git:`GStreamer recipes
+      </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
+      It allows to build the GStreamer `"ugly"
+      <https://github.com/GStreamer/gst-plugins-ugly>`__  and
+      `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins.
+
+      See the ":ref:`dev-manual/licenses:other variables related to commercial licenses`"
+      section in the Development Tasks Manual for usage details.
+
    :term:`COMMON_LICENSE_DIR`
       Points to ``meta/files/common-licenses`` in the
       :term:`Source Directory`, which is where generic license
-- 
2.37.2

Re: [docs] [PATCH] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[Quentin Schulz]

Hi Michael,

On 2/21/23 11:44, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> - Add COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables to the
>    variable index.
> - Clarify that these plugins are still open-source
> - Improve line width
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>   documentation/dev-manual/licenses.rst  | 30 +++++++++++++++-----------
>   documentation/ref-manual/variables.rst | 20 +++++++++++++++++
>   2 files changed, 37 insertions(+), 13 deletions(-)
> 
> diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst
> index 65914e5efe..54d3a2e5f1 100644
> --- a/documentation/dev-manual/licenses.rst
> +++ b/documentation/dev-manual/licenses.rst
> @@ -242,10 +242,8 @@ defined in the
>      COMMERCIAL_AUDIO_PLUGINS ?= ""
>      COMMERCIAL_VIDEO_PLUGINS ?= ""
>   
> -If you
> -want to enable these components, you can do so by making sure you have
> -statements similar to the following in your ``local.conf`` configuration
> -file::
> +If you want to enable these components, you can do so by making sure you have
> +statements similar to the following in your ``local.conf`` configuration file::
>   
>      COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
>          gst-plugins-ugly-mpegaudioparse"
> @@ -253,20 +251,26 @@ file::
>          gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
>      LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
>   
> -
> -Of course, you could also create a matching list for those
> -components using the more general "commercial" in the
> -:term:`LICENSE_FLAGS_ACCEPTED` variable, but that would also enable all
> -the other packages with :term:`LICENSE_FLAGS`
> +Of course, you could also create a matching list for those components using
> +the more general "commercial" in the :term:`LICENSE_FLAGS_ACCEPTED` variable,
> +but that would also enable all the other packages with :term:`LICENSE_FLAGS`
>   containing "commercial", which you may or may not want::
>   
>      LICENSE_FLAGS_ACCEPTED = "commercial"
>   
>   Specifying audio and video plugins as part of the
> -``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements
> -(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the
> -plugins or components into built images, thus adding support for media
> -formats or components.
> +:term:`COMMERCIAL_AUDIO_PLUGINS` and :term:`COMMERCIAL_VIDEO_PLUGINS` statements
> +(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the plugins or

s/with the/with/ or s/with the enabling/with the enabling of/

as "along with the enabling <smth>" feels wrong to me.

> +components into built images, thus adding support for media formats or
> +components.
> +
> +.. note::
> +
> +   GStreamer "ugly" and "bad" plugins are actually available through
> +   open source licenses. However, the "ugly" ones can be subject to software
> +   patents in some countries, making it necessary to pay licensing fees
> +   to distribute them. The "bad" ones are just unreliable and therefore

s/are just unreliable/are deemed unreliable/

Also mention that this isn't a choice of Yocto but rather gstreamer 
community's?

> +   should be used with care.
>   
>   Maintaining Open Source License Compliance During Your Product's Lifecycle
>   ==========================================================================
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 760c608bde..26215f679f 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -1313,6 +1313,26 @@ system and gives an overview of their function and contents.
>         optional at the distribution level, in case the hardware supports
>         Bluetooth but you do not ever intend to use it.
>   
> +   :term:`COMMERCIAL_AUDIO_PLUGINS`
> +      This variable is specific to the :yocto_git:`GStreamer recipes
> +      </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
> +      It allows to build the GStreamer `"ugly"
> +      <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >`__  and
> +      `"bad" <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >`__ audio plugins.
> +
> +      See the ":ref:`dev-manual/licenses:other variables related to commercial licenses`"
> +      section in the Development Tasks Manual for usage details.
> +
> +   :term:`COMMERCIAL_VIDEO_PLUGINS`
> +      This variable is specific to the :yocto_git:`GStreamer recipes
> +      </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
> +      It allows to build the GStreamer `"ugly"
> +      <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >`__  and
> +      `"bad" <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >`__ video plugins.
> +
> +      See the ":ref:`dev-manual/licenses:other variables related to commercial licenses`"
> +      section in the Development Tasks Manual for usage details.
> +

Please don't mention where to find the documentation if you link it. It 
allows to move the source across manuals without having to update the 
text, only the links.

If you want to point to a specific section of the paragraph about 
commercial licenses, maybe add a target in there? e.g.

.. _gstreamer-commercial-licenses:

Cheers,
Quentin

Re: [docs] [PATCH] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[Michael Opdenacker]

Hi Quentin,

Many thanks for the review!

On 21.02.23 at 13:01, Quentin Schulz wrote:
> -``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements
>> -(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the
>> -plugins or components into built images, thus adding support for media
>> -formats or components.
>> +:term:`COMMERCIAL_AUDIO_PLUGINS` and 
>> :term:`COMMERCIAL_VIDEO_PLUGINS` statements
>> +(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes 
>> the plugins or
>
> s/with the/with/ or s/with the enabling/with the enabling of/
>
> as "along with the enabling <smth>" feels wrong to me.


Right. I'll fix this. There were a few style issues in the existing 
text. I'll double check in other places.

>
>> +components into built images, thus adding support for media formats or
>> +components.
>> +
>> +.. note::
>> +
>> +   GStreamer "ugly" and "bad" plugins are actually available through
>> +   open source licenses. However, the "ugly" ones can be subject to 
>> software
>> +   patents in some countries, making it necessary to pay licensing fees
>> +   to distribute them. The "bad" ones are just unreliable and therefore
>
> s/are just unreliable/are deemed unreliable/
>
> Also mention that this isn't a choice of Yocto but rather gstreamer 
> community's?


Right, this makes sense. This was my text this time.

>
>> +   should be used with care.
>>     Maintaining Open Source License Compliance During Your Product's 
>> Lifecycle
>> ==========================================================================
>> diff --git a/documentation/ref-manual/variables.rst 
>> b/documentation/ref-manual/variables.rst
>> index 760c608bde..26215f679f 100644
>> --- a/documentation/ref-manual/variables.rst
>> +++ b/documentation/ref-manual/variables.rst
>> @@ -1313,6 +1313,26 @@ system and gives an overview of their function 
>> and contents.
>>         optional at the distribution level, in case the hardware 
>> supports
>>         Bluetooth but you do not ever intend to use it.
>>   +   :term:`COMMERCIAL_AUDIO_PLUGINS`
>> +      This variable is specific to the :yocto_git:`GStreamer recipes
>> + 
>> </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
>> +      It allows to build the GStreamer `"ugly"
>> + 
>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ 
>> >`__  and
>> +      `"bad" 
>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ 
>> >`__ audio plugins.
>> +
>> +      See the ":ref:`dev-manual/licenses:other variables related to 
>> commercial licenses`"
>> +      section in the Development Tasks Manual for usage details.
>> +
>> +   :term:`COMMERCIAL_VIDEO_PLUGINS`
>> +      This variable is specific to the :yocto_git:`GStreamer recipes
>> + 
>> </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
>> +      It allows to build the GStreamer `"ugly"
>> + 
>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ 
>> >`__  and
>> +      `"bad" 
>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ 
>> >`__ video plugins.
>> +
>> +      See the ":ref:`dev-manual/licenses:other variables related to 
>> commercial licenses`"
>> +      section in the Development Tasks Manual for usage details.
>> +
>
> Please don't mention where to find the documentation if you link it. 
> It allows to move the source across manuals without having to update 
> the text, only the links.
>
> If you want to point to a specific section of the paragraph about 
> commercial licenses, maybe add a target in there? e.g.
>
> .. _gstreamer-commercial-licenses:


Good idea. We have tons of references like that in the manual, but we 
could gradually update them.

Thanks again!
Cheers
Michael.

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

Re: [docs] [PATCH] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[Quentin Schulz]

Hi Michael,

On 2/21/23 13:57, Michael Opdenacker wrote:
> Hi Quentin,
> 
> Many thanks for the review!
> 
> On 21.02.23 at 13:01, Quentin Schulz wrote:
>> -``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements
>>> -(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the
>>> -plugins or components into built images, thus adding support for media
>>> -formats or components.
>>> +:term:`COMMERCIAL_AUDIO_PLUGINS` and 
>>> :term:`COMMERCIAL_VIDEO_PLUGINS` statements
>>> +(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes 
>>> the plugins or
>>
>> s/with the/with/ or s/with the enabling/with the enabling of/
>>
>> as "along with the enabling <smth>" feels wrong to me.
> 
> 
> Right. I'll fix this. There were a few style issues in the existing 
> text. I'll double check in other places.
> 
>>
>>> +components into built images, thus adding support for media formats or
>>> +components.
>>> +
>>> +.. note::
>>> +
>>> +   GStreamer "ugly" and "bad" plugins are actually available through
>>> +   open source licenses. However, the "ugly" ones can be subject to 
>>> software
>>> +   patents in some countries, making it necessary to pay licensing fees
>>> +   to distribute them. The "bad" ones are just unreliable and therefore
>>
>> s/are just unreliable/are deemed unreliable/
>>
>> Also mention that this isn't a choice of Yocto but rather gstreamer 
>> community's?
> 
> 
> Right, this makes sense. This was my text this time.
> 
>>
>>> +   should be used with care.
>>>     Maintaining Open Source License Compliance During Your Product's 
>>> Lifecycle
>>> ==========================================================================
>>> diff --git a/documentation/ref-manual/variables.rst 
>>> b/documentation/ref-manual/variables.rst
>>> index 760c608bde..26215f679f 100644
>>> --- a/documentation/ref-manual/variables.rst
>>> +++ b/documentation/ref-manual/variables.rst
>>> @@ -1313,6 +1313,26 @@ system and gives an overview of their function 
>>> and contents.
>>>         optional at the distribution level, in case the hardware 
>>> supports
>>>         Bluetooth but you do not ever intend to use it.
>>>   +   :term:`COMMERCIAL_AUDIO_PLUGINS`
>>> +      This variable is specific to the :yocto_git:`GStreamer recipes
>>> + 
>>> </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
>>> +      It allows to build the GStreamer `"ugly"
>>> + 
>>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >`__  and
>>> +      `"bad" 
>>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >`__ audio plugins.
>>> +
>>> +      See the ":ref:`dev-manual/licenses:other variables related to 
>>> commercial licenses`"
>>> +      section in the Development Tasks Manual for usage details.
>>> +
>>> +   :term:`COMMERCIAL_VIDEO_PLUGINS`
>>> +      This variable is specific to the :yocto_git:`GStreamer recipes
>>> + 
>>> </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
>>> +      It allows to build the GStreamer `"ugly"
>>> + 
>>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >`__  and
>>> +      `"bad" 
>>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >`__ video plugins.
>>> +
>>> +      See the ":ref:`dev-manual/licenses:other variables related to 
>>> commercial licenses`"
>>> +      section in the Development Tasks Manual for usage details.
>>> +
>>
>> Please don't mention where to find the documentation if you link it. 
>> It allows to move the source across manuals without having to update 
>> the text, only the links.
>>
>> If you want to point to a specific section of the paragraph about 
>> commercial licenses, maybe add a target in there? e.g.
>>
>> .. _gstreamer-commercial-licenses:
> 
> 
> Good idea. We have tons of references like that in the manual, but we 
> could gradually update them.
> 

Correct. And I'm now cursing myself for having updated some links to the 
sections and losing the exact location the old xml documentation was 
pointing at when I reviewed the xml to sphinx update. Specifically, we 
lost that for the QA section where everything is a list now and we have 
no automatic way for Sphinx to reference those items elsewhere (well, if 
I had known/thought about those manual targets... :) ).

More work for future me/us :)

Cheers,
Quentin

[PATCH v2] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

- Add COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables to the
  variable index.
- Clarify that these plugins are still open-source
- Improve line width

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>

---

Changes in V2:
- Style fixes
- Highlight that the "bad" status is according to GStreamer contributors
- Add a new "gstreamer-commercial-licenses" target so that we can refer
  to the modified section without hardcoding the title and the manual
  name in the reference. That's more resistant to changes.
According to the review from Quentin Schulz (thanks!)
---
 documentation/dev-manual/licenses.rst  | 32 +++++++++++++++-----------
 documentation/ref-manual/variables.rst | 18 +++++++++++++++
 2 files changed, 37 insertions(+), 13 deletions(-)

diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst
index 65914e5efe..91a2ebce81 100644
--- a/documentation/dev-manual/licenses.rst
+++ b/documentation/dev-manual/licenses.rst
@@ -232,6 +232,8 @@ Here are some other scenarios:
    in the :term:`LICENSE_FLAGS_ACCEPTED` list (e.g.
    "commercial_foo_1.2") to specifically match a versioned recipe.
 
+.. _gstreamer-commercial-licenses:
+
 Other Variables Related to Commercial Licenses
 ----------------------------------------------
 
@@ -242,10 +244,8 @@ defined in the
    COMMERCIAL_AUDIO_PLUGINS ?= ""
    COMMERCIAL_VIDEO_PLUGINS ?= ""
 
-If you
-want to enable these components, you can do so by making sure you have
-statements similar to the following in your ``local.conf`` configuration
-file::
+If you want to enable these components, you can do so by making sure you have
+statements similar to the following in your ``local.conf`` configuration file::
 
    COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
        gst-plugins-ugly-mpegaudioparse"
@@ -253,20 +253,26 @@ file::
        gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
    LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
 
-
-Of course, you could also create a matching list for those
-components using the more general "commercial" in the
-:term:`LICENSE_FLAGS_ACCEPTED` variable, but that would also enable all
-the other packages with :term:`LICENSE_FLAGS`
+Of course, you could also create a matching list for those components using the
+more general "commercial" string in the :term:`LICENSE_FLAGS_ACCEPTED` variable,
+but that would also enable all the other packages with :term:`LICENSE_FLAGS`
 containing "commercial", which you may or may not want::
 
    LICENSE_FLAGS_ACCEPTED = "commercial"
 
 Specifying audio and video plugins as part of the
-``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements
-(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the
-plugins or components into built images, thus adding support for media
-formats or components.
+:term:`COMMERCIAL_AUDIO_PLUGINS` and :term:`COMMERCIAL_VIDEO_PLUGINS` statements
+(along with :term:`LICENSE_FLAGS_ACCEPTED`) includes the plugins or
+components into built images, thus adding support for media formats or
+components.
+
+.. note::
+
+   GStreamer "ugly" and "bad" plugins are actually available through
+   open source licenses. However, the "ugly" ones can be subject to software
+   patents in some countries, making it necessary to pay licensing fees
+   to distribute them. The "bad" ones are just deemed unreliable by the
+   GStreamer community and should therefore be used with care.
 
 Maintaining Open Source License Compliance During Your Product's Lifecycle
 ==========================================================================
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 760c608bde..1848791938 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1313,6 +1313,24 @@ system and gives an overview of their function and contents.
       optional at the distribution level, in case the hardware supports
       Bluetooth but you do not ever intend to use it.
 
+   :term:`COMMERCIAL_AUDIO_PLUGINS`
+      This variable is specific to the :yocto_git:`GStreamer recipes
+      </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
+      It allows to build the GStreamer `"ugly"
+      <https://github.com/GStreamer/gst-plugins-ugly>`__  and
+      `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins.
+
+      See the :ref:`gstreamer-commercial-licenses` section for usage details.
+
+   :term:`COMMERCIAL_VIDEO_PLUGINS`
+      This variable is specific to the :yocto_git:`GStreamer recipes
+      </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
+      It allows to build the GStreamer `"ugly"
+      <https://github.com/GStreamer/gst-plugins-ugly>`__  and
+      `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins.
+
+      See the :ref:`gstreamer-commercial-licenses` section for usage details.
+
    :term:`COMMON_LICENSE_DIR`
       Points to ``meta/files/common-licenses`` in the
       :term:`Source Directory`, which is where generic license
-- 
2.37.2

Re: [docs] [PATCH v2] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[Quentin Schulz]

Hi Michael,

On 2/21/23 19:41, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> - Add COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables to the
>    variable index.
> - Clarify that these plugins are still open-source
> - Improve line width
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> ---
> 
> Changes in V2:
> - Style fixes
> - Highlight that the "bad" status is according to GStreamer contributors
> - Add a new "gstreamer-commercial-licenses" target so that we can refer
>    to the modified section without hardcoding the title and the manual
>    name in the reference. That's more resistant to changes.
> According to the review from Quentin Schulz (thanks!)
> ---
>   documentation/dev-manual/licenses.rst  | 32 +++++++++++++++-----------
>   documentation/ref-manual/variables.rst | 18 +++++++++++++++
>   2 files changed, 37 insertions(+), 13 deletions(-)
> 
> diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst
> index 65914e5efe..91a2ebce81 100644
> --- a/documentation/dev-manual/licenses.rst
> +++ b/documentation/dev-manual/licenses.rst
> @@ -232,6 +232,8 @@ Here are some other scenarios:
>      in the :term:`LICENSE_FLAGS_ACCEPTED` list (e.g.
>      "commercial_foo_1.2") to specifically match a versioned recipe.
>   
> +.. _gstreamer-commercial-licenses:
> +

My bad, I thought there were more examples, unrelated to GStreamer, in 
the "Other Variables Related to Commercial Licenses" section. But here I 
don't think it makes much sense to add this target actually since we 
already have some automatically added by sphinx for sections/subsections.

Otherwise,
Reviewed-by: Quentin Schulz <foss+yocto@0leil.net>

Cheers,
Quentin

Re: [docs] [PATCH v2] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[Michael Opdenacker]

Hi Quentin,

On 22.02.23 at 14:49, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Michael,
>
> On 2/21/23 19:41, Michael Opdenacker via lists.yoctoproject.org wrote:
>> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>
>> - Add COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables to the
>>    variable index.
>> - Clarify that these plugins are still open-source
>> - Improve line width
>>
>> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>
>> ---
>>
>> Changes in V2:
>> - Style fixes
>> - Highlight that the "bad" status is according to GStreamer contributors
>> - Add a new "gstreamer-commercial-licenses" target so that we can refer
>>    to the modified section without hardcoding the title and the manual
>>    name in the reference. That's more resistant to changes.
>> According to the review from Quentin Schulz (thanks!)
>> ---
>>   documentation/dev-manual/licenses.rst  | 32 +++++++++++++++-----------
>>   documentation/ref-manual/variables.rst | 18 +++++++++++++++
>>   2 files changed, 37 insertions(+), 13 deletions(-)
>>
>> diff --git a/documentation/dev-manual/licenses.rst 
>> b/documentation/dev-manual/licenses.rst
>> index 65914e5efe..91a2ebce81 100644
>> --- a/documentation/dev-manual/licenses.rst
>> +++ b/documentation/dev-manual/licenses.rst
>> @@ -232,6 +232,8 @@ Here are some other scenarios:
>>      in the :term:`LICENSE_FLAGS_ACCEPTED` list (e.g.
>>      "commercial_foo_1.2") to specifically match a versioned recipe.
>>   +.. _gstreamer-commercial-licenses:
>> +
>
> My bad, I thought there were more examples, unrelated to GStreamer, in 
> the "Other Variables Related to Commercial Licenses" section. But here 
> I don't think it makes much sense to add this target actually since we 
> already have some automatically added by sphinx for sections/subsections.
>
> Otherwise,
> Reviewed-by: Quentin Schulz <foss+yocto@0leil.net>


I'm not sure I understand, because the idea to use references to targets 
without referring to the document name made sense to me.

Here's a V3 anyway, that may help clarify any misunderstanding.

Thanks
Michael.

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

Re: [docs] [PATCH v2] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[Quentin Schulz]

Hi Michael,

On 2/23/23 10:57, Michael Opdenacker wrote:
> Hi Quentin,
> 
> On 22.02.23 at 14:49, Quentin Schulz via lists.yoctoproject.org wrote:
>> Hi Michael,
>>
>> On 2/21/23 19:41, Michael Opdenacker via lists.yoctoproject.org wrote:
>>> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>>
>>> - Add COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables to the
>>>    variable index.
>>> - Clarify that these plugins are still open-source
>>> - Improve line width
>>>
>>> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>>
>>> ---
>>>
>>> Changes in V2:
>>> - Style fixes
>>> - Highlight that the "bad" status is according to GStreamer contributors
>>> - Add a new "gstreamer-commercial-licenses" target so that we can refer
>>>    to the modified section without hardcoding the title and the manual
>>>    name in the reference. That's more resistant to changes.
>>> According to the review from Quentin Schulz (thanks!)
>>> ---
>>>   documentation/dev-manual/licenses.rst  | 32 +++++++++++++++-----------
>>>   documentation/ref-manual/variables.rst | 18 +++++++++++++++
>>>   2 files changed, 37 insertions(+), 13 deletions(-)
>>>
>>> diff --git a/documentation/dev-manual/licenses.rst 
>>> b/documentation/dev-manual/licenses.rst
>>> index 65914e5efe..91a2ebce81 100644
>>> --- a/documentation/dev-manual/licenses.rst
>>> +++ b/documentation/dev-manual/licenses.rst
>>> @@ -232,6 +232,8 @@ Here are some other scenarios:
>>>      in the :term:`LICENSE_FLAGS_ACCEPTED` list (e.g.
>>>      "commercial_foo_1.2") to specifically match a versioned recipe.
>>>   +.. _gstreamer-commercial-licenses:
>>> +
>>
>> My bad, I thought there were more examples, unrelated to GStreamer, in 
>> the "Other Variables Related to Commercial Licenses" section. But here 
>> I don't think it makes much sense to add this target actually since we 
>> already have some automatically added by sphinx for sections/subsections.
>>
>> Otherwise,
>> Reviewed-by: Quentin Schulz <foss+yocto@0leil.net>
> 
> 
> I'm not sure I understand, because the idea to use references to targets 
> without referring to the document name made sense to me.
> 

What would be the use for the autogeneration of sphinx targets from 
sphinx sections if we have some sections with additional manual targets?

What I wanted to use manual targets for is for pointing at content 
**within** a Sphinx section. e.g. 
https://docs.yoctoproject.org/3.1.23/ref-manual/faq.html. We could have 
had a target for each Q: line for example instead of migrating to 
sections and subsections like we did recently (c.f. what's in langdale).

Hope I explained myself a bit better this time :)

Cheers,
Quentin

Re: [docs] [PATCH v2] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables

[Michael Opdenacker]

Hi Quentin,

On 23.02.23 at 11:27, Quentin Schulz via lists.yoctoproject.org wrote:
> What would be the use for the autogeneration of sphinx targets from 
> sphinx sections if we have some sections with additional manual targets?
>
> What I wanted to use manual targets for is for pointing at content 
> **within** a Sphinx section. e.g. 
> https://docs.yoctoproject.org/3.1.23/ref-manual/faq.html. We could 
> have had a target for each Q: line for example instead of migrating to 
> sections and subsections like we did recently (c.f. what's in langdale).
>
> Hope I explained myself a bit better this time :)


Good idea. It think I got it this time :-D
Thanks
Michael.

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