Add some more details, and document a couple of undocumented variables

that specify the distribution files.

s/http/HTTP/ in a few places.

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -524,9 +524,9 @@ lib/X11/oneko/mouse.xpm
           <emphasis>mainstream</emphasis> sources when and where you
           can.</para>
 
-        <para>If you cannot find a FTP/http site that is well-connected to the
+        <para>If you cannot find a FTP/HTTP site that is well-connected to the
           net, or can only find sites that have irritatingly non-standard
-          formats, you might want to put a copy on a reliable FTP or http
+          formats, you might want to put a copy on a reliable FTP or HTTP
           server that you control (e.g., your home page).  Make sure you set
           <makevar>MASTER_SITES</makevar> to reflect your choice.</para>
 
@@ -676,20 +676,27 @@ lib/X11/oneko/mouse.xpm
 	  default, though this should be rarely, if ever,
 	  necessary.</para>
       </sect1>
+    
+    <sect1>
+      <title>Naming and categorisation</title>
 
-      <sect1>
+      <para>The first part of the port's <filename>Makefile</filename> names
+	the port, describes it's version number, and lists it in the correct
+	category.</para>
+
+      <sect2>
         <title><makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar></title>
 
         <para>You should set <makevar>PORTNAME</makevar> to the
           base name of your port, and <makevar>PORTVERSION</makevar>
           to the version number of the port.</para>
-      </sect1>
+      </sect2>
 
-      <sect1>
+      <sect2>
 	<title><makevar>PORTREVISION</makevar> and
 	  <makevar>PORTEPOCH</makevar></title>
 
-	<sect2>
+	<sect3>
 	  <title><makevar>PORTREVISION</makevar></title>
 
 	  <para>The <makevar>PORTREVISION</makevar> variable is a
@@ -787,9 +794,9 @@ lib/X11/oneko/mouse.xpm
 	    automated tools (e.g.  <command>pkg_version</command>)
 	    will highlight the fact that a new package is
 	    available.</para>
-	</sect2>
+	</sect3>
 
-	<sect2>
+	<sect3>
 	  <title><makevar>PORTEPOCH</makevar></title>
 
 	  <para>From time to time a software vendor or FreeBSD porter
@@ -832,9 +839,9 @@ lib/X11/oneko/mouse.xpm
 	    <makevar>PORTVERSION</makevar> of 1.2.20000917 or similar,
 	    not 20000917, so that the succeeding release, say 1.3, is
 	    still a numerically greater value.</para>
-	</sect2>
+	</sect3>
 
-	<sect2>
+	<sect3>
 	  <title>Example of <makevar>PORTREVISION</makevar> and
 	    <makevar>PORTEPOCH</makevar> usage</title>
 
@@ -897,10 +904,10 @@ PORTEPOCH=	1</programlisting>
               <literal>3</literal> is still numerically less than
               <literal>10</literal>.</para>
 	  </note>
-        </sect2>
+        </sect3>
-      </sect1>
+      </sect2>
 
-      <sect1>
+      <sect2>
         <title><makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar></title>
 
 	<para>Two optional variables, <makevar>PKGNAMEPREFIX</makevar> and
@@ -919,9 +926,44 @@ PORTEPOCH=	1</programlisting>
           <makevar>PKGNAMEPREFIX</makevar> and
           <makevar>PKGNAMESUFFIX</makevar>, respectively.  Do not make
           them part of <makevar>PORTNAME</makevar>.</para>
-      </sect1>
+      </sect2>
 
