reorg man page to list deprecated options in a final section

diff --git a/dh b/dh
index b86e36ad158736306579f703b10977791ce79ad1..14e3c18e6c287ce8aad9a57ea097208b3eef9429 100755 (executable)
--- a/dh
+++ b/dh
@@ -11,7 +11,7 @@ use Debian::Debhelper::Dh_Lib;
 
 =head1 SYNOPSIS
 
-B<dh> I<sequence> [B<--with> I<addon>[B<,>I<addon> ...]] [B<--list>] [B<--until> I<cmd>] [B<--before> I<cmd>] [B<--after> I<cmd>] [B<--remaining>] [S<I<debhelper options>>]
+B<dh> I<sequence> [B<--with> I<addon>[B<,>I<addon> ...]] [B<--list>] [S<I<debhelper options>>]
 
 =head1 DESCRIPTION
 
@@ -53,67 +53,16 @@ The inverse of B<--with>, disables using the given addon.
 
 List all available addons.
 
-=item B<--until> I<cmd>
-
-Run commands in the sequence until and including I<cmd>, then stop.
-(Deprecated)
-
-=item B<--before> I<cmd>
-
-Run commands in the sequence before I<cmd>, then stop.
-(Deprecated)
-
-=item B<--after> I<cmd>
-
-Run commands in the sequence that come after I<cmd>.
-(Deprecated)
-
-=item B<--remaining>
-
-Run all commands in the sequence that have yet to be run.
-(Deprecated)
-
 =item B<--no-act>
 
 Prints commands that would run for a given sequence, but does not run them.
 
 =back
 
-All other options passed to B<dh> are passed on to each command it runs. This
+Other options passed to B<dh> are passed on to each command it runs. This
 can be used to set an option like B<-v> or B<-X> or B<-N>, as well as for more
 specialised options.
 
-In the above options, I<cmd> can be a full name of a debhelper command, or
-a substring. It'll first search for a command in the sequence exactly
-matching the name, to avoid any ambiguity. If there are multiple substring
-matches, the last one in the sequence will be used.
-
-=cut
-
-sub command_pos {
-       my $command=shift;
-       my @sequence=@_;
-
-       foreach my $i (0..$#sequence) {
-               if ($command eq $sequence[$i]) {
-                       return $i;
-               }
-       }
-
-       my @matches;
-       foreach my $i (0..$#sequence) {
-               if ($sequence[$i] =~ /\Q$command\E/) {
-                       push @matches, $i;
-               }
-       }
-       if (! @matches) {
-               error "command specification \"$command\" does not match any command in the sequence"
-       }
-       else {
-               return pop @matches;
-       }
-}
-
 =head1 EXAMPLES
 
 To see what commands are included in a sequence, without actually doing
@@ -288,6 +237,36 @@ through to debhelper commands that are run inside override targets. The
 contents (and indeed, existence) of this environment variable, as the name
 might suggest, is subject to change at any time.
 
+=head1 DEPRECATED OPTIONS
+
+The following options are deprecated. It's much 
+better to use override targets instead.
+
+=over 4
+
+=item B<--until> I<cmd>
+
+Run commands in the sequence until and including I<cmd>, then stop.
+
+=item B<--before> I<cmd>
+
+Run commands in the sequence before I<cmd>, then stop.
+
+=item B<--after> I<cmd>
+
+Run commands in the sequence that come after I<cmd>.
+
+=item B<--remaining>
+
+Run all commands in the sequence that have yet to be run.
+
+=back
+
+In the above options, I<cmd> can be a full name of a debhelper command, or
+a substring. It'll first search for a command in the sequence exactly
+matching the name, to avoid any ambiguity. If there are multiple substring
+matches, the last one in the sequence will be used.
+
 =cut
 
 # Stash this away before init modifies it.
@@ -866,6 +845,30 @@ sub warn_deprecated {
        }
 }
 
+sub command_pos {
+       my $command=shift;
+       my @sequence=@_;
+
+       foreach my $i (0..$#sequence) {
+               if ($command eq $sequence[$i]) {
+                       return $i;
+               }
+       }
+
+       my @matches;
+       foreach my $i (0..$#sequence) {
+               if ($sequence[$i] =~ /\Q$command\E/) {
+                       push @matches, $i;
+               }
+       }
+       if (! @matches) {
+               error "command specification \"$command\" does not match any command in the sequence"
+       }
+       else {
+               return pop @matches;
+       }
+}
+
 =head1 SEE ALSO
 
 L<debhelper(7)>