5 dh_installdocs - install documentation into package build directories
10 use Debian::Debhelper::Dh_Lib;
14 B<dh_installdocs> [S<I<debhelper options>>] [B<-A>] [B<-n>] [B<-X>I<item>] [S<I<file ...>>]
18 dh_installdocs is a debhelper program that is responsible for installing
19 documentation into usr/share/doc/package in package build directories.
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.
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.
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.
40 Files named debian/package.docs can list other files to be installed.
42 Files named debian/package.doc-base, will be installed as doc-base control
43 files, and will make this program automatically generate the postinst and
44 prerm commands needed to interface with the doc-base package. Note that the
45 doc-id will be determined from the "Document:" entry in the
46 doc-base control file in question.
48 If your package needs to register more than one document, you need multiple
49 files. To accomplish this, you can use files named debian/package.doc-base.*
57 Install all files specified by command line parameters in ALL packages
60 =item B<-n>, B<--noscripts>
62 Do not modify postinst/prerm scripts.
64 =item B<-Xitem>, B<--exclude=item>
66 Exclude files that contain "item" anywhere in their filename from
71 Install these files as documentation into the first package acted on. (Or
72 in all packages if B<-A> is specified).
78 Note that dh_installdocs will happily copy entire directory hierarchies if
79 you ask it to (similar to cp -a). If it is asked to install a
80 directory, it will install the complete contents of the directory.
82 Note that this command is not idempotent. "dh_clean B<-k>" should be called
83 between invocations of this command. Otherwise, it may cause multiple
84 instances of the same text to be added to maintainer scripts.
90 foreach my $package (@{$dh{DOPACKAGES}}) {
91 my $tmp=tmpdir($package);
92 my $file=pkgfile($package,"docs");
94 # If this is a symlink, leave it alone.
95 if ( ! -d "$tmp/usr/share/doc/$package" &&
96 ! -l "$tmp/usr/share/doc/$package") {
97 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc/$package");
103 @docs=filearray($file, ".");
106 if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
112 if ($dh{EXCLUDE_FIND}) {
113 $exclude = ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
115 foreach my $doc (@docs) {
116 next if excludefile($doc);
117 if (-d $doc && $exclude) {
118 my ($dir_basename) = basename($doc);
119 # Pity there's no cp --exclude ..
122 complex_doit("cd $doc/.. && find $dir_basename -type f$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;");
125 doit("cp","-a",$doc,"$tmp/usr/share/doc/$package");
128 doit("chown","-R","0.0","$tmp/usr/share/doc");
129 doit("chmod","-R","go=rX","$tmp/usr/share/doc");
130 doit("chmod","-R","u+rw","$tmp/usr/share/doc");
133 # .Debian is correct, according to policy, but I'm easy.
134 my $readme_debian=pkgfile($package,'README.Debian');
135 if (! $readme_debian) {
136 $readme_debian=pkgfile($package,'README.debian');
138 if ($readme_debian && ! excludefile($readme_debian)) {
139 doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian",
140 "$tmp/usr/share/doc/$package/README.Debian");
143 my $todo=pkgfile($package,'TODO');
144 if ($todo && ! excludefile($todo)) {
145 if (isnative($package)) {
146 doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
147 "$tmp/usr/share/doc/$package/TODO");
150 doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
151 "$tmp/usr/share/doc/$package/TODO.Debian");
155 # If the "directory" is a dangling symlink, then don't install
156 # the copyright file. This is useful for multibinary packages
157 # that share a doc directory.
158 if (-d "$tmp/usr/share/doc/$package") {
159 # Support debian/package.copyright, but if not present, fall
160 # back on debian/copyright for all packages, not just the
161 # main binary package.
162 my $copyright=pkgfile($package,'copyright');
163 if (! $copyright && -e "debian/copyright") {
164 $copyright="debian/copyright";
166 if ($copyright && ! excludefile($copyright)) {
167 doit("install","-g",0,"-o",0,"-m","644","-p",$copyright,
168 "$tmp/usr/share/doc/$package/copyright");
172 # Handle doc-base files. There are two filename formats, the usual
173 # plus an extended format (debian/package.*).
176 opendir(DEB,"debian/") || error("can't read debian directory: $!");
177 # If this is the main package, we need to handle unprefixed filenames.
178 # For all packages, we must support both the usual filename format plus
179 # that format with a period an something appended.
180 my $regexp="\Q$package\E\.";
181 if ($package eq $dh{MAINPACKAGE}) {
182 $regexp="(|$regexp)";
184 foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) {
185 # Parse the file to get the doc id.
186 open (IN, "debian/$fn") || die "Cannot read debian/$fn.";
188 if (/^Document:\s+(.*)(\s+)?/) {
198 if (! -d "$tmp/usr/share/doc-base/") {
199 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc-base/");
202 foreach my $fn (keys %doc_ids) {
203 doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn",
204 "$tmp/usr/share/doc-base/$doc_ids{$fn}");
205 if (! $dh{NOSCRIPTS}) {
206 autoscript($package,"postinst","postinst-doc-base",
207 "s/#DOC-ID#/$doc_ids{$fn}/",
209 autoscript($package,"prerm","prerm-doc-base",
210 "s/#DOC-ID#/$doc_ids{$fn}/",
220 This program is a part of debhelper.
224 Joey Hess <joeyh@debian.org>