Policy: install-info is run by a dpkg trigger.

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

diff --git a/policy.sgml b/policy.sgml
index 58ef0eafdd882684884f04ab51f42468d5f1893b..1390cf41c5e0d69d6de6135e806776c1c181c73d 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>


@@ -10867,12 +10879,6 @@ END-INFO-DIR-ENTRY
        <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
        they interact with packages.</p>
 
        <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
        they interact with packages.</p>
 

-      <p>
-       It also documents the interaction between
-       <prgn>dselect</prgn>'s core and the access method scripts it
-       uses to actually install the selected packages, and describes
-       how to create a new access method.</p>
-

       <p>
        This manual does not go into detail about the options and
        usage of the package building and installation tools.  It
       <p>
        This manual does not go into detail about the options and
        usage of the package building and installation tools.  It


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


@@ -10905,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">.
-      </p>
-
-      <p>
-       The second part is an archive containing the files and
-       directories to be installed.
+       See <manref name="deb" section="5"> and <ref id="pkg-controlarea">.

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


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


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


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


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