[Webhob] updating documentation.conf

[Webhob] updating documentation.conf

[Barros Pena, Belen]

Web Hob will provide information about build configuration, including a
table of variable / value pairs. We would like to provide a short
description of those variables, and the easiest way to do that is adding
such descriptions to documentation.conf.

Currently, documentation.conf is loosely structured in thematic sections
(things like "conf/bitbake.conf", "dependencies", "packaging", etc). My
question is, can I get rid of those sections and just organise the
document alphabetically?

Thanks,

Belén

---------------------------------------------------------------------
Intel Corporation (UK) Limited
Registered No. 1134945 (England)
Registered Office: Pipers Way, Swindon SN3 1RJ
VAT No: 860 2173 47

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.

Re: [Webhob] updating documentation.conf

[Richard Purdie]

On Wed, 2013-08-14 at 10:40 +0000, Barros Pena, Belen wrote:
> Web Hob will provide information about build configuration, including a
> table of variable / value pairs. We would like to provide a short
> description of those variables, and the easiest way to do that is adding
> such descriptions to documentation.conf.
> 
> Currently, documentation.conf is loosely structured in thematic sections
> (things like "conf/bitbake.conf", "dependencies", "packaging", etc). My
> question is, can I get rid of those sections and just organise the
> document alphabetically?

I'm fully in favour of updating this file. If the current ordering
doesn't make sense, that can change.

Cheers,

Richard

Re: [Webhob] updating documentation.conf

[Barros Pena, Belen]

The information I added to documentation.conf is now showing up in Web Hob
(thanks, Alex!).

Looking at it, it seems that the description is not picked up for
variables with a suffix (things like PREFERRED_PROVIDER_xyz). Could that
be fixed? Do you want an issue in Bugzilla for this?

Belen



On 16/08/2013 11:24, "Richard Purdie" <richard.purdie@linuxfoundation.org>
wrote:

>On Wed, 2013-08-14 at 10:40 +0000, Barros Pena, Belen wrote:
>> Web Hob will provide information about build configuration, including a
>> table of variable / value pairs. We would like to provide a short
>> description of those variables, and the easiest way to do that is adding
>> such descriptions to documentation.conf.
>> 
>> Currently, documentation.conf is loosely structured in thematic sections
>> (things like "conf/bitbake.conf", "dependencies", "packaging", etc). My
>> question is, can I get rid of those sections and just organise the
>> document alphabetically?
>
>I'm fully in favour of updating this file. If the current ordering
>doesn't make sense, that can change.
>
>Cheers,
>
>Richard
>

---------------------------------------------------------------------
Intel Corporation (UK) Limited
Registered No. 1134945 (England)
Registered Office: Pipers Way, Swindon SN3 1RJ
VAT No: 860 2173 47

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.

Re: [Webhob] updating documentation.conf

[Damian, Alexandru]

