diff -r 6d8923ea5ca3 en_US.ISO8859-1/articles/freebsd-update-server/article.sgml
--- a/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml	Fri Nov 20 10:05:02 2009 +0200
+++ b/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml	Fri Nov 20 17:48:23 2009 +0200
@@ -80,11 +80,11 @@
       </listitem>
 
       <listitem>
-	<para>An <ulink
-	    url="&url.books.handbook;/network-apache.html">Apache
-	    web server</ulink>, with over half of the space required for the
-	  build.  For instance, our test builds total 4&nbsp;GB, and the
-	  webserver space needed to distribute updates is 2.6&nbsp;GB.</para>
+	<para>A web server, like <ulink
+	    url="&url.books.handbook;/network-apache.html">Apache</ulink>,
+	  with over half of the space required for the build.  For instance,
+	  our test builds total 4&nbsp;GB, and the webserver space needed to
+	  distribute updates is 2.6&nbsp;GB.</para>
       </listitem>
 
       <listitem>
@@ -97,7 +97,8 @@
   <sect1 id="Configuration">
     <title>Configuration: Installation & Setup</title>
 
-    <para>Download <ulink url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
+    <para>Download
+      the <ulink url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
       software.  A tarball may be downloaded, or use &man.csup.1; and the
       <literal>projects-all</literal> collection.</para>
 
@@ -138,19 +139,20 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>FTP</literal></term>
 
 	<listitem>
-	  <para>This is where the subroutine <function>fetchiso()</function>
-	    declared in <filename>scripts/build.subr</filename> will contact
-	    the configured source for downloading the &os; ISO.  This setting
-	    is not limited to <application>ftp</application>, it may also be
-	    a web (<application>httpd</application>) address as well.
-	    For our purposes, ISO's are on the same server as our internal
-	    http server that will be serving updates.  The software has been
-	    configured to look in that location.  For this setup, we have to
-	    alter the routine to fetch the ISO.  By copying the source
-	    <filename>build.subr</filename> to
-	    <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename> this
-	    file will be sourced instead of the released source for
-	    <filename>build.subr</filename>.</para>
+	  <para>This is the location where ISO images are downloaded from (by
+	    the <function>fetchiso()</function> subroutine
+	    of <filename>scripts/build.subr</filename>).  The location
+	    configured here is not limited to FTP URIs.  Any URI scheme
+	    supported by the standard &man.fetch.1; utility should work fine.
+	    In our own setup the ISO images are on the same internal http
+	    server that will be serving the updates.</para>
+
+	  <para>Customizations to the <function>fetchiso()</function> code can
+	    be installed by copying the
+	    default <filename>build.subr</filename> script to the release- and
+	    architecture-specific area
+	    at <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename>
+	    and applying local edits.</para>
 	</listitem>
       </varlistentry>
 
@@ -158,9 +160,8 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>BUILDHOSTNAME</literal></term>
 
 	<listitem>
-	  <para>Host where software will be built.  Coincidentally, this
-	    information will be displayed on updated systems when
-	    issuing:</para>
+	  <para>The name of the build host.  This information will be
+	    displayed on updated systems when issuing:</para>
 
 	  <screen>&prompt.user; <userinput>uname -v</userinput></screen>
 	</listitem>
@@ -170,15 +171,16 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>SSHKEY</literal></term>
 
 	<listitem>
-	  <para>Key used when uploading data to an update server which will
-	    provide patches or upgrades to clients.  A key pair may be
-	    created using <command>ssh-keygen -t dsa</command>.  Alteration
-	    of this parameter is not required as stadnard password
-	    authentication through <application>ssh</application> will be
-	    used.</para>
+	  <para>The <application>SSH</application> key for uploading files to
+	    the update server.  A key pair can be created by
+	    typing <command>ssh-keygen -t dsa</command>.  This parameter is
+	    optional; standard password authentication will be used as a
+	    fallback authentication method when <literal>SSHKEY</literal> is
+	    not defined.</para>
 
