#!/usr/bin/perl

=head1 NAME

dh_installdocs - install documentation into package build directories

=cut

use strict;
use warnings;
use Debian::Debhelper::Dh_Lib;

=head1 SYNOPSIS

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

=head1 DESCRIPTION

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

When upstream's own build system installs all the desired documentation
correctly, then B<dh_install> may be a better tool for handling the upstream
documentation.  In this case, B<dh_installdocs> is still useful for installing
packaging related documentation (e.g. the F<debian/copyright> file).

=head1 FILES

=over 4

=item debian/I<package>.docs

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

In compat 11 (or later), these will be installed into
F</usr/share/doc/mainpackage>.  Previously it would be
F</usr/share/doc/package>.

=item F<debian/copyright>

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>.README.Debian

=item debian/I<package>.TODO

Each of these files is automatically installed if present for a
I<package>.

=item F<debian/README.Debian>

=item F<debian/TODO>

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
determined from the B<Document:> entry in the doc-base control file in
question. In the event that multiple doc-base files in a single source
package share the same doc-id, they will be installed to
usr/share/doc-base/package instead of usr/share/doc-base/doc-id.

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

If your package needs to register more than one document, you need
multiple doc-base files, and can name them like this. In the event
that multiple doc-base files of this style in a single source package
share the same doc-id, they will be installed to
usr/share/doc-base/package-* instead of usr/share/doc-base/doc-id.

=back

=head1 OPTIONS

=over 4

=item B<-A>, B<--all>

Install all files specified by command line parameters in ALL packages
acted on.

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

Exclude files that contain I<item> anywhere in their filename from
being installed. Note that this includes doc-base files.

=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>.)

B<CAVEAT 1>: If a previous version of the package was built without this
option and is now built with it (or vice-versa), it requires a "dir to
symlink" (or "symlink to dir") migration.  Since debhelper has no
knowledge of previous versions, you have to enable this migration
itself.

This can be done by providing a "debian/I<package>.maintscript" file
and using L<dh_installdeb(1)> to provide the relevant maintainer
script snippets.

B<CAVEAT 2>: The use of B<--link-doc> should only be done when the
packages have same "architecture" type.  A link from a architecture
independent package to a architecture dependent package (or vice
versa) will not work.  Since compat 10, debhelper will actively reject
unsupported combinations.

=item I<file> ...

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<debian/package.docs> file:

  README
  TODO
  debian/notes-for-maintainers.txt
  docs/manual.txt
  docs/manual.pdf
  docs/manual-html/

=head1 NOTES

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.

=cut

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) {
		install_dir($target);
	}
	$docdir_created{$package}=1;
}

init(options => {
	"link-doc=s" => \$dh{LINK_DOC},
});

