Move Diane's commit to experimental.

1 files changed, 98 insertions, 0 deletions

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).