Re: [yocto] All incompassing documentation
On Wed, Sep 19, 2012 at 12:02 AM, Jeff Osier-Mixon je...@jefro.net wrote: Anyone have a good term for source packages? Source tarball? ___ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
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 twoer...@gmail.com wrote: On Tue, Sep 18, 2012 at 2:23 PM, Brian Lloyd bll...@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@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
Re: [yocto] All incompassing documentation
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-boun...@yoctoproject.org [mailto:yocto-boun...@yoctoproject.org] On Behalf Of Brian Lloyd Sent: Wednesday, September 19, 2012 8:51 AM To: yocto@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 twoer...@gmail.com wrote: On Tue, Sep 18, 2012 at 2:23 PM, Brian Lloyd bll...@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@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto ___ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
Re: [yocto] All incompassing documentation
I'm afraid source tarball doesn't quite work, as not all are required to be tarballs, e.g. if something is in a git repo or in a local CVS repo. Can it be true that there is no single term that refers to the collection of pieces that, when built, create a discrete package? On Wed, Sep 19, 2012 at 8:50 AM, Brian Lloyd bll...@familyhonor.net wrote: 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. I think these actually refer to the same thing. Packages are products of the Yocto Project build process whose purpose is to be installed on the target. They are packaged using a specific format (.rpm, .deb, .ipk). This is a universal development term, at least within the wider Linux community, not a specific Yocto Project term. Unless I misunderstand what you are saying? 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. There shouldn't be any applications on your host (meaning: built for your host) that end up being installed on the target. There may be packages that you have downloaded that you'd like to install on your target, but that 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. Can you tell us what you mean by host package? 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 twoer...@gmail.com wrote: On Tue, Sep 18, 2012 at 2:23 PM, Brian Lloyd bll...@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@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto -- Jeff Osier-Mixon http://jefro.net/blog Yocto Project Community Manager @Intel http://yoctoproject.org ___ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
Re: [yocto] All incompassing documentation
It also occurs to me that a source for the confusion might be that there is more than one build process going on with BitBake. It is used both to create packages and to install them into a rootfs in order to create an image. Thus, the workflow looks something like this, starting from the point of download: [tarball/repo] - [source] - [binary] - [package] - [image] or, the evolution of a chunk of information, in terms of its file type: [.tar.gz/.git] - [*.c,*.h,Makefile,etc] - [executable] - [.rpm,.deb,.ipk] - [.ext3] Yes, this is a gross generalization with many exceptions. I'm just trying to capture discrete terms for each step of the process. Our term package is often used to describe the first item, sometimes to describe the second item, and always used to describe the fourth item. It is also sometimes used to describe the repository - the ecosystem of files that defines a given piece of software. Brian - thanks very much for starting this conversation. Terminology is important, and just because people use overloaded terms every day doesn't mean we shouldn't work to differentiate them. -- Jeff Osier-Mixon http://jefro.net/blog Yocto Project Community Manager @Intel http://yoctoproject.org ___ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
[yocto] All incompassing documentation
I took a look at the mega-manual for the first time after hearing mention of it in the meeting. From a new user perspective, it seems a step backwards. While everything may be there, it has the needle in the haystack feeling. The only way to find something is to search for it, but what search term to use? How do you even learn the basic terminology so you are speaking the same language everyone else is? The individual documents had tables of contents that would let you find what you were looking for, or at least take a stab at it. In this document, it feels hopeless. For instance, I want to know about creating new software Packages but a search for packages is not at all helpful. With no table of contents I cannot use that to narrow down my search for what is of interest. 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). Another issue I see is that information in the document seems to be more redundant (seems as separately it was just as redundant just not as noticeable). While including the same information in multiple documents is good when the documents are separated and a user is using just one of them, when pulling them together like this having an area at the beginning go over installation (quick start) and then have a later section go over it again seems a little redundant, and adds a lot more to search through when trying to find items of interest. Also on the redundancy issue, when two documents need to cover the same thing, such as which packages to install in a distro, I suggest a common source for the section be used that both share. While having things worded differently can help have things make sense to more people, having to look in separate locations for the different ways it is said isn't a good idea. So, if both ways of saying it are useful, both documents probably should have both wordings, and they should be found together, or at the least one references the other (for more details/specific steps see Appendix XYZ). There are exceptions (a quick start guide for instance), but those exceptions probably should either be treated like an appendix or not included in this document. So, areas I'm curious about: How is the redundancy being reduced, or is it not considered an issue? What options to help a user find the sections of interest are being considered, or is search for keywords the way the document is envisioned to be used? Interestingly, after not needing to build the documentation from the sources being mentioned, I ran into this in the documentation: BitBake: The task executor and scheduler used by the OpenEmbedded build system to build images. For more information on BitBake, see the BitBake documentation in the bitbake/doc/manual directory of the Source Directory. Which of course I then had to build to read, so seems at least some documentation is expected to be built from sources. Hopefully I haven't rambled so much to turn everyone off. At least one thing about documentation I haven't mastered is keeping it short... Brian ___ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
Re: [yocto] All incompassing documentation
On Tue, Sep 18, 2012 at 2:23 PM, Brian Lloyd bll...@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 image. Linux distributions also use the term packages to mean (essentially) the same thing (except their packages are not assembled through the use of bitbake). So I don't think package is a vague term; an rpm, or a deb, or an ipk... these are all packages. I do agree, however, that in the general, computer-user populace the term package is bandied about indiscriminately, but that doesn't mean we should have to use something else or come up with a new term altogether. ___ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
Re: [yocto] All incompassing documentation
snipped On Tue, Sep 18, 2012 at 12:04 PM, Trevor Woerner twoer...@gmail.com wrote: On Tue, Sep 18, 2012 at 2:23 PM, Brian Lloyd bll...@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? -- Jeff Osier-Mixon http://jefro.net/blog Yocto Project Community Manager @Intel http://yoctoproject.org ___ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
