documentation/poky-ref-manual/faq.xml: Scrubbed for term Poky.

In general, the term Poky can be replaced by "the Yocto Project."
The term Poky can be used as a term for the Yocto Project build system.
I left it in place for a few areas where it was easy and would not
be confusing.

I also performed general rewrites for the FAQ.

(From yocto-docs rev: bb24bcf21311c68576fb8c3fec86ad8303f557f2)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 143 insertions, 111 deletions

diff --git a/documentation/poky-ref-manual/faq.xml b/documentation/poky-ref-manual/faq.xml
index 25444f6..dec9133 100644
--- a/documentation/poky-ref-manual/faq.xml
+++ b/documentation/poky-ref-manual/faq.xml
@@ -83,14 +83,14 @@
         </question>
         <answer>
             <para>
-                There are two main ways to get a board supported in Poky;
+                There are two main ways to get a board supported in the Yocto Project;
                 <itemizedlist>
                     <listitem><para>Send the Yocto Project team information on the board
                         and if the team does not have it yet they will consider adding it.</para></listitem>
                     <listitem><para>Send the Yocto Project team the BitBake recipes if you have them.
                         </para></listitem>
                 </itemizedlist>
-                Usually, if the board is not a completely exotic, adding support in 
+                Usually, if the board is not completely exotic, adding support in 
                 the Yocto Project is fairly straightforward.
             </para>
         </answer>
@@ -99,13 +99,13 @@
     <qandaentry>
         <question>
             <para>
-                Are there any products running poky?
+                Are there any products using Poky?
             </para>
         </question>
         <answer>
             <para>
                 The <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink> is using 
-                Poky.  
+                the Yocto Project build system Poky.  
                 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
                 for more information.
                 There are a number of pre-production devices using Poky and the Yocto Project team
@@ -113,158 +113,170 @@
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
-                What is the Poky output ?
+                What does the Yocto Project build system Poky produce as output?
             </para>
         </question>
         <answer>
             <para>
-                The output of a Poky build will depend on how it was started, as the same set of recipes can be used to output various formats. Usually the output is a flashable image ready for the target device.
+                Because the same set of recipes can be used to create output of various formats, the 
+                output of a Yocto Project build depends on how it was started. 
+                Usually, the output is a flashable image ready for the target device.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
-                How do I add my package to Poky?
+                How do I add my package to the Yocto Project?
             </para>
         </question>
         <answer>
             <para>
-                To add a package you need to create a BitBake recipe - see the Poky handbook to find out how to create a recipe.
+                To add a package, you need to create a BitBake recipe.
+                For information on how to add a package, see the 
+                <link linkend='usingpoky-extend-addpkg'>Adding a Package</link> section
+                earlier in this manual.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
-                Do I have to reflash my entire board with a new poky image when recompiling a package?
+                Do I have to reflash my entire board with a new Yocto Project image when recompiling 
+                a package?
             </para>
         </question>
         <answer>
             <para>
-                Poky can build packages in various formats, ipk (for ipkg/opkg), Debian package (.deb), or RPM. The packages can then be upgraded using the package tools on the device, much like on a desktop distribution like Ubuntu or Fedora.
+                The Yocto Project can build packages in various formats such as
+                <filename>ipk</filename> for <filename>ipkg</filename>/<filename>opkg</filename>, 
+                Debian package (<filename>.deb</filename>), or RPM. 
+                The packages can then be upgraded using the package tools on the device, much like 
+                on a desktop distribution such as Ubuntu or Fedora.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
-                What is GNOME Mobile? What's the difference between GNOME Mobile and GNOME?
+                What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
             </para>
         </question>
         <answer>
             <para>
