toaster-manual: Applied final review edits.

This should be it unless there are late coming comments.

(From yocto-docs rev: cb32e3330a6fe2d26425f8765689749afcd989e9)

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

3 files changed, 113 insertions, 98 deletions

diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
index 05184fa1eb..cc118643cd 100644
--- a/documentation/toaster-manual/toaster-manual-reference.xml
+++ b/documentation/toaster-manual/toaster-manual-reference.xml
@@ -12,19 +12,18 @@
         This final chapter provides conceptual information on layer sources,
         releases, and JSON configuration files.
         Also provided is a quick look at some useful
-        <filename>manage.py</filename> commands.
+        <filename>manage.py</filename> commands that are Toaster-specific.
         Information on <filename>manage.py</filename> commands does exist
         across the Web and the information in this manual by no means
-        attempts to provide a command reference.
-        However, having relevant command useful for the Toaster context
-        is helpful.
+        attempts to provide a command comprehensive reference.
     </para>
 
     <section id='layer-source'>
         <title>Layer Source</title>
 
         <para>
-            In general, a layer source is some source of existing layers.
+            In general, a "layer source" is a source of information about
+            existing layers.
             In particular, we are concerned with layers that you can use
             with the Yocto Project and Toaster.
             This chapter describes a particular type of layer source called
@@ -145,7 +144,7 @@
                 </section>
 
                 <section id='select-the-toasterconf-json-file'>
-                    <title>Select the <filename>toasterconf.json</filename> File</title>
+                    <title>Select for Use the <filename>toasterconf.json</filename> File</title>
 
                     <para>
                         If you do not want to use the Administration
@@ -155,8 +154,8 @@
                     </para>
 
                     <para>
-                        When you set up Toaster in Build Mode, you are prompted to
-                        select a Toaster configuration file.
+                        When you set up Toaster in Build Mode, you are prompted
+                        to select a Toaster configuration file.
                         This configuration file is used to set up the initial
                         configuration values within the Toaster database
                         including the layer sources.
@@ -309,9 +308,8 @@
      $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-yocto/conf/toasterconf.json
                         </literallayout>
                         After entering this command, you need to update the
-                        information from the layer index to populate the
-                        Toaster database with the information from your layer
-                        index.
+                        Toaster database with the information coming from your
+                        new layer source.
                         To do that, you should run the
                         "<filename>lsupdates</filename>" command from the directory
                         that contains the Toaster database.
@@ -329,7 +327,7 @@
                         information is available by using the Toaster web interface.
                         To do that, visit the "All compatible layers" page inside a
                         Toaster project.
-                        The layers from your layer index should be listed there.
+                        The layers from your layer source should be listed there.
                     </para>
                 </section>
             </section>
@@ -340,6 +338,8 @@
         <title>Releases</title>
 
         <para>
+            When you create a Toaster project using the web interface,
+            you are asked to choose a "Release."
             In the context of Toaster, the term "Release" refers to a set of
             layers and a BitBake version the OpenEmbedded build system uses
             to build something.
@@ -347,8 +347,6 @@
             correspond to Yocto Project release branches.
             However, you can modify, delete, and create new releases
             according to your needs.
-            When you create a Toaster project using the web interface,
-            you are asked to choose a "Release."
             This section provides some background information on releases.
         </para>
 
@@ -461,7 +459,7 @@
                                 This name is never exposed through Toaster.
                                 </para></listitem>
                             <listitem><para><emphasis>Git URL:</emphasis>
-                                The URL <filename>giturl</filename>
+                                The URL (<filename>giturl</filename>)
                                 for the BitBake Git repository cloned
                                 for Toaster projects.
                                 </para></listitem>
@@ -493,9 +491,6 @@
                         (<filename>defaultlayers</filename>) automatically
                         added to the project configuration when a project is
                         created.
-                        You can download the recommended configuration
-                        for this case from
-                        <ulink url='&YOCTO_WIKI_URL;/wiki/File:Toasterconf.json.txt.patch'></ulink>.
                         </para></listitem>
                     <listitem><para><emphasis>Layer Source Priorities</emphasis>
                         A specification of
@@ -522,9 +517,11 @@
             <para>
                 To summarize what comprises a release, consider the following
                 example from a Toaster JSON file.
