* Finished updates to chapter 7

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

diff --git a/policy.sgml b/policy.sgml
index df49d6430b4fe9cabadc72bc43237cecb6e4444b..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


@@ -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


@@ -1467,7 +1467,7 @@
        format.
       </p>
 
        format.
       </p>
 

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

 
        <p>
          A control file consists of one or more paragraphs of fields.
 
        <p>
          A control file consists of one or more paragraphs of fields.


@@ -2108,7 +2108,7 @@
 
        <p>
          The architectures we build on and build for are determined
 
        <p>
          The architectures we build on and build for are determined

-         by <prgn>make</prgn> variables using
+         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
          <prgn>dpkg-architecture</prgn>.  You can determine the
          Debian architecture and the GNU style architecture
          specification string for the build machine (the machine type


@@ -2241,9 +2241,7 @@
            <p>
              To be precise, the string should match the following
              Perl regular expression:
            <p>
              To be precise, the string should match the following
              Perl regular expression:

-             <example>
-/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
-             </example>
+             <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.
              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.


@@ -3081,7 +3079,7 @@
 
 
     <chapt id="relationships"><heading>Declaring relationships between
 
 
     <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


@@ -3093,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>


@@ -3106,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>
 


@@ -3125,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>
 


@@ -3144,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).


@@ -3153,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>
 


@@ -3177,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.


@@ -3214,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>


@@ -3236,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>


@@ -3294,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>


@@ -3340,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


@@ -3377,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>


@@ -3395,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


@@ -3416,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>


@@ -3450,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>
+      <sect id="replaces"><heading>Overwriting files and replacing
+         packages - <tt>Replaces</tt></heading>

 
        <p>
 
        <p>

-         The <tt>Replaces</tt> control file field has two purposes,
-         which come into play in different situations.
+         The <tt>Replaces</tt> control file field has two distinct
+         purposes, which come into play in different situations.

        </p>
 
        </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.
-       </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>
 


@@ -3541,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>


@@ -3564,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>


@@ -3580,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>
 
 


@@ -4053,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>
 


@@ -5272,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


@@ -5848,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">


@@ -6038,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>


@@ -6050,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


@@ -6456,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>