-                <ulink url='http://www.gnome.org/mobile/'>GNOME Mobile</ulink> is a subset of the GNOME platform targeted at mobile and embedded devices. The the main difference between GNOME Mobile and standard GNOME is that desktop-orientated libraries have been removed, along with deprecated libraries, creating a much smaller footprint. 
+                <ulink url='http://www.gnome.org/mobile/'>GNOME Mobile</ulink> is a subset of the GNOME 
+                platform targeted at mobile and embedded devices. 
+                The the main difference between GNOME Mobile and standard GNOME is that 
+                desktop-orientated libraries have been removed, along with deprecated libraries, 
+                creating a much smaller footprint. 
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
-                I see the error 'chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x'. What's wrong?
+                I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
+                What is wrong?
             </para>
         </question>
         <answer>
             <para>
-                You're probably running the build on an NTFS filesystem. Use a sane one like ext2/3/4 instead!
+                You are probably running the build on an NTFS filesystem. 
+                Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
-                How do I make Poky work in RHEL/CentOS?
+                How do I make the Yocto Project work in RHEL/CentOS?
             </para>
         </question>
         <answer>
             <para>
-                To get Poky working under RHEL/CentOS 5.1 you need to first install some required packages. The standard CentOS packages needed are:
+                To get the Yocto Project working under RHEL/CentOS 5.1 you need to first 
+                install some required packages. 
+                The standard CentOS packages needed are:
                 <itemizedlist>
-                    <listitem>
-                        <para>
-                            "Development tools" (selected during installation)
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            texi2html
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            compat-gcc-34
-                        </para>
-                    </listitem>
+                    <listitem><para>"Development tools" (selected during installation)</para></listitem>
+                    <listitem><para><filename>texi2html</filename></para></listitem>
+                    <listitem><para><filename>compat-gcc-34</filename></para></listitem>
                 </itemizedlist>
-            </para>
-
-            <para>
-                On top of those the following external packages are needed:
+                On top of these, you need the following external packages:
                 <itemizedlist>
-                    <listitem>
-                        <para>
-                            python-sqlite2 from <ulink
-                                url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG
-                                repository</ulink>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            help2man from <ulink
-                                url='http://centos.karan.org/el5/extras/testing/i386/RPMS/help2man-1.33.1-2.noarch.rpm'>Karan
-                                repository</ulink>
-                        </para>
-                    </listitem>
+                    <listitem><para><filename>python-sqlite2</filename> from 
+                        <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
+                        </para></listitem>
+                    <listitem><para><filename>help2man</filename> from 
+                        <ulink url='http://centos.karan.org/el5/extras/testing/i386/RPMS/help2man-1.33.1-2.noarch.rpm'>Karan repository</ulink></para></listitem>
                 </itemizedlist>
             </para>
 
             <para>
-                Once these packages are installed Poky will be able to build standard images however there 
-                may be a problem with QEMU segfaulting. You can either disable the generation of binary 
-                locales by setting <glossterm><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
-                </glossterm> to "0" or remove the linux-2.6-execshield.patch from the kernel and rebuild 
-                it since its that patch which causes the problems with QEMU.
+                Once these packages are installed, the Yocto Project will be able to build standard 
+                images.
+                However, there might be a problem with the QEMU emulator segfaulting. 
+                You can either disable the generation of binary locales by setting 
+                <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
+                </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
+                from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
                 I see lots of 404 responses for files on 
-                http://autobuilder.yoctoproject.org/sources/*. Is something wrong?
+                <filename>http://autobuilder.yoctoproject.org/sources/*</filename>. Is something wrong?
             </para>
         </question>
         <answer>
             <para>
-                Nothing is wrong, Poky will check any configured source mirrors before downloading 
-                from the upstream sources. It does this searching for both source archives and 
-                pre-checked out versions of SCM managed software. This is so in large installations, 
-                it can reduce load on the SCM servers themselves. The address above is one of the 
-                default mirrors configured into standard Poky so if an upstream source disappears, 
-                we can place sources there so builds continue to work.
+                Nothing is wrong.
+                The Yocto Project checks any configured source mirrors before downloading 
+                from the upstream sources. 
+                The Yocto Project does this searching for both source archives and 
+                pre-checked out versions of SCM managed software. 
+                These checks help in large installations because it can reduce load on the SCM servers 
+                themselves. 
+                The address above is one of the default mirrors configured into the 
+                Yocto Project.
+                Consequently, if an upstream source disappears, the team 
+                can place sources there so builds continue to work.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
-                I have a machine specific data in a package for one machine only but the package is 
-                 being marked as machine specific in all cases, how do I stop it?
+                I have machine-specific data in a package for one machine only but the package is 
+                being marked as machine-specific in all cases, how do I prevent this?
             </para>
         </question>
         <answer>
             <para>
