Fix old descriptions of Stow (#22)

De-emphasise the package management aspects, since these days
almost everyone prefers to use modern package managers such as
rpm / dpkg / Nix for (system-wide) package management.

Also include more popular modern use cases for Stow such as management
of dotfiles and software compiled in the user's $HOME directory.

Fixes #22: https://github.com/aspiers/stow/issues/22

4 files changed, 114 insertions, 64 deletions

diff --git a/README.md b/README.md
index 29d760d..bde1cf0 100644
--- a/README.md
+++ b/README.md
@@ -4,19 +4,54 @@
 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
+This README describes GNU Stow.  This is not the definitive
+documentation for Stow; for that, see the [info
+manual](https://www.gnu.org/software/stow/manual/).
+
+Stow is a symlink farm manager program which takes distinct sets
+of software and/or data located in separate directories on the
+filesystem, and makes them all appear to be installed in a single
+directory tree.
+
+Originally Stow was born to address the need to administer, upgrade,
+install, and remove files in independent software packages without
+confusing them with other files sharing the same file system space.
+For instance, many years ago it used to be common to compile programs
+such as Perl and Emacs from source and install them in `/usr/local`.
+By using Stow, `/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.
+While this is useful for keeping track of system-wide and per-user
+installations of software built from source, in more recent times
+software packages are often managed by more sophisticated package
+management software such as
+[`rpm`](https://en.wikipedia.org/wiki/Rpm_(software)),
+[`dpkg`](https://en.wikipedia.org/wiki/Dpkg), and
+[Nix](https://en.wikipedia.org/wiki/Nix_package_manager) / [GNU
+Guix](https://en.wikipedia.org/wiki/GNU_Guix), or language-native
+package managers such as Ruby's
+[`gem`](https://en.wikipedia.org/wiki/RubyGems), Python's
+[`pip`](https://en.wikipedia.org/wiki/Pip_(package_manager)),
+Javascript's [`npm`](https://en.wikipedia.org/wiki/Npm_(software)),
+and so on.
+
+However Stow is still used not only for software package management,
+but also for other purposes, such as facilitating [a more controlled
+approach to management of configuration files in the user's home
+directory](http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html),
+especially when [coupled with version control
+systems](http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html).
+
+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., `/usr/local/stow/emacs`), so it's always possible
+to rebuild the target tree (e.g., `/usr/local`).
 
 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.
diff --git a/bin/stow.in b/bin/stow.in
index adff6de..d64c381 100755
--- a/bin/stow.in
+++ b/bin/stow.in
@@ -1,6 +1,6 @@
 #!@PERL@
 
-# GNU Stow - manage the installation of multiple software packages
+# GNU Stow - manage farms of symbolic links
 # Copyright (C) 1993, 1994, 1995, 1996 by Bob Glickstein
 # Copyright (C) 2000, 2001 Guillaume Morin
 # Copyright (C) 2007 Kahlil Hodgson
@@ -21,7 +21,7 @@
 
 =head1 NAME
 
-stow - software package installation manager
+stow - manage farms of symbolic links
 
 =head1 SYNOPSIS
 
@@ -29,33 +29,34 @@ stow [ options ] package ...
 
 =head1 DESCRIPTION
 
-This manual page describes GNU Stow @VERSION@, 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.
+This manual page describes GNU Stow @VERSION@.  This is not the
+definitive documentation for Stow; for that, see the accompanying info
+manual, e.g. by typing C<info stow>.
+
+Stow is a symlink farm manager which takes distinct sets of software
+and/or data located in separate directories on the filesystem, and
+makes them all appear to be installed in a single directory tree.
+
+Originally Stow was born to address the need to administer, upgrade,
+install, and remove files in independent software packages without
+confusing them with other files sharing the same file system space.
+For instance, many years ago it used to be common to compile programs
+such as Perl and Emacs from source.  By using Stow, F</usr/local/bin>
+could contain symlinks to files within F</usr/local/stow/emacs/bin>,
+F</usr/local/stow/perl/bin> etc., and likewise recursively for any
+other subdirectories such as F<.../share>, F<.../man>, and so on.
+
+While this is useful for keeping track of system-wide and per-user
+installations of software built from source, in more recent times
+software packages are often managed by more sophisticated package
+management software such as rpm, dpkg, and Nix / GNU Guix, or
+language-native package managers such as Ruby's gem, Python's pip,
+Javascript's npm, and so on.
+
+However Stow is still used not only for software package management,
+but also for other purposes, such as facilitating a more controlled
+approach to management of configuration files in the user's home
+directory, especially when coupled with version control systems.
 
 Stow was inspired by Carnegie Mellon's Depot program, but is
 substantially simpler and safer. Whereas Depot required database files
@@ -66,6 +67,9 @@ 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>).
 
+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.
+
 =head1 TERMINOLOGY
 
 A "package" is a related collection of files and directories that
diff --git a/doc/stow.texi b/doc/stow.texi
index 118fd77..f7ae2d1 100644
--- a/doc/stow.texi
+++ b/doc/stow.texi
@@ -15,8 +15,7 @@
 
 @copying
 This manual describes GNU Stow version @value{VERSION}
-(@value{UPDATED}), a program for managing the installation of software
-packages.
+(@value{UPDATED}), a program for managing farms of symbolic links.
 
 Software and documentation is copyrighted by the following:
 
@@ -82,10 +81,9 @@ approved by the Free Software Foundation.
 
 @ifinfo
 This manual describes GNU Stow @value{VERSION} (@value{UPDATED}), a
-program for managing sets of symbolic links, in order to make groups
-of related files (such as distinct packages of software, or
-configuration files) in one place in the filesystem appear to be
-located in another place.
+symlink farm manager which takes distinct sets of software and/or data
+located in separate directories on the filesystem, and makes them
+appear to be installed in a single directory tree.
 @end ifinfo
 @end ifnottex
 
@@ -131,19 +129,20 @@ Advice on changing compilation and installation parameters
 @node Introduction, Terminology, Top, Top
 @chapter Introduction
 
-Stow is a tool for managing sets of symbolic links in order to
-facilitate the installation of multiple software packages, or other
-groups of related files, such as configuration files, into a single
+GNU Stow is a symlink farm manager which takes distinct sets of
+software and/or data located in separate directories on the
+filesystem, and makes them all appear to be installed in a single
 directory tree.
 
 Originally Stow was born to address the need to administer, upgrade,
 install, and remove files in independent software packages without
 confusing them with other files sharing the same file system space.
-For instance, it used to be common to compile Perl and Emacs from
-source and install them in @file{/usr/local}.  When one does so, one
-winds up with the following files@footnote{As of Perl 4.036 and Emacs
-19.22.  These are now ancient releases but the example still holds
-valid.} in @file{/usr/local/man/man1}:
+For instance, many years ago it used to be common to compile programs
+such as Perl and Emacs from source and install them in
+@file{/usr/local}.  When one does so, one winds up with the following
+files@footnote{As of Perl 4.036 and Emacs 19.22.  These are now
+ancient releases but the example still holds valid.} in
+@file{/usr/local/man/man1}:
 
 @example
 a2p.1
@@ -171,11 +170,20 @@ tree; i.e. (in the typical case) there should be a @file{bin} directory
 containing executables, a @file{man/man1} directory containing section 1
 man pages, and so on.
 
-In more recent times, software packages are often managed by more
-sophisticated package management software such as
+While this is useful for keeping track of system-wide and per-user
+installations of software built from source, in more recent times
+software packages are often managed by more sophisticated package
+management software such as
 @uref{https://en.wikipedia.org/wiki/Rpm_(software), @command{rpm}},
 @uref{https://en.wikipedia.org/wiki/Dpkg, @command{dpkg}}, and
-@uref{https://en.wikipedia.org/wiki/Nix_package_manager, Nix}.
+@uref{https://en.wikipedia.org/wiki/Nix_package_manager, Nix} /
+@uref{https://en.wikipedia.org/wiki/GNU_Guix, GNU Guix}, or
+language-native package managers such as
+@uref{https://en.wikipedia.org/wiki/RubyGems, Ruby's @command{gem}},
+@uref{https://en.wikipedia.org/wiki/Pip_(package_manager), Python's
+@command{pip}}, @uref{https://en.wikipedia.org/wiki/Npm_(software),
+Javascript's @command{npm}}, and so on.
+
 However Stow is still used not only for software package management,
 but also for other purposes, such as facilitating a more controlled
 approach to management of configuration files in the user's home
@@ -184,13 +192,16 @@ especially when coupled with version control
 systems@footnote{@uref{http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html}}.
 
 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., @file{/usr/local/stow/emacs}), so it's always possible
-to rebuild the target tree (e.g., @file{/usr/local}).
+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., @file{/usr/local/stow/emacs}), so it's always
+possible to rebuild the target tree (e.g., @file{/usr/local}).
+
+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.
 
 For information about the latest version of Stow, you can refer to
 @uref{http://www.gnu.org/software/stow/}.
diff --git a/lib/Stow.pm.in b/lib/Stow.pm.in
index e190c6c..fac2c9c 100755
--- a/lib/Stow.pm.in
+++ b/lib/Stow.pm.in
@@ -4,7 +4,7 @@ package Stow;
 
 =head1 NAME
 
-Stow - manage the installation of multiple software packages
+Stow - manage farms of symbolic links
 
 =head1 SYNOPSIS