X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=dh_undocumented;h=7d98b207d5eb264260c417f5ef9b898e53d9e084;hb=7bf320dd5c5f4995c4a03d3c14c8d70d5443480e;hp=6a30f7220c8430384bddf864f3cf71c245086c47;hpb=6181521757b2af650b992d6aa02ca7790c964584;p=debhelper.git

diff --git a/dh_undocumented b/dh_undocumented
index 6a30f72..7d98b20 100755
--- a/dh_undocumented
+++ b/dh_undocumented
@@ -1,43 +1,90 @@
 #!/usr/bin/perl -w
-#
-# Passed a list of undocumented man pages, generates symlinks to
-# undocumented.7.gz for those man pages.
-#
-# Also, it looks for debian/undocumented files for more lists of
-# undocumented man pages.
-
-BEGIN { push @INC, "debian", "/usr/share/debhelper" }
-use Dh_Lib;
+
+=head1 NAME
+
+dh_undocumented - make symlinks to undocumented.7.gz man page
+
+=cut
+
+use strict;
+use Debian::Debhelper::Dh_Lib;
+
+=head1 SYNOPSIS
+
+B<dh_undocumented> [S<I<debhelper options>>] [B<-A>] [S<I<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 $PACKAGE (@{$dh{DOPACKAGES}}) {
-	$TMP=tmpdir($PACKAGE);
-	$undocumented=pkgfile($PACKAGE,"undocumented");
+foreach my $package (@{$dh{DOPACKAGES}}) {
+	my $tmp=tmpdir($package);
+	my $undocumented=pkgfile($package,"undocumented");
 
-	@undoc=();
+	my @undoc;
 	if ($undocumented) {
 		@undoc=filearray($undocumented);
 	}
 
-	if (($PACKAGE eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
+	if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
 		push @undoc, @ARGV;
 	}	
 
-	foreach $file (@undoc) {
-		$file=~s/.gz$//; # .gz extention is optional in input.
+	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 undocuemtned.7 man page will look.
-		($section)=$file=~m/^.*\.(\d)/;
+		# the undocumented.7 man page will look.
+		my ($dir, $reldir);
+		my ($section)=$file=~m/^.*\.(\d)/;
 		if (!$section) {
-			error("\"$file\" does not have an extention.");
+			error("\"$file\" does not have an extension.");
 		}	
-		if ($file=~/.*\.\dx/) {
-			$dir="usr/X11R6/man/man$section";
-			$reldir="../../../share/man/man7/";
-		}
-		elsif ($section != 7) {
+		if ($section != 7) {
 			$dir="usr/share/man/man$section";
 			$reldir="../man7/";
 		}
@@ -46,9 +93,27 @@ foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
 			$reldir="";
 		}
 
-		if (! -d "$TMP/$dir") {
-			doit("install","-d","$TMP/$dir");
+		# If an uncompressed version of the page exists, something
+		# is weird.
+		if (-e "$tmp/$dir/$file") {
+			error("A man page $tmp/$dir/$file exists.");
 		}
-		doit("ln","-sf","${reldir}undocumented.7.gz","$TMP/$dir/$file.gz");
+		
+		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