[yocto] building a hierarchical poky variable glossary, noting what's missing

[Rifenbark, Scott M]

Robert, 

I can see your link being referenced from the YP ref-manual to augment variable descriptions and explanations.  Also, your compilation could act as another source of information similar to the list of "other information" items that currently are shown at the front of the dev-manual.

Scott

>-----Original Message-----
>From: yocto-bounces at yoctoproject.org [mailto:yocto-
>bounces at yoctoproject.org] On Behalf Of Robert P. J. Day
>Sent: Tuesday, August 26, 2014 4:11 AM
>To: Yocto discussion list
>Subject: [yocto] building a hierarchical poky variable glossary, noting what's
>missing
>
>
>  g'day, eh? for my own benefit (that is, for the sake of my upcoming yocto
>project courses), i'm starting a topic-based poky variable glossary, just so i can
>quickly display all of the variables related to a particular topic.
>
>  i know there's *some* of that in the ref manual here:
>
> http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#ref-
>varlocality
>
>but i'm interested in a much more complete list and, more importantly, i want
>to add chunks of code or explanations where i think it's useful. i started one of
>those a while back, but i'm updating it now and it's here (ignore everything
>below "----- OLD CONTENT, TO BE DELETED -----"):
>
> http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary
>
>and here are a couple features i'm adding that might be of interest to other
>doc writers (like scott rifenbark).
>
>  first, as i add more sections and variables, each variable will be represented
>by a link to the (in-progress) ref manual entry, just so i can take advantage of
>what already exists, so that's no big deal.
>
>  next, in some cases, it's informative to grab some code or output from grep
>to accompany the variable reference, such as what i do here for the
>PARALLEL_MAKE* variables, just to show how they're being
>used:
>
>http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary#Genera
>l_build_variables
>
>this makes it really easy during class to show what some variables are doing,
>and how to use them.
>
>  finally, i can also note which variables aren't currently documented in either
>the ref manual or in the meta/conf/documentation.conf file, since that takes
>little extra time.
>
>  here's an example documenting the variables that affect the final size of the
>rootfs image:
>
>http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary#Final_r
>ootfs.2Fimage_size
>
>first, as you can see, in some cases, it makes sense to reproduce the code that
>uses all those variables so students see how they hang together, after which i
>list the variables, and there are two variations i'm using to show missing
>documentation.
>
>  if there's no hyperlink (as with IMAGE_ROOTFS_MAXSIZE), that means there
>is no entry for that variable in the poky reference manual, so someone is
>welcome to add that.
>
>  also, the string "{!doc}" means there's no entry for that variable in the
>"documentation.conf" file so, once again, someone is welcome to do
>something about that if they want.
>
>  finally, in some cases, it's not clear whether a variable should be documented
>anywhere if it's obvious it's being used only locally in a recipe or class and is
>not meant to be manipulated by the developer.
>here's an example:
>
> http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary#U-Boot
>
>note in u-boot.inc the variable SPL_BINARY, then SPL_IMAGE and
>SPL_SYMLINK which are calculated based on it. so which of these (if
>any) deserve documentation? for now, i'm going with SPL_BINARY since it's
>meant to be used by the developer (i even show show where), but i'm leaving
>out the other two. it's all a judgment call.
>
>  clearly, this is a long-term project but i'll add more sections on a regular basis
>and try to keep things up to date. if there's a better way to do this, i'm open to
>suggestions.
>
>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 at yoctoproject.org
>https://lists.yoctoproject.org/listinfo/yocto