#!/usr/bin/perl

=encoding UTF-8

=head1 NAME

dh_installdocs - install documentation into package build directories

=cut

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

our $VERSION = DH_BUILTIN_VERSION;

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

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

In compat 11 and later, B<dh_installdocs> offers many of the features that
L<dh_install(1)> also have.  Furthermore, B<dh_installdocs> also supports
the B<nodoc> build profile to exclude documentation (regardless of compat
level).

=head1 FILES

=over 4

=item debian/I<package>.docs

List documentation files to be installed into I<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<--doc-main-package=>I<main-package>

Set the main package for a documentation package.  This is used to
install the documentation of the documentation package in F<<
/usr/share/doc/I<main-package> >> as recommended by the Debian policy
manual 3.9.7 in §12.3.

In compat 11 (or later), this option is only useful if debhelper's
auto-detection of the main package is wrong.  The option can also be
used to silence a warning from debhelper when the auto-detection fails
but the default happens to be correct.

This option cannot be used when B<dh_installdocs> is instructed to act
on multiple packages.  If you need this option, you will generally
need to combine it with B<-p> to ensure exactly one package is acted
on.

Please keep in mind that some documentation (the copyright file,
README.Debian, etc.) will be unaffected by this option.

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

Please note that this option only applies to the documentation
directory for the package itself.  When the package ships
documentation for another package (e.g. see B<--doc-main-package>), it
will not use a symlink for the documentation of the other package.


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},
	"sourcedir=s" => \$dh{SOURCEDIR},
	'doc-main-package=s' => \$dh{DOC_MAIN_PACKAGE},
});

my $called_getpackages = 0;
my $default_error_handler = compat(10) ? \&glob_expand_error_handler_warn_and_discard : \&glob_expand_error_handler_reject;
my $nodocs = is_build_profile_active('nodoc') || get_buildoption('nodoc') ? 1 : 0;
# We cannot assume documentation is built under nodoc, but if it is we must flag it as handled
# or dh_missing might make noise.
$default_error_handler = \&glob_expand_error_handler_silently_ignore if $nodocs;

if (@{$dh{DOPACKAGES}} > 1 and $dh{DOC_MAIN_PACKAGE}) {
	error('--doc-main-package should be used with -p<doc-pkg>');
}

if ($dh{DOC_MAIN_PACKAGE}) {
	assert_opt_is_known_package($dh{DOC_MAIN_PACKAGE}, '--doc-main-package');
}

foreach my $package (getpackages()) {
	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);
	my $skip_install = process_pkg($package) ? 0 : 1;
	my @search_dirs = ('.');
	my $error_handler = $skip_install ? \&glob_expand_error_handler_silently_ignore : $default_error_handler;
	@search_dirs = ($dh{SOURCEDIR} // '.', default_sourcedir($package)) if not compat(10);

	if (not $skip_install) {
		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, \@search_dirs, $error_handler);
	}

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

	log_installed_files($package, @docs);

	next if $skip_install;

	if (not $nodocs and @docs) {
		my $exclude = ' -and ! -empty';
		my $target_package = compute_doc_main_package($package);
		if (not defined($target_package)) {
			warning("Cannot auto-detect main package for ${package}.  If the default is wrong, please use --doc-main-package");
			$target_package = $package;
		}
		if ($dh{EXCLUDE_FIND}) {
			$exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
		}
		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 -f $doc && ! -s _; # 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;
				# Gracefully handling tmpdir being absolute (-P/...)
				my $docdir = $target_dir =~ m{^/} ? $target_dir : "${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","u+rw,go=rX","$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");
		}
	}

	next if $nodocs;

	# 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