-                Set <glossterm><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
-                </glossterm> = "0" in the .bb file but make sure the package is manually marked as 
-                machine specific in the case that needs it. The code which handles <glossterm><link 
-                linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link></glossterm>
-		is in base.bbclass.
+                Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
+                </filename> = "0" in the <filename>.bb</filename> file but make sure the package is 
+                manually marked as 
+                machine-specific in the case that needs it. 
+                The code that handles 
+                <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>
+                SRC_URI_OVERRIDES_PACKAGE_ARCH</link></filename> is in <filename>base.bbclass</filename>.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
@@ -273,14 +285,21 @@
         </question>
         <answer>
             <para>
-                Most source fetching by Poky is done by wget and you therefore need to specify the proxy 
-                settings in a .wgetrc file in your home directory. Example settings in that file would be
-                'http_proxy = http://proxy.yoyodyne.com:18023/' and 'ftp_proxy = http://proxy.yoyodyne.com:18023/'.
-                Poky also includes a site.conf.sample file which shows how to configure cvs and git proxy servers
+                Most source fetching by the Yocto Project is done by <filename>wget</filename>
+                and you therefore need to specify the proxy settings in a 
+                <filename>.wgetrc</filename> file in your home directory. 
+                Example settings in that file would be 
+                <literallayout class='monospaced'>
+     http_proxy = http://proxy.yoyodyne.com:18023/
+     ftp_proxy = http://proxy.yoyodyne.com:18023/
+                </literallayout>
+                The Yocto Project also includes a <filename>site.conf.sample</filename>
+                file that shows how to configure CVS and Git proxy servers
                 if needed.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
@@ -289,26 +308,37 @@
         </question>
         <answer>
             <para>
-	        In Intrepid, Ubuntu turned on by default normally optional compile-time security features 
-		and warnings. There are more details at <ulink
-                url='https://wiki.ubuntu.com/CompilerFlags'>https://wiki.ubuntu.com/CompilerFlags</ulink>.
-		You can work around this problem by disabling those options by adding " -Wno-format-security -U_FORTIFY_SOURCE" 
-		to the BUILD_CPPFLAGS variable in conf/bitbake.conf.
+	            In Intrepid, Ubuntu turns on by default the normally optional compile-time security features 
+		        and warnings. 
+                There are more details at 
+                <ulink url='https://wiki.ubuntu.com/CompilerFlags'>https://wiki.ubuntu.com/CompilerFlags</ulink>.
+		        You can work around this problem by disabling those options by adding 
+                the following to the <filename>BUILD_CPPFLAGS</filename> variable in the
+                <filename>conf/bitbake.conf</filename> file.
+                <literallayout class='monospaced'>
+     " -Wno-format-security -U_FORTIFY_SOURCE" 
+                </literallayout>
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
-                What’s the difference between foo and foo-native?
+                What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>?
             </para>
         </question>
         <answer>
             <para>
-                The *-native targets are designed to run on the system the build is running on. These are usually tools that are needed to assist the build in some way such as quilt-native which is used to apply patches. The non-native version is the one that would run on the target device.
+                The <filename>*-native</filename> targets are designed to run on the system 
+                being used for the build.
+                These are usually tools that are needed to assist the build in some way such as 
+                <filename>quilt-native</filename>, which is used to apply patches. 
+                The non-native version is the one that runs on the target device.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
@@ -317,10 +347,17 @@
         </question>
         <answer>
             <para>
