From 2e7d650a2ab3ced7688fb550f55798dd55381367 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Wed, 30 Sep 2015 12:55:13 -0700
Subject: [PATCH] ref-manual: Updates to clarify Fetcher URL directory
 parameters

Updated the SRC_URI variable description to cross-reference
the "Fetchers" section in the BitBake User Manual and added
some more Fetcher URL parameters specific to certain fetchers.
This was done to help clarify how to put fetched code into
specific directories.

Also updated the bin_packages.bbclass description to have a
better example.  Used a git:// fetcher example and provided

some specific URL parameters.

(From yocto-docs rev: 7133b49092096c253ffce99f39d4fa6db7810061)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/ref-classes.xml   | 12 +++++++--
 documentation/ref-manual/ref-variables.xml | 29 +++++++++++++++++++---
 2 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index ba7c3f79f6..30d0e5de06 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -211,14 +211,22 @@
         use for this class.
         <note>
             For RPMs and other packages that do not contain a subdirectory,
-            you should specify a "subdir" parameter.
+            you should specify an appropriate fetcher parameter to point to
+            the subdirectory.
+            For example, if BitBake is using the Git fetcher
+            (<filename>git://</filename>), the "subpath" parameter limits
+            the checkout to a specific subpath of the tree.
             Here is an example where <filename>${BP}</filename> is used so that
             the files are extracted into the subdirectory expected by the
             default value of
             <link linkend='var-S'><filename>S</filename></link>:
             <literallayout class='monospaced'>
-     SRC_URI = "http://example.com/downloads/somepackage.rpm;subdir=${BP}"
+     SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
             </literallayout>
+            See the
+            "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
+            section in the BitBake User Manual for more information on
+            supported BitBake Fetchers.
         </note>
     </para>
 </section>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 7cc01c64ef..0bc7a82b48 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -11240,7 +11240,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 </para>
 
                 <para>
-                    The following list explains the available URI protocols:
+                    The following list explains the available URI protocols.
+                    URI protocols are highly dependent on particular BitBake
+                    Fetcher submodules.
+                    Depending on the fetcher BitBake uses, various URL
+                    parameters are employed.
+                    For specifics on the supported Fetchers, see the
+                    "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
+                    section in the BitBake User Manual.
                     <itemizedlist>
                         <listitem><para><emphasis><filename>file://</filename> -</emphasis>
                             Fetches files, which are usually files shipped with
@@ -11368,11 +11375,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                         <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
                             whether or not to unpack the file if it is an archive.
                             The default action is to unpack the file.</para></listitem>
+                        <listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file
+                            (or extracts its contents) into the specified
+                            subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+                            when the Git fetcher is used.
+                            </para></listitem>
                         <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
                             (or extracts its contents) into the specified
-                            subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
-                            This option is useful for unusual tarballs or other archives that
-                            do not have their files already in a subdirectory within the archive.
+                            subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+                            when the local (<filename>file://</filename>)
+                            fetcher is used.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
+                            (or extracts its contents) into the specified
+                            subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+                            when the CVS fetcher is used.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>subpath</filename> -</emphasis>
+                            Limits the checkout to a specific subpath of the
+                            tree when using the Git fetcher is used.
                             </para></listitem>
                         <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
                             name to be used for association with <filename>SRC_URI</filename> checksums