Further symbols wording fixes from Charles Plessy

Retain the dpkg-shlibdeps section in the appendix as a stub pointing
to the main page so that we don't renumber subsequent sections.  Add
more explanation for why dependencies change for each build of a
binary package.  Combine the dpkg-shlibdeps instructions somewhat and
mention that debian/substvars is only a default.

diff --git a/policy.sgml b/policy.sgml
index 55200064a4ffe8250dceafd2099e7b0555cc3bad..57caf5dc68290d9bb2c86e6352ec8a58ed7be8a2 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -5832,8 +5832,12 @@ Replaces: mail-transport-agent
          installed.  These dependencies must be added to the binary
          package when it is built, since they may change based on which
          version of a shared library the binary or library was linked
          installed.  These dependencies must be added to the binary
          package when it is built, since they may change based on which
          version of a shared library the binary or library was linked

-         with.  To allow these dependencies to be constructed, shared
-         libraries must provide either a <file>symbols</file> file or
+         with even if there are no changes to the source of the binary
+         (for example, symbol versions change, macros become functions or
+         vice versa, or the binary package may determine at compile-time
+         whether new library interfaces are available and can be called).
+         To allow these dependencies to be constructed, shared libraries
+         must provide either a <file>symbols</file> file or

          a <file>shlibs</file> file, which provide information on the
          package dependencies required to ensure the presence of this
          library.  Any package which uses a shared library must use these
          a <file>shlibs</file> file, which provide information on the
          package dependencies required to ensure the presence of this
          library.  Any package which uses a shared library must use these


@@ -5894,23 +5898,22 @@ Replaces: mail-transport-agent
              the libraries and the symbols in those libraries directly
              needed by the binaries or shared libraries in the package.
            </footnote>
              the libraries and the symbols in those libraries directly
              needed by the binaries or shared libraries in the package.
            </footnote>

-           <prgn>dpkg-shlibdeps</prgn> will use the <file>symbols</file>
-           or <file>shlibs</file> files installed by the shared libraries
-           to generate dependency information.
-         </p>
-
-         <p>
-           If your package contains any compiled binaries or shared
-           libraries, put a call to <prgn>dpkg-shlibdeps</prgn> into
+           To do this, put a call to <prgn>dpkg-shlibdeps</prgn> into

            your <file>debian/rules</file> file in the source package.
            List all of the compiled binaries, libraries, or loadable
            modules in your package.<footnote>
            your <file>debian/rules</file> file in the source package.
            List all of the compiled binaries, libraries, or loadable
            modules in your package.<footnote>

-             The easiest way to do this is to use a package helper
-             framework such as <package>debhelper</package>.  If you are
+             The easiest way to call <prgn>dpkg-shlibdeps</prgn>
+             correctly is to use a package helper framework such
+             as <package>debhelper</package>.  If you are

              using <package>debhelper</package>,
              the <prgn>dh_shlibdeps</prgn> program will do this work for
              you.  It will also correctly handle multi-binary packages.
            </footnote>
              using <package>debhelper</package>,
              the <prgn>dh_shlibdeps</prgn> program will do this work for
              you.  It will also correctly handle multi-binary packages.
            </footnote>

+           <prgn>dpkg-shlibdeps</prgn> will use the <file>symbols</file>
+           or <file>shlibs</file> files installed by the shared libraries
+           to generate dependency information.  The package must then
+           provide a substitution variable into which the discovered
+           dependency information can be placed.

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


@@ -5928,25 +5931,26 @@ Replaces: mail-transport-agent
          </p>
 
          <p>
          </p>
 
          <p>

-           This command puts the dependency information into
-           the <file>debian/substvars</file> file, which is then used
-           by <prgn>dpkg-gencontrol</prgn>.  You will need to place
-           a <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
-           field in the control file of every binary package built by
-           this source package that contains compiled binaries,
-           libraries, or loadable modules.  If you have multiple binary
-           packages, you will need to call <prgn>dpkg-shlibdeps</prgn> on
-           each one which contains compiled libraries or binaries, using
-           the <tt>-T</tt> option to the <tt>dpkg</tt> utilities to
-           specify a different <file>substvars</file> file for each
-           binary package.<footnote>
+           <prgn>dpkg-shlibdeps</prgn> puts the dependency information
+           into the <file>debian/substvars</file> file by default, which
+           is then used by <prgn>dpkg-gencontrol</prgn>.  You will need
+           to place a <tt>${shlibs:Depends}</tt> variable in
+           the <tt>Depends</tt> field in the control file of every binary
+           package built by this source package that contains compiled
+           binaries, libraries, or loadable modules.  If you have
+           multiple binary packages, you will need to
+           call <prgn>dpkg-shlibdeps</prgn> on each one which contains
+           compiled libraries or binaries, using the <tt>-T</tt> option
+           to the <tt>dpkg</tt> utilities to specify a
+           different <file>substvars</file> file for each binary
+           package.<footnote>

              Again, <prgn>dh_shlibdeps</prgn>
              and <prgn>dh_gencontrol</prgn> will handle everything except
              Again, <prgn>dh_shlibdeps</prgn>
              and <prgn>dh_gencontrol</prgn> will handle everything except

-             the control file modification for you if you're
-             using <package>debhelper</package>, including generating
-             separate <file>substvars</file> files for each binary
-             package and calling <prgn>dpkg-gencontrol</prgn> with the
-             appropriate flags.
+             the addition of the variable to the control file for you if
+             you're using <package>debhelper</package>, including
+             generating separate <file>substvars</file> files for each
+             binary package and calling <prgn>dpkg-gencontrol</prgn> with
+             the appropriate flags.

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


@@ -6132,8 +6136,8 @@ Replaces: mail-transport-agent
                    During the package build, if the package itself
                    contains shared libraries with <file>symbols</file>
                    files, they will be generated in these staging
                    During the package build, if the package itself
                    contains shared libraries with <file>symbols</file>
                    files, they will be generated in these staging

-                   directories
-                   by <prgn>dpkg-gensymbols</prgn>.  <file>symbols</file>
+                   directories by <prgn>dpkg-gensymbols</prgn>
+                   (see <ref id="providing-symbols">).  <file>symbols</file>

                    files found in the build tree take precedence
                    over <file>symbols</file> files from other binary
                    packages.
                    files found in the build tree take precedence
                    over <file>symbols</file> files from other binary
                    packages.


@@ -11070,6 +11074,17 @@ END-INFO-DIR-ENTRY
            <prgn>dpkg-genchanges</prgn>.</p>
        </sect1>
 
            <prgn>dpkg-genchanges</prgn>.</p>
        </sect1>
 

+       <sect1 id="pkg-dpkg-shlibdeps">
+         <heading>
+           <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+           dependencies
+         </heading>
+
+         <p>
+           See <manref name="dpkg-shlibdeps" section="1">.
+         </p>
+       </sect1>
+

        <sect1 id="pkg-dpkg-distaddfile">
          <heading>
            <prgn>dpkg-distaddfile</prgn> - adds a file to
        <sect1 id="pkg-dpkg-distaddfile">
          <heading>
            <prgn>dpkg-distaddfile</prgn> - adds a file to