[PATCH] doc: bitbake-user-manual: fix syntax in example and improve description

[PATCH] doc: bitbake-user-manual: fix syntax in example and improve description

[Michael Opdenacker]

The previous syntax of the example was clearly incorrect
The example and description were also ambiguous, one could think that
it was "bitbake recipe" instead of "bitbake <recipename>"

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 20c330e6..01ac4d5e 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -91,9 +91,10 @@ level changes:
       Variables that are exported to the environment are preceded by the
       string "export" in the command's output.
 
--  For recipe changes, use the following::
+-  To find changes to a given variable in a specific recipe, use the
+   following::
 
-      $ bitbake recipe -e \| grep VARIABLE="
+      $ bitbake recipename -e | grep VARIABLENAME=\"
 
    This command checks to see if the variable actually makes
    it into a specific recipe.
-- 
2.25.1

Re: [bitbake-devel] [PATCH] doc: bitbake-user-manual: fix syntax in example and improve description

[Richard Purdie]

Hi Michael,

On Thu, 2021-07-22 at 19:10 +0200, Michael Opdenacker wrote:
> The previous syntax of the example was clearly incorrect
> The example and description were also ambiguous, one could think that
> it was "bitbake recipe" instead of "bitbake <recipename>"
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>  doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index 20c330e6..01ac4d5e 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -91,9 +91,10 @@ level changes:
>        Variables that are exported to the environment are preceded by the
>        string "export" in the command's output.
>  
> 
> 
> 
> --  For recipe changes, use the following::
> +-  To find changes to a given variable in a specific recipe, use the
> +   following::
>  
> 
> 
> 
> -      $ bitbake recipe -e \| grep VARIABLE="
> +      $ bitbake recipename -e | grep VARIABLENAME=\"
>  
> 
> 
> 
>     This command checks to see if the variable actually makes
>     it into a specific recipe.



I should probably highlight there is a new command, "bitbake-getvar":

http://git.yoctoproject.org/cgit.cgi/poky/commit/?id=7bbeddeee1992d8c8fb71ba2dd49b03d0ae1ce86

We probably want to document that.

Whilst I'm thinking about it, the override discussions on the architecture list
are going to have implications for documentation too.

http://git.yoctoproject.org/cgit.cgi/poky/commit/?id=75fad23fc06c008a03414a1fc288a8614c6af9ca

An example of my scripted conversion run against the manuals is included
in this commit:

http://git.yoctoproject.org/cgit.cgi/poky-contrib/diff/documentation/ref-manual/variables.rst?h=rpurdie/overrides-convert&id=9ac22a64a4c0ac4640552e90674e6459f0fece9a



Cheers,

Richard

Re: [docs] [bitbake-devel] [PATCH] doc: bitbake-user-manual: fix syntax in example and improve description

[Michael Opdenacker]

Hi Richard,

On 7/23/21 12:14 AM, Richard Purdie wrote:
> I should probably highlight there is a new command, "bitbake-getvar":
>
> http://git.yoctoproject.org/cgit.cgi/poky/commit/?id=7bbeddeee1992d8c8fb71ba2dd49b03d0ae1ce86
>
> We probably want to document that.


Sure, this sounds like a very good idea indeed. I'll take care of that.

>
> Whilst I'm thinking about it, the override discussions on the architecture list
> are going to have implications for documentation too.
>
> http://git.yoctoproject.org/cgit.cgi/poky/commit/?id=75fad23fc06c008a03414a1fc288a8614c6af9ca


Of course! I was wondering when we are supposed to start updating the
documentation. Probably right now, indeed, right?

>
> An example of my scripted conversion run against the manuals is included
> in this commit:
>
> http://git.yoctoproject.org/cgit.cgi/poky-contrib/diff/documentation/ref-manual/variables.rst?h=rpurdie/overrides-convert&id=9ac22a64a4c0ac4640552e90674e6459f0fece9a

Where can I find the script (or commands) that you used to modify the
documentation?

Thanks,
Michael.

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

Re: [docs] [bitbake-devel] [PATCH] doc: bitbake-user-manual: fix syntax in example and improve description

[Michael Opdenacker]

Hi Richard,

On 7/23/21 10:35 AM, Michael Opdenacker wrote:
>
> Of course! I was wondering when we are supposed to start updating the
> documentation. Probably right now, indeed, right?
>
>> An example of my scripted conversion run against the manuals is included
>> in this commit:
>>
>> http://git.yoctoproject.org/cgit.cgi/poky-contrib/diff/documentation/ref-manual/variables.rst?h=rpurdie/overrides-convert&id=9ac22a64a4c0ac4640552e90674e6459f0fece9a
> Where can I find the script (or commands) that you used to modify the
> documentation?

