user-manual-fetching.xml: Brought up to wmat version.

Rather than investigate, cherry-pick, and edit individual commits
from the wmat branch, I have used a single commit to bring this
version of the chapter up to (and a bit beyond) the wmat version
of the file.  Asided from dropping in the text verbatim, I
took care of obvious spacing and formatting issues.  The file
is now at a good base equal to what was in the wmat version.

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>

1 files changed, 228 insertions, 91 deletions

diff --git a/doc/user-manual/user-manual-fetching.xml b/doc/user-manual/user-manual-fetching.xml
index 24780454c..85df7a1a1 100644
--- a/doc/user-manual/user-manual-fetching.xml
+++ b/doc/user-manual/user-manual-fetching.xml
@@ -1,92 +1,229 @@
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-    <chapter>
-        <title>File download support</title>
-        <section>
-            <title>Overview</title>
-            <para>BitBake provides support to download files this procedure is called fetching and it handled by the fetch and fetch2 modules. At this point the original fetch code is considered to be replaced by fetch2 and this manual only related to the fetch2 codebase.</para>
-
-            <para>The SRC_URI is normally used to tell BitBake which files to fetch. The next sections will describe the available fetchers and their options. Each fetcher honors a set of variables and per URI parameters separated by a <quote>;</quote> consisting of a key and a value. The semantics of the variables and parameters are defined by the fetcher. BitBake tries to have consistent semantics between the different fetchers.
-            </para>
-
-            <para>The overall fetch process is that first, fetches are attempted from PREMIRRORS. If those don't work, the original SRC_URI is attempted and if that fails, BitBake will fall back to MIRRORS. Cross urls are supported, so its possible to mirror a git repository on an http server as a tarball for example. Some example commonly used mirror definitions are:</para>
-
-            <para><screen><varname>PREMIRRORS</varname> ?= "\
-bzr://.*/.*   http://somemirror.org/sources/ \n \
-cvs://.*/.*   http://somemirror.org/sources/ \n \
-git://.*/.*   http://somemirror.org/sources/ \n \
-hg://.*/.*    http://somemirror.org/sources/ \n \
-osc://.*/.*   http://somemirror.org/sources/ \n \
-p4://.*/.*    http://somemirror.org/sources/ \n \
-svk://.*/.*   http://somemirror.org/sources/ \n \
-svn://.*/.*   http://somemirror.org/sources/ \n"
-
-<varname>MIRRORS</varname> =+ "\
-ftp://.*/.*      http://somemirror.org/sources/ \n \
-http://.*/.*     http://somemirror.org/sources/ \n \
-https://.*/.*    http://somemirror.org/sources/ \n"</screen></para>
-
-            <para>Non-local downloaded output is placed into the directory specified by the <varname>DL_DIR</varname>. For non local archive downloads the code can verify sha256 and md5 checksums for the download to ensure the file has been downloaded correctly. These may be specified either in the form <varname>SRC_URI[md5sum]</varname> for the md5 checksum and <varname>SRC_URI[sha256sum]</varname> for the sha256 checksum or as parameters on the SRC_URI such as SRC_URI="http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d". If <varname>BB_STRICT_CHECKSUM</varname> is set, any download without a checksum will trigger an error message. In cases where multiple files are listed in SRC_URI, the name parameter is used assign names to the urls and these are then specified in the checksums in the form SRC_URI[name.sha256sum].</para>
-
-        </section>
-
-        <section>
-            <title>Local file fetcher</title>
-            <para>The URN for the local file fetcher is <emphasis>file</emphasis>. The filename can be either absolute or relative. If the filename is relative, <varname>FILESPATH</varname> and failing that <varname>FILESDIR</varname> will be used to find the appropriate relative file. The metadata usually extend these variables to include variations of the values in <varname>OVERRIDES</varname>. Single files and complete directories can be specified.
-<screen><varname>SRC_URI</varname>= "file://relativefile.patch"
-<varname>SRC_URI</varname>= "file://relativefile.patch;this=ignored"
-<varname>SRC_URI</varname>= "file:///Users/ich/very_important_software"
-</screen>
-            </para>
-        </section>
-
-        <section>
-            <title>CVS fetcher</title>
-            <para>The URN for the CVS fetcher is <emphasis>cvs</emphasis>. This fetcher honors the variables <varname>CVSDIR</varname>, <varname>SRCDATE</varname>, <varname>FETCHCOMMAND_cvs</varname>, <varname>UPDATECOMMAND_cvs</varname>. <varname>DL_DIR</varname> specifies where a temporary checkout is saved. <varname>SRCDATE</varname> specifies which date to use when doing the fetching (the special value of "now" will cause the checkout to be updated on every build). <varname>FETCHCOMMAND</varname> and <varname>UPDATECOMMAND</varname> specify which executables to use for the CVS checkout or update.
-            </para>
-            <para>The supported parameters are <varname>module</varname>, <varname>tag</varname>, <varname>date</varname>, <varname>method</varname>, <varname>localdir</varname>, <varname>rsh</varname> and <varname>scmdata</varname>. The <varname>module</varname> specifies which module to check out, the <varname>tag</varname> describes which CVS TAG should be used for the checkout. By default the TAG is empty. A <varname>date</varname> can be specified to override the SRCDATE of the configuration to checkout a specific date.  The special value of "now" will cause the checkout to be updated on every build.<varname>method</varname> is by default <emphasis>pserver</emphasis>. If <emphasis>ext</emphasis> is used the <varname>rsh</varname> parameter will be evaluated and <varname>CVS_RSH</varname> will be set. Finally, <varname>localdir</varname> is used to checkout into a special directory relative to <varname>CVSDIR</varname>.
-
-<screen><varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
-<varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
-</screen>
-            </para>
-        </section>
-
-        <section>
-            <title>HTTP/FTP fetcher</title>
-            <para>The URNs for the HTTP/FTP fetcher are <emphasis>http</emphasis>, <emphasis>https</emphasis> and <emphasis>ftp</emphasis>. This fetcher honors the variables <varname>FETCHCOMMAND_wget</varname>. <varname>FETCHCOMMAND</varname> contains the command used for fetching. <quote>${URI}</quote> and <quote>${FILES}</quote> will be replaced by the URI and basename of the file to be fetched.
-            </para>
-            <para><screen><varname>SRC_URI</varname> = "http://oe.handhelds.org/not_there.aac"
-<varname>SRC_URI</varname> = "ftp://oe.handhelds.org/not_there_as_well.aac"
-<varname>SRC_URI</varname> = "ftp://you@oe.handheld.sorg/home/you/secret.plan"
-</screen></para>
-        </section>
-
-        <section>
-            <title>SVN fetcher</title>
-            <para>The URN for the SVN fetcher is <emphasis>svn</emphasis>.
-            </para>
-            <para>This fetcher honors the variables <varname>FETCHCOMMAND_svn</varname>, <varname>SVNDIR</varname>, <varname>SRCREV</varname>. <varname>FETCHCOMMAND</varname> contains the subversion command. <varname>SRCREV</varname> specifies which revision to use when doing the fetching.
-            </para>
-            <para>The supported parameters are <varname>proto</varname>, <varname>rev</varname> and <varname>scmdata</varname>. <varname>proto</varname> is the Subversion protocol, <varname>rev</varname> is the Subversion revision. If <varname>scmdata</varname> is set to <quote>keep</quote>, the <quote>.svn</quote> directories will be available during compile-time.
-            </para>
-            <para><screen><varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
-<varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
-</screen></para>
-        </section>
-
-        <section>
-            <title>GIT fetcher</title>
-            <para>The URN for the GIT Fetcher is <emphasis>git</emphasis>.
-            </para>
-            <para>The variable <varname>GITDIR</varname> will be used as the base directory where the git tree is cloned to.
-            </para>
-            <para>The parameters are <emphasis>tag</emphasis>, <emphasis>protocol</emphasis> and <emphasis>scmdata</emphasis>. <emphasis>tag</emphasis> is a Git tag, the default is <quote>master</quote>. <emphasis>protocol</emphasis> is the Git protocol to use and defaults to <quote>git</quote> if a hostname is set, otherwise its <quote>file</quote>. If <emphasis>scmdata</emphasis> is set to <quote>keep</quote>, the <quote>.git</quote> directory will be available during compile-time.
-            </para>
-            <para><screen><varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
-<varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
-            </screen></para>
-        </section>
-
-    </chapter>
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter>
+<title>File download support</title>
+
+    <section id='file-download-overview'>
+        <title>Overview</title>
+
+        <para>
+            BitBake provides support to download files.
+            This procedure is called fetching and is handled by the
+            fetch and fetch2 modules.
+            At this point, the original fetch code is considered to
+            be replaced by fetch2 and this manual is only related
+            to the fetch2 codebase.
+        </para>
+
+        <para>
+            The <filename>SRC_URI</filename> is normally used to
+            tell BitBake which files to fetch.
+            The next sections describe the available fetchers and
+            their options.
+            Each fetcher honors a set of variables and per
+            URI parameters separated by a “;” consisting of a key and
+            a value.
+            The semantics of the variables and parameters are
+            defined by the fetcher.
+            BitBake tries to have consistent semantics between the
+            different fetchers.
+        </para>
+
+        <para>
+            The overall fetch process first attempts to fetch from
+            <filename>PREMIRRORS</filename>.
+            If these fail, the original <filename>SRC_URI</filename>
+            is attempted.
+            If that fails, BitBake falls back to
+            <filename>MIRRORS</filename>.
+            Because cross-URLs are supported, it is possible to mirror
+            a Git repository on an HTTP server as a tarball.
+            Here are some examples that show commonly used mirror
+            definitions:
+            <literallayout class='monospaced'>
+     PREMIRRORS?= "\ bzr://.*/.*
+     http://somemirror.org/sources/ \n \ cvs://.*/.*
+     http://somemirror.org/sources/ \n \ git://.*/.*
+     http://somemirror.org/sources/ \n \ hg://.*/.*
+     http://somemirror.org/sources/ \n \ osc://.*/.*
+     http://somemirror.org/sources/ \n \ p4://.*/.*
+     http://somemirror.org/sources/ \n \ svk://.*/.*
+     http://somemirror.org/sources/ \n \ svn://.*/.*
+     http://somemirror.org/sources/ \n"
+     MIRRORS=+ "\ ftp://.*/.*
+     http://somemirror.org/sources/ \n \ http://.*/.*
+     http://somemirror.org/sources/ \n \ https://.*/.*
+     http://somemirror.org/sources/ \n"
+            </literallayout>
+        </para>
+
+        <para>
+            Non-local downloaded output is placed
+            into the directory specified by the
+            <filename>DL_DIR</filename> variable.
+            For non local archive downloads, the code can verify
+            sha256 and md5 checksums for the download to ensure
+            the file has been downloaded correctly.
+            These can be specified in the following forms
+            for md5 and sha256 checksums, respectively:
+            <literallayout class='monospaced'>
+     SRC_URI[md5sum]
+     SRC_URI[sha256sum]
+            </literallayout>
+            You can also specify them as parameters on the
+            <filename>SRC_URI</filename>:
+            <literallayout class='monospaced'>
+     SRC_URI="http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
+            </literallayout>
+            If <filename>BB_STRICT_CHECKSUM</filename> is set, any download
+            without a checksum will trigger an error message.
+            In cases where multiple files are listed in
+            <filename>SRC_URI</filename>, the name parameter is used
+            assign names to the URLs and these are then specified
+            in the checksums using the following form:
+            <literallayout class='monospaced'>
+     SRC_URI[name.sha256sum]
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='local-file-fetcher'>
+        <title>Local file fetcher</title>
+
+        <para>
+            The URN for the local file fetcher is file.
+            The filename can be either absolute or relative.
+            If the filename is relative,
+            <filename>FILESPATH</filename> and failing that
+            <filename>FILESDIR</filename> will be used to find the
+            appropriate relative file.
+            The metadata usually extend these variables to include
+            variations of the values in <filename>OVERRIDES</filename>.
+            Single files and complete directories can be specified.
+            <literallayout class='monospaced'>
+     SRC_URI= "file://relativefile.patch"
+     SRC_URI="file://relativefile.patch;this=ignored"
+     SRC_URI="file:///Users/ich/very_important_software"
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='cvs-fetcher'>
+        <title>CVS fetcher</title>
+
+        <para>
+            The URN for the CVS fetcher is cvs.
+            This fetcher honors the variables <filename>CVSDIR</filename>,
+            <filename>SRCDATE</filename>, <filename>FETCHCOMMAND_cvs</filename>,
+            <filename>UPDATECOMMAND_cvs</filename>.
+            <filename>DL_DIR</filename> specifies where a
+            temporary checkout is saved.
+            <filename>SRCDATE</filename> specifies which date to
+            use when doing the fetching (the special value of "now"
+            will cause the checkout to be updated on every build).
+            <filename>FETCHCOMMAND</filename> and
+            <filename>UPDATECOMMAND</filename> specify which executables
+            to use for the CVS checkout or update.
+        </para>
+
+        <para>
+            The supported parameters are module, tag, date,
+            method, localdir, rshand scmdata.
+            The module specifies which module to check out,
+            the tag describes which CVS TAG should be used for
+            the checkout.
+            By default, the TAG is empty.
+            A date can be specified to override the
+            <filename>SRCDATE</filename> of the
+            configuration to checkout a specific date.
+            The special value of "now" will cause the checkout to be
+            updated on every build.
+            method is by default pserver.
+            If ext is used the rsh parameter will be evaluated
+            and <filename>CVS_RSH</filename> will be set.
+            Finally, local dir is used to checkout into a special
+            directory relative to <filename>CVSDIR</filename>.
+            <literallayout class='monospaced'>
+     SRC_URI="cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
+     SRC_URI="cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='http-ftp-fetcher'>
+        <title>HTTP/FTP fetcher</title>
+
+        <para>
+            The URNs for the HTTP/FTP fetcher are http, https, and ftp.
+            This fetcher honors the variables
+            <filename>FETCHCOMMAND_wget</filename>.
+            <filename>FETCHCOMMAND</filename> contains the command used
+            for fetching.
+            “${URI}” and “${FILES}” will be replaced by the URI and
+            basename of the file to be fetched.
+            <literallayout class='monospaced'>
+     SRC_URI="http://oe.handhelds.org/not_there.aac"
+     SRC_URI="ftp://oe.handhelds.org/not_there_as_well.aac"
+     SRC_URI="ftp://you@oe.handheld.sorg/home/you/secret.plan"
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='svn-fetcher'>
+        <title>SVN Fetcher</title>
+
+        <para>
+            The URN for the SVN fetcher is svn.
+        </para>
+
+        <para>
+            This fetcher honors the variables
+            <filename>FETCHCOMMAND_svn</filename>,
+            <filename>SVNDIR</filename>,
+            and <filename>SRCREV</filename>.
+            <filename>FETCHCOMMAND</filename> contains the
+            subversion command.
+            <filename>SRCREV</filename> specifies which revision
+            to use when doing the fetching.
+        </para>
+
+        <para>
+            The supported parameters are proto, rev and scmdata.
+            proto is the Subversion protocol, rev is the
+            Subversion revision.
+            If scmdata is set to “keep”, the “.svn” directories will
+            be available during compile-time.
+            <literallayout class='monospaced'>
+     SRC_URI="svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
+     SRC_URI="svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='git-fetcher'>
+        <title>GIT Fetcher</title>
+
+        <para>
+            The URN for the GIT Fetcher is git.
+        </para>
+
+        <para>
+            The variable <filename>GITDIR</filename> will be used as the
+            base directory where the Git tree is cloned to.
+        </para>
+
+        <para>
+            The parameters are tag, protocol, and scmdata.
+            The tag parameter is a Git tag, the default is “master”.
+            The protocol tag is the Git protocol to use and defaults to “git”
+            if a hostname is set, otherwise it is “file”.
+            If scmdata is set to “keep”, the “.git” directory will be available
+            during compile-time.
+            <literallayout class='monospaced'>
+     SRC_URI="git://git.oe.handhelds.org/git/vip.git;tag=version-1"
+     SRC_URI="git://git.oe.handhelds.org/git/vip.git;protocol=http"
+            </literallayout>
+        </para>
+    </section>
+</chapter>