* Finished updates to chapter 7

[debian/debian-policy.git] / policy.sgml

diff --git a/policy.sgml b/policy.sgml
index 85a1926e6f1578a6ea8989ae69aea07ca23e4845..68083420d2e1f9a7885c83519ff5dfdb5d6e200b 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -86,9 +86,9 @@
          <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
          distribution or on the World Wide Web at
          <url id="http://www.gnu.org/copyleft/gpl.html"
          <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
          distribution or on the World Wide Web at
          <url id="http://www.gnu.org/copyleft/gpl.html"

-              name="The GNU General Public Licence">. You can also obtain it by writing to the
-         Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-         Boston, MA 02111-1307, USA.
+              name="The GNU General Public Licence">. You can also
+         obtain it by writing to the Free Software Foundation, Inc.,
+         59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

        </p>
       </copyright>
     </titlepag>
        </p>
       </copyright>
     </titlepag>


@@ -132,7 +132,7 @@
                    interfaces not changing, and the package
                    management software authors need to ensure
                    compatibility with these interface
                    interfaces not changing, and the package
                    management software authors need to ensure
                    compatibility with these interface

-                   definitions. (Control file and and changelog file
+                   definitions. (Control file and changelog file

                    formats are examples.)
                  </p>
                </item>
                    formats are examples.)
                  </p>
                </item>


@@ -164,7 +164,7 @@
          <em>may</em>, and the adjectives <em>required</em>,
          <em>recommended</em> and <em>optional</em>, are used to
          distinguish the significance of the various guidelines in
          <em>may</em>, and the adjectives <em>required</em>,
          <em>recommended</em> and <em>optional</em>, are used to
          distinguish the significance of the various guidelines in

-         this policy document. Packages that do not conform the the
+         this policy document. Packages that do not conform to the

          guidelines denoted by <em>must</em> (or <em>required</em>)
          will generally not be considered acceptable for the Debian
          distribution. Non-conformance with guidelines denoted by
          guidelines denoted by <em>must</em> (or <em>required</em>)
          will generally not be considered acceptable for the Debian
          distribution. Non-conformance with guidelines denoted by


@@ -578,7 +578,7 @@
          <p>
            Every package must be accompanied by a verbatim copy of
            its copyright and distribution license in the file
          <p>
            Every package must be accompanied by a verbatim copy of
            its copyright and distribution license in the file

-           <tt>/usr/share/doc/<ital>&lt;package-name&gt;</ital>/copyright</tt>
+           <tt>/usr/share/doc/<em>&lt;package-name&gt;</em>/copyright</tt>

            (see <ref id="copyrightfile"> for further details).
          </p>
          <p>
            (see <ref id="copyrightfile"> for further details).
          </p>
          <p>


@@ -673,13 +673,13 @@
            <list compact="compact">
              <item>
                <p>
            <list compact="compact">
              <item>
                <p>

-                 <ital>subsection</ital> if the package is in the
+                 <em>subsection</em> if the package is in the

                  <em>main</em> section,
                </p>
              </item>
              <item>
                <p>
                  <em>main</em> section,
                </p>
              </item>
              <item>
                <p>

-                 <ital>section/subsection</ital> if the package is in
+                 <em>section/subsection</em> if the package is in

                  the <em>contrib</em> or <em>non-free</em> section,
                  and
                </p>
                  the <em>contrib</em> or <em>non-free</em> section,
                  and
                </p>


@@ -764,8 +764,8 @@
            <item>
              <p>
                These packages provide a reasonably small but not too
            <item>
              <p>
                These packages provide a reasonably small but not too

-               limited character-mode system.  This is what will
-               install by default if the user doesn't select anything
+               limited character-mode system.  This is what will be
+               installed by default if the user doesn't select anything

                else.  It doesn't include many large applications, but
                it does include Emacs (this is more of a piece of
                infrastructure than an application) and a reasonable
                else.  It doesn't include many large applications, but
                it does include Emacs (this is more of a piece of
                infrastructure than an application) and a reasonable


@@ -1181,7 +1181,7 @@
       <sect>
        <heading>Source packages</heading>
 
       <sect>
        <heading>Source packages</heading>
 

-       <sect1>
+       <sect1 id="standardsversion">

          <heading>Standards conformance</heading>
 
          <p>
          <heading>Standards conformance</heading>
 
          <p>


@@ -1458,29 +1458,40 @@
 
       <p>
        Many of the tools in the package management suite manipulate
 
       <p>
        Many of the tools in the package management suite manipulate

-       data in a common format, known as control files.  Binary and
-       source packages have control data as do the <tt>.changes</tt>
-       files which control the installation of uploaded files, and
-       <prgn>dpkg</prgn>'s internal databases are in a similar
+       data represented in a common format, known as <em>control
+       data</em>.  The data is often stored in <em>control
+       files</em>.  Binary and source packages have control files,
+       and the <tt>.changes</tt> files which control the installation
+       of uploaded files are also in control file format.
+       <prgn>Dpkg</prgn>'s internal databases are in a similar

        format.
       </p>
 
        format.
       </p>
 

-      <sect><heading>Syntax of control files</heading>
+      <sect id="controlsyntax"><heading>Syntax of control files</heading>

 
        <p>
 
        <p>

-         A file consists of one or more paragraphs of fields.  The
-         paragraphs are separated by blank lines.  Some control files
-         only allow one paragraph; others allow several, in which
-         case each paragraph often refers to a different package.
+         A control file consists of one or more paragraphs of fields.
+         The paragraphs are separated by blank lines.  Some control
+         files allow only one paragraph; others allow several, in
+         which case each paragraph usually refers to a different
+         package.  (For example, in source packages, the first
+         paragraph refers to the source package, and later paragraphs
+         refer to binary packages generated from the source.)

        </p>
 
        <p>
        </p>
 
        <p>

-         Each paragraph is a series of fields and values; each field
-         consists of a name, followed by a colon and the value.  It
-         ends at the end of the line.  Horizontal whitespace (spaces
-         and tabs) may occur immediately before or after the value
-         and is ignored there; it is conventional to put a single
-         space after the colon.
+         Each paragraph consists of a series of data fields; each
+         field consists of the field name, followed by a colon and
+         then the data/value associated with that field.  It ends at
+         the end of the line.  Horizontal whitespace (spaces and
+         tabs) may occur immediately before or after the value and is
+         ignored there; it is conventional to put a single space
+         after the colon.  For example, a field might be:
+         <example>
+           Package: libc6
+         </example>
+         the field name is <tt>Package</tt> and the field value
+         <tt>libc6</tt>.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -1493,9 +1504,9 @@
        <p>
          Except where otherwise stated only a single line of data is
          allowed and whitespace is not significant in a field body.
        <p>
          Except where otherwise stated only a single line of data is
          allowed and whitespace is not significant in a field body.

-         Whitespace may never appear inside names (of packages,
-         architectures, files or anything else), version numbers or
-         in between the characters of multi-character version
+         Whitespace must not appear inside names (of packages,
+         architectures, files or anything else) or version numbers,
+         or between the characters of multi-character version

          relationships.
        </p>
 
          relationships.
        </p>
 


@@ -1510,21 +1521,12 @@
          would mean a new paragraph.
        </p>
 
          would mean a new paragraph.
        </p>
 

-       <p>
-         It is important to note that there are several fields which
-         are optional as far as <prgn>dpkg</prgn> and the related
-         tools are concerned, but which must appear in every Debian
-         package, or whose omission may cause problems.  When writing
-         the control files for Debian packages you <em>must</em> read
-         the Debian policy manual in conjunction with the details
-         below and the list of fields for the particular file.</p>

       </sect>
 
       <sect><heading>List of fields</heading>
        <p>
          This list here is not supposed to be exhaustive. Most fields
       </sect>
 
       <sect><heading>List of fields</heading>
        <p>
          This list here is not supposed to be exhaustive. Most fields

-         are dealt with elsewhere in this document and in the
-         dpkg documentation.
+         are dealt with elsewhere in this document.

        </p>
        <sect1 id="f-Package"><heading><tt>Package</tt>
          </heading>
        </p>
        <sect1 id="f-Package"><heading><tt>Package</tt>
          </heading>


@@ -1537,10 +1539,10 @@
 
          <p>
            They must be at least two characters long and must start
 
          <p>
            They must be at least two characters long and must start

-           with an alphanumeric character.  The use of lowercase
-           package names is strongly recommended unless the package
-           you're building (or referring to, in other fields) is
-           already using uppercase.</p>
+           with an alphanumeric character and not be all digits.  The
+           use of lowercase package names is strongly recommended
+           unless the package you're building (or referring to, in
+           other fields) is already using uppercase.</p>

        </sect1>
 
        <sect1 id="f-Version"><heading><tt>Version</tt>
        </sect1>
 
        <sect1 id="f-Version"><heading><tt>Version</tt>


@@ -1563,12 +1565,9 @@
            complies.  This is updated manually when editing the
            source package to conform to newer standards; it can
            sometimes be used to tell when a package needs attention.
            complies.  This is updated manually when editing the
            source package to conform to newer standards; it can
            sometimes be used to tell when a package needs attention.

+           Its format is described above; see
+           <ref id="standardsversion">.

          </p>
          </p>

-
-         <p>
-           Its format is the same as that of a version number except
-           that no epoch or Debian revision is allowed - see <ref
-                                                                  id="versions">.</p>

        </sect1>
 
 
        </sect1>
 
 


@@ -1579,23 +1578,21 @@
            In a <tt>.changes</tt> file or parsed changelog output
            this contains the (space-separated) name(s) of the
            distribution(s) where this version of the package should
            In a <tt>.changes</tt> file or parsed changelog output
            this contains the (space-separated) name(s) of the
            distribution(s) where this version of the package should

