X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=dh_installdocs;h=104b796ea460a44701639cad9cf696a4d2255633;hb=e2a6d4cec4a7ee952cf6a7f250d80f1d75a38f95;hp=7bfe8ff167803eca067f66a3b7c01ddbd53de797;hpb=8ba59bbb27c5caf42ccb9c96c9be803b3310448f;p=debhelper.git diff --git a/dh_installdocs b/dh_installdocs index 7bfe8ff..104b796 100755 --- a/dh_installdocs +++ b/dh_installdocs @@ -11,47 +11,57 @@ use Debian::Debhelper::Dh_Lib; =head1 SYNOPSIS -B [S>] [B<-A>] [B<-n>] [B<-X>I] [S>] +B [S>] [B<-A>] [B<-X>I] [S ...>] =head1 DESCRIPTION -dh_installdocs is a debhelper program that is responsible for installing -documentation into usr/share/doc/package in package build directories. - -dh_installdocs automatically installs debian/copyright if it exists. If -dh_installdocs is acting on multiple packages, debian/copyright files will be -installed into all packages. However, if you need to have seperate copyright -files for different binary packages, you can use files named -debian/package.copyright. - -Any filenames specified as parameters will be installed into the first -package dh_installdocs is told to act on. By default, this is the first -binary package in debian/control, but if you use B<-p>, B<-i>, or B<-a> flags, it -will be the first package specified by those flags. - -Also, debian/README.Debian (or debian/README.debian) and debian/TODO, if -they exist, will be installed into the first binary package listed in -debian/control, if dh_installdocs is acting on that package. Note that -debian/TODO will be installed named TODO.Debian, if the package is not a -debian native package. Also note that README.debian is installed as -README.Debian, for consistency. Note that debian/package.README.Debian and -debian/package.TODO can be used to specify files for subpackages. - -Files named debian/package.docs can list other files to be installed. - -This program will automatically generate postinst and prerm commands to -maintain a compatibility symlink, /usr/doc/package, to the documentation in -/usr/share/doc/package. See L for an explanation of how -this works. - -Files named debian/package.doc-base, will be installed as doc-base control -files, and will make this program automatically generate the postinst and -prerm commands needed to interface with the doc-base package. Note that the -doc-id will be determined from the "Document:" entry in the -doc-base control file in question. +B is a debhelper program that is responsible for installing +documentation into F in package build directories. + +=head1 FILES + +=over 4 + +=item debian/I.docs + +List documentation files to be installed into I. + +=item F + +The copyright file is installed into all packages, unless a more +specific copyright file is available. + +=item debian/I.copyright + +=item debian/I.README.Debian + +=item debian/I.TODO + +Each of these files is automatically installed if present for a +I. + +=item F + +=item F + +These files are installed into the first binary package listed in +debian/control. + +Note that F files are also installed as F, +and F files will be installed as F in non-native packages. + +=item debian/I.doc-base + +Installed as doc-base control files. Note that the doc-id will be +determined from the B entry in the doc-base control file in +question. + +=item debian/I.doc-base.* If your package needs to register more than one document, you need multiple -files. To accomplish this, you can use files named debian/package.doc-base.* +doc-base files, and can name them like this. + +=back =head1 OPTIONS @@ -62,44 +72,112 @@ files. To accomplish this, you can use files named debian/package.doc-base.* Install all files specified by command line parameters in ALL packages acted on. -=item B<-n>, B<--noscripts> +=item B<-X>I, B<--exclude=>I + +Exclude files that contain I anywhere in their filename from +being installed. Note that this includes doc-base files. + +=item B<--link-doc=>I -Do not modify postinst/prerm scripts. +Make the documentation directory of all packages acted on be a symlink to +the documentation directory of I. This has no effect when acting on +I itself, or if the documentation directory to be created already +exists when B is run. To comply with policy, I must +be a binary package that comes from the same source package. -=item B<-Xitem>, B<--exclude=item> +debhelper will try to avoid installing files into linked documentation +directories that would cause conflicts with the linked package. The B<-A> +option will have no effect on packages with linked documentation +directories, and F, F, F, and F files will +not be installed. -Exclude files that contain "item" anywhere in their filename from -being installed. +(An older method to accomplish the same thing, which is still supported, +is to make the documentation directory of a package be a dangling symlink, +before calling B.) -=item I +=item I ... Install these files as documentation into the first package acted on. (Or in all packages if B<-A> is specified). =back +=head1 EXAMPLES + +This is an example of a F file: + + README + TODO + debian/notes-for-maintainers.txt + docs/manual.txt + docs/manual.pdf + docs/manual-html/ + =head1 NOTES -Note that dh_installdocs will happily copy entire directory hierarchies if -you ask it to (similar to cp -a). If it is asked to install a +Note that B will happily copy entire directory hierarchies if +you ask it to (similar to B). If it is asked to install a directory, it will install the complete contents of the directory. -Note that this command is not idempotent. "dh_clean B<-k>" should be called +Note that this command is not idempotent. L should be called between invocations of this command. Otherwise, it may cause multiple instances of the same text to be added to maintainer scripts. =cut -init(); +my %docdir_created; +# Create documentation directories on demand. This allows us to use dangling +# symlinks for linked documentation directories unless additional files need +# to be installed. +sub ensure_docdir { + my $package=shift; + return if $docdir_created{$package}; + my $tmp=tmpdir($package); + + my $target; + if ($dh{LINK_DOC} && $dh{LINK_DOC} ne $package) { + $target="$tmp/usr/share/doc/$dh{LINK_DOC}"; + } + else { + $target="$tmp/usr/share/doc/$package"; + } + + # If this is a symlink, leave it alone. + if (! -d $target && ! -l $target) { + doit("install","-g",0,"-o",0,"-d",$target); + } + $docdir_created{$package}=1; +} + +init(options => { + "link-doc=s" => \$dh{LINK_DOC}, +}); foreach my $package (@{$dh{DOPACKAGES}}) { + next if is_udeb($package); + my $tmp=tmpdir($package); my $file=pkgfile($package,"docs"); + my $link_doc=($dh{LINK_DOC} && $dh{LINK_DOC} ne $package); - # If this is a symlink, leave it alone. - if ( ! -d "$tmp/usr/share/doc/$package" && - ! -l "$tmp/usr/share/doc/$package") { - doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc/$package"); + if ($link_doc) { + # Make sure that the parent directory exists. + if (! -d "$tmp/usr/share/doc" && ! -l "$tmp/usr/share/doc") { + doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc"); + } + # Create symlink to another documentation directory if + # necessary. + if (! -d "$tmp/usr/share/doc/$package" && + ! -l "$tmp/usr/share/doc/$package") { + doit("ln", "-sf", $dh{LINK_DOC}, "$tmp/usr/share/doc/$package"); + # Policy says that if you make your documentation + # directory a symlink, then you have to depend on + # the target. + addsubstvar($package, "misc:Depends", $dh{LINK_DOC}); + } + } + else { + ensure_docdir($package); } my @docs; @@ -108,29 +186,35 @@ foreach my $package (@{$dh{DOPACKAGES}}) { @docs=filearray($file, "."); } - if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) { + if (($package eq $dh{FIRSTPACKAGE} || ($dh{PARAMS_ALL} && ! $link_doc)) && @ARGV) { push @docs, @ARGV; } if (@docs) { my $exclude = ''; if ($dh{EXCLUDE_FIND}) { - $exclude = ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)'; + $exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)'; + } + if (! compat(4)) { + # ignore empty files in subdirs + $exclude .= ' -and ! -empty'; } foreach my $doc (@docs) { next if excludefile($doc); - if (-d $doc && $exclude) { - my ($dir_basename) = basename($doc); - # Pity there's no cp --exclude .. - my $pwd=`pwd`; - chomp $pwd; - complex_doit("cd $doc/.. && find $dir_basename -type f$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;"); + next if -e $doc && ! -s $doc && ! compat(4); # ignore empty files + ensure_docdir($package); + if (-d $doc && length $exclude) { + my $basename = basename($doc); + my $dir = ($basename eq '.') ? $doc : "$doc/.."; + my $pwd=`pwd`; + chomp $pwd; + complex_doit("cd '$dir' && find '$basename' \\( -type f -or -type l \\)$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;"); } else { - doit("cp","-a",$doc,"$tmp/usr/share/doc/$package"); + doit("cp", "-a", $doc, "$tmp/usr/share/doc/$package"); } } - doit("chown","-R","0.0","$tmp/usr/share/doc"); + doit("chown","-R","0:0","$tmp/usr/share/doc"); doit("chmod","-R","go=rX","$tmp/usr/share/doc"); doit("chmod","-R","u+rw","$tmp/usr/share/doc"); } @@ -140,13 +224,15 @@ foreach my $package (@{$dh{DOPACKAGES}}) { if (! $readme_debian) { $readme_debian=pkgfile($package,'README.debian'); } - if ($readme_debian && ! excludefile($readme_debian)) { + if (! $link_doc && $readme_debian && ! excludefile($readme_debian)) { + ensure_docdir($package); doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian", "$tmp/usr/share/doc/$package/README.Debian"); } my $todo=pkgfile($package,'TODO'); - if ($todo && ! excludefile($todo)) { + if (! $link_doc && $todo && ! excludefile($todo)) { + ensure_docdir($package); if (isnative($package)) { doit("install","-g",0,"-o",0,"-m","644","-p",$todo, "$tmp/usr/share/doc/$package/TODO"); @@ -160,7 +246,7 @@ foreach my $package (@{$dh{DOPACKAGES}}) { # If the "directory" is a dangling symlink, then don't install # the copyright file. This is useful for multibinary packages # that share a doc directory. - if (-d "$tmp/usr/share/doc/$package") { + if (! $link_doc && (! -l "$tmp/usr/share/doc/$package" || -d "$tmp/usr/share/doc/$package")) { # Support debian/package.copyright, but if not present, fall # back on debian/copyright for all packages, not just the # main binary package. @@ -169,21 +255,12 @@ foreach my $package (@{$dh{DOPACKAGES}}) { $copyright="debian/copyright"; } if ($copyright && ! excludefile($copyright)) { - doit("install","-g",0,"-o",0,"-m","644","-p",$copyright, - "$tmp/usr/share/doc/$package/copyright"); + ensure_docdir($package); + doit("install","-g",0,"-o",0,"-m","644","-p",$copyright, + "$tmp/usr/share/doc/$package/copyright"); } } - # Add in the /usr/doc compatibility symlinks code. - if (! $dh{NOSCRIPTS}) { - autoscript($package,"postinst","postinst-doc", - "s/#PACKAGE#/$package/g", - ); - autoscript($package,"prerm","prerm-doc", - "s/#PACKAGE#/$package/g", - ); - } - # Handle doc-base files. There are two filename formats, the usual # plus an extended format (debian/package.*). my %doc_ids; @@ -197,14 +274,21 @@ foreach my $package (@{$dh{DOPACKAGES}}) { $regexp="(|$regexp)"; } foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) { + # .EX are example files, generated by eg, dh-make + next if $fn=~/\.EX$/; + next if excludefile($fn); # Parse the file to get the doc id. open (IN, "debian/$fn") || die "Cannot read debian/$fn."; while () { - if (/^Document:\s+(.*)(\s+)?/) { + s/\s*$//; + if (/^Document\s*:\s*(.*)/) { $doc_ids{$fn}=$1; last; } } + if (! exists $doc_ids{$fn}) { + warning("Could not parse $fn for doc-base Document id; skipping"); + } close IN; } closedir(DEB); @@ -217,20 +301,12 @@ foreach my $package (@{$dh{DOPACKAGES}}) { foreach my $fn (keys %doc_ids) { doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn", "$tmp/usr/share/doc-base/$doc_ids{$fn}"); - if (! $dh{NOSCRIPTS}) { - autoscript($package,"postinst","postinst-doc-base", - "s/#DOC-ID#/$doc_ids{$fn}/", - ); - autoscript($package,"prerm","prerm-doc-base", - "s/#DOC-ID#/$doc_ids{$fn}/", - ); - } } } =head1 SEE ALSO -L +L This program is a part of debhelper.