-                The configuration names the release "master" and sets it to
-                use the master branch of the
-                <filename>openembedded-core</filename> layer.
+                The configuration names the release "master" and uses the
+                "master" branch provided by the layer source of type
+                "layerindex", which is called "OpenEmbedded", and sets
+                the <filename>openembedded-core</filename> layer as the one
+                to be added by default to any projects created in Toaster.
                 The BitBake version used would be defined as shown earlier
                 in the previous list:
                 <literallayout class='monospaced'>
@@ -548,13 +545,13 @@
         <title>JSON Files</title>
 
         <para>
-            If you are going to be using the Toaster in Build Mode, it must
+            If you are going to be using Toaster in Build Mode, it must
             be initially configured before use.
             Configuration customizes layer source settings and Toaster defaults
             for all users and is performed by the person responsible for
             Toaster Configuration (i.e  the Toaster Administrator).
             The Toaster Administrator performs this configuration through the
-            admin web interface.
+            Django administration interface.
         </para>
 
         <para>
@@ -575,10 +572,10 @@
             <filename>toasterconf.json</filename>.
             The Toaster Administrator can customize the file prior to loading
             it into Toaster.
-            In the Local Toaster Build Mode, the system startup script
-            actively looks for compatible configuration files and prompts
-            you to select a file to load if it detects that the database has
-            not been configured.
+            When you set up Toaster locally to run in Build Mode, the system
+            startup script actively looks for compatible configuration files
+            and prompts you to select a file to load if it detects that the
+            database has not been configured.
         </para>
 
         <section id='json-file-choices'>
@@ -630,7 +627,7 @@
             <para>
                 The <filename>toasterconf.json</filename> file consists of
                 easily readable areas: configuration, layer sources, BitBake,
-                default, and releases.
+                default release, and releases.
             </para>
 
             <section id='json-config-area'>
@@ -760,8 +757,13 @@
                 <para>
                     This area of the JSON file defines the version of
                     BitBake Toaster uses.
-                    As shipped, Toaster is configured to recognize three
+                    As shipped, Toaster is configured to recognize four
                     versions of BitBake: master, dizzy, and HEAD.
+                    <note>
+                        HEAD is a special option that builds whatever is
+                        available on disk, without checking out any remote
+                        Git repositories.
+                    </note>
                 </para>
 
                 <para>
@@ -937,14 +939,16 @@
                 using the
                 <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link>
                 command.
-                For example, assuming default repository and build directory
-                names, the following two commands put you in the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-                and then return a list of the current builds, which would
-                be one in this case:
+                Here is an example that assumes default repository and build
+                directory names:
                 <literallayout class='monospaced'>
-     $ cd $HOME/poky/build
+     $ cd ~/poky/build
      $ python ../bitbake/lib/toaster/manage.py buildslist
+                </literallayout>
+                If your Toaster database had only one build, the above
+                <filename>buildslist</filename> command would return something
+                like the following:
+                <literallayout class='monospaced'>
      1: qemux86 poky core-image-minimal
                 </literallayout>
             </para>
@@ -1000,7 +1004,7 @@
                 <literallayout class='monospaced'>
      $ bitbake/lib/toaster/manage.py checksettings
                 </literallayout>
-                In Managed Mode, Toaster uses settings that are based on the
+                In Build Mode, Toaster uses settings that are based on the
                 database to configure the building tasks.
                 The <filename>checksettings</filename> command verifies that
                 the database settings are valid in the sense that they have
@@ -1026,8 +1030,8 @@
             <title><filename>loadconf</filename></title>
 
             <para>
-                The <filename>loadconf</filename> command loads a Toaster
-                configuration file (JSON file).
+                The <filename>loadconf</filename> command loads an
+                existing Toaster configuration file (JSON file).
                 You must run this on a new database that does not have any
                 data.
                 Running this command on an existing database that has data
@@ -1037,8 +1041,8 @@
      $ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable>
                 </literallayout>
                 The <filename>loadconf</filename> command configures a database
-                based on the supplied <filename>toasterconf.json</filename>
-                file.
+                based on the supplied existing
+                <filename>toasterconf.json</filename> file.
                 For information on the <filename>toasterconf.json</filename>,
                 see the
                 "<link linkend='toaster-json-files'>JSON Files</link>"