-                If the same build is failing in totally different and random ways the most likely explanation is that either the hardware you're running it on has some problem or if you are running it under virtualisation, the virtualisation probably has bugs. Poky processes a massive amount of data causing lots of network, disk and cpu activity and is sensitive to even single bit failure in any of these areas. Totally random failures have always been traced back to hardware or virtualisation issues.
+                If the same build is failing in totally different and random ways,
+                the most likely explanation is that either the hardware you're running the 
+                build on has some problem, or, if you are running the build under virtualisation, 
+                the virtualisation probably has bugs. 
+                The Yocto Project processes a massive amount of data causing lots of network, disk and 
+                CPU activity and is sensitive to even single bit failures in any of these areas. 
+                True random failures have always been traced back to hardware or virtualisation issues.
             </para>
         </answer>
     </qandaentry>
+
     <qandaentry>
         <question>
             <para>
@@ -329,7 +366,13 @@
         </question>
         <answer>
             <para>
-                This is a difficult question and you need to consult your lawyer for the answer for your specific case. Its worth bearing in mind that for GPL compliance there needs to be enough information shipped to allow someone else to rebuild the same end result as you are shipping. This means sharing the source code, any patches applied to it but also any configuration information about how that package was configured and built.
+                This is a difficult question and you need to consult your lawyer for the answer
+                for your specific case.
+                It is worth bearing in mind that for GPL compliance there needs to be enough
+                information shipped to allow someone else to rebuild the same end result 
+                you are shipping. 
+                This means sharing the source code, any patches applied to it, and also any
+                configuration information about how that package was configured and built.
             </para>
         </answer>
     </qandaentry>
@@ -344,7 +387,7 @@
             <para>
                 You need to create a form factor file as described in 
                 <xref linkend='bsp-filelayout-misc-recipes'>"Miscellaneous Recipe Files"</xref>
-                and set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to one.
+                and set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to one as follows:
                 <literallayout class='monospaced'>
      HAVE_TOUCHSCREEN=1
                 </literallayout>
@@ -362,7 +405,7 @@
             <para>
                 The default interfaces file provided by the netbase recipe does not 
                 automatically bring up network interfaces. 
-                Therefore you will need to add a BSP-specific netbase that includes an interfaces 
+                Therefore, you will need to add a BSP-specific netbase that includes an interfaces 
                 file.
                 See <xref linkend='bsp-filelayout-misc-recipes'>"Miscellaneous Recipe Files"</xref>
                 for information on creating these types of miscellaneous recipe files.
@@ -386,7 +429,7 @@
         <answer>
             <para>
                 Images are created to be 1.2 times the size of the populated root filesystem. 
-                To modify this ratio so that there is more free space available you need to 
+                To modify this ratio so that there is more free space available, you need to 
                 set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>.  
                 For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets 
                 the image size ratio to one and a half times the size of the populated 
@@ -406,9 +449,10 @@
         </question>
         <answer>
             <para>
-                We have tried to do this before but too many of the tools we depend on such as autoconf 
+                The Yocto Project team has tried to do this before but too many of the tools 
+                the Yocto Project depends on such as <filename>autoconf</filename> 
                 break when they find spaces in pathnames.  
-                Until that situation changes we will not support spaces in pathnames.
+                Until that situation changes, the team will not support spaces in pathnames.
             </para>
         </answer>
     </qandaentry>
@@ -422,17 +466,18 @@
         <answer>
             <para>
                 The toolchain configuration is very flexible and customizable.
-                It is primarily controlled with the TCMODE variable.
+                It is primarily controlled with the 
+                <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable.
                 This variable controls which file to include 
                 (<filename>conf/distro/include/tcmode-*.inc</filename>).
             </para>
             <para>
-                The default value of TCMODE is "default".
+                The default value of <filename>TCMODE</filename> is "default".
                 However, other patterns are accepted.
                 In particular, "external-*" refers to external toolchains of which there are some basic examples
                 included with the core.
                 A user can use their own custom toolchain definition in their own layer 
