toaster-manual: 2nd draft for review.

Fixes [YOCTO #6901]

This is the 2nd review draft of the manual.

(From yocto-docs rev: 9f541e4421e0e74e59e3b3da1896b6c1254daf08)

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

3 files changed, 374 insertions, 290 deletions

diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml
index 36c3b6bdc0..378f33420c 100644
--- a/documentation/toaster-manual/toaster-manual-intro.xml
+++ b/documentation/toaster-manual/toaster-manual-intro.xml
@@ -6,10 +6,13 @@
 <title>Introduction</title>
 
     <para>
-        Toaster is an Application Programming Interface (API) and
-        web-based interface to the OpenEmbedded build system, which uses
+        Toaster is web interface to the OpenEmbedded build system, which uses
         BitBake.
-        Both interfaces are based on a Representational State Transfer
+        The interface allows you to access a datastore that retains build
+        information and report out on the information.
+    </para>
+<!--THE FOLLOWING IS DETAIL THAT I THINK BELEN WANTED OUT FOR THE MOMENT
+        The interface is based on a Representational State Transfer
         (REST) API that queries for and returns build information using
         <filename>GET</filename> and <filename>JSON</filename>.
         These types of search operations retrieve sets of objects from
@@ -18,64 +21,95 @@
         You can order the results of the search by key and the search
         parameters are consistent for all object types.
     </para>
+-->
 
     <para>
         You can use Toaster in several different modes:
         <itemizedlist>
-            <listitem><para><emphasis>Interactive Mode:</emphasis>
+            <listitem><para><emphasis>Analysis Mode:</emphasis>
                 In this mode, you can record builds and statistics.
-                In Interactive Mode, you have direct access to the
+                In Analysis Mode, you have direct access to the
                 <filename>bitbake</filename> command, which you use to build
-                images.
+                images.</para>
+                <para>Analysis Mode requires you to have first started
+                Toaster and then to initiate your build using the
+                <filename>bitbake</filename> command from the shell.
+                Toaster must be started before the build or it will not
+                collect build data.
                 </para></listitem>
-            <listitem><para><emphasis>Managed Mode:</emphasis>
+            <listitem><para><emphasis>Build Mode:</emphasis>
                 In this mode, Toaster handles the build configuration GUI
-                (through Project pages) and build scheduling and execution.
-                Additionally, in addition to these features, builds are
-                triggered through the web interface.
+                (through project pages) and build scheduling and execution.
+                In this mode, all your interaction with the build system
+                happens through the web interface.
                 You do not have direct access to the
                 <filename>bitbake</filename> command.</para>
-
-                <para>Managed Mode also works two separate ways: Local
-                Managed Mode and Remote Managed Mode.
-                Local Managed Mode is the out-of-box mode available once
-                you checkout poky and allows you to perform builds on your
-                local machine.
-                Remote Managed Mode, also known as Hosted Toaster, is a
-                production setup best for organizations supporting multiple
-                users and for organizations using customized Toaster
-                installations.
+                <para>Using this mode, you configure and start your builds
+                with Toaster's GUI.
+                Each configuration is a project, which requires version and
+                build system selection.
+                As shipped, Toaster supports the Yocto Project releases
+                1.8 and beyond.
+                Aside from these supported releases, you can also select
+                the "Local Yocto Project", which allows you to use your
+                local clone of the Yocto Project
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                (e.g. <filename>poky</filename>).</para>
+                <para>Build Mode also works two separate ways: locally and
+                remotely.
+                While you can use Build Mode locally, it is best to use
+                Toaster's Build Mode through a hosted service where it can
+                shared by multiple user.
                 </para></listitem>
         </itemizedlist>
     </para>
 
     <para>
-        Using the interfaces you can do the following:
+        Using Toaster, you can do the following:
+        <note><title>REVIEWER NOTE</title>
+            Belen suggested we split this list out into things that
+            Analysis Mode and Build Mode can do.
+            Also, we can structure the lists so the Build Mode list
+            leverages off what is listed for Analysis Mode.
+            I do not know the information for the complete lists.
+            Someone needs to help me out here.
+            For now, I am leaving the list as follows and will need some
+            information.
+        </note>
         <itemizedlist>
-            <listitem><para>See information about the tasks executed
-                and reused during the build.</para></listitem>
-            <listitem><para>See what is built (recipes and
+            <listitem><para>
+                See information about the tasks executed
+                and reused during the build.
+                </para></listitem>
+            <listitem><para>
+                See what is built (recipes and
                 packages) and what packages were installed into the final
-                image.</para></listitem>
-            <listitem><para>See performance-related information such
-                as build time, CPU usage, and disk I/O.</para></listitem>
-            <listitem><para>Examine error, warning and trace messages
-                to aid in debugging.</para></listitem>
+                image.
+                </para></listitem>
+            <listitem><para>
+                See performance-related information such
+                as build time, CPU usage, and disk I/O.
+                </para></listitem>
+            <listitem><para>
+                Examine error, warning and trace messages
+                to aid in debugging.
+                </para></listitem>
         </itemizedlist>
     </para>
 
     <note>
         <para>
-            This release of Toaster provides you with information
-            about a BitBake run.
-            The tool does not allow you to configure and launch a build.
-            However, future development includes plans to integrate the
-            configuration and build launching capabilities of
+            This release of Toaster does allow you to configure and initiate
+            builds.
+            However, you cannot use Toaster to customize image recipes, which
+            still must either be done by hand or through
             <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
+            As Toaster matures, it eventually will equal and surpass Hob
+            functionality, at which time Hob will be deprecated.
         </para>
 
         <para>
-            For more information on using Hob to build an image,
+            For more information on Hob,
             see the
             "<ulink url='&YOCTO_DOCS_DEV_URL;#image-development-using-hob'>Image Development Using Hob</ulink>"
            section in the Yocto Project Development Manual.
@@ -85,6 +119,9 @@
     <para>
         The remainder of this manual describes what you need to have in
         place to use Toaster, how to start it, use it, and stop it.
+    </para>
+
+<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY
         For additional information on installing and running Toaster, see the
         "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
         section of the "Toaster" wiki page.
@@ -93,7 +130,5 @@
         <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
         Wiki page.
     </para>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
 -->
+</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index ac9e9313ff..f56d67ed37 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -7,273 +7,317 @@
 <title>Setting Up and Using Toaster</title>
 
     <para>
-        You can set up local and production instances of Toaster.
-        This chapter describes how to set up both these types of instances.
+        You can set up Toaster as a local instance or as a hosted service.
+        Furthermore, you can use Toaster in Analysis Mode or Build Mode
+        from both set ups.
     </para>
 
-    <section id='toaster-setting-up-a-local-instance'>
-        <title>Setting Up a Local Instance</title>
+    <section id='using-toaster-in-analysis-mode'>
+        <title>Using Toaster in Analysis Mode</title>
 
         <para>
-            Follow these steps to set up and run a local instance of Toaster:
-            <orderedlist>
-                <listitem><para><emphasis>Prepare your build system:</emphasis>
-                    Be sure your system has the Toaster requirements
-                    by following the steps in the
-                    "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
-                    section.
-                    </para></listitem>
-                <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
-                    Get the requirements set up so that you can use the
-                    Yocto Project to build images.
-                    See the
-                    "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
-                    section in the Yocto Project Quick Start for information.
-                    </para></listitem>
-                <listitem><para><emphasis>Be sure Ports are free:</emphasis>
-                    Make sure that port 8000 and 8200 are free.
-                    In other words, make sure the ports do not have servers
-                    on them.
-                    </para></listitem>
-                <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
-                    From your
-                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-                    (e.g. <filename>poky/build</filename>), source the build
-                    environment setup script (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>).
-                    </para></listitem>
-                <listitem><para><emphasis>Start Toaster:</emphasis>
-                    From the
-                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
-                    start Toaster:
-                    <literallayout class='monospaced'>
-     $ source toaster start
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para><emphasis>Start Your Build using BitBake:</emphasis>
-                    Use the <filename>bitbake</filename> command to start your
-                    build.
-                    Here is an example that builds the
-                    <filename>core-image-minimal</filename> image:
-                    <literallayout class='monospaced'>
-     $ bitbake core-image-minimal
-                    </literallayout>
-                    </para></listitem>
-            </orderedlist>
+            This section describes how to use Toaster in Analysis Mode
+            after setting Toaster up as a local instance or as a hosted
+            service.
         </para>
 
-        <para>
-            For information on how to use Toaster, see the
-            "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
-            section.
-        </para>
-    </section>
+        <section id='setting-up-locally-and-running-in-analysis-mode'>
+            <title>Setting Up Locally and Running in Analysis Mode</title>
 
-    <section id='toaster-setting-up-a-production-instance'>
-        <title>Setting Up a Production Instance</title>
+            <para>
+                Follow these steps to set up a local instance of Toaster and
+                then run in Analysis Mode:
+                <orderedlist>
+                    <listitem><para><emphasis>Prepare your Build System:</emphasis>
+                        Be sure your system has the Toaster requirements
+                        by following the steps in the
+                        "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
+                        Get the requirements set up so that you can use the
+                        Yocto Project to build images.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
+                        section in the Yocto Project Quick Start for information.
+                        </para></listitem>
+                    <listitem><para><emphasis>Be Sure Ports are Free:</emphasis>
+                        Make sure that port 8000 and 8200 are free.
+                        In other words, make sure the ports do not have servers
+                        on them.
+                        </para></listitem>
+                    <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
+                        From your
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                        (e.g. <filename>poky/build</filename>), source the build
+                        environment setup script (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>).
+                        </para></listitem>
+                    <listitem><para><emphasis>Start Toaster:</emphasis>
+                        From the
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+                        start Toaster:
+                        <literallayout class='monospaced'>
+     $ source toaster start
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Start Your Build Using BitBake:</emphasis>
+                        Use the <filename>bitbake</filename> command to start your
+                        build.
+                        Here is an example that builds the
+                        <filename>core-image-minimal</filename> image:
+                        <literallayout class='monospaced'>
+     $ bitbake core-image-minimal
+                        </literallayout>
+                        </para></listitem>
+                </orderedlist>
+            </para>
 
-        <para>
-            A production instance of Toaster resides on a server and allows
-            multiple users to take advantage of Toaster.
-            In a production environment, you might want to have multiple
-            instances of Toaster running on various remote build machines.
-            You can create this situation by basically modifying how Toaster
-            starts.
-        </para>
+            <para>
+                For information on how to use Toaster, see the
+                "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
+                section.
+            </para>
+        </section>
 
-        <para>
-            Starting Toaster with the <filename>toaster</filename> command
-            (i.e. the script), causes three things to start:
-            <itemizedlist>
-                <listitem><para>
-                    The BitBake server.
-                    </para></listitem>
-                <listitem><para>
-                     the Toaster User Interface, which connects to the
-                     BitBake server on one side and to the SQL
-                     database on the other side.
-                     </para></listitem>
-                <listitem><para>
-                     The web server, which reads the database and displays the
-                     web user interface.
-                     </para></listitem>
-            </itemizedlist>
-            Rather than starting Toaster with the script, you can set up
-            and start multiple instances of Toaster by manually starting
-            as many or few of these three components across your environment.
-            This is possible because it is not required that Toaster starts
-            all three of its separate components in order to run.
-            Minimally, an instance of Toaster requires just one of the
-            components.
-        </para>
+        <section id='setting-up-a-hosted-service-and-running-in-analysis-mode'>
+            <title>Setting Up a Hosted Service and Running in Analysis Mode</title>
 
-        <para>
-            The concepts for setting up multiple instances of Toaster revolve
-            around maintaining a common SQL database and Web server that
-            show data from that common database as well as setting up
-            separate instances of BitBake servers and Toaster user interfaces
-            for each separate BitBake build directory.
-            The common SQL database and the Web server show data from all the
-            various BitBake builds.
-            Setting the SQL database outside of any
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-            maintains a separation layer between the various builds.
-            The database is persistent because the logging database is set
-            up external to the database server (e.g. MySQL).
-            It is not even necessary to run the BitBake servers, the SQL
-            server, and the Web server on the same machine.
-            Each component can be run on its own machine.
-        </para>
+            <para>
+                A hosted service resides on a server and allows
+                multiple users to take advantage of Toaster.
+                In a production environment, you might want to have multiple
+                local instances of Toaster, which run on various remote
+                build machines, and have those local instances access and use
+                a single hosted Toaster service.
+            </para>
 
-        <para>
-            Follow these steps to set up and run a production instance of
-            Toaster:
-            <orderedlist>
-                <listitem><para><emphasis>Prepare your build system:</emphasis>
-                    Be sure your system has the Toaster requirements
-                    by following the steps in the
-                    "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
-                    section.
-                    </para></listitem>
-                <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
-                    Get the requirements set up so that you can use the
-                    Yocto Project to build images.
-                    See the
-                    "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
-                    section in the Yocto Project Quick Start for information.
-                    </para></listitem>
-                <listitem><para><emphasis>Be sure Ports are free:</emphasis>
-                    Make sure that port 8000 and 8200 are free.
-                    In other words, make sure the ports do not have servers
-                    on them.
-                    </para></listitem>
-                <listitem><para><emphasis>Set up the SQL Logging Server and the Web Server:</emphasis>
-                    You can use any SQL server out of the box (e.g.
-                    <filename>mysgl-server</filename> for an Ubuntu build
-                    system).
-                    <note>
-                        If you are concerned about performance, you might want
-                        to hand-tune the server.
-                    </note>
-                    You must set up proper username and password access for
-                    the server for everyone that will be using Toaster.
-                    You need administration rights for the
-                    <filename>mysql</filename> root account, which is not the
-                    same thing as root access on the machine.</para>
+            <para>
+                Starting Toaster with the <filename>toaster</filename> command
+                (i.e. the script), causes three things to start:
+                <itemizedlist>
+                    <listitem><para>
+                        The BitBake server.
+                        </para></listitem>
+                    <listitem><para>
+                        The Toaster User Interface, which connects to the
+                        BitBake server on one side and to the SQL
+                        database on the other side.
+                        </para></listitem>
+                    <listitem><para>
+                        The web server, which reads the database and displays
+                        the web user interface.
+                        </para></listitem>
+                </itemizedlist>
+                Rather than starting Toaster with the script, you can set up
+                and start multiple instances of Toaster by manually starting
+                as many or few of these three components across your
+                environment.
+                This is possible because it is not required that Toaster starts
+                all three of its separate components in order to run.
+                Minimally, a local instance of Toaster requires just one of the
+                components.
+            </para>
 
-                    <para>Clone a separate, local Git repository of the
-                    Toaster master branch to use for running the Web server:
-                    <literallayout class='monospaced'>
-     $ git clone (NEED THE GIT REPO URL HERE)
-                    </literallayout>
-                    You do not perform builds on this tree.
-                    You need to create this local repository away from any
-                    build areas.</para>
+            <para>
+                The concepts for setting up multiple local instances of
+                Toaster that share a single hosted service revolve
+                around maintaining a common SQL database and Web server that
+                shows data from that common database as well as setting up
+                separate local instances of BitBake servers and Toaster user
+                interfaces for each of those separate BitBake build
+                directories.
+            </para>
 
-                    <para>In the separately cloned tree for the Web server,
-                    edit the
-                    <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
-                    file so that the <filename>DATABASES</filename> value
-                    points to the previously created database server.
-                    Use the username and password established earlier.</para>
+            <para>
+                The common SQL database and the Web server show data from
+                all the various BitBake builds.
+                Setting the SQL database outside of any
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                maintains a separation layer between the various local builds
+                and the common database.
+                The database is persistent because the logging database is set
+                up external to the BitBake database server (e.g. MySQL).
+                It is not even necessary to run the BitBake servers, the SQL
+                server, and the Web server on the same machine.
+                Each component can be run on its own machine.
+            </para>
 
-                    <para>Run the database sync scripts to create the needed
-                    tables as follows:
-                    <literallayout class='monospaced'>
+            <para>
+                Follow these steps to set up and run a hosted service and run
+                Toaster in Analysis Mode:
+                <orderedlist>
+                    <listitem><para><emphasis>Prepare your Build System:</emphasis>
+                        Be sure your system has the Toaster requirements
+                        by following the steps in the
+                        "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
+                        Get the requirements set up so that you can use the
+                        Yocto Project to build images.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
+                        section in the Yocto Project Quick Start for information.
+                        </para></listitem>
+                    <listitem><para><emphasis>Be Sure Ports are Free:</emphasis>
+                        Make sure that port 8000 and 8200 are free.
+                        In other words, make sure the ports do not have servers
+                        on them.
+                        </para></listitem>
+                    <listitem><para><emphasis>Set up the SQL Logging Server and the Web Server:</emphasis>
+                        You can use any SQL server out of the box (e.g.
+                        <filename>mysgl-server</filename> for an Ubuntu build
+                        system).
+                        <note>
+                            If you are concerned about performance, you might
+                            want to hand-tune the server.
+                        </note>
+                        You must set up proper username and password access on
+                        the shared server for everyone that will be using
+                        Toaster.
+                        You need administration rights for the
+                        <filename>mysql</filename> root account, which is not
+                        the same thing as root access on the machine.</para>
+                        <para>Clone a separate, local Git repository of the
+                        Toaster master branch to use for running the Web
+                        server.
+                        The Git repository for Toaster is part of the
+                        Yocto Project
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                        Consequently, you just need to set up a separate
+                        local clone of the Yocto Project Source Directory
+                        (e.g. <filename>poky</filename>):
+                        <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/poky
+                        </literallayout>
+                        You do not perform builds on this tree.
+                        You need to create this local repository away from any
+                        build areas.</para>
+                        <para>In the separately cloned tree for the Web server,
+                        edit the
+                        <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
+                        file so that the <filename>DATABASES</filename> value
+                        points to the previously created database server.
+                        Use the username and password established
+                        earlier.</para>
+                        <para>Run the database sync scripts to create the
+                        needed tables as follows:
+                        <literallayout class='monospaced'>
      $ python bitbake/lib/toaster/manage.py syncdb
      $ python bitbake/lib/toaster/manage.py migrate orm
-                    </literallayout>
-                    You can start the web server in the foreground or the
-                    background using these commands, respectively:
-                    <literallayout class='monospaced'>
+                        </literallayout>
+                        You can start the Web server in the foreground or the
+                        background using these commands, respectively:
+                        <literallayout class='monospaced'>
      $ python bitbake/lib/toaster/manage.py runserver
      $ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log &amp;
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using</emphasis>
-                    For each build system that will be using Toaster and the
-                    SQL server, you need to edit the
-                    <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
-                    to alter the <filename>DATABASES</filename> value to point
-                    to the common SQL logging server.
-                    (I DON'T SEE HOW TO DO THIS FROM THE WIKI - I NEED MORE
-                    CLARIFICATION).</para>
-
-                    <para>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'>
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis>
+                        For each build system that will be using Toaster and
+                        the shared SQL server, you need to edit the
+                        <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
+                        file to alter the <filename>DATABASES</filename> value
+                        so that it points to the common SQL logging server.
+                        <note><title>REVIEWER NOTE</title>
+                            I don't see how to do this from the Wiki.
+                            I need more clarification.
+                        </note></para>
+                        <para>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'>
      INHERIT += "toaster"
      INHERIT += "buildhistory"
      BUILDHISTORY_COMMIT = "1"
-                    </literallayout>
-                    Start the BitBake server using the following command:
-                    <literallayout class='monospaced'>
-     $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
-                    </literallayout>
-                    Start the logging user interface using the following
-                    command:
-                    <literallayout class='monospaced'>
-     $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &amp;
-                    </literallayout>
-                    <note>
-                        No hard-coded ports are used as there is enough code
-                        to run <filename>autodiscovery</filename>
-                        for ports to prevent collisions.
-                    </note>
-                    </para></listitem>
-                <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
-                    From your
-                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-                    on each of the build systems,
-                    (e.g. <filename>poky/build</filename>), source the build
-                    environment setup script (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>).
-                    </para></listitem>
-                <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
-                    Use the <filename>bitbake</filename> command to start a
-                    build on a build system.
-                    Here is an example that builds the
-                    <filename>core-image-minimal</filename> image:
-                    <literallayout class='monospaced'>
+                        </literallayout>
+                        Start the BitBake server using the following command:
+                        <literallayout class='monospaced'>
+     $ bitbake &dash;&dash;postread conf/toaster.conf &dash;&dash;server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
+                        </literallayout>
+                        Start the logging user interface using the following
+                        command:
+                        <literallayout class='monospaced'>
+     $ nohup bitbake &dash;&dash;observe-only -u toasterui >toaster_ui.log &amp;
+                        </literallayout>
+                        <note>
+                            No hard-coded ports are used as there is enough code
+                            to run <filename>autodiscovery</filename>
+                            for ports to prevent collisions.
+                        </note>
+                        </para></listitem>
+                    <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
+                        From your
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                        on each of the build systems,
+                        (e.g. <filename>poky/build</filename>), source the
+                        build environment setup script (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>).
+                        </para></listitem>
+                    <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
+                        Use the <filename>bitbake</filename> command to start a
+                        build on a build system.
+                        Here is an example that builds the
+                        <filename>core-image-minimal</filename> image:
+                        <literallayout class='monospaced'>
      $ bitbake core-image-minimal
-                    </literallayout>
-                    When you are finished with a build in a given
-                    Build Directory, be sure to <filename>kill</filename>
-                    the BitBake server for that build area:
-                    <literallayout class='monospaced'>
+                        </literallayout>
+                        When you are finished with a build in a given
+                        Build Directory, be sure to <filename>kill</filename>
+                        the BitBake server for that build area:
+                        <literallayout class='monospaced'>
      $ bitbake -m
-                    </literallayout>
-                    </para></listitem>
-            </orderedlist>
-        </para>
+                        </literallayout>
+                        </para></listitem>
+                </orderedlist>
+            </para>
 
-        <para>
-            For information on how to use Toaster, see the
-            "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
-            section.
-        </para>
+            <para>
+                For information on how to use Toaster, see the
+                "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
+                section.
+            </para>
+        </section>
     </section>
 
-    <section id='setting-up-a-hosted-managed-mode-for-toaster'>
-        <title>Setting Up a Hosted Managed Mode for Toaster</title>
+    <section id='using-toaster-in-build-mode'>
+        <title>Using Toaster in Build Mode</title>
 
         <para>
-            (RIGHT NOW, THE
-            <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_hosted_managed_mode_for_Toaster'>WIKI PAGE</ulink>
-            HAS SOME INFORMATION ON THIS.
-            I DON'T GET IT THOUGH.
-            I NEED SOME MORE INFORMATION IN ORDER TO UNDERSTAND THIS AND
-            CREATE A SECTION.
+            This section describes how to use Toaster in Build Mode
+            after setting Toaster up as a local instance or as a hosted
+            service.
         </para>
+
+        <section id='setting-up-locally-and-running-in-build-mode'>
+            <title>Setting Up Locally and Running in Build Mode</title>
+
+            <note><title>REVIEWER NOTE</title>
+                I need the information on how to do this.
+            </note>
+        </section>
+
+        <section id='setting-up-a-hosted-service-and-running-in-build-mode'>
+            <title>Setting Up a Hosted Service and Running in Build Mode</title>
+
+            <note><title>REVIEWER NOTE</title>
+                Right now, the
+                <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_hosted_managed_mode_for_Toaster'>WIKI PAGE</ulink>
+                has some information on this but I don't understand it.
+                I need more information.
+            </note>
+        </section>
     </section>
 
     <section id='using-the-toaster-interface'>
@@ -312,15 +356,12 @@
             Toaster interface, see the
             <ulink url='https://www.yoctoproject.org/documentation/toaster-manual-17'>Toaster Documentation</ulink>
             on the Yocto Project website.
-            (SO WE NEED TO DECIDE IF THESE VIDS ARE GOING TO ROLL OVER INTO
-            1.8 AND REMAIN ON A "TOASTER MANUAL" PAGE AS THEY DO IN 1.7.
-            OR, IF WE ARE GOING TO GET THE LINKS TO THE VIDS HERE IN THIS
-            MANUAL.)
+            <note><title>REVIEWER NOTE</title>
+               We have agreed to get rid of the manual page on the website,
+               contains the links to the GUI videos.
+               We have agreed to host the videos on Vimeo and to embed the
+               videos in this new Toaster manual.
+            </note>
         </para>
     </section>
 </chapter>
-
-
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
index 93f48c7b26..b884036035 100644
--- a/documentation/toaster-manual/toaster-manual-start.xml
+++ b/documentation/toaster-manual/toaster-manual-start.xml
@@ -9,8 +9,8 @@
     <para>
         This chapter describes how you need to prepare your system in order to
         use Toaster.
-        Toaster requires some packages that you must have installed before trying
-        to run Toaster.
+        Toaster requires some packages that you must have installed before
+        trying to run Toaster.
     </para>
 
     <section id='toaster-setting-up-the-basic-system-requirements'>
@@ -47,6 +47,17 @@
             </literallayout>
             Follow these steps to get set up:
             <orderedlist>
+                <listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis>
+                    <filename>virtualenv</filename> is a tool to create
+                    isolated Python environments by creating folders that
+                    contain all the necessary executables to use the packages
+                    that Python projects need.
+                    You can use <filename>pip</filename> to install
+                    <filename>virtualenv</filename>:
+                    <literallayout class='monospaced'>
+     $ pip install virtualenv
+                    </literallayout>
+                    </para></listitem>
                 <listitem><para><emphasis>Create and activate a virtual environment:</emphasis>
                     <literallayout class='monospaced'>
      $ virtualenv venv
@@ -70,6 +81,3 @@
     </section>
 
 </chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->