Permalink
Browse files

Revamp README.

  • Loading branch information...
1 parent af36a44 commit b6f9ef2b2fb4ce11a28ec389dd620ede52ed948d @aspiers committed Mar 1, 2012
Showing with 47 additions and 21 deletions.
  1. +47 −21 README
View
68 README
@@ -1,27 +1,53 @@
-This is GNU Stow, a program for managing the installation of software
-packages, keeping them separate (/usr/local/stow/emacs vs.
-/usr/local/stow/perl, for example) while making them appear to be
-installed in the same place (/usr/local). Stow doesn't store an extra
-state between runs, so there's no danger of mangling directories when
-file hierarchies don't match the database. Also, stow will never
-delete any files, directories, or links that appear in a stow
-directory, so it is always possible to rebuild the target tree.
+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.
-You can get the latest information about Stow from
-http://www.gnu.org/software/stow/stow.html
+Feedback
+--------
-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).
+Please do send comments, questions, and constructive criticism. The
+mailing lists and any other communication channels are detailed on the
+above home page.
-Stow is free software, licensed under the GNU General Public License, which
-can be found in the file COPYING.
+Brief history
+-------------
-Please mail comments, questions, and criticisms to the current maintainers
-via help-stow@gnu.org or bug-stow@gnu.org.
+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).

0 comments on commit b6f9ef2

Please sign in to comment.