Tidy up chkstow code and documentation.

bin/chkstow.in

@@ -8,10 +8,12 @@ require 5.6.1;
 use File::Find;
 use Getopt::Long;
 
-our $Wanted = \&bad_links;
+my $DEFAULT_TARGET = '/usr/local/';
-our %Package=();
+
+our $Wanted   = \&bad_links;
+our %Package  = ();
 our $Stow_dir = '';
-our $Target = q{/usr/local/};
+our $Target   = $DEFAULT_TARGET;
 
 # put the main loop into a block so that tests can load this as a module
 if ( not caller() ) {
@@ -38,11 +40,13 @@ sub usage {
 USAGE: chkstow [options]
 
 Options:
-    -b, --badlinks        Report symlinks that point to non-existant files.
+    -t DIR, --target=DIR  Set the target directory to DIR
-    -a, --aliens          Report non-symlinks in the target directory.
+                          (default is $DEFAULT_TARGET)
-    -l, --list            List packages in the target directory.
+    -b, --badlinks        Report symlinks that point to non-existent files
-    -t DIR, --target=DIR  Set the target directory to DIR (default
+    -a, --aliens          Report non-symlinks in the target directory
-							   is /usr/local)
+    -l, --list            List packages in the target directory
+
+--badlinks is the default mode.
 EOT
     exit(0);
 }
@@ -104,5 +108,6 @@ sub list {
 
 # Local variables:
 # mode: perl
+# cperl-indent-level: 4
 # End:
 # vim: ft=perl

doc/stow.texi

@@ -355,12 +355,14 @@ doing.  Verbosity levels are 0, 1, 2, and 3; 0 is the default.  Using
 
 @item -p
 @itemx --compat
-Scan the whole target tree when unstowing.  By default, only directories
+Scan the whole target tree when unstowing.  By default, only
-specified in the @dfn{installation image} are scanned during an unstow
+directories specified in the @dfn{installation image} are scanned
-operation.  Scanning the whole tree can be prohibitive if your target tree is
+during an unstow operation.  Scanning the whole tree can be
-very large.  This option restores the legacy behaviour; however, the
+prohibitive if your target tree is very large.  This option restores
-@samp{--badlinks} option may be a better way of ensuring that your
+the legacy behaviour; however, the @samp{--badlinks} option to the
-installation does not have any dangling symlinks.
+@command{chkstow} utility may be a better way of ensuring that your
+installation does not have any dangling symlinks (@pxref{Target
+Maintenance}).
 
 @item -V
 @itemx --version
@@ -395,29 +397,6 @@ might like to use this feature. This option may be repeated any number
 of times.
 @end table
 
-The following options are useful for cleaning up your target tree:
-
-@table @samp
-@item -b
-@itemx --badlinks
-Checks target directory for bogus symbolic links. That is, links that point to
-non-existent files.
-
-@item -a
-@itemx --aliens
-Checks for files in the target directory that are not symbolic links. The
-target directory should be managed by stow alone, except for directories that
-contain a @file{.stow} file.
-
-@item -l
-@itemx --list
-Will display the target package for every symbolic link in the stow target
-directory.
-The following options are deprecated:
-@end table
-
-@xref{Resource Files}, for a way to set default values for any of these
-options.
 
 @c ===========================================================================
 @node Ignore Lists, Installing Packages, Invoking Stow, Top
@@ -779,19 +758,46 @@ symlink, and thus cannot remove it).
 @node Target Maintenance, Resource Files, Multiple Stow Directories, Top
 @chapter Target Maintenance
 
-From time to time you will need to clean up your target tree.
+From time to time you will need to clean up your target tree.  Since
-Stow includes three operational modes that performs checks that
+version 2, Stow provides a new utility @command{chkstow} to help with
-would generally be too expensive to performed during normal stow
+this.  It includes three operational modes which performs checks that
+would generally be too expensive to be performed during normal stow
 execution.
 
-I've added a -l option to chkstow
+The syntax of the @code{chkstow} command is:
-which will give you a listing of every package name that has already been stowed
-should be able to diff this with your directory listing
 
-bash
+@example
-cd build/scripts
+chkstow [@var{options}]
-diff <(../bin/chkstow -l) <(ls -1)
+@end example
 
+@noindent
+The following options are supported:
+
+@table @samp
+
+@item -t @var{dir}
+@itemx --target=@var{dir}
+Set the target directory to @var{dir} instead of the parent of the stow
+directory.  Defaults to the parent of the stow directory, so it is typical to
+execute @code{stow} from the directory @file{/usr/local/stow}.
+
+@item -b
+@itemx --badlinks
+Checks target directory for bogus symbolic links. That is, links that point to
+non-existent files.
+
+@item -a
+@itemx --aliens
+Checks for files in the target directory that are not symbolic links. The
+target directory should be managed by stow alone, except for directories that
+contain a @file{.stow} file.
+
+@item -l
+@itemx --list
+Will display the target package for every symbolic link in the stow target
+directory.
+
+@end table
 
 @c ===========================================================================
 @node Resource Files, Compile-time vs Install-time, Target Maintenance, Top