[-- Attachment #1: Type: text/plain, Size: 2136 bytes --]

not sure how this should be handled, Paul thinks it should be in there ?

AFAIK, suffixed variables get used instead of the normal ones, so they are
more like replacements.
I guess the design ask that we should the only the variables with doc
attached, so they would be hidden.


Isn't this the case ?


On Wed, Aug 21, 2013 at 4:51 PM, Barros Pena, Belen <
belen.barros.pena@intel.com> wrote:

> The information I added to documentation.conf is now showing up in Web Hob
> (thanks, Alex!).
>
> Looking at it, it seems that the description is not picked up for
> variables with a suffix (things like PREFERRED_PROVIDER_xyz). Could that
> be fixed? Do you want an issue in Bugzilla for this?
>
> Belen
>
>
>
> On 16/08/2013 11:24, "Richard Purdie" <richard.purdie@linuxfoundation.org>
> wrote:
>
> >On Wed, 2013-08-14 at 10:40 +0000, Barros Pena, Belen wrote:
> >> Web Hob will provide information about build configuration, including a
> >> table of variable / value pairs. We would like to provide a short
> >> description of those variables, and the easiest way to do that is adding
> >> such descriptions to documentation.conf.
> >>
> >> Currently, documentation.conf is loosely structured in thematic sections
> >> (things like "conf/bitbake.conf", "dependencies", "packaging", etc). My
> >> question is, can I get rid of those sections and just organise the
> >> document alphabetically?
> >
> >I'm fully in favour of updating this file. If the current ordering
> >doesn't make sense, that can change.
> >
> >Cheers,
> >
> >Richard
> >
>
> ---------------------------------------------------------------------
> Intel Corporation (UK) Limited
> Registered No. 1134945 (England)
> Registered Office: Pipers Way, Swindon SN3 1RJ
> VAT No: 860 2173 47
>
> This e-mail and any attachments may contain confidential material for
> the sole use of the intended recipient(s). Any review or distribution
> by others is strictly prohibited. If you are not the intended
> recipient, please contact the sender and delete all copies.
>



-- 
Alex Damian
Yocto Project
SSG / OTC

[-- Attachment #2: Type: text/html, Size: 2932 bytes --]

Re: [Webhob] updating documentation.conf

[Paul Eggleton]

On Thursday 22 August 2013 16:02:05 Damian, Alexandru wrote:
> On Wed, Aug 21, 2013 at 4:51 PM, Barros Pena, Belen <
> belen.barros.pena@intel.com> wrote:
> > The information I added to documentation.conf is now showing up in Web Hob
> > (thanks, Alex!).
> > 
> > Looking at it, it seems that the description is not picked up for
> > variables with a suffix (things like PREFERRED_PROVIDER_xyz). Could that
> > be fixed? Do you want an issue in Bugzilla for this?
>
> not sure how this should be handled, Paul thinks it should be in there ?
> 
> AFAIK, suffixed variables get used instead of the normal ones, so they are
> more like replacements.
> I guess the design ask that we should the only the variables with doc
> attached, so they would be hidden.
> 
> Isn't this the case ?

I think that variables like PREFERRED_PROVIDER are kind of a special case - 
their overrides will never be in OVERRIDES except when bitbake is reading from 
them. If we want to show them in the variables list then we might have to 
handle them specially (or just do something like cut the variable name back to 
the last capital letter in order to look up the doc flag).

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: [Webhob] updating documentation.conf

[Barros Pena, Belen]

On 22/08/2013 16:02, "Damian, Alexandru" <alexandru.damian@intel.com>
wrote:

>not sure how this should be handled, Paul thinks it should be in there ?
>
>
>AFAIK, suffixed variables get used instead of the normal ones, so they
>are more like replacements.
>
>I guess the design ask that we should the only the variables with doc
>attached,

Well Š no :) 

The design actually asked nothing, since it is still very much in the
works. My request to the team was in the lines of: can we provide a short
explanation of the variables we show? When trying to work out how to
actually do this, we were suggested to use documentation.conf to provide
such explanations. This is quite different from saying "show variables
with the [doc] flag".

> so they would be hidden.
>
>
>
>Isn't this the case ?
>
>
>
>On Wed, Aug 21, 2013 at 4:51 PM, Barros Pena, Belen
><belen.barros.pena@intel.com> wrote:
>
>The information I added to documentation.conf is now showing up in Web Hob
>(thanks, Alex!).
>
>Looking at it, it seems that the description is not picked up for
>variables with a suffix (things like PREFERRED_PROVIDER_xyz). Could that
>be fixed? Do you want an issue in Bugzilla for this?
>
>Belen
>
>
>
>On 16/08/2013 11:24, "Richard Purdie" <richard.purdie@linuxfoundation.org>
>wrote:
>
>>On Wed, 2013-08-14 at 10:40 +0000, Barros Pena, Belen wrote:
>>> Web Hob will provide information about build configuration, including a
>>> table of variable / value pairs. We would like to provide a short
>>> description of those variables, and the easiest way to do that is
>>>adding
>>> such descriptions to documentation.conf.
>>>
>>> Currently, documentation.conf is loosely structured in thematic
>>>sections
>>> (things like "conf/bitbake.conf", "dependencies", "packaging", etc). My
>>> question is, can I get rid of those sections and just organise the
>>> document alphabetically?
>>
>>I'm fully in favour of updating this file. If the current ordering
>>doesn't make sense, that can change.
>>
>>Cheers,
>>
>>Richard
>>
>
>
>
>---------------------------------------------------------------------
>Intel Corporation (UK) Limited
>Registered No. 1134945 (England)
>Registered Office: Pipers Way, Swindon SN3 1RJ
>VAT No: 860 2173 47
>
>This e-mail and any attachments may contain confidential material for
>the sole use of the intended recipient(s). Any review or distribution
>by others is strictly prohibited. If you are not the intended
>recipient, please contact the sender and delete all copies.
>
>
>
>
>
>
>
>
>-- 
>Alex Damian
>Yocto Project
>
>SSG / OTC 
>
>

---------------------------------------------------------------------
Intel Corporation (UK) Limited
Registered No. 1134945 (England)
Registered Office: Pipers Way, Swindon SN3 1RJ
VAT No: 860 2173 47

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.

Re: [Webhob] updating documentation.conf

[Richard Purdie]

On Thu, 2013-08-22 at 15:40 +0000, Barros Pena, Belen wrote:
> 
> On 22/08/2013 16:02, "Damian, Alexandru" <alexandru.damian@intel.com>
> wrote:
> 
> >not sure how this should be handled, Paul thinks it should be in there ?
> >
> >
> >AFAIK, suffixed variables get used instead of the normal ones, so they
> >are more like replacements.
> >
> >I guess the design ask that we should the only the variables with doc
> >attached,
> 
> Well Š no :) 
> 
> The design actually asked nothing, since it is still very much in the
> works. My request to the team was in the lines of: can we provide a short
> explanation of the variables we show? When trying to work out how to
> actually do this, we were suggested to use documentation.conf to provide
> such explanations. This is quite different from saying "show variables
> with the [doc] flag".

