alleviating some of the confusion with sections and subsections, prompted by Florian...

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2099 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/developers-reference.sgml b/developers-reference.sgml
index f0c6956bee8964288c17634c8297026877c33033..75da87d3d10f4c8c50b3ba7fd8bc3569be3cb814 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.165 $">
+  <!entity cvs-rev "$Revision: 1.166 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -761,6 +761,13 @@ On the other hand, a CD-ROM vendor could easily check the individual
 package licenses of the packages in <em>non-free</em> and include as
 many on the CD-ROMs as he's allowed to. (Since this varies greatly from
 vendor to vendor, this job can't be done by the Debian developers.)
+       <p>
+Note also that the term "section" is also used to refer to categories
+which simplify the organization and browsing of available packages, e.g.
+<em>admin</em>, <em>net</em>, <em>utils</em> etc. Once upon a time, these
+sections (subsections, rather) existed in the form of subdirectories within
+the Debian archive. Nowadays, these exist only in the "Section" header
+fields of packages.
 
 
       <sect1>Architectures
@@ -794,20 +801,6 @@ available at the <url id="&url-debian-ports;" name="Debian Ports web
 pages">.
 
 
-<!--      <sect1>Subsections
-       <p>
-The sections <em>main</em>, <em>contrib</em>, and <em>non-free</em>
-are split into <em>subsections</em> to simplify the installation
-process and the maintenance of the archive. Subsections simply exist to
-simplify the organization and browsing of available packages. The
-<url id="&url-debian-policy;" name="Debian Policy Manual"> gives
-the authoritative list of subsections.
-
-       <p>
-Note however that with the introduction of package pools (see the top-level
-<em>pool/</em> directory), the subsections in the form of subdirectories
-will eventually cease to exist. They will be kept in the packages' `Section'
-header fields, though. -->
 
       <sect1>Packages
        <p>
@@ -1496,7 +1489,7 @@ automatically using the <tt>Description</tt> field, see <ref
 id="upload-bugfix">.
 
 
-       <sect2>The original source tarball
+      <sect1>The original source tarball
          <p>
 The first time a version is uploaded which corresponds to a particular
 upstream version, the original source tar file should be uploaded and
@@ -1517,7 +1510,7 @@ source tar-file used by <prgn>dpkg-source</prgn> when constructing the
 byte-for-byte identical with the one already in the archive.
 
 
-       <sect2 id="upload-dist">Picking a distribution
+      <sect1 id="upload-dist">Picking a distribution
          <p>
 The <tt>Distribution</tt> field, which originates from the first line of
 the <file>debian/changelog</file> file, indicates which distribution the
@@ -1535,8 +1528,7 @@ because the dependencies of the package may vary with the distribution.
 In particular, it never makes sense to combine the <em>experimental</em>
 distribution with anything else.
 
-
-         <sect3 id="upload-stable">Uploading to <em>stable</em>
+       <sect2 id="upload-stable">Uploading to <em>stable</em>
            <p>
 Uploading to <em>stable</em> means that the package will be placed into the
 <file>stable-proposed-updates</file> directory of the Debian archive for further
@@ -1572,7 +1564,7 @@ verbose, if necessary) in your changelog entries for uploads to
 <em>stable</em>, because otherwise the package won't be considered for
 inclusion.
 
-         <sect3 id="upload-t-p-u">Uploading to <em>testing-proposed-updates</em>
+       <sect2 id="upload-t-p-u">Uploading to <em>testing-proposed-updates</em>
            <p>
 The testing distribution is fed with packages from unstable according to the rules
 explained in <ref id="testing">. However, the release manager may stop the testing
@@ -1590,6 +1582,7 @@ packages through <em>unstable</em>. If you can't (for example because you have a
 newer development version in unstable), you may use it but it is recommended to ask
 the authorization of the release manager before.
 
+
       <sect1 id="uploading">Uploading a package
 
        <sect2 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
@@ -1775,7 +1768,7 @@ The installation notification also includes information on what
 section the package was inserted into.  If there is a disparity, you
 will receive a separate email notifying you of that.  Read on below.
 
-       <sect2 id="override-file">The override file
+       <sect1 id="override-file">Package section and priority, or the override file
          <p>
 The <file>debian/control</file> file's <tt>Section</tt> and
 <tt>Priority</tt> fields do not actually specify where the file will
@@ -1803,7 +1796,10 @@ priority to the new one.  Be sure to explain your reasoning.
 For more information about <em>override files</em>, see <manref
 name="dpkg-scanpackages" section="8">, &file-bts-mailing;, and
 &file-bts-info;.
-
+       <p>
+Note also that the term "section" is used for the separation of packages
+according to their licensing, e.g. <em>main</em>, <em>contrib</em> and
+<em>non-free</em>. This is described in another section, <ref id="archive">.
 
 
     <sect id="nmu">Non-Maintainer Uploads (NMUs)