Initial build - GNU stow suitable for linking into your home dir using GNU stow

.local/bin/chkstow

@@ -0,0 +1,113 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+require 5.006_001;
+
+use File::Find;
+use Getopt::Long;
+
+my $DEFAULT_TARGET = '/usr/local/';
+
+our $Wanted   = \&bad_links;
+our %Package  = ();
+our $Stow_dir = '';
+our $Target   = $DEFAULT_TARGET;
+
+# put the main loop into a block so that tests can load this as a module
+if ( not caller() ) {
+    if (@ARGV == 0) {
+        usage();
+    }
+    process_options();
+    #check_stow($Target, $Wanted);
+    check_stow();
+}
+
+sub process_options {
+    GetOptions(
+	'b|badlinks' => sub { $Wanted = \&bad_links },
+	'a|aliens'   => sub { $Wanted = \&aliens    },
+	'l|list'     => sub { $Wanted = \&list      },
+	't|target=s' => \$Target,
+	) or usage();
+    return;
+}
+
+sub usage {
+    print <<"EOT";
+USAGE: chkstow [options]
+
+Options:
+    -t DIR, --target=DIR  Set the target directory to DIR
+                          (default is $DEFAULT_TARGET)
+    -b, --badlinks        Report symlinks that point to non-existent files
+    -a, --aliens          Report non-symlinks in the target directory
+    -l, --list            List packages in the target directory
+
+--badlinks is the default mode.
+EOT
+    exit(0);
+}
+
+sub check_stow {
+    #my ($Target, $Wanted) = @_;
+
+    my (%options) = (
+        wanted     => $Wanted,
+        preprocess => \&skip_dirs,
+    );
+
+    find(\%options, $Target);
+
+    if ($Wanted == \&list) {
+        delete $Package{''};
+        delete $Package{'..'};
+
+        if (keys %Package) {
+            print map "$_\n", sort(keys %Package);
+        }
+    }
+    return;
+}
+
+sub skip_dirs {
+    # skip stow source and unstowed targets
+    if (-e ".stow" || -e ".notstowed" ) {
+        warn "skipping $File::Find::dir\n";
+        return ();
+    }
+    else {
+        return @_;
+    }
+}
+
+# checking for files that do not link to anything
+sub bad_links {
+    -l && !-e && print "Bogus link: $File::Find::name\n";
+}
+
+# checking for files that are not owned by stow
+sub aliens  {
+    !-l && !-d && print "Unstowed file: $File::Find::name\n";
+}
+
+# just list the packages in the the target directory
+# FIXME: what if the stow dir is not called 'stow'?
+sub list {
+    if (-l) {
+        $_ = readlink;
+        s{\A(?:\.\./)+stow/}{}g;
+        s{/.*}{}g;
+        $Package{$_} = 1;
+    }
+}
+
+1; # Hey, it's a module!
+
+# Local variables:
+# mode: perl
+# cperl-indent-level: 4
+# End:
+# vim: ft=perl

.local/bin/stow