PREFERRED_PROVIDER is perhaps a special case since it will usually have
a suffix and we're not going to add a [doc] tag for every single one.
Special casing that one in the code may make sense.

Are there any other suffixed variables that are causing similar
problems?

I suspect Paul's proposal of knocking off the lowercase suffixes and
seeing if a [doc] tag exists might be the best/only way to attempt to
handle this.

Cheers,

Richard

Re: [Webhob] updating documentation.conf

[Barros Pena, Belen]

On 22/08/2013 18:11, "Richard Purdie" <richard.purdie@linuxfoundation.org>
wrote:

>On Thu, 2013-08-22 at 15:40 +0000, Barros Pena, Belen wrote:
>> 
>> On 22/08/2013 16:02, "Damian, Alexandru" <alexandru.damian@intel.com>
>> wrote:
>> 
>> >not sure how this should be handled, Paul thinks it should be in there
>>?
>> >
>> >
>> >AFAIK, suffixed variables get used instead of the normal ones, so they
>> >are more like replacements.
>> >
>> >I guess the design ask that we should the only the variables with doc
>> >attached,
>> 
>> Well Š no :) 
>> 
>> The design actually asked nothing, since it is still very much in the
>> works. My request to the team was in the lines of: can we provide a
>>short
>> explanation of the variables we show? When trying to work out how to
>> actually do this, we were suggested to use documentation.conf to provide
>> such explanations. This is quite different from saying "show variables
>> with the [doc] flag".
>
>PREFERRED_PROVIDER is perhaps a special case since it will usually have
>a suffix and we're not going to add a [doc] tag for every single one.
>Special casing that one in the code may make sense.
>
>Are there any other suffixed variables that are causing similar
>problems?

Yes, a few: B, SECTION, PREFERRED_VERSION, BASE_LIB, LAYERDEPENDS, etc.
That's why I brought it up.

>
>I suspect Paul's proposal of knocking off the lowercase suffixes and
>seeing if a [doc] tag exists might be the best/only way to attempt to
>handle this.
>
>Cheers,
>
>Richard
>

---------------------------------------------------------------------
Intel Corporation (UK) Limited
Registered No. 1134945 (England)
Registered Office: Pipers Way, Swindon SN3 1RJ
VAT No: 860 2173 47

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.

Re: [Webhob] updating documentation.conf

[Damian, Alexandru]

[-- Attachment #1: Type: text/plain, Size: 2515 bytes --]

Ok, knocking lowercase suffixes, I'll do it.

Architectural call, Richard - should it be done on Webhob, or in Bitbake.
I'd do it in bitbake since the [doc] field may be used to other purposes in
the future


Alex


On Thu, Aug 22, 2013 at 6:32 PM, Barros Pena, Belen <
belen.barros.pena@intel.com> wrote:

>
> On 22/08/2013 18:11, "Richard Purdie" <richard.purdie@linuxfoundation.org>
> wrote:
>
> >On Thu, 2013-08-22 at 15:40 +0000, Barros Pena, Belen wrote:
> >>
> >> On 22/08/2013 16:02, "Damian, Alexandru" <alexandru.damian@intel.com>
> >> wrote:
> >>
> >> >not sure how this should be handled, Paul thinks it should be in there
> >>?
> >> >
> >> >
> >> >AFAIK, suffixed variables get used instead of the normal ones, so they
> >> >are more like replacements.
> >> >
> >> >I guess the design ask that we should the only the variables with doc
> >> >attached,
> >>
> >> Well Š no :)
> >>
> >> The design actually asked nothing, since it is still very much in the
> >> works. My request to the team was in the lines of: can we provide a
> >>short
> >> explanation of the variables we show? When trying to work out how to
> >> actually do this, we were suggested to use documentation.conf to provide
> >> such explanations. This is quite different from saying "show variables
> >> with the [doc] flag".
> >
> >PREFERRED_PROVIDER is perhaps a special case since it will usually have
> >a suffix and we're not going to add a [doc] tag for every single one.
> >Special casing that one in the code may make sense.
> >
> >Are there any other suffixed variables that are causing similar
> >problems?
>
> Yes, a few: B, SECTION, PREFERRED_VERSION, BASE_LIB, LAYERDEPENDS, etc.
> That's why I brought it up.
>
> >
> >I suspect Paul's proposal of knocking off the lowercase suffixes and
> >seeing if a [doc] tag exists might be the best/only way to attempt to
> >handle this.
> >
> >Cheers,
> >
> >Richard
> >
>
> ---------------------------------------------------------------------
> Intel Corporation (UK) Limited
> Registered No. 1134945 (England)
> Registered Office: Pipers Way, Swindon SN3 1RJ
> VAT No: 860 2173 47
>
> This e-mail and any attachments may contain confidential material for
> the sole use of the intended recipient(s). Any review or distribution
> by others is strictly prohibited. If you are not the intended
> recipient, please contact the sender and delete all copies.
>



