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
Signature · 7 lines
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================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
Quoted 50 lines
-----Original Message-----
From: [email protected] [mailto:yocto- [email protected]] 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 glossaryexpecting 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-
Uand what seems to be missing is:
*
UBOOT_ARCH
*UBOOT_SUFFIX
*UBOOT_BINARY
*UBOOT_IMAGE
*UBOOT_MAKE_TARGET
*UBOOT_SYMLINKshort 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.caTwitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday===========================================================
=============
_______________________________________________
yocto mailing list
[email protected]
https://lists.yoctoproject.org/listinfo/yocto
Quoted 11 lines · 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
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
Signature · 7 lines
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================This will be useful for me... thanks Robert.
Scott
Quoted 70 lines
-----Original Message-----
From: Robert P. J. Day [mailto:[email protected]]
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 glossaryQuoted 11 lines · 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,
Scottfor 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_variablesthat 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 linkand 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.caTwitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday===========================================================
=============
Quoted 1 line · Scott M
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
Signature · 7 lines
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================Hi Robert,
Quoted 15 lines · On Tuesday 05 November 2013 01:34:56 Robert P. J. Day wrote:
Quoted 1 line · Scott M
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 byUBOOT_MAKE_TARGET?)
Quoted 4 lines
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
Signature · 2 lines
Paul Eggleton Intel Open Source Technology Centre
Quoted 5 lines · 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.
well I have a different response as alternative file a bug in YP bugzilla :)
Quoted 35 lines
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_SYMLINKshort 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.caTwitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday========================================================================
_______________________________________________
yocto mailing list
[email protected]
https://lists.yoctoproject.org/listinfo/yocto