-           be or was installed.  Distribution names follow the rules
-           for package names.  (See <ref id="f-Package">).
-         </p>
-
-         <p>
+           be installed.  Valid distributions are determined by the
+           archive maintainers.

            <footnote>
            <footnote>

-               Current distribution values are:
+               Current distribution names are:

                <taglist>
                  <tag><em>stable</em></tag>
                  <item>
                    <p>
                      This is the current `released' version of Debian
                <taglist>
                  <tag><em>stable</em></tag>
                  <item>
                    <p>
                      This is the current `released' version of Debian

-                     GNU/Linux.  Once the
-                     distribution is <em>stable</em> only major bug fixes
-                     are allowed. When changes are made to this
-                     distribution, the release number is increased
-                     (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
+                     GNU/Linux.  Once the distribution is
+                     <em>stable</em> only security fixes and other
+                     major bug fixes are allowed. When changes are
+                     made to this distribution, the release number is
+                     increased (for example: 2.2r1 becomes 2.2r2 then
+                     2.2r3, etc).

                    </p>
                  </item>
 
                    </p>
                  </item>
 


@@ -1611,71 +1608,51 @@
                    </p>
                  </item>
 
                    </p>
                  </item>
 

+                 <tag><em>testing</em></tag>
+                 <item>
+                   <p>
+                     This distribution value refers to the
+                     <em>testing</em> part of the Debian distribution
+                     tree.  It receives its packages from the
+                     unstable distribution after a short time lag to
+                     ensure that there are no major issues with the
+                     unstable packages.  It is less prone to breakage
+                     than unstable, but still risky.  It is not
+                     possible to upload packages directly to
+                     <em>testing</em>.
+                   </p>
+                 </item>
+

                  <tag><em>frozen</em></tag>
                  <item>
                    <p>
                  <tag><em>frozen</em></tag>
                  <item>
                    <p>

-                     From time to time, the <em>unstable</em>
+                     From time to time, the <em>frozen</em>

                      distribution enters a state of `code-freeze' in
                      anticipation of release as a <em>stable</em>
                      version. During this period of testing only
                      fixes for existing or newly-discovered bugs will
                      distribution enters a state of `code-freeze' in
                      anticipation of release as a <em>stable</em>
                      version. During this period of testing only
                      fixes for existing or newly-discovered bugs will

-                     be allowed.
+                     be allowed.  The exact details of this stage are
+                     determined by the Release Manager.

                    </p>
                  </item>
 
                  <tag><em>experimental</em></tag>
                  <item>
                    <p>
                    </p>
                  </item>
 
                  <tag><em>experimental</em></tag>
                  <item>
                    <p>

-                     The packages with this distribution value are deemed
-                     by their maintainers to be high risk. Oftentimes they
-                     represent early beta or developmental packages from
-                     various sources that the maintainers want people to
-                     try, but are not ready to be a part of the other parts
-                     of the Debian distribution tree. Download at your own
+                     The packages with this distribution value are
+                     deemed by their maintainers to be high
+                     risk. Oftentimes they represent early beta or
+                     developmental packages from various sources that
+                     the maintainers want people to try, but are not
+                     ready to be a part of the other parts of the
+                     Debian distribution tree. Download at your own

                      risk.
                    </p>
                  </item>
                </taglist>
                      risk.
                    </p>
                  </item>
                </taglist>

-               There are several sections in each
-               distribution. Currently, these sections are:

 
 

-               <taglist>
-                 <tag><em>main</em></tag>
-                 <item>
-                   <p>
-                     The packages in this section are those in the
-                     main Debian distribution.  They are all free
-                     (according to the Debian free software
-                     guidelines) and meet any other criteria for
-                     inclusion described in this manual.</p>
-                 </item>
-
-                 <tag><em>contrib</em></tag>
-                 <item>
-                   <p>
-                     The packages in this section do not meet the
-                     criteria for inclusion in the main Debian
-                     distribution as defined by this manual, but are
-                     otherwise free, as defined by the Debian free
-                     software guidelines.</p>
-                 </item>
-
-                 <tag><em>non-free</em></tag>
-                 <item>
-                   <p>
-                     Packages in <em>non-free</em> do not meet the
-                     criteria of free software, as defined by the
-                     Debian free software guidelines. Again, use your
-                     best judgment in downloading from this
-                     Distribution.</p>
-                 </item>
-
-               </taglist> You should list <em>all</em> distributions that
-               the package should be installed into. Except in unusual
-               circumstances, installations to <em>stable</em> should also
-               go into <em>frozen</em> (if it exists) and
-               <em>unstable</em>. Likewise, installations into
-               <em>frozen</em> should also go into <em>unstable</em>.
+               You should list <em>all</em> distributions that the
+               package should be installed into.

            </footnote>
          </p>
        </sect1>
            </footnote>
          </p>
        </sect1>


@@ -1684,11 +1661,11 @@
       </sect>
     </chapt>
 
       </sect>
     </chapt>
 

-    <chapt id="versions"><heading>Version numbering    </heading>
+    <chapt id="versions"><heading>Version numbering</heading>

 
       <p>
 
       <p>

-       Every package has a version number, in its <tt>Version</tt>
-       control file field.
+       Every package has a version number recorded in its
+       <tt>Version</tt> control file field.

       </p>
 
       <p>
       </p>
 
       <p>


@@ -1703,7 +1680,7 @@
 
       <p>
        The version number format is:
 
       <p>
        The version number format is:

-       &lsqb<var>epoch</var><tt>:</tt>&rsqb;<var>upstream-version</var>&lsqb;<tt>-</tt><var>debian-revision</var>&rsqb;
+       &lsqb<var>epoch</var><tt>:</tt>&rsqb;<var>upstream_version</var>&lsqb;<tt>-</tt><var>debian_revision</var>&rsqb;

       </p>
 
       <p>
       </p>
 
       <p>


@@ -1715,7 +1692,7 @@
            <p>
              This is a single (generally small) unsigned integer.  It
              may be omitted, in which case zero is assumed.  If it is
            <p>
              This is a single (generally small) unsigned integer.  It
              may be omitted, in which case zero is assumed.  If it is

-             omitted then the <var>upstream-version</var> may not
+             omitted then the <var>upstream_version</var> may not

              contain any colons.
            </p>
 
              contain any colons.
            </p>
 


@@ -1727,81 +1704,81 @@
 
          </item>
 
 
          </item>
 

-         <tag><var>upstream-version</var></tag>
+         <tag><var>upstream_version</var></tag>

          <item>
 
            <p>
          <item>
 
            <p>

-             This is the main part of the version.  It is usually the
-             version number of the original (`upstream') package from
-             which the <tt>.deb</tt> file has been made, if this is
-             applicable.  Usually this will be in the same format as
-             that specified by the upstream author(s); however, it
-             may need to be reformatted to fit into the package
-             management system's format and comparison scheme.
+             This is the main part of the version number.  It is
+             usually the version number of the original (`upstream')
+             package from which the <tt>.deb</tt> file has been made,
+             if this is applicable.  Usually this will be in the same
+             format as that specified by the upstream author(s);
+             however, it may need to be reformatted to fit into the
+             package management system's format and comparison
+             scheme.

            </p>
 
            <p>
              The comparison behavior of the package management system
            </p>
 
            <p>
              The comparison behavior of the package management system

-             with respect to the <var>upstream-version</var> is
-             described below.  The <var>upstream-version</var>
+             with respect to the <var>upstream_version</var> is
+             described below.  The <var>upstream_version</var>

              portion of the version number is mandatory.
            </p>
 
            <p>
              portion of the version number is mandatory.
            </p>
 
            <p>

-             The <var>upstream-version</var> may contain only
-             alphanumerics and the characters <tt>.</tt> <tt>+</tt>
-             <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
-             and should start with a digit.  If there is no
-             <var>debian-revision</var> then hyphens are not allowed;
+             The <var>upstream_version</var> may contain only
+             alphanumerics
+             <footnote>
+               <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
+             </footnote>
+             and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
+             <tt>:</tt> (full stop, plus, hyphen, colon) and should
+             start with a digit.  If there is no
+             <var>debian_revision</var> then hyphens are not allowed;

              if there is no <var>epoch</var> then colons are not
              allowed.</p>
          </item>
 
              if there is no <var>epoch</var> then colons are not
              allowed.</p>
          </item>
 

-         <tag><var>debian-revision</var></tag>
+         <tag><var>debian_revision</var></tag>

          <item>
 
            <p>
          <item>
 
            <p>

-             This part of the version represents the version of the
-             modifications that were made to the package to make it a
-             Debian binary package.  It is in the same format as the
-             <var>upstream-version</var> and is compared in the same
-             way.
+             This part of the version number specifies the version of
+             the Debian package based on the upstream version.  It
+             may contain only alphanumerics and the characters
+             <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
+             compared in the same way as the
+             <var>upstream_version</var> is.

            </p>
 
            <p>
              It is optional; if it isn't present then the
            </p>
 
            <p>
              It is optional; if it isn't present then the

-             <var>upstream-version</var> may not contain a hyphen.
+             <var>upstream_version</var> may not contain a hyphen.

              This format represents the case where a piece of
              software was written specifically to be turned into a
              This format represents the case where a piece of
              software was written specifically to be turned into a

-             Debian binary package, and so there is only one
-             `debianization' of it and therefore no revision
-             indication is required.
+             Debian package, and so there is only one `debianization'
+             of it and therefore no revision indication is required.

            </p>
 
            <p>
              It is conventional to restart the
            </p>
 
            <p>
              It is conventional to restart the

-             <var>debian-revision</var> at <tt>1</tt> each time the
-             <var>upstream-version</var> is increased.
-           </p>
-
-           <p>
-             The package management system will break the
-             <var>upstream-version</var> and
-             <var>debian-revision</var> apart at the last hyphen in
-             the string.  The absence of a <var>debian-revision</var>
-             compares earlier than the presence of one (but note that
-             the <var>debian-revision</var> is the least significant
-             part of the version number).
+             <var>debian_revision</var> at <tt>1</tt> each time the
+             <var>upstream_version</var> is increased.

            </p>
 
            <p>
            </p>
 
            <p>

-             The <var>debian-revision</var> may contain only
-             alphanumerics and the characters <tt>+</tt> and
-             <tt>.</tt> (plus and full stop).
+             The package management system will break the version
+             number apart at the last hyphen in the string (if there
+             is one) to determine the <var>upstream_version</var> and
+             <var>debian_revision</var>.  The absence of a
+             <var>debian_revision</var> compares earlier than the
+             presence of one (but note that the
+             <var>debian_revision</var> is the least significant part
+             of the version number).

            </p>
          </item>
        </taglist>
            </p>
          </item>
        </taglist>

-       The <var>upstream-version</var> and <var>debian-revision</var>
+       The <var>upstream_version</var> and <var>debian_revision</var>

        parts are compared by the package management system using the
        same algorithm:
       </p>
        parts are compared by the package management system using the
        same algorithm:
       </p>


@@ -1830,21 +1807,22 @@
       </p>
 
       <p>
       </p>
 
       <p>

-       These two steps are repeated (chopping initial non-digit
-       strings and initial digit strings off from the start) until a
+       These two steps (comparing and removing initial non-digit
+       strings and initial digit strings) are repeated until a

        difference is found or both strings are exhausted.
       </p>
 
       <p>
        Note that the purpose of epochs is to allow us to leave behind
        mistakes in version numbering, and to cope with situations
        difference is found or both strings are exhausted.
       </p>
 
       <p>
        Note that the purpose of epochs is to allow us to leave behind
        mistakes in version numbering, and to cope with situations

-       where the version numbering changes.  It is <em>not</em> there
-       to cope with version numbers containing strings of letters
-       which the package management system cannot interpret (such as
-       <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
-       author of this manual has heard of a package whose versions
-       went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
-       <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
+       where the version numbering scheme changes.  It is
+       <em>not</em> intended to cope with version numbers containing
+       strings of letters which the package management system cannot
+       interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
+       silly orderings (the author of this manual has heard of a
+       package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
+       <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
+       <tt>2</tt> and so forth).

       </p>
 
       <p>
       </p>
 
       <p>


@@ -1875,7 +1853,7 @@
          too.</p>
 
        <p>
          too.</p>
 
        <p>

-         Note, that other version formats based on dates which are
+         Note that other version formats based on dates which are

          parsed correctly by the package management system should
          <em>not</em> be changed.</p>
 
          parsed correctly by the package management system should
          <em>not</em> be changed.</p>
 


@@ -1890,10 +1868,9 @@
 
       <sect id="timestamps"><heading>Time Stamps</heading>
        <p>
 
       <sect id="timestamps"><heading>Time Stamps</heading>
        <p>

-         Maintainers are encouraged to preserve the modification
-         times of the upstream source files in a package, as far as
-         is reasonably possible. Even though this is optional, this
-         is still a good idea.
+         Maintainers should preserve the modification times of the
+         upstream source files in a package, as far as is reasonably
+         possible.

          <footnote>
            <p>
              The rationale is that there is some information conveyed
          <footnote>
            <p>
              The rationale is that there is some information conveyed


@@ -1908,12 +1885,12 @@
       </sect>
 
       <sect id="debianrules"><heading><tt>debian/rules</tt> - the
       </sect>
 
       <sect id="debianrules"><heading><tt>debian/rules</tt> - the

-         main building script    </heading>
+         main building script</heading>

 
        <p>
          This file must be an executable makefile, and contains the
          package-specific recipes for compiling the package and
 
        <p>
          This file must be an executable makefile, and contains the
          package-specific recipes for compiling the package and

-         building binary package(s) out of the source.
+         building binary package(s) from the source.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -1926,7 +1903,7 @@
          Since an interactive <tt>debian/rules</tt> script makes it
          impossible to auto-compile that package and also makes it
          hard for other people to reproduce the same binary
          Since an interactive <tt>debian/rules</tt> script makes it
          impossible to auto-compile that package and also makes it
          hard for other people to reproduce the same binary

-         package, all <strong>required targets</strong> MUST be
+         package, all <em>required targets</em> MUST be

          non-interactive. At a minimum, required targets are the
          ones called by <prgn>dpkg-buildpackage</prgn>, namely,
          <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
          non-interactive. At a minimum, required targets are the
          ones called by <prgn>dpkg-buildpackage</prgn>, namely,
          <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,


@@ -1936,17 +1913,21 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         The targets which must be present are:
+         The required and optional targets are as follows:

          <taglist>
            <tag><tt>build</tt></tag>
            <item>
              <p>
          <taglist>
            <tag><tt>build</tt></tag>
            <item>
              <p>

-               This should perform all non-interactive
-               configuration and compilation of the package.  If a
-               package has an interactive pre-build configuration
-               routine, the Debianised source package should be
-               built after this has taken place, so that it can be
-               built without rerunning the configuration.
+               This should perform all non-interactive configuration
+               and compilation of the package.  If a package has an
+               interactive pre-build configuration routine, the
+               Debianized source package must either be built after
+               this has taken place (so that the binary package can
+               be built without rerunning the configuration) or the
+               configuration routine modified to become
+               non-interactive.  (The latter is preferable if there
+               are architecture-specific features detected by the
+               configuration routine.)

              </p>
 
              <p>
              </p>
 
              <p>


@@ -1969,19 +1950,35 @@
              </p>
 
              <p>
              </p>
 
              <p>

-               The <prgn>build</prgn> target may need to run
-               <prgn>clean</prgn> first - see below.
+               The <prgn>build</prgn> target may need to run the
+               <prgn>clean</prgn> target first - see below.

              </p>
 
              <p>
              </p>
 
              <p>

-               When a package has a configuration routine that
-               takes a long time, or when the makefiles are poorly
-               designed, or when <prgn>build</prgn> needs to run
-               <prgn>clean</prgn> first, it is a good idea to
+               When a package has a configuration and build routine
+               which takes a long time, or when the makefiles are
+               poorly designed, or when <prgn>build</prgn> needs to
+               run <prgn>clean</prgn> first, it is a good idea to

                <tt>touch build</tt> when the build process is
                complete.  This will ensure that if <tt>debian/rules
                <tt>touch build</tt> when the build process is
                complete.  This will ensure that if <tt>debian/rules

-                 build</tt> is run again it will not rebuild the
-               whole program.
+               build</tt> is run again it will not rebuild the whole
+               program.
+               <footnote>
+                 <p>
+                   Another common way to do this is for <prgn>build</prgn>
+                   to depend on <prgn>build-stamp</prgn> and to do
+                   nothing else, and for the <prgn>build-stamp</prgn>
+                   target to do the building and to <tt>touch
+                   build-stamp</tt> on completion.  This is
+                   especially useful if the build routine creates a
+                   file or directory called <tt>build</tt>; in such a
+                   case, <prgn>build</prgn> will need to be listed as
+                   a phony target (i.e., as a dependency of the
+                   <tt>.PHONY</tt> target).  See the documentation of
+                   <prgn>make</prgn> for more information on phony
+                   targets.
+                 </p>
+               </footnote>

              </p>
            </item>
 
              </p>
            </item>
 


@@ -1991,11 +1988,11 @@
            <item>
              <p>
                The <prgn>binary</prgn> target must be all that is
            <item>
              <p>
                The <prgn>binary</prgn> target must be all that is

-               necessary for the user to build the binary
-               package. All these targets are required to be
-               non-interactive.  It is split into two parts:
-               <prgn>binary-arch</prgn> builds the packages' output
-               files which are specific to a particular
+               necessary for the user to build the binary package(s)
+               produced from this source package.  All of these
+               targets are required to be non-interactive.  It is
+               split into two parts: <prgn>binary-arch</prgn> builds
+               the binary packages which are specific to a particular

                architecture, and <prgn>binary-indep</prgn> builds
                those which are not.
              </p>
                architecture, and <prgn>binary-indep</prgn> builds
                those which are not.
              </p>


@@ -2008,7 +2005,7 @@
              </p>
 
              <p>
              </p>
 
              <p>

-               Both <prgn>binary-*</prgn> targets should depend on
+               Each <prgn>binary-*</prgn> target should depend on

                the <prgn>build</prgn> target, above, so that the
                package is built if it has not been already.  It
                should then create the relevant binary package(s),
                the <prgn>build</prgn> target, above, so that the
                package is built if it has not been already.  It
                should then create the relevant binary package(s),


@@ -2019,17 +2016,24 @@
              </p>
 
              <p>
              </p>
 
              <p>

-               If one of the <prgn>binary-*</prgn> targets has
-               nothing to do (this will be always be the case if
-               the source generates only a single binary package,
-               whether architecture-dependent or not) it
-               <em>must</em> still exist, and must always
-               succeed.
+               Both the <prgn>binary-arch</prgn> and
+               <prgn>binary-indep</prgn> targets <em>must</em> exist.
+               If one of them has nothing to do (which will always be
+               the case if the source generates only a single binary
+               package, whether architecture-dependent or not), it
+               must still exist and must always succeed.

              </p>
 
              <p>
                The <prgn>binary</prgn> targets must be invoked as
                root.
              </p>
 
              <p>
                The <prgn>binary</prgn> targets must be invoked as
                root.

+               <footnote>
+                 <p>
+                   The <prgn>fakeroot</prgn> package often allows one
+                   to build a package correctly even without being
+                   root.
+                 </p>
+               </footnote>

              </p>
            </item>
 
              </p>
            </item>
 


@@ -2037,19 +2041,18 @@
            <item>
 
              <p>
            <item>
 
              <p>

-               This must undo any effects that the
-               <prgn>build</prgn> and <prgn>binary</prgn> targets
-               may have had, except that it should leave alone any
-               output files created in the parent directory by a
-               run of <prgn>binary</prgn>. This target must be
-               non-interactive.
+               This must undo any effects that the <prgn>build</prgn>
+               and <prgn>binary</prgn> targets may have had, except
+               that it should leave alone any output files created in
+               the parent directory by a run of a <prgn>binary</prgn>
+               target. This target must be non-interactive.

              </p>
 
              <p>
              </p>
 
              <p>

-               If a <prgn>build</prgn> file is touched at the end
-               of the <prgn>build</prgn> target, as suggested
-               above, it should be removed as the first thing that
-               <prgn>clean</prgn> does, so that running
+               If a <prgn>build</prgn> file is touched at the end of
+               the <prgn>build</prgn> target, as suggested above, it
+               should be removed as the first action that
+               <prgn>clean</prgn> performs, so that running

                <prgn>build</prgn> again after an interrupted
                <prgn>clean</prgn> doesn't think that everything is
                already done.
                <prgn>build</prgn> again after an interrupted
                <prgn>clean</prgn> doesn't think that everything is
                already done.


@@ -2092,8 +2095,8 @@
 
        <p>
          The <prgn>build</prgn>, <prgn>binary</prgn> and
 
        <p>
          The <prgn>build</prgn>, <prgn>binary</prgn> and

-         <prgn>clean</prgn> targets must be invoked with a current
-         directory of the package's top-level directory.
+         <prgn>clean</prgn> targets must be invoked with the current
+         directory being the package's top-level directory.

        </p>
 
 
        </p>
 
 


@@ -2104,11 +2107,14 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         The architecture we build on and build for is determined by
-         make variables via dpkg-architecture. You can get the Debian
-         architecture and the GNU style architecture specification
-         string for the build machine as well as the host
-         machine. Here is a list of supported make variables:
+         The architectures we build on and build for are determined
+         by <prgn>make</prgn> variables using the utility
+         <prgn>dpkg-architecture</prgn>.  You can determine the
+         Debian architecture and the GNU style architecture
+         specification string for the build machine (the machine type
+         we are building on) as well as for the host machine (the
+         machine type we are building for).  Here is a list of
+         supported <prgn>make</prgn> variables:

          <list compact="compact">
            <item>
              <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
          <list compact="compact">
            <item>
              <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>


@@ -2118,25 +2124,23 @@
                specification string)</p>
            </item>
            <item>
                specification string)</p>
            </item>
            <item>

-             <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+             <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of
+             <tt>DEB_*_GNU_TYPE</tt>)</p>

            </item>
            <item>
              <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
            </item>
            <item>
              <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of