@@ -1050,7 +1054,7 @@
             <title><filename>runbuilds</filename></title>
 
             <para>
-                The <filename>runbuilds</filename> command launched
+                The <filename>runbuilds</filename> command launches
                 scheduled builds.
                 Access the command as follows:
                 <literallayout class='monospaced'>
@@ -1061,8 +1065,8 @@
                 per schedule.
                 The command returns after the builds start but before they
                 complete.
-                The "toasterui" build recorded updates the database when the
-                builds complete.
+                The Toaster Logging Interface records and updates the database
+                when the builds complete.
             </para>
         </section>
     </section>
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index bed38508ff..2a32912e38 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -209,7 +209,7 @@
                         you install and set up a front-end web server.
                         This server allows for load balancing and
                         multi-threading over Toaster and
-                        <filename>django</filename> WSGI.
+                        <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>.
                         Here is an example that uses Apache web server.
                         <literallayout class='monospaced'>
      $ apt-get install apache2 libapache2-mod-wsgi
@@ -282,19 +282,41 @@
                         </para></listitem>
                     <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis>
                         In the Build Directory, create the required
-                        <filename>conf/toaster.conf</filename> file as
-                        described in
-                        <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>.
-                        Briefly, for each Build Directory, you need to inherit
-                        the
-                        <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'>toaster</ulink>
-                        class by setting the following in your
-                        <filename>local.conf</filename> configuration file:
-                        <literallayout class='monospaced'>
+                        <filename>conf/toaster.conf</filename> file by doing
+                        the following:
+                        <note>
+                            The following statements are automatically added
+                            to the <filename>toaster.conf</filename> file
+                            when Toaster starts through the
+                            <filename>toaster start</filename> command.
+                        </note>
+                        <itemizedlist>
+                            <listitem><para>
+                                Be sure that Toaster inherits the
+                                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'><filename>toaster</filename></ulink>
+                                class and it is enabled in Bitbake in order to
+                                record target image package information:
+                                <literallayout class='monospaced'>
      INHERIT += "toaster"
+                                </literallayout>
+                                </para></listitem>
+                            <listitem><para>
+                                Enable build history in BitBake.
+                                Build history is needed to record target image
+                                package information:
+                                <literallayout class='monospaced'>
      INHERIT += "buildhistory"
      BUILDHISTORY_COMMIT = "1"
-                        </literallayout>
+                                </literallayout>
+                                This last command is not strictly needed.
+                                However, without it build history will not
+                                properly work.
+                                For information on build history, see the
+                                "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+                                section in the Yocto Project Development
+                                Manual.
+                                </para></listitem>
+                        </itemizedlist>
                         You also need to point to the database.
                         You can do this by exporting the
                         <filename>DATABASE_URL</filename> variable as follows:
@@ -434,8 +456,7 @@
                         Toaster configuration file.
                         Toaster configurations are stored in
                         JSON files called
-                        <filename>toasterconf.json</filename> and supports
-                        several types.
+                        <filename>toasterconf.json</filename>.
                         For information on JSON files, see the
                         "<link linkend='toaster-json-files'>JSON Files</link>"
                         section.</para>
@@ -498,27 +519,6 @@
      MANAGED="True"
                         </literallayout>
                         </para></listitem>
-                    <listitem><para><emphasis>Configure the Build Environment:</emphasis>
-                        Configure the build environment by running the
-                        following:
-                        <literallayout class='monospaced'>
-     bitbake/lib/toaster/manage.py checksettings
-                        </literallayout>
-                        For reference information on Toaster-specific
-                        <filename>manage.py</filename> commands, see the
-                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
-                        section.
-                        </para></listitem>
-                    <listitem><para><emphasis>Load a Configuration File:</emphasis>
-                        Load a configuration file by running the following:
-                        <literallayout class='monospaced'>
-     bitbake/lib/toaster/manage.py loadconf <replaceable>path-to-toasterconf.json-file</replaceable>
-                        </literallayout>
-                        For reference information on Toaster-specific
-                        <filename>manage.py</filename> commands, see the
-                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
-                        section.
-                        </para></listitem>
                     <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis>
                         You need to configure each build environment, layer
                         sources, and BitBake versions.</para>
@@ -675,7 +675,7 @@
                         build artifacts, downloading sources, and running
                         builds.
                         All three directories need to be writable by