-	  <para>&man.ssh-keygen.1; has more detailed information in creating
-	    a key pair.</para>
+	  <para>&man.ssh-keygen.1; has more detailed information
+	    about <application>SSH</application> and the appropriate steps for
+	    creating and using one.</para>
 	</listitem>
       </varlistentry>
 
@@ -186,7 +188,8 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>MASTERACCT</literal></term>
 
 	<listitem>
-	  <para>Account that files are uploaded to on remote system.</para>
+	  <para>Account that files are uploaded to on the update
+	    server.</para>
 	</listitem>
       </varlistentry>
 
@@ -194,54 +197,68 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>MASTERDIR</literal></term>
 
 	<listitem>
-	  <para>Directory where files are uploaded to on remote
-	    system.</para>
+	  <para>Directory where files are uploaded to on the update
+	    server.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
-    <para>Now that build directives are set, the installation files are
-      configured for a build.  For this example, we will use
-      <literal>RELEASE-7.2</literal> under <literal>amd64</literal>
-      architecture.  Configuration files for &i386;
-      architecture are available with downloaded source.</para>
+     <para>The default <filename>build.conf</filename> file shipped with
+       the <application>freebsd-update-server</application> sources are
+       suitable for building &i386; releases of &os;.  As an example of
+       building an update server for other architectures we will show in
+       the following paragraphs the configuration changes needed for an
+       AMD64 update server:</para>
 
-    <para>Create build environment directory under <filename
-	class="directory">scripts/RELEASE-7.2/amd64</filename>.</para>
+    <procedure>
+      <step>
+        <para>Create a build environment for AMD64:</para>
 
-    <informalexample>
-      <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64</userinput></screen>
-    </informalexample>
+        <informalexample>
+          <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64</userinput></screen>
+        </informalexample>
+      </step>
 
-    <para>This is the <filename>build.conf</filename> file that should be
-      placed in the directory just created.</para>
+      <step>
 
-    <programlisting># SHA256 hash of RELEASE disc1.iso image.
+        <para>Install a <filename>build.conf</filename> file in the
+          newly created build directory.  The build configuration
+          options for &os; 7.2-RELEASE on AMD64 should be similar
+          to:</para>
+
+        <programlisting># SHA256 hash of RELEASE disc1.iso image.
 export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5
 
 # Components of the world, source, and kernels
 export WORLDPARTS="base catpages dict doc games info manpages proflibs lib32"
-export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5	\
-		lib libexec release rescue sbin secure share sys tools	\
-		ubin usbin cddl"
+export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5  \
+                lib libexec release rescue sbin secure share sys tools  \
+                ubin usbin cddl"
 export KERNELPARTS="generic"
 
 # EOL date
 export EOL=1275289200</programlisting>
 
-    <note>
-      <para>To generate the "End of Life" number for
-	<filename>build.conf</filename>, refer to the "Estimated EOL" posted
-	on the <ulink url="&url.base;/security/security.html">&os;
-	Security Website</ulink>.  Based on this date, you can issue
-	<command>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' +%s</command>,
-	and substitute actual date parameters for those stated by
-	&os;.</para>
+        <note>
+          <para>To generate the "End of Life" number for
+            <filename>build.conf</filename>, refer to the "Estimated
+            EOL" posted on
+            the <ulink url="&url.base;/security/security.html">&os;
+              Security Website</ulink>.  You can derive the value
+            of <literal>EOL</literal> from the date listed on the web
+            site, using the &man.date.1; utility, e.g.:</para>
 
-      <para>The &man.sha256.1; hash key for the desired release, is
-	published within the respective <ulink
-	  url="&url.base;/releases/">release announcement </ulink>.</para>
-    </note>
+          <screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'</userinput></screen>
+        </note>
+
+        <note>
+          <para>The &man.sha256.1; hash key for the desired release, is
+            published within the
+            respective <ulink url="&url.base;/releases/">release
+              announcement</ulink>.</para>
+        </note>
+      </step>
+    </procedure>
   </sect1>
 
   <sect1 id="build">
@@ -273,9 +290,9 @@ enter aes-256-cbc encryption password:
 Verifying - enter aes-256-cbc encryption password:</screen>
 
     <note>