-               DEB_*_GNU_TYPE)</p>
+               <tt>DEB_*_GNU_TYPE</tt>)</p>

          </list>
          </list>

-       </p>
-
-       <p>

          where <tt>*</tt> is either <tt>BUILD</tt> for specification of
          where <tt>*</tt> is either <tt>BUILD</tt> for specification of

-         the build machine or <tt>HOST</tt> for specification of the machine
-         we build for.
+         the build machine or <tt>HOST</tt> for specification of the
+         host machine.

        </p>
 
        <p>
          Backward compatibility can be provided in the rules file
          by setting the needed variables to suitable default
        </p>
 
        <p>
          Backward compatibility can be provided in the rules file
          by setting the needed variables to suitable default

-         values, please refer to the documentation of
-         dpkg-architecture for details.
+         values; please refer to the documentation of
+         <prgn>dpkg-architecture</prgn> for details.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -2159,8 +2163,9 @@
              Though there is nothing stopping an author who is also
              the Debian maintainer from using it for all their
              changes, it will have to be renamed if the Debian and
              Though there is nothing stopping an author who is also
              the Debian maintainer from using it for all their
              changes, it will have to be renamed if the Debian and

-             upstream maintainers become different
-             people.
+             upstream maintainers become different people.  In such a
+             case, however, it might be better to maintain the
+             package as a non-native package.

            </p>
          </footnote>.
        </p>
            </p>
          </footnote>.
        </p>


