dh_installman

   1 #!/usr/bin/perl -w
   2
   3 =head1 NAME
   4
   5 dh_installman - install man pages into package build directories
   6
   7 =cut
   8
   9 use strict;
  10 use File::Find;
  11 use Debian::Debhelper::Dh_Lib;
  12
  13 =head1 SYNOPSIS
  14
  15 B<dh_installman> [S<I<debhelper options>>] [S<I<manpage> ...>]
  16
  17 =head1 DESCRIPTION
  18
  19 B<dh_installman> is a debhelper program that handles installing
  20 man pages into the correct locations in package build directories. You tell
  21 it what man pages go in your packages, and it figures out where to install
  22 them based on the section field in their B<.TH> or B<.Dt> line. If you have
  23 a properly formatted B<.TH> or B<.Dt> line, your man page will be installed
  24 into the right directory, with the right name (this includes proper handling
  25 of pages with a subsection, like B<3perl>, which are placed in F<man3>, and
  26 given an extension of F<.3perl>). If your B<.TH> or B<.Dt> line is incorrect
  27 or missing, the program may guess wrong based on the file extension.
  28
  29 It also supports translated man pages, by looking for extensions
  30 like F<.ll.8> and F<.ll_LL.8>, or by use of the B<--language> switch.
  31
  32 If B<dh_installman> seems to install a man page into the wrong section or with
  33 the wrong extension, this is because the man page has the wrong section
  34 listed in its B<.TH> or B<.Dt> line. Edit the man page and correct the
  35 section, and B<dh_installman> will follow suit. See L<man(7)> for details
  36 about the B<.TH> section, and L<mdoc(7)> for the B<.Dt> section. If
  37 B<dh_installman> seems to install a man page into a directory
  38 like F</usr/share/man/pl/man1/>, that is because your program has a
  39 name like F<foo.pl>, and B<dh_installman> assumes that means it is translated
  40 into Polish. Use B<--language=C> to avoid this.
  41
  42 After the man page installation step, B<dh_installman> will check to see if
  43 any of the man pages in the temporary directories of any of the packages it
  44 is acting on contain F<.so> links. If so, it changes them to symlinks.
  45
  46 Also, B<dh_installman> will use man to guess the character encoding of each
  47 manual page and convert it to UTF-8. If the guesswork fails for some
  48 reason, you can override it using an encoding declaration. See
  49 L<manconv(1)> for details.
  50
  51 =head1 FILES
  52
  53 =over 4
  54
  55 =item debian/I<package>.manpages
  56
  57 Lists man pages to be installed.
  58
  59 =back
  60
  61 =head1 OPTIONS
  62
  63 =over 4
  64
  65 =item B<-A>, B<--all>
  66
  67 Install all files specified by command line parameters in ALL packages
  68 acted on.
  69
  70 =item B<--language=>I<ll>
  71
  72 Use this to specify that the man pages being acted on are written in the
  73 specified language.
  74
  75 =item I<manpage> ...
  76
  77 Install these man pages into the first package acted on. (Or in all
  78 packages if B<-A> is specified).
  79
  80 =back
  81
  82 =head1 NOTES
  83
  84 An older version of this program, L<dh_installmanpages(1)>, is still used
  85 by some packages, and so is still included in debhelper.
  86 It is, however, deprecated, due to its counterintuitive and inconsistent
  87 interface. Use this program instead.
  88
  89 =cut
  90
  91 init(options => {
  92         "language=s" => \$dh{LANGUAGE},
  93 });
  94
  95 my @sofiles;
  96 my @sodests;
  97
  98 foreach my $package (@{$dh{DOPACKAGES}}) {
  99         next if is_udeb($package);
 100
 101         my $tmp=tmpdir($package);
 102         my $file=pkgfile($package,"manpages");
 103         my @manpages;
 104
 105         @manpages=filearray($file, ".") if $file;
 106
 107         if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
 108                 push @manpages, @ARGV;
 109         }
 110
 111         foreach my $page (@manpages) {
 112                 my $basename=basename($page);
 113
 114                 # Support compressed pages.
 115                 my $gz='';
 116                 if ($basename=~m/(.*)(\.gz)/) {
 117                         $basename=$1;
 118                         $gz=$2;
 119                 }
 120
 121                 my $section;
 122                 # See if there is a .TH or .Dt entry in the man page. If so,
 123                 # we'll pull the section field from that.
 124                 if ($gz) {
 125                         open (IN, "zcat $page|") or die "$page: $!";
 126                 }
 127                 else {
 128                         open (IN, $page) or die "$page: $!";
 129                 }
 130                 while (<IN>) {
 131                         if (/^\.TH\s+\S+\s+"?(\d+[^"\s]*)"?/ ||
 132                             /^\.Dt\s+\S+\s+(\d+[^\s]*)/) {
 133                                 $section=$1;
 134                                 last;
 135                         }
 136                 }
 137                 # Failing that, we can try to get it from the filename.
 138                 if (! $section) {
 139                         ($section)=$basename=~m/.*\.([1-9]\S*)/;
 140                 }
 141
 142                 # Now get the numeric component of the section.
 143                 my ($realsection)=$section=~m/^(\d)/ if defined $section;
 144                 if (! $realsection) {
 145                         error("Could not determine section for $page");
 146                 }
 147
 148                 # Get the man page's name -- everything up to the last dot.
 149                 my ($instname)=$basename=~m/^(.*)\./;
 150
 151                 my $destdir="$tmp/usr/share/man/man$realsection/";
 152                 my $langcode;
 153                 if (! defined $dh{LANGUAGE} || ! exists $dh{LANGUAGE}) {
 154                         # Translated man pages are typically specified by adding the
 155                         # language code to the filename, so detect that and
 156                         # redirect to appropriate directory, stripping the code.
 157                         ($langcode)=$basename=~m/.*\.([a-z][a-z](?:_[A-Z][A-Z])?)\.(?:[1-9]|man)/;
 158                 }
 159                 elsif ($dh{LANGUAGE} ne 'C') {
 160                         $langcode=$dh{LANGUAGE};
 161                 }
 162
 163                 if (defined $langcode && $langcode ne '') {
 164                         # Strip the language code from the instname.
 165                         $instname=~s/\.$langcode$//;
 166                 }
 167
 168                 if (defined $langcode && $langcode ne '') {
 169                         $destdir="$tmp/usr/share/man/$langcode/man$realsection/";
 170                 }
 171                 $destdir=~tr:/:/:s; # just for looks
 172                 my $instpage="$destdir$instname.$section";
 173
 174                 next if -l $instpage;
 175                 next if compat(5) && -e $instpage;
 176
 177                 if (! -d $destdir) {
 178                         doit "install","-d",$destdir;
 179                 }
 180                 if ($gz) {
 181                         complex_doit "zcat \Q$page\E > \Q$instpage\E";
 182                 }
 183                 else {
 184                         doit "install","-p","-m644",$page,$instpage;
 185                 }
 186         }
 187
 188         # Now the .so conversion.
 189         @sofiles=@sodests=();
 190         foreach my $dir (qw{usr/share/man}) {
 191                 if (-e "$tmp/$dir") {
 192                         find(\&find_so_man, "$tmp/$dir");
 193                 }
 194         }
 195         foreach my $sofile (@sofiles) {
 196                 my $sodest=shift(@sodests);
 197                 doit "rm","-f",$sofile;
 198                 doit "ln","-sf",$sodest,$sofile;
 199         }
 200
 201         # Now utf-8 conversion.
 202         if (defined `man --version`) {
 203                 foreach my $dir (qw{usr/share/man}) {
 204                         next unless -e "$tmp/$dir";
 205                         find(sub {
 206                                 return if ! -f $_ || -l $_;
 207                                 my ($tmp, $orig)=($_.".new", $_);
 208                                 complex_doit "man --recode UTF-8 ./\Q$orig\E > \Q$tmp\E";
 209                                 # recode uncompresses compressed pages
 210                                 doit "rm", "-f", $orig if s/\.(gz|Z)$//;
 211                                 doit "chmod", 644, $tmp;
 212                                 doit "mv", "-f", $tmp, $_;
 213                         }, "$tmp/$dir");
 214                 }
 215         }
 216 }
 217
 218 # Check if a file is a .so man page, for use by File::Find.
 219 sub find_so_man {
 220         # The -s test is becuase a .so file tends to be small. We don't want
 221         # to open every man page. 1024 is arbitrary.
 222         if (! -f $_ || -s $_ > 1024 || -s == 0) {
 223                 return;
 224         }
 225
 226         # Test first line of file for the .so thing.
 227         if (/\.gz$/) {
 228                 open (SOTEST, "zcat $_|") or die "$_: $!";
 229         }
 230         else {
 231                 open (SOTEST,$_) || die "$_: $!";
 232         }
 233         my $l=<SOTEST>;
 234         close SOTEST;
 235
 236         if (! defined $l) {
 237                 error("failed to read $_");
 238         }
 239
 240         if ($l=~m/\.so\s+(.*)\s*/) {
 241                 my $solink=$1;
 242                 # This test is here to prevent links like ... man8/../man8/foo.8
 243                 if (basename($File::Find::dir) eq
 244                     dirname($solink)) {
 245                         $solink=basename($solink);
 246                 }
 247                 # A so link with a path is relative to the base of the man
 248                 # page hierarchy, but without a path, is relative to the
 249                 # current section.
 250                 elsif ($solink =~ m!/!) {
 251                         $solink="../$solink";
 252                 }
 253
 254                 if (-e $solink || -e "$solink.gz") {
 255                         push @sofiles,"$File::Find::dir/$_";
 256                         push @sodests,$solink;
 257                 }
 258         }
 259 }
 260
 261 =head1 SEE ALSO
 262
 263 L<debhelper(7)>
 264
 265 This program is a part of debhelper.
 266
 267 =head1 AUTHOR
 268
 269 Joey Hess <joeyh@debian.org>
 270
 271 =cut