#!/usr/bin/perl -w

=head1 NAME

dh_undocumented - make symlinks to undocumented.7.gz man page

=cut

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

=head1 SYNOPSIS

 dh_undocumented [debhelper options] [-A] [manpage ...]

=head1 DESCRIPTION

dh_undocumented is a debhelper program that is responsible for making
symlinks to L<undocumented(7)> for man pages that are not present in your
package.

The program takes a list of man pages that should be symlinked to
L<undocumented(7)>. It examines the extension to see what section the man
page belongs in. After figuring this out, it generates the necessary
symlinks.

The lists of man pages that need symlinks can be specified in two ways. Any
man page names specified as
parameters will be set up in the first package dh_undocumented is told
to act on. By default, this is the first binary package in debian/control,
but if you use -p, -i, or -a flags, it will be the first package specified
by those flags.

Also, a file named debian/package.undocumented can list other man page
names to set up.

=head1 OPTIONS

=over 4

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

Install undocumented man page symlinks for any man pages specified by
command line parameters in ALL packages acted on. I doubt anyone will find
this useful, it's here for consitency with other debhelper programs.

=item I<manpage ...>

Install undocumented man page symlinks for each of these man pages
into the first package acted on. (Or in all packages acted on if -A is
specified.)

=back NOTES

Note that Debian policy prohibits links to L<undocumented(7)> unless the
package has an open bug report stating that it has no man page. You should
really just write a man page instead; this program is an easy way out.

=cut

init();

foreach my $package (@{$dh{DOPACKAGES}}) {
	my $tmp=tmpdir($package);
	my $undocumented=pkgfile($package,"undocumented");

	my @undoc;
	if ($undocumented) {
		@undoc=filearray($undocumented);
	}

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

	foreach my $file (@undoc) {
		$file=~s/.gz$//; # .gz extension is optional in input.

		# Determine what directory the file belongs in,
		# /usr/share/man, or /usr/X11R6/man, and how the link to
		# the undocumented.7 man page will look.
		my ($dir, $reldir);
		my ($section)=$file=~m/^.*\.(\d)/;
		if (!$section) {
			error("\"$file\" does not have an extension.");
		}	
		if ($section != 7) {
			$dir="usr/share/man/man$section";
			$reldir="../man7/";
		}
		else {
			$dir="usr/share/man/man$section";
			$reldir="";
		}

		# If an uncompressed version of the page exists, something
		# is weird.
		if (-e "$tmp/$dir/$file") {
			error("A man page $tmp/$dir/$file exists.");
		}
		
		if (! -d "$tmp/$dir") {
			doit("install","-d","$tmp/$dir");
		}		
		doit("ln","-sf","${reldir}undocumented.7.gz","$tmp/$dir/$file.gz");
	}
}

=head1 SEE ALSO

L<debhelper(1)>

This program is a part of debhelper.

=head1 AUTHOR

Joey Hess <joeyh@debian.org>

=cut