bitbake: user-manual: Review edits applied throughout from Paul Eggleton.

Applied review edits from Paul Eggleton spanning the entire book.
Small areas affected in all chapters except the "Hello World"
Appendix.

Noteworthy changes in the variables chapter where I added two new
variables: BBINCLUDELOGS_LINES and BB_CONSOLELOG.

(Bitbake rev: 2d4b09be70c6df0c1605f7e291149c682999cf50)

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

5 files changed, 71 insertions, 52 deletions

diff --git a/bitbake/doc/user-manual/user-manual-execution.xml b/bitbake/doc/user-manual/user-manual-execution.xml
index 6110a93e2a..a67516e858 100644
--- a/bitbake/doc/user-manual/user-manual-execution.xml
+++ b/bitbake/doc/user-manual/user-manual-execution.xml
@@ -85,8 +85,10 @@
             Next, the <filename>bitbake.conf</filename> file is searched
             using the <filename>BBPATH</filename> variable that was
             just constructed.
-            The <filename>bitbake.conf</filename> file usually indicates
-            all the other key include files to parse.
+            The <filename>bitbake.conf</filename> file may also include other
+            configuration files using the
+            <filename>include</filename> or
+            <filename>require</filename> directives.
         </para>
 
         <para>
@@ -358,11 +360,11 @@
 
         <para>
             As an example of adding an extra provider, suppose a recipe named
-            <filename>package1.bb</filename> contained the following:
+            <filename>foo_1.0.bb</filename> contained the following:
             <literallayout class='monospaced'>
-     PROVIDES += "virtual/package"
+     PROVIDES += "virtual/bar_1.0"
             </literallayout>
-            The recipe now provides both "package1" and "virtual/package".
+            The recipe now provides both "foo_1.0" and "virtual/bar_1.0".
             The "virtual/" namespace is often used to denote cases where
             multiple providers are expected with the user choosing between
             them.
diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml
index c66596ed6e..5aa53defc4 100644
--- a/bitbake/doc/user-manual/user-manual-fetching.xml
+++ b/bitbake/doc/user-manual/user-manual-fetching.xml
@@ -50,7 +50,7 @@
         </para>
 
         <para>
-            The instance of the fetch module is usually followed by:
+            The instantiation of the fetch class is usually followed by:
             <literallayout class='monospaced'>
      rootdir = l.getVar('WORKDIR', True)
      fetcher.unpack(rootdir)
diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml
index d46e823c72..c7f01ad726 100644
--- a/bitbake/doc/user-manual/user-manual-intro.xml
+++ b/bitbake/doc/user-manual/user-manual-intro.xml
@@ -421,8 +421,8 @@
         <title>The BitBake Command</title>
 
         <para>
-            The BitBake command is the primary interface to the BitBake
-            tool.
+            The <filename>bitbake</filename> command is the primary interface
+            to the BitBake tool.
             This section presents the BitBake command syntax and provides
             several execution examples.
         </para>
@@ -536,13 +536,16 @@ Options:
      $ bitbake -b foo_1.0.bb
                     </literallayout>
                     The following command runs the clean task on the
-                    <filename>foo_1.0.bb</filename> recipe file:
+                    <filename>foo.bb</filename> recipe file:
                     <literallayout class='monospaced'>
      $ bitbake -b foo.bb -c clean
                     </literallayout>
                     <note>
                         The "-b" option explicitly does not handle recipe
                         dependencies.
+                        Other than for debugging purposes, it is instead
+                        recommended that you use the syntax presented in the
+                        next section.
                     </note>
                 </para>
             </section>
@@ -570,9 +573,7 @@ Options:
                     "--buildfile" or "-b" only accepts a "PROVIDES".
                     You cannot provide anything else.
                     By default, a recipe file generally "PROVIDES" its
-                    "packagename", "packagename-version", and
-                    "packagename-version-revision" as shown in the following
-                    example:
+                    "packagename" as shown in the following example:
                     <literallayout class='monospaced'>
      $ bitbake foo
                     </literallayout>
@@ -628,7 +629,8 @@ Options:
 
                 <para>
                     Here are two examples that create dependency graphs.
-                    The second example omits common depends from the graph:
+                    The second example omits depends common in OpenEmbedded from
+                    the graph:
                     <literallayout class='monospaced'>
      $ bitbake -g foo
 
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 3a19b96303..f7682c0fed 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -41,14 +41,18 @@
                 contents using a syntax that is similar to shell scripting.
                 Following is an example that results in <filename>A</filename>
                 containing "aval" and <filename>B</filename> evaluating to
-                "preavalpost".
+                "preavalpost" based on that current value of
+                <filename>A</filename>.
                 <literallayout class='monospaced'>
      A = "aval"
      B = "pre${A}post"
                 </literallayout>
-                Because the expansion happens later, the value of
-                <filename>B</filename> expands differently if the value
-                of <filename>A</filename> changes.
+                You should realize that whenever <filename>B</filename> is
+                referenced, its evaluation will depend on the state of
+                <filename>A</filename> at that time.
+                Thus, later evaluations of <filename>B</filename> in the
+                previous example could result in different values
+                depending on the value of <filename>A</filename>.
             </para>
         </section>
 
