Move Diane's commit to experimental.

3 files changed, 218 insertions, 1 deletions

diff --git a/debian/changelog b/debian/changelog
index 49567ae..299750b 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,8 @@
 pkg-kde-tools (0.15.17~) UNRELEASED; urgency=medium
 
-  * 
+  [ Diane Trout ]
+  * Add man pages for pkgkde-gensymbols and pkgkde-symbolshelper
+    (Closes: #782866).
 
  -- Maximiliano Curia <maxy@debian.org>  Thu, 26 Mar 2015 17:22:29 +0100
 
diff --git a/man1/pkgkde-gensymbols.1 b/man1/pkgkde-gensymbols.1
new file mode 100644
index 0000000..cd0ea55
--- /dev/null
+++ b/man1/pkgkde-gensymbols.1
@@ -0,0 +1,117 @@
+.TH PKGKDE\-GENSYMBOLS 1 "2015-04-18" "0.15" "Debian KDE dpkg-gensymbols wrapper"
+.SH NAME
+.B pkgkde\-gensymbols
+\- a helper tool for Debian pkg-kde symbols files.
+.SH SYNOPSIS
+.B pkgkde\-gensymbols
+[\fB
+.P
+.SH DESCRIPTION
+.B pkgkde-gensymbols
+is a wrapper around dpkg-gensymbols that provides additional support
+for tracking C++ symbols such as template instantiated symbols.
+See
+.BR dpkg\-gensymbols (1)
+for more information about maintaining symbols files.
+.P
+.SH OPTIONS
+.TP
+.BI \-P package-build-dir
+Scan \fIpackage-build-dir\fR instead of debian/tmp.
+.TP
+.BI \-p package
+Define the package name. Required if more than one binary package is listed in
+debian/control (or if there's no debian/control file).
+.TP
+.BI \-v version
+Define the package version. Defaults to the version extracted from
+debian/changelog. Required if called outside of a source package tree.
+.TP
+.BI \-e library-file
+Only analyze libraries explicitly listed instead of finding all public
+libraries. You can use shell patterns used for pathname expansions (see
+the \fBFile::Glob\fP(3perl) manual page for details) in \fIlibrary-file\fR
+to match multiple libraries with a single argument (otherwise you need
+multiple \fB\-e\fR).
+.TP
+.BI \-I filename
+Use \fIfilename\fR as reference file to generate the symbols file
+that is integrated in the package itself.
+.TP
+.BR \-O [\fIfilename\fP]
+Print the generated symbols file to standard output or to \fIfilename\fR
+if specified, rather than to
+.B debian/tmp/DEBIAN/symbols
+(or
+.IB package-build-dir /DEBIAN/symbols
+if
+.B \-P
+was used). If \fIfilename\fR is pre-existing, its contents are used as
+basis for the generated symbols file.
+You can use this feature to update a symbols file so that it matches a
+newer upstream version of your library.
+.TP
+.BI \-t
+Write the symbol file in template mode rather than the format compatible with
+\fBdeb\-symbols\fP(5). The main difference is that in the template mode symbol
+names and tags are written in their original form contrary to the
+post-processed symbol names with tags stripped in the compatibility mode.
+Moreover, some symbols might be omitted when writing a standard
+\fBdeb\-symbols\fP(5) file (according to the tag processing rules) while all
+symbols are always written to the symbol file template.
+.TP
+.BI \-c [0-4]
+Define the checks to do when comparing the generated symbols file with the
+template file used as starting point. By default the level is 1. Increasing
+levels do more checks and include all checks of lower levels. Level 0 never
+fails. Level 1 fails if some symbols have disappeared. Level 2 fails if some
+new symbols have been introduced. Level 3 fails if some libraries have
+disappeared. Level 4 fails if some libraries have been introduced.
+
+This value can be overridden by the environment variable
+.BR DPKG_GENSYMBOLS_CHECK_LEVEL .
+.TP
+.BI \-q
+Keep quiet and never generate a diff between generated symbols file and the
+template file used as starting point or show any warnings about new/lost
+libraries or new/lost symbols. This option only disables informational output
+but not the checks themselves (see \fB\-c\fP option).
+.TP
+.BI \-a arch
+Assume \fIarch\fR as host architecture when processing symbol files. Use this
+option to generate a symbol file or diff for any architecture provided its
+binaries are already available.
+.TP
+.BI \-d
+Enable debug mode. Numerous messages are displayed to explain what
+.B dpkg\-gensymbols
+does.
+.TP
+.BI \-V
+Enable verbose mode. The generated symbols file contains deprecated
+symbols as comments. Furthermore in template mode, pattern symbols
+are followed by comments listing real symbols that have matched the
+pattern.
+.TP
+.BR \-? ", " \-\-help
+Show the usage message and exit.
+.TP
+.BR \-\-version
+Show the version and exit.
+.SH NOTES
+This man page was based on the pkg-kde symbols file help page and
+the
+.BR dpkg-gensymbols (1)
+man page.
+.SH SEE ALSO
+.BR http://pkg-kde.alioth.debian.org/symbolfiles.html
+.br
+.BR https://people.redhat.com/drepper/symbol\-versioning
+.br
+.BR https://people.redhat.com/drepper/goodpractice.pdf
+.br
+.BR https://people.redhat.com/drepper/dsohowto.pdf
+.br
+.BR dpkg\-gensymbols (1),
+.BR deb\-symbols (5),
+.BR dpkg\-shlibdeps (1).
diff --git a/man1/pkgkde-symbolshelper.1 b/man1/pkgkde-symbolshelper.1
new file mode 100644
index 0000000..ee8356e
--- /dev/null
+++ b/man1/pkgkde-symbolshelper.1
@@ -0,0 +1,98 @@
+.TH PKGKDE\-SYMBOLSHELPER 1 "2015-04-18" "0.15" "Debian KDE symbols helper"
+.SH NAME
+.B pkgkde\-symbolshelper
+\- a tool to help simplify managing C++ symbols files for the KDE project.
+.SH SYNOPSIS
+.B pkgkde\-symbolshelper
+\fBcreate\fR | \fBpatch\fR | \fBbatchpatch\fR | \fBrewrite\fR
+.P
+.SH DESCRIPTION
+.B pkgkde-symbolshelper
+provides helps to automate the process of managing your
+.BR deb\-symbols (5)
+files.
+.P
+There are four commands, create, patch, batchpatch, and rewrite.
+.P
+.SH CREATING SYMBOLS FILE
+To create the symbols file for a library package libfoo1 whose version
+is 1.7
+.nf
+.RS
+\f(CW
+pkgkde-gensymbols -plibfoo1 -v1.7 -Osymbols.amd64 -edebian/libfoo1/usr/lib/libfoo.so.1
+pkgkde-symbolshelper create -o debian/libfoo1.symbols -v 1.7 symbols.amd64
+\fR
+.RE
+.ni
+.P
+The above commands should be invoked from the top level directory of
+your package's source after having built the package before cleaning,
+so that debian/libfoo1/usr/lib/libfoo.so.1 exists).
+.P
+"symbols.amd64" is the filename of the intermediate symbols file that
+will be generated by pkgkde-gensymbols. This filename must be in the
+format "name.architecture" or "name_architecture" where "architecture"
+is the cpu architecture on which you have built this package.
+.SH UPDATING A SYMBOLS FILE FOR A NEW LIBRARY VERSION
+After building a new version of the library (for instance 1.8 of our
+libfoo1 library from above), symbols may have been added or removed,
+and in both cases one must check and update the symbols file. During
+the build, a diff between the current symbols file and the one based
+on the current built library will printed in the output.
+.BR pkgkde-symbolshelper
+can read the build log to find this diff, to save the build log one may want
+to do:
+.nf
+.RS
+\f(CW
+dpkg-buildpackage | tee buildlog
+pkgkde-symbolshelper patch -p libfoo1 -v 1.8 < buildlog
+\fR
+.RE
+.fi
+.PP
+.SH UPDATING MULTIPLE SYMBOLS FILES AT ONCE
+For source packages that provide multiple binary library packages, it is
+useful to have a method to patch all the symbol files at once,
+.BR pkgkde-symbolshelper
+offers a way to do this using the
+.BR batchpatch command. For example:
+.nf
+.RS
+\f(CW
+pkgkde-symbolshelper batchpatch -v 1.8 < buildlog
+\fR
+.RE
+.fi
+.PP
+.BR batchpatch
+can also be of use when one wants to update symbol files for multiple
+architectures at once. There is an additional command
+.BR pkgkde\-getbuildlogs
+that will download the build logs for multiple architectures from
+Debian's build servers.
+.nf
+.RS
+\f(CW
+pkgkde-getbuildlogs
+pkgkde-symbolshelper batchpatch -v 1.8 foo_unstable_logs/foo_1.8-1*.build
+\fR
+.RE
+.fi
+.PP
+.SH NOTES
+This man page was based text written by others from the pkg-kde
+symbols file help page.
+.SH SEE ALSO
+.BR http://pkg-kde.alioth.debian.org/symbolfiles.html
+.br
+.BR https://people.redhat.com/drepper/symbol\-versioning
+.br
+.BR https://people.redhat.com/drepper/goodpractice.pdf
+.br
+.BR https://people.redhat.com/drepper/dsohowto.pdf
+.br
+.BR dpkg\-gensymbols (1),
+.BR deb\-symbols (5),
+.BR dpkg\-shlibdeps (1).