Do not attempt to divert a conffile.

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

diff --git a/policy.sgml b/policy.sgml
index d81891c7c5f2b52af5c26cebabde59dc4b2d9014..56782145e358644e012b1199bf1bc9a98c64993b 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -158,6 +158,14 @@
          distributed in some other way or is intended for local use
          only.
        </p>
          distributed in some other way or is intended for local use
          only.
        </p>

+
+       <p>
+         udebs (stripped-down binary packages used by the Debian Installer) do
+         not comply with all of the requirements discussed here.  See the
+         <url name="Debian Installer internals manual"
+         id="http://d-i.alioth.debian.org/doc/internals/ch03.html"> for more
+         information about them.
+       </p>

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


@@ -1322,9 +1330,9 @@ zope.
          The package installation scripts should avoid producing
          output which is unnecessary for the user to see and
          should rely on <prgn>dpkg</prgn> to stave off boredom on
          The package installation scripts should avoid producing
          output which is unnecessary for the user to see and
          should rely on <prgn>dpkg</prgn> to stave off boredom on

-         the part of a user installing many packages.  This means,
-         amongst other things, using the <tt>--quiet</tt> option on
-         <prgn>install-info</prgn>.
+         the part of a user installing many packages. This means,
+         amongst other things, not passing the <tt>--verbose</tt>
+         option to <prgn>update-alternatives</prgn>.

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


@@ -2153,7 +2161,7 @@ zope.
        <p>
          The architectures we build on and build for are determined
          by <prgn>make</prgn> variables using the
        <p>
          The architectures we build on and build for are determined
          by <prgn>make</prgn> variables using the

-         utility <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
+         utility <prgn>dpkg-architecture</prgn>.

          You can determine the Debian architecture and the GNU style
          architecture specification string for the build architecture as
          well as for the host architecture.  The build architecture is
          You can determine the Debian architecture and the GNU style
          architecture specification string for the build architecture as
          well as for the host architecture.  The build architecture is


@@ -3961,8 +3969,7 @@ Checksums-Sha256:
          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 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>,
+         programs <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</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 be in the
          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 be in the


@@ -6735,7 +6742,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
                    The <file>shlibs</file> control files for all the
                    packages currently installed on the system.  These are
                    normally found
                    The <file>shlibs</file> control files for all the
                    packages currently installed on the system.  These are
                    normally found