@@ -2174,13 +2179,13 @@
        <p>
          That format is a series of entries like this:
          <example>
        <p>
          That format is a series of entries like this:
          <example>

-           <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>

 
 

-           * <var>change details</var>
-             <var>more change details</var>
-           * <var>even more change details</var>
+  * <var>change details</var>
+    <var>more change details</var>
+  * <var>even more change details</var>

 
 

-           -- <var>maintainer name and email address</var>  <var>date</var>
+ -- <var>maintainer name and email address</var>  <var>date</var>

          </example>
        </p>
 
          </example>
        </p>
 


@@ -2205,6 +2210,16 @@
          <prgn>dpkg</prgn> changelog format (though there is
          currently only one useful <var>keyword</var>,
          <tt>urgency</tt>).
          <prgn>dpkg</prgn> changelog format (though there is
          currently only one useful <var>keyword</var>,
          <tt>urgency</tt>).

+         <footnote>
+           <p>
+             Usual urgency values are <tt>low</tt>, <tt>medium</tt>,
+             <tt>high</tt> and <tt>critical</tt>.  They have an
+             effect on how quickly a package will be considered for
+             inclusion into the <tt>testing</tt> distribution, and
+             give an indication of the importance of any fixes
+             included in this upload.
+           </p>
+         </footnote>

        </p>
 
        <p>
        </p>
 
        <p>


@@ -2217,13 +2232,31 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         The maintainer name and email address need <em>not</em>
-         necessarily be those of the usual package maintainer.
-         They should be the details of the person doing
-         <em>this</em> version.  The information here will be
-         copied to the <tt>.changes</tt> file, and then later used
-         to send an acknowledgement when the upload has been
-         installed.
+         If this upload resolves bugs recorded in the Bug Tracking
+         System (BTS), they may be automatically closed on the
+         inclusion of this package into the Debian archive by
+         including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
+         in the change details.
+         <footnote>
+           <p>
+             To be precise, the string should match the following
+             Perl regular expression:
+             <tt>/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i</tt>
+             Then all of the bug numbers listed will be closed by the
+             archive maintenance script (<prgn>katie</prgn>), or in
+             the case of an NMU, marked as fixed.
+           </p>
+         </footnote>
+       </p>
+
+       <p>
+         The maintainer name and email address used in the changelog
+         should be the details of the person uploading <em>this</em>
+         version.  They are <em>not</em> necessarily those of the
+         usual package maintainer.  The information here will be
+         copied to the <tt>Changed-By</tt> field in the
+         <tt>.changes</tt> file, and then later used to send an
+         acknowledgement when the upload has been installed.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -2235,7 +2268,7 @@
            </p>
          </footnote>; it should include the time zone specified
          numerically, with the time zone name or abbreviation
            </p>
          </footnote>; it should include the time zone specified
          numerically, with the time zone name or abbreviation

-         optionally present as a comment.
+         optionally present as a comment in parentheses.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -2266,21 +2299,22 @@
        <p>
          When <prgn>dpkg-gencontrol</prgn>,
          <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
        <p>
          When <prgn>dpkg-gencontrol</prgn>,
          <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>

-         generate control files they do variable substitutions on
-         their output just before writing it.  Variable
+         generate control files they perform variable substitutions
+         on their output just before writing it.  Variable

          substitutions have the form
          <tt>${<var>variable-name</var>}</tt>.  The optional file
          substitutions have the form
          <tt>${<var>variable-name</var>}</tt>.  The optional file

-         <tt>debian/substvars</tt> contains variable substitutions
-         to be used; variables can also be set directly from
+         <tt>debian/substvars</tt> contains variable substitutions to
+         be used; variables can also be set directly from

          <tt>debian/rules</tt> using the <tt>-V</tt> option to the
          <tt>debian/rules</tt> using the <tt>-V</tt> option to the

-         source packaging commands, and certain predefined
-         variables are available.
+         source packaging commands, and certain predefined variables
+         are also available.

        </p>
 
        <p>
        </p>
 
        <p>

-         The is usually generated and modified dynamically by
-         <tt>debian/rules</tt> targets; in this case it must be
-         removed by the <prgn>clean</prgn> target.
+         The <tt>debian/substvars</tt> file is usually generated and
+         modified dynamically by <tt>debian/rules</tt> targets; in
+         this case it must be removed by the <prgn>clean</prgn>
+         target.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -2319,11 +2353,12 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         <prgn>dpkg-gencontrol</prgn> adds an entry to this file
-         for the <tt>.deb</tt> file that will be created by
-         <prgn>dpkg-deb</prgn> from the control file that it
-         generates, so for most packages all that needs to be done
-         with this file is to delete it in <prgn>clean</prgn>.
+         When <prgn>dpkg-gencontrol</prgn> is run for a binary
+         package, it adds an entry to <tt>debian/files</tt> for the
+         <tt>.deb</tt> file that will be created when <prgn>dpkg-deb
+         --build</prgn> is run for that binary package.  So for most
+         packages all that needs to be done with this file is to
+         delete it in the <prgn>clean</prgn> target.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -2346,8 +2381,6 @@
              packages, but only when extracting
              them.
            </p>
              packages, but only when extracting
              them.
            </p>

-         </footnote>
-         <footnote>

            <p>
              Hard links may be permitted at some point in the
              future, but would require a fair amount of
            <p>
              Hard links may be permitted at some point in the
              future, but would require a fair amount of