my $called_getpackages = 0;

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 ($link_doc) {
		getpackages('both') unless $called_getpackages++;

		if (package_binary_arch($package) ne package_binary_arch($dh{LINK_DOC})) {
			if (compat(9)) {
				warning("WARNING: --link-doc between architecture all and not all packages breaks binNMUs");
			} else {
				error("--link-doc not allowed between ${package} and $dh{LINK_DOC} (one is arch:all and the other not)");
			}
		}
		# Make sure that the parent directory exists.
		if (! -d "$tmp/usr/share/doc" && ! -l "$tmp/usr/share/doc") {
			install_dir("$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") {
			make_symlink_raw_target($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} (= \${binary:Version})");
		}
	}
	else {
		ensure_docdir($package);
	}

	my @docs;

	if ($file) {
		@docs=filearray($file, ".");
	}

	if (($package eq $dh{FIRSTPACKAGE} || ($dh{PARAMS_ALL} && ! $link_doc)) && @ARGV) {
		push @docs, @ARGV;
	}

	if (@docs) {
		my $target_package = $package;
		my $exclude = ' -and ! -empty';
		if ($dh{EXCLUDE_FIND}) {
			$exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
		}
		if (not compat(10)) {
			$target_package = $dh{MAINPACKAGE};
		}
		my $target_dir = "$tmp/usr/share/doc/$target_package";
		install_dir($target_dir) unless -l $target_dir;
		foreach my $doc (@docs) {
			next if excludefile($doc);
			next if -e $doc && ! -s $doc; # 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;
				my $docdir = "$pwd/$target_dir";
				complex_doit("cd '$dir' && " .
							 "find '$basename' \\( -type f -or -type l \\)$exclude -print0 | LC_ALL=C sort -z | " .
							 "xargs -0 -I {} cp --reflink=auto --parents -dp {} $docdir");
			}
			else {
				doit("cp", '--reflink=auto', "-a", $doc, $target_dir);
			}
		}
		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");
	}

	# .Debian is correct, according to policy, but I'm easy.
	my $readme_debian=pkgfile($package,'README.Debian');
	if (! $readme_debian) {
		$readme_debian=pkgfile($package,'README.debian');
	}
	if (! $link_doc && $readme_debian && ! excludefile($readme_debian)) {
		ensure_docdir($package);
		install_file($readme_debian,
					 "$tmp/usr/share/doc/$package/README.Debian");
	}

	my $todo=pkgfile($package,'TODO');
	if (! $link_doc && $todo && ! excludefile($todo)) {
		ensure_docdir($package);
		if (isnative($package)) {
			install_file($todo, "$tmp/usr/share/doc/$package/TODO");
		}
		else {
			install_file($todo,
				"$tmp/usr/share/doc/$package/TODO.Debian");
		}
	}

	# 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 (! $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.
		my $copyright=pkgfile($package,'copyright');
		if (! $copyright && -e "debian/copyright") {
			$copyright="debian/copyright";
		}
		if ($copyright && ! excludefile($copyright)) {
			ensure_docdir($package);
			install_file($copyright,
				"$tmp/usr/share/doc/$package/copyright");
		}
	}

	# Handle doc-base files. There are two filename formats, the usual
	# plus an extended format (debian/package.*).
	my %doc_ids;
	
	opendir(DEB,"debian/") || error("can't read debian directory: $!");
	# If this is the main package, we need to handle unprefixed filenames.
	# For all packages, we must support both the usual filename format plus
	# that format with a period an something appended.
	my $regexp="\Q$package\E\.";
	if ($package eq $dh{MAINPACKAGE}) {
		$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(my $fd, '<', "debian/$fn") || die "Cannot read debian/$fn.";
		while (<$fd>) {
			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($fd);
	}
	closedir(DEB);
	
	if (%doc_ids) {
		install_dir("$tmp/usr/share/doc-base/");
	}
	# check for duplicate document ids
	my %used_doc_ids;
	for my $fn (keys %doc_ids) {
		$used_doc_ids{$doc_ids{$fn}}++;
	}
	foreach my $fn (keys %doc_ids) {
		# if this document ID is duplicated, we will install
		# to usr/share/doc-base/packagename instead of
		# usr/share/doc-base/doc_id. To allow for multiple
		# conflicting doc-bases in a single package, we will
		# install to usr/share/doc-base/packagename-extrabits
		# if the doc-base file is
		# packagename.doc-base.extrabits
		if ($used_doc_ids{$doc_ids{$fn}} > 1) {
			my $fn_no_docbase = $fn;
			$fn_no_docbase =~ s/\.doc-base(?:\.(.*))?/
			    if (defined $1 and length $1) {"-$1"} else {''}/xe;
			install_file("debian/$fn",
						 "$tmp/usr/share/doc-base/$fn_no_docbase");
		}
		else {
			install_file("debian/$fn",
						 "$tmp/usr/share/doc-base/$doc_ids{$fn}");
		}
	}
}

=head1 SEE ALSO

L<debhelper(7)>

This program is a part of debhelper.

=head1 AUTHOR

Joey Hess <joeyh@debian.org>

=cut

# Local Variables:
# indent-tabs-mode: t
# tab-width: 4
# cperl-indent-level: 4
# End: