Further wording changes on top of Jonathan Nieder's work

Add a footnote explaining what a "reasonable" program is.  Clarify
the shlibs versioning text.  Other minor textual changes for
clarity.

diff --git a/policy.sgml b/policy.sgml
index 0965b76bf89cb2fcbaaa62e6671016458f042e62..fa1c39aca19f0e8e051179f648d35f0ebe1304d1 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -5978,11 +5978,11 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
          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
          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 provides information on the
+         a <file>shlibs</file> file.  These provide information on the

          package dependencies required to ensure the presence of
          interfaces provided by this library.  Any package with binaries
          package dependencies required to ensure the presence of
          interfaces provided by this library.  Any package with binaries

-         or libraries linking to a shared library must use these files
-         to determine the required dependencies when it is built.  Other
+         or libraries linking to a shared library must use these files to
+         determine the required dependencies when it is built.  Other

          packages which use a shared library (for example using
          <tt>dlopen()</tt>) should compute appropriate dependencies
          using these files at build time as well.
          packages which use a shared library (for example using
          <tt>dlopen()</tt>) should compute appropriate dependencies
          using these files at build time as well.


@@ -5990,21 +5990,25 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
 
        <p>
          The two mechanisms differ in the degree of detail that they
 
        <p>
          The two mechanisms differ in the degree of detail that they

-         provide.  A <file>symbols</file> file documents for each symbol
-         exported by a library the minimal version of the package any
-         binary using this symbol will need, which is typically the
-         version of the package in which the symbol was introduced.
-         This permits detailed analysis of the symbols used by a
+         provide.  A <file>symbols</file> file documents, for each symbol
+         exported by a library, the minimal version of the package any
+         binary using this symbol will need.  This is typically the
+         version of the package in which the symbol was introduced.  This
+         information permits detailed analysis of the symbols used by a

          particular package and construction of an accurate dependency,
          but it requires the package maintainer to track more information
          particular package and construction of an accurate dependency,
          but it requires the package maintainer to track more information

-         about the shared library.  A <file>shlibs</file> file, in
-         contrast, only documents the last time the library ABI changed
-         in any way.  It only provides information about the library as a
-         whole, not individual symbols.  When a package is built using a
-         shared library with only a <file>shlibs</file> file, the generated
-         dependency will require a version of the shared library equal to
-         or newer than the version of the last ABI change.  This
-         generates unnecessarily restrictive dependencies compared
+         about the shared library.
+       </p>
+
+       <p>
+         A <file>shlibs</file> file, in contrast, only documents the last
+         time the library ABI changed in any way.  It only provides
+         information about the library as a whole, not individual
+         symbols.  When a package is built using a shared library with
+         only a <file>shlibs</file> file, the generated dependency will
+         require a version of the shared library equal to or newer than
+         the version of the last ABI change.  This generates
+         unnecessarily restrictive dependencies compared

          to <file>symbols</file> files if none of the symbols used by the
          package have changed.  This, in turn, may make upgrades
          needlessly complex and unnecessarily restrict use of the package
          to <file>symbols</file> files if none of the symbols used by the
          package have changed.  This, in turn, may make upgrades
          needlessly complex and unnecessarily restrict use of the package


@@ -6012,12 +6016,15 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
        </p>
 
        <p>
        </p>
 
        <p>

-         <file>shlibs<file> files also have a flawed representation of
+         <file>shlibs<file> files also only support a limited range of

          library SONAMEs, making it difficult to use <file>shlibs</file>
          files in some unusual corner cases.<footnote>
          library SONAMEs, making it difficult to use <file>shlibs</file>
          files in some unusual corner cases.<footnote>

-           libfooN.shlibs says 'libfoo N' instead of the actual SONAME,
-           so if the SONAME doesn't match one of the two expected
-           formats (libfoo-N.so or libfoo.so.N) it can't be represented.
+           A <file>shlibs</file> file represents an SONAME as a library
+           name and version number, such as <tt>libfoo VERSION</tt>,
+           instead of recording the actual SONAME.  If the SONAME doesn't
+           match one of the two expected formats
+           (<tt>libfoo-VERSION.so</tt> or <tt>libfoo.so.VERSION</tt>), it
+           cannot be represented.

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


@@ -6029,8 +6036,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
          maintain.  However, maintaining exhaustive symbols information
          for a C++ library can be quite onerous, so <file>shlibs</file>
          files may be more appropriate for most C++ libraries.  Libraries
          maintain.  However, maintaining exhaustive symbols information
          for a C++ library can be quite onerous, so <file>shlibs</file>
          files may be more appropriate for most C++ libraries.  Libraries

-         with a corresponding udeb must also provide <file>shlibs</file>,
-         since the udeb infrastructure does not use <file>symbols</file>.
+         with a corresponding udeb must also provide
+         a <file>shlibs</file> file, since the udeb infrastructure does
+         not use <file>symbols</file> files.

        </p>
 
        <sect1 id="dpkg-shlibdeps">
        </p>
 
        <sect1 id="dpkg-shlibdeps">


@@ -6089,10 +6097,10 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
            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
            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, for example 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>
+           compiled libraries or binaries.  For example, you could use
+           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
              the addition of the variable to the control file for you if
              Again, <prgn>dh_shlibdeps</prgn>
              and <prgn>dh_gencontrol</prgn> will handle everything except
              the addition of the variable to the control file for you if


@@ -6166,7 +6174,18 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
            backward-compatible if any reasonable program or library that
            was linked with the previous version of the shared library
            will still work correctly with the new version of the shared
            backward-compatible if any reasonable program or library that
            was linked with the previous version of the shared library
            will still work correctly with the new version of the shared

-           library.  Adding new symbols to the shared library is a
+           library.<footnote>
+             An example of an "unreasonable" program is one that uses
+             library interfaces that are documented as internal and
+             unsupported.  If the only programs or libraries affected by
+             a change are "unreasonable" ones, other techniques, such as
+             declaring <tt>Breaks</tt> relationships with affected
+             packages or treating their usage of the library as bugs in
+             those packages, may be appropriate instead of changing the
+             SONAME.  However, the default approach is to change the
+             SONAME for any change to the ABI that could break a program.
+           </footnote>
+           Adding new symbols to the shared library is a

            backward-compatible change.  Removing symbols from the shared
            library is not.  Changing the behavior of a symbol may or may
            not be backward-compatible depending on the change; for
            backward-compatible change.  Removing symbols from the shared
            library is not.  Changing the behavior of a symbol may or may
            not be backward-compatible depending on the change; for