@@ -0,0 +1,667 @@
+#!/usr/bin/perl
+
+# GNU Stow - manage the installation of multiple software packages
+# Copyright (C) 1993, 1994, 1995, 1996 by Bob Glickstein
+# Copyright (C) 2000, 2001 Guillaume Morin
+# Copyright (C) 2007 Kahlil Hodgson
+# Copyright (C) 2011 Adam Spiers
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <http://www.gnu.org/licenses/>.
+
+=head1 NAME
+
+stow - software package installation manager
+
+=head1 SYNOPSIS
+
+stow [ options ] package ...
+
+=head1 DESCRIPTION
+
+This manual page describes GNU Stow 2.2.2, a program for managing
+the installation of software packages. This is not the definitive
+documentation for stow; for that, see the info manual.
+
+Stow is a tool for managing the installation of multiple software
+packages in the same run-time directory tree. One historical
+difficulty of this task has been the need to administer, upgrade,
+install, and remove files in independent packages without confusing
+them with other files sharing the same filesystem space. For instance,
+it is common to install Perl and Emacs in F</usr/local>.  When one
+does so, one winds up (as of Perl 4.036 and Emacs 19.22) with the
+following files in F</usr/local/man/man1>: F<a2p.1>; F<ctags.1>;
+F<emacs.1>; F<etags.1>; F<h2ph.1>; F<perl.1>; and F<s2p.1>.  Now
+suppose it's time to uninstall Perl. Which man pages get removed?
+Obviously F<perl.1> is one of them, but it should not be the
+administrator's responsibility to memorize the ownership of individual
+files by separate packages.
+
+The approach used by Stow is to install each package into its own
+tree, then use symbolic links to make it appear as though the files
+are installed in the common tree. Administration can be performed in
+the package's private tree in isolation from clutter from other
+packages.  Stow can then be used to update the symbolic links. The
+structure of each private tree should reflect the desired structure in
+the common tree; i.e. (in the typical case) there should be a F<bin>
+directory containing executables, a F<man/man1> directory containing
+section 1 man pages, and so on.
+
+Stow was inspired by Carnegie Mellon's Depot program, but is
+substantially simpler and safer. Whereas Depot required database files
+to keep things in sync, Stow stores no extra state between runs, so
+there's no danger (as there was in Depot) of mangling directories when
+file hierarchies don't match the database. Also unlike Depot, Stow
+will never delete any files, directories, or links that appear in a
+Stow directory (e.g., F</usr/local/stow/emacs>), so it's always
+possible to rebuild the target tree (e.g., F</usr/local>).
+
+=head1 TERMINOLOGY
+
+A "package" is a related collection of files and directories that
+you wish to administer as a unit -- e.g., Perl or Emacs -- and that
+needs to be installed in a particular directory structure -- e.g.,
+with F<bin>, F<lib>, and F<man> subdirectories.
+
+A "target directory" is the root of a tree in which one or more
+packages wish to B<appear> to be installed. A common, but by no means
+the only such location is F</usr/local>.  The examples in this manual
+page will use F</usr/local> as the target directory.
+
+A "stow directory" is the root of a tree containing separate
+packages in private subtrees. When Stow runs, it uses the current
+directory as the default stow directory. The examples in this manual
+page will use F</usr/local/stow> as the stow directory, so that
+individual packages will be, for example, F</usr/local/stow/perl> and
+F</usr/local/stow/emacs>.
+
+An "installation image" is the layout of files and directories
+required by a package, relative to the target directory. Thus, the
+installation image for Perl includes: a F<bin> directory containing
+F<perl> and F<a2p> (among others); an F<info> directory containing
+Texinfo documentation; a F<lib/perl> directory containing Perl
+libraries; and a F<man/man1> directory containing man pages.
+
+A "package directory" is the root of a tree containing the
+installation image for a particular package. Each package directory
+must reside in a stow directory -- e.g., the package directory
+F</usr/local/stow/perl> must reside in the stow directory
+F</usr/local/stow>.  The "name" of a package is the name of its
+directory within the stow directory -- e.g., F<perl>.
+
+Thus, the Perl executable might reside in
+F</usr/local/stow/perl/bin/perl>, where F</usr/local> is the target
+directory, F</usr/local/stow> is the stow directory,
+F</usr/local/stow/perl> is the package directory, and F<bin/perl>
+within is part of the installation image.
+
+A "symlink" is a symbolic link. A symlink can be "relative" or
+"absolute". An absolute symlink names a full path; that is, one
+starting from F</>.  A relative symlink names a relative path; that
+is, one not starting from F</>.  The target of a relative symlink is
+computed starting from the symlink's own directory.  Stow only creates
+relative symlinks.
+
+=head1 OPTIONS
+
+The stow directory is assumed to be the value of the C<STOW_DIR>
+environment variable or if unset the current directory, and the target
+directory is assumed to be the parent of the current directory (so it
+is typical to execute F<stow> from the directory F</usr/local/stow>).
+Each F<package> given on the command line is the name of a package in
+the stow directory (e.g., F<perl>).  By default, they are installed
+into the target directory (but they can be deleted instead using
+C<-D>).
+
+=over 4
+
+=item -n
+
+=item --no
+
+Do not perform any operations that modify the filesystem; merely show
+what would happen.
+
+=item -d DIR
+
+=item --dir=DIR
+
+Set the stow directory to C<DIR> instead of the current directory.
+This also has the effect of making the default target directory be the
+parent of C<DIR>.
+
+=item -t DIR
+
+=item --target=DIR
+
+Set the target directory to C<DIR> instead of the parent of the stow
+directory.
+
+=item -v
+
+=item --verbose[=N]
+
+Send verbose output to standard error describing what Stow is
+doing. Verbosity levels are 0, 1, 2, 3, and 4; 0 is the default.
+Using C<-v> or C<--verbose> increases the verbosity by one; using
+`--verbose=N' sets it to N.
+
+=item -S
+
+=item --stow
+
+Stow the packages that follow this option into the target directory.
+This is the default action and so can be omitted if you are only
+stowing packages rather than performing a mixture of
+stow/delete/restow actions.
+
+=item -D
+
+=item --delete
+
+Unstow the packages that follow this option from the target directory rather
+than installing them.
+
+=item -R
+
+=item --restow
+
+Restow packages (first unstow, then stow again). This is useful
+for pruning obsolete symlinks from the target tree after updating
+the software in a package.
+
+=item --adopt
+
+B<Warning!>  This behaviour is specifically intended to alter the
+contents of your stow directory.  If you do not want that, this option
+is not for you.
+
+When stowing, if a target is encountered which already exists but is a
+plain file (and hence not owned by any existing stow package), then
+normally Stow will register this as a conflict and refuse to proceed.
+This option changes that behaviour so that the file is moved to the
+same relative place within the package's installation image within the
+stow directory, and then stowing proceeds as before.  So effectively,
+the file becomes adopted by the stow package, without its contents
+changing.
+
+=item --no-folding
+
+Disable folding of newly stowed directories when stowing, and
+refolding of newly foldable directories when unstowing.
+
+=item --ignore=REGEX
+
+Ignore files ending in this Perl regex.
+
+=item --defer=REGEX
+
+Don't stow files beginning with this Perl regex if the file is already
+stowed to another package.
+
+=item --override=REGEX
+
+Force stowing files beginning with this Perl regex if the file is
+already stowed to another package.
+
+=item -V
+
+=item --version
+
+Show Stow version number, and exit.
+
+=item -h
+
+=item --help
+
+Show Stow command syntax, and exit.
+
+=back
+
+=head1 INSTALLING PACKAGES
+
+The default action of Stow is to install a package. This means
+creating symlinks in the target tree that point into the package tree.
+Stow attempts to do this with as few symlinks as possible; in other
+words, if Stow can create a single symlink that points to an entire
+subtree within the package tree, it will choose to do that rather than
+create a directory in the target tree and populate it with symlinks.
+
+For example, suppose that no packages have yet been installed in
+F</usr/local>; it's completely empty (except for the F<stow>
+subdirectory, of course). Now suppose the Perl package is installed.
+Recall that it includes the following directories in its installation
+image: F<bin>; F<info>; F<lib/perl>; F<man/man1>.  Rather than
+creating the directory F</usr/local/bin> and populating it with
+symlinks to F<../stow/perl/bin/perl> and F<../stow/perl/bin/a2p> (and
+so on), Stow will create a single symlink, F</usr/local/bin>, which
+points to F<stow/perl/bin>.  In this way, it still works to refer to
+F</usr/local/bin/perl> and F</usr/local/bin/a2p>, and fewer symlinks
+have been created. This is called "tree folding", since an entire
+subtree is "folded" into a single symlink.
+
+To complete this example, Stow will also create the symlink
+F</usr/local/info> pointing to F<stow/perl/info>; the symlink
+F</usr/local/lib> pointing to F<stow/perl/lib>; and the symlink
+F</usr/local/man> pointing to F<stow/perl/man>.
+
+Now suppose that instead of installing the Perl package into an empty
+target tree, the target tree is not empty to begin with. Instead, it
+contains several files and directories installed under a different
+system-administration philosophy. In particular, F</usr/local/bin>
+already exists and is a directory, as are F</usr/local/lib> and
+F</usr/local/man/man1>.  In this case, Stow will descend into
+F</usr/local/bin> and create symlinks to F<../stow/perl/bin/perl> and
+F<../stow/perl/bin/a2p> (etc.), and it will descend into
+F</usr/local/lib> and create the tree-folding symlink F<perl> pointing
+to F<../stow/perl/lib/perl>, and so on. As a rule, Stow only descends
+as far as necessary into the target tree when it can create a
+tree-folding symlink.
+
+The time often comes when a tree-folding symlink has to be undone
+because another package uses one or more of the folded subdirectories
+in its installation image. This operation is called "splitting open"
+a folded tree. It involves removing the original symlink from the
+target tree, creating a true directory in its place, and then
+populating the new directory with symlinks to the newly-installed
+package B<and> to the old package that used the old symlink. For
+example, suppose that after installing Perl into an empty
+F</usr/local>, we wish to install Emacs.  Emacs's installation image
+includes a F<bin> directory containing the F<emacs> and F<etags>
+executables, among others. Stow must make these files appear to be
+installed in F</usr/local/bin>, but presently F</usr/local/bin> is a
+symlink to F<stow/perl/bin>.  Stow therefore takes the following
+steps: the symlink F</usr/local/bin> is deleted; the directory
+F</usr/local/bin> is created; links are made from F</usr/local/bin> to
+F<../stow/emacs/bin/emacs> and F<../stow/emacs/bin/etags>; and links
+are made from F</usr/local/bin> to F<../stow/perl/bin/perl> and
+F<../stow/perl/bin/a2p>.
+
+When splitting open a folded tree, Stow makes sure that the symlink
+it is about to remove points inside a valid package in the current stow
+directory.
+
+=head2 Stow will never delete anything that it doesn't own.
+
+Stow "owns" everything living in the target tree that points into a
+package in the stow directory. Anything Stow owns, it can recompute if
+lost. Note that by this definition, Stow doesn't "own" anything
+B<in> the stow directory or in any of the packages.
+
+If Stow needs to create a directory or a symlink in the target tree
+and it cannot because that name is already in use and is not owned by
+Stow, then a conflict has arisen. See the "Conflicts" section in the
+info manual.
+
+=head1 DELETING PACKAGES
+
+When the C<-D> option is given, the action of Stow is to delete a
+package from the target tree. Note that Stow will not delete anything
+it doesn't "own". Deleting a package does B<not> mean removing it from
+the stow directory or discarding the package tree.
+
+To delete a package, Stow recursively scans the target tree, skipping
+over the stow directory (since that is usually a subdirectory of the
+target tree) and any other stow directories it encounters (see
+"Multiple stow directories" in the info manual). Any symlink it
+finds that points into the package being deleted is removed. Any
+directory that contained only symlinks to the package being deleted is
+removed. Any directory that, after removing symlinks and empty
+subdirectories, contains only symlinks to a single other package, is
+considered to be a previously "folded" tree that was "split open."
+Stow will re-fold the tree by removing the symlinks to the surviving
+package, removing the directory, then linking the directory back to
+the surviving package.
+
+=head1 SEE ALSO
+
+The full documentation for F<stow> is maintained as a Texinfo manual.
+If the F<info> and F<stow> programs are properly installed at your site, the command
+
+    info stow
+
+should give you access to the complete manual.
+
+=head1 BUGS
+
+Please report bugs in Stow using the Debian bug tracking system.
+
+Currently known bugs include:
+
+=over 4
+
+=item * The empty-directory problem.
+
+If package F<foo> includes an empty directory -- say, F<foo/bar> --
+then if no other package has a F<bar> subdirectory, everything's fine.
+If another stowed package F<quux>, has a F<bar> subdirectory, then
+when stowing, F<targetdir/bar> will be "split open" and the contents
+of F<quux/bar> will be individually stowed.  So far, so good. But when
+unstowing F<quux>, F<targetdir/bar> will be removed, even though
+F<foo/bar> needs it to remain.  A workaround for this problem is to
+create a file in F<foo/bar> as a placeholder. If you name that file
+F<.placeholder>, it will be easy to find and remove such files when
+this bug is fixed.
+
+=item *
+
+When using multiple stow directories (see "Multiple stow directories"
+in the info manual), Stow fails to "split open" tree-folding symlinks
+(see "Installing packages" in the info manual) that point into a stow
+directory which is not the one in use by the current Stow
+command. Before failing, it should search the target of the link to
+see whether any element of the path contains a F<.stow> file. If it
+finds one, it can "learn" about the cooperating stow directory to
+short-circuit the F<.stow> search the next time it encounters a
+tree-folding symlink.
+
+=back
+
+=head1 AUTHOR
+
+This man page was originally constructed by Charles Briscoe-Smith from
+parts of Stow's info manual, and then converted to POD format by Adam
+Spiers.  The info manual contains the following notice, which, as it
+says, applies to this manual page, too.  The text of the section
+entitled "GNU General Public License" can be found in the file
+F</usr/share/common-licenses/GPL> on any Debian GNU/Linux system.  If
+you don't have access to a Debian system, or the GPL is not there,
+write to the Free Software Foundation, Inc., 59 Temple Place, Suite
+330, Boston, MA, 02111-1307, USA.
+
+=head1 COPYRIGHT
+
+Copyright (C)
+1993, 1994, 1995, 1996 by Bob Glickstein <bobg+stow@zanshin.com>;
+2000, 2001 by Guillaume Morin;
+2007 by Kahlil Hodgson;
+2011 by Adam Spiers;
+and others.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the section entitled "GNU General Public License" is included with the
+modified manual, and provided that the entire resulting derived work
+is distributed under the terms of a permission notice identical to
+this one.
+
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+=cut
+
+use strict;
+use warnings;
+
+require 5.006_001;
+
+use POSIX qw(getcwd);
+use Getopt::Long;
+
+use Cwd qw(abs_path);
+use File::Basename qw(dirname);
+use lib dirname(dirname(abs_path($0))) . '/share/perl';
+use Stow;
+use Stow::Util qw(parent error);
+
+my $ProgramName = $0;
+$ProgramName =~ s{.*/}{};
+
+main() unless caller();
+
+sub main {
+    my ($options, $pkgs_to_unstow, $pkgs_to_stow) = process_options();
+
+    my $stow = new Stow(%$options);
+    # current dir is now the target directory
+
+    $stow->plan_unstow(@$pkgs_to_unstow);
+    $stow->plan_stow  (@$pkgs_to_stow);
+
+    my %conflicts = $stow->get_conflicts;
+
+    if (%conflicts) {
+        foreach my $action ('unstow', 'stow') {
+            next unless $conflicts{$action};
+            foreach my $package (sort keys %{ $conflicts{$action} }) {
+                warn "WARNING! ${action}ing $package would cause conflicts:\n";
+                    #if $stow->get_action_count > 1;
+                foreach my $message (sort @{ $conflicts{$action}{$package} }) {
+                    warn "  * $message\n";
+                }
+            }
+        }
+        warn "All operations aborted.\n";
+        exit 1;
+    }
+    else {
+        if ($options->{simulate}) {
+            warn "WARNING: in simulation mode so not modifying filesystem.\n";
+            return;
+        }
+
+        $stow->process_tasks();
+    }
+}
+
+
+#===== SUBROUTINE ===========================================================
+# Name      : process_options()
+# Purpose   : parse command line options
+# Parameters: none
+# Returns   : (\%options, \@pkgs_to_unstow, \@pkgs_to_stow)
+# Throws    : a fatal error if a bad command line option is given
+# Comments  : checks @ARGV for valid package names
+#============================================================================
+sub process_options {
+    my %options        = ();
+    my @pkgs_to_unstow = ();
+    my @pkgs_to_stow   = ();
+    my $action = 'stow';
+
+    unshift @ARGV, get_config_file_options();
+    #$,="\n"; print @ARGV,"\n"; # for debugging rc file
+
+    Getopt::Long::config('no_ignore_case', 'bundling', 'permute');
+    GetOptions(
+        \%options,
+        'verbose|v:+', 'help|h', 'simulate|n|no',
+        'version|V', 'compat|p', 'dir|d=s', 'target|t=s',
+        'adopt', 'no-folding',
+
+        # clean and pre-compile any regex's at parse time
+        'ignore=s' =>
+        sub {
+            my $regex = $_[1];
+            push @{$options{ignore}}, qr($regex\z);
+        },
+
+        'override=s' =>
+        sub {
+            my $regex = $_[1];
+            push @{$options{override}}, qr(\A$regex);
+        },
+
+        'defer=s' =>
+        sub {
+            my $regex = $_[1];
+            push @{$options{defer}}, qr(\A$regex);
+        },
+
+        # a little craziness so we can do different actions on the same line:
+        # a -D, -S, or -R changes the action that will be performed on the
+        # package arguments that follow it.
+        'D|delete'  => sub { $action = 'unstow' },
+        'S|stow'    => sub { $action = 'stow'   },
+        'R|restow'  => sub { $action = 'restow' },
+
+        # Handler for non-option arguments
+        '<>' =>
+        sub {
+            if ($action eq 'restow') {
+                push @pkgs_to_unstow, $_[0];
+                push @pkgs_to_stow, $_[0];
+            }
+            elsif ($action eq 'unstow') {
+                push @pkgs_to_unstow, $_[0];
+            }
+            else {
+                push @pkgs_to_stow, $_[0];
+            }
+        },
+    ) or usage();
+
+    usage()   if $options{help};
+    version() if $options{version};
+
+    sanitize_path_options(\%options);
+    check_packages(\@pkgs_to_unstow, \@pkgs_to_stow);
+
+    return (\%options, \@pkgs_to_unstow, \@pkgs_to_stow);
+}
+
+sub sanitize_path_options {
+    my ($options) = @_;
+
+    if (exists $options->{dir}) {
+        $options->{dir}    =~ s/\A +//;
+        $options->{dir}    =~ s/ +\z//;
+    }
+    else {
+        $options->{dir} = exists $ENV{STOW_DIR} ? $ENV{STOW_DIR} : getcwd();
+    }
+
+    if (exists $options->{target}) {
+        $options->{target} =~ s/\A +//;
+        $options->{target} =~ s/ +\z//;
+    }
+    else {
+        $options->{target} = parent($options->{dir}) || '.';
+    }
+}
+
+sub check_packages {
+    my ($pkgs_to_stow, $pkgs_to_unstow) = @_;
+
+    if (not @$pkgs_to_stow and not @$pkgs_to_unstow) {
+        usage("No packages to stow or unstow");
+    }
+
+    # check package arguments
+    for my $package (@$pkgs_to_stow, @$pkgs_to_unstow) {
+        $package =~ s{/+$}{};    # delete trailing slashes
+        if ($package =~ m{/}) {
+            error("Slashes are not permitted in package names");
+        }
+    }
+}
+
+
+#===== SUBROUTINE ============================================================
+# Name      : get_config_file_options()
+# Purpose   : search for default settings in any .stowrc files
+# Parameters: none
+# Returns   : a list of default options
+# Throws    : no exceptions
+# Comments  : prepends the contents of '~/.stowrc' and '.stowrc' to the command
+#           : line so they get parsed just like normal arguments. (This was
+#           : hacked in so that Emil and I could set different preferences).
+#=============================================================================
+sub get_config_file_options {
+    my @defaults = ();
+    for my $file ("$ENV{HOME}/.stowrc", '.stowrc') {
+        if (-r $file) {
+            warn "Loading defaults from $file\n";
+            open my $FILE, '<', $file
+                or die "Could not open $file for reading\n";
+            while (my $line = <$FILE>){
+                chomp $line;
+                push @defaults, split " ", $line;
+            }
+            close $FILE or die "Could not close open file: $file\n";
+        }
+    }
+    return @defaults;
+}
+
+#===== SUBROUTINE ===========================================================
+# Name      : usage()
+# Purpose   : print program usage message and exit
+# Parameters: $msg => string to prepend to the usage message
+# Returns   : n/a
+# Throws    : n/a
+# Comments  : if 'msg' is given, then exit with non-zero status
+#============================================================================
+sub usage {
+    my ($msg) = @_;
+
+    if ($msg) {
+        print "$ProgramName: $msg\n\n";
+    }
+
+    print <<"EOT";
+$ProgramName (GNU Stow) version $Stow::VERSION
+
+SYNOPSIS:
+
+    $ProgramName [OPTION ...] [-D|-S|-R] PACKAGE ... [-D|-S|-R] PACKAGE ...
+
+OPTIONS:
+
+    -d DIR, --dir=DIR     Set stow dir to DIR (default is current dir)
+    -t DIR, --target=DIR  Set target to DIR (default is parent of stow dir)
+
+    -S, --stow            Stow the package names that follow this option
+    -D, --delete          Unstow the package names that follow this option
+    -R, --restow          Restow (like stow -D followed by stow -S)
+
+    --ignore=REGEX        Ignore files ending in this Perl regex
+    --defer=REGEX         Don't stow files beginning with this Perl regex
+                          if the file is already stowed to another package
+    --override=REGEX      Force stowing files beginning with this Perl regex
+                          if the file is already stowed to another package
+    --adopt               (Use with care!)  Import existing files into stow package
+                          from target.  Please read docs before using.
+    -p, --compat          Use legacy algorithm for unstowing
+
+    -n, --no, --simulate  Do not actually make any filesystem changes
+    -v, --verbose[=N]     Increase verbosity (levels are 0,1,2,3;
+                            -v or --verbose adds 1; --verbose=N sets level)
+    -V, --version         Show stow version number
+    -h, --help            Show this help
+
+Report bugs to: bug-stow\@gnu.org
+Stow home page: <http://www.gnu.org/software/stow/>
+General help using GNU software: <http://www.gnu.org/gethelp/>
+EOT
+    exit defined $msg ? 1 : 0;
+}
+
+sub version {
+    print "$ProgramName (GNU Stow) version $Stow::VERSION\n";
+    exit 0;
+}
+
+1; # This file is required by t/stow.t
+
+# Local variables:
+# mode: perl
+# cperl-indent-level: 4
+# end:
+# vim: ft=perl

.local/share/doc/stow/ChangeLog.OLD

@@ -0,0 +1,232 @@
+Thu Jan 31 2008  Kahlil Hodgson  <kal@grebo.cs.rmit.edu.au>
+
+	* stow.texi: Austin Wood and Chris Hoobin clean this up for version 2.
+
+	* texi2man: new script by Austin and Chris to generate a man page from the
+	texinfo file.
+
+
+Sun Nov 25 19:31:32 2007  Kahlil Hodgson <kahlil@internode.con.net>
+	* all: Version 2.0.1
+
+	* AUTHORS: added Kahlil Hodgson as a new author and current maintainer.
+
+	* stow.in: major rewrite to produce version 2.0.1 see NEWS for details
+	
+	* t/: added test suite and support code
+	
+	* configure.in: renamed to configure.ac as per autotools recommendation.
+
+	* configure.ac: 
+	Use AC_INT rather than obsolete AM_INTI_MAKEFILE usage.
+	Remove redundant VERSION and PACKAGE setttings
+	Remove redundant AC_ARG_PROGRAM
+	Use AM_INIT_AUTOMAKE([-Wall -Werror]) because we are pedantic.
+	Add AC_PREREQ([2.6.1])
+	
+	* Makefile.am, configure.ac: 
+	Use explicit rewrite in Makefile.am, rather than AC_CONFIG_FILES(stow.in),
+	as per autotools recommendation.
+
+	* Makefile.am: 
+	Add TESTS and TEST_ENVIRONMENT for files in t/
+	Use dist_man_MANS instead of EXTRA_DIST for man page 
+
+	* INSTALL: update to reflect autotools modernization.
+
+	* NEWS: update to describe cahnges in Version 2.0.1.
+
+	* README: update to point to the right websites and email addresses.
+	
+	* THANKS: 
+	Add Emil Mikulc who's ideas largely inspired Version 2 and 
+	and Geoffrey Giesemann who did some initial testing and found some
+	important bugs.
+
+	* TODO: remove tasks that where implemented in Version 2
+
+	* stow.texi: update documentation to reflect Version 2 changes.
+	
+	* stow.8: update to reflect Version 2 changes.
+
+Sat Jan 26 16:15:21 2002  Guillaume Morin  <gmorin@gnu.org>
+
+    * stow.in: if $ENV{'STOW_DIR'} is set, this becomes the default
+      Stow directory.
+
+Sun Jan 06 12:18:50 2002  Guillaume Morin  <gmorin@gnu.org>
+
+    * Makefile.am: use EXTRA_DIST to include manpage in distribution
+
+Wed Jan 02 21:33:41 2002  Guillaume Morin  <gmorin@gnu.org>
+
+    * stow.in: Stow now only warns the user if a subdirectory
+      is unreadable during unstowing.
+
+Wed Jan 02 20:58:05 2002  Guillaume Morin  <gmorin@gnu.org>
+
+    * stow.in: fixed JoinPaths so that subdirs called "0" are
+      correctly pushed. Thanks a lot to Gergely Nagy
+      <algernon@bonehunter.rulez.org> who patiently helped me to chase 
+      this bug.
+
+Sun Dec 30 21:58:25 2001  Guillaume Morin  <gmorin@gnu.org>
+
+    * stow.in: fixed a bug introduced by previous changes when
+      Target argument was relative. (thanks to Luca Filipozzi
+      <lfilipoz@debian.org> for pointing this out)
+	   
+Sun Dec 30 18:23:25 2001  Guillaume Morin  <gmorin@gnu.org>
+
+    * stow.in: now requires Perl 5. Use POSIX getcwd instead of broken
+      fastcwd. Fixed bug when CommonParent is /. Stow does not remove
+      initially empty directories anymore.
+	
+Sun Dec 30 18:07:51 2001  Guillaume Morin  <gmorin@gnu.org>
+
+    * configure.in: automake fixes (fp_ -> AC, +AC_INIT_AUTOMAKE)
+
+Fri Oct 11 22:09:45 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* stow.html, configure.in: Version 1.3.2.
+
+	* README, stow.texi: Correct the URL again.
+
+Fri Oct 11 18:20:42 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* configure.in: Version 1.3.1.
+
+	* stow.html: Update Stow manual URL.  Mention version 1.3.1.
+
+	* README: Update Stow URL.
+
+	* Makefile.am: stow-manual.html -> manual.html.
+
+	* stow.texi:
+	Add a reference to the Stow home page on the GNU web server.  Change
+	several occurrences of "which" to "that" for grammatical superiority.
+
+Wed Oct  9 00:34:07 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* Makefile.am:
+	Add maintainer-only rules for stow-manual.html and stow-manual.texi.
+
+Wed Oct  9 00:32:31 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* README: Refer to the new location for the Stow home page.
+
+	* stow.html: Make it right for the GNU web server.
+
+Tue Oct  8 21:54:09 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* stow.texi: Document --restow
+
+	* stow.in: Add --restow (-R) option
+
+	* configure.in: Add "perl4" to search for Perl binary.
+	Bump version number to 1.3.
+
+Mon Jun 24 23:23:03 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* stow.texi: Delete trailing whitespace.
+
+Fri Jun 21 19:44:26 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* Makefile.am:
+	Don't explicitly mention version.texi.  Automake now does it
+ 	automagically, by noticing the `@include version.texi' in
+ 	stow.texi.  Awesome.
+
+	* stow.texi:
+	Use @include instead of @input.  This is more Texinfoid, plus
+	allows Automake to automatically deduce the need for
+	version.texi.
+
+	* stow.in:
+	Elide trailing slashes from package names, then complain if
+	package names have slashes in them.
+
+Tue Jun 18 23:19:04 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* README: Call it "Gnu Stow".
+
+Tue Jun 18 22:15:45 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* configure.in:
+	Bump version number to 1.2.
+
+	Look for Perl under the names `perl' and `perl5'.  If not found,
+	print a warning.
+
+	* stow.texi:
+	Add a section about bootstrapping.  Add text about hacking Gnu
+	Make output.
+
+	* INSTALL:
+	Describe what happens when Perl isn't found during `configure'.
+
+Mon Jun 17 19:43:25 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* THANKS: Thank Fritz.
+
+Fri Jun 14 19:18:50 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* AUTHORS: Credit John Bazik and Gord Matzigkeit.
+
+	* stow.texi: Remove a "known bug" -- the pwd dependency is gone.
+
+	* stow.in:
+	Use fastcwd, from fastcwd.pl (which is GPL'd), to remove
+ 	dependency on an external pwd binary.  Suggested by Gord
+	Matzigkeit.
+
+	* stow.in: Add a missing comma.
+
+Thu Jun 13 21:52:10 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* stow.in:
+	Change three occurrences of `my' to `local' for Perl 4
+	compatibility.
+
+Thu Jun 13 18:07:37 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* configure.in: Bump version number to 1.1.
+
+	* Makefile.am:
+	Add `stow' to the list of clean targets.  Don't redirect output
+ 	directly into a make target.
+
+	* AUTHORS, README:
+	Use <bobg+stow@zanshin.com> as the contact address.
+
+	* TODO: New file.
+
+	* stow.in:
+	Refer to "Gnu Stow" in a few places.  Use <bobg+stow@zanshin.com>
+ 	as the contact address.  Handle long and short options.  Handle
+ 	`version' and `help' options.  Refer to "packages," not
+ 	"collections," for consistency with the manual.
+
+	* stow.texi:
+	Refer to "Gnu Stow" in a few places.  Use <bobg+stow@zanshin.com>
+ 	as the contact address.  Add sections on Reporting bugs and Known
+ 	bugs.  Create a master menu.  Minor rewording.  Remove the period
+ 	from a node name.
+
+	* TODO, THANKS: New files.
+
+Mon Jun 10 14:44:13 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* NEWS: Create NEWS file for release.  1.0 now ready.
+
+	* stow.texi: Big revisions in preparation for release.
+
+Sun Jun  9 15:47:19 1996  Bob Glickstein  <bobg@zoger.ipost.com>
+
+	* stow.in: Enhance argument parsing, losing Perl 4 support in the
+	process.
+	(later) Perl 4 support restored.
+
+Fri Jun  7 12:13:33 1996  Bob Glickstein  <bobg@hiro.zanshin.com>
+
+	* Created stow, formerly "depot."

.local/share/doc/stow/README

@@ -0,0 +1,53 @@
+README for GNU Stow
+===================
+
+This is GNU Stow, a symlink farm manager program which takes distinct
+packages of software and/or data located in separate directories on
+the filesystem, and makes them appear to be installed in the same
+place.  For example, /usr/local/bin could contain symlinks to files
+within /usr/local/stow/emacs/bin, /usr/local/stow/perl/bin etc., and
+likewise recursively for any other subdirectories such as .../share,
+.../man, and so on.
+
+This is particularly useful for keeping track of system-wide and
+per-user installations of software built from source, but can also
+facilitate a more controlled approach to management of configuration
+files in the user's home directory, especially when coupled with
+version control systems.
+
+Stow is implemented as a combination of a Perl script providing a CLI
+interface, and a backend Perl module which does most of the work.
+
+You can get the latest information about Stow from the home page:
+
+    http://www.gnu.org/software/stow/
+
+License
+-------
+
+Stow is free software, licensed under the GNU General Public License,
+which can be found in the file COPYING.
+
+Installation
+------------
+
+See INSTALL for installation instructions.
+
+Feedback
+--------
+
+Please do send comments, questions, and constructive criticism.  The
+mailing lists and any other communication channels are detailed on the
+above home page.
+
+Brief history
+-------------
+
+Stow was inspired by Carnegie Mellon's "Depot" program, but is
+substantially simpler.  Whereas Depot requires database files to keep
+things in sync, Stow stores no extra state between runs, so there's no
+danger (as there is in Depot) of mangling directories when file
+hierarchies don't match the database.  Also unlike Depot, Stow will
+never delete any files, directories, or links that appear in a Stow
+directory (e.g., /usr/local/stow/emacs), so it's always possible to
+rebuild the target tree (e.g., /usr/local).

.local/share/doc/stow/manual-split/Bootstrapping.html

@@ -0,0 +1,89 @@
+<html lang="en">
+<head>
+<title>Bootstrapping - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime" title="Compile-time vs Install-time">
+<link rel="next" href="Reporting-Bugs.html#Reporting-Bugs" title="Reporting Bugs">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Bootstrapping"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Reporting-Bugs.html#Reporting-Bugs">Reporting Bugs</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">Compile-time vs Install-time</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">13 Bootstrapping</h2>
+
+<p>Suppose you have a stow directory all set up and ready to go:
+<samp><span class="file">/usr/local/stow/perl</span></samp> contains the Perl installation,
+<samp><span class="file">/usr/local/stow/stow</span></samp> contains Stow itself, and perhaps you have
+other packages waiting to be stowed.  You'd like to be able to do this:
+
+<pre class="example">     cd /usr/local/stow
+     stow -vv *
+</pre>
+   <p class="noindent">but <samp><span class="command">stow</span></samp> is not yet in your <samp><span class="env">PATH</span></samp>.  Nor can you do this:
+
+<pre class="example">     cd /usr/local/stow
+     stow/bin/stow -vv *
+</pre>
+   <p class="noindent">because the &lsquo;<samp><span class="samp">#!</span></samp>&rsquo; line at the beginning of <samp><span class="command">stow</span></samp> tries to
+locate Perl (usually in <samp><span class="file">/usr/local/bin/perl</span></samp>), and that won't be
+found.  The solution you must use is:
+
+<pre class="example">     cd /usr/local/stow
+     perl/bin/perl stow/bin/stow -vv *
+</pre>
+   <!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Compile_002dtime-vs-Install_002dtime.html

@@ -0,0 +1,144 @@
+<html lang="en">
+<head>
+<title>Compile-time vs Install-time - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Resource-Files.html#Resource-Files" title="Resource Files">
+<link rel="next" href="Bootstrapping.html#Bootstrapping" title="Bootstrapping">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Compile-time-vs-Install-time"></a>
+<a name="Compile_002dtime-vs-Install_002dtime"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Bootstrapping.html#Bootstrapping">Bootstrapping</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Resource-Files.html#Resource-Files">Resource Files</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">12 Compile-time vs Install-time</h2>
+
+<p>Software whose installation is managed with Stow needs to be installed
+in one place (the package directory, e.g. <samp><span class="file">/usr/local/stow/perl</span></samp>)
+but needs to appear to run in another place (the target tree, e.g.,
+<samp><span class="file">/usr/local</span></samp>).  Why is this important?  What's wrong with Perl, for
+instance, looking for its files in <samp><span class="file">/usr/local/stow/perl</span></samp> instead
+of in <samp><span class="file">/usr/local</span></samp>?
+
+   <p>The answer is that there may be another package, e.g.,
+<samp><span class="file">/usr/local/stow/perl-extras</span></samp>, stowed under <samp><span class="file">/usr/local</span></samp>.  If
+Perl is configured to find its files in <samp><span class="file">/usr/local/stow/perl</span></samp>, it
+will never find the extra files in the &lsquo;<samp><span class="samp">perl-extras</span></samp>&rsquo; package, even
+though they're intended to be found by Perl.  On the other hand, if Perl
+looks for its files in <samp><span class="file">/usr/local</span></samp>, then it will find the
+intermingled Perl and &lsquo;<samp><span class="samp">perl-extras</span></samp>&rsquo; files.
+
+   <p>This means that when you compile a package, you must tell it the
+location of the run-time, or target tree; but when you install it, you
+must place it in the stow tree.
+
+<h3 class="section">12.1 Advice on changing compilation and installation parameters</h3>
+
+<p>Some software packages allow you to specify, at compile-time, separate
+locations for installation and for run-time.  Perl is one such package;
+see <a href="Perl-and-Perl-5-Modules.html#Perl-and-Perl-5-Modules">Perl and Perl 5 Modules</a>.  Others allow you to compile the
+package, then give a different destination in the &lsquo;<samp><span class="samp">make install</span></samp>&rsquo;
+step without causing the binaries or other files to get rebuilt.  Most
+GNU software falls into this category; Emacs is a notable exception. 
+See <a href="GNU-Emacs.html#GNU-Emacs">GNU Emacs</a>, and <a href="Other-FSF-Software.html#Other-FSF-Software">Other FSF Software</a>.
+
+   <p>Still other software packages cannot abide the idea of separate
+installation and run-time locations at all.  If you try to &lsquo;<samp><span class="samp">make
+install prefix=/usr/local/stow/</span><var>foo</var></samp>&rsquo;, then first the whole package
+will be recompiled to hardwire the <samp><span class="file">/usr/local/stow/</span><var>foo</var></samp>
+path.  With these packages, it is best to compile normally, then run
+&lsquo;<samp><span class="samp">make -n install</span></samp>&rsquo;, which should report all the steps needed to
+install the just-built software.  Place this output into a file, edit
+the commands in the file to remove recompilation steps and to reflect
+the Stow-based installation location, and execute the edited file as a
+shell script in place of &lsquo;<samp><span class="samp">make install</span></samp>&rsquo;.  Be sure to execute the
+script using the same shell that &lsquo;<samp><span class="samp">make install</span></samp>&rsquo; would have used.
+
+   <p>(If you use GNU Make and a shell [such as GNU bash] that understands
+<samp><span class="command">pushd</span></samp> and <samp><span class="command">popd</span></samp>, you can do the following:
+
+     <ol type=1 start=1>
+<li>Replace all lines matching &lsquo;<samp><span class="samp">make[</span><var>n</var><span class="samp">]: Entering directory
+</span><var>dir</var></samp>&rsquo; with &lsquo;<samp><span class="samp">pushd </span><var>dir</var></samp>&rsquo;. 
+<li>Replace all lines matching &lsquo;<samp><span class="samp">make[</span><var>n</var><span class="samp">]: Leaving directory
+</span><var>dir</var></samp>&rsquo; with &lsquo;<samp><span class="samp">popd</span></samp>&rsquo;. 
+<li>Delete all lines matching &lsquo;<samp><span class="samp">make[</span><var>n</var><span class="samp">]: Nothing to be done for
+</span><var>rule</var></samp>&rsquo;.
+        </ol>
+
+   <p>Then find other lines in the output containing <samp><span class="command">cd</span></samp> or <samp><span class="command">make</span></samp>
+commands and rewrite or delete them.  In particular, you should be able
+to delete sections of the script that resemble this:
+
+<pre class="example">     for i in <var>dir_1</var> <var>dir_2</var> <span class="roman">...</span>; do \
+       (cd $i; make <var>args</var> <span class="roman">...</span>) \
+     done
+</pre>
+   <p class="noindent">Note, that's &ldquo;should be able to,&rdquo; not &ldquo;can.&rdquo;  Be sure to modulate
+these guidelines with plenty of your own intelligence.
+
+   <p>The details of stowing some specific packages are described in the
+following sections.
+
+<ul class="menu">
+<li><a accesskey="1" href="GNU-Emacs.html#GNU-Emacs">GNU Emacs</a>
+<li><a accesskey="2" href="Other-FSF-Software.html#Other-FSF-Software">Other FSF Software</a>
+<li><a accesskey="3" href="Cygnus-Software.html#Cygnus-Software">Cygnus Software</a>
+<li><a accesskey="4" href="Perl-and-Perl-5-Modules.html#Perl-and-Perl-5-Modules">Perl and Perl 5 Modules</a>
+</ul>
+
+<!--  -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Conflicts.html

@@ -0,0 +1,100 @@
+<html lang="en">
+<head>
+<title>Conflicts - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Deleting-Packages.html#Deleting-Packages" title="Deleting Packages">
+<link rel="next" href="Mixing-Operations.html#Mixing-Operations" title="Mixing Operations">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Conflicts"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Mixing-Operations.html#Mixing-Operations">Mixing Operations</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Deleting-Packages.html#Deleting-Packages">Deleting Packages</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">7 Conflicts</h2>
+
+<p><a name="index-conflicts-31"></a>If, during installation, a file or symlink exists in the target tree and
+has the same name as something Stow needs to create, and if the
+existing name is not a folded tree that can be split open, then a
+<dfn>conflict</dfn> has arisen.  A conflict also occurs if a directory exists
+where Stow needs to place a symlink to a non-directory.  On the
+other hand, if the existing name is merely a symlink that already points
+where Stow needs it to, then no conflict has occurred.  (Thus it
+is harmless to install a package that has already been installed.)
+
+   <p>For complex packages, scanning the stow and target trees in tandem,
+and deciding whether to make directories or links, split-open or fold
+directories, can actually take a long time (a number of seconds). 
+Moreover, an accurate analysis of potential conflicts requires us to
+take into account all of these operations.
+
+   <p><a name="Deferred-Operation"></a>
+
+<h3 class="section">7.1 Deferred Operation</h3>
+
+<p><a name="index-deferred-operation-32"></a>
+Since version 2.0, Stow now adopts a two-phase algorithm, first
+scanning for any potential conflicts before any stowing or unstowing
+operations are performed.  If any conflicts are found, they are
+displayed and then Stow terminates without making any modifications to
+the filesystem.  This means that there is much less risk of a package
+being partially stowed or unstowed due to conflicts.
+
+   <p>Prior to version 2.0, if a conflict was discovered, the stow or unstow
+operation could be aborted mid-flow, leaving the target tree in an
+inconsistent state.
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Cygnus-Software.html

@@ -0,0 +1,95 @@
+<html lang="en">
+<head>
+<title>Cygnus Software - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime" title="Compile-time vs Install-time">
+<link rel="prev" href="Other-FSF-Software.html#Other-FSF-Software" title="Other FSF Software">
+<link rel="next" href="Perl-and-Perl-5-Modules.html#Perl-and-Perl-5-Modules" title="Perl and Perl 5 Modules">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Cygnus-Software"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Perl-and-Perl-5-Modules.html#Perl-and-Perl-5-Modules">Perl and Perl 5 Modules</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Other-FSF-Software.html#Other-FSF-Software">Other FSF Software</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">Compile-time vs Install-time</a>
+<hr>
+</div>
+
+<h3 class="section">12.4 Cygnus Software</h3>
+
+<p>Cygnus is a commercial supplier and supporter of GNU software.  It has
+also written several of its own packages, released under the terms of
+the GNU General Public License; and it has taken over the maintenance of
+other packages.  Among the packages released by Cygnus are &lsquo;<samp><span class="samp">gdb</span></samp>&rsquo;,
+&lsquo;<samp><span class="samp">gnats</span></samp>&rsquo;, and &lsquo;<samp><span class="samp">dejagnu</span></samp>&rsquo;.
+
+   <p>Cygnus packages have the peculiarity that each one unpacks into a
+directory tree with a generic top-level Makefile, which is set up to
+compile <em>all</em> of Cygnus' packages, any number of which may reside
+under the top-level directory.  In other words, even if you're only
+building &lsquo;<samp><span class="samp">gnats</span></samp>&rsquo;, the top-level Makefile will look for, and try to
+build, <samp><span class="file">gdb</span></samp> and <samp><span class="file">dejagnu</span></samp> subdirectories, among many others.
+
+   <p>The result is that if you try &lsquo;<samp><span class="samp">make -n install
+prefix=/usr/local/stow/</span><var>package</var></samp>&rsquo; at the top level of a Cygnus
+package, you'll get a bewildering amount of output.  It will then be
+very difficult to visually scan the output to see whether the install
+will proceed correctly.  Unfortunately, it's not always clear how to
+invoke an install from the subdirectory of interest.
+
+   <p>In cases like this, the best approach is to run your &lsquo;<samp><span class="samp">make install
+prefix=...</span></samp>&rsquo;, but be ready to interrupt it if you detect that it
+is recompiling files.  Usually it will work just fine; otherwise,
+install manually.
+
+<!--  -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Deferred-Operation.html

@@ -0,0 +1 @@
+<meta http-equiv="refresh" content="0; url=Conflicts.html#Deferred%20Operation">

.local/share/doc/stow/manual-split/Deleting-Packages.html

@@ -0,0 +1,112 @@
+<html lang="en">
+<head>
+<title>Deleting Packages - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Installing-Packages.html#Installing-Packages" title="Installing Packages">
+<link rel="next" href="Conflicts.html#Conflicts" title="Conflicts">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Deleting-Packages"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Conflicts.html#Conflicts">Conflicts</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Installing-Packages.html#Installing-Packages">Installing Packages</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">6 Deleting Packages</h2>
+
+<p><a name="index-deletion-28"></a>When the <samp><span class="option">-D</span></samp> option is given, the action of Stow is to
+delete a package from the target tree.  Note that Stow will not
+delete anything it doesn't &ldquo;own&rdquo;.  Deleting a package does <em>not</em>
+mean removing it from the stow directory or discarding the package
+tree.
+
+   <p>To delete a package, Stow recursively scans the target tree, skipping over any
+directory that is not included in the installation image.<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>
+For example, if the target directory is <samp><span class="file">/usr/local</span></samp> and the
+installation image for the package being deleted has only a <samp><span class="file">bin</span></samp>
+directory and a <samp><span class="file">man</span></samp> directory at the top level, then we only scan
+<samp><span class="file">/usr/local/bin</span></samp> and  <samp><span class="file">/usr/local/bin/man</span></samp>, and not
+<samp><span class="file">/usr/local/lib</span></samp> or <samp><span class="file">/usr/local/share</span></samp>, or for that matter
+<samp><span class="file">/usr/local/stow</span></samp>.  Any symlink it finds that points into the package
+being deleted is removed.  Any directory that contained only symlinks to the
+package being deleted is removed.
+
+   <p><a name="tree-refolding"></a>
+
+<h3 class="section">6.1 Refolding &ldquo;foldable&rdquo; trees.</h3>
+
+<p><a name="index-refolding-trees-29"></a><a name="index-tree-refolding-30"></a>
+After removing symlinks and empty subdirectories, any directory that
+contains only symlinks to a single other package is considered to be a
+previously &ldquo;folded&rdquo; tree that was &ldquo;split open.&rdquo;  Stow will refold
+the tree by removing the symlinks to the surviving package, removing
+the directory, then linking the directory back to the surviving
+package.  However, this behaviour can be prevented via the
+<samp><span class="option">--no-folding</span></samp> option; see <a href="Invoking-Stow.html#Invoking-Stow">Invoking Stow</a>.
+
+<!-- =========================================================================== -->
+   <div class="footnote">
+<hr>
+<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> This
+approach was introduced in version 2 of GNU Stow.  Previously, the whole
+target tree was scanned and stow directories were explicitly omitted.  This
+became problematic when dealing with very large installations.  The only
+situation where this is useful is if you accidentally delete a directory in
+the package tree, leaving you with a whole bunch of dangling links.  Note that
+you can enable the old approach with the <samp><span class="option">-p</span></samp> option.  Alternatively, you can
+use the <samp><span class="option">--badlinks</span></samp> option get stow to search for dangling links in your target tree and remove the offenders manually.</p>
+
+   <hr></div>
+
+   </body></html>
+

.local/share/doc/stow/manual-split/GNU-Emacs.html

@@ -0,0 +1,97 @@
+<html lang="en">
+<head>
+<title>GNU Emacs - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime" title="Compile-time vs Install-time">
+<link rel="prev" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime" title="Compile-time vs Install-time">
+<link rel="next" href="Other-FSF-Software.html#Other-FSF-Software" title="Other FSF Software">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="GNU-Emacs"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Other-FSF-Software.html#Other-FSF-Software">Other FSF Software</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">Compile-time vs Install-time</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">Compile-time vs Install-time</a>
+<hr>
+</div>
+
+<h3 class="section">12.2 GNU Emacs</h3>
+
+<p>Although the Free Software Foundation has many enlightened practices
+regarding Makefiles and software installation (see see <a href="Other-FSF-Software.html#Other-FSF-Software">Other FSF Software</a>), Emacs, its flagship program, doesn't quite follow the
+rules.  In particular, most GNU software allows you to write:
+
+<pre class="example">     make
+     make install prefix=/usr/local/stow/<var>package</var>
+</pre>
+   <p class="noindent">If you try this with Emacs, then the new value for <var>prefix</var> in the
+&lsquo;<samp><span class="samp">make install</span></samp>&rsquo; step will cause some files to get recompiled with
+the new value of <var>prefix</var> wired into them.  In Emacs 19.23 and
+later,<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>
+the way to work around this problem is:
+
+<pre class="example">     make
+     make install-arch-dep install-arch-indep prefix=/usr/local/stow/emacs
+</pre>
+   <p>In 19.22 and some prior versions of Emacs, the workaround was:
+
+<pre class="example">     make
+     make do-install prefix=/usr/local/stow/emacs
+</pre>
+   <!--  -->
+   <div class="footnote">
+<hr>
+<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> As I write this, the current version of Emacs is 19.31.</p>
+
+   <hr></div>
+
+   </body></html>
+

.local/share/doc/stow/manual-split/GNU-General-Public-License.html

@@ -0,0 +1,411 @@
+<html lang="en">
+<head>
+<title>GNU General Public License - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Known-Bugs.html#Known-Bugs" title="Known Bugs">
+<link rel="next" href="Index.html#Index" title="Index">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="GNU-General-Public-License"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Index.html#Index">Index</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Known-Bugs.html#Known-Bugs">Known Bugs</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="unnumbered">GNU General Public License</h2>
+
+<div align="center">Version 2, June 1991</div>
+
+<pre class="display">     Copyright &copy; 1989, 1991 Free Software Foundation, Inc.
+     675 Mass Ave, Cambridge, MA 02139, USA
+     
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+</pre>
+   <h3 class="unnumberedsec">Preamble</h3>
+
+<p>The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software&mdash;to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+   <p>When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+   <p>To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights. 
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+   <p>For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+   <p>We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+   <p>Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+   <p>Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+   <p>The precise terms and conditions for copying, distribution and
+modification follow.
+
+     <ol type=1 start=0>
+<li>This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The &ldquo;Program&rdquo;, below,
+refers to any such program or work, and a &ldquo;work based on the Program&rdquo;
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term &ldquo;modification&rdquo;.)  Each licensee is addressed as &ldquo;you&rdquo;.
+
+     <p>Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program). 
+Whether that is true depends on what the Program does.
+
+     <li>You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+     <p>You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+     <li>You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+          <ol type=a start=1>
+<li>You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+          <li>You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+          <li>If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License.  (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+          </ol>
+
+     <p>These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+     <p>Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+     <p>In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+     <li>You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+          <ol type=a start=1>
+<li>Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+          <li>Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+          <li>Accompany it with the information you received as to the offer
+to distribute corresponding source code.  (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+          </ol>
+
+     <p>The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+     <p>If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+     <li>You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License. 
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+     <li>You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+     <li>Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein. 
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+     <li>If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+     <p>If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+     <p>It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+     <p>This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+     <li>If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+     <li>The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+     <p>Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and &ldquo;any
+later version&rdquo;, you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+     <li>If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+     <li>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM &ldquo;AS IS&rdquo; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+     <li>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+        </ol>
+
+<h3 class="unnumberedsec">How to Apply These Terms to Your New Programs</h3>
+
+<p>If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+   <p>To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the &ldquo;copyright&rdquo; line and a pointer to where the full notice is found.
+
+<pre class="smallexample">     <var>one line to give the program's name and an idea of what it does.</var>
+     Copyright (C) 19<var>yy</var>  <var>name of author</var>
+     
+     This program is free software; you can redistribute it and/or
+     modify it under the terms of the GNU General Public License
+     as published by the Free Software Foundation; either version 2
+     of the License, or (at your option) any later version.
+     
+     This program is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+     GNU General Public License for more details.
+     
+     You should have received a copy of the GNU General Public License
+     along with this program; if not, write to the Free Software
+     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+</pre>
+   <p>Also add information on how to contact you by electronic and paper mail.
+
+   <p>If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+<pre class="smallexample">     Gnomovision version 69, Copyright (C) 19<var>yy</var> <var>name of author</var>
+     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+     type `show w'.  This is free software, and you are welcome
+     to redistribute it under certain conditions; type `show c'
+     for details.
+</pre>
+   <p>The hypothetical commands &lsquo;<samp><span class="samp">show w</span></samp>&rsquo; and &lsquo;<samp><span class="samp">show c</span></samp>&rsquo; should show
+the appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than &lsquo;<samp><span class="samp">show w</span></samp>&rsquo; and
+&lsquo;<samp><span class="samp">show c</span></samp>&rsquo;; they could even be mouse-clicks or menu items&mdash;whatever
+suits your program.
+
+   <p>You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a &ldquo;copyright disclaimer&rdquo; for the program, if
+necessary.  Here is a sample; alter the names:
+
+<pre class="smallexample">     Yoyodyne, Inc., hereby disclaims all copyright
+     interest in the program `Gnomovision'
+     (which makes passes at compilers) written
+     by James Hacker.
+     
+     <var>signature of Ty Coon</var>, 1 April 1989
+     Ty Coon, President of Vice
+</pre>
+   <p>This General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications
+with the library.  If this is what you want to do, use the GNU Library
+General Public License instead of this License.
+
+   </body></html>
+

.local/share/doc/stow/manual-split/Ignore-Lists.html

@@ -0,0 +1,77 @@
+<html lang="en">
+<head>
+<title>Ignore Lists - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Invoking-Stow.html#Invoking-Stow" title="Invoking Stow">
+<link rel="next" href="Installing-Packages.html#Installing-Packages" title="Installing Packages">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Ignore-Lists"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Installing-Packages.html#Installing-Packages">Installing Packages</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Invoking-Stow.html#Invoking-Stow">Invoking Stow</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">4 Ignore Lists</h2>
+
+<p><a name="index-ignore-lists-14"></a><a name="index-ignoring-files-and-directories-15"></a>
+
+<ul class="menu">
+<li><a accesskey="1" href="Motivation-For-Ignore-Lists.html#Motivation-For-Ignore-Lists">Motivation For Ignore Lists</a>
+<li><a accesskey="2" href="Types-And-Syntax-Of-Ignore-Lists.html#Types-And-Syntax-Of-Ignore-Lists">Types And Syntax Of Ignore Lists</a>
+<li><a accesskey="3" href="Justification-For-Yet-Another-Set-Of-Ignore-Files.html#Justification-For-Yet-Another-Set-Of-Ignore-Files">Justification For Yet Another Set Of Ignore Files</a>
+</ul>
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Installing-Packages.html

@@ -0,0 +1,156 @@
+<html lang="en">
+<head>
+<title>Installing Packages - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Ignore-Lists.html#Ignore-Lists" title="Ignore Lists">
+<link rel="next" href="Deleting-Packages.html#Deleting-Packages" title="Deleting Packages">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Installing-Packages"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Deleting-Packages.html#Deleting-Packages">Deleting Packages</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Ignore-Lists.html#Ignore-Lists">Ignore Lists</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">5 Installing Packages</h2>
+
+<p><a name="index-installation-17"></a>The default action of Stow is to install a package.  This means creating
+symlinks in the target tree that point into the package tree.  Stow
+attempts to do this with as few symlinks as possible; in other words, if
+Stow can create a single symlink that points to an entire subtree within
+the package tree, it will choose to do that rather than create a
+directory in the target tree and populate it with symlinks.
+
+   <p><a name="tree-folding"></a>
+
+<h3 class="section">5.1 Tree folding</h3>
+
+<p><a name="index-tree-folding-18"></a><a name="index-directory-folding-19"></a><a name="index-folding-trees-20"></a>For example, suppose that no packages have yet been installed in
+<samp><span class="file">/usr/local</span></samp>; it's completely empty (except for the <samp><span class="file">stow</span></samp>
+subdirectory, of course).  Now suppose the Perl package is installed. 
+Recall that it includes the following directories in its installation
+image:  <samp><span class="file">bin</span></samp>; <samp><span class="file">info</span></samp>; <samp><span class="file">lib/perl</span></samp>; <samp><span class="file">man/man1</span></samp>. 
+Rather than creating the directory <samp><span class="file">/usr/local/bin</span></samp> and populating
+it with symlinks to <samp><span class="file">../stow/perl/bin/perl</span></samp> and
+<samp><span class="file">../stow/perl/bin/a2p</span></samp> (and so on), Stow will create a
+single symlink, <samp><span class="file">/usr/local/bin</span></samp>, which points to
+<samp><span class="file">stow/perl/bin</span></samp>.  In this way, it still works to refer to
+<samp><span class="file">/usr/local/bin/perl</span></samp> and <samp><span class="file">/usr/local/bin/a2p</span></samp>, and fewer
+symlinks have been created.  This is called <dfn>tree folding</dfn>, since an
+entire subtree is &ldquo;folded&rdquo; into a single symlink.
+
+   <p>To complete this example, Stow will also create the symlink
+<samp><span class="file">/usr/local/info</span></samp> pointing to <samp><span class="file">stow/perl/info</span></samp>; the symlink
+<samp><span class="file">/usr/local/lib</span></samp> pointing to <samp><span class="file">stow/perl/lib</span></samp>; and the symlink
+<samp><span class="file">/usr/local/man</span></samp> pointing to <samp><span class="file">stow/perl/man</span></samp>.
+
+   <p>Now suppose that instead of installing the Perl package into an empty
+target tree, the target tree is not empty to begin with.  Instead, it
+contains several files and directories installed under a different
+system-administration philosophy.  In particular, <samp><span class="file">/usr/local/bin</span></samp>
+already exists and is a directory, as are <samp><span class="file">/usr/local/lib</span></samp> and
+<samp><span class="file">/usr/local/man/man1</span></samp>.  In this case, Stow will descend into
+<samp><span class="file">/usr/local/bin</span></samp> and create symlinks to
+<samp><span class="file">../stow/perl/bin/perl</span></samp> and <samp><span class="file">../stow/perl/bin/a2p</span></samp> (etc.),
+and it will descend into <samp><span class="file">/usr/local/lib</span></samp> and create the
+tree-folding symlink <samp><span class="file">perl</span></samp> pointing to
+<samp><span class="file">../stow/perl/lib/perl</span></samp>, and so on.  As a rule, Stow only
+descends as far as necessary into the target tree when it can create a
+tree-folding symlink.  However, this behaviour can be changed via
+the <samp><span class="option">--no-folding</span></samp> option; see <a href="Invoking-Stow.html#Invoking-Stow">Invoking Stow</a>.
+
+   <p><a name="Tree-unfolding"></a>
+
+<h3 class="section">5.2 Tree unfolding</h3>
+
+<p><a name="index-splitting-open-folded-trees-21"></a><a name="index-unfolding-trees-22"></a><a name="index-tree-unfolding-23"></a><a name="index-tree-unsplitting-24"></a>The time often comes when a tree-folding symlink has to be undone
+because another package uses one or more of the folded subdirectories in
+its installation image.  This operation is called <dfn>splitting open</dfn> or
+<dfn>unfolding</dfn> a folded tree.  It involves removing the original symlink from
+the target tree, creating a true directory in its place, and then populating the
+new directory with symlinks to the newly-installed package <em>and</em> to
+the old package that used the old symlink.  For example, suppose that
+after installing Perl into an empty <samp><span class="file">/usr/local</span></samp>, we wish to
+install Emacs.  Emacs's installation image includes a <samp><span class="file">bin</span></samp>
+directory containing the <samp><span class="file">emacs</span></samp> and <samp><span class="file">etags</span></samp> executables,
+among others.  Stow must make these files appear to be installed
+in <samp><span class="file">/usr/local/bin</span></samp>, but presently <samp><span class="file">/usr/local/bin</span></samp> is a
+symlink to <samp><span class="file">stow/perl/bin</span></samp>.  Stow therefore takes the
+following steps:  the symlink <samp><span class="file">/usr/local/bin</span></samp> is deleted; the
+directory <samp><span class="file">/usr/local/bin</span></samp> is created; links are made from
+<samp><span class="file">/usr/local/bin</span></samp> to <samp><span class="file">../stow/emacs/bin/emacs</span></samp> and
+<samp><span class="file">../stow/emacs/bin/etags</span></samp>; and links are made from
+<samp><span class="file">/usr/local/bin</span></samp> to <samp><span class="file">../stow/perl/bin/perl</span></samp> and
+<samp><span class="file">../stow/perl/bin/a2p</span></samp>.
+
+<h3 class="section">5.3 Ownership</h3>
+
+<p><a name="index-ownership-25"></a>When splitting open a folded tree, Stow makes sure that the
+symlink it is about to remove points inside a valid package in the
+current stow directory.  <em>Stow will never delete anything
+that it doesn't own</em>.  Stow &ldquo;owns&rdquo; everything living in the
+target tree that points into a package in the stow directory.  Anything
+Stow owns, it can recompute if lost: symlinks that point into a package in
+the stow directory, or directories that only contain symlinks that stow
+&ldquo;owns&rdquo;.   Note that by this definition, Stow doesn't &ldquo;own&rdquo; anything
+<em>in</em> the stow directory or in any of the packages.
+
+<h3 class="section">5.4 Conflicts during installation</h3>
+
+<p><a name="index-conflicts-26"></a><a name="index-installation-conflicts-27"></a>If Stow needs to create a directory or a symlink in the target
+tree and it cannot because that name is already in use and is not owned
+by Stow, then a <dfn>conflict</dfn> has arisen.  See <a href="Conflicts.html#Conflicts">Conflicts</a>.
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Introduction.html

@@ -0,0 +1,119 @@
+<html lang="en">
+<head>
+<title>Introduction - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="index.html#Top" title="Top">
+<link rel="next" href="Terminology.html#Terminology" title="Terminology">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Introduction"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Terminology.html#Terminology">Terminology</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="index.html#Top">Top</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">1 Introduction</h2>
+
+<p>Stow is a tool for managing the installation of multiple software
+packages in the same run-time directory tree.  One historical difficulty
+of this task has been the need to administer, upgrade, install, and
+remove files in independent packages without confusing them with other
+files sharing the same file system space.  For instance, it is common to
+install Perl and Emacs in <samp><span class="file">/usr/local</span></samp>.  When one does so, one
+winds up with the following files<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> in <samp><span class="file">/usr/local/man/man1</span></samp>:
+
+<pre class="example">     a2p.1
+     ctags.1
+     emacs.1
+     etags.1
+     h2ph.1
+     perl.1
+     s2p.1
+</pre>
+   <p class="noindent">Now suppose it's time to uninstall Perl.  Which man pages
+get removed?  Obviously <samp><span class="file">perl.1</span></samp> is one of them, but it should not
+be the administrator's responsibility to memorize the ownership of
+individual files by separate packages.
+
+   <p>The approach used by Stow is to install each package into its own
+tree, then use symbolic links to make it appear as though the files are
+installed in the common tree.  Administration can be performed in the
+package's private tree in isolation from clutter from other packages. 
+Stow can then be used to update the symbolic links.  The structure
+of each private tree should reflect the desired structure in the common
+tree; i.e. (in the typical case) there should be a <samp><span class="file">bin</span></samp> directory
+containing executables, a <samp><span class="file">man/man1</span></samp> directory containing section 1
+man pages, and so on.
+
+   <p>Stow was inspired by Carnegie Mellon's Depot program, but is
+substantially simpler and safer.  Whereas Depot required database files
+to keep things in sync, Stow stores no extra state between runs, so
+there's no danger (as there was in Depot) of mangling directories when
+file hierarchies don't match the database.  Also unlike Depot, Stow will
+never delete any files, directories, or links that appear in a Stow
+directory (e.g., <samp><span class="file">/usr/local/stow/emacs</span></samp>), so it's always possible
+to rebuild the target tree (e.g., <samp><span class="file">/usr/local</span></samp>).
+
+   <p>For information about the latest version of Stow, you can refer to
+<a href="http://www.gnu.org/software/stow/">http://www.gnu.org/software/stow/</a>.
+
+<!-- =========================================================================== -->
+   <div class="footnote">
+<hr>
+<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> As of Perl 4.036 and Emacs
+19.22.</p>
+
+   <hr></div>
+
+   </body></html>
+

.local/share/doc/stow/manual-split/Invoking-Stow.html

@@ -0,0 +1,206 @@
+<html lang="en">
+<head>
+<title>Invoking Stow - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Terminology.html#Terminology" title="Terminology">
+<link rel="next" href="Ignore-Lists.html#Ignore-Lists" title="Ignore Lists">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Invoking-Stow"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Ignore-Lists.html#Ignore-Lists">Ignore Lists</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Terminology.html#Terminology">Terminology</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">3 Invoking Stow</h2>
+
+<p>The syntax of the <samp><span class="command">stow</span></samp> command is:
+
+<pre class="example">     stow [<var>options</var>] [<var>action flag</var>] <var>package <small class="dots">...</small></var>
+</pre>
+   <p class="noindent">Each <var>package</var> is the name of a package (e.g., &lsquo;<samp><span class="samp">perl</span></samp>&rsquo;) in the stow
+directory that we wish to install into (or delete from) the target directory. 
+The default action is to install the given packages, although alternate actions
+may be specified by preceding the package name(s) with an <var>action flag</var>.
+
+<p class="noindent">The following options are supported:
+
+     <dl>
+<dt>&lsquo;<samp><span class="samp">-d </span><var>dir</var></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--dir=</span><var>dir</var></samp>&rsquo;<dd>Set the stow directory to <var>dir</var>.  Defaults to the value of the environment
+variable <samp><span class="env">STOW_DIR</span></samp> if set, or the current directory otherwise.
+
+     <br><dt>&lsquo;<samp><span class="samp">-t </span><var>dir</var></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--target=</span><var>dir</var></samp>&rsquo;<dd>Set the target directory to <var>dir</var> instead of the parent of the stow
+directory.  Defaults to the parent of the stow directory, so it is typical to
+execute <samp><span class="command">stow</span></samp> from the directory <samp><span class="file">/usr/local/stow</span></samp>.
+
+     <br><dt>&lsquo;<samp><span class="samp">--ignore=</span><var>regexp</var></samp>&rsquo;<dd>This (repeatable) option lets you suppress acting on files that match the
+given perl regular expression.  For example, using the options
+
+     <pre class="example">          --ignore='*.orig' --ignore='*.dist'
+</pre>
+     <p class="noindent">will cause stow to ignore files ending in <samp><span class="file">.orig</span></samp> or <samp><span class="file">.dist</span></samp>.
+
+     <p>Note that the regular expression is anchored to the end of the filename,
+because this is what you will want to do most of the time.
+
+     <p>Also note that by default Stow automatically ignores a &ldquo;sensible&rdquo;
+built-in list of files and directories such as <samp><span class="file">CVS</span></samp>, editor
+backup files, and so on.  See <a href="Ignore-Lists.html#Ignore-Lists">Ignore Lists</a>, for more details.
+
+     <br><dt>&lsquo;<samp><span class="samp">--defer=</span><var>regexp</var></samp>&rsquo;<dd>This (repeatable) option avoids stowing a file matching the given
+regular expression, if that file is already stowed by another package. 
+This is effectively the opposite of <samp><span class="option">--override</span></samp>.
+
+     <p>(N.B. the name <samp><span class="option">--defer</span></samp> was chosen in the sense that the package
+currently being stowed is treated with lower precedence than any
+already installed package, not in the sense that the operation is
+being postponed to be run at a later point in time; do not confuse
+this nomenclature with the wording used in <a href="Deferred-Operation.html#Deferred-Operation">Deferred Operation</a>.)
+
+     <p>For example, the following options
+
+     <pre class="example">          --defer=man --defer=info
+</pre>
+     <p class="noindent">will cause stow to skip over pre-existing man and info pages.
+
+     <p>Equivalently, you could use &lsquo;<samp><span class="samp">--defer='man|info'</span></samp>&rsquo; since the
+argument is just a Perl regex.
+
+     <p>Note that the regular expression is anchored to the beginning of the path
+relative to the target directory, because this is what you will want to do most
+of the time.
+
+     <br><dt>&lsquo;<samp><span class="samp">--override=</span><var>regexp</var></samp>&rsquo;<dd>This (repeatable) option forces any file matching the regular expression to be
+stowed, even if the file is already stowed to another package. For example,
+the following options
+
+     <pre class="example">          --override=man --override=info
+</pre>
+     <p class="noindent">will permit stow to overwrite links that point to pre-existing man and info
+pages that are owned by stow and would otherwise cause a conflict.
+
+     <p>The regular expression is anchored to the beginning of the path relative to
+the target directory, because this is what you will want to do most of the time.
+
+     <br><dt>&lsquo;<samp><span class="samp">--no-folding</span></samp>&rsquo;<dd>
+This disables any further <a href="tree-folding.html#tree-folding">tree folding</a> or <a href="tree-refolding.html#tree-refolding">tree refolding</a>. 
+If a new subdirectory is encountered whilst stowing a new package, the
+subdirectory is created within the target, and its contents are
+symlinked, rather than just creating a symlink for the directory.  If
+removal of symlinks whilst unstowing a package causes a subtree to be
+foldable (i.e. only containing symlinks to a single package), that
+subtree will not be removed and replaced with a symlink.
+
+     <p><a name="index-adopting-existing-files-10"></a><br><dt>&lsquo;<samp><span class="samp">--adopt</span></samp>&rsquo;<dd><strong>Warning!</strong> This behaviour is specifically intended to alter the
+contents of your stow directory.  If you do not want that, this option
+is not for you.
+
+     <p>When stowing, if a target is encountered which already exists but is a
+plain file (and hence not owned by any existing stow package), then
+normally Stow will register this as a conflict and refuse to proceed. 
+This option changes that behaviour so that the file is moved to the
+same relative place within the package's installation image within the
+stow directory, and then stowing proceeds as before.  So effectively,
+the file becomes adopted by the stow package, without its contents
+changing.
+
+     <p>This is particularly useful when the stow package is under the control
+of a version control system, because it allows files in the target
+tree, with potentially different contents to the equivalent versions
+in the stow package's installation image, to be adopted into the
+package, then compared by running something like &lsquo;<samp><span class="samp">git diff ...</span></samp>&rsquo;
+inside the stow package, and finally either kept (e.g. via &lsquo;<samp><span class="samp">git
+commit ...</span></samp>&rsquo;) or discarded (&lsquo;<samp><span class="samp">git checkout HEAD ...</span></samp>&rsquo;).
+
+     <p><a name="index-dry-run-11"></a><a name="index-simulated-run-12"></a><br><dt>&lsquo;<samp><span class="samp">-n</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--no</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--simulate</span></samp>&rsquo;<dd>Do not perform any operations that modify the file system; in combination with
+<samp><span class="option">-v</span></samp> can be used to merely show what would happen.
+
+     <p><a name="index-verbosity-levels-13"></a><br><dt>&lsquo;<samp><span class="samp">-v</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--verbose[=</span><var>n</var><span class="samp">]</span></samp>&rsquo;<dd>Send verbose output to standard error describing what Stow is
+doing.  Verbosity levels are 0, 1, 2, and 3; 0 is the default.  Using
+<samp><span class="option">-v</span></samp> or <samp><span class="option">--verbose</span></samp> increases the verbosity by one; using
+&lsquo;<samp><span class="samp">--verbose=</span><var>n</var></samp>&rsquo; sets it to <var>n</var>.
+
+     <br><dt>&lsquo;<samp><span class="samp">-p</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--compat</span></samp>&rsquo;<dd>Scan the whole target tree when unstowing.  By default, only
+directories specified in the <dfn>installation image</dfn> are scanned
+during an unstow operation.  Scanning the whole tree can be
+prohibitive if your target tree is very large.  This option restores
+the legacy behaviour; however, the <samp><span class="option">--badlinks</span></samp> option to the
+<samp><span class="command">chkstow</span></samp> utility may be a better way of ensuring that your
+installation does not have any dangling symlinks (see <a href="Target-Maintenance.html#Target-Maintenance">Target Maintenance</a>).
+
+     <br><dt>&lsquo;<samp><span class="samp">-V</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--version</span></samp>&rsquo;<dd>Show Stow version number, and exit.
+
+     <br><dt>&lsquo;<samp><span class="samp">-h</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--help</span></samp>&rsquo;<dd>Show Stow command syntax, and exit. 
+</dl>
+
+   <p>The following <var>action flags</var> are supported:
+
+     <dl>
+<dt>&lsquo;<samp><span class="samp">-D</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--delete</span></samp>&rsquo;<dd>Delete (unstow) the package name(s) that follow this option from the <dfn>target
+directory</dfn>. This option may be repeated any number of times.
+
+     <br><dt>&lsquo;<samp><span class="samp">-R</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--restow</span></samp>&rsquo;<dd>Restow (first unstow, then stow again) the package names that follow this
+option.  This is useful for pruning obsolete symlinks from the target tree
+after updating the software in a package. This option may be repeated any
+number of times.
+
+     <br><dt>&lsquo;<samp><span class="samp">-S</span></samp>&rsquo;<br><dt>&lsquo;<samp><span class="samp">--stow</span></samp>&rsquo;<dd>explictly stow the package name(s) that follow this option.  May be
+omitted if you are not using the <samp><span class="option">-D</span></samp> or <samp><span class="option">-R</span></samp> options in the
+same invocation.  See <a href="Mixing-Operations.html#Mixing-Operations">Mixing Operations</a>, for details of when you
+might like to use this feature. This option may be repeated any number
+of times. 
+</dl>
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Justification-For-Yet-Another-Set-Of-Ignore-Files.html

@@ -0,0 +1,93 @@
+<html lang="en">
+<head>
+<title>Justification For Yet Another Set Of Ignore Files - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Ignore-Lists.html#Ignore-Lists" title="Ignore Lists">
+<link rel="prev" href="Types-And-Syntax-Of-Ignore-Lists.html#Types-And-Syntax-Of-Ignore-Lists" title="Types And Syntax Of Ignore Lists">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Justification-For-Yet-Another-Set-Of-Ignore-Files"></a>
+<p>
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Types-And-Syntax-Of-Ignore-Lists.html#Types-And-Syntax-Of-Ignore-Lists">Types And Syntax Of Ignore Lists</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Ignore-Lists.html#Ignore-Lists">Ignore Lists</a>
+<hr>
+</div>
+
+<h3 class="section">4.3 Justification For Yet Another Set Of Ignore Files</h3>
+
+<p>The reader may note that this format is very similar to existing
+ignore list file formats, such as those for <samp><span class="command">cvs</span></samp>, <samp><span class="command">git</span></samp>,
+<samp><span class="command">rsync</span></samp> etc., and wonder if another set of ignore lists is
+justified.  However there are good reasons why Stow does not simply
+check for the presence of say, <samp><span class="file">.cvsignore</span></samp>, and use that if it
+exists.  Firstly, there is no guarantee that a stow package would
+contain any version control meta-data, or permit introducing this if
+it didn't already exist.
+
+   <p>Secondly even if it did, version control system ignore lists generally
+reflect <em>build-time</em> ignores rather than <em>install-time</em>, and
+there may be some intermediate or temporary files on those ignore
+lists generated during development or at build-time which it would be
+inappropriate to stow, even though many files generated at build-time
+(binaries, libraries, documentation etc.) certainly do need to be
+stowed.  Similarly, if a file is <em>not</em> in the version control
+system's ignore list, there is no way of knowing whether the file is
+intended for end use, let alone whether the version control system is
+tracking it or not.
+
+   <p>Therefore it seems clear that ignore lists provided by version control
+systems do not provide sufficient information for Stow to determine
+which files and directories to stow, and so it makes sense for Stow to
+support independent ignore lists.
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Known-Bugs.html

@@ -0,0 +1,76 @@
+<html lang="en">
+<head>
+<title>Known Bugs - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Reporting-Bugs.html#Reporting-Bugs" title="Reporting Bugs">
+<link rel="next" href="GNU-General-Public-License.html#GNU-General-Public-License" title="GNU General Public License">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Known-Bugs"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="GNU-General-Public-License.html#GNU-General-Public-License">GNU General Public License</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Reporting-Bugs.html#Reporting-Bugs">Reporting Bugs</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">15 Known Bugs</h2>
+
+<p>There are no known bugs in Stow version 2.2.2! 
+If you think you have found one, please see <a href="Reporting-Bugs.html#Reporting-Bugs">Reporting Bugs</a>.
+
+<!-- @itemize @bullet -->
+<!-- @item -->
+<!-- Put known bugs here -->
+<!-- @end itemize -->
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Mixing-Operations.html

@@ -0,0 +1,90 @@
+<html lang="en">
+<head>
+<title>Mixing Operations - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Conflicts.html#Conflicts" title="Conflicts">
+<link rel="next" href="Multiple-Stow-Directories.html#Multiple-Stow-Directories" title="Multiple Stow Directories">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Mixing-Operations"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Multiple-Stow-Directories.html#Multiple-Stow-Directories">Multiple Stow Directories</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Conflicts.html#Conflicts">Conflicts</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">8 Mixing Operations</h2>
+
+<p><a name="index-mixing-operations-33"></a>
+Since version 2.0, multiple distinct actions can be specified in a single
+invocation of GNU Stow.  For example, to update an installation of Emacs from
+version 21.3 to 21.4a you can now do the following:
+
+<pre class="example">     stow -D emacs-21.3 -S emacs-21.4a
+</pre>
+   <p class="noindent">which will replace emacs-21.3 with emacs-21.4a using a single invocation.
+
+   <p><a name="index-deferred-operation-34"></a>This is much faster and cleaner than performing two separate
+invocations of stow, because redundant folding/unfolding operations
+can be factored out.  In addition, all the operations are calculated
+and merged before being executed (see <a href="Deferred-Operation.html#Deferred-Operation">Deferred Operation</a>), so the
+amount of of time in which GNU Emacs is unavailable is minimised.
+
+   <p>You can mix and match any number of actions, for example,
+
+<pre class="example">     stow -S pkg1 pkg2 -D pkg3 pkg4 -S pkg5 -R pkg6
+</pre>
+   <p class="noindent">will unstow pkg3, pkg4 and pkg6, then stow pkg1, pkg2, pkg5 and pkg6.
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Motivation-For-Ignore-Lists.html

@@ -0,0 +1,94 @@
+<html lang="en">
+<head>
+<title>Motivation For Ignore Lists - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Ignore-Lists.html#Ignore-Lists" title="Ignore Lists">
+<link rel="prev" href="Ignore-Lists.html#Ignore-Lists" title="Ignore Lists">
+<link rel="next" href="Types-And-Syntax-Of-Ignore-Lists.html#Types-And-Syntax-Of-Ignore-Lists" title="Types And Syntax Of Ignore Lists">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Motivation-For-Ignore-Lists"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Types-And-Syntax-Of-Ignore-Lists.html#Types-And-Syntax-Of-Ignore-Lists">Types And Syntax Of Ignore Lists</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Ignore-Lists.html#Ignore-Lists">Ignore Lists</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Ignore-Lists.html#Ignore-Lists">Ignore Lists</a>
+<hr>
+</div>
+
+<h3 class="section">4.1 Motivation For Ignore Lists</h3>
+
+<p>In many situations, there will exist files under the package
+directories which it would be undesirable to stow into the target
+directory.  For example, files related version control such as
+<samp><span class="file">.gitignore</span></samp>, <samp><span class="file">CVS</span></samp>, <samp><span class="file">*,v</span></samp> (RCS files) should typically
+not have symlinks from the target tree pointing to them.  Also there
+may be files or directories relating to the build of the package which
+are not needed at run-time.
+
+   <p>In these cases, it can be rather cumbersome to specify a
+<samp><span class="option">--ignore</span></samp> parameter for each file or directory to be ignored. 
+This could be worked around by ensuring the existence of
+<samp><span class="file">~/.stowrc</span></samp> containing multiple <samp><span class="option">--ignore</span></samp> lines, or if a
+different set of files/directories should be ignored depending on
+which stow package is involved, a <samp><span class="file">.stowrc</span></samp> file for each stow
+package, but this would require the user to ensure that they were in
+the correct directory before invoking stow, which would be tedious and
+error-prone.  Furthermore, since Stow shifts parameters from
+<samp><span class="file">.stowrc</span></samp> onto ARGV at run-time, it could clutter up the process
+table with excessively long parameter lists, or even worse, exceed the
+operating system's limit for process arguments.
+
+   <p><a name="index-ignore-lists-16"></a>Therefore in addition to <samp><span class="option">--ignore</span></samp> parameters, Stow provides a
+way to specify lists of files and directories to ignore.
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Multiple-Stow-Directories.html

@@ -0,0 +1,86 @@
+<html lang="en">
+<head>
+<title>Multiple Stow Directories - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Mixing-Operations.html#Mixing-Operations" title="Mixing Operations">
+<link rel="next" href="Target-Maintenance.html#Target-Maintenance" title="Target Maintenance">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Multiple-Stow-Directories"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Target-Maintenance.html#Target-Maintenance">Target Maintenance</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Mixing-Operations.html#Mixing-Operations">Mixing Operations</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">9 Multiple Stow Directories</h2>
+
+<p>If there are two or more system administrators who wish to maintain
+software separately, or if there is any other reason to want two or more
+stow directories, it can be done by creating a file named <samp><span class="file">.stow</span></samp>
+in each stow directory.  The presence of <samp><span class="file">/usr/local/foo/.stow</span></samp>
+informs Stow that, though <samp><span class="file">foo</span></samp> is not the current stow
+directory, even if it is a subdirectory of the target directory,
+nevertheless it is <em>a</em> stow directory and as such Stow
+doesn't &ldquo;own&rdquo; anything in it (see <a href="Installing-Packages.html#Installing-Packages">Installing Packages</a>).  This will
+protect the contents of <samp><span class="file">foo</span></samp> from a &lsquo;<samp><span class="samp">stow -D</span></samp>&rsquo;, for instance.
+
+<!-- There is a test for the following case in t/examples.t: -->
+   <p>When multiple stow directories share a target tree, if a tree-folding
+symlink is encountered and needs to be split open during an
+installation, as long as the top-level stow directory into which the
+existing symlink points contains <samp><span class="file">.stow</span></samp>, Stow knows how to split
+open the tree in the correct manner.
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Other-FSF-Software.html

@@ -0,0 +1,85 @@
+<html lang="en">
+<head>
+<title>Other FSF Software - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime" title="Compile-time vs Install-time">
+<link rel="prev" href="GNU-Emacs.html#GNU-Emacs" title="GNU Emacs">
+<link rel="next" href="Cygnus-Software.html#Cygnus-Software" title="Cygnus Software">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Other-FSF-Software"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Cygnus-Software.html#Cygnus-Software">Cygnus Software</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="GNU-Emacs.html#GNU-Emacs">GNU Emacs</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">Compile-time vs Install-time</a>
+<hr>
+</div>
+
+<h3 class="section">12.3 Other FSF Software</h3>
+
+<p>The Free Software Foundation, the organization behind the GNU project,
+has been unifying the build procedure for its tools for some time. 
+Thanks to its tools &lsquo;<samp><span class="samp">autoconf</span></samp>&rsquo; and &lsquo;<samp><span class="samp">automake</span></samp>&rsquo;, most packages
+now respond well to these simple steps, with no other intervention
+necessary:
+
+<pre class="example">     ./configure <var>options</var>
+     make
+     make install prefix=/usr/local/stow/<var>package</var>
+</pre>
+   <p>Hopefully, these tools can evolve to be aware of Stow-managed packages,
+such that providing an option to &lsquo;<samp><span class="samp">configure</span></samp>&rsquo; can allow &lsquo;<samp><span class="samp">make</span></samp>&rsquo;
+and &lsquo;<samp><span class="samp">make install</span></samp>&rsquo; steps to work correctly without needing to
+&ldquo;fool&rdquo; the build process.
+
+<!--  -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Perl-and-Perl-5-Modules.html

@@ -0,0 +1,150 @@
+<html lang="en">
+<head>
+<title>Perl and Perl 5 Modules - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime" title="Compile-time vs Install-time">
+<link rel="prev" href="Cygnus-Software.html#Cygnus-Software" title="Cygnus Software">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Perl-and-Perl-5-Modules"></a>
+<p>
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Cygnus-Software.html#Cygnus-Software">Cygnus Software</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">Compile-time vs Install-time</a>
+<hr>
+</div>
+
+<h3 class="section">12.5 Perl and Perl 5 Modules</h3>
+
+<p>Perl 4.036 allows you to specify different locations for installation
+and for run-time.  It is the only widely-used package in this author's
+experience that allows this, though hopefully more packages will adopt
+this model.
+
+   <p>Unfortunately, the authors of Perl believed that only AFS sites need
+this ability.  The configuration instructions for Perl 4 misleadingly
+state that some occult means are used under AFS to transport files from
+their installation tree to their run-time tree.  In fact, that confusion
+arises from the fact that Depot, Stow's predecessor, originated at
+Carnegie Mellon University, which was also the birthplace of AFS.  CMU's
+need to separate install-time and run-time trees stemmed from its use of
+Depot, not from AFS.
+
+   <p>The result of this confusion is that Perl 5's configuration script
+doesn't even offer the option of separating install-time and run-time
+trees <em>unless</em> you're running AFS.  Fortunately, after you've
+entered all the configuration settings, Perl's setup script gives you
+the opportunity to edit those settings in a file called
+<samp><span class="file">config.sh</span></samp>.  When prompted, you should edit this file and replace
+occurrences of
+
+<pre class="example">     inst<span class="roman">...</span>/usr/local<span class="roman">...</span>
+</pre>
+   <p class="noindent">with
+
+<pre class="example">     inst<span class="roman">...</span>/usr/local/stow/perl<span class="roman">...</span>
+</pre>
+   <p class="noindent">You can do this with the following Unix command:
+
+<pre class="example">     sed 's,^\(inst.*/usr/local\),\1/stow/perl,' config.sh &gt; config.sh.new
+     mv config.sh.new config.sh
+</pre>
+   <p>Hopefully, the Perl authors will correct this deficiency in Perl 5's
+configuration mechanism.
+
+   <p>Perl 5 modules&mdash;i.e., extensions to Perl 5&mdash;generally conform to a set
+of standards for building and installing them.  The standard says that
+the package comes with a top-level <samp><span class="file">Makefile.PL</span></samp>, which is a Perl
+script.  When it runs, it generates a <samp><span class="file">Makefile</span></samp>.
+
+   <p>If you followed the instructions above for editing <samp><span class="file">config.sh</span></samp> when
+Perl was built, then when you create a <samp><span class="file">Makefile</span></samp> from a
+<samp><span class="file">Makefile.PL</span></samp>, it will contain separate locations for run-time
+(<samp><span class="file">/usr/local</span></samp>) and install-time (<samp><span class="file">/usr/local/stow/perl</span></samp>). 
+Thus you can do
+
+<pre class="example">     perl Makefile.PL
+     make
+     make install
+</pre>
+   <p class="noindent">and the files will be installed into <samp><span class="file">/usr/local/stow/perl</span></samp>. 
+However, you might prefer each Perl module to be stowed separately.  In
+that case, you must edit the resulting Makefile, replacing
+<samp><span class="file">/usr/local/stow/perl</span></samp> with <samp><span class="file">/usr/local/stow/</span><var>module</var></samp>. 
+The best way to do this is:
+
+<pre class="example">     perl Makefile.PL
+     find . -name Makefile -print | \
+       xargs perl -pi~ -e 's,^(INST.*/stow)/perl,$1/<var>module</var>,;'
+     make
+     make install
+</pre>
+   <p class="noindent">(The use of &lsquo;<samp><span class="samp">find</span></samp>&rsquo; and &lsquo;<samp><span class="samp">xargs</span></samp>&rsquo; ensures that all Makefiles in
+the module's source tree, even those in subdirectories, get edited.)  A
+good convention to follow is to name the stow directory for a Perl
+<var>module</var> <samp><span class="file">cpan.</span><var>module</var></samp>, where &lsquo;<samp><span class="samp">cpan</span></samp>&rsquo; stands for
+Comprehensive Perl Archive Network, a collection of FTP sites that is
+the source of most Perl 5 extensions.  This way, it's easy to tell at a
+glance which of the subdirectories of <samp><span class="file">/usr/local/stow</span></samp> are Perl 5
+extensions.
+
+   <p>When you stow separate Perl 5 modules separately, you are likely to
+encounter conflicts (see <a href="Conflicts.html#Conflicts">Conflicts</a>) with files named <samp><span class="file">.exists</span></samp>
+and <samp><span class="file">perllocal.pod</span></samp>.  One way to work around this is to remove
+those files before stowing the module.  If you use the
+<samp><span class="file">cpan.</span><var>module</var></samp> naming convention, you can simply do this:
+
+<pre class="example">     cd /usr/local/stow
+     find cpan.* \( -name .exists -o -name perllocal.pod \) -print | \
+       xargs rm
+</pre>
+   <!--  -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Reporting-Bugs.html

@@ -0,0 +1,98 @@
+<html lang="en">
+<head>
+<title>Reporting Bugs - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Bootstrapping.html#Bootstrapping" title="Bootstrapping">
+<link rel="next" href="Known-Bugs.html#Known-Bugs" title="Known Bugs">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Reporting-Bugs"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Known-Bugs.html#Known-Bugs">Known Bugs</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Bootstrapping.html#Bootstrapping">Bootstrapping</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">14 Reporting Bugs</h2>
+
+<p>Please send bug reports to the current maintainers by electronic
+mail.  The address to use is &lsquo;<samp><span class="samp">&lt;bug-stow@gnu.org&gt;</span></samp>&rsquo;.  Please
+include:
+
+     <ul>
+<li>the version number of Stow (&lsquo;<samp><span class="samp">stow --version</span></samp>&rsquo;);
+
+     <li>the version number of Perl (&lsquo;<samp><span class="samp">perl -v</span></samp>&rsquo;);
+
+     <li>the system information, which can often be obtained with &lsquo;<samp><span class="samp">uname
+-a</span></samp>&rsquo;;
+
+     <li>a description of the bug;
+
+     <li>the precise command you gave;
+
+     <li>the output from the command (preferably verbose output, obtained by
+adding &lsquo;<samp><span class="samp">--verbose=3</span></samp>&rsquo; to the Stow command line). 
+</ul>
+
+   <p>If you are really keen, consider developing a minimal test case and
+creating a new test.  See the <samp><span class="file">t/</span></samp> directory in the source for
+lots of examples.
+
+   <p>Before reporting a bug, please read the manual carefully, especially
+<a href="Known-Bugs.html#Known-Bugs">Known Bugs</a>, to see whether you're encountering
+something that doesn't need reporting. 
+(see <a href="Conflicts.html#Conflicts">Conflicts</a>).
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Resource-Files.html

@@ -0,0 +1,108 @@
+<html lang="en">
+<head>
+<title>Resource Files - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Target-Maintenance.html#Target-Maintenance" title="Target Maintenance">
+<link rel="next" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime" title="Compile-time vs Install-time">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Resource-Files"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">Compile-time vs Install-time</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Target-Maintenance.html#Target-Maintenance">Target Maintenance</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">11 Resource Files</h2>
+
+<p><a name="index-resource-files-36"></a><a name="index-configuration-files-37"></a>
+Default command line options may be set in <samp><span class="file">.stowrc</span></samp> (current directory) or
+<samp><span class="file">~/.stowrc</span></samp> (home directory). These are parsed in that order, and effectively
+prepended to you command line.  This feature can be used for some interesting
+effects.
+
+   <p>For example, suppose your site uses more than one stow directory, perhaps in
+order to share around responsibilities with a number of systems
+administrators. One of the administrators might have the following in their
+<samp><span class="file">~/.stowrc</span></samp> file:
+
+<pre class="example">     --dir=/usr/local/stow2
+     --target=/usr/local
+     --ignore='~'
+     --ignore='^CVS'
+</pre>
+   <p>so that the <samp><span class="command">stow</span></samp> command will default to operating on the
+<samp><span class="file">/usr/local/stow2</span></samp> directory, with <samp><span class="file">/usr/local</span></samp> as the
+target, and ignoring vi backup files and CVS directories.
+
+   <p>If you had a stow directory <samp><span class="file">/usr/local/stow/perl-extras</span></samp> that
+was only used for Perl modules, then you might place the following in
+<samp><span class="file">/usr/local/stow/perl-extras/.stowrc</span></samp>:
+
+<pre class="example">     --dir=/usr/local/stow/perl-extras
+     --target=/usr/local
+     --override=bin
+     --override=man
+     --ignore='perllocal\.pod'
+     --ignore='\.packlist'
+     --ignore='\.bs'
+</pre>
+   <p>so that when you are in the <samp><span class="file">/usr/local/stow/perl-extras</span></samp>
+directory, <samp><span class="command">stow</span></samp> will regard any subdirectories as stow
+packages, with <samp><span class="file">/usr/local</span></samp> as the target (rather than the
+immediate parent directory <samp><span class="file">/usr/local/stow</span></samp>), overriding any
+pre-existing links to bin files or man pages, and ignoring some cruft
+that gets installed by default.
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Target-Maintenance.html

@@ -0,0 +1,98 @@
+<html lang="en">
+<head>
+<title>Target Maintenance - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Multiple-Stow-Directories.html#Multiple-Stow-Directories" title="Multiple Stow Directories">
+<link rel="next" href="Resource-Files.html#Resource-Files" title="Resource Files">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Target-Maintenance"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Resource-Files.html#Resource-Files">Resource Files</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Multiple-Stow-Directories.html#Multiple-Stow-Directories">Multiple Stow Directories</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">10 Target Maintenance</h2>
+
+<p><a name="index-maintenance-35"></a>From time to time you will need to clean up your target tree.  Since
+version 2, Stow provides a new utility <samp><span class="command">chkstow</span></samp> to help with
+this.  It includes three operational modes which performs checks that
+would generally be too expensive to be performed during normal stow
+execution.
+
+   <p>The syntax of the <samp><span class="command">chkstow</span></samp> command is:
+
+<pre class="example">     chkstow [<var>options</var>]
+</pre>
+   <p class="noindent">The following options are supported:
+
+     <dl>
+<dt>&lsquo;<samp><span class="samp">-t </span><var>dir</var></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--target=</span><var>dir</var></samp>&rsquo;<dd>Set the target directory to <var>dir</var> instead of the parent of the stow
+directory.  Defaults to the parent of the stow directory, so it is typical to
+execute <samp><span class="command">stow</span></samp> from the directory <samp><span class="file">/usr/local/stow</span></samp>.
+
+     <br><dt>&lsquo;<samp><span class="samp">-b</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--badlinks</span></samp>&rsquo;<dd>Checks target directory for bogus symbolic links. That is, links that point to
+non-existent files.
+
+     <br><dt>&lsquo;<samp><span class="samp">-a</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--aliens</span></samp>&rsquo;<dd>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 <samp><span class="file">.stow</span></samp> file.
+
+     <br><dt>&lsquo;<samp><span class="samp">-l</span></samp>&rsquo;<dt>&lsquo;<samp><span class="samp">--list</span></samp>&rsquo;<dd>Will display the target package for every symbolic link in the stow target
+directory.
+
+   </dl>
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Terminology.html

@@ -0,0 +1,113 @@
+<html lang="en">
+<head>
+<title>Terminology - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Introduction.html#Introduction" title="Introduction">
+<link rel="next" href="Invoking-Stow.html#Invoking-Stow" title="Invoking Stow">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Terminology"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Invoking-Stow.html#Invoking-Stow">Invoking Stow</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Introduction.html#Introduction">Introduction</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<h2 class="chapter">2 Terminology</h2>
+
+   <p class="indent"><a name="index-package-1"></a>A <dfn>package</dfn> is a related collection of files and directories that
+you wish to administer as a unit &mdash; e.g., Perl or Emacs &mdash; and that needs
+to be installed in a particular directory structure &mdash; e.g., with
+<samp><span class="file">bin</span></samp>, <samp><span class="file">lib</span></samp>, and <samp><span class="file">man</span></samp> subdirectories.
+
+   <p><a name="index-target-directory-2"></a>A <dfn>target directory</dfn> is the root of a tree in which one or more
+packages wish to <em>appear</em> to be installed.  A common, but by no
+means the only such location is <samp><span class="file">/usr/local</span></samp>.  The examples in this
+manual will use <samp><span class="file">/usr/local</span></samp> as the target directory.
+
+   <p><a name="index-stow-directory-3"></a>A <dfn>stow directory</dfn> is the root of a tree containing separate
+packages in private subtrees.  When Stow runs, it uses the current
+directory as the default stow directory.  The examples in this manual
+will use <samp><span class="file">/usr/local/stow</span></samp> as the stow directory, so that
+individual packages will be, for example, <samp><span class="file">/usr/local/stow/perl</span></samp>
+and <samp><span class="file">/usr/local/stow/emacs</span></samp>.
+
+   <p><a name="index-installation-image-4"></a>An <dfn>installation image</dfn> is the layout of files and directories
+required by a package, relative to the target directory.  Thus, the
+installation image for Perl includes: a <samp><span class="file">bin</span></samp> directory containing
+<samp><span class="file">perl</span></samp> and <samp><span class="file">a2p</span></samp> (among others); an <samp><span class="file">info</span></samp> directory
+containing Texinfo documentation; a <samp><span class="file">lib/perl</span></samp> directory containing
+Perl libraries; and a <samp><span class="file">man/man1</span></samp> directory containing man pages.
+
+   <p><a name="index-package-directory-5"></a><a name="index-package-name-6"></a>A <dfn>package directory</dfn> is the root of a tree containing the
+installation image for a particular package.  Each package directory
+must reside in a stow directory &mdash; e.g., the package directory
+<samp><span class="file">/usr/local/stow/perl</span></samp> must reside in the stow directory
+<samp><span class="file">/usr/local/stow</span></samp>.  The <dfn>name</dfn> of a package is the name of its
+directory within the stow directory &mdash; e.g., <samp><span class="file">perl</span></samp>.
+
+   <p>Thus, the Perl executable might reside in
+<samp><span class="file">/usr/local/stow/perl/bin/perl</span></samp>, where <samp><span class="file">/usr/local</span></samp> is the
+target directory, <samp><span class="file">/usr/local/stow</span></samp> is the stow directory,
+<samp><span class="file">/usr/local/stow/perl</span></samp> is the package directory, and
+<samp><span class="file">bin/perl</span></samp> within is part of the installation image.
+
+   <p><a name="index-symlink-7"></a><a name="index-relative-symlink-8"></a><a name="index-absolute-symlink-9"></a>A <dfn>symlink</dfn> is a symbolic link.  A symlink can be <dfn>relative</dfn> or
+<dfn>absolute</dfn>.  An absolute symlink names a full path; that is, one
+starting from <samp><span class="file">/</span></samp>.  A relative symlink names a relative path; that
+is, one not starting from <samp><span class="file">/</span></samp>.  The target of a relative symlink is
+computed starting from the symlink's own directory.  Stow only
+creates relative symlinks.
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/Tree-unfolding.html

@@ -0,0 +1 @@
+<meta http-equiv="refresh" content="0; url=Installing-Packages.html#Tree%20unfolding">

.local/share/doc/stow/manual-split/Types-And-Syntax-Of-Ignore-Lists.html

@@ -0,0 +1,167 @@
+<html lang="en">
+<head>
+<title>Types And Syntax Of Ignore Lists - Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Ignore-Lists.html#Ignore-Lists" title="Ignore Lists">
+<link rel="prev" href="Motivation-For-Ignore-Lists.html#Motivation-For-Ignore-Lists" title="Motivation For Ignore Lists">
+<link rel="next" href="Justification-For-Yet-Another-Set-Of-Ignore-Files.html#Justification-For-Yet-Another-Set-Of-Ignore-Files" title="Justification For Yet Another Set Of Ignore Files">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled ``GNU General Public License'' is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Types-And-Syntax-Of-Ignore-Lists"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Justification-For-Yet-Another-Set-Of-Ignore-Files.html#Justification-For-Yet-Another-Set-Of-Ignore-Files">Justification For Yet Another Set Of Ignore Files</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Motivation-For-Ignore-Lists.html#Motivation-For-Ignore-Lists">Motivation For Ignore Lists</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Ignore-Lists.html#Ignore-Lists">Ignore Lists</a>
+<hr>
+</div>
+
+<h3 class="section">4.2 Types And Syntax Of Ignore Lists</h3>
+
+<p>If you put Perl regular expressions, one per line, in a
+<samp><span class="file">.stow-local-ignore</span></samp> file within any top level package directory,
+in which case any file or directory within that package matching any
+of these regular expressions will be ignored.  In the absence of this
+package-specific ignore list, Stow will instead use the contents of
+<samp><span class="file">~/.stow-global-ignore</span></samp>, if it exists.  If neither the
+package-local or global ignore list exist, Stow will use its own
+built-in default ignore list, which serves as a useful example of the
+format of these ignore list files:
+
+<pre class="example"><pre class="verbatim">     # Comments and blank lines are allowed.
+     
+     RCS
+     .+,v
+     
+     CVS
+     \.\#.+       # CVS conflict files / emacs lock files
+     \.cvsignore
+     
+     \.svn
+     _darcs
+     \.hg
+     
+     \.git
+     \.gitignore
+     
+     .+~          # emacs backup files
+     \#.*\#       # emacs autosave files
+     
+     ^/README.*
+     ^/LICENSE.*
+     ^/COPYING
+</pre></pre>
+   <p>Stow first iterates through the chosen ignore list (built-in, global,
+or package-local) as per above, stripping out comments (if you want to
+include the &lsquo;<samp><span class="samp">#</span></samp>&rsquo; symbol in a regular expression, escape it with a
+blackslash) and blank lines, placing each regular expressions into one
+of two sets depending on whether it contains the &lsquo;<samp><span class="samp">/</span></samp>&rsquo; forward
+slash symbol.
+
+   <p>Then in order to determine whether a file or directory should be
+ignored:
+
+     <ol type=1 start=1>
+<li>Stow calculates its path relative to the top-level package directory,
+prefixing that with &lsquo;<samp><span class="samp">/</span></samp>&rsquo;.  If any of the regular expressions
+containing a &lsquo;<samp><span class="samp">/</span></samp>&rsquo; <em>exactly</em><a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> match
+a subpath<a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a> of this relative path, then the file or
+directory will be ignored.
+
+     <li>If none of the regular expressions containing a &lsquo;<samp><span class="samp">/</span></samp>&rsquo; match in the
+manner described above, Stow checks whether the
+<em>basename</em><a rel="footnote" href="#fn-3" name="fnd-3"><sup>3</sup></a> of the file or directory matches
+<em>exactly</em> against the remaining regular expressions which do not
+contain a &lsquo;<samp><span class="samp">/</span></samp>&rsquo;, and if so, ignores the file or directory.
+
+     <li>Otherwise, the file or directory is not ignored.
+        </ol>
+
+<!-- N.B. if you change the examples below, please also consider -->
+<!-- updating test_examples_in_manual() in t/ignore.t. -->
+   <p>For example, if a file <samp><span class="file">bazqux</span></samp> is in the <samp><span class="file">foo/bar</span></samp>
+subdirectory of the package directory, Stow would use
+&lsquo;<samp><span class="samp">/foo/bar/bazqux</span></samp>&rsquo; as the text for matching against regular
+expressions which contain &lsquo;<samp><span class="samp">/</span></samp>&rsquo;, and &lsquo;<samp><span class="samp">bazqux</span></samp>&rsquo; as the text for
+matching against regular expressions which don't contain &lsquo;<samp><span class="samp">/</span></samp>&rsquo;. 
+Then regular expressions &lsquo;<samp><span class="samp">bazqux</span></samp>&rsquo;, &lsquo;<samp><span class="samp">baz.*</span></samp>&rsquo;, &lsquo;<samp><span class="samp">.*qux</span></samp>&rsquo;,
+&lsquo;<samp><span class="samp">bar/.*x</span></samp>&rsquo;, and &lsquo;<samp><span class="samp">^/foo/.*qux</span></samp>&rsquo; would all match (causing the
+file to be ignored), whereas &lsquo;<samp><span class="samp">bar</span></samp>&rsquo;, &lsquo;<samp><span class="samp">baz</span></samp>&rsquo;, &lsquo;<samp><span class="samp">qux</span></samp>&rsquo;, and
+&lsquo;<samp><span class="samp">o/bar/b</span></samp>&rsquo; would not (although &lsquo;<samp><span class="samp">bar</span></samp>&rsquo; would cause its parent
+directory to be ignored and prevent Stow from recursing into that
+anyway, in which case the file <samp><span class="file">bazqux</span></samp> would not even be
+considered for stowing).
+
+   <p>As a special exception to the above algorithm, any
+<samp><span class="file">.stow-local-ignore</span></samp> present in the top-level package directory
+is <em>always</em> ignored, regardless of the contents of any ignore
+list, because this file serves no purpose outside the stow directory.
+
+<!-- =========================================================================== -->
+   <div class="footnote">
+<hr>
+<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> Exact matching means the
+regular expression is anchored at the beginning and end, in contrast
+to unanchored regular expressions which will match a substring.</p>
+
+   <p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> In this context, &ldquo;subpath&rdquo; means a contiguous
+subset of path segments; e.g for the relative path
+<samp><span class="file">one/two/three</span></samp>, there are six valid subpaths: <samp><span class="file">one</span></samp>,
+<samp><span class="file">two</span></samp>, <samp><span class="file">three</span></samp>, <samp><span class="file">one/two</span></samp>, <samp><span class="file">two/three</span></samp>,
+<samp><span class="file">one/two/three</span></samp>.</p>
+
+   <p class="footnote"><small>[<a name="fn-3" href="#fnd-3">3</a>]</small> The &ldquo;basename&rdquo; is the name of the file or
+directory itself, excluding any directory path prefix - as returned by
+the <samp><span class="command">basename</span></samp> command.</p>
+
+   <hr></div>
+
+   </body></html>
+

.local/share/doc/stow/manual-split/index.html

@@ -0,0 +1,164 @@
+<html lang="en">
+<head>
+<title>Stow</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="Stow">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="#Top">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<!--
+This manual describes GNU Stow version 2.2.2
+(9 November 2015), a program for managing the installation of software
+packages.
+
+Software and documentation is copyrighted by the following:
+
+(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
+
+(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>
+
+(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
+
+(C) 2011 Adam Spiers <stow@adamspiers.org>
+
+     Permission is granted to make and distribute verbatim copies of
+     this manual provided the copyright notice and this permission
+     notice are preserved on all copies.
+
+     Permission is granted to copy and distribute modified versions of
+     this manual under the conditions for verbatim copying, provided
+     also that the section entitled "GNU General Public License" is
+     included with the modified manual, and provided that the entire
+     resulting derived work is distributed under the terms of a
+     permission notice identical to this one.
+
+     Permission is granted to copy and distribute translations of this
+     manual into another language, under the above conditions for
+     modified versions, except that this permission notice may be
+     stated in a translation approved by the Free Software Foundation.
+   -->
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<h1 class="settitle">Stow</h1>
+<div class="contents">
+<h2>Table of Contents</h2>
+<ul>
+<li><a name="toc_Top" href="index.html#Top">Stow</a>
+<li><a name="toc_Introduction" href="Introduction.html#Introduction">1 Introduction</a>
+<li><a name="toc_Terminology" href="Terminology.html#Terminology">2 Terminology</a>
+<li><a name="toc_Invoking-Stow" href="Invoking-Stow.html#Invoking-Stow">3 Invoking Stow</a>
+<li><a name="toc_Ignore-Lists" href="Ignore-Lists.html#Ignore-Lists">4 Ignore Lists</a>
+<ul>
+<li><a href="Motivation-For-Ignore-Lists.html#Motivation-For-Ignore-Lists">4.1 Motivation For Ignore Lists</a>
+<li><a href="Types-And-Syntax-Of-Ignore-Lists.html#Types-And-Syntax-Of-Ignore-Lists">4.2 Types And Syntax Of Ignore Lists</a>
+<li><a href="Justification-For-Yet-Another-Set-Of-Ignore-Files.html#Justification-For-Yet-Another-Set-Of-Ignore-Files">4.3 Justification For Yet Another Set Of Ignore Files</a>
+</li></ul>
+<li><a name="toc_Installing-Packages" href="Installing-Packages.html#Installing-Packages">5 Installing Packages</a>
+<ul>
+<li><a href="Installing-Packages.html#Installing-Packages">5.1 Tree folding</a>
+<li><a href="Installing-Packages.html#Installing-Packages">5.2 Tree unfolding</a>
+<li><a href="Installing-Packages.html#Installing-Packages">5.3 Ownership</a>
+<li><a href="Installing-Packages.html#Installing-Packages">5.4 Conflicts during installation</a>
+</li></ul>
+<li><a name="toc_Deleting-Packages" href="Deleting-Packages.html#Deleting-Packages">6 Deleting Packages</a>
+<ul>
+<li><a href="Deleting-Packages.html#Deleting-Packages">6.1 Refolding &ldquo;foldable&rdquo; trees.</a>
+</li></ul>
+<li><a name="toc_Conflicts" href="Conflicts.html#Conflicts">7 Conflicts</a>
+<ul>
+<li><a href="Conflicts.html#Conflicts">7.1 Deferred Operation</a>
+</li></ul>
+<li><a name="toc_Mixing-Operations" href="Mixing-Operations.html#Mixing-Operations">8 Mixing Operations</a>
+<li><a name="toc_Multiple-Stow-Directories" href="Multiple-Stow-Directories.html#Multiple-Stow-Directories">9 Multiple Stow Directories</a>
+<li><a name="toc_Target-Maintenance" href="Target-Maintenance.html#Target-Maintenance">10 Target Maintenance</a>
+<li><a name="toc_Resource-Files" href="Resource-Files.html#Resource-Files">11 Resource Files</a>
+<li><a name="toc_Compile_002dtime-vs-Install_002dtime" href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">12 Compile-time vs Install-time</a>
+<ul>
+<li><a href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">12.1 Advice on changing compilation and installation parameters</a>
+<li><a href="GNU-Emacs.html#GNU-Emacs">12.2 GNU Emacs</a>
+<li><a href="Other-FSF-Software.html#Other-FSF-Software">12.3 Other FSF Software</a>
+<li><a href="Cygnus-Software.html#Cygnus-Software">12.4 Cygnus Software</a>
+<li><a href="Perl-and-Perl-5-Modules.html#Perl-and-Perl-5-Modules">12.5 Perl and Perl 5 Modules</a>
+</li></ul>
+<li><a name="toc_Bootstrapping" href="Bootstrapping.html#Bootstrapping">13 Bootstrapping</a>
+<li><a name="toc_Reporting-Bugs" href="Reporting-Bugs.html#Reporting-Bugs">14 Reporting Bugs</a>
+<li><a name="toc_Known-Bugs" href="Known-Bugs.html#Known-Bugs">15 Known Bugs</a>
+<li><a name="toc_GNU-General-Public-License" href="GNU-General-Public-License.html#GNU-General-Public-License">GNU General Public License</a>
+<ul>
+<li><a href="GNU-General-Public-License.html#GNU-General-Public-License">Preamble</a>
+<li><a href="GNU-General-Public-License.html#GNU-General-Public-License">How to Apply These Terms to Your New Programs</a>
+</li></ul>
+<li><a name="toc_Index" href="Index.html#Index">Index</a>
+</li></ul>
+</div>
+
+
+
+<!-- ========================================================================== -->
+<div class="node">
+<a name="Top"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Introduction.html#Introduction">Introduction</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="../index.html#dir">(dir)</a>
+<hr>
+</div>
+
+<h2 class="unnumbered">Stow</h2>
+
+<ul class="menu">
+<li><a accesskey="1" href="Introduction.html#Introduction">Introduction</a>:                 Description of Stow. 
+<li><a accesskey="2" href="Terminology.html#Terminology">Terminology</a>:                  Terms used by this manual. 
+<li><a accesskey="3" href="Invoking-Stow.html#Invoking-Stow">Invoking Stow</a>:                Option summary. 
+<li><a accesskey="4" href="Ignore-Lists.html#Ignore-Lists">Ignore Lists</a>:                 Controlling what gets stowed. 
+<li><a accesskey="5" href="Installing-Packages.html#Installing-Packages">Installing Packages</a>:          Using Stow to install. 
+<li><a accesskey="6" href="Deleting-Packages.html#Deleting-Packages">Deleting Packages</a>:            Using Stow to uninstall. 
+<li><a accesskey="7" href="Conflicts.html#Conflicts">Conflicts</a>:                    When Stow can't stow. 
+<li><a accesskey="8" href="Mixing-Operations.html#Mixing-Operations">Mixing Operations</a>:            Multiple actions per invocation. 
+<li><a accesskey="9" href="Multiple-Stow-Directories.html#Multiple-Stow-Directories">Multiple Stow Directories</a>:    Further segregating software. 
+<li><a href="Target-Maintenance.html#Target-Maintenance">Target Maintenance</a>:           Cleaning up mistakes. 
+<li><a href="Resource-Files.html#Resource-Files">Resource Files</a>:               Setting default command line options. 
+<li><a href="Compile_002dtime-vs-Install_002dtime.html#Compile_002dtime-vs-Install_002dtime">Compile-time vs Install-time</a>:   Faking out `make install'. 
+<li><a href="Bootstrapping.html#Bootstrapping">Bootstrapping</a>:                When stow and perl are not yet stowed. 
+<li><a href="Reporting-Bugs.html#Reporting-Bugs">Reporting Bugs</a>:               How, what, where, and when to report. 
+<li><a href="Known-Bugs.html#Known-Bugs">Known Bugs</a>:                   Don't report any of these. 
+<li><a href="GNU-General-Public-License.html#GNU-General-Public-License">GNU General Public License</a>:   Copying terms. 
+<li><a href="Index.html#Index">Index</a>:                        Index of concepts.
+
+</li></ul>
+<p>--- The Detailed Node Listing ---
+
+<p>Ignore Lists
+
+</p>
+<ul class="menu">
+<li><a href="Motivation-For-Ignore-Lists.html#Motivation-For-Ignore-Lists">Motivation For Ignore Lists</a>
+<li><a href="Types-And-Syntax-Of-Ignore-Lists.html#Types-And-Syntax-Of-Ignore-Lists">Types And Syntax Of Ignore Lists</a>
+<li><a href="Justification-For-Yet-Another-Set-Of-Ignore-Files.html#Justification-For-Yet-Another-Set-Of-Ignore-Files">Justification For Yet Another Set Of Ignore Files</a>
+
+</li></ul>
+<p>Advice on changing compilation and installation parameters
+
+</p>
+<ul class="menu">
+<li><a href="GNU-Emacs.html#GNU-Emacs">GNU Emacs</a>
+<li><a href="Other-FSF-Software.html#Other-FSF-Software">Other FSF Software</a>
+<li><a href="Cygnus-Software.html#Cygnus-Software">Cygnus Software</a>
+<li><a href="Perl-and-Perl-5-Modules.html#Perl-and-Perl-5-Modules">Perl and Perl 5 Modules</a>
+
+   </ul>
+
+<!-- =========================================================================== -->
+   </body></html>
+

.local/share/doc/stow/manual-split/tree-folding.html

@@ -0,0 +1 @@
+<meta http-equiv="refresh" content="0; url=Installing-Packages.html#tree%20folding">

.local/share/doc/stow/manual-split/tree-refolding.html

@@ -0,0 +1 @@
+<meta http-equiv="refresh" content="0; url=Deleting-Packages.html#tree%20refolding">

.local/share/doc/stow/version.texi

@@ -0,0 +1,4 @@
+@set UPDATED 9 November 2015
+@set UPDATED-MONTH November 2015
+@set EDITION 2.2.2
+@set VERSION 2.2.2

.local/share/info/dir

@@ -0,0 +1,18 @@
+This is the file .../info/dir, which contains the
+topmost node of the Info hierarchy, called (dir)Top.
+The first time you invoke Info you start off looking at this node.
+
+File: dir,	Node: Top	This is the top of the INFO tree
+
+  This (the Directory node) gives a menu of major topics.
+  Typing "q" exits, "?" lists all Info commands, "d" returns here,
+  "h" gives a primer for first-timers,
+  "mEmacs<Return>" visits the Emacs manual, etc.
+
+  In Emacs, you can click mouse button 2 on a menu item or cross reference
+  to select it.
+
+* Menu:
+
+System administration
+* Stow: (stow).           GNU Stow.

.local/share/man/man8/stow.8

@@ -0,0 +1,508 @@
+.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+.    if \nF \{
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "IO::FILE=IO(0X81D9F0) 1"
+.TH IO::FILE=IO(0X81D9F0) 1 "2015-11-09" "perl v5.20.1" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+stow \- software package installation manager
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+stow [ options ] package ...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This manual page describes \s-1GNU\s0 Stow 2.2.2, a program for managing
+the installation of software packages. This is not the definitive
+documentation for stow; for that, see the info manual.
+.PP
+Stow is a tool for managing the installation of multiple software
+packages in the same run-time directory tree. One historical
+difficulty of this task has been the need to administer, upgrade,
+install, and remove files in independent packages without confusing
+them with other files sharing the same filesystem space. For instance,
+it is common to install Perl and Emacs in \fI/usr/local\fR.  When one
+does so, one winds up (as of Perl 4.036 and Emacs 19.22) with the
+following files in \fI/usr/local/man/man1\fR: \fIa2p.1\fR; \fIctags.1\fR;
+\&\fIemacs.1\fR; \fIetags.1\fR; \fIh2ph.1\fR; \fIperl.1\fR; and \fIs2p.1\fR.  Now
+suppose it's time to uninstall Perl. Which man pages get removed?
+Obviously \fIperl.1\fR is one of them, but it should not be the
+administrator's responsibility to memorize the ownership of individual
+files by separate packages.
+.PP
+The approach used by Stow is to install each package into its own
+tree, then use symbolic links to make it appear as though the files
+are installed in the common tree. Administration can be performed in
+the package's private tree in isolation from clutter from other
+packages.  Stow can then be used to update the symbolic links. The
+structure of each private tree should reflect the desired structure in
+the common tree; i.e. (in the typical case) there should be a \fIbin\fR
+directory containing executables, a \fIman/man1\fR directory containing
+section 1 man pages, and so on.
+.PP
+Stow was inspired by Carnegie Mellon's Depot program, but is
+substantially simpler and safer. Whereas Depot required database files
+to keep things in sync, Stow stores no extra state between runs, so
+there's no danger (as there was in Depot) of mangling directories when
+file hierarchies don't match the database. Also unlike Depot, Stow
+will never delete any files, directories, or links that appear in a
+Stow directory (e.g., \fI/usr/local/stow/emacs\fR), so it's always
+possible to rebuild the target tree (e.g., \fI/usr/local\fR).
+.SH "TERMINOLOGY"
+.IX Header "TERMINOLOGY"
+A \*(L"package\*(R" is a related collection of files and directories that
+you wish to administer as a unit \*(-- e.g., Perl or Emacs \*(-- and that
+needs to be installed in a particular directory structure \*(-- e.g.,
+with \fIbin\fR, \fIlib\fR, and \fIman\fR subdirectories.
+.PP
+A \*(L"target directory\*(R" is the root of a tree in which one or more
+packages wish to \fBappear\fR to be installed. A common, but by no means
+the only such location is \fI/usr/local\fR.  The examples in this manual
+page will use \fI/usr/local\fR as the target directory.
+.PP
+A \*(L"stow directory\*(R" is the root of a tree containing separate
+packages in private subtrees. When Stow runs, it uses the current
+directory as the default stow directory. The examples in this manual
+page will use \fI/usr/local/stow\fR as the stow directory, so that
+individual packages will be, for example, \fI/usr/local/stow/perl\fR and
+\&\fI/usr/local/stow/emacs\fR.
+.PP
+An \*(L"installation image\*(R" is the layout of files and directories
+required by a package, relative to the target directory. Thus, the
+installation image for Perl includes: a \fIbin\fR directory containing
+\&\fIperl\fR and \fIa2p\fR (among others); an \fIinfo\fR directory containing
+Texinfo documentation; a \fIlib/perl\fR directory containing Perl
+libraries; and a \fIman/man1\fR directory containing man pages.
+.PP
+A \*(L"package directory\*(R" is the root of a tree containing the
+installation image for a particular package. Each package directory
+must reside in a stow directory \*(-- e.g., the package directory
+\&\fI/usr/local/stow/perl\fR must reside in the stow directory
+\&\fI/usr/local/stow\fR.  The \*(L"name\*(R" of a package is the name of its
+directory within the stow directory \*(-- e.g., \fIperl\fR.
+.PP
+Thus, the Perl executable might reside in
+\&\fI/usr/local/stow/perl/bin/perl\fR, where \fI/usr/local\fR is the target
+directory, \fI/usr/local/stow\fR is the stow directory,
+\&\fI/usr/local/stow/perl\fR is the package directory, and \fIbin/perl\fR
+within is part of the installation image.
+.PP
+A \*(L"symlink\*(R" is a symbolic link. A symlink can be \*(L"relative\*(R" or
+\&\*(L"absolute\*(R". An absolute symlink names a full path; that is, one
+starting from \fI/\fR.  A relative symlink names a relative path; that
+is, one not starting from \fI/\fR.  The target of a relative symlink is
+computed starting from the symlink's own directory.  Stow only creates
+relative symlinks.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The stow directory is assumed to be the value of the \f(CW\*(C`STOW_DIR\*(C'\fR
+environment variable or if unset the current directory, and the target
+directory is assumed to be the parent of the current directory (so it
+is typical to execute \fIstow\fR from the directory \fI/usr/local/stow\fR).
+Each \fIpackage\fR given on the command line is the name of a package in
+the stow directory (e.g., \fIperl\fR).  By default, they are installed
+into the target directory (but they can be deleted instead using
+\&\f(CW\*(C`\-D\*(C'\fR).
+.IP "\-n" 4
+.IX Item "-n"
+.PD 0
+.IP "\-\-no" 4
+.IX Item "--no"
+.PD
+Do not perform any operations that modify the filesystem; merely show
+what would happen.
+.IP "\-d \s-1DIR\s0" 4
+.IX Item "-d DIR"
+.PD 0
+.IP "\-\-dir=DIR" 4
+.IX Item "--dir=DIR"
+.PD
+Set the stow directory to \f(CW\*(C`DIR\*(C'\fR instead of the current directory.
+This also has the effect of making the default target directory be the
+parent of \f(CW\*(C`DIR\*(C'\fR.
+.IP "\-t \s-1DIR\s0" 4
+.IX Item "-t DIR"
+.PD 0
+.IP "\-\-target=DIR" 4
+.IX Item "--target=DIR"
+.PD
+Set the target directory to \f(CW\*(C`DIR\*(C'\fR instead of the parent of the stow
+directory.
+.IP "\-v" 4
+.IX Item "-v"
+.PD 0
+.IP "\-\-verbose[=N]" 4
+.IX Item "--verbose[=N]"
+.PD
+Send verbose output to standard error describing what Stow is
+doing. Verbosity levels are 0, 1, 2, 3, and 4; 0 is the default.
+Using \f(CW\*(C`\-v\*(C'\fR or \f(CW\*(C`\-\-verbose\*(C'\fR increases the verbosity by one; using
+`\-\-verbose=N' sets it to N.
+.IP "\-S" 4
+.IX Item "-S"
+.PD 0
+.IP "\-\-stow" 4
+.IX Item "--stow"
+.PD
+Stow the packages that follow this option into the target directory.
+This is the default action and so can be omitted if you are only
+stowing packages rather than performing a mixture of
+stow/delete/restow actions.
+.IP "\-D" 4
+.IX Item "-D"
+.PD 0
+.IP "\-\-delete" 4
+.IX Item "--delete"
+.PD
+Unstow the packages that follow this option from the target directory rather
+than installing them.
+.IP "\-R" 4
+.IX Item "-R"
+.PD 0
+.IP "\-\-restow" 4
+.IX Item "--restow"
+.PD
+Restow packages (first unstow, then stow again). This is useful
+for pruning obsolete symlinks from the target tree after updating
+the software in a package.
+.IP "\-\-adopt" 4
+.IX Item "--adopt"
+\&\fBWarning!\fR  This behaviour is specifically intended to alter the
+contents of your stow directory.  If you do not want that, this option
+is not for you.
+.Sp
+When stowing, if a target is encountered which already exists but is a
+plain file (and hence not owned by any existing stow package), then
+normally Stow will register this as a conflict and refuse to proceed.
+This option changes that behaviour so that the file is moved to the
+same relative place within the package's installation image within the
+stow directory, and then stowing proceeds as before.  So effectively,
+the file becomes adopted by the stow package, without its contents
+changing.
+.IP "\-\-no\-folding" 4
+.IX Item "--no-folding"
+Disable folding of newly stowed directories when stowing, and
+refolding of newly foldable directories when unstowing.
+.IP "\-\-ignore=REGEX" 4
+.IX Item "--ignore=REGEX"
+Ignore files ending in this Perl regex.
+.IP "\-\-defer=REGEX" 4
+.IX Item "--defer=REGEX"
+Don't stow files beginning with this Perl regex if the file is already
+stowed to another package.
+.IP "\-\-override=REGEX" 4
+.IX Item "--override=REGEX"
+Force stowing files beginning with this Perl regex if the file is
+already stowed to another package.
+.IP "\-V" 4
+.IX Item "-V"
+.PD 0
+.IP "\-\-version" 4
+.IX Item "--version"
+.PD
+Show Stow version number, and exit.
+.IP "\-h" 4
+.IX Item "-h"
+.PD 0
+.IP "\-\-help" 4
+.IX Item "--help"
+.PD
+Show Stow command syntax, and exit.
+.SH "INSTALLING PACKAGES"
+.IX Header "INSTALLING PACKAGES"
+The default action of Stow is to install a package. This means
+creating symlinks in the target tree that point into the package tree.
+Stow attempts to do this with as few symlinks as possible; in other
+words, if Stow can create a single symlink that points to an entire
+subtree within the package tree, it will choose to do that rather than
+create a directory in the target tree and populate it with symlinks.
+.PP
+For example, suppose that no packages have yet been installed in
+\&\fI/usr/local\fR; it's completely empty (except for the \fIstow\fR
+subdirectory, of course). Now suppose the Perl package is installed.
+Recall that it includes the following directories in its installation
+image: \fIbin\fR; \fIinfo\fR; \fIlib/perl\fR; \fIman/man1\fR.  Rather than
+creating the directory \fI/usr/local/bin\fR and populating it with
+symlinks to \fI../stow/perl/bin/perl\fR and \fI../stow/perl/bin/a2p\fR (and
+so on), Stow will create a single symlink, \fI/usr/local/bin\fR, which
+points to \fIstow/perl/bin\fR.  In this way, it still works to refer to
+\&\fI/usr/local/bin/perl\fR and \fI/usr/local/bin/a2p\fR, and fewer symlinks
+have been created. This is called \*(L"tree folding\*(R", since an entire
+subtree is \*(L"folded\*(R" into a single symlink.
+.PP
+To complete this example, Stow will also create the symlink
+\&\fI/usr/local/info\fR pointing to \fIstow/perl/info\fR; the symlink
+\&\fI/usr/local/lib\fR pointing to \fIstow/perl/lib\fR; and the symlink
+\&\fI/usr/local/man\fR pointing to \fIstow/perl/man\fR.
+.PP
+Now suppose that instead of installing the Perl package into an empty
+target tree, the target tree is not empty to begin with. Instead, it
+contains several files and directories installed under a different
+system-administration philosophy. In particular, \fI/usr/local/bin\fR
+already exists and is a directory, as are \fI/usr/local/lib\fR and
+\&\fI/usr/local/man/man1\fR.  In this case, Stow will descend into
+\&\fI/usr/local/bin\fR and create symlinks to \fI../stow/perl/bin/perl\fR and
+\&\fI../stow/perl/bin/a2p\fR (etc.), and it will descend into
+\&\fI/usr/local/lib\fR and create the tree-folding symlink \fIperl\fR pointing
+to \fI../stow/perl/lib/perl\fR, and so on. As a rule, Stow only descends
+as far as necessary into the target tree when it can create a
+tree-folding symlink.
+.PP
+The time often comes when a tree-folding symlink has to be undone
+because another package uses one or more of the folded subdirectories
+in its installation image. This operation is called \*(L"splitting open\*(R"
+a folded tree. It involves removing the original symlink from the
+target tree, creating a true directory in its place, and then
+populating the new directory with symlinks to the newly-installed
+package \fBand\fR to the old package that used the old symlink. For
+example, suppose that after installing Perl into an empty
+\&\fI/usr/local\fR, we wish to install Emacs.  Emacs's installation image
+includes a \fIbin\fR directory containing the \fIemacs\fR and \fIetags\fR
+executables, among others. Stow must make these files appear to be
+installed in \fI/usr/local/bin\fR, but presently \fI/usr/local/bin\fR is a
+symlink to \fIstow/perl/bin\fR.  Stow therefore takes the following
+steps: the symlink \fI/usr/local/bin\fR is deleted; the directory
+\&\fI/usr/local/bin\fR is created; links are made from \fI/usr/local/bin\fR to
+\&\fI../stow/emacs/bin/emacs\fR and \fI../stow/emacs/bin/etags\fR; and links
+are made from \fI/usr/local/bin\fR to \fI../stow/perl/bin/perl\fR and
+\&\fI../stow/perl/bin/a2p\fR.
+.PP
+When splitting open a folded tree, Stow makes sure that the symlink
+it is about to remove points inside a valid package in the current stow
+directory.
+.SS "Stow will never delete anything that it doesn't own."
+.IX Subsection "Stow will never delete anything that it doesn't own."
+Stow \*(L"owns\*(R" everything living in the target tree that points into a
+package in the stow directory. Anything Stow owns, it can recompute if
+lost. Note that by this definition, Stow doesn't \*(L"own\*(R" anything
+\&\fBin\fR the stow directory or in any of the packages.
+.PP
+If Stow needs to create a directory or a symlink in the target tree
+and it cannot because that name is already in use and is not owned by
+Stow, then a conflict has arisen. See the \*(L"Conflicts\*(R" section in the
+info manual.
+.SH "DELETING PACKAGES"
+.IX Header "DELETING PACKAGES"
+When the \f(CW\*(C`\-D\*(C'\fR option is given, the action of Stow is to delete a
+package from the target tree. Note that Stow will not delete anything
+it doesn't \*(L"own\*(R". Deleting a package does \fBnot\fR mean removing it from
+the stow directory or discarding the package tree.
+.PP
+To delete a package, Stow recursively scans the target tree, skipping
+over the stow directory (since that is usually a subdirectory of the
+target tree) and any other stow directories it encounters (see
+\&\*(L"Multiple stow directories\*(R" in the info manual). Any symlink it
+finds that points into the package being deleted is removed. Any
+directory that contained only symlinks to the package being deleted is
+removed. Any directory that, after removing symlinks and empty
+subdirectories, contains only symlinks to a single other package, is
+considered to be a previously \*(L"folded\*(R" tree that was \*(L"split open.\*(R"
+Stow will re-fold the tree by removing the symlinks to the surviving
+package, removing the directory, then linking the directory back to
+the surviving package.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The full documentation for \fIstow\fR is maintained as a Texinfo manual.
+If the \fIinfo\fR and \fIstow\fR programs are properly installed at your site, the command
+.PP
+.Vb 1
+\&    info stow
+.Ve
+.PP
+should give you access to the complete manual.
+.SH "BUGS"
+.IX Header "BUGS"
+Please report bugs in Stow using the Debian bug tracking system.
+.PP
+Currently known bugs include:
+.IP "\(bu" 4
+The empty-directory problem.
+.Sp
+If package \fIfoo\fR includes an empty directory \*(-- say, \fIfoo/bar\fR \*(--
+then if no other package has a \fIbar\fR subdirectory, everything's fine.
+If another stowed package \fIquux\fR, has a \fIbar\fR subdirectory, then
+when stowing, \fItargetdir/bar\fR will be \*(L"split open\*(R" and the contents
+of \fIquux/bar\fR will be individually stowed.  So far, so good. But when
+unstowing \fIquux\fR, \fItargetdir/bar\fR will be removed, even though
+\&\fIfoo/bar\fR needs it to remain.  A workaround for this problem is to
+create a file in \fIfoo/bar\fR as a placeholder. If you name that file
+\&\fI.placeholder\fR, it will be easy to find and remove such files when
+this bug is fixed.
+.IP "\(bu" 4
+When using multiple stow directories (see \*(L"Multiple stow directories\*(R"
+in the info manual), Stow fails to \*(L"split open\*(R" tree-folding symlinks
+(see \*(L"Installing packages\*(R" in the info manual) that point into a stow
+directory which is not the one in use by the current Stow
+command. Before failing, it should search the target of the link to
+see whether any element of the path contains a \fI.stow\fR file. If it
+finds one, it can \*(L"learn\*(R" about the cooperating stow directory to
+short-circuit the \fI.stow\fR search the next time it encounters a
+tree-folding symlink.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+This man page was originally constructed by Charles Briscoe-Smith from
+parts of Stow's info manual, and then converted to \s-1POD\s0 format by Adam
+Spiers.  The info manual contains the following notice, which, as it
+says, applies to this manual page, too.  The text of the section
+entitled \*(L"\s-1GNU\s0 General Public License\*(R" can be found in the file
+\&\fI/usr/share/common\-licenses/GPL\fR on any Debian GNU/Linux system.  If
+you don't have access to a Debian system, or the \s-1GPL\s0 is not there,
+write to the Free Software Foundation, Inc., 59 Temple Place, Suite
+330, Boston, \s-1MA, 02111\-1307, USA.\s0
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C)
+1993, 1994, 1995, 1996 by Bob Glickstein <bobg+stow@zanshin.com>;
+2000, 2001 by Guillaume Morin;
+2007 by Kahlil Hodgson;
+2011 by Adam Spiers;
+and others.
+.PP
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the section entitled \*(L"\s-1GNU\s0 General Public License\*(R" is included with the
+modified manual, and provided that the entire resulting derived work
+is distributed under the terms of a permission notice identical to
+this one.
+.PP
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.

.local/share/perl/Stow/Util.pm

@@ -0,0 +1,208 @@
+package Stow::Util;
+
+=head1 NAME
+
+Stow::Util - general utilities
+
+=head1 SYNOPSIS
+
+    use Stow::Util qw(debug set_debug_level error ...);
+
+=head1 DESCRIPTION
+
+Supporting utility routines for L<Stow>.
+
+=cut
+
+use strict;
+use warnings;
+
+use POSIX qw(getcwd);
+
+use base qw(Exporter);
+our @EXPORT_OK = qw(
+    error debug set_debug_level set_test_mode
+    join_paths parent canon_path restore_cwd
+);
+
+our $ProgramName = 'stow';
+our $VERSION = '2.2.2';
+
+#############################################################################
+#
+# General Utilities: nothing stow specific here.
+#
+#############################################################################
+
+=head1 IMPORTABLE SUBROUTINES
+
+=head2 error($format, @args)
+
+Outputs an error message in a consistent form and then dies.
+
+=cut
+
+sub error {
+    my ($format, @args) = @_;
+    die "$ProgramName: ERROR: " . sprintf($format, @args) . "\n";
+}
+
+=head2 set_debug_level($level)
+
+Sets verbosity level for C<debug()>.
+
+=cut
+
+our $debug_level = 0;
+
+sub set_debug_level {
+    my ($level) = @_;
+    $debug_level = $level;
+}
+
+=head2 set_test_mode($on_or_off)
+
+Sets testmode on or off.
+
+=cut
+
+our $test_mode = 0;
+
+sub set_test_mode {
+    my ($on_or_off) = @_;
+    if ($on_or_off) {
+        $test_mode = 1;
+    }
+    else {
+        $test_mode = 0;
+    }
+}
+
+=head2 debug($level, $msg)
+
+Logs to STDERR based on C<$debug_level> setting.  C<$level> is the
+minimum verbosity level required to output C<$msg>.  All output is to
+STDERR to preserve backward compatibility, except for in test mode,
+when STDOUT is used instead.  In test mode, the verbosity can be
+overridden via the C<TEST_VERBOSE> environment variable.
+
+Verbosity rules:
+
+=over 4
+
+=item    0: errors only
+
+=item >= 1: print operations: LINK/UNLINK/MKDIR/RMDIR/MV
+
+=item >= 2: print operation exceptions
+
+e.g. "_this_ already points to _that_", skipping, deferring,
+overriding, fixing invalid links
+
+=item >= 3: print trace detail: trace: stow/unstow/package/contents/node
+
+=item >= 4: debug helper routines
+
+=item >= 5: debug ignore lists
+
+=back
+
+=cut
+
+sub debug {
+    my ($level, $msg) = @_;
+    if ($debug_level >= $level) {
+        if ($test_mode) {
+            print "# $msg\n";
+        }
+        else {
+            warn "$msg\n";
+        }
+    }
+}
+
+#===== METHOD ===============================================================
+# Name      : join_paths()
+# Purpose   : concatenates given paths
+# Parameters: path1, path2, ... => paths
+# Returns   : concatenation of given paths
+# Throws    : n/a
+# Comments  : factors out redundant path elements:
+#           : '//' => '/' and 'a/b/../c' => 'a/c'
+#============================================================================
+sub join_paths {
+    my @paths = @_;
+
+    # weed out empty components and concatenate
+    my $result = join '/', grep {! /\A\z/} @paths;
+
+    # factor out back references and remove redundant /'s)
+    my @result = ();
+    PART:
+    for my $part (split m{/+}, $result) {
+        next PART if $part eq '.';
+        if (@result && $part eq '..' && $result[-1] ne '..') {
+            pop @result;
+        }
+        else {
+            push @result, $part;
+        }
+    }
+
+    return join '/', @result;
+}
+
+#===== METHOD ===============================================================
+# Name      : parent
+# Purpose   : find the parent of the given path
+# Parameters: @path => components of the path
+# Returns   : returns a path string
+# Throws    : n/a
+# Comments  : allows you to send multiple chunks of the path
+#           : (this feature is currently not used)
+#============================================================================
+sub parent {
+    my @path = @_;
+    my $path = join '/', @_;
+    my @elts = split m{/+}, $path;
+    pop @elts;
+    return join '/', @elts; 
+}
+
+#===== METHOD ===============================================================
+# Name      : canon_path
+# Purpose   : find absolute canonical path of given path
+# Parameters: $path
+# Returns   : absolute canonical path
+# Throws    : n/a
+# Comments  : is this significantly different from File::Spec->rel2abs?
+#============================================================================
+sub canon_path {
+    my ($path) = @_;
+
+    my $cwd = getcwd();
+    chdir($path) or error("canon_path: cannot chdir to $path from $cwd");
+    my $canon_path = getcwd();
+    restore_cwd($cwd);
+
+    return $canon_path;
+}
+
+sub restore_cwd {
+    my ($prev) = @_;
+    chdir($prev) or error("Your current directory $prev seems to have vanished");
+}
+
+=head1 BUGS
+
+=head1 SEE ALSO
+
+=cut
+
+1;
+
+# Local variables:
+# mode: perl
+# cperl-indent-level: 4
+# end:
+# vim: ft=perl