@@ -2455,10 +2488,10 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         These scripts should be the files <tt>preinst</tt>,
+         These scripts are the files <tt>preinst</tt>,

          <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
          control area of the package.  They must be proper executable
          <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
          control area of the package.  They must be proper executable

-         files; if they are scripts (which is recommended) they must
+         files; if they are scripts (which is recommended), they must

          start with the usual <tt>#!</tt> convention.  They should be
          readable and executable by anyone, and not world-writable.
        </p>
          start with the usual <tt>#!</tt> convention.  They should be
          readable and executable by anyone, and not world-writable.
        </p>


@@ -2475,22 +2508,12 @@
          well.
        </p>
 
          well.
        </p>
 

-       <p>
-         It is necessary for the error recovery procedures that the
-         scripts be idempotent: i.e., invoking the same script several
-         times in the same situation should do no harm.  If the first
-         call failed, or aborted half way through for some reason,
-         the second call should merely do the things that were left
-         undone the first time, if any, and exit with a success
-         status.
-       </p>
-

        <p>
          When a package is upgraded a combination of the scripts from
        <p>
          When a package is upgraded a combination of the scripts from

-         the old and new packages is called in amongst the other
-         steps of the upgrade procedure.  If your scripts are going
-         to be at all complicated you need to be aware of this, and
-         may need to check the arguments to your scripts.
+         the old and new packages is called during the upgrade
+         procedure.  If your scripts are going to be at all
+         complicated you need to be aware of this, and may need to
+         check the arguments to your scripts.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -2501,39 +2524,47 @@
          <prgn>postrm</prgn> afterwards.
        </p>
 
          <prgn>postrm</prgn> afterwards.
        </p>
 

-       <p> Programs called from maintainer scripts should not
-         normally have a path prepended to them. Before installation
-         is started the package management system checks to see if
-         the programs <prgn>ldconfig</prgn>,
+       <p>
+         Programs called from maintainer scripts should not normally
+         have a path prepended to them. Before installation is
+         started, the package management system checks to see if the
+         programs <prgn>ldconfig</prgn>,

          <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
          and <prgn>update-rc.d</prgn> can be found via the
          <tt>PATH</tt> environment variable. Those programs, and any
          <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
          and <prgn>update-rc.d</prgn> can be found via the
          <tt>PATH</tt> environment variable. Those programs, and any

-         other program that one would expect to on the <tt>PATH</tt>,
-         should thus be invoked without an absolute
+         other program that one would expect to be on the
+         <tt>PATH</tt>, should thus be invoked without an absolute

          pathname. Maintainer scripts should also not reset the
          pathname. Maintainer scripts should also not reset the

-         <tt>PATH</tt>, though they might choose to modify it by pre-
-         or appending package-specific directories. These
+         <tt>PATH</tt>, though they might choose to modify it by
+         prepending or appending package-specific directories. These

          considerations really apply to all shell scripts.</p>
       </sect>
          considerations really apply to all shell scripts.</p>
       </sect>

+

       <sect>
        <heading>Maintainer scripts Idempotency</heading>
 
        <p>
       <sect>
        <heading>Maintainer scripts Idempotency</heading>
 
        <p>

-         It is very important to make maintainer scripts
-         idempotent.
-         <footnote>
+         It is necessary for the error recovery procedures that the
+         scripts be idempotent.  This means that if it is run
+         successfully, and then it is called again, it doesn't bomb
+         out or cause any harm, but just ensures that everything is
+         the way it ought to be.  If the first call failed, or
+         aborted half way through for some reason, the second call
+         should merely do the things that were left undone the first
+         time, if any, and exit with a success status if everything
+         is OK.
+         <footnote> 

            <p>
            <p>

-             That means that if it runs successfully or fails
-             and then you call it again it doesn't bomb out,
-             but just ensures that everything is the way it
-             ought to be.
+             This is so that if an error occurs, the user interrupts
+             <prgn>dpkg</prgn> or some other unforeseen circumstance
+             happens you don't leave the user with a badly-broken
+             package when <prgn>dpkg</prgn> attempts to repeat the
+             action.

            </p>
            </p>

-         </footnote> This is so that if an error occurs, the
-         user interrupts <prgn>dpkg</prgn> or some other
-         unforeseen circumstance happens you don't leave the
-         user with a badly-broken package.
+         </footnote>

        </p>
       </sect>
        </p>
       </sect>

+

       <sect>
        <heading>Controlling terminal for maintainer scripts</heading>
 
       <sect>
        <heading>Controlling terminal for maintainer scripts</heading>
 


@@ -2591,7 +2622,7 @@
            </item>
            <item>
              <p><var>old-postinst</var> <tt>abort-upgrade</tt>
            </item>
            <item>
              <p><var>old-postinst</var> <tt>abort-upgrade</tt>

-               <var>new version</var></p>
+               <var>new-version</var></p>

            </item>
            <item>
              <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
            </item>
            <item>
              <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>


@@ -2683,10 +2714,11 @@
          The procedure on installation/upgrade/overwrite/disappear
          (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
          stage of <tt>dpkg --install</tt>) is as follows.  In each
          The procedure on installation/upgrade/overwrite/disappear
          (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
          stage of <tt>dpkg --install</tt>) is as follows.  In each

-         case if an error occurs the actions are, in general, run
-         backwards - this means that the maintainer scripts are run
-         with different arguments in reverse order.  These are the
-         `error unwind' calls listed below.
+         case, if a major error occurs (unless listed below) the
+         actions are, in general, run backwards - this means that the
+         maintainer scripts are run with different arguments in
+         reverse order.  These are the `error unwind' calls listed
+         below.

 
          <enumlist>
            <item>
 
          <enumlist>
            <item>


@@ -2777,7 +2809,7 @@
                      <example>
                        <var>new-preinst</var> install
                      </example>
                      <example>
                        <var>new-preinst</var> install
                      </example>

-                     Error unwind versions, respectively:
+                     Error unwind actions, respectively:

                      <example>
                        <var>new-postrm</var> abort-upgrade <var>old-version</var>
                        <var>new-postrm</var> abort-install <var>old-version</var>
                      <example>
                        <var>new-postrm</var> abort-upgrade <var>old-version</var>
                        <var>new-postrm</var> abort-install <var>old-version</var>


@@ -2794,19 +2826,22 @@
                The new package's files are unpacked, overwriting any
                that may be on the system already, for example any
                from the old version of the same package or from
                The new package's files are unpacked, overwriting any
                that may be on the system already, for example any
                from the old version of the same package or from

-               another package (backups of the old files are left
-               around, and if anything goes wrong the package
+               another package.  Backups of the old files are kept
+               temporarily, and if anything goes wrong the package

                management system will attempt to put them back as
                management system will attempt to put them back as

-               part of the error unwind).
+               part of the error unwind.

              </p>
 
              <p>
                It is an error for a package to contains files which
                are on the system in another package, unless
                <tt>Replaces</tt> is used (see <ref id="replaces">).
              </p>
 
              <p>
                It is an error for a package to contains files which
                are on the system in another package, unless
                <tt>Replaces</tt> is used (see <ref id="replaces">).

-               Currently the <tt>--force-overwrite</tt> flag is
+               <!--
+               The following paragraph is not currently the case:
+               Currently the <tt>- - force-overwrite</tt> flag is

                enabled, downgrading it to a warning, but this may not
                always be the case.
                enabled, downgrading it to a warning, but this may not
                always be the case.

+               -->

              </p>
 
              <p>
              </p>
 
              <p>


@@ -2821,7 +2856,7 @@
 
              <p>
                Packages which overwrite each other's files produce
 
              <p>
                Packages which overwrite each other's files produce

-               behavior which though deterministic is hard for the
+               behavior which, though deterministic, is hard for the

                system administrator to understand.  It can easily
                lead to `missing' programs if, for example, a package
                is installed which overwrites a file from another
                system administrator to understand.  It can easily
                lead to `missing' programs if, for example, a package
                is installed which overwrites a file from another


@@ -2835,7 +2870,7 @@
              </p>
 
              <p>
              </p>
 
              <p>

-               A directory will never be replaced by a symbolic links
+               A directory will never be replaced by a symbolic link

                to a directory or vice versa; instead, the existing
                state (symlink or not) will be left alone and
                <prgn>dpkg</prgn> will follow the symlink if there is
                to a directory or vice versa; instead, the existing
                state (symlink or not) will be left alone and
                <prgn>dpkg</prgn> will follow the symlink if there is


@@ -2889,7 +2924,7 @@
              <p>Any packages all of whose files have been overwritten during the
                installation, and which aren't required for
                dependencies, are considered to have been removed.
              <p>Any packages all of whose files have been overwritten during the
                installation, and which aren't required for
                dependencies, are considered to have been removed.

-               For each such package,
+               For each such package

                <enumlist>
                  <item>
                    <p><prgn>dpkg</prgn> calls:
                <enumlist>
                  <item>
                    <p><prgn>dpkg</prgn> calls:


@@ -2936,12 +2971,17 @@
            <item>
              <p>
                The new package's status is now sane, and recorded as
            <item>
              <p>
                The new package's status is now sane, and recorded as

-               `unpacked'.  Here is another point of no return - if
-               the conflicting package's removal fails we do not
-               unwind the rest of the installation; the conflicting
-               package is left in a half-removed limbo.
+               `unpacked'.
+             </p>
+
+             <p>
+               Here is another point of no return - if the
+               conflicting package's removal fails we do not unwind
+               the rest of the installation; the conflicting package
+               is left in a half-removed limbo.

              </p>
            </item>
              </p>
            </item>

+

            <item>
              <p>
                If there was a conflicting package we go and do the
            <item>
              <p>
                If there was a conflicting package we go and do the


