concepts-manual: General edits

Removed redundant links, changed some wordings.  This was a general
scrub of the prose.

(From yocto-docs rev: 2c0ff0af7df3aa46fc05aaf28039a2ffb380424a)

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

1 files changed, 58 insertions, 61 deletions

diff --git a/documentation/concepts-manual/concepts-manual-concepts.xml b/documentation/concepts-manual/concepts-manual-concepts.xml
index 4ad4ebc74b..010eda6191 100644
--- a/documentation/concepts-manual/concepts-manual-concepts.xml
+++ b/documentation/concepts-manual/concepts-manual-concepts.xml
@@ -5,13 +5,6 @@
 <chapter id=' concepts-manual-concepts'>
 <title>Yocto Project Concepts</title>
 
-    <para>
-        This chapter describes concepts for various areas of the Yocto Project.
-        Currently, topics include Yocto Project components, cross-development
-        generation, shared state (sstate) cache, runtime dependencies,
-        Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses.
-    </para>
-
     <section id='yocto-project-components'>
         <title>Yocto Project Components</title>
 
@@ -67,8 +60,9 @@
             <title>BitBake</title>
 
             <para>
-                BitBake is the tool at the heart of the OpenEmbedded build
-                system and is responsible for parsing the
+                BitBake is the tool at the heart of the
+                <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+                and is responsible for parsing the
                 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
                 generating a list of tasks from it, and then executing those
                 tasks.
@@ -93,8 +87,7 @@
                 The most common usage for BitBake is
                 <filename>bitbake <replaceable>packagename</replaceable></filename>,
                 where <filename>packagename</filename> is the name of the
-                package you want to build (referred to as the "target" in this
-                manual).
+                package you want to build (referred to as the "target").
                 The target often equates to the first part of a recipe's
                 filename (e.g. "foo" for a recipe named
                 <filename>foo_1.3.0-r0.bb</filename>).
@@ -180,8 +173,10 @@
                 in the build's configuration file (e.g.
                 <filename>poky/build/conf/local.conf</filename>).
                 <note>
