filling in the "missing" entries in the ref manual variable glossary

filling in the "missing" entries in the ref manual variable glossary

[Robert P. J. Day]

  expecting the standard reaction to be, "hey, feel free to submit a
patch :-)", i've noticed that there are (unsurprisingly) quite a
number of variables missing from the variable glossary in the ref
manual.

  just related to u-boot (which i've been messing with this morning),
here's the current situation:

http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-U

and what seems to be missing is:

  * UBOOT_ARCH
  * UBOOT_SUFFIX
  * UBOOT_BINARY
  * UBOOT_IMAGE
  * UBOOT_MAKE_TARGET
  * UBOOT_SYMLINK

short of submitting full patches for things like this, is there at
least a list we can keep track of this stuff on? i'm not sure i have
the time to submit full explanatory patches for everything i run
across, but i can at least report what's missing if that's useful.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: filling in the "missing" entries in the ref manual variable glossary

[Rifenbark, Scott M]

Hey Robert, 

You don't need to submit full patches and explanations for these.  Noting that they are missing and need documenting is perfect.  If you do have time when you point out a missing variable, providing a brief explanation would help.  And... reporting what is missing is extremely useful.  It has been (and will continue to be) an ongoing process of fully documenting variables in the reference manual.

Thanks, 
Scott

>-----Original Message-----
>From: yocto-bounces@yoctoproject.org [mailto:yocto-
>bounces@yoctoproject.org] On Behalf Of Robert P. J. Day
>Sent: Thursday, October 24, 2013 8:40 AM
>To: Yocto discussion list
>Subject: [yocto] filling in the "missing" entries in the ref manual variable
>glossary
>
>
>  expecting the standard reaction to be, "hey, feel free to submit a patch :-)",
>i've noticed that there are (unsurprisingly) quite a number of variables missing
>from the variable glossary in the ref manual.
>
>  just related to u-boot (which i've been messing with this morning), here's the
>current situation:
>
>http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-
>U
>
>and what seems to be missing is:
>
>  * UBOOT_ARCH
>  * UBOOT_SUFFIX
>  * UBOOT_BINARY
>  * UBOOT_IMAGE
>  * UBOOT_MAKE_TARGET
>  * UBOOT_SYMLINK
>
>short of submitting full patches for things like this, is there at least a list we can
>keep track of this stuff on? i'm not sure i have the time to submit full
>explanatory patches for everything i run across, but i can at least report what's
>missing if that's useful.
>
>rday
>
>--
>
>===========================================================
>=============
>Robert P. J. Day                                 Ottawa, Ontario, CANADA
>                        http://crashcourse.ca
>
>Twitter:                                       http://twitter.com/rpjday
>LinkedIn:                               http://ca.linkedin.com/in/rpjday
>===========================================================
>=============
>_______________________________________________
>yocto mailing list
>yocto@yoctoproject.org
>https://lists.yoctoproject.org/listinfo/yocto

Re: filling in the "missing" entries in the ref manual variable glossary

[Khem Raj]

On Thu, Oct 24, 2013 at 8:39 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>
>   expecting the standard reaction to be, "hey, feel free to submit a
> patch :-)", i've noticed that there are (unsurprisingly) quite a
> number of variables missing from the variable glossary in the ref
> manual.

well I have a different response as alternative file a bug in YP bugzilla :)

