[gnome-continuous-yocto/gnomeostree-3.28-rocko: 7920/8267] ref-manual: Updated Added a New Recipe to Workspace Layer section

[Emmanuele Bassi <ebassi src gnome org>]

commit ab9f5a5300374716f528393b45308e69d0cc27d1
Author: Kristi Rifenbark <kristi rifenbark gmail com>
Date:   Tue Sep 26 16:41:01 2017 -0700

    ref-manual: Updated Added a New Recipe to Workspace Layer section
    
    Fixes [YOCTO #11392]
    
    Updated the section to document how to specify a branch,
    tag, or revision when using devtool add with a remote
    URL.
    
    (From yocto-docs rev: 903b4a4e72908572a5f8b8c822869bbd0fe76ec9)
    
    Signed-off-by: Kristi Rifenbark <kristi rifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 documentation/ref-manual/ref-devtool-reference.xml |   58 ++++++++++++++++----
 1 files changed, 46 insertions(+), 12 deletions(-)
---
diff --git a/documentation/ref-manual/ref-devtool-reference.xml 
b/documentation/ref-manual/ref-devtool-reference.xml
index b7c0e33..a577d1a 100644
--- a/documentation/ref-manual/ref-devtool-reference.xml
+++ b/documentation/ref-manual/ref-devtool-reference.xml
@@ -208,9 +208,9 @@
             The following example creates and adds a new recipe named
             <filename>jackson</filename> to a workspace layer the tool creates.
             The source code built by the recipes resides in
-            <filename>/home/scottrif/sources/jackson</filename>:
+            <filename>/home/<replaceable>user</replaceable>/sources/jackson</filename>:
             <literallayout class='monospaced'>
-     $ devtool add jackson /home/scottrif/sources/jackson
+     $ devtool add jackson /home/<replaceable>user</replaceable>/sources/jackson
             </literallayout>
         </para>
 
@@ -228,18 +228,52 @@
             append files, and source files into the existing workspace layer.
             The <filename>.bbappend</filename> file is created to point
             to the external source tree.
+            <note>
+                If your recipe has runtime dependencies defined, you must be sure
+                that these packages exist on the target hardware before attempting
+                to run your application.
+                If dependent packages (e.g. libraries) do not exist on the target,
+                your application, when run, will fail to find those functions.
+                For more information, see the
+                "<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your 
Software on the Target Machine</link>"
+                section.
+            </note>
         </para>
 
-        <note>
-            If your recipe has runtime dependencies defined, you must be sure
-            that these packages exist on the target hardware before attempting
-            to run your application.
-            If dependent packages (e.g. libraries) do not exist on the target,
-            your application, when run, will fail to find those functions.
-            For more information, see the
-            "<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your Software 
on the Target Machine</link>"
-            section.
-        </note>
+        <para>
+            By default, <filename>devtool add</filename> uses the latest
+            revision (i.e. master) when unpacking files from a remote URI.
+            In some cases, you might want to specify a source revision by
+            branch, tag, or commit hash. You can specify these options when
+            using the <filename>devtool add</filename> command:
+            <itemizedlist>
+                <listitem><para>
+                    To specify a source branch, use the
+                    <filename>--srcbranch</filename> option:
+                    <literallayout class='monospaced'>
+     $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson 
/home/<replaceable>user</replaceable>/sources/jackson
+                    </literallayout>
+                    In the previous example, you are checking out the
+                    &DISTRO_NAME_NO_CAP; branch.
+                    </para></listitem>
+                <listitem><para>
+                    To specify a specific tag or commit hash, use the
+                    <filename>--srcrev</filename> option:
+                    <literallayout class='monospaced'>
+     $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/<replaceable>user</replaceable>/sources/jackson
+     $ devtool add --srcrev <replaceable>some_commit_hash</replaceable> 
/home/<replaceable>user</replaceable>/sources/jackson
+                    </literallayout>
+                    The previous examples check out the &DISTRO_REL_TAG; tag
+                    and the commit associated with the
+                    <replaceable>some_commit_hash</replaceable> hash.
+                    </para></listitem>
+            </itemizedlist>
+            <note>
+                If you prefer to use the latest revision every time the recipe is
+                built, use the options <filename>--autorev</filename>
+                or <filename>-a</filename>.
+            </note>
+        </para>
     </section>
 
     <section id='devtool-extracting-the-source-for-an-existing-recipe'>