I found your script from patch messages
(http://git.yoctoproject.org/cgit.cgi/poky-contrib/commit/?h=rpurdie/overrides-convert&id=f7c5c3bbb9bc5d4c4c8f798d64a020a4504542df),
and it seems to do the job fine. I just had to exclude the migration
guides, but that's easy to do it manually.

How shall I proceed? Shall I send a big patch to
docs@lists.yoctoproject.org for people to review and check that the
output from your script is right?

Thanks in advance
Michael.

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

Re: [docs] [bitbake-devel] [PATCH] doc: bitbake-user-manual: fix syntax in example and improve description

[Richard Purdie]

On Fri, 2021-07-23 at 10:35 +0200, Michael Opdenacker wrote:
> Hi Richard,
> 
> On 7/23/21 12:14 AM, Richard Purdie wrote:
> > I should probably highlight there is a new command, "bitbake-getvar":
> > 
> > http://git.yoctoproject.org/cgit.cgi/poky/commit/?id=7bbeddeee1992d8c8fb71ba2dd49b03d0ae1ce86
> > 
> > We probably want to document that.
> 
> 
> Sure, this sounds like a very good idea indeed. I'll take care of that.

Thanks.

> > Whilst I'm thinking about it, the override discussions on the architecture list
> > are going to have implications for documentation too.
> > 
> > http://git.yoctoproject.org/cgit.cgi/poky/commit/?id=75fad23fc06c008a03414a1fc288a8614c6af9ca
> 
> 
> Of course! I was wondering when we are supposed to start updating the
> documentation. Probably right now, indeed, right?

I think we need to get final approval on what we're converting on the
openembedded-architecture list, then we can start.

> > An example of my scripted conversion run against the manuals is included
> > in this commit:
> > 
> > http://git.yoctoproject.org/cgit.cgi/poky-contrib/diff/documentation/ref-manual/variables.rst?h=rpurdie/overrides-convert&id=9ac22a64a4c0ac4640552e90674e6459f0fece9a
> 
> Where can I find the script (or commands) that you used to modify the
> documentation?

It was done with a script in the same tree:

http://git.yoctoproject.org/cgit.cgi/poky-contrib/commit/?h=rpurdie/overrides-convert&id=f7c5c3bbb9bc5d4c4c8f798d64a020a4504542df

Not pretty or efficient but does roughly what we need. I'm still working on it
with some build tests on master-next to see how close this is to working.

The main issue is the script doesn't spot some manual/docs specific example 
overrides.

Cheers,

Richard

Re: [docs] [bitbake-devel] [PATCH] doc: bitbake-user-manual: fix syntax in example and improve description

[Richard Purdie]

On Mon, 2021-07-26 at 17:44 +0200, Michael Opdenacker wrote:
> Hi Richard,
> 
> On 7/23/21 10:35 AM, Michael Opdenacker wrote:
> > 
> > Of course! I was wondering when we are supposed to start updating the
> > documentation. Probably right now, indeed, right?
> > 
> > > An example of my scripted conversion run against the manuals is included
> > > in this commit:
> > > 
> > > http://git.yoctoproject.org/cgit.cgi/poky-contrib/diff/documentation/ref-manual/variables.rst?h=rpurdie/overrides-convert&id=9ac22a64a4c0ac4640552e90674e6459f0fece9a
> > Where can I find the script (or commands) that you used to modify the
> > documentation?
> 
> I found your script from patch messages
> (http://git.yoctoproject.org/cgit.cgi/poky-contrib/commit/?h=rpurdie/overrides-convert&id=f7c5c3bbb9bc5d4c4c8f798d64a020a4504542df),
> and it seems to do the job fine. I just had to exclude the migration
> guides, but that's easy to do it manually.

Sounds good and yes, we can just exclude those paths (we could even do that
in the script).

> How shall I proceed? Shall I send a big patch to
> docs@lists.yoctoproject.org for people to review and check that the
> output from your script is right?

We need to get final approval on exactly what we're converting, then yes.
I wanted to ensure you knew this was coming! :)

I'd note there are some _arc overrides in the docs as there as in the metadata
which need manually tweaking. I also spotted some _sh4. Those are rather obscure
and we may want to use a more common example anyway?

Cheers,

Richard