[PATCH] bitbake-user-manual: Correct description of the ??= operator

[PATCH] bitbake-user-manual: Correct description of the ??= operator

[Jacob Kroon]

Signed-off-by: Jacob Kroon <jacob.kroon@gmail.com>
---
 .../bitbake-user-manual-metadata.rst          | 31 +++++++++----------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index af4b1358..1c146f0f 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -195,22 +195,21 @@ value. However, if ``A`` is not set, the variable is set to "aval".
 Setting a weak default value (??=)
 ----------------------------------
 
-It is possible to use a "weaker" assignment than in the previous section
-by using the "??=" operator. This assignment behaves identical to "?="
-except that the assignment is made at the end of the parsing process
-rather than immediately. Consequently, when multiple "??=" assignments
-exist, the last one is used. Also, any "=" or "?=" assignment will
-override the value set with "??=". Here is an example::
-
-   A ??= "somevalue"
-   A ??= "someothervalue"
-
-If ``A`` is set before the above statements are
-parsed, the variable retains its value. If ``A`` is not set, the
-variable is set to "someothervalue".
-
-Again, this assignment is a "lazy" or "weak" assignment because it does
-not occur until the end of the parsing process.
+The weak default value of a variable is the value which that variable
+will expand to if no value has been assigned to it via one of the other
+assignment operators. Here is an example::
+
+   W ??= "x"
+   A := "${W}"
+   W ??= "y"
+   B = "${W}"
+   W ?= "z"
+
+After parsing we will have::
+
+   A = "x"
+   B = "z"
+   W = "z"
 
 Immediate variable expansion (:=)
 ---------------------------------

Re: [bitbake-devel] [PATCH] bitbake-user-manual: Correct description of the ??= operator

[Pavel Zhukov]

IMO the example with ":=" should go under "immediately variable expantion" section.
The change mentions operator which has not been
described earlier and this may be confusing for the person who reads the
manual for the first time.

-- Pavel

"Jacob Kroon" <jacob.kroon@gmail.com> writes:

> Signed-off-by: Jacob Kroon <jacob.kroon@gmail.com>
> ---
>  .../bitbake-user-manual-metadata.rst          | 31 +++++++++----------
>  1 file changed, 15 insertions(+), 16 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index af4b1358..1c146f0f 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -195,22 +195,21 @@ value. However, if ``A`` is not set, the variable is set to "aval".
>  Setting a weak default value (??=)
>  ----------------------------------
>  
> -It is possible to use a "weaker" assignment than in the previous section
> -by using the "??=" operator. This assignment behaves identical to "?="
> -except that the assignment is made at the end of the parsing process
> -rather than immediately. Consequently, when multiple "??=" assignments
> -exist, the last one is used. Also, any "=" or "?=" assignment will
> -override the value set with "??=". Here is an example::
> -
> -   A ??= "somevalue"
> -   A ??= "someothervalue"
> -
> -If ``A`` is set before the above statements are
> -parsed, the variable retains its value. If ``A`` is not set, the
> -variable is set to "someothervalue".
> -
> -Again, this assignment is a "lazy" or "weak" assignment because it does
> -not occur until the end of the parsing process.
> +The weak default value of a variable is the value which that variable
> +will expand to if no value has been assigned to it via one of the other
> +assignment operators. Here is an example::
> +
> +   W ??= "x"
> +   A := "${W}"
> +   W ??= "y"
> +   B = "${W}"
> +   W ?= "z"
> +
> +After parsing we will have::
> +
> +   A = "x"
> +   B = "z"
> +   W = "z"
>  
>  Immediate variable expansion (:=)
>  ---------------------------------
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#13728): https://lists.openembedded.org/g/bitbake-devel/message/13728
> Mute This Topic: https://lists.openembedded.org/mt/91517826/6390638
> Group Owner: bitbake-devel+owner@lists.openembedded.org
> Unsubscribe: https://lists.openembedded.org/g/bitbake-devel/unsub [pavel@zhukoff.net]
> -=-=-=-=-=-=-=-=-=-=-=-

Re: [bitbake-devel] [PATCH] bitbake-user-manual: Correct description of the ??= operator

[Jacob Kroon]

On 6/3/22 12:16, Pavel Zhukov wrote:
> 
> IMO the example with ":=" should go under "immediately variable expantion" section.
> The change mentions operator which has not been
> described earlier and this may be confusing for the person who reads the
> manual for the first time.
> 

I see you what you mean, but I'd say it is ok to use syntax that has not 
yet been described in examples, otherwise it would be difficult to give 
examples. And I can't move an example that is supposed to demonstrate 
how "??=" works to a completely different operator description. But 
maybe I could add a comment in the example like:

A := "${W}" # Immediate variable expansion

Jacob

> -- Pavel
> 
> "Jacob Kroon" <jacob.kroon@gmail.com> writes:
> 
>> Signed-off-by: Jacob Kroon <jacob.kroon@gmail.com>
>> ---
>>   .../bitbake-user-manual-metadata.rst          | 31 +++++++++----------
>>   1 file changed, 15 insertions(+), 16 deletions(-)
>>
>> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
>> index af4b1358..1c146f0f 100644
>> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
>> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
>> @@ -195,22 +195,21 @@ value. However, if ``A`` is not set, the variable is set to "aval".
>>   Setting a weak default value (??=)
>>   ----------------------------------
>>   
>> -It is possible to use a "weaker" assignment than in the previous section
>> -by using the "??=" operator. This assignment behaves identical to "?="
>> -except that the assignment is made at the end of the parsing process
>> -rather than immediately. Consequently, when multiple "??=" assignments
>> -exist, the last one is used. Also, any "=" or "?=" assignment will
>> -override the value set with "??=". Here is an example::
>> -
>> -   A ??= "somevalue"
>> -   A ??= "someothervalue"
>> -
>> -If ``A`` is set before the above statements are
>> -parsed, the variable retains its value. If ``A`` is not set, the
>> -variable is set to "someothervalue".
>> -
>> -Again, this assignment is a "lazy" or "weak" assignment because it does
>> -not occur until the end of the parsing process.
>> +The weak default value of a variable is the value which that variable
>> +will expand to if no value has been assigned to it via one of the other
>> +assignment operators. Here is an example::
>> +
>> +   W ??= "x"
>> +   A := "${W}"
>> +   W ??= "y"
>> +   B = "${W}"
>> +   W ?= "z"
>> +
>> +After parsing we will have::
>> +
>> +   A = "x"
>> +   B = "z"
>> +   W = "z"
>>   
>>   Immediate variable expansion (:=)
>>   ---------------------------------
>>
>>
>> -=-=-=-=-=-=-=-=-=-=-=-
>> Links: You receive all messages sent to this group.
>> View/Reply Online (#13728): https://lists.openembedded.org/g/bitbake-devel/message/13728
>> Mute This Topic: https://lists.openembedded.org/mt/91517826/6390638
>> Group Owner: bitbake-devel+owner@lists.openembedded.org
>> Unsubscribe: https://lists.openembedded.org/g/bitbake-devel/unsub [pavel@zhukoff.net]
>> -=-=-=-=-=-=-=-=-=-=-=-
>