dh_installdocs

   1 #!/usr/bin/perl -w
   2
   3 =head1 NAME
   4
   5 dh_installdocs - install documentation into package build directories
   6
   7 =cut
   8
   9 use strict;
  10 use Debian::Debhelper::Dh_Lib;
  11
  12 =head1 SYNOPSIS
  13
  14 B<dh_installdocs> [S<I<debhelper options>>] [B<-A>] [B<-n>] [B<-X>I<item>] [S<I<file ...>>]
  15
  16 =head1 DESCRIPTION
  17
  18 dh_installdocs is a debhelper program that is responsible for installing
  19 documentation into usr/share/doc/package in package build directories.
  20
  21 dh_installdocs automatically installs debian/copyright if it exists. If
  22 dh_installdocs is acting on multiple packages, debian/copyright files will be
  23 installed into all packages. However, if you need to have seperate copyright
  24 files for different binary packages, you can use files named
  25 debian/package.copyright.
  26
  27 Any filenames specified as parameters will be installed into the first
  28 package dh_installdocs is told to act on. By default, this is the first
  29 binary package in debian/control, but if you use B<-p>, B<-i>, or B<-a> flags, it
  30 will be the first package specified by those flags.
  31
  32 Also, debian/README.Debian (or debian/README.debian) and debian/TODO, if
  33 they exist, will be installed into the first binary package listed in
  34 debian/control, if dh_installdocs is acting on that package. Note that
  35 debian/TODO will be installed named TODO.Debian, if the package is not a
  36 debian native package. Also note that README.debian is installed as
  37 README.Debian, for consistency. Note that debian/package.README.Debian and
  38 debian/package.TODO can be used to specify files for subpackages.
  39
  40 Files named debian/package.docs can list other files to be installed.
  41
  42 This program will automatically generate postinst and prerm commands to
  43 maintain a compatibility symlink, /usr/doc/package, to the documentation in
  44 /usr/share/doc/package. See L<dh_installdeb(1)> for an explanation of how
  45 this works.
  46
  47 Files named debian/package.doc-base, will be installed as doc-base control
  48 files, and will make this program automatically generate the postinst and
  49 prerm commands needed to interface with the doc-base package. Note that the
  50 doc-id will be determined from the "Document:" entry in the
  51 doc-base control file in question.
  52
  53 If your package needs to register more than one document, you need multiple
  54 files. To accomplish this, you can use files named debian/package.doc-base.*
  55
  56 =head1 OPTIONS
  57
  58 =over 4
  59
  60 =item B<-A>, B<--all>
  61
  62 Install all files specified by command line parameters in ALL packages
  63 acted on.
  64
  65 =item B<-n>, B<--noscripts>
  66
  67 Do not modify postinst/prerm scripts.
  68
  69 =item B<-Xitem>, B<--exclude=item>
  70
  71 Exclude files that contain "item" anywhere in their filename from
  72 being installed.
  73
  74 =item I<file ...>
  75
  76 Install these files as documentation into the first package acted on. (Or
  77 in all packages if B<-A> is specified).
  78
  79 =back
  80
  81 =head1 NOTES
  82
  83 Note that dh_installdocs will happily copy entire directory hierarchies if
  84 you ask it to (similar to cp -a). If it is asked to install a
  85 directory, it will install the complete contents of the directory.
  86
  87 Note that this command is not idempotent. "dh_clean B<-k>" should be called
  88 between invocations of this command. Otherwise, it may cause multiple
  89 instances of the same text to be added to maintainer scripts.
  90
  91 =cut
  92
  93 init();
  94
  95 foreach my $package (@{$dh{DOPACKAGES}}) {
  96         my $tmp=tmpdir($package);
  97         my $file=pkgfile($package,"docs");
  98
  99         # If this is a symlink, leave it alone.
 100         if ( ! -d "$tmp/usr/share/doc/$package" &&
 101              ! -l "$tmp/usr/share/doc/$package") {
 102                 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc/$package");
 103         }
 104
 105         my @docs;
 106
 107         if ($file) {
 108                 @docs=filearray($file, ".");
 109         }
 110
 111         if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
 112                 push @docs, @ARGV;
 113         }
 114
 115         if (@docs) {
 116                 my $exclude = '';
 117                 if ($dh{EXCLUDE_FIND}) {
 118                         $exclude = ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
 119                 }
 120                 foreach my $doc (@docs) {
 121                         next if excludefile($doc);
 122                         if (-d $doc && $exclude) {
 123                             my ($dir_basename) = basename($doc);
 124                             # Pity there's no cp --exclude ..
 125                             my $pwd=`pwd`;
 126                             chomp $pwd;
 127                             complex_doit("cd $doc/.. && find $dir_basename -type f$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;");
 128                         }
 129                         else {
 130                                 doit("cp","-a",$doc,"$tmp/usr/share/doc/$package");
 131                         }
 132                 }
 133                 doit("chown","-R","0.0","$tmp/usr/share/doc");
 134                 doit("chmod","-R","go=rX","$tmp/usr/share/doc");
 135                 doit("chmod","-R","u+rw","$tmp/usr/share/doc");
 136         }
 137
 138         # .Debian is correct, according to policy, but I'm easy.
 139         my $readme_debian=pkgfile($package,'README.Debian');
 140         if (! $readme_debian) {
 141                 $readme_debian=pkgfile($package,'README.debian');
 142         }
 143         if ($readme_debian && ! excludefile($readme_debian)) {
 144                 doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian",
 145                         "$tmp/usr/share/doc/$package/README.Debian");
 146         }
 147
 148         my $todo=pkgfile($package,'TODO');
 149         if ($todo && ! excludefile($todo)) {
 150                 if (isnative($package)) {
 151                         doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
 152                                 "$tmp/usr/share/doc/$package/TODO");
 153                 }
 154                 else {
 155                         doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
 156                                 "$tmp/usr/share/doc/$package/TODO.Debian");
 157                 }
 158         }
 159
 160         # If the "directory" is a dangling symlink, then don't install
 161         # the copyright file. This is useful for multibinary packages
 162         # that share a doc directory.
 163         if (-d "$tmp/usr/share/doc/$package") {
 164                 # Support debian/package.copyright, but if not present, fall
 165                 # back on debian/copyright for all packages, not just the
 166                 # main binary package.
 167                 my $copyright=pkgfile($package,'copyright');
 168                 if (! $copyright && -e "debian/copyright") {
 169                         $copyright="debian/copyright";
 170                 }
 171                 if ($copyright && ! excludefile($copyright)) {
 172                                 doit("install","-g",0,"-o",0,"-m","644","-p",$copyright,
 173                                         "$tmp/usr/share/doc/$package/copyright");
 174                 }
 175         }
 176
 177         # Add in the /usr/doc compatibility symlinks code.
 178         if (! $dh{NOSCRIPTS}) {
 179                 autoscript($package,"postinst","postinst-doc",
 180                         "s/#PACKAGE#/$package/g",
 181                 );
 182                 autoscript($package,"prerm","prerm-doc",
 183                         "s/#PACKAGE#/$package/g",
 184                 );
 185         }
 186
 187         # Handle doc-base files. There are two filename formats, the usual
 188         # plus an extended format (debian/package.*).
 189         my %doc_ids;
 190
 191         opendir(DEB,"debian/") || error("can't read debian directory: $!");
 192         # If this is the main package, we need to handle unprefixed filenames.
 193         # For all packages, we must support both the usual filename format plus
 194         # that format with a period an something appended.
 195         my $regexp="\Q$package\E\.";
 196         if ($package eq $dh{MAINPACKAGE}) {
 197                 $regexp="(|$regexp)";
 198         }
 199         foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) {
 200                 # Parse the file to get the doc id.
 201                 open (IN, "debian/$fn") || die "Cannot read debian/$fn.";
 202                 while (<IN>) {
 203                         if (/^Document:\s+(.*)(\s+)?/) {
 204                                 $doc_ids{$fn}=$1;
 205                                 last;
 206                         }
 207                 }
 208                 close IN;
 209         }
 210         closedir(DEB);
 211
 212         if (%doc_ids) {
 213                 if (! -d "$tmp/usr/share/doc-base/") {
 214                         doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc-base/");
 215                 }
 216         }
 217         foreach my $fn (keys %doc_ids) {
 218                 doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn",
 219                      "$tmp/usr/share/doc-base/$doc_ids{$fn}");
 220                 if (! $dh{NOSCRIPTS}) {
 221                         autoscript($package,"postinst","postinst-doc-base",
 222                                 "s/#DOC-ID#/$doc_ids{$fn}/",
 223                         );
 224                         autoscript($package,"prerm","prerm-doc-base",
 225                                 "s/#DOC-ID#/$doc_ids{$fn}/",
 226                         );
 227                 }
 228         }
 229 }
 230
 231 =head1 SEE ALSO
 232
 233 L<debhelper(1)>
 234
 235 This program is a part of debhelper.
 236
 237 =head1 AUTHOR
 238
 239 Joey Hess <joeyh@debian.org>
 240
 241 =cut