Updated French man page translation. Closes: #685560

[debhelper.git] / dh_installdocs

diff --git a/dh_installdocs b/dh_installdocs
index 465693bcedbe540933cbd180a22149a08ae94d40..104b796ea460a44701639cad9cf696a4d2255633 100755 (executable)
--- a/dh_installdocs
+++ b/dh_installdocs
@@ -11,12 +11,12 @@ use Debian::Debhelper::Dh_Lib;
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 

-B<dh_installdocs> [S<I<debhelper options>>] [B<-A>] [B<-X>I<item>] [S<I<file ...>>]
+B<dh_installdocs> [S<I<debhelper options>>] [B<-A>] [B<-X>I<item>] [S<I<file> ...>]

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 

-dh_installdocs is a debhelper program that is responsible for installing
-documentation into usr/share/doc/package in package build directories.
+B<dh_installdocs> is a debhelper program that is responsible for installing
+documentation into F<usr/share/doc/package> in package build directories.

 
 =head1 FILES
 
 
 =head1 FILES
 


@@ -24,13 +24,12 @@ documentation into usr/share/doc/package in package build directories.
 
 =item debian/I<package>.docs
 
 
 =item debian/I<package>.docs
 

-List documentaton files to be installed into I<package>.
+List documentation files to be installed into I<package>.

 
 

-=item debian/copyright
+=item F<debian/copyright>

 
 

-=item debian/README.Debian
-
-=item debian/TODO
+The copyright file is installed into all packages, unless a more
+specific copyright file is available.

 
 =item debian/I<package>.copyright
 
 
 =item debian/I<package>.copyright
 


@@ -38,16 +37,23 @@ List documentaton files to be installed into I<package>.
 
 =item debian/I<package>.TODO
 
 
 =item debian/I<package>.TODO
 

-Each of these files is automatically installed if present. Use the package
-specific name if I<package> needs a different version of the file.
+Each of these files is automatically installed if present for a
+I<package>.
+
+=item F<debian/README.Debian>
+
+=item F<debian/TODO>

 
 

-Note that debian/README.debian is also installed as README.Debian,
-and debian/TODO will be installed as TODO.Debian in non-native packages.
+These files are installed into the first binary package listed in
+debian/control.
+
+Note that F<README.debian> files are also installed as F<README.Debian>,
+and F<TODO> files will be installed as F<TODO.Debian> in non-native packages.

 
 =item debian/I<package>.doc-base
 
 Installed as doc-base control files. Note that the doc-id will be
 
 =item debian/I<package>.doc-base
 
 Installed as doc-base control files. Note that the doc-id will be

-determined from the "Document:" entry in the doc-base control file in
+determined from the B<Document:> entry in the doc-base control file in

 question.
 
 =item debian/I<package>.doc-base.*
 question.
 
 =item debian/I<package>.doc-base.*


@@ -66,12 +72,30 @@ doc-base files, and can name them like this.
 Install all files specified by command line parameters in ALL packages
 acted on.
 
 Install all files specified by command line parameters in ALL packages
 acted on.
 

-=item B<-Xitem>, B<--exclude=item>
+=item B<-X>I<item>, B<--exclude=>I<item>

 
 

-Exclude files that contain "item" anywhere in their filename from
+Exclude files that contain I<item> anywhere in their filename from

 being installed. Note that this includes doc-base files.
 
 being installed. Note that this includes doc-base files.
 

-=item I<file ...>
+=item B<--link-doc=>I<package>
+
+Make the documentation directory of all packages acted on be a symlink to
+the documentation directory of I<package>. This has no effect when acting on
+I<package> itself, or if the documentation directory to be created already
+exists when B<dh_installdocs> is run. To comply with policy, I<package> must
+be a binary package that comes from the same source package.
+
+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<copyright>, F<changelog>, F<README.Debian>, and F<TODO> files will
+not be 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<dh_installdocs>.)
+
+=item I<file> ...

 
 Install these files as documentation into the first package acted on. (Or
 in all packages if B<-A> is specified).
 
 Install these files as documentation into the first package acted on. (Or
 in all packages if B<-A> is specified).


@@ -80,7 +104,7 @@ in all packages if B<-A> is specified).
 
 =head1 EXAMPLES
 
 
 =head1 EXAMPLES
 

-This is an example of a debian/package.docs file:
+This is an example of a F<debian/package.docs> file:

 
   README
   TODO
 
   README
   TODO


@@ -91,8 +115,8 @@ This is an example of a debian/package.docs file:
 
 =head1 NOTES
 
 
 =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<dh_installdocs> will happily copy entire directory hierarchies if
+you ask it to (similar to B<cp -a>). If it is asked to install a

 directory, it will install the complete contents of the directory.
 
 Note that this command is not idempotent. L<dh_prep(1)> should be called
 directory, it will install the complete contents of the directory.
 
 Note that this command is not idempotent. L<dh_prep(1)> should be called


@@ -101,18 +125,59 @@ instances of the same text to be added to maintainer scripts.
 
 =cut
 
 
 =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");
 
 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;
        }
 
        my @docs;


@@ -121,7 +186,7 @@ foreach my $package (@{$dh{DOPACKAGES}}) {
                @docs=filearray($file, ".");
        }
 
                @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;
        }
 
                push @docs, @ARGV;
        }
 


@@ -137,6 +202,7 @@ foreach my $package (@{$dh{DOPACKAGES}}) {
                foreach my $doc (@docs) {
                        next if excludefile($doc);
                        next if -e $doc && ! -s $doc && ! compat(4); # ignore empty files
                foreach my $doc (@docs) {
                        next if excludefile($doc);
                        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/..";
                        if (-d $doc && length $exclude) {
                                my $basename = basename($doc);
                                my $dir = ($basename eq '.') ? $doc : "$doc/..";


@@ -158,13 +224,15 @@ foreach my $package (@{$dh{DOPACKAGES}}) {
        if (! $readme_debian) {
                $readme_debian=pkgfile($package,'README.debian');
        }
        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');
                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");
                if (isnative($package)) {
                        doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
                                "$tmp/usr/share/doc/$package/TODO");


@@ -178,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 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.
                # Support debian/package.copyright, but if not present, fall
                # back on debian/copyright for all packages, not just the 
                # main binary package.


@@ -187,8 +255,9 @@ foreach my $package (@{$dh{DOPACKAGES}}) {
                        $copyright="debian/copyright";
                }
                if ($copyright && ! excludefile($copyright)) {
                        $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");

                }
        }
 
                }
        }
 


@@ -217,6 +286,9 @@ foreach my $package (@{$dh{DOPACKAGES}}) {
                                last;
                        }
                }
                                last;
                        }
                }

+               if (! exists $doc_ids{$fn}) {
+                       warning("Could not parse $fn for doc-base Document id; skipping");
+               }

                close IN;
        }
        closedir(DEB);
                close IN;
        }
        closedir(DEB);