-      <sect1>
+      <sect2>
+        <title><makevar>CATEGORIES</makevar></title>
+
+        <para>When a package is created, it is put under
+          <filename>/usr/ports/packages/All</filename> and links are made from
+          one or more subdirectories of
+          <filename>/usr/ports/packages</filename>.  The names of these
+          subdirectories are specified by the variable
+          <makevar>CATEGORIES</makevar>.  It is intended to make life easier
+          for the user when he is wading through the pile of packages on the
+          FTP site or the CDROM.  Please take a look at the existing <link
+            linkend="porting-categories">categories</link> and pick the ones
+          that are suitable for your port.</para>
+
+        <para>This list also determines where in the ports tree the port is
+          imported.  If you put more than one category here, it is assumed
+          that the port files will be put in the subdirectory with the name in
+          the first category.  See the <link
+            linkend="porting-categories">categories</link> section for more
+          discussion about how to pick the right categories.</para>
+
+        <para>If your port truly belongs to something that is different from
+          all the existing ones, you can even create a new category name.  In
+          that case, please send mail to the &a.ports; to propose a new
+          category.</para>
+      </sect2>
+    </sect1>
+
+    <sect1>
+      <title>The distribution files</title>
+
+      <para>The second part of the <filename>Makefile</filename> describes the
+	files that must be downloaded in order to build the port, and where
+	they can be downloaded from.</para>
+
+      <sect2>
         <title><makevar>DISTNAME</makevar></title>
 
         <para><makevar>DISTNAME</makevar> is the name of the port as
@@ -950,39 +992,12 @@ PORTEPOCH=	1</programlisting>
             <makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar>
             (and possibly <makevar>EXTRACT_SUFX</makevar>).</para>
 	</note>
-      </sect1>
+      </sect2>
 
-      <sect1>
+      <sect2>
-        <title><makevar>CATEGORIES</makevar></title>
-
-        <para>When a package is created, it is put under
-          <filename>/usr/ports/packages/All</filename> and links are made from
-          one or more subdirectories of
-          <filename>/usr/ports/packages</filename>.  The names of these
-          subdirectories are specified by the variable
-          <makevar>CATEGORIES</makevar>.  It is intended to make life easier
-          for the user when he is wading through the pile of packages on the
-          FTP site or the CDROM.  Please take a look at the existing <link
-            linkend="porting-categories">categories</link> and pick the ones
-          that are suitable for your port.</para>
-
-        <para>This list also determines where in the ports tree the port is
-          imported.  If you put more than one category here, it is assumed
-          that the port files will be put in the subdirectory with the name in
-          the first category.  See the <link
-            linkend="porting-categories">categories</link> section for more
-          discussion about how to pick the right categories.</para>
-
-        <para>If your port truly belongs to something that is different from
-          all the existing ones, you can even create a new category name.  In
-          that case, please send mail to the &a.ports; to propose a new
-          category.</para>
-      </sect1>
-
-      <sect1>
         <title><makevar>MASTER_SITES</makevar></title>
 
-        <para>Record the directory part of the FTP/http-URL pointing at the
+        <para>Record the directory part of the FTP/HTTP-URL pointing at the
           original tarball in <makevar>MASTER_SITES</makevar>.  Do not forget
           the trailing slash (<filename>/</filename>)!</para>
 
@@ -1019,13 +1034,47 @@ MASTER_SITE_SUBDIR=   applications</programlisting>
           variables in <filename>/etc/make.conf</filename> to override our
           choices, and use their favorite mirrors of these popular archives
           instead.</para>
-      </sect1>
+      </sect2>
 