-                        the "poky" user.
+                        the user, which is "poky" in this example.
                         The build artifacts directory needs to readable by the
                         apache user.
                         You also need free disk space in the range of
@@ -688,33 +688,42 @@
                         </literallayout>
                         </para></listitem>
                     <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis>
-                        Download the <filename>toasterconf.json</filename> file
-                        from the
-                        <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
-                        wiki page and edit it to suit your environment.
+                        <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>Download the hosted <filename>toasterconf.json</filename> file</ulink>
+                        from the Yocto Project wiki and edit it to suit your
+                        environment.
                         For information on the relevant sections of the file,
                         see the
                         "<link linkend='toaster-json-files'>JSON Files</link>"
+                        section.</para>
+                        <para>After editing the file, load it by running
+                        the following:
+                        <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file
+                        </literallayout>
+                        For reference information on Toaster-specific
+                        <filename>manage.py</filename>, see the
+                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
                         section.
                         </para></listitem>
                     <listitem><para><emphasis>Check the Toaster Settings:</emphasis>
-                        You can check the Toaster settings by running this
-                        command:
+                        Configure the build environment by running the
+                        following:
                         <literallayout class='monospaced'>
      $ bitbake/lib/toaster/manage.py checksettings
                         </literallayout>
                         When prompted, paste in the directory paths created
-                        previously during Step 9.
-                        Alternatively, you can select the edited
-                        <filename>toasterconf.json</filename> file set up in
-                        Step 5.
+                        previously during Step 7.
+                        For reference information on Toaster-specific
+                        <filename>manage.py</filename>, see the
+                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+                        section.
                         </para></listitem>
                     <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
                         For a production environment, it is recommended that
                         you install and set up a front-end web server.
                         This server allows for load balancing and
                         multi-threading over Toaster and
-                        <filename>django</filename> WSGI.
+                        <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>.
                         Here is an example that uses Apache web server:
                         <literallayout class='monospaced'>
      $ apt-get install apache2 libapache2-mod-wsgi
@@ -764,7 +773,7 @@
                         </literallayout>
                         </para></listitem>
                     <listitem><para><emphasis>Start Toaster:</emphasis>
-                        Synchronize the databases for toaster, and then start
+                        Synchronize the databases for Toaster, and then start
                         up the web server.
                         Here is an example that continues with the assumed
                         components from the previous steps:
@@ -803,13 +812,13 @@
                     <listitem><para><emphasis>Open the Browser:</emphasis>
                         Once the Apache server is running, connect to it with
                         your favorite browser and verify that the Toaster
-                        interface comes up.
-                        You can track accesses and errors in the Apache
-                        service logs:
+                        interface comes up:
                         <literallayout class='monospaced'>
      http://localhost:8000/toastergui
                         </literallayout>
-                        You can now use the Toaster web interface.
+                        You can now use the Toaster web interface to do thing
+                        such as track accesses and errors in the Apache
+                        service logs.
                         </para></listitem>
                 </orderedlist>
             </para>
@@ -823,8 +832,10 @@
             The Toaster web interface allows you to do the following:
             <itemizedlist>
                 <listitem><para>
-                    Browse all OpenEmbedded layers available for your
-                    selected version of the build system
+                    Browse published layers in the
+                    <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink>
+                    that are available for your selected version of the build
+                    system.
                     </para></listitem>
                 <listitem><para>
                     Import your own layers for building.
diff --git a/documentation/toaster-manual/toaster-manual.xml b/documentation/toaster-manual/toaster-manual.xml
index 7371ca2b8d..b53277fa69 100644
--- a/documentation/toaster-manual/toaster-manual.xml
+++ b/documentation/toaster-manual/toaster-manual.xml
@@ -33,7 +33,7 @@
         <revhistory>
             <revision>
                 <revnumber>1.8</revnumber>
-                <date>Sometime in 2015</date>
+                <date>October 2015</date>
                 <revremark>Released with the Yocto Project 1.8 Release.</revremark>
             </revision>
        </revhistory>
@@ -51,7 +51,7 @@
       <note>
           For the latest version of this manual associated with this
           Yocto Project release, see the
-          <ulink url='&YOCTO_DOCS_ADT_URL;'>Toaster User Manual</ulink>
+          <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>
           from the Yocto Project website.
       </note>