bitbake: user-manual-fetching: Editing pass over the manual chapter

(Bitbake rev: b0fc79e6405b7070a42cfda035e87edc832f8334)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 53 insertions, 44 deletions

diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml
index 1ff8acb4e0..cdca64c801 100644
--- a/bitbake/doc/user-manual/user-manual-fetching.xml
+++ b/bitbake/doc/user-manual/user-manual-fetching.xml
@@ -4,25 +4,25 @@
 <chapter>
 <title>File download support</title>
 
-    <section>
+    <section id='file-download-overview'>
         <title>Overview</title>
 
         <para>
-            BitBake provides support to download files
-            this procedure is called fetching and it handled by the
+            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 only related
+            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 will describe the available fetchers and
+            The next sections 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
+            URI parameters separated by a “;” consisting of a key and
             a value.
             The semantics of the variables and parameters are
             defined by the fetcher.
@@ -31,16 +31,16 @@
         </para>
 
         <para>
-            The overall fetch process is that first, fetches are attempted from
+            The overall fetch process first attempts to fetch from
             <filename>PREMIRRORS</filename>.
-            If those don't work, the original <filename>SRC_URI</filename>
-            is attempted
-            and if that fails, BitBake will fall back to
+            If these fail, the original <filename>SRC_URI</filename>
+            is attempted.
+            If that fails, BitBake falls back to
             <filename>MIRRORS</filename>.
-            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:
+            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 \
@@ -63,26 +63,33 @@ MIRRORS =+ "\
             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
+            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
-            <filename>SRC_URI[md5sum]</filename>
-            for the md5 checksum and
-            <filename>SRC_URI[sha256sum]</filename>
-            for the sha256 checksum or as parameters on the SRC_URI such as
-            SRC_URI="http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d".
+            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
-            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].
+            <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>
+    <section id='local-file-fetcher'>
         <title>Local file fetcher</title>
 
         <para>
@@ -103,7 +110,7 @@ MIRRORS =+ "\
         </para>
     </section>
 
-    <section>
+    <section id='cvs-fetcher'>
         <title>CVS fetcher</title>
 
         <para>
@@ -145,16 +152,16 @@ MIRRORS =+ "\
         </para>
     </section>
 
-    <section>
+    <section id='http-ftp-fetcher'>
         <title>HTTP/FTP fetcher</title>
 
         <para>
-            The URNs for the HTTP/FTP fetcher are http, https and ftp.
+            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.
-            <quote>${URI}</quote> and <quote>${FILES}</quote> will be replaced by the URI and
+            “${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"
@@ -164,8 +171,9 @@ MIRRORS =+ "\
         </para>
     </section>
 
-    <section>
-        <title>SVN fetcher</title>
+    <section id='svn-fetcher'>
+        <title>SVN Fetcher</title>
+
         <para>
             The URN for the SVN fetcher is svn.
         </para>
@@ -174,7 +182,7 @@ MIRRORS =+ "\
             This fetcher honors the variables
             <filename>FETCHCOMMAND_svn</filename>,
             <filename>SVNDIR</filename>,
-            <filename>SRCREV</filename>.
+            and <filename>SRCREV</filename>.
             <filename>FETCHCOMMAND</filename> contains the
             subversion command.
             <filename>SRCREV</filename> specifies which revision
@@ -185,8 +193,8 @@ MIRRORS =+ "\
             The supported parameters are proto, rev and scmdata.
             proto is the Subversion protocol, rev is the
             Subversion revision.
-            If scmdata is set to <quote>keep</quote>, the <quote>.svn</quote> directories will
-             be available during compile-time.
+            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"
@@ -194,23 +202,24 @@ MIRRORS =+ "\
         </para>
     </section>
 
-    <section>
-        <title>GIT fetcher</title>
+    <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.
+            base directory where the Git tree is cloned to.
         </para>
 
         <para>
-            The parameters are tag, protocol and scmdata.
-             tag is a Git tag, the default is <quote>master</quote>.
-             protocol is the Git protocol to use and defaults to <quote>git</quote>
-            if a hostname is set, otherwise its <quote>file</quote>.
-            If scmdata is set to <quote>keep</quote>, the <quote>.git</quote> directory will be available
+            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"