-      <sect1 id="porting-patchfiles">
+      <sect2>
+	<title><makevar>DISTFILES</makevar></title>
+
+	<para>Sometimes the names of the files to be downloaded have no
+	  resemblance to the name of the port.  For example, it might be
+	  called <filename>source.tar.gz</filename> or similar.  In other
+	  cases the application's source code might be in several different
+	  archives, all of which must be downloaded.</para>
+
+	<para>If this is the case, set <makevar>DISTFILES</makevar> to be a
+	  space separated list of all the files that must be
+	  downloaded.</para>
+
+	<programlisting>DISTFILES=     source1.tar.gz source2.tar.gz</programlisting>
+      </sect2>
+
+      <sect2>
+	<title><makevar>EXTRACT_ONLY</makevar></title>
+
+	<para>If only some of the <makevar>DISTFILES</makevar> must be
+	  extracted&mdash;for example, one of them is the source code, while
+	  another is an uncompressed document&mdash;list the filenames that
+	  must be extracted in <makevar>EXTRACT_ONLY</makevar>.</para>
+
+	<programlisting>DISTFILES=     source.tar.gz manual.html
+EXTRACT_ONLY=  source.tar.gz</programlisting>
+
+	<para>If <emphasis>none</emphasis> of the <makevar>DISTFILES</makevar>
+	  should be uncompressed then set <makevar>EXTRACT_ONLY</makevar> to
+	  the empty string.</para>
+
+	<programlisting>EXTRACT_ONLY=</programlisting>
+      </sect2>
+
+      <sect2 id="porting-patchfiles">
         <title><makevar>PATCHFILES</makevar></title>
 
         <para>If your port requires some additional patches that are available
-          by FTP or http, set <makevar>PATCHFILES</makevar> to the names of
+          by FTP or HTTP, set <makevar>PATCHFILES</makevar> to the names of
           the files and <makevar>PATCH_SITES</makevar> to the URL of the
           directory that contains them (the format is the same as
           <makevar>MASTER_SITES</makevar>).</para>
@@ -1054,7 +1103,7 @@ MASTER_SITE_SUBDIR=   applications</programlisting>
           not be writable.</para>
 
         <note>
-          <para>Note that the tarball will have been extracted alongside the
+          <para>The tarball will have been extracted alongside the
             regular source by then, so there is no need to explicitly extract
             it if it is a regular gzip'd or compress'd tarball. If you do the
             latter, take extra care not to overwrite something that already
@@ -1062,7 +1111,50 @@ MASTER_SITE_SUBDIR=   applications</programlisting>
             remove the copied patch in the <maketarget>pre-clean</maketarget>
             target.</para>
         </note>
-      </sect1>
+      </sect2>
+
+      <sect2>
+	<title>Multiple distribution files from different sites</title>
+
+	<para>Some applications consist of multiple distribution files that
+	  must be downloaded from a number of different sites.  For example,
+	  <application>Ghostscript</application> consists of the core of the
+	  program, and then a large number of driver files that are used
+	  depending on the user's printer.  Some of these driver files are
+	  supplied with the core, but many others must be downloaded from a
+	  variety of different sites.</para>
+
+	<para>To support this, each entry in <makevar>DISTFILES</makevar> may
+	  be followed by a colon and a <quote>tag name</quote>.  Each site
+	  listed in <makevar>MASTER_SITES</makevar> is then followed by a
+	  colon, and the tag that indicates which distribution files should be
+	  downloaded from this site.</para>
+
+	<para>For example, consider an application with the source split in to
+	  <filename>source1.tar.gz</filename> and
+	  <filename>source2.tar.gz</filename>, which must be downloaded from
+	  two different sites.  The port's <filename>Makefile</filename> would
+	  include lines like this:</para>
+
+	<programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
+              ftp://ftp.example2.com/:source2
+DISTFILES=    source1.tar.gz:source1 \
+              source2.tar.gz:source2</programlisting>
+
+	<para>Multiple distribution files can have the same tag.  Continuing
+	  the previous example, suppose that there was a third distfile,
+	  <filename>source3.tar.gz</filename>, that should be downloaded from
+	  <hostid>ftp.example2.com</hostid>.  The
+	  <filename>Makefile</filename> would then be written like
+	  this.</para>
+
+	<programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
+              ftp://ftp.example2.com/:source2
+DISTFILES=    source1.tar.gz:source1 \
+              source2.tar.gz:source2 \
+              source3.tar.gz:source2</programlisting>
+      </sect2>
+    </sect1>
 
       <sect1>
         <title><makevar>MAINTAINER</makevar></title>