-                   in <file>/var/lib/dpkg/info/*.symbols</file>, but
+                   in <file>/var/lib/dpkg/info/*.shlibs</file>, but

                    packages should not rely on this and instead should
                    use <tt>dpkg-query --control-path <var>package</var>
                    shlibs</tt> if for some reason these files need to be
                    packages should not rely on this and instead should
                    use <tt>dpkg-query --control-path <var>package</var>
                    shlibs</tt> if for some reason these files need to be


@@ -10489,18 +10496,23 @@ name ["<var>syshostname</var>"]:
 
        <p>
          The <prgn>install-info</prgn> program maintains a directory of
 
        <p>
          The <prgn>install-info</prgn> program maintains a directory of

-         installed info documents in <file>/usr/share/info/dir</file> for
-         the use of info readers.<footnote>
-           It was previously necessary for packages installing info
-           documents to run <prgn>install-info</prgn> from maintainer
-           scripts.  This is no longer necessary.  The installation
-           system now uses dpkg triggers.
-         </footnote>
-         This file must not be included in packages.  Packages containing
-         info documents should depend on <tt>dpkg (>= 1.15.4) |
-         install-info</tt> to ensure that the directory file is properly
-         rebuilt during partial upgrades from Debian 5.0 (lenny) and
-         earlier.
+         installed info documents in <file>/usr/share/info/dir</file> for the
+         use of info readers.  This file must not be included in packages
+         other than <package>install-info</package>.
+       </p>
+
+       <p>
+         <prgn>install-info</prgn> is automatically invoked when
+         appropriate using dpkg triggers.  Packages other than
+         <package>install-info</package> <em>should not</em> invoke
+         <prgn>install-info</prgn> directly and <em>should not</em>
+         depend on, recommend, or suggest <package>install-info</package>
+         for this purpose.
+       </p>
+
+       <p>
+         Info readers requiring the <file>/usr/share/info/dir</file> file
+         should depend on <package>install-info</package>.

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


@@ -10876,10 +10888,7 @@ END-INFO-DIR-ENTRY
 
       <p>
        The utility programs which are provided with <prgn>dpkg</prgn>
 
       <p>
        The utility programs which are provided with <prgn>dpkg</prgn>

-       for managing various system configuration and similar issues,
-       such as <prgn>update-rc.d</prgn> and
-       <prgn>install-info</prgn>, are not described in detail here -
-       please see their man pages.
+       not described in detail here, are documented in their man pages.

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


@@ -10899,25 +10908,9 @@ END-INFO-DIR-ENTRY
       <heading>Binary packages (from old Packaging Manual)</heading>
 
       <p>
       <heading>Binary packages (from old Packaging Manual)</heading>
 
       <p>

-       The binary package has two main sections.  The first part
-       consists of various control information files and scripts used
-       by <prgn>dpkg</prgn> when installing and removing.  See <ref
-       id="pkg-controlarea">.
+       See <manref name="deb" section="5"> and <ref id="pkg-controlarea">.

       </p>
 
       </p>
 

-      <p>
-       The second part is an archive containing the files and
-       directories to be installed.
-      </p>
-
-      <p>
-       In the future binary packages may also contain other
-       components, such as checksums and digital signatures. The
-       format for the archive is described in full in the
-       <file>deb(5)</file> man page.
-      </p>
-
-

       <sect id="pkg-bincreating"><heading>Creating package files -
       <prgn>dpkg-deb</prgn>
        </heading>
       <sect id="pkg-bincreating"><heading>Creating package files -
       <prgn>dpkg-deb</prgn>
        </heading>


@@ -11219,55 +11212,7 @@ END-INFO-DIR-ENTRY
          </heading>
 
          <p>
          </heading>
 
          <p>

-           <prgn>dpkg-buildpackage</prgn> is a script which invokes
-           <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
-           targets <tt>clean</tt>, <tt>build</tt> and
-           <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
-           <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
-           source and binary package upload.
-         </p>
-
-         <p>
-           It is usually invoked by hand from the top level of the
-           built or unbuilt source directory.  It may be invoked with
-           no arguments; useful arguments include:
-           <taglist compact="compact">
-             <tag><tt>-uc</tt>, <tt>-us</tt></tag>
-             <item>
-               <p>
-                 Do not sign the <tt>.changes</tt> file or the
-                 source package <tt>.dsc</tt> file, respectively.</p>
-             </item>
-             <tag><tt>-p<var>sign-command</var></tt></tag>
-             <item>
-               <p>
-                 Invoke <var>sign-command</var> instead of finding
-                 <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
-                 <var>sign-command</var> must behave just like
-                 <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
-             </item>
-             <tag><tt>-r<var>root-command</var></tt></tag>
-             <item>
-               <p>
-                 When root privilege is required, invoke the command
-                 <var>root-command</var>.  <var>root-command</var>
-                 should invoke its first argument as a command, from
-                 the <prgn>PATH</prgn> if necessary, and pass its
-                 second and subsequent arguments to the command it
-                 calls.  If no <var>root-command</var> is supplied
-                 then <var>dpkg-buildpackage</var> will use
-                 the <prgn>fakeroot</prgn> command, which is sufficient
-                 to build most packages without actually requiring root
-                 privileges.</p>
-             </item>
-             <tag><tt>-b</tt>, <tt>-B</tt></tag>
-             <item>
-               <p>
-                 Two types of binary-only build and upload - see
-                 <manref name="dpkg-source" section="1">.
-               </p>
-             </item>
-           </taglist>
+           See <manref name="dpkg-buildpackage" section="1">.

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


@@ -11391,23 +11336,10 @@ END-INFO-DIR-ENTRY
          </heading>
 
          <p>
          </heading>
 
          <p>

-           This program is usually called by package-independent
-           automatic building scripts such as
-           <prgn>dpkg-buildpackage</prgn>, but it may also be called
-           by hand.
-         </p>
-
-         <p>
-           It is usually called in the top level of a built source
-           tree, and when invoked with no arguments will print out a
-           straightforward <file>.changes</file> file based on the
-           information in the source package's changelog and control
-           file and the binary and source packages which should have
-           been built.
+           See <manref name="dpkg-genchanges" section="1">.

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

-

        <sect1 id="pkg-dpkg-parsechangelog">
           <heading>
             <prgn>dpkg-parsechangelog</prgn> - produces parsed
        <sect1 id="pkg-dpkg-parsechangelog">
           <heading>
             <prgn>dpkg-parsechangelog</prgn> - produces parsed


@@ -11415,12 +11347,7 @@ END-INFO-DIR-ENTRY
          </heading>
 
          <p>
          </heading>
 
          <p>

-           This program is used internally by
-           <prgn>dpkg-source</prgn> et al.  It may also occasionally
-           be useful in <file>debian/rules</file> and elsewhere.  It
-           parses a changelog, <file>debian/changelog</file> by default,
-           and prints a control-file format representation of the
-           information in it to standard output.
+           See <manref name="dpkg-parsechangelog" section="1">.

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


@@ -11431,10 +11358,7 @@ END-INFO-DIR-ENTRY
           </heading>
 
           <p>
           </heading>
 
           <p>

-            This program can be used manually, but is also invoked by
-            <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
-            environment or make variables which specify the build and host
-            architecture for the package building process.
+           See <manref name="dpkg-architecture" section="1">.

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


@@ -12123,6 +12047,11 @@ END-INFO-DIR-ENTRY
        there is a time, after it has been diverted but before
        <prgn>dpkg</prgn> has installed the new version, when the file
        does not exist.</p>
        there is a time, after it has been diverted but before
        <prgn>dpkg</prgn> has installed the new version, when the file
        does not exist.</p>

+
+      <p>
+       Do not attempt to divert a conffile, as <prgn>dpkg</prgn> does not
+       handle it well.
+      </p>

     </appendix>
 
   </book>
     </appendix>
 
   </book>