-                    Any recipe that PROVIDES a <filename>virtual/*</filename>
-                    item that is ultimately not selected through
+                    Any recipe that
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
+                    a <filename>virtual/*</filename> item that is ultimately
+                    not selected through
                     <filename>PREFERRED_PROVIDER</filename> does not get built.
                     Preventing these recipes from building is usually the
                     desired behavior since this mechanism's purpose is to
@@ -224,9 +219,7 @@
 
             <para>
                 Class files (<filename>.bbclass</filename>) contain information
-                that is useful to share between
-                <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
-                files.
+                that is useful to share between Metadata files.
                 An example is the
                 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
                 class, which contains common settings for any application that
@@ -288,16 +281,18 @@
 
         <para>
             Most of the work occurs on the Build Host.
-            This is the machine used to build images and generally work within the
-            the Yocto Project environment.
-            When you run BitBake to create an image, the OpenEmbedded build system
+            This is the machine used to build images and generally work within
+            the the Yocto Project environment.
+            When you run
+            <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+            to create an image, the OpenEmbedded build system
             uses the host <filename>gcc</filename> compiler to bootstrap a
             cross-compiler named <filename>gcc-cross</filename>.
             The <filename>gcc-cross</filename> compiler is what BitBake uses to
             compile source files when creating the target image.
             You can think of <filename>gcc-cross</filename> simply as an
-            automatically generated cross-compiler that is used internally within
-            BitBake only.
+            automatically generated cross-compiler that is used internally
+            within BitBake only.
             <note>
                 The extensible SDK does not use
                 <filename>gcc-cross-canadian</filename> since this SDK
@@ -370,11 +365,11 @@
         <para>
             You can use the OpenEmbedded build system to build an installer for
             the relocatable SDK used to develop applications.
-            When you run the installer, it installs the toolchain, which contains
-            the development tools (e.g., the
-            <filename>gcc-cross-canadian</filename>),
+            When you run the installer, it installs the toolchain, which
+            contains the development tools (e.g.,
+            <filename>gcc-cross-canadian</filename>,
             <filename>binutils-cross-canadian</filename>, and other
-            <filename>nativesdk-*</filename> tools,
+            <filename>nativesdk-*</filename> tools),
             which are tools native to the SDK (i.e. native to
             <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_ARCH'><filename>SDK_ARCH</filename></ulink>),
             you need to cross-compile and test your software.
@@ -476,8 +471,9 @@
 
         <para>
             By design, the OpenEmbedded build system builds everything from
-            scratch unless BitBake can determine that parts do not need to be
-            rebuilt.
+            scratch unless
+            <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+            can determine that parts do not need to be rebuilt.
             Fundamentally, building from scratch is attractive as it means all
             parts are built fresh and there is no possibility of stale data
             causing problems.
@@ -518,9 +514,10 @@
         </para>
 
         <para>
-            For the first question, the build system detects changes in the
-            "inputs" to a given task by creating a checksum (or signature) of
-            the task's inputs.
+            For the first question, the
+            <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+            detects changes in the "inputs" to a given task by creating a
+            checksum (or signature) of the task's inputs.
             If the checksum changes, the system assumes the inputs have changed
             and the task needs to be rerun.
             For the second question, the shared state (sstate) code tracks
@@ -607,7 +604,8 @@
                 Also, the build process has the objective of making native
                 or cross packages relocatable.
                 <note>
-                    Both native and cross packages run on the build host.
+                    Both native and cross packages run on the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
                     However, cross packages generate output for the target
                     architecture.
                 </note>
@@ -629,7 +627,7 @@
             </para>
 
             <para>
-                So far we have solutions for shell scripts.
+                So far, solutions for shell scripts exist.
                 What about Python tasks?
                 The same approach applies even though these tasks are more
                 difficult.
@@ -643,7 +641,7 @@
             <para>
                 Like the <filename>WORKDIR</filename> case, situations exist
                 where dependencies should be ignored.
-                For these cases, you can instruct the build process to
+                For these situations, you can instruct the build process to
                 ignore a dependency by using a line like the following:
                 <literallayout class='monospaced'>
      PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
@@ -656,7 +654,7 @@
             </para>
 
             <para>
-                Equally, there are cases where we need to add dependencies
+                Equally, there are cases where you need to add dependencies
                 BitBake is not able to find.
                 You can accomplish this by using a line like the following:
                 <literallayout class='monospaced'>
@@ -668,7 +666,7 @@
             </para>
 
             <para>
-                Consider a case with in-line Python, for example, where
+                As an example, consider a case with in-line Python where
                 BitBake is not able to figure out dependencies.
                 When running in debug mode (i.e. using
                 <filename>-DDD</filename>), BitBake produces output when it
@@ -696,9 +694,9 @@
             </para>
 
             <para>
-                At the code level, there are a variety of ways both the
+                At the code level, a variety of ways exist by which both the
                 basehash and the dependent task hashes can be influenced.
-                Within the BitBake configuration file, we can give BitBake
+                Within the BitBake configuration file, you can give BitBake
                 some extra information to help it construct the basehash.
                 The following statement effectively results in a list of
                 global variable dependency excludes - variables never
@@ -799,8 +797,8 @@
             </para>
 
             <para>
-                There are two types of output, one is just about creating a
-                directory in
+                Two types of output exist.
+                One type is just about creating a directory in
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
                 A good example is the output of either
                 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
@@ -1156,8 +1154,7 @@
                     current version of the package that provides the shared
                     library must be used, as if
                     "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
-                    had been added to
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>.
+                    had been added to <filename>RDEPENDS</filename>.
                     This forces an upgrade of the package containing the shared
                     library when installing the package that depends on the
                     library, if needed.</para>
@@ -1170,18 +1167,15 @@
                     </para></listitem>
                 <listitem><para>
                     <filename>pcdeps</filename>:
-                    During the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
-                    task of each recipe, all pkg-config modules
+                    During the <filename>do_package</filename> task of each
+                    recipe, all pkg-config modules
                     (<filename>*.pc</filename> files) installed by the recipe
                     are located.
                     For each module, the package that contains the module is
                     registered as providing the module.
                     The resulting module-to-package mapping is saved globally in
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
-                    by the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
-                    task.</para>
+                    <filename>PKGDATA_DIR</filename> by the
+                    <filename>do_packagedata</filename> task.</para>
 
                     <para>Simultaneously, all pkg-config modules installed by
                     the recipe are inspected to see what other pkg-config
@@ -1238,8 +1232,7 @@
 
         <para>
             The <filename>do_package</filename> task depends on the
-            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
-            task of each recipe in
+            <filename>do_packagedata</filename> task of each recipe in
             <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
             through use of a
             <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
@@ -1268,7 +1261,9 @@
 
         <para>
             One approach to allowing tasks to perform root-only operations
-            would be to require BitBake to run as root.
+            would be to require
+            <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+            to run as root.
             However, this method is cumbersome and has security issues.
             The approach that is actually used is to run tasks that benefit
             from root privileges in a "fake" root environment.
@@ -1288,8 +1283,9 @@
         </para>
 
         <para>
-            In the OpenEmbedded build system, the program that implements
-            fakeroot is known as Pseudo.
+            In the
+            <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>,
+            the program that implements fakeroot is known as Pseudo.
             Pseudo overrides system calls by using the environment variable
             <filename>LD_PRELOAD</filename>, which results in the illusion
             of running as root.
@@ -1469,8 +1465,9 @@
         <title>Licenses</title>
 
         <para>
-            This section describes the mechanism by which the OpenEmbedded
-            build system tracks changes to licensing text.
+            This section describes the mechanism by which the
+            <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+            tracks changes to licensing text.
             The section also describes how to enable commercially licensed
             recipes, which by default are disabled.
         </para>
@@ -1611,7 +1608,9 @@
                         <itemizedlist>
                             <listitem><para>
                                 If you specify an empty or invalid "md5"
-                                parameter, BitBake returns an md5 mis-match
+                                parameter,
+                                <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+                                returns an md5 mis-match
                                 error and displays the correct "md5" parameter
                                 value during the build.
                                 The correct parameter is also captured in
@@ -1704,9 +1703,8 @@
                             License flag matching allows you to control what recipes
                     the OpenEmbedded build system includes in the build.
                     Fundamentally, the build system attempts to match
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
-                    strings found in recipes against
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
+                    <filename>LICENSE_FLAGS</filename> strings found in recipes
+                    against <filename>LICENSE_FLAGS_WHITELIST</filename>
                     strings found in the whitelist.
                     A match causes the build system to include a recipe in the
                     build, while failure to find a match causes the build
@@ -1834,8 +1832,7 @@
                     Of course, you could also create a matching whitelist
                     for those components using the more general "commercial"
                     in the whitelist, but that would also enable all the
-                    other packages with
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
+                    other packages with <filename>LICENSE_FLAGS</filename>
                     containing "commercial", which you may or may not want:
                     <literallayout class='monospaced'>
      LICENSE_FLAGS_WHITELIST = "commercial"