@@ -1387,19 +1391,16 @@
                                 Using "expand=True" expands the value.</entry>
                         </row>
                         <row>
-                            <entry align="left"><filename>d.setVar("X", value)</filename></entry>
-                            <entry align="left">Sets the variable "X" to the value of the Python
-                            variable called "value".</entry>
+                            <entry align="left"><filename>d.setVar("X", "value")</filename></entry>
+                            <entry align="left">Sets the variable "X" to "value".</entry>
                         </row>
                         <row>
-                            <entry align="left"><filename>d.appendVar("X", value)</filename></entry>
-                            <entry align="left">Adds the value of the Python variable called
-                            "value" to the end of the variable "X".</entry>
+                            <entry align="left"><filename>d.appendVar("X", "value")</filename></entry>
+                            <entry align="left">Adds "value" to the end of the variable "X".</entry>
                         </row>
                         <row>
-                            <entry align="left"><filename>d.prependVar("X", value)</filename></entry>
-                            <entry align="left">Adds the value of the Python variable called
-                            "value" to the start of the variable "X".</entry>
+                            <entry align="left"><filename>d.prependVar("X", "value")</filename></entry>
+                            <entry align="left">Adds "value" to the start of the variable "X".</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.delVar("X")</filename></entry>
@@ -1415,18 +1416,17 @@
                                 Using "expand=True" expands the named flag.</entry>
                         </row>
                         <row>
-                            <entry align="left"><filename>d.setVarFlag("X", flag, value)</filename></entry>
-                            <entry align="left">Sets the named flag for variable "X" to the value
-                                of the Python variable called "value".</entry>
+                            <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry>
+                            <entry align="left">Sets the named flag for variable "X" to "value".</entry>
                         </row>
                         <row>
-                            <entry align="left"><filename>d.appendVarFlag("X", flag, value)</filename></entry>
-                            <entry align="left">Appends a value to the named flag on the
+                            <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry>
+                            <entry align="left">Appends "value" to the named flag on the
                             variable "X".</entry>
                         </row>
                         <row>
-                            <entry align="left"><filename>d.prependVarFlag("X", flag, value)</filename></entry>
-                            <entry align="left">Prepends a value to the named flag on
+                            <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry>
+                            <entry align="left">Prepends "value" to the named flag on
                                the variable "X".</entry>
                         </row>
                         <row>
diff --git a/bitbake/doc/user-manual/user-manual-ref-variables.xml b/bitbake/doc/user-manual/user-manual-ref-variables.xml
index b785f04aba..6a5af89ffa 100644
--- a/bitbake/doc/user-manual/user-manual-ref-variables.xml
+++ b/bitbake/doc/user-manual/user-manual-ref-variables.xml
@@ -102,6 +102,15 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-BB_CONSOLELOG'><glossterm>BB_CONSOLELOG</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the path to a log file into which BitBake's user
+                    interface writes output during the build.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-BB_CURRENTTASK'><glossterm>BB_CURRENTTASK</glossterm>
             <glossdef>
                 <para>
@@ -681,12 +690,19 @@
         <glossentry id='var-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm>
             <glossdef>
                 <para>
-                    Lists flags that can be safely excluded from checksum
+                    Lists variable flags (varflags)
+                    that can be safely excluded from checksum
                     and dependency data for keys in the datastore.
                     When generating checksum or dependency data for keys in the
                     datastore, the flags set against that key are normally
                     included in the checksum.
                 </para>
+
+                <para>
+                    For more information on varflags, see the
+                    "<link linkend='variable-flags'>Variable Flags</link>"
+                    section.
+                </para>
             </glossdef>
         </glossentry>
 
@@ -959,7 +975,23 @@
 
         <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
             <glossdef>
-                <para>Variable that controls how BitBake displays logs on build failure.</para>
+                <para>
+                    If set to a value, enables printing the task log when
+                    reporting a failed task.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
+            <glossdef>
+                <para>
+                    If
+                    <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
+                    is set, specifies the maximum number of lines from the
+                    task log file to print when reporting a failed task.
+                    If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
+                    the entire log is printed.
+                </para>
             </glossdef>
         </glossentry>
 
@@ -1483,14 +1515,6 @@
                     the upstream source, and then locations specified by
                     <filename>MIRRORS</filename> in that order.
                 </para>
-
-                <para>
-                    Assuming your distribution (<filename>DISTRO</filename>)
-                    is "poky", the default value for
-                    <filename>MIRRORS</filename> is defined in the
-                    <filename>conf/distro/poky.conf</filename> file in the
-                    <filename>meta-yocto</filename> Git repository.
-                </para>
             </glossdef>
         </glossentry>
 
@@ -1697,15 +1721,6 @@
                 </para>
 
                 <para>
-                    Assuming your distribution
-                    (<filename>DISTRO</filename>)
-                    is "poky", the default value for
-                    <filename>PREMIRRORS</filename> is defined in the
-                    <filename>conf/distro/poky.conf</filename> file in the
-                    <filename>meta-yocto</filename> Git repository.
-                </para>
-
-                <para>
                     Typically, you would add a specific server for the
                     build system to attempt before any others by adding
                     something like the following to your configuration: