mirror-tutorial/en mirror-tutorial-en.xml,1.3,1.4

[Paul W. Frields (pfrields)]

Author: pfrields

Update of /cvs/docs/mirror-tutorial/en
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv6711

Modified Files:
	mirror-tutorial-en.xml 
Log Message:
- Style editing
- Revise lftp section to prevent disaster for the unwary
- Jump version to 1.0, freeing me from the ugly past



Index: mirror-tutorial-en.xml
===================================================================
RCS file: /cvs/docs/mirror-tutorial/en/mirror-tutorial-en.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- mirror-tutorial-en.xml	6 Feb 2006 20:29:48 -0000	1.3
+++ mirror-tutorial-en.xml	6 Feb 2006 23:20:23 -0000	1.4
@@ -6,235 +6,17 @@
 %FEDORA-ENTITIES-EN;
 
 <!ENTITY DOCNAME "mirror-tutorial">
-<!ENTITY DOCVERSION "0.37.2">
-<!ENTITY DOCDATE "2005-12-28">
+<!ENTITY DOCVERSION "1.0">
+<!ENTITY DOCDATE "2006-02-06">
 <!ENTITY DOCID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)"> <!-- change version of manual and date here -->
 
+<!ENTITY FDP-INFO SYSTEM "fdp-info-en.xml">
 <!ENTITY FCLOCALVER "4">
 ]>
 
 <article id="mirror-tutorial" lang="en">
-  <articleinfo>
-    <title>Mirror Tutorial</title>
-    <copyright>
-      <year>2004</year>
-      <year>2005</year>
-      <holder>Paul W. Frields</holder>
-    </copyright>
-    <authorgroup>
-      <author>
-	<surname>Frields</surname>
-	<firstname>Paul</firstname>
-	<othername role="mi">W.</othername>
-      </author>
-    </authorgroup>
-    &LEGALNOTICE;
-    <revhistory>
-      <revision>
-	<revnumber>0.2</revnumber>
-	<date>2004-08-31</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-            Initial version for editorial process.
-          </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.21</revnumber>
-	<date>2004-09-02</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Revised screen sections to use inline tags as discussed on
-	    fedora-docs-list; minor error corrections.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.22</revnumber>
-	<date>2004-09-06</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Style editing.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.23</revnumber>
-	<date>2004-09-08</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-            Additional style editing.
-          </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.24</revnumber>
-	<date>2004-09-09</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Brought introduction section in line with &FDP; standards.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.25</revnumber>
-	<date>2004-10-13</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Incorporated all suggested changes by KWade.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.26</revnumber>
-	<date>2004-12-01</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Updated repository setup to include createrepo.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.27</revnumber>
-	<date>2004-12-01</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Minor corrections.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.28</revnumber>
-	<date>2005-01-30</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Minor corrections.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.29</revnumber>
-	<date>2005-07-22</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Minor note on yum versioning for repodata; fixed entities ref.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.30</revnumber>
-	<date>2005-08-01</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Add entities and draft notice.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.31</revnumber>
-	<date>2005-08-29</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Use bug reporting entity, add BETA classification.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.32</revnumber>
-	<date>2005-10-12</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Fix default network sharing protocol (#169581, #169584)
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.33</revnumber>
-	<date>2005-10-15</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Some style changes and more indexing.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.34</revnumber>
-	<date>2005-10-16</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Added client configuration section.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.35</revnumber>
-	<date>2005-11-09</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Added some security info and fixes (#169584).
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.36</revnumber>
-	<date>2005-11-11</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Added some additional information about repository
-	    configuration (#172815, #172819).
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.37</revnumber>
-	<date>2005-11-17</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Fixed createrepo and yum-arch command issues (#172819).
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.37.1</revnumber>
-	<date>2005-11-25</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Minor revision fixing service reload command.
-	  </para>
-	</revdescription>
-      </revision>
-      <revision>
-	<revnumber>0.37.2</revnumber>
-	<date>2005-12-28</date>
-	<authorinitials>PaulWFrields</authorinitials>
-	<revdescription>
-	  <para>
-	    Minor revision updating entity names and incorporating
-	    variablelist.
-	  </para>
-	</revdescription>
-      </revision>
-    </revhistory>
-  </articleinfo>
+
+  &FDP-INFO;
 
   <section id="sn-introduction">
     <title>Introduction</title>
@@ -640,13 +422,13 @@
 	<title>Download Using HTTP or FTP</title>
 	<para>
 	  To download via HTTP or FTP, use either the
-	  <command>wget</command> or the <command>lftp</command>
-	  command. <command>wget</command> recurses subdirectories
-	  automatically and pulls down entire trees of data with a
-	  single command. If you are not careful, however, it is
-	  possible to pull down much more data than you intended. The
-	  following commands mirror the entire current &FC;
-	  distribution:
+	  <command>wget</command> or <command>lftp</command>
+	  command. The <command>wget</command> command recurses
+	  subdirectories automatically and pulls down entire trees of
+	  data with a single command. If you are not careful, however,
+	  it is possible to pull down much more data than you
+	  intended. The following commands mirror the entire current
+	  &FC; distribution:
 	</para>
 
 <screen>
@@ -702,104 +484,95 @@
 
 	<para>
 	  The <command>lftp</command> command works like the
-	  <command>wget</command> command, mirroring the content of a
-	  HTTP or FTP server. But there are problems with updating the
-	  mirror with <command>wget</command>, like not deleting
-	  old files locally. This is very important when creating an
-	  updates repository mirror, where new files are created
-	  frequently and old files are automatically removed from the
-	  upstream mirrors.
+	  <command>wget</command> command, and mirrors the content of a
+	  HTTP or FTP server.  The <command>wget</command> command,
+	  however, does not delete old files locally.  This feature is
+	  important for update repository mirrors to stay synchronized
+	  to upstream mirrors.  New files are created and old files are
+	  automatically removed from the upstream mirrors on a frequent
+	  basis.
 	</para>
 
 	<para>
-	  With <command>lftp</command> you can synchronize files and
-	  directories from a remote host just like
-	  <command>rsync</command>, but using HTTP or FTP protocols. For
-	  example: doing the above method used by wget to mirror the
-	  entire current Fedora Core distribution:
+	  The <command>lftp</command> command synchronizes files and
+	  directories from a remote host like <command>rsync</command>,
+	  but uses HTTP or FTP protocols.  Use the following command to
+	  mirror the entire &FC; distribution with
+	  <command>lftp</command>:
 	</para>
 
 <screen>
-<userinput>cd /var/www/mirror
-lftp -e "open http://mirror.example.com/pub/mirror/linux/core/&FCVER;/i386/ && \
-mirror --delete --verbose && \
-quit"</userinput>
+<userinput>cd /var/www/mirror && \
+lftp -c "open http://mirror.example.com/pub/mirror/linux/core/&FCVER;/i386/ && \
+mirror --delete --verbose"</userinput>
 </screen>
 
 	<para>
-	  The <command>-e</command> parameter tells
-	  <command>lftp</command> to execute given commands. Doing
-	  this, you can execute many actions from a single command.
-	  Commands are separated with &&, so note the commands
-	  above:
+	  The <option>-c</option> parameter executes a set of commands
+	  in a <command>lftp</command> process. Commands are separated
+	  with <command>&&</command> to prevent the
+	  <command>lftp</command> command from executing if the
+	  <command>cd</command> command fails.  The commands in the
+	  <command>lftp</command> command set work the same way.  The
+	  command syntax <command>A && B</command> is often
+	  shorthand for "if A returns success, run B."  An explanation
+	  of the <command>lftp</command> commands follows:
 	</para>
 	  
 	<itemizedlist>
 	  <listitem>
 	    <para>
 	      <command>open</command> connects to the site and changes
-	      the directory automatically.
+	      directory automatically.
 	    </para>
 	  </listitem>
 	  <listitem>
 	    <para>
-	      <command>mirror --delete --verbose</command> tells
-	      <command>lftp</command> to fetch all files and/or
-	      directories recursively in the current directory (opened
-	      by the <command>open</command> command). The
-	      <command>--delete</command> parameter excludes all local
-	      files that are not in the remote directory, and the
-	      <command>--verbose</command> parameter prints some
+	      <command>mirror</command> fetches all files and
+	      directories recursively in the current directory. The
+	      <command>--delete</command> option excludes all local
+	      files that are not in the remote directory.  The
+	      <command>--verbose</command> option prints some
 	      information in the screen and is optional.
 	    </para>
 	  </listitem>
-	  <listitem>
-	    <para>
-	      <command>quit</command> is last executed and
-	      <command>lftp</command> exits finishing the job.
-	    </para>
-	  </listitem>
 	</itemizedlist>
 
 	<para>
-	  <command>lftp</command> will mantain an exact copy of the
-	  directory for you: only new files will be downloaded and old
-	  files will be deleted.
+	  The <command>lftp</command> command above mantains an exact
+	  copy of the directory for you.  It downloads only new or
+	  changed files, and deletes only those that no longer exist on
+	  the upstream mirror.
 	</para>
 
 	<para>
-	  As with <command>wget</command>, it is possible that you may
-	  download some unwanted files in directories.
-	  <command>lftp</command> supports regular expressions when
-	  excluding files within a <command>mirror</command> command.
-	  In another example, the command below shows how to mirror an
-	  current Fedora Core distribution updates repository,
-	  excluding the <filename>debug</filename> and
+	  As with <command>wget</command>, it is possible you may
+	  download some unwanted files.  The <command>lftp</command>
+	  command supports regular expressions for excluding files
+	  within a <command>mirror</command> command.  The command below
+	  shows how to mirror an current &FC; distribution updates
+	  repository, excluding <filename>debug</filename> and
 	  <filename>repodata</filename> directories:
 	</para>
 
 <screen>
-<userinput>cd /var/www/mirror
-lftp -e "set mirror:exclude-regex 'debug\/|repodata\/' && \
+<userinput>cd /var/www/mirror && \
+lftp -c "set mirror:exclude-regex 'debug\/|repodata\/' && \
 open http://mirror.example.com/pub/mirror/linux/core/updates/&FCVER;/i386/ && \
-mirror --delete --verbose && \
-quit"</userinput>
+mirror --delete --verbose"</userinput>
 </screen>
 
-	<para>There are many usages for the <command>lftp</command>
-	command. Consult the <command>lftp</command> man pages for more
-	details.</para>
+	<para>Consult the <command>lftp</command> man pages for more
+	details and usage options.</para>
 
 	<tip>
 	  <title>Using Proxy for HTTP or FTP retrieval</title>
 	  <para>
-	    Sometimes when behind a proxy or firewall, you may need to
-	    do mirroring throught a http proxy. This can be accomplished
-	    exporting the environment variables
-	    <command>http_proxy</command> and
-	    <command>ftp_proxy</command> before running the
-	    <command>wget</command> or <command>lftp</command> commands,
-	    like this:
+	    If you are behind a proxy or firewall, you may need to use a
+	    HTTP proxy to mirror files.  To do this, export the
+	    environment variables <command>http_proxy</command> and
+	    <command>ftp_proxy</command> before you run the
+	    <command>wget</command> or <command>lftp</command> commands:
 	  </para>
 
 <screen>