[yocto] All incompassing documentation

[Rifenbark, Scott M]

These are all great points and we can adjust the manual set to use proper forms of the term.  We do have a "Terms" section and can add a clear definition of the term there.  Then, throughout the docs as the term is used it can be linked back to the definition.  Once we settle on the primary use I can go forward with that.  Regarding an index - Indices are great and the set should have one. This needs to be a "to do" item for the set.  I have written many indices and a good index takes a lot of effort.  Case in point - there are documentation specialists that limit their work exclusively to creating indices.

Good feedback!

Thanks,
Scott

-----Original Message-----
From: yocto-bounces at yoctoproject.org [mailto:yocto-bounces at yoctoproject.org] On Behalf Of Brian Lloyd
Sent: Wednesday, September 19, 2012 8:51 AM
To: yocto at yoctoproject.org
Subject: Re: [yocto] All incompassing documentation

I would like to point out Yocto's own documentation uses it for two
separate items, which is the point I was making.  Neither of which are
source tarballs....


It is a product produced by Yocto.
It is the items to be installed from the host system.


That may be right, but if so, we can't say that for Yocto it only means
the first, as we use it for the second as well.  If we want it to only
be the first, then we must use a different term for the second, such as
host applications, and the user should be notified of the unusual word
choice and why early in the documentation.  I believe there are several
locations where terms are explained already in the documentation, even
if we later use the term in a way other than that identified as it's
meaning (3.4. Yocto Project Terms comes to mind).  Discussing Package
meaning there, perhaps we should identify the term that will be used for
host package, or how we will identify when the term is used with a
different meaning than the one just given.


Or if we concede that packages is what the user expects to see when
discussing what to install, we need to disambiguate in some way to
differentiate the two uses.  Indexes are good at this.  The biggest
advantage to an index over straight search is that author's can use
context to differentiate the different uses when a word has them.
Another option could be prepending to both the context at each location
used, so we use Yocto package and host package or where we always prefix
context to one of the two for every use.  However, doing only one with a
context makes for more manual searches, where we are making a document
with the goal of making searching for information more effective.


On Tue, 2012-09-18 at 21:02 -0700, Jeff Osier-Mixon wrote:
> <snipped>
> 
> On Tue, Sep 18, 2012 at 12:04 PM, Trevor Woerner <twoerner at gmail.com> wrote:
> > On Tue, Sep 18, 2012 at 2:23 PM, Brian Lloyd <blloyd at familyhonor.net> wrote:
> >> Most of my hits for such an item
> >> discuss the packages I will need to install in my host distribution so I
> >> can use the yocto project (not surprised, the danger of a term as vague
> >> as packages).
> >
> > In bitbake/yocto/OE/etc. the term "packages" is not vague and has a
> > very specific meaning: bitbake processes recipes to produce one or
> > more packages. Some of these packages are then assembled into an
> 
> This is quite true - but the term itself is overloaded. I have often
> heard "package" referred to also as the collection of source code one
> would use to create a given piece of software, e.g. "the busybox
> package". This is no doubt the result of downloading numerous
> "packages" from the net in binary form rather than source. It doesn't
> help that there are "source packages" in the RPM world
> (http://www.rpm.org/max-rpm/s1-rpm-miscellania-srpms.html) and in the
> Debian world (http://www.debian.org/doc/manuals/apt-howto/ch-sourcehandling.en.html),
> so the confusion is natural.
> 
> In OE-based systems like the Yocto Project, the term refers to the
> results of a build rather than the ingredients. I agree with you that
> we should continue to push the correct usage to unload the term.
> Anyone have a good term for "source packages"?
> 


_______________________________________________
yocto mailing list
yocto at yoctoproject.org
https://lists.yoctoproject.org/listinfo/yocto