convert INSTALL to Markdown

3 files changed, 176 insertions, 173 deletions

diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index d00e279..0000000
--- a/INSTALL
+++ /dev/null
@@ -1,172 +0,0 @@
-Prerequisites
-=============
-
-Stow is a collection of Perl scripts and modules.  You must have Perl
-5.6.1 or later in order for it to run.  The test suite also requires
-the Test::More and Test::Output modules which can be obtained from
-CPAN.  They are also available as packages in some of the GNU/Linux
-distributions.
-
-Installation methods
-====================
-
-Stow can either be installed via the standard GNU Autotools procedure
-(./configure, make install) or since 2.1.0, via CPAN-style via
-Module::Build.
-
-Advantages of the Autotools approach:
-
-  - It's arguably more flexible.
-
-  - It will install the documentation in Info, HTML, man, and PDF
-    formats.
-
-Advantages of the Module::Build approach:
-
-  - It's more in keeping with the standard way to distribute CPAN
-    modules.
-
-  - It performs dependency checking to ensure you have the necessary
-    Perl modules installed.
-
-Basic Installation via Module::Build
-====================================
-
-The steps in building Stow are:
-
-1.  `cd' to the directory containing the source code (and this file).
-
-2.  If you are building from an official GNU release tarball, type
-    `./configure && make' to configure stow for your system.  If you
-    are building from a CPAN tarball, this step can be skipped.
-
-    If `make' warns that the Perl module installation directory is
-    not in @INC, then you should run:
-
-      eval `perl -V:siteprefix`
-      ./configure --prefix=$siteprefix && make
-
-    to avoid a superfluous "use lib" line in your stow executable.
-
-3.  Type `perl Build.PL'.
-
-4.  Type `./Build install' to install the various files.  As noted
-    above, this installs fewer files than the Autotools installation.
-
-Basic Installation via Autotools
-================================
-
-The steps in building Stow are:
-
-1.  `cd' to the directory containing the source code (and this file).
-
-2.  Type `./configure' to configure stow for your system.  This step
-    will attempt to locate your copy of perl and set its location in
-    `Makefile.in'.  You can use the normal arguments to change the
-    default installation paths (see below); additionally you can use
-    the
-
-      --with-pmdir=/path/to/perl/modules
-
-    option to manually choose where the Perl modules get installed.
-    However, if you don't, the configure script will go to great
-    lengths to try to choose a sensible default.
-
-3.  Type `make install' to install the various files.  If the chosen
-    installation directory for Perl modules is not included in Perl's
-    built-in @INC search path, the Makefile rules will automatically
-    insert a
-
-      use lib "...";
-
-    line into the generated stow script to ensure that it can always
-    locate the Perl modules without needing to manually set PERL5LIB.
-
-4.  You can remove the generated files from the source code directory
-    by typing `make clean'.  To also remove the files that `configure'
-    created (so you can compile the package for a different computer),
-    type `make distclean'.  There is also a `make maintainer-clean'
-    target, but that is intended mainly for stow's developers.  If you
-    use it, you may have to get all sorts of other programs in order
-    to regenerate files that came with the distribution.
-
-Installation Names
-==================
-
-By default, `make install' will install the package's files in
-`/usr/local/bin' and `/usr/local/info'.  You can specify an
-installation prefix other than `/usr/local' by giving `configure' the
-option `--prefix=PATH'.
-
-If the package supports it, you can cause programs to be installed
-with an extra prefix or suffix on their names by giving `configure'
-the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
-
-Since `stow' is concerned with separating a package's installation
-tree from its run-time tree, you might want to install `stow' into a
-directory such as `/usr/local/stow/stow' but have it run out of
-`/usr/local'.  Do this by giving the run-time prefix (e.g.,
-/usr/local) to configure as described above; then run `make'; then run
-`make install prefix=/usr/local/stow/stow'.  For more information on
-this technique, see the Stow manual.
-
-The configuration system
-========================
-
-The `configure' shell script attempts to guess correct values for
-various system-dependent variables used during compilation.  It uses
-those values to create a `Makefile' and to create the `stow' script
-itself, using Makefile.in and stow.in as templates.  Finally, it
-creates a shell script `config.status' that you can run in the future
-to recreate the current configuration, a file `config.cache' that
-saves the results of its tests to speed up reconfiguring, and a file
-`config.log' containing other output.
-
-The file `configure.ac' is used to create `configure' by a program
-called `autoconf'.  You only need `configure.ac' if you want to change
-it or regenerate `configure' using a newer version of `autoconf'.
-
-The file `Makefile.am' is used to create `Makefile.in' by a program
-called `automake'.  You only need `Makefile.am' if you want to change
-it or regenerate `Makefile.in' using a newer version of `automake'.
-
-Sharing Defaults
-================
-
-If you want to set default values for `configure' scripts to share,
-you can create a site shell script called `config.site' that gives
-default values for variables like `CC', `cache_file', and `prefix'.
-`configure' looks for `PREFIX/share/config.site' if it exists, then
-`PREFIX/etc/config.site' if it exists.  Or, you can set the
-`CONFIG_SITE' environment variable to the location of the site script.
-A warning: not all `configure' scripts look for a site script.
-
-Operation Controls
-==================
-
-   `configure' recognizes the following options to control how it
-operates.
-
-`--cache-file=FILE'
-     Use and save the results of the tests in FILE instead of
-     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
-     debugging `configure'.
-
-`--help'
-     Print a summary of the options to `configure', and exit.
-
-`--quiet'
-`--silent'
-`-q'
-     Do not print messages saying which checks are being made.
-
-`--srcdir=DIR'
-     Look for the package's source code in directory DIR.  Usually
-     `configure' can determine that directory automatically.
-
-`--version'
-     Print the version of Autoconf used to generate the `configure'
-     script, and exit.
-
-`configure' also accepts some other, not widely useful, options.
-
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..f962755
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,175 @@
+How to install GNU Stow
+=======================
+
+Prerequisites
+-------------
+
+Stow is a collection of Perl scripts and modules.  You must have Perl
+5.6.1 or later in order for it to run.  The test suite also requires
+the `Test::More` and `Test::Output` modules which can be obtained from
+CPAN.  They are also available as packages in some of the GNU/Linux
+distributions.
+
+Installation methods
+--------------------
+
+Stow can either be installed via the standard GNU Autotools procedure
+(`./configure && make install`) or since 2.1.0, via CPAN-style via
+Module::Build.
+
+Advantages of the Autotools approach:
+
+  - It's arguably more flexible.
+
+  - It will install the documentation in Info, HTML, man, and PDF
+    formats.
+
+Advantages of the `Module::Build` approach:
+
+  - It's more in keeping with the standard way to distribute CPAN
+    modules.
+
+  - It performs dependency checking to ensure you have the necessary
+    Perl modules installed.
+
+Basic Installation via `Module::Build`
+--------------------------------------
+
+The steps in building Stow are:
+
+1.  `cd` to the directory containing the source code (and this file).
+
+2.  If you are building from an official GNU release tarball, type
+    `./configure && make` to configure stow for your system.  If you
+    are building from a CPAN tarball, this step can be skipped.
+
+    If `make` warns that the Perl module installation directory is
+    not in `@INC`, then you should run:
+
+        eval `perl -V:siteprefix`
+        ./configure --prefix=$siteprefix && make
+
+    to avoid a superfluous `use lib` line in your stow executable.
+
+3.  Type `perl Build.PL`.
+
+4.  Type `./Build install` to install the various files.  As noted
+    above, this installs fewer files than the Autotools installation.
+
+Basic Installation via Autotools
+--------------------------------
+
+The steps in building Stow are:
+
+1.  `cd` to the directory containing the source code (and this file).
+
+2.  Type `./configure` to configure stow for your system.  This step
+    will attempt to locate your copy of perl and set its location in
+    `Makefile.in`.  You can use the normal arguments to change the
+    default installation paths (see below); additionally you can use
+    the
+
+        --with-pmdir=/path/to/perl/modules
+
+    option to manually choose where the Perl modules get installed.
+    However, if you don't, the `configure` script will go to great
+    lengths to try to choose a sensible default.
+
+3.  Type `make install` to install the various files.  If the chosen
+    installation directory for Perl modules is not included in Perl's
+    built-in `@INC` search path, the Makefile rules will automatically
+    insert a
+
+        use lib "...";
+
+    line into the generated stow script to ensure that it can always
+    locate the Perl modules without needing to manually set `PERL5LIB`.
+
+4.  You can remove the generated files from the source code directory
+    by typing `make clean`.  To also remove the files that `configure`
+    created (so you can compile the package for a different computer),
+    type `make distclean`.  There is also a `make maintainer-clean`
+    target, but that is intended mainly for stow's developers.  If you
+    use it, you may have to get all sorts of other programs in order
+    to regenerate files that came with the distribution.
+
+Installation Names
+------------------
+
+By default, `make install` will install the package's files in
+`/usr/local/bin` and `/usr/local/info`.  You can specify an
+installation prefix other than `/usr/local` by giving `configure` the
+option `--prefix=PATH`.
+
+If the package supports it, you can cause programs to be installed
+with an extra prefix or suffix on their names by giving `configure`
+the option `--program-prefix=PREFIX` or `--program-suffix=SUFFIX`.
+
+Since `stow` is concerned with separating a package's installation
+tree from its run-time tree, you might want to install `stow` into a
+directory such as `/usr/local/stow/stow` but have it run out of
+`/usr/local`.  Do this by giving the run-time prefix (e.g.,
+/usr/local) to configure as described above; then run `make`; then run
+`make install prefix=/usr/local/stow/stow`.  For more information on
+this technique, see the Stow manual.
+
+The configuration system
+------------------------
+
+The `configure` shell script attempts to guess correct values for
+various system-dependent variables used during compilation.  It uses
+those values to create a `Makefile` and to create the `stow` script
+itself, using Makefile.in and stow.in as templates.  Finally, it
+creates a shell script `config.status` that you can run in the future
+to recreate the current configuration, a file `config.cache` that
+saves the results of its tests to speed up reconfiguring, and a file
+`config.log` containing other output.
+
+The file `configure.ac` is used to create `configure` by a program
+called `autoconf`.  You only need `configure.ac` if you want to change
+it or regenerate `configure` using a newer version of `autoconf`.
+
+The file `Makefile.am` is used to create `Makefile.in` by a program
+called `automake`.  You only need `Makefile.am` if you want to change
+it or regenerate `Makefile.in` using a newer version of `automake`.
+
+Sharing Defaults
+----------------
+
+If you want to set default values for `configure` scripts to share,
+you can create a site shell script called `config.site` that gives
+default values for variables like `CC`, `cache_file`, and `prefix`.
+`configure` looks for `PREFIX/share/config.site` if it exists, then
+`PREFIX/etc/config.site` if it exists.  Or, you can set the
+`CONFIG_SITE` environment variable to the location of the site script.
+A warning: not all `configure` scripts look for a site script.
+
+Operation Controls
+------------------
+
+`configure` recognizes the following options to control how it
+operates.
+
+`--cache-file=FILE`
+     Use and save the results of the tests in FILE instead of
+     `./config.cache`.  Set FILE to `/dev/null` to disable caching, for
+     debugging `configure`.
+
+`--help`
+     Print a summary of the options to `configure`, and exit.
+
+`--quiet`
+`--silent`
+`-q`
+     Do not print messages saying which checks are being made.
+
+`--srcdir=DIR`
+     Look for the package's source code in directory DIR.  Usually
+     `configure` can determine that directory automatically.
+
+`--version`
+     Print the version of Autoconf used to generate the `configure`
+     script, and exit.
+
+`configure` also accepts some other, not widely useful, options.
+
diff --git a/README.md b/README.md
index 9d0a5f1..4f8e816 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@ which can be found in the file [`COPYING`](COPYING).
 Installation
 ------------
 
-See [`INSTALL`](INSTALL) for installation instructions.
+See [`INSTALL.md`](INSTALL.md) for installation instructions.
 
 Feedback
 --------