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 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 .TH line and their filename
  23 extension. It also supports translated man pages, by looking for extensions
  24 like .ll.8 and .ll_LL.8
  25
  26 If dh_installman seems to install a man page into the wrong section or with
  27 the wrong extension, this is because the man page has thw wrong section
  28 listed in its .TH line. Edit the man page and correct the section, and
  29 dh_installman will follow suit.  See to L<man(7)> for details about the .TH
  30 section.
  31
  32 Any man page filenames specified as parameters will be installed into the
  33 first package dh_installman is told to act on. By default, this is the
  34 first binary package in debian/control, but if you use -p, -i, or -a flags,
  35 it will be the first package specified by those flags.
  36
  37 Files named debian/package.manpages can list other man pages to be
  38 installed.
  39
  40 After the man page installation step, dh_installman will check to see if
  41 any of the man pages in the temporary directories of any of the packages it
  42 is acting on contain ".so" links. If so, it changes them to symlinks.
  43
  44 =head1 OPTIONS
  45
  46 =over 4
  47
  48 =item B<-A>, B<--all>
  49
  50 Install all files specified by command line parameters in ALL packages
  51 acted on.
  52
  53 =item I<manpage ...>
  54
  55 Install these man pages into the first package acted on. (Or in all
  56 packages if -A is specified).
  57
  58 =back
  59
  60 =head1 NOTES
  61
  62 An older version of this program, L<dh_installmanpages(1)>, is still used
  63 by some packages, and so is still included in debhelper.
  64 It is, however, deprecated, due to its counterintuitive and inconsistent
  65 interface. Use this program instead.
  66
  67 =cut
  68
  69 init();
  70
  71 my @sofiles;
  72 my @sodests;
  73
  74 foreach my $package (@{$dh{DOPACKAGES}}) {
  75         my $tmp=tmpdir($package);
  76         my $file=pkgfile($package,"manpages");
  77         my @manpages;
  78
  79         if ($file) {
  80                 @manpages=filearray($file, ".");
  81         }
  82
  83         if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
  84                 push @manpages, @ARGV;
  85         }
  86
  87         foreach my $page (@manpages) {
  88                 my $basename=basename($page);
  89
  90                 # Support compressed pages.
  91                 my $gz='';
  92                 if ($basename=~m/(.*)(\.gz)/) {
  93                         $basename=$1;
  94                         $gz=$2;
  95                 }
  96
  97                 my $section;
  98                 # See if there is a .TH entry in the man page. If so,
  99                 # we'll pull the section field from that.
 100                 if ($gz) {
 101                         open (IN, "zcat $page|") or die "$page: $!";
 102                 }
 103                 else {
 104                         open (IN, $page) or die "$page: $!";
 105                 }
 106                 while (<IN>) {
 107                         if (/^\.TH\s+\S+\s+(\d+\S*)\s/) {
 108                                 $section=$1;
 109                                 last;
 110                         }
 111                 }
 112                 # Failing that, we can try to get it from the filename.
 113                 if (! $section) {
 114                         ($section)=$basename=~m/.*\.([1-9]\S*)/;
 115                 }
 116
 117                 # Now get the numeric component of the section.
 118                 my ($realsection)=$section=~m/^(\d)/ if defined $section;
 119
 120                 # If there is no numeric section, bail.
 121                 if (! $realsection) {
 122                         error("Could not determine section for $page");
 123                 }
 124
 125                 # Get the man page's name -- everything up to the last dot.
 126                 my ($instname)=$basename=~m/^(.*)\./;
 127
 128                 my $destdir="$tmp/usr/share/man/man$realsection/";
 129                 # Translated man pages are typically specified by adding the
 130                 # language code to the filename, so detect that and
 131                 # redirect to appropriate directory, stripping the code.
 132                 my ($langcode)=$basename=~m/.*\.([a-z][a-z](?:_[A-Z][A-Z])?)\.(?:[1-9]|man)/;
 133                 if (defined $langcode && $langcode ne '') {
 134                         $destdir="$tmp/usr/share/man/$langcode/man$section/";
 135                         # Strip the language code from the instname.
 136                         $instname=~s/\.$langcode$//;
 137                 }
 138                 $destdir=~tr:/:/:s; # just for looks
 139
 140                 if (! -e "$destdir/$instname.$section" &&
 141                     ! -l "$destdir/$instname.$section") {
 142                         if (! -d $destdir) {
 143                                 doit "install","-d",$destdir;
 144                         }
 145                         doit "install","-p","-m644",$page,
 146                                 "$destdir$instname.$section$gz";
 147                 }
 148
 149         }
 150
 151         # Now the .so conversion.
 152         @sofiles=@sodests=();
 153         foreach my $dir (qw{usr/share/man usr/X11R6/man}) {
 154                 if (-e "$tmp/$dir") {
 155                         find(\&find_so_man, "$tmp/$dir");
 156                 }
 157         }
 158         foreach my $sofile (@sofiles) {
 159                 my $sodest=shift(@sodests);
 160                 doit "rm","-f",$sofile;
 161                 doit "ln","-sf",$sodest,$sofile;
 162         }
 163 }
 164
 165 # Check if a file is a .so man page, for use by File::Find.
 166 sub find_so_man {
 167         # The -s test is becuase a .so file tends to be small. We don't want
 168         # to open every man page. 1024 is arbitrary.
 169         if (! -f $_ || -s $_ > 1024) {
 170                 return;
 171         }
 172
 173         # Test first line of file for the .so thing.
 174         open (SOTEST,$_) || die "$_: $!";
 175         my $l=<SOTEST>;
 176         close SOTEST;
 177         if ($l=~m/\.so\s+(.*)/) {
 178                 my $solink=$1;
 179                 # This test is here to prevent links like ... man8/../man8/foo.8
 180                 if (basename($File::Find::dir) eq
 181                     dirname($solink)) {
 182                         $solink=basename($solink);
 183                 }
 184                 else {
 185                         $solink="../$solink";
 186                 }
 187
 188                 push @sofiles,"$File::Find::dir/$_";
 189                 push @sodests,$solink;
 190         }
 191 }
 192
 193 =head1 SEE ALSO
 194
 195 L<debhelper(1)>
 196
 197 This program is a part of debhelper.
 198
 199 =head1 AUTHOR
 200
 201 Joey Hess <joeyh@debian.org>
 202
 203 =cut