-- 
Alex Damian
Yocto Project
SSG / OTC

[-- Attachment #2: Type: text/html, Size: 3515 bytes --]

Re: [Webhob] updating documentation.conf

[Richard Purdie]

On Thu, 2013-08-22 at 21:53 +0100, Damian, Alexandru wrote:
> Ok, knocking lowercase suffixes, I'll do it.
> 
> 
> Architectural call, Richard - should it be done on Webhob, or in
> Bitbake. I'd do it in bitbake since the [doc] field may be used to
> other purposes in the future
> 
The UPPERCASE_lowercase style is an OE convention, bitbake doesn't care.
It can be a utility function in bitbake but it shouldn't be in the
bitbake core if that makes sense.

Cheers,

Richard

Re: [Webhob] updating documentation.conf

[Barros Pena, Belen]

On 22/08/2013 23:26, "Richard Purdie" <richard.purdie@linuxfoundation.org>
wrote:

>On Thu, 2013-08-22 at 21:53 +0100, Damian, Alexandru wrote:
>> Ok, knocking lowercase suffixes, I'll do it.

Just to make sure we are talking about the same thing: we should display
the variables with their suffixes, but pick up the variable description
even if there is a suffix.


>> 
>> 
>> Architectural call, Richard - should it be done on Webhob, or in
>> Bitbake. I'd do it in bitbake since the [doc] field may be used to
>> other purposes in the future
>> 
>The UPPERCASE_lowercase style is an OE convention, bitbake doesn't care.
>It can be a utility function in bitbake but it shouldn't be in the
>bitbake core if that makes sense.
>
>Cheers,
>
>Richard
>
>
>

---------------------------------------------------------------------
Intel Corporation (UK) Limited
Registered No. 1134945 (England)
Registered Office: Pipers Way, Swindon SN3 1RJ
VAT No: 860 2173 47

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.

Re: [Webhob] updating documentation.conf

[Damian, Alexandru]

[-- Attachment #1: Type: text/plain, Size: 1509 bytes --]

Ok, I got a patch in testing.


On Fri, Aug 23, 2013 at 9:54 AM, Barros Pena, Belen <
belen.barros.pena@intel.com> wrote:

>
> On 22/08/2013 23:26, "Richard Purdie" <richard.purdie@linuxfoundation.org>
> wrote:
>
> >On Thu, 2013-08-22 at 21:53 +0100, Damian, Alexandru wrote:
> >> Ok, knocking lowercase suffixes, I'll do it.
>
> Just to make sure we are talking about the same thing: we should display
> the variables with their suffixes, but pick up the variable description
> even if there is a suffix.
>
>
> >>
> >>
> >> Architectural call, Richard - should it be done on Webhob, or in
> >> Bitbake. I'd do it in bitbake since the [doc] field may be used to
> >> other purposes in the future
> >>
> >The UPPERCASE_lowercase style is an OE convention, bitbake doesn't care.
> >It can be a utility function in bitbake but it shouldn't be in the
> >bitbake core if that makes sense.
> >
> >Cheers,
> >
> >Richard
> >
> >
> >
>
> ---------------------------------------------------------------------
> Intel Corporation (UK) Limited
> Registered No. 1134945 (England)
> Registered Office: Pipers Way, Swindon SN3 1RJ
> VAT No: 860 2173 47
>
> This e-mail and any attachments may contain confidential material for
> the sole use of the intended recipient(s). Any review or distribution
> by others is strictly prohibited. If you are not the intended
> recipient, please contact the sender and delete all copies.
>



-- 
Alex Damian
Yocto Project
SSG / OTC

[-- Attachment #2: Type: text/html, Size: 2220 bytes --]