-                (or <filename>local.conf</filename> directory) at the location 
+                (or as defined in the <filename>local.conf</filename> file) at the location 
                 <filename>conf/distro/include/tcmode-*.inc</filename>.
             </para>
             <para>
@@ -446,29 +491,27 @@
         </answer>
     </qandaentry>
 
-
-
-
     <qandaentry>
         <question>
             <para>
-                How does Poky obtain source code and will it work behind my firewall or proxy server?
+                How does the Yocto Project obtain source code and will it work behind my 
+                firewall or proxy server?
             </para>
         </question>
         <answer>
             <para>
-                The way Poky obtains source code is highly configurable.
-                You can setup Poky to get source code in most environments if
+                The way the Yocto Project obtains source code is highly configurable.
+                You can setup the Yocto Project to get source code in most environments if
                 HTTP transport is available.
             </para>
             <para>
-                When Poky searches for source code it first tries the local download directory.
+                When the build system searches for source code, it first tries the local download directory.
                 If that location fails, Poky tries PREMIRRORS, the upstream source, 
                 and then MIRRORS in that order.
             </para>
             <para>
                 By default, Poky uses the Yocto Project source PREMIRRORS for SCM-based sources, 
-                upstreams for normal tarballs and then falls back to a number of other mirrors 
+                upstreams for normal tarballs, and then falls back to a number of other mirrors 
                 including the Yocto Project source mirror if those fail.
             </para>
             <para>
@@ -484,7 +527,7 @@
                 </literallayout>
             </para>
             <para>
-                These changes cause Poky to intercept GIT, FTP, HTTP, and HTTPS
+                These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
                 requests and direct them to the <filename>http://</filename> sources mirror.
                 You can use <filename>file://</filename> URLs to point to local directories 
                 or network shares as well.
@@ -494,8 +537,6 @@
                 <literallayout class='monospaced'>
      BB_NO_NETWORK = "1"
                 </literallayout>
-             </para>
-             <para>
                  This statement tells BitBake to throw an error instead of trying to access the 
                  Internet.
                  This technique is useful if you want to ensure code builds only from local sources.
@@ -505,8 +546,6 @@
                  <literallayout class='monospaced'>
      BB_FETCH_PREMIRRORONLY = "1"
                  </literallayout>
-             </para>
-             <para>
                  This statement limits Poky to pulling source from the PREMIRRORS only.
                  Again, this technique is useful for reproducing builds.
              </para>
@@ -515,8 +554,6 @@
                  <literallayout class='monospaced'>
      BB_GENERATE_MIRROR_TARBALLS = "1"
                  </literallayout>
-             </para>
-             <para>
                  This statement tells Poky to generate mirror tarballs.
                  This technique is useful if you want to create a mirror server.
                  If not, however, the technique can simply waste time during the build.
@@ -524,7 +561,7 @@
              <para>
                  Finally, consider an example where you are behind an HTTP-only firewall.
                  You could make the following changes to the <filename>local.conf</filename>
-                 configuration file as long as the premirror server is up to date:
+                 configuration file as long as the PREMIRROR server is up to date:
                  <literallayout class='monospaced'>
      PREMIRRORS_prepend = "\
      ftp://.*/.* http://autobuilder.yoctoproject.org/sources/ \n \
@@ -532,10 +569,8 @@
      https://.*/.* http://autobuilder.yoctoproject.org/sources/ \n"
      BB_FETCH_PREMIRRORONLY = "1" 
                  </literallayout>
-             </para>
-             <para>
                  These changes would cause Poky to successfully fetch source over HTTP and 
-                 any network accesses to anything other than the premirror would fail.
+                 any network accesses to anything other than the PREMIRROR would fail.
              </para>
              <para>
                  Poky also honors the standard environment variables 
@@ -545,9 +580,6 @@
              </para>
         </answer>
     </qandaentry>
-
-
-
 </qandaset>
 </appendix>
 <!--