-      <para>Note down the generated KeyPrint; this value is entered into
-	<filename>/etc/freebsd-update.conf</filename> for binary
-	updates.</para>
+      <para>Keep a note of the generated key fingerpring.  This value is
+	entered into <filename>/etc/freebsd-update.conf</filename> for
+	binary updates.</para>
     </note>
 
     <para>At this point, we are ready to stage a build.</para>
@@ -330,8 +347,8 @@ world|base|/usr/lib/libalias_ftp.a
 
     <note>
       <para>Then the build of the world is performed again, with world
-	patches.  A more detailed explanation may be found in
-	<filename>scripts/build.subr</filename>.</para>
+	patches.  A more detailed explanation may be found
+	in <filename>scripts/build.subr</filename>.</para>
     </note>
 
     <screen>Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE
@@ -411,10 +428,7 @@ to sign the release.</screen>
       file named <filename>USAGE</filename>.  Execute
       <filename>scripts/approve.sh</filename>, as directed.  This will sign
       the release, and move components into a staging area suitable for
-      uploading.  It is important to make sure that your key is mounted
-      during this process.  A simple <command>df</command> will show if it
-      is mounted.  If not mounted, mount the key with the passphrase supplied
-      when creating it earlier.</para>
+      uploading.</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
@@ -436,6 +450,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
 &prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 RELEASE-7.2</replaceable></userinput></screen>
     </informalexample>
 
+    <!-- If freebsd-update works with other http servers too, we should
+	 avoid making the instructions Apache-specific here. -->
     <para>The uploaded files will need to be in the
       <literal>DocumentRoot</literal> of the webserver in order for updates
       to be distributed.  For further explanation, please refer to the
@@ -443,6 +459,10 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
 	url="&url.books.handbook;/network-apache.html">Apache
 	documentation</ulink>.</para>
 
+    <!-- This note seems either out of place.  I find it hard to read and it
+	 is a bit difficult to understand why it is related to the rest of
+	 this section.  It looks like something that would fit nicely in an
+	 introductory section about the way a freebsd-update server works. -->
     <note>
       <para>Updates for the current release of the &os; system you are
 	updating, and what you want to upgrade <emphasis>to</emphasis> need
@@ -453,11 +473,14 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
 	&os; 7.2-RELEASE.</para>
     </note>
 
+    <!-- What is a 'KeyPrint'? -->
     <para>Update client's <literal>KeyPrint</literal> and
       <literal>ServerName</literal> in
       <filename>/etc/freebsd-update.conf</filename>, and perform updates as
       instructed in the <ulink
 	url="&url.books.handbook;/updating-freebsdupdate.html">&os; Update</ulink>
+      <!-- One sentence, two instances of 'in'.  We can probably reword this
+	   part to avoid repetition. -->
       instructions in the Handbook.</para>
 
     <para>For reference, here is the entire run of <ulink
@@ -467,9 +490,9 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
   <sect1 id="patch">
     <title>Building a Patch</title>
 
-    <para>In the event a <ulink
+    <para>Every time a <ulink
 	url="&url.base;/security/advisories.html">security advisory</ulink>
-      is posted, a patch update can be built.</para>
+      is announced, a patch update can be built.</para>
 
     <para>For this example, we will be using 7.1-RELEASE.</para>
 
@@ -487,8 +510,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
       </listitem>
     </itemizedlist>
 
-    <para>Create patch directory under
-      <filename class="directory">/usr/local/freebsd-update-server/patches/</filename> for the respective release.</para>
+    <para>Create the patch directory of the respective release
+      under <filename class="directory">/usr/local/freebsd-update-server/patches/</filename>.</para>
 
     <informalexample>
       <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/patches/RELEASE-7.1/</userinput></screen>
@@ -507,8 +530,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
       we can see it is called <literal>SA-09:12.bind</literal>.  After
       downloading the file, it is required to rename the file to an
       appropriate patch level.  It is suggested to keep this inline with