@@ -2961,7 +3001,7 @@
        <p>
          When we configure a package (this happens with <tt>dpkg
            --install</tt>, or with <tt>--configure</tt>), we first
        <p>
          When we configure a package (this happens with <tt>dpkg
            --install</tt>, or with <tt>--configure</tt>), we first

-         update the conffiles and then call:
+         update any <tt>conffile</tt>s and then call:

          <example>
            <var>postinst</var> configure <var>most-recently-configured-version</var>
          </example>
          <example>
            <var>postinst</var> configure <var>most-recently-configured-version</var>
          </example>


@@ -2995,7 +3035,7 @@
            </item>
            <item>
              <p>
            </item>
            <item>
              <p>

-               The package's files are removed (except conffiles).
+               The package's files are removed (except <tt>conffile</tt>s).

              </p>
            </item>
            <item>
              </p>
            </item>
            <item>


@@ -3004,15 +3044,17 @@
                </example></p>
            </item>
            <item>
                </example></p>
            </item>
            <item>

-             <p>All the maintainer scripts except the postrm are removed.
+             <p>
+               All the maintainer scripts except the <tt>postrm</tt>
+               are removed.

              </p>
 
              <p>
                If we aren't purging the package we stop here.  Note
              </p>
 
              <p>
                If we aren't purging the package we stop here.  Note

-               that packages which have no postrm and no conffiles
-               are automatically purged when removed, as there is no
-               difference except for the <prgn>dpkg</prgn>
-               status.</p>
+               that packages which have no <tt>postrm</tt> and no
+               <tt>conffile</tt>s are automatically purged when
+               removed, as there is no difference except for the
+               <prgn>dpkg</prgn> status.</p>

            </item>
            <item>
              <p>
            </item>
            <item>
              <p>


@@ -3030,13 +3072,14 @@
            </item>
          </enumlist>
          No attempt is made to unwind after errors during
            </item>
          </enumlist>
          No attempt is made to unwind after errors during

-         removal.</p>
+         removal.
+       </p>

       </sect>
     </chapt>
 
 
     <chapt id="relationships"><heading>Declaring relationships between
       </sect>
     </chapt>
 
 
     <chapt id="relationships"><heading>Declaring relationships between

-       packages      </heading>
+       packages</heading>

 
       <p>
        Packages can declare in their control file that they have
 
       <p>
        Packages can declare in their control file that they have


@@ -3048,9 +3091,10 @@
       </p>
 
       <p>
       </p>
 
       <p>

-       This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
-       <tt>Suggests</tt>, <tt>Enhances</tt>, <tt>Conflicts</tt>,
-       <tt>Provides</tt> and <tt>Replaces</tt> control file fields.
+       This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+       <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+       <tt>Conflicts</tt>, <tt>Provides</tt> and <tt>Replaces</tt>
+       control file fields.

       </p>
 
       <p>
       </p>
 
       <p>


@@ -3061,7 +3105,7 @@
 
       <p>
         This is done using the <tt>Build-Depends</tt>,
 
       <p>
         This is done using the <tt>Build-Depends</tt>,

-        <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
+        <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and

         <tt>Build-Conflicts-Indep</tt> control file fields.
       </p>
 
         <tt>Build-Conflicts-Indep</tt> control file fields.
       </p>
 


@@ -3080,18 +3124,17 @@
           control file fields of the package, which declare
           dependencies on other packages, the package names listed may
           also include lists of alternative package names, separated
           control file fields of the package, which declare
           dependencies on other packages, the package names listed may
           also include lists of alternative package names, separated

-          by vertical bar symbols <tt>|</tt> (pipe symbols).  In such
-          a case, the presence of any one of the alternative packages
-          is installed, that part of the dependency is considered to
-          be satisfied.
+          by vertical bar (pipe) symbols <tt>|</tt>.  In such a case,
+          if any one of the alternative packages is installed, that
+          part of the dependency is considered to be satisfied.

        </p>
 
        <p>
        </p>
 
        <p>

-         All the fields except <tt>Provides</tt> may restrict their
-         applicability to particular versions of each named package.
-         This is done in parentheses after each individual package
-         name; the parentheses should contain a relation from the
-         list below followed by a version number, in the format
+         All of the fields except for <tt>Provides</tt> may restrict
+         their applicability to particular versions of each named
+         package.  This is done in parentheses after each individual
+         package name; the parentheses should contain a relation from
+         the list below followed by a version number, in the format

          described in <ref id="versions">.
        </p>
 
          described in <ref id="versions">.
        </p>
 


@@ -3099,8 +3142,8 @@
          The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
          <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
          strictly earlier, earlier or equal, exactly equal, later or
          The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
          <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
          strictly earlier, earlier or equal, exactly equal, later or

-         equal and strictly later, respectively.  The forms
-         <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean
+         equal and strictly later, respectively.  The deprecated
+         forms <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean

          earlier/later or equal, rather than strictly earlier/later,
          so they should not appear in new packages (though
          <prgn>dpkg</prgn> still supports them).
          earlier/later or equal, rather than strictly earlier/later,
          so they should not appear in new packages (though
          <prgn>dpkg</prgn> still supports them).


@@ -3108,22 +3151,23 @@
 
        <p>
          Whitespace may appear at any point in the version
 
        <p>
          Whitespace may appear at any point in the version

-         specification, and must appear where it's necessary to
+         specification subject to the rules in <ref
+         id="controlsyntax">, and must appear where it's necessary to

          disambiguate; it is not otherwise significant.  For
          consistency and in case of future changes to
          <prgn>dpkg</prgn> it is recommended that a single space be
          used after a version relationship and before a version
          disambiguate; it is not otherwise significant.  For
          consistency and in case of future changes to
          <prgn>dpkg</prgn> it is recommended that a single space be
          used after a version relationship and before a version

-         number; it is usual also to put a single space after each
-         comma, on either side of each vertical bar, and before each
-         open parenthesis.
+         number; it is also conventional to put a single space after
+         each comma, on either side of each vertical bar, and before
+         each open parenthesis.

        </p>
 
        <p>
        </p>
 
        <p>

-         For example:
+         For example, a list of dependencies might appear as:

          <example>
          <example>

-           Package: metamail
-           Version: 2.7-3
-           Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+           Package: mutt
+           Version: 1.3.17-1
+           Depends: libc6 (>= 2.2.1), exim | mail-transport-agent

          </example>
        </p>
 
          </example>
        </p>
 


