documentation: Updated the section on creating a general script

Split this section into two sections: one for creating the layer
using bitbake-layers create-layer and one for adding the layer
to bblayers.conf using bitbake-layers add-layer.

Needed to update some references in the yocto-project-qs and
kernel-dev manuals.

(From yocto-docs rev: 741a29b0cbeaaeaa0ac9155036ace2623938aee3)

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

3 files changed, 53 insertions, 15 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 20f97b9f86..11b53ac116 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -966,11 +966,24 @@
                 The <filename>bitbake-layers</filename> script with the
                 <filename>create-layer</filename> subcommand simplifies
                 creating a new general layer.
-                <note>
-                    For information on BSP layers, see the
-                    "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
-                    section in the Yocto Project Board Specific (BSP)
-                    Developer's Guide.
+                <note><title>Notes</title>
+                    <itemizedlist>
+                        <listitem><para>
+                            For information on BSP layers, see the
+                            "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+                            section in the Yocto Project Board Specific (BSP)
+                            Developer's Guide.
+                            </para></listitem>
+                        <listitem><para>
+                            In order to use a layer with the OpenEmbedded
+                            build system, you need to add the layer to your
+                            <filename>bblayers.conf</filename> configuration
+                            file.
+                            See the
+                            "<link linkend='adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</link>"
+                            section for more information.
+                            </para></listitem>
+                    </itemizedlist>
                 </note>
                 The default mode of the script's operation with this
                 subcommand is to create a layer with the following:
@@ -1009,6 +1022,13 @@
                 <literallayout class='monospaced'>
      $ bitbake-layers create-layer <replaceable>your_layer_name</replaceable>
                 </literallayout>
+                As an example, the following command adds a layer named
+                <filename>meta-scottrif</filename>:
+                <literallayout class='monospaced'>
+     $ bitbake-layers create-layer meta-scottrif
+     NOTE: Starting bitbake server...
+     Add your new layer with 'bitbake-layers add-layer meta-scottrif'
+                </literallayout>
             </para>
 
             <para>
@@ -1051,19 +1071,31 @@
                              Filename of the example recipe
                 </literallayout>
             </para>
+        </section>
+
+        <section id='adding-a-layer-using-the-bitbake-layers-script'>
+            <title>Adding a Layer Using the <filename>bitbake-layers</filename> Script</title>
 
             <para>
                 Once you create your general layer, you must add it to your
                 <filename>bblayers.conf</filename> file.
-                You can add your layer by using the
+                Adding the layer to this configuration file makes the
+                OpenEmbedded build system aware of your layer so that it can
+                search it for metadata.
+            </para>
+
+            <para>
+                Add your layer by using the
                 <filename>bitbake-layers add-layer</filename> command:
                 <literallayout class='monospaced'>
      $ bitbake-layers add-layer <replaceable>your_layer_name</replaceable>
                 </literallayout>
-                Here is an example where a layer named
-                <filename>meta-scottrif</filename> is added and then the
-                layers are shown using the
-                <filename>bitbake-layers show-layers</filename> command:
+                Here is an example that adds a layer named
+                <filename>meta-scottrif</filename> to the configuration file.
+                Following the command that adds the layer is another
+                <filename>bitbake-layers</filename> command that shows the
+                layers that are in your <filename>bblayers.conf</filename>
+                file:
                 <literallayout class='monospaced'>
      $ bitbake-layers add-layer meta-scottrif
      NOTE: Starting bitbake server...
@@ -1081,6 +1113,11 @@
                 </literallayout>
                 Adding the layer to this file enables the build system to
                 locate the layer during the build.
+                <note>
+                    During a build, the OpenEmbedded build system looks in
+                    the layers from the top of the list down to the bottom
+                    in that order.
+                </note>
                 </para>
         </section>
     </section>
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 1ea5ca53d2..9686609bf5 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -136,7 +136,7 @@
                             Developer's Guide, respectively.
                             For information on how to use the
                             <filename>bitbake-layers create-layer</filename>
-                            command, see the
+                            command to quickly set up a layer, see the
                             "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
                             section in the Yocto Project Development Tasks
                             Manual.
@@ -360,7 +360,7 @@
                             Developer's Guide, respectively.
                             For information on how to use the
                             <filename>bitbake-layers create-layer</filename>
-                            command, see the
+                            command to quickly set up a layer, see the
                             "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
                             section in the Yocto Project Development Tasks
                             Manual.
@@ -489,7 +489,8 @@
                 See the
                 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
                 section in the Yocto Project Development Tasks Manual for
-                information on how to use this script.
+                information on how to use this script to quick set up a
+                new layer.
             </note>
         </para>
 
diff --git a/documentation/yocto-project-qs/qs.xml b/documentation/yocto-project-qs/qs.xml
index 23553f3516..2e5defe6a0 100644
--- a/documentation/yocto-project-qs/qs.xml
+++ b/documentation/yocto-project-qs/qs.xml
@@ -971,8 +971,8 @@
                         section in the same manual.
                         </para></listitem>
                     <listitem><para>
-                        <emphasis>Add a Layer for Software:</emphasis>
-                        For steps on how to add a general layer for software,
+                        <emphasis>Create a Layer for Software:</emphasis>
+                        For steps on how to create a general layer for software,
                         see the
                         "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
                         section in the Yocto Project Development Tasks Manual.