-      official &os; patch levels, however, this is just a suggestion.
-      For this build, let us follow the brief and call this
+      official &os; patch levels, but you are free to choose any name you prefer.
+      For this build, let us follow the currently established practice of &os; and call this
       <literal>p7</literal>.  Rename the file:</para>
 
     <informalexample>
@@ -524,9 +547,11 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
     <note>
       <para>When running a patch level build, we are assuming that previous
 	patches are in place.  When a patch build is run, it will run all
-	patches less than or equal to the number specified.  Beyond this,
-	you will have to take appropriate measures to verify authenticity
-	of the patch.</para>
+	patches less than or equal to the number specified.</para>
+
+      <para><emphasis>It is up to the administrator of the freebsd-update
+	  server to take appropriate measures to verify the authenticity of
+	  every patch.</emphasis></para>
 
       <para>You can also add your own patches to any build.  Use the number
 	zero, or any other number.</para>
@@ -642,7 +667,7 @@ files to confirm that they look sensible
 # sh -e approve.sh amd64 7.1-RELEASE
 to sign the build.</screen>
 
-    <para>Follow the same process as noted before for appoving a build.</para>
+    <para>Follow the same process as noted before for approving a build:</para>
 
     <screen>&prompt.root; <userinput>sh -e scripts/approve.sh amd64 7.1-RELEASE</userinput>
 Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.1-RELEASE
@@ -657,7 +682,7 @@ ready to be uploaded.  Remember to run
 to unmount the decrypted key once you have finished signing all
 the new builds.</screen>
 
-    <para>After approving the build, upload the software.</para>
+    <para>After approving the build, upload the software:</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
@@ -671,21 +696,40 @@ the new builds.</screen>
   <sect1 id="tips">
     <title>Tips</title>
 
+    <!-- These are nice tips, but there are only a few of them and they need a
+	 bit of rewording to make sense.  I'd like to see something that
+	 explains at least the following for every tip:
+
+	 * Why is this tip necessary?  What is the original problem it tries
+	   to solve?
+	 * How to install the changes of the tip (preferrably in a <procedure>
+	   element, with clearly separated steps.
+	 * How to check that the changes of the tip had a measurable and
+	   noticeable effect.
+
+	 We can do this in a followup commit.  It doesn't have to be completed
+	 *before* we commit this to CVS. -->
+
     <itemizedlist>
       <listitem>
 	<para>If you build your own release using the native
-	  <command>make release</command>,
+	  <command>make release</command> procedure, the
 	  <application>freebsd-update-server</application> code will work
+	  <!-- "from your release" seems a bit odd.  I think this part means
+	       that the freebsd-update code can be tweaked to build custom,
+	       locally tuned release snapshots.  Is that so? -->
 	  from your release.  As an example, you may build a release without
 	  ports or documentation and add a custom kernel.  After removing
 	  functionality pertaining to the documentation subroutine and
-	  altering the <literal>buildworld()</literal> subroutine in
-	  <filename>scripts/build.subr</filename> the
+	  altering the <function>buildworld()</function> subroutine in
+	  <filename>scripts/build.subr</filename>, the
 	  <application>freebsd-update-code</application> will successfully
 	  build update code on this release.</para>
       </listitem>
 
       <listitem>
+	<!-- We seem to be contradicting ourselves here.  Is it safe to add -j
+	     or other flags?  If not, why are we recommending it? -->
 	<para>Add <command>make -j <replaceable>NUMBER</replaceable></command>
 	  to <filename>scripts/build.subr</filename> to speed up processing.
 	  Adding flags to anything other than
@@ -695,6 +739,10 @@ the new builds.</screen>
       </listitem>
 
       <listitem>
+	<!-- Parse error.  I don't understand what this paragraph suggests or
+	     recommends.  Also, why do we need to block RSTs?  I don't really
+	     like gratuitous blocking of RST, ICMP or other packets.  Our
+	     kernel can rate-limit most of the "strange" packets alredy. -->
 	<para>Create a firewall rule to block outgoing RST packets.  Due to
 	  a bug noted <ulink
 	    url="http://unix.derkeiler.com/Mailing-Lists/FreeBSD/stable/2009-04/msg00365.html">in this posting</ulink>,