@@ -3132,7 +3176,7 @@
          (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
          <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
          may be restricted to a certain set of architectures.  This
          (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
          <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
          may be restricted to a certain set of architectures.  This

-         is done in brackets after each individual package name and
+         is indicated in brackets after each individual package name and

          the optional version specification.  The brackets enclose a
          list of Debian architecture names separated by whitespace.
          Exclamation marks may be prepended to each of the names.
          the optional version specification.  The brackets enclose a
          list of Debian architecture names separated by whitespace.
          Exclamation marks may be prepended to each of the names.


@@ -3169,17 +3213,22 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         All but <tt>Pre-Depends</tt> and <tt>Conflicts</tt>
-         (discussed below) take effect <em>only</em> when a package
-         is to be configured.  They do not prevent a package being on
-         the system in an unconfigured state while its dependencies
-         are unsatisfied, and it is possible to replace a package
-         whose dependencies are satisfied and which is properly
-         installed with a different version whose dependencies are
-         not and cannot be satisfied; when this is done the depending
-         package will be left unconfigured (since attempts to
-         configure it will give errors) and will not function
-         properly.
+         A <tt>Depends</tt> field takes effect <em>only</em> when a
+         package is to be configured.  It does not prevent a package
+         being on the system in an unconfigured state while its
+         dependencies are unsatisfied, and it is possible to replace
+         a package whose dependencies are satisfied and which is
+         properly installed with a different version whose
+         dependencies are not and cannot be satisfied; when this is
+         done the depending package will be left unconfigured (since
+         attempts to configure it will give errors) and will not
+         function properly.  If it is necessary, a
+         <tt>Pre-Depends</tt> field can be used, which has a partial
+         effect even when a package is being unpacked, as explained
+         in detail below.  (The other three dependency fields,
+         <tt>Recommends</tt>, <tt>Suggests</tt> and
+         <tt>Enhances</tt>, are only used by the various front-ends
+         to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)

        </p>
 
        <p>
        </p>
 
        <p>


@@ -3191,20 +3240,37 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         Thus <tt>Depends</tt> allows package maintainers to impose
-         an order in which packages should be configured.
+         The <tt>Depends</tt> field thus allows package maintainers
+         to impose an order in which packages should be configured.
+       </p>
+
+       <p>
+         The meaning of the five dependency fields is as follows:

          <taglist>
            <tag><tt>Depends</tt></tag>
            <item>
 
          <taglist>
            <tag><tt>Depends</tt></tag>
            <item>
 

-             <p>This declares an absolute dependency.
+             <p>
+               This declares an absolute dependency.  A package will
+               not be configured unless all of the packages listed in
+               its <tt>Depends</tt> field have been correctly
+               configured.

              </p>
 
              <p>
                The <tt>Depends</tt> field should be used if the
                depended-on package is required for the depending
                package to provide a significant amount of
              </p>
 
              <p>
                The <tt>Depends</tt> field should be used if the
                depended-on package is required for the depending
                package to provide a significant amount of

-               functionality.</p>
+               functionality.
+             </p>
+             <p>
+               The <tt>Depends</tt> field should also be used if the
+               <prgn>postinst</prgn>, <prgn>prerm</prgn> or
+               <prgn>postrm</prgn> scripts require the package to be
+               present in order to run.  Note, however, that the
+               <prgn>postrm</prgn> cannot rely on any non-essential
+               packages to be present during the <tt>purge</tt>
+               phase.

            </item>
 
            <tag><tt>Recommends</tt></tag>
            </item>
 
            <tag><tt>Recommends</tt></tag>


@@ -3249,35 +3315,43 @@
                also forces <prgn>dpkg</prgn> to complete installation
                of the packages named before even starting the
                installation of the package which declares the
                also forces <prgn>dpkg</prgn> to complete installation
                of the packages named before even starting the
                installation of the package which declares the

-               Pre-dependency.
+               pre-dependency, as follows:

              </p>
 
              <p>
              </p>
 
              <p>

-               <tt>Pre-Depends</tt> should be used sparingly,
-               preferably only by packages whose premature upgrade or
-               installation would hamper the ability of the system to
-               continue with any upgrade that might be in progress.
+               When a package declaring a pre-dependency is about to
+               be <em>unpacked</em> the pre-dependency can be
+               satisfied if the depended-on package is either fully
+               configured, <em>or even if</em> the depended-on
+               package(s) are only unpacked or half-configured,
+               provided that they have been configured correctly at
+               some point in the past (and not removed or partially
+               removed since).  In this case, both the
+               previously-configured and currently unpacked or
+               half-configured versions must satisfy any version
+               clause in the <tt>Pre-Depends</tt> field.

              </p>
 
              <p>
              </p>
 
              <p>

-               When the package declaring it is being configured, a
-               <tt>Pre-Dependency</tt> will be considered satisfied
-               only if the depending package has been correctly
-               configured, just as if an ordinary <tt>Depends</tt>
-               had been used.
+               When the package declaring a pre-dependency is about
+               to be <em>configured</em>, the pre-dependency will be
+               treated as a normal <tt>Depends</tt>, that is, it will
+               be considered satisfied only if the depended-on
+               package has been correctly configured.

              </p>
 
              <p>
              </p>
 
              <p>

-               However, when a package declaring a Pre-dependency is
-               being unpacked the predependency can be satisfied even
-               if the depended-on package(s) are only unpacked or
-               half-configured, provided that they have been
-               configured correctly at some point in the past (and
-               not removed or partially removed since).  In this case
-               both the previously-configured and currently unpacked
-               or half-configured versions must satisfy any version
-               clause in the <tt>Pre-Depends</tt> field.
+               <tt>Pre-Depends</tt> should be used sparingly,
+               preferably only by packages whose premature upgrade or
+               installation would hamper the ability of the system to
+               continue with any upgrade that might be in progress.

              </p>
              </p>

+
+             <p>
+               <tt>Pre-Depends</tt> are also required if the
+               <prgn>preinst</prgn> script depends on the named
+               package.  It is best to avoid this situation if
+               possible.

            </item>
          </taglist>
        </p>
            </item>
          </taglist>
        </p>


@@ -3295,30 +3369,30 @@
        </p>
 
 
        </p>
 
 

-      <sect id="conflicts"><heading>Alternative binary packages -
-         <tt>Conflicts</tt> and <tt>Replaces</tt>
-       </heading>
+      <sect id="conflicts"><heading>Conflicting binary packages -
+          <tt>Conflicts</tt></heading>

 
        <p>
           When one binary package declares a conflict with another
 
        <p>
           When one binary package declares a conflict with another

-         <prgn>dpkg</prgn> will refuse to allow them to be installed
-         on the system at the same time.
+         using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
+         refuse to allow them to be installed on the system at the
+         same time.

        </p>
 
        <p>
          If one package is to be installed, the other must be removed
          first - if the package being installed is marked as
        </p>
 
        <p>
          If one package is to be installed, the other must be removed
          first - if the package being installed is marked as

-         replacing (<ref id="replaces">) the one on the system, or
-         the one on the system is marked as deselected, or both
+         replacing (see <ref id="replaces">) the one on the system,
+         or the one on the system is marked as deselected, or both

          packages are marked <tt>Essential</tt>, then
          <prgn>dpkg</prgn> will automatically remove the package
          which is causing the conflict, otherwise it will halt the
          packages are marked <tt>Essential</tt>, then
          <prgn>dpkg</prgn> will automatically remove the package
          which is causing the conflict, otherwise it will halt the

-         installation of the new package with an error. This
-         mechanism specifically doesn't work when the installed
-         package is <tt>Essential</tt>, but the new package is not.
+         installation of the new package with an error.  This
+         mechanism is specifically designed to produce an error when
+         the installed package is <tt>Essential</tt>, but the new
+         package is not.

        </p>
 
        </p>
 

-

        <p>
          A package will not cause a conflict merely because its
          configuration files are still installed; it must be at least
        <p>
          A package will not cause a conflict merely because its
          configuration files are still installed; it must be at least


@@ -3332,7 +3406,7 @@
          prevent their installation, and allows a package to conflict
          with others providing a replacement for it.  You use this
          feature when you want the package in question to be the only
          prevent their installation, and allows a package to conflict
          with others providing a replacement for it.  You use this
          feature when you want the package in question to be the only

-         package providing something.
+         package providing some feature.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -3350,14 +3424,15 @@
         <p>
          As well as the names of actual (`concrete') packages, the
          package relationship fields <tt>Depends</tt>,
         <p>
          As well as the names of actual (`concrete') packages, the
          package relationship fields <tt>Depends</tt>,

+         <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+         <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,

          <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
          <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,

-         <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
-         <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
-         mention virtual packages.
+         <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
+         may mention `virtual packages'.

        </p>
 
        <p>
        </p>
 
        <p>

-         A virtual package is one which appears in the
+         A <em>virtual package</em> is one which appears in the

          <tt>Provides</tt> control file field of another package.
          The effect is as if the package(s) which provide a
          particular virtual package name had been listed by name
          <tt>Provides</tt> control file field of another package.
          The effect is as if the package(s) which provide a
          particular virtual package name had been listed by name


@@ -3371,16 +3446,18 @@
          packages which provide it.  This is so that, for example,
          supposing we have
          <example>
          packages which provide it.  This is so that, for example,
          supposing we have
          <example>

-           Package: vm
-           Depends: emacs
+           Package: foo
+           Depends: bar

          </example>
          </example>

-         and someone else releases an xemacs package they can say
+         and someone else releases an enhanced version of the
+         <tt>bar</tt> package (for example, a non-US variant), they
+         can say:

          <example>
          <example>

-           Package: xemacs
-           Provides: emacs
-         </example> and all will work in the interim (until a purely
-         virtual package name is decided on and the <tt>emacs</tt>
-         and <tt>vm</tt> packages are changed to use it).
+           Package: bar-plus
+           Provides: bar
+         </example>
+         and the <tt>bar-plus</tt> package will now also satisfy the
+         dependency for the <tt>foo</tt> package.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -3405,87 +3482,101 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         If you want to specify which of a set of real packages should be the
-         default to satisfy a particular dependency on a virtual package, you
-         should list the real package as an alternative before the virtual.
+         If you want to specify which of a set of real packages
+         should be the default to satisfy a particular dependency on
+         a virtual package, you should list the real package as an
+         alternative before the virtual one.

        </p>
       </sect>
 
 
        </p>
       </sect>
 
 

-      <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
-         files and replacing packages
-       </heading>
-
-       <p>
-         The <tt>Replaces</tt> control file field has two purposes,
-         which come into play in different situations.
-       </p>
+      <sect id="replaces"><heading>Overwriting files and replacing
+         packages - <tt>Replaces</tt></heading>

 
        <p>
 
        <p>

-         Virtual packages (<ref id="virtual">) are not considered
-         when looking at a <tt>Replaces</tt> field - the packages
-         declared as being replaced must be mentioned by their real
-         names.
+         The <tt>Replaces</tt> control file field has two distinct
+         purposes, which come into play in different situations.

        </p>
 
        </p>
 

-       <sect1><heading>Overwriting files in other packages
-         </heading>
+       <sect1><heading>Overwriting files in other packages</heading>

 
          <p>
            Firstly, as mentioned before, it is usually an error for a
            package to contain files which are on the system in
 
          <p>
            Firstly, as mentioned before, it is usually an error for a
            package to contain files which are on the system in

-           another package, though currently the
-           <tt>--force-overwrite</tt> flag is enabled by default,
-           downgrading the error to a warning,
+           another package.

          </p>
 
          <p>
          </p>
 
          <p>

-           If the overwriting package declares that it replaces the
-           one containing the file being overwritten then
-           <prgn>dpkg</prgn> will proceed, and replace the file from
-           the old package with that from the new.  The file will no
-           longer be listed as `owned' by the old package.
+           However, if the overwriting package declares that it
+           <tt>Replaces</tt> the one containing the file being
+           overwritten, then <prgn>dpkg</prgn> will replace the file
+           from the old package with that from the new.  The file
+           will no longer be listed as `owned' by the old package.

          </p>
 
          <p>
            If a package is completely replaced in this way, so that
            <prgn>dpkg</prgn> does not know of any files it still
          </p>
 
          <p>
            If a package is completely replaced in this way, so that
            <prgn>dpkg</prgn> does not know of any files it still

-           contains, it is considered to have disappeared.  It will
+           contains, it is considered to have `disappeared'.  It will

            be marked as not wanted on the system (selected for
            be marked as not wanted on the system (selected for

-           removal) and not installed.  Any conffiles details noted
-           in the package will be ignored, as they will have been
-           taken over by the replacing package(s).  The package's
-           <prgn>postrm</prgn> script will be run to allow the
-           package to do any final cleanup required.  See <ref
-                                                               id="mscriptsinstact">.
+           removal) and not installed.  Any <tt>conffile</tt>s
+           details noted for the package will be ignored, as they
+           will have been taken over by the overwriting package.  The
+           package's <prgn>postrm</prgn> script will be run with a
+           special argument to allow the package to do any final
+           cleanup required.  See <ref id="mscriptsinstact">.
+         </p>
+
+         <p>
+           If an installed package, <tt>foo</tt> say, declares that
+           it replaces another, <tt>bar</tt>, and an attempt is made
+           to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
+           files in the <tt>bar</tt> package which would overwrite
+           those already present in <tt>foo</tt>.  This is so that
+           you can install an older version of a package without
+           problems.

          </p>
 
          <p>
          </p>
 
          <p>

-           In the future <prgn>dpkg</prgn> will discard files which
-           would overwrite those from an already installed package
-           which declares that it replaces the package being
-           installed.  This is so that you can install an older
-           version of a package without problems.
+           For this usage of <tt>Replaces</tt>, virtual packages (see
+           <ref id="virtual">) are not considered when looking at a
+           <tt>Replaces</tt> field - the packages declared as being
+           replaced must be mentioned by their real names.

          </p>
 
          <p>
          </p>
 
          <p>

-           This usage of <tt>Replaces</tt> only takes effect when
-           both packages are at least partially on the system at
-           once, so that it can only happen if they do not conflict
-           or if the conflict has been overridden.</p>
+           Furthermore, this usage of <tt>Replaces</tt> only takes
+           effect when both packages are at least partially on the
+           system at once, so that it can only happen if they do not
+           conflict or if the conflict has been overridden.
+         </p>
+

        </sect1>
 
        <sect1><heading>Replacing whole packages, forcing their
        </sect1>
 
        <sect1><heading>Replacing whole packages, forcing their

-           removal
-         </heading>
+           removal</heading>

 
          <p>
            Secondly, <tt>Replaces</tt> allows the packaging system to
            resolve which package should be removed when there is a
            conflict - see <ref id="conflicts">.  This usage only
            takes effect when the two packages <em>do</em> conflict,
 
          <p>
            Secondly, <tt>Replaces</tt> allows the packaging system to
            resolve which package should be removed when there is a
            conflict - see <ref id="conflicts">.  This usage only
            takes effect when the two packages <em>do</em> conflict,

-           so that the two effects do not interfere with each other.
+           so that the two usages of this field do not interfere with
+           each other.

          </p>
          </p>

+
+         <p>
+           In this situation, the package declared as being replaced
+           can be a virtual package, so for example, all mail
+           transport agents (MTAs) would have the following fields in
+           their control files:
+           <example>
+Provides: mail-transport-agent
+Conflicts: mail-transport-agent
+Replaces: mail-transport-agent
+           </example>
+           ensuring that only one MTA can be installed at any one
+           time.

        </sect1>
       </sect>
 
        </sect1>
       </sect>
 


@@ -3496,21 +3587,22 @@
 
         <p>
           A source package may declare a dependency or a conflict on a
 
         <p>
           A source package may declare a dependency or a conflict on a

-          binary package.  This is done with the control file fields
-          <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
-          <tt>Build-Conflicts</tt>, and
-          <tt>Build-Conflicts-Indep</tt>.  Their semantics are that
-          the dependencies and conflicts they define must be satisfied
-          (as defined earlier for binary packages), when one of the
-          targets in <tt>debian/rules</tt> that the particular field
-          applies to is invoked.
+          binary package, indicating which packages are required to be
+          present on the system in order to build the binary packages
+          from the source package.  This is done with the control file
+          fields <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+          <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>.
+          The dependencies and conflicts they define must be satisfied
+          (as defined earlier for binary packages) in order to invoke
+          the targets in <tt>debian/rules</tt>, as follows:

 
          <taglist>
            <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
            <item>
              <p>
                 The <tt>Build-Depends</tt> and
 
          <taglist>
            <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
            <item>
              <p>
                 The <tt>Build-Depends</tt> and

-               <tt>Build-Conflicts</tt> fields apply to the targets
+               <tt>Build-Conflicts</tt> fields must be satisfied when
+               any of the following targets is invoked:

                <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
                and <tt>binary-indep</tt>.
              </p>
                <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
                and <tt>binary-indep</tt>.
              </p>


@@ -3519,8 +3611,9 @@
            <item>
              <p>
                 The <tt>Build-Depends-Indep</tt> and
            <item>
              <p>
                 The <tt>Build-Depends-Indep</tt> and

-               <tt>Build-Conflicts-Indep</tt> fields apply to the
-               targets <tt>binary</tt> and <tt>binary-indep</tt>.
+               <tt>Build-Conflicts-Indep</tt> fields must be
+               satisfied when any of the following targets is
+               invoked: <tt>binary</tt> and <tt>binary-indep</tt>.

              </p>
            </item>
          </taglist>
              </p>
            </item>
          </taglist>


@@ -3535,32 +3628,7 @@
       </heading>
 
       <p>
       </heading>
 
       <p>

-       <prgn>dpkg</prgn> can do a certain amount of automatic
-       handling of package configuration files.
-      </p>
-
-      <p>
-       Whether this mechanism is appropriate depends on a number of
-       factors, but basically there are two approaches to any
-       particular configuration file.
-      </p>
-
-      <p>
-       The easy method is to ship a best-effort configuration in the
-       package, and use <prgn>dpkg</prgn>'s conffile mechanism to
-       handle updates.  If the user is unlikely to want to edit the
-       file, but you need them to be able to without losing their
-       changes, and a new package with a changed version of the file
-       is only released infrequently, this is a good approach.
-      </p>
-
-      <p>
-       The hard method is to build the configuration file from
-       scratch in the <prgn>postinst</prgn> script, and to take the
-       responsibility for fixing any mistakes made in earlier
-       versions of the package automatically.  This will be
-       appropriate if the file is likely to need to be different on
-       each system.
+       This chapter has been superseded by <ref id="config files">.

       </p>
 
 
       </p>
 
 


@@ -4008,8 +4076,27 @@
            permissions 2775 (group-writable and set-group-id) and be
            owned by <tt>root.staff</tt>.</p>
        </sect1>
            permissions 2775 (group-writable and set-group-id) and be
            owned by <tt>root.staff</tt>.</p>
        </sect1>

+       <sect1>
+         <heading>The system-wide mail directory</heading>
+         <p>
+           The system-wide mail directory is <tt>/var/mail</tt>. This
+           directory is part of the base system and should not owned
+           by any particular mail agents.  The use of the old
+           location <tt>/var/spool/mail</tt> is deprecated, even
+           though the spool may still be physically located there.
+           To maintain partial upgrade compatibility for systems
+           which have <tt>/var/spool/mail</tt> as their physical mail
+           spool, packages using <tt>/var/mail</tt> must depend on
+           either <package>libc6</package> (&gt;= 2.1.3-13), or on
+           <package>base-files</package> (&gt;= 2.2.0), or on later
+           versions of either one of these packages.
+         </p>
+       </sect1>
+

       </sect>
 
       </sect>
 

+
+

       <sect>
        <heading>Users and groups</heading>
 
       <sect>
        <heading>Users and groups</heading>
 


@@ -5227,10 +5314,11 @@
 
        <p>
          You should follow the directions in the <em>Debian Packaging
 
        <p>
          You should follow the directions in the <em>Debian Packaging

-           Manual</em> for putting the shared library in its package,
-         and you must include a <tt>shlibs</tt> control area
-         file with details of the dependencies for packages which
-         use the library.</p>
+           Manual</em> (or other documentation of the Debian
+         packaging tools) for putting the shared library in its
+         package, and you must include a <tt>shlibs</tt> control area
+         file with details of the dependencies for packages which use
+         the library.</p>

 
        <p>
          Shared libraries should not be installed
 
        <p>
          Shared libraries should not be installed


@@ -5803,7 +5891,7 @@
       </sect>
     </chapt>
 
       </sect>
     </chapt>
 

-    <chapt>
+    <chapt id="customized-programs">

       <heading>Customized programs</heading>
 
       <sect id="arch-spec">
       <heading>Customized programs</heading>
 
       <sect id="arch-spec">


@@ -5993,7 +6081,7 @@
          </enumlist></p></sect>
 
 
          </enumlist></p></sect>
 
 

-      <sect>
+      <sect id="mail-transport-agents">

        <heading>Mail transport, delivery and user agents</heading>
 
        <p>
        <heading>Mail transport, delivery and user agents</heading>
 
        <p>


@@ -6005,10 +6093,14 @@
          serious brain damage!</p>
 
        <p>
          serious brain damage!</p>
 
        <p>

-         The mail spool is <tt>/var/spool/mail</tt> and the interface
+         The mail spool is <tt>/var/mail</tt> and the interface

          to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
          to send a mail message is <tt>/usr/sbin/sendmail</tt> (as

-         per the FHS).  The mail spool is part of the base system
-         and not part of the MTA package.</p>
+         per the FHS).  On older systems, the mail spool may be
+         physically located in /var/spool/mail, but all access to the
+         mail spool should be via the /var/mail symlink. The mail
+         spool is part of the base system and not part of the MTA
+         package.
+       </p> 

 
        <p>
          All Debian MUAs, MTAs, MDAs and other mailbox accessing
 
        <p>
          All Debian MUAs, MTAs, MDAs and other mailbox accessing


@@ -6411,6 +6503,17 @@
        </p>
       </sect>
 
        </p>
       </sect>
 

+      <sect>
+       <heading>Perl programs and modules</heading>
+       <p>
+         Perl programs and modules should follow the current Perl             
+          policy as defined in the file found on                               
+         <ftpsite>ftp.debian.org</ftpsite> in                                 
+         <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>  
+         or your local mirror.  In addition, it is included in the            
+         <tt>debian-policy</tt> package.                                
+       </p>
+      </sect>

 
       <sect>
        <heading>Emacs lisp programs</heading>
 
       <sect>
        <heading>Emacs lisp programs</heading>