Updated dpkg-gensymbols's man page with lots of information

Explain the new include mechanism and in which cases it can be useful.
Also explain the need to keep the symbols file up-to-date. Include
recommendations to verify that upstream changes the library in sane ways.
This probably needs to be expanded, but probably in an external non-dpkg
related document that we could point to.

diff --git a/man/dpkg-gensymbols.1 b/man/dpkg-gensymbols.1
index 7a76f1b4e6186ff3c814fc57527f6123739dd05b..8bd39979599ba9580fa164cdddf73039a0e6c011 100644 (file)
--- a/man/dpkg-gensymbols.1
+++ b/man/dpkg-gensymbols.1
@@ -39,6 +39,65 @@ one, \fBdpkg\-gensymbols\fR will print a diff between the two versions.
 Furthermore if the difference are too significant, it will even fail (you
 can customize how much difference you can tolerate, see the \fB\-c\fR
 option).
+.SH MAINTAINING SYMBOLS FILES
+The symbols files are really useful only if they reflect the evolution of
+the package through several releases. Thus the maintainer has to update
+them every time that a new symbol is added so that its associated minimal
+version matches reality. To do this properly he can use the diffs contained
+in the build logs. In most cases, the diff can be directly applied to his
+debian/\fIpackage\fR.symbols file.
+.P
+Before applying any patch to the symbols file, the maintainer should
+double-check that it's sane. Public symbols are not supposed to disappear,
+so the patch should ideally only add new lines.
+.SS Using includes
+.P 
+When the set of exported symbols differ between architectures, it's no
+more possible to use a common symbols file. Using one file per
+architecture works, but it can also lead to duplication of information.
+In those cases, you can factorize the common part in some external file
+and include that file in your \fIpackage\fR.symbols.\fIarch\fR file by
+using an include directive like this:
+.PP
+#include "\fIpackages\fR.symbols.common"
+.P
+The symbols files are read line by line, and include directives
+are processed as soon as they are encountered. This means that
+the content of the included file can override any content that appeared
+before the include directive and that any content after the
+directive can override anything contained in the included file.
+.P
+An included file must be a valid symbols file on its own. Thus you have
+to repeat the header line containing the SONAME of the library and the
+dependency template. Remember that those lines might override the header
+defined previously in the main symbols file. Thus the recommended way to
+handle architecture specific information is to put include directives
+directly at the beginning of the symbols file:
+.PP
+#include "libsomething1.symbols.common"
+.br
+libsomething.so.1 libsomething1 #MINVER#
+ arch_specific_symbol@Base 1.0
+.SS Good library management
+.P
+A well-maintained library has the following features:
+.IP \(bu 4
+its API is stable (public symbols are never dropped, only new public
+symbols are added) and changes in incompatible ways only when the SONAME
+changes;
+.IP \(bu 4
+ideally, it uses symbol versioning to achieve ABI stability despite
+internal changes and API extension;
+.IP \(bu 4
+it doesn't export private symbols.
+.P
+While maintaining the symbols file, it's easy to notice appearance and
+disappearance of symbols. But it's more difficult to catch incompatible
+API and ABI change. Thus the maintainer should read thoroughly the
+upstream changelog looking for cases where the rules of good library
+management have been broken. If potential problems are discovered,
+the upstream author should be notified as an upstream fix is always better
+than a Debian specific work-around.
 .SH OPTIONS
 .TP
 .BI \-P package-build-dir
@@ -89,6 +148,12 @@ Show the usage message and exit.
 Show the version and exit.
 .
 .SH "SEE ALSO"
+.BR http://people.redhat.com/drepper/symbol-versioning
+.br
+.BR http://people.redhat.com/drepper/goodpractice.pdf
+.br
+.BR http://people.redhat.com/drepper/dsohowto.pdf
+.br
 .BR deb\-symbols (5),
 .BR dpkg\-shlibdeps (1).
 .