=head1 SYNOPSIS
-B<dh_installman> [S<I<debhelper options>>] [S<I<manpage ...>>]
+B<dh_installman> [S<I<debhelper options>>] [S<I<manpage> ...>]
=head1 DESCRIPTION
-dh_installman is a debhelper program that handles installing
+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 .TH line. If you have a
-properly formatted .TH 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 "3perl", which are placed in man3, and given an
-extension of ".3perl"). If your .TH line is incorrect or missing, the program
-may guess wrong based on the file extension.
+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 .ll.8 and .ll_LL.8, or by use of the --language switch.
+like F<.ll.8> and F<.ll_LL.8>, or by use of the B<--language> switch.
-If dh_installman seems to install a man page into the wrong section or with
+If B<dh_installman> seems to install a man page into the wrong section or with
the wrong extension, this is because the man page has the wrong section
-listed in its .TH line. Edit the man page and correct the section, and
-dh_installman will follow suit. See to L<man(7)> for details about the .TH
-section. If dh_installman seems to install a man page into a directory
-like /usr/share/man/pl/man1/, that is because your program has a
-name like "foo.pl", and dh_installman assumes that means it is translated
-into Polish. Use --language=C to avoid this.
-
-Any man page filenames specified as parameters will be installed into the
-first package dh_installman is told to act on. By default, this is the
-first binary package in debian/control, but if you use -p, -i, or -a flags,
-it will be the first package specified by those flags.
-
-Files named debian/package.manpages can list other man pages to be
-installed.
-
-After the man page installation step, dh_installman will check to see if
+listed in its B<.TH> or B<.Dt> line. Edit the man page and correct the
+section, and B<dh_installman> will follow suit. See L<man(7)> for details
+about the B<.TH> section, and L<mdoc(7)> for the B<.Dt> section. If
+B<dh_installman> seems to install a man page into a directory
+like F</usr/share/man/pl/man1/>, that is because your program has a
+name like F<foo.pl>, and B<dh_installman> assumes that means it is translated
+into Polish. Use B<--language=C> to avoid this.
+
+After the man page installation step, B<dh_installman> will check to see if
any of the man pages in the temporary directories of any of the packages it
-is acting on contain ".so" links. If so, it changes them to symlinks.
+is acting on contain F<.so> links. If so, it changes them to symlinks.
+
+Also, B<dh_installman> will use man to guess the character encoding of each
+manual page and convert it to UTF-8. If the guesswork fails for some
+reason, you can override it using an encoding declaration. See
+L<manconv(1)> for details.
+
+=head1 FILES
+
+=over 4
+
+=item debian/I<package>.manpages
+
+Lists man pages to be installed.
+
+=back
=head1 OPTIONS
Install all files specified by command line parameters in ALL packages
acted on.
-=item B<--language>=ll
+=item B<--language=>I<ll>
Use this to specify that the man pages being acted on are written in the
specified language.
-=item I<manpage ...>
+=item I<manpage> ...
Install these man pages into the first package acted on. (Or in all
-packages if -A is specified).
+packages if B<-A> is specified).
=back
=cut
-init();
+init(options => {
+ "language=s" => \$dh{LANGUAGE},
+});
my @sofiles;
my @sodests;
my $file=pkgfile($package,"manpages");
my @manpages;
- if ($file) {
- @manpages=filearray($file, ".");
- }
+ @manpages=filearray($file, ".") if $file;
if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
push @manpages, @ARGV;
}
my $section;
- # See if there is a .TH entry in the man page. If so,
+ # See if there is a .TH or .Dt entry in the man page. If so,
# we'll pull the section field from that.
if ($gz) {
open (IN, "zcat $page|") or die "$page: $!";
open (IN, $page) or die "$page: $!";
}
while (<IN>) {
- if (/^\.TH\s+\S+\s+"?(\d+[^"\s]*)"?/) {
+ if (/^\.TH\s+\S+\s+"?(\d+[^"\s]*)"?/ ||
+ /^\.Dt\s+\S+\s+(\d+[^\s]*)/) {
$section=$1;
last;
}
# Now get the numeric component of the section.
my ($realsection)=$section=~m/^(\d)/ if defined $section;
-
- # If there is no numeric section, bail.
if (! $realsection) {
error("Could not determine section for $page");
}
$destdir="$tmp/usr/share/man/$langcode/man$realsection/";
}
$destdir=~tr:/:/:s; # just for looks
+ my $instpage="$destdir$instname.$section";
- next if -l "$destdir/$instname.$section";
- next if compat(5) && -e "$destdir/$instname.$section";
+ next if -l $instpage;
+ next if compat(5) && -e $instpage;
if (! -d $destdir) {
doit "install","-d",$destdir;
}
- doit "install","-p","-m644",$page,
- "$destdir$instname.$section$gz";
-
+ if ($gz) {
+ complex_doit "zcat \Q$page\E > \Q$instpage\E";
+ }
+ else {
+ doit "install","-p","-m644",$page,$instpage;
+ }
}
# Now the .so conversion.
@sofiles=@sodests=();
- foreach my $dir (qw{usr/share/man usr/X11R6/man}) {
+ foreach my $dir (qw{usr/share/man}) {
if (-e "$tmp/$dir") {
find(\&find_so_man, "$tmp/$dir");
}
doit "rm","-f",$sofile;
doit "ln","-sf",$sodest,$sofile;
}
+
+ # Now utf-8 conversion.
+ if (defined `man --version`) {
+ foreach my $dir (qw{usr/share/man}) {
+ next unless -e "$tmp/$dir";
+ find(sub {
+ return if ! -f $_ || -l $_;
+ my ($tmp, $orig)=($_.".new", $_);
+ complex_doit "man --recode UTF-8 ./\Q$orig\E > \Q$tmp\E";
+ # recode uncompresses compressed pages
+ doit "rm", "-f", $orig if s/\.(gz|Z)$//;
+ doit "chmod", 644, $tmp;
+ doit "mv", "-f", $tmp, $_;
+ }, "$tmp/$dir");
+ }
+ }
}
# Check if a file is a .so man page, for use by File::Find.
dirname($solink)) {
$solink=basename($solink);
}
- else {
+ # A so link with a path is relative to the base of the man
+ # page hierarchy, but without a path, is relative to the
+ # current section.
+ elsif ($solink =~ m!/!) {
$solink="../$solink";
}
- push @sofiles,"$File::Find::dir/$_";
- push @sodests,$solink;
+ if (-e $solink || -e "$solink.gz") {
+ push @sofiles,"$File::Find::dir/$_";
+ push @sodests,$solink;
+ }
}
}