[debhelper-devel] [debhelper] 01/01: dh_installman: Improve description and add example config file

[Niels Thykier]

This is an automated email from the git hooks/post-receive script.

nthykier pushed a commit to branch master
in repository debhelper.

commit 6c2243f87d7ed8c01eb0182b3573d9ba3929c8f1
Author: Niels Thykier <niels at thykier.net>
Date:   Fri May 5 19:15:24 2017 +0000

    dh_installman: Improve description and add example config file
    
    Signed-off-by: Niels Thykier <niels at thykier.net>
---
 debian/changelog |  2 ++
 dh_installman    | 43 ++++++++++++++++++++++++++++++++++---------
 2 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index cb8a528..989fafa 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -49,6 +49,8 @@ debhelper (10.3) UNRELEASED; urgency=medium
     has been removed in stretch.
   * python_support.pm: Remove the content with a deprecation warning as
     the module can no longer do anything.
+  * dh_installman.1: Improve the manpage to clarify the scope of
+    dh_installman and provide an examples.  (Closes: LP: #184156)
 
   [ Steven Chamberlain ]
   * When cross-compiling for GNU/kFreeBSD host systems, set
diff --git a/dh_installman b/dh_installman
index 8093777..7ae605e 100755
--- a/dh_installman
+++ b/dh_installman
@@ -17,15 +17,26 @@ B<dh_installman> [S<I<debhelper options>>] [S<I<manpage> ...>]
 
 =head1 DESCRIPTION
 
-B<dh_installman> is a debhelper program that handles installing
-man pages into the correct locations in package build directories. You tell
-it what man pages go in your packages, and it figures out where to install
-them based on the section field in their B<.TH> or B<.Dt> line. If you have
-a properly formatted B<.TH> or B<.Dt> line, your man page will be installed
-into the right directory, with the right name (this includes proper handling
-of pages with a subsection, like B<3perl>, which are placed in F<man3>, and
-given an extension of F<.3perl>). If your B<.TH> or B<.Dt> line is incorrect
-or missing, the program may guess wrong based on the file extension.
+B<dh_installman> is a debhelper program that handles installing man
+pages into the correct locations in package build directories for when
+upstream's build system does not properly install them as a part of
+its install step (or it does not have an install step).
+
+If upstream's installs the manpages in the proper directories,
+L<dh_install(1)> may be easier to use for deciding which package
+should ship the manpages.  In this case, B<dh_installman> can still be
+useful for converting the manpage encoding to UTF-8 and for converting
+F<.so> links (as described below).  However, that part happens
+automatically without any explicit configuration.
+
+You tell it what man pages go in your packages, and it figures out
+where to install them based on the section field in their B<.TH> or
+B<.Dt> line. If you have a properly formatted B<.TH> or B<.Dt> line,
+your man page will be installed into the right directory, with the
+right name (this includes proper handling of pages with a subsection,
+like B<3perl>, which are placed in F<man3>, and given an extension of
+F<.3perl>). If your B<.TH> or B<.Dt> line is incorrect or missing, the
+program may guess wrong based on the file extension.
 
 It also supports translated man pages, by looking for extensions
 like F<.ll.8> and F<.ll_LL.8>, or by use of the B<--language> switch.
@@ -80,6 +91,20 @@ packages if B<-A> is specified).
 
 =back
 
+=head1 EXAMPLES
+
+An example F<debian/manpages> file could look like this:
+
+  doc/man/foo.1
+  # Translations
+  doc/man/foo.da.1
+  doc/man/foo.de.1
+  doc/man/foo.fr.1
+  # NB: The following line is considered a polish translation
+  # of "foo.1" (and not a manpage written in perl called "foo.pl")
+  doc/man/foo.pl.1
+  # ...
+
 =head1 NOTES
 
 An older version of this program, L<dh_installmanpages(1)>, is still used

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debhelper/debhelper.git