>
>   just related to u-boot (which i've been messing with this morning),
> here's the current situation:
>
> http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-U
>
> and what seems to be missing is:
>
>   * UBOOT_ARCH
>   * UBOOT_SUFFIX
>   * UBOOT_BINARY
>   * UBOOT_IMAGE
>   * UBOOT_MAKE_TARGET
>   * UBOOT_SYMLINK
>
> short of submitting full patches for things like this, is there at
> least a list we can keep track of this stuff on? i'm not sure i have
> the time to submit full explanatory patches for everything i run
> across, but i can at least report what's missing if that's useful.
>
> rday
>
> --
>
> ========================================================================
> Robert P. J. Day                                 Ottawa, Ontario, CANADA
>                         http://crashcourse.ca
>
> Twitter:                                       http://twitter.com/rpjday
> LinkedIn:                               http://ca.linkedin.com/in/rpjday
> ========================================================================
> _______________________________________________
> yocto mailing list
> yocto@yoctoproject.org
> https://lists.yoctoproject.org/listinfo/yocto

Re: filling in the "missing" entries in the ref manual variable glossary

[Robert P. J. Day]

On Thu, 24 Oct 2013, Rifenbark, Scott M wrote:

> Hey Robert,
>
> You don't need to submit full patches and explanations for these.
> Noting that they are missing and need documenting is perfect.  If
> you do have time when you point out a missing variable, providing a
> brief explanation would help.  And... reporting what is missing is
> extremely useful.  It has been (and will continue to be) an ongoing
> process of fully documenting variables in the reference manual.
>
> Thanks,
> Scott

  for better or worse, here's what i've decided to do. for my own
teaching purposes so i can quickly refer to all the variables related
to a single subject in front of a class, i started a wiki page which
will be an OE variable glossary broken into sections and grouping
related variables. here's the initial result for nothing more than
variables related to u-boot:

http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary#U-Boot_variables

that entire section took about 10 minutes to write and i now have what
i *think* is a list of every OE variable related to u-boot in the
following format:

 * if a variable is already documented in the ref manual, i just link
to it and leave it at that
 * if a variable isn't documented, i add it to the list but
(obviously) without a link

 and since i also want to see the usage of these things, i do a quick
"grep" for each one, which showed me that nothing seems to be using
the documented "UBOOT_TARGET" variable, but it seems that what
*should* be documented is "UBOOT_MAKE_TARGET" instead. and also, none
of the SPL-related variables are mentioned in the reference manual so
i list them as well. as i said, that section took all of about 10
minutes to write so it's not all that time-consuming.

 this is what i'm going to be working on over the next several days,
so if scott (or anyone else) wants to play along, that page will
certainly point out what variables are missing from the ref manual, as
well as any oddities i run across and someone else can submit patches
for the ref manual -- there's just no way i have the time to create
all the patches, but i can certainly at least point out what needs
patching.

 thoughts?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: filling in the "missing" entries in the ref manual variable glossary

[Rifenbark, Scott M]

This will be useful for me... thanks Robert.

Scott

>-----Original Message-----
>From: Robert P. J. Day [mailto:rpjday@crashcourse.ca]
>Sent: Friday, November 01, 2013 6:46 AM
>To: Rifenbark, Scott M
>Cc: Yocto discussion list
>Subject: RE: [yocto] filling in the "missing" entries in the ref manual variable
>glossary
>
>On Thu, 24 Oct 2013, Rifenbark, Scott M wrote:
>
>> Hey Robert,
>>
>> You don't need to submit full patches and explanations for these.
>> Noting that they are missing and need documenting is perfect.  If you
>> do have time when you point out a missing variable, providing a brief
>> explanation would help.  And... reporting what is missing is extremely
>> useful.  It has been (and will continue to be) an ongoing process of
>> fully documenting variables in the reference manual.
>>
>> Thanks,
>> Scott
>
>  for better or worse, here's what i've decided to do. for my own teaching
>purposes so i can quickly refer to all the variables related to a single subject in
>front of a class, i started a wiki page which will be an OE variable glossary
>broken into sections and grouping related variables. here's the initial result for
>nothing more than variables related to u-boot:
>
>http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary#U-
>Boot_variables
>
>that entire section took about 10 minutes to write and i now have what i
>*think* is a list of every OE variable related to u-boot in the following format:
>
> * if a variable is already documented in the ref manual, i just link to it and
>leave it at that
> * if a variable isn't documented, i add it to the list but
>(obviously) without a link
>
> and since i also want to see the usage of these things, i do a quick "grep" for
>each one, which showed me that nothing seems to be using the documented
>"UBOOT_TARGET" variable, but it seems that what
>*should* be documented is "UBOOT_MAKE_TARGET" instead. and also, none
>of the SPL-related variables are mentioned in the reference manual so i list
>them as well. as i said, that section took all of about 10 minutes to write so it's
>not all that time-consuming.
>
> this is what i'm going to be working on over the next several days, so if scott
>(or anyone else) wants to play along, that page will certainly point out what
>variables are missing from the ref manual, as well as any oddities i run across
>and someone else can submit patches for the ref manual -- there's just no
>way i have the time to create all the patches, but i can certainly at least point
>out what needs patching.
>
> thoughts?
>
>rday
>
>--
>
>===========================================================
>=============
>Robert P. J. Day                                 Ottawa, Ontario, CANADA
>                        http://crashcourse.ca
>
>Twitter:                                       http://twitter.com/rpjday
>LinkedIn:                               http://ca.linkedin.com/in/rpjday
>===========================================================
>=============
>

Re: filling in the "missing" entries in the ref manual variable glossary

[Robert P. J. Day]

On Mon, 4 Nov 2013, Rifenbark, Scott M wrote:

> This will be useful for me... thanks Robert.

  i'm about halfway through the categorized variable glossary:

http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary

and a few variables that caught my eye:

 * BUGTRACKER (not mentioned)
 * TUNE_ARCH (not mentioned)
 * TUNE_FEATURES (not mentioned)
 * CLASSOVERRIDE (not mentioned)
 * UBOOT_TARGET (mentioned, but replaced by UBOOT_MAKE_TARGET?)

and a number of UBOOT-related variables aren't mentioned. not clear if
any of these *should* be added -- there's obviously a limit to how
many variables you should explain -- but you can decide if any should
be added to the ref manual.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: filling in the "missing" entries in the ref manual variable glossary

[Paul Eggleton]

Hi Robert,

On Tuesday 05 November 2013 01:34:56 Robert P. J. Day wrote:
> On Mon, 4 Nov 2013, Rifenbark, Scott M wrote:
> > This will be useful for me... thanks Robert.
> 
>   i'm about halfway through the categorized variable glossary:
> 
> http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary
> 
> and a few variables that caught my eye:
> 
>  * BUGTRACKER (not mentioned)
>  * TUNE_ARCH (not mentioned)
>  * TUNE_FEATURES (not mentioned)
>  * CLASSOVERRIDE (not mentioned)
>  * UBOOT_TARGET (mentioned, but replaced by UBOOT_MAKE_TARGET?)
> 
> and a number of UBOOT-related variables aren't mentioned. not clear if
> any of these *should* be added -- there's obviously a limit to how
> many variables you should explain -- but you can decide if any should
> be added to the ref manual.

I think a variable should be documented if anyone will ever need to know what 
it does - and that probably includes almost all variables. I have talked with 
Scott in the past about some kind of labelling system for the variable 
glossary so you can see at a glance where the variable is supposed to be used 
and (hopefully, if we can come up with sane categorisation) when it's 
appropriate to modify.

IMO, all of those you listed should be documented. I've just entered a bug 
about documenting the tune files / variables at least:

https://bugzilla.yoctoproject.org/show_bug.cgi?id=5463

Cheers,
Paul


-- 

Paul Eggleton
Intel Open Source Technology Centre