documentation: Fixed links to "bitbake-term"

Fixes [YOCTO #11630]

Moving the "Yocto Project Terms" section from the dev-manual to
the ref-manual.  Doing so caused all the links to the id
"bitbake-term" to break.  These had to be individually fixed.

Discovered two unresolved references that were a consequence of
moving that section to the ref-manual.  These were fixed as well.

(From yocto-docs rev: 829ca6b64562f00a69f3956e9636c7edaa90ce16)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

7 files changed, 356 insertions, 8 deletions

diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index 459d571926..c0f1747961 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -34,7 +34,7 @@
                 Upstream releases, local projects, and SCMs.</para></listitem>
             <listitem><para><emphasis>Build System:</emphasis>
                 Processes under the control of
-                <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
+                <link linkend='bitbake-term'>BitBake</link>.
                 This block expands on how BitBake fetches source, applies
                 patches, completes compilation, analyzes output for package
                 generation, creates and tests packages, generates images, and
@@ -727,7 +727,7 @@
 
         <para>
             The OpenEmbedded build system uses
-            <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
+            <link linkend='bitbake-term'>BitBake</link>
             to produce images.
             You can see from the
             <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
index 5f3f173495..cdbdd4da24 100644
--- a/documentation/ref-manual/faq.xml
+++ b/documentation/ref-manual/faq.xml
@@ -17,7 +17,7 @@
                 refers to the specific reference build system that
                 the Yocto Project provides.
                 Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
-                and <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
+                and <link linkend='bitbake-term'>BitBake</link>.
                 Thus, the generic term used here for the build system is
                 the "OpenEmbedded build system."
                 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
@@ -810,7 +810,7 @@
             <para>
                 This situation results when a build system does
                 not recognize the environment variables supplied to it by
-                <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
+                <link linkend='bitbake-term'>BitBake</link>.
                 The incident that prompted this FAQ entry involved a Makefile
                 that used an environment variable named
                 <filename>BINDIR</filename> instead of the more standard
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index 7423467150..58ee073868 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -39,6 +39,354 @@
     </para>
 </section>
 
+<section id='yocto-project-terms'>
+    <title>Yocto Project Terms</title>
+
+    <para>
+        Following is a list of terms and definitions users new to the Yocto Project development
+        environment might find helpful.
+        While some of these terms are universal, the list includes them just in case:
+        <itemizedlist>
+            <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
+                a recipe file.
+                Append files are known as BitBake append files and <filename>.bbappend</filename> files.
+                The OpenEmbedded build system expects every append file to have a corresponding
+                recipe (<filename>.bb</filename>) file.
+                Furthermore, the append file and corresponding recipe file
+                must use the same root filename.
+                The filenames can differ only in the file type suffix used (e.g.
+                <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
+                </para>
+                <para>Information in append files extends or overrides the
+                information in the similarly-named recipe file.
+                For an example of an append file in use, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
+                section in the Yocto Project Development Manual.
+                <note>
+                    Append files can also use wildcard patterns in their version numbers
+                    so they can be applied to more than one version of the underlying recipe file.
+                </note>
+                </para></listitem>
+            <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
+                The task executor and scheduler used by the OpenEmbedded build
+                system to build images.
+                For more information on BitBake, see the
+                <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+                </para></listitem>
+            <listitem>
+                <para id='build-directory'><emphasis>Build Directory:</emphasis>
+                This term refers to the area used by the OpenEmbedded build
+                system for builds.
+                The area is created when you <filename>source</filename> the
+                setup environment script that is found in the Source Directory
+                (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                or
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
+                The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
+                variable points to the Build Directory.</para>
+
+                <para>
+                    You have a lot of flexibility when creating the Build
+                    Directory.
+                    Following are some examples that show how to create the
+                    directory.
+                    The examples assume your
+                    <link linkend='source-directory'>Source Directory</link> is
+                    named <filename>poky</filename>:
+                   <itemizedlist>
+                        <listitem><para>Create the Build Directory inside your
+                            Source Directory and let the name of the Build
+                            Directory default to <filename>build</filename>:
+                            <literallayout class='monospaced'>
+     $ cd $HOME/poky
+     $ source &OE_INIT_FILE;
+                            </literallayout></para></listitem>
+                        <listitem><para>Create the Build Directory inside your
+                            home directory and specifically name it
+                            <filename>test-builds</filename>:
+                            <literallayout class='monospaced'>
+     $ cd $HOME
+     $ source poky/&OE_INIT_FILE; test-builds
+                            </literallayout></para></listitem>
+                        <listitem><para>
+                            Provide a directory path and
+                            specifically name the Build Directory.
+                            Any intermediate folders in the pathname must
+                            exist.
+                            This next example creates a Build Directory named
+                            <filename>YP-&POKYVERSION;</filename>
+                            in your home directory within the existing
+                            directory <filename>mybuilds</filename>:
+                            <literallayout class='monospaced'>
+     $cd $HOME
+     $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
+                            </literallayout></para></listitem>
+                    </itemizedlist>
+                    <note>
+                        By default, the Build Directory contains
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
+                        which is a temporary directory the build system uses for
+                        its work.
+                        <filename>TMPDIR</filename> cannot be under NFS.
+                        Thus, by default, the Build Directory cannot be under NFS.
+                        However, if you need the Build Directory to be under NFS,
+                        you can set this up by setting <filename>TMPDIR</filename>
+                        in your <filename>local.conf</filename> file
+                        to use a local drive.
+                        Doing so effectively separates <filename>TMPDIR</filename>
+                        from <filename>TOPDIR</filename>, which is the Build
+                        Directory.
+                    </note>
+                    </para></listitem>
+            <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
+                and inheritance so that commonly used patterns can be defined once and then easily used
+                in multiple recipes.
+                For reference information on the Yocto Project classes, see the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
+                Yocto Project Reference Manual.
+                Class files end with the <filename>.bbclass</filename> filename extension.
+                </para></listitem>
+            <listitem><para><emphasis>Configuration File:</emphasis>
+                Configuration information in various <filename>.conf</filename>
+                files provides global definitions of variables.
+                The <filename>conf/local.conf</filename> configuration file in
+                the
+                <link linkend='build-directory'>Build Directory</link>
+                contains user-defined variables that affect every build.
+                The <filename>meta-poky/conf/distro/poky.conf</filename>
+                configuration file defines Yocto "distro" configuration
+                variables used only when building with this policy.
+                Machine configuration files, which
+                are located throughout the
+                <link linkend='source-directory'>Source Directory</link>, define
+                variables for specific hardware and are only used when building
+                for that target (e.g. the
+                <filename>machine/beaglebone.conf</filename> configuration
+                file defines variables for the Texas Instruments ARM Cortex-A8
+                development board).
+                Configuration files end with a <filename>.conf</filename>
+                filename extension.
+                </para></listitem>
+            <listitem><para id='cross-development-toolchain'>
+                <emphasis>Cross-Development Toolchain:</emphasis>
+                    In general, a cross-development toolchain is a collection of
+                    software development tools and utilities that run on one
+                    architecture and allow you to develop software for a
+                    different, or targeted, architecture.
+                    These toolchains contain cross-compilers, linkers, and
+                    debuggers that are specific to the target architecture.
+                </para>
+
+                <para>The Yocto Project supports two different cross-development
+                    toolchains:
+                    <itemizedlist>
+                        <listitem><para>A toolchain only used by and within
+                            BitBake when building an image for a target
+                            architecture.</para></listitem>
+                        <listitem><para>A relocatable toolchain used outside of
+                            BitBake by developers when developing applications
+                            that will run on a targeted device.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    Creation of these toolchains is simple and automated.
+                    For information on toolchain concepts as they apply to the
+                    Yocto Project, see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+                    section in the Yocto Project Reference Manual.
+                    You can also find more information on using the
+                    relocatable toolchain in the
+                    <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
+                </para></listitem>
+            <listitem><para><emphasis>Image:</emphasis>
+                An image is an artifact of the BitBake build process given
+                a collection of recipes and related Metadata.
+                Images are the binary output that run on specific hardware or
+                QEMU and are used for specific use-cases.
+                For a list of the supported image types that the Yocto Project provides, see the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+                chapter in the Yocto Project Reference Manual.</para></listitem>
+            <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
+                a BSP, or an application stack.
+                For a discussion specifically on BSP Layers, see the
+                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+                section in the Yocto Project Board Support Packages (BSP)
+                Developer's Guide.</para></listitem>
+            <listitem><para id='metadata'><emphasis>Metadata:</emphasis>
+                The files that BitBake parses when building an image.
+                In general, Metadata includes recipes, classes, and
+                configuration files.
+                In the context of the kernel ("kernel Metadata"),
+                it refers to Metadata in the <filename>meta</filename>
+                branches of the kernel source Git repositories.
+                </para></listitem>
+            <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
+                with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
+                This Metadata is found in the <filename>meta</filename> directory of the
+                <link linkend='source-directory'>Source Directory</link>.</para></listitem>
+            <listitem><para id='build-system-term'><emphasis>OpenEmbedded Build System:</emphasis>
+                The build system specific to the Yocto Project.
+                The OpenEmbedded build system is based on another project known
+                as "Poky", which uses
+                <link linkend='bitbake-term'>BitBake</link> as the task
+                executor.
+                Throughout the Yocto Project documentation set, the
+                OpenEmbedded build system is sometimes referred to simply
+                as "the build system".
+                If other build systems, such as a host or target build system
+                are referenced, the documentation clearly states the
+                difference.
+                <note>
+                    For some historical information about Poky, see the
+                    <link linkend='poky'>Poky</link> term.
+                </note>
+                </para></listitem>
+            <listitem><para><emphasis>Package:</emphasis>
+                In the context of the Yocto Project, this term refers to a
+                recipe's packaged output produced by BitBake (i.e. a
+                "baked recipe").
+                A package is generally the compiled binaries produced from the
+                recipe's sources.
+                You "bake" something by running it through BitBake.</para>
+                <para>It is worth noting that the term "package" can, in general, have subtle
+                meanings.  For example, the packages referred to in the
+                "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" section are
+                compiled binaries that, when installed, add functionality to your Linux
+                distribution.</para>
+                <para>Another point worth noting is that historically within the Yocto Project,
+                recipes were referred to as packages - thus, the existence of several BitBake
+                variables that are seemingly mis-named,
+                (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
+                </para></listitem>
+            <listitem><para><emphasis>Package Groups:</emphasis>
+                Arbitrary groups of software Recipes.
+                You use package groups to hold recipes that, when built,
+                usually accomplish a single task.
+                For example, a package group could contain the recipes for a
+                company’s proprietary or value-add software.
+                Or, the package group could contain the recipes that enable
+                graphics.
+                A package group is really just another recipe.
+                Because package group files are recipes, they end with the
+                <filename>.bb</filename> filename extension.</para></listitem>
+            <listitem><para id='poky'><emphasis>Poky:</emphasis>
+                The term "poky" can mean several things.
+                In its most general sense, it is an open-source
+                project that was initially developed by OpenedHand.
+                With OpenedHand, poky was developed off of the existing
+                OpenEmbedded build system becoming a commercially
+                supportable build system for embedded Linux.
+                After Intel Corporation acquired OpenedHand, the
+                project poky became the basis for the Yocto Project's
+                build system.</para>
+                <para>Within the Yocto Project source repositories,
+                <filename>poky</filename> exists as a separate Git
+                repository you can clone to yield a local copy on your
+                host system.
+                Thus, "poky" can refer to the local copy of the Source
+                Directory used for development within the Yocto
+                Project.</para>
+                <para>Finally, "poky" can refer to the default
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+                (i.e. distribution) created when you use the Yocto
+                Project in conjunction with the
+                <filename>poky</filename> repository to build an image.
+                </para></listitem>
+            <listitem><para><emphasis>Recipe:</emphasis>
+                A set of instructions for building packages.
+                A recipe describes where you get source code, which patches
+                to apply, how to configure the source, how to compile it and so on.
+                Recipes also describe dependencies for libraries or for other
+                recipes.
+                Recipes represent the logical unit of execution, the software
+                to build, the images to build, and use the
+                <filename>.bb</filename> file extension.
+                </para></listitem>
+            <listitem>
+                <para id='source-directory'><emphasis>Source Directory:</emphasis>
+                This term refers to the directory structure created as a result
+                of creating a local copy of the <filename>poky</filename> Git
+                repository <filename>git://git.yoctoproject.org/poky</filename>
+                or expanding a released <filename>poky</filename> tarball.
+                <note>
+                    Creating a local copy of the <filename>poky</filename>
+                    Git repository is the recommended method for setting up
+                    your Source Directory.
+                </note>
+                Sometimes you might hear the term "poky directory" used to refer
+                to this directory structure.
+                <note>
+                    The OpenEmbedded build system does not support file or
+                    directory names that contain spaces.
+                    Be sure that the Source Directory you use does not contain
+                    these types of names.
+                </note></para>
+
+                <para>The Source Directory contains BitBake, Documentation,
+                Metadata and other files that all support the Yocto Project.
+                Consequently, you must have the Source Directory in place on
+                your development system in order to do any development using
+                the Yocto Project.</para>
+
+                <para>When you create a local copy of the Git repository, you
+                can name the repository anything you like.
+                Throughout much of the documentation, "poky"
+                is used as the name of the top-level folder of the local copy of
+                the poky Git repository.
+                So, for example, cloning the <filename>poky</filename> Git
+                repository results in a local Git repository whose top-level
+                folder is also named "poky".</para>
+
+                <para>While it is not recommended that you use tarball expansion
+                to set up the Source Directory, if you do, the top-level
+                directory name of the Source Directory is derived from the
+                Yocto Project release tarball.
+                For example, downloading and unpacking
+                <filename>&YOCTO_POKY_TARBALL;</filename> results in a
+                Source Directory whose root folder is named
+                <filename>&YOCTO_POKY;</filename>.</para>
+
+                <para>It is important to understand the differences between the
+                Source Directory created by unpacking a released tarball as
+                compared to cloning
+                <filename>git://git.yoctoproject.org/poky</filename>.
+                When you unpack a tarball, you have an exact copy of the files
+                based on the time of release - a fixed release point.
+                Any changes you make to your local files in the Source Directory
+                are on top of the release and will remain local only.
+                On the other hand, when you clone the <filename>poky</filename>
+                Git repository, you have an active development repository with
+                access to the upstream repository's branches and tags.
+                In this case, any local changes you make to the local
+                Source Directory can be later applied to active development
+                branches of the upstream <filename>poky</filename> Git
+                repository.</para>
+
+                <para>For more information on concepts related to Git
+                repositories, branches, and tags, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
+                section in the Yocto Project Development Manual.
+                </para></listitem>
+            <listitem><para><emphasis>Task:</emphasis>
+                A unit of execution for BitBake (e.g.
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>,
+                and so forth).
+                </para></listitem>
+            <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
+                that are not local to the development system but located in a master area that is controlled
+                by the maintainer of the source code.
+                For example, in order for a developer to work on a particular piece of code, they need to
+                first get a copy of it from an "upstream" source.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
 <section id='intro-manualoverview'>
     <title>Documentation Overview</title>
     <para>
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 442324f1f7..0513b219cd 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -1218,7 +1218,7 @@
 
         <para>
             The following changes have been made to
-            <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
+            <link linkend='bitbake-term'>BitBake</link>.
         </para>
 
         <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml
index c713ffcf11..aa8408f432 100644
--- a/documentation/ref-manual/resources.xml
+++ b/documentation/ref-manual/resources.xml
@@ -89,7 +89,7 @@
                 Discussion mailing list about OpenEmbedded.</para></listitem>
             <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> -
                 Discussion mailing list about the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
+                <link linkend='bitbake-term'>BitBake</link>
                 build tool.</para></listitem>
             <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> -
                 Discussion mailing list about
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 1964a9a105..0c949880e7 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -18,7 +18,7 @@
 
     <para>
         The
-        <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
+        <link linkend='bitbake-term'>BitBake</link>
         task executor together with various types of configuration files form
         the OpenEmbedded Core.
         This section overviews these components by describing their use and
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 4e97e3ec02..d1ac18fb2f 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -208,7 +208,7 @@
             (<filename>qemux86</filename>) might be in
             <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
             To see the commands
-            <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> ran
+            <link linkend='bitbake-term'>BitBake</link> ran
             to generate a log, look at the corresponding
             <filename>run.do_</filename><replaceable>taskname</replaceable>
             file in the same directory.