Documented building and installation of flexwestes-install

Since GNU autotools no longer provides a stock INSTALLATION file, we provide one that speaks to flex specifically.

fixes #402

4 files changed, 69 insertions, 44 deletions

diff --git a/.gitignore b/.gitignore
index e92979c..daf0ef9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,7 +8,6 @@
 .libs
 ABOUT-NLS
 ChangeLog
-INSTALL
 Makefile
 Makefile.in
 aclocal.m4
diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..d103bd6
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,67 @@
+# INSTALLING Flex
+
+## Should you be here at all?
+
+If building, developing or compiling C programs is new to you, you probably want to use your operating system's standard means of installing software to install flex. If you do not need the latest features of flex, you probably just want to use your operating system's standard means of installing software to obtain flex.
+
+## Now that you know you should be here ...
+
+If  you are not familiar with bootstrapping C code from a git repository or if GNU autotools seems like a jumble of tenuous incantationery to you, then make sure that you downloaded one of the release tar archives of flex. You can verify this by checking the filename of what you downloaded. If it is something like "flex-<version>.tar.<compressiontype>" then you have a release tar archives. If you have a filename like "flex.tar.gz" or "flex.zip", you have a copy of the git repository and you didn't download the thing you wanted to.
+
+## Building from a release archive
+
+To build flex from a release archive:
+
+$ ./configure <any configure options you need>
+$ make
+
+To see what options are available from the configure script:
+
+$ ./configure --help
+
+Optionally run the test suite:
+
+$ make check
+
+To install the flex you just built:
+
+$ make install
+
+Note that you may want to make use of the DESTDIR argument on the "make install" command line or that you may want to have used the "--prefix" argument with configure (or mostly equivalently the "prefix" argument on the make command line).
+
+## Building from the git repository
+
+To build from the git repository:
+
+First, make sure you have a copy of flex installed somewhere on your path so that configure can find it. You can usually do this with your operating system's standard means of installing software. Sometimes, you have to build from a recent release of flex, however.
+
+You will also need all the programs that flex needs in order to be built from scratch --
+
+* compiler suite - flex is built with gcc
+* bash, or a good Bourne-style shell
+* m4 - `m4 -P` needs to work; GNU m4 and a few others are suitable
+* GNU bison;  to generate parse.c from parse.y
+* autoconf; for handling the build system
+* automake; for Makefile generation
+* gettext; for i18n support
+* help2man; to generate the flex man page
+* tar, gzip, lzip, etc.; for packaging of the source distribution
+* GNU texinfo; to build and test the flex manual. Note that if you want
+  to build the dvi/ps/pdf versions of the documentation you will need
+  texi2dvi and related programs, along with a sufficiently powerful
+  implementation of TeX to process them. See your operating system
+  documentation for how to achieve this. The printable versions of the
+  manual are not built unless specifically requested, but the targets
+  are included by automake.
+* GNU indent; for indenting the flex source the way we want it done
+
+In cases where the versions of the above tools matter, the file
+configure.ac will specify the minimum required versions.
+
+Then:
+
+$ ./autogen.sh
+
+After autogen.sh finishes successfully, building flex follows the same steps as building flex from a release archive.
+
+Note that, in addition to "make check", "make distcheck" builds a release archive and builds and tests flex from inside a directory containing only known distributed files.
diff --git a/Makefile.am b/Makefile.am
index 409ab7d..d1628af 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -38,7 +38,8 @@ dist_doc_DATA = \
 	README.md
 
 EXTRA_DIST = \
-	.indent.pro
+	.indent.pro \
+	INSTALL
 
 dist_noinst_SCRIPTS = \
 	autogen.sh \
diff --git a/README.md b/README.md
index d586360..bfdf424 100644
--- a/README.md
+++ b/README.md
@@ -42,48 +42,6 @@ interest:
 * tests/ - regression tests. See TESTS/README for details.
 * po/ - internationalization support files.
 
-You need the following tools to build flex from the maintainer's
-repository:
-
-* compiler suite - flex is built with gcc
-* bash, or a good Bourne-style shell
-* m4 - `m4 -P` needs to work; GNU m4 and a few others are suitable
-* GNU bison;  to generate parse.c from parse.y
-* autoconf; for handling the build system
-* automake; for Makefile generation
-* gettext; for i18n support
-* help2man; to generate the flex man page
-* tar, gzip, lzip, etc.; for packaging of the source distribution
-* GNU texinfo; to build and test the flex manual. Note that if you want
-  to build the dvi/ps/pdf versions of the documentation you will need
-  texi2dvi and related programs, along with a sufficiently powerful
-  implementation of TeX to process them. See your operating system
-  documentation for how to achieve this. The printable versions of the
-  manual are not built unless specifically requested, but the targets
-  are included by automake.
-* GNU indent; for indenting the flex source the way we want it done
-
-In cases where the versions of the above tools matter, the file
-configure.ac will specify the minimum required versions.
-
-Once you have all the necessary tools installed, life becomes
-simple. To prepare the flex tree for building, run the script:
-
-```bash
-./autogen.sh
-```
-
-in the top level of the flex source tree.
-
-This script calls the various tools needed to get flex ready for the
-GNU-style configure script to be able to work.
-
-From this point on, building flex follows the usual routine:
-
-```bash
-configure && make && make install
-```
-
 ---
 
 This file is part of flex.