Re: Bug#571776: document symbols

[Russ Allbery <rra@debian.org>]

Jonathan Nieder <jrnieder@gmail.com> writes:
> Jonathan Nieder wrote:

>> I'll reply with an interdiff relative to the last version of the
>> patch.

> Here it is.

And here is the interdiff between your patch and what I currently have, to
make it easier for you and anyone who was familiar with your version of
the patch to review what I further changed.

I'm going to reply to this thread in a moment with the whole current
patch, for hopefully the last time, and then we can try to get seconds and
(at least) merge this monster.

commit 97cb027db4afab774ea4f4ff9e7bef7a6dcbbda0
Author: Russ Allbery <rra@debian.org>
Date:   Sun Aug 12 14:14:23 2012 -0700

    Further wording changes on top of Jonathan Neider'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 0965b76..fa1c39a 100644
--- 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
-	  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
	  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.
@@ -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
-	  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
-	  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
@@ -6012,12 +6016,15 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
 	</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>
-	    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>
 
@@ -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
-	  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">
@@ -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
-	    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
@@ -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
-	    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

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>