Drop deprecated programs from the list of commands in debhelper(7). Closes: #548382

9 files changed, 40 insertions, 16 deletions

diff --git a/Makefile b/Makefile
index 6c128e26..3d47ea93 100644
--- a/Makefile
+++ b/Makefile
@@ -10,12 +10,19 @@ MAKEMANLIST=perl -e ' \
 		        $$file=<IN>; \
 		        close IN; \
 		        if ($$file=~m/=head1 .*?\n\n(.*?) - (.*?)\n\n/s) { \
-		                $$collect.="=item $$1(1)\n\n$$2\n\n"; \
+				my $$item="=item $$1(1)\n\n$$2\n\n"; \
+				if ($$2!~/deprecated/) { \
+			                $$list.=$$item; \
+				} \
+				else { \
+			                $$list_deprecated.=$$item; \
+				} \
 		        } \
 		} \
 		END { \
 			while (<STDIN>) { \
-		        	s/\#LIST\#/$$collect/; \
+		        	s/\#LIST\#/$$list/; \
+		        	s/\#LIST_DEPRECATED\#/$$list_deprecated/; \
 				print; \
 			}; \
 		}'
@@ -30,12 +37,9 @@ POD2MAN=pod2man --utf8 -c Debhelper -r "$(VERSION)"
 # l10n to be built is determined from .po files
 LANGS=$(notdir $(basename $(wildcard man/po4a/po/*.po)))
 
-build: version
+build: version debhelper.7
 	find . -maxdepth 1 -type f -perm +100 -name "dh*" \
 		-exec $(POD2MAN) {} {}.1 \;
-	cat debhelper.pod | \
-		$(MAKEMANLIST) `find . -maxdepth 1 -type f -perm +100 -name "dh_*" | sort` | \
-		$(POD2MAN) --name="debhelper" --section=7  > debhelper.7
 	po4a --previous -L UTF-8 man/po4a/po4a.cfg 
 	set -e; \
 	for lang in $(LANGS); do \
@@ -55,6 +59,11 @@ version:
 	printf "package Debian::Debhelper::Dh_Version;\n\$$version='$(VERSION)';\n1" > \
 		Debian/Debhelper/Dh_Version.pm
 
+debhelper.7: debhelper.pod
+	cat debhelper.pod | \
+		$(MAKEMANLIST) `find . -maxdepth 1 -type f -perm +100 -name "dh_*" | sort` | \
+		$(POD2MAN) --name="debhelper" --section=7  > debhelper.7
+
 clean:
 	rm -f *.1 *.7 Debian/Debhelper/Dh_Version.pm
 	po4a --previous --rm-translations --rm-backups man/po4a/po4a.cfg
diff --git a/debhelper.pod b/debhelper.pod
index 78de41d5..98aa422c 100644
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -28,7 +28,7 @@ package contains a tutorial about making your first package using debhelper.
 
 =head1 DEBHELPER COMMANDS
 
-Here is the complete list of available debhelper commands. See their man
+Here is the list of debhelper commands you can use. See their man
 pages for additional documentation.
 
 =over 4
@@ -37,8 +37,20 @@ pages for additional documentation.
 
 =back
 
+=head2 Deprecated Commands
+
+A few debhelper commands are deprecated and should not be used.
+
+=over 4
+
+#LIST_DEPRECATED#
+
+=back
+
+=head2 Other Commands
+
 If a program's name starts with "dh_", and the program is not on the above
-list, then it is not part of the debhelper package, but it should still
+lists, then it is not part of the debhelper package, but it should still
 work like the other programs described on this page.
 
 =head1 DEBHELPER CONFIG FILES
diff --git a/debian/changelog b/debian/changelog
index 1eca2a1f..b9debf47 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -14,6 +14,8 @@ debhelper (7.4.4) UNRELEASED; urgency=low
   * Add deprecation warnings for -u to the documentation, since putting
     options after -- is much more sane. (However, -u will not go away any
     time soon.) Closes: #554509
+  * Drop deprecated programs from the list of commands in debhelper(7).
+    Closes: #548382
 
  -- Joey Hess <joeyh@debian.org>  Wed, 28 Oct 2009 18:10:45 -0400
 
diff --git a/dh_installmanpages b/dh_installmanpages
index 2257517b..4a5f4735 100755
--- a/dh_installmanpages
+++ b/dh_installmanpages
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_installmanpages - old-style man page installer
+dh_installmanpages - old-style man page installer (deprecated)
 
 =cut
 
diff --git a/dh_python b/dh_python
index 857504f7..8f8c3788 100755
--- a/dh_python
+++ b/dh_python
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_python - calculates python dependencies and adds postinst and prerm python scripts
+dh_python - calculates python dependencies and adds postinst and prerm python scripts (deprecated)
 
 =cut
 
diff --git a/dh_suidregister b/dh_suidregister
index 3bc9bd98..5af99e73 100755
--- a/dh_suidregister
+++ b/dh_suidregister
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_suidregister - obsolete suid registration program
+dh_suidregister - suid registration program (deprecated)
 
 =head1 SYNOPSIS
 
@@ -12,8 +12,8 @@ Do not run!
 
 This program used to register suid and sgid files with L<suidregister(1)>,
 but with the introduction of L<dpkg-statoverride(8)>, registration of files
-in this way is unnecessary, and even harmful, so this program should not be
-used.
+in this way is unnecessary, and even harmful, so this program is deprecated
+and should not be used.
 
 =head1 CONVERTING TO STATOVERRIDE
 
diff --git a/dh_testversion b/dh_testversion
index 9c1c391d..db411ab0 100755
--- a/dh_testversion
+++ b/dh_testversion
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_testversion - ensure that the correct version of debhelper is installed
+dh_testversion - ensure that the correct version of debhelper is installed (deprecated)
 
 =cut
 
diff --git a/dh_undocumented b/dh_undocumented
index 5596485c..32cfbd8b 100755
--- a/dh_undocumented
+++ b/dh_undocumented
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_undocumented - obsolete undocumented.7 symlink program
+dh_undocumented - undocumented.7 symlink program (deprecated no-op)
 
 =cut
 
diff --git a/doc/TODO b/doc/TODO
index 64e5b66a..50418b8d 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -22,7 +22,8 @@ Deprecated:
 * dh_suidregister. Once nothing in the archive uses it.
 * dh_installmanpages.
 * dh_testversion. Remove as soon as nothing uses it.
-* dh_movefiles. I won't hold my breath.
+* dh_movefiles. I won't hold my breath. Have not added deprecation
+  docs or message yet.
 * dh_undocumented
 * dh_installinit --init-script (make it warn)
 * dh_python