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