Documentation

- Added INSTALL file contents (thanks to jonbobbly).

AUTHORS

@@ -15,4 +15,4 @@ suggestions:
   Fidel Mato
   David Stahl
   David Patrick
-
+  jonbobbly

INSTALL

@@ -7,31 +7,121 @@ Please follow the instructions below to build tasksh with cmake.
 Pre-requisites
 --------------
 
-You will need the CMake build system installed in order to build tasksh
-from source.
+You will need the CMake build system installed in order to build tasksh from
+source.  Information on cmake can be obtained at http://cmake.org
 
-More information on cmake can be obtained at http://cmake.org
+Additionally, you will need:
+
+  libreadline
 
 
 Basic Installation
 ------------------
 
+Briefly, these shell commands will unpack, build and install taskwarrior:
+
+  $ tar xzf tasksh-X.Y.Z.tar.gz                   [1]
+  $ cd tasksh-X.Y.Z                               [2]
+  $ cmake .                                       [3]
+  $ make                                          [4]
+  $ sudo make install                             [5]
+  $ cd .. ; rm -r tasksh-X.Y.Z                    [6]
+
+These commands are explained below:
+
+  1. Unpacks the source tarball.  This creates the directory tasksh-X.Y.Z,
+     containing all the code.
+
+  2. Change directory to the root of the distribution.
+
+  3. Invokes CMake to scan for dependencies and machine-specific details, then
+     generate the makefiles.  This may take a minute.
+
+  4. Builds tasksh.  This may take a minute.
+
+  5. Installs the program, documentation and other data files.
+
+  6. Removes the temporary directory.
+
+
 Build and configurations options
 --------------------------------
 
-Localizations
--------------
+You can customize the configuration run with cmake variables. This will modify
+the installation process:
+
+To change the installation directory you use the following configuration
+variable:
+
+  $ cmake -DCMAKE_INSTALL_PREFIX=<path-to-installation-dir> .
+
+cmake configuration variables are applied with the -D option and consist of a
+<name> and a <value>:
+
+  $ cmake -D<name>=<value> .
+
+Four more variables can customize the installation process. The following table
+lists them and their defaults plus the CMAKE_INSTALL_PREFIX:
+
+  CMAKE_INSTALL_PREFIX  /usr/local
+  TASKSH_BINDIR         bin
+  TASKSH_DOCDIR         share/doc/tasksh
+  TASKSH_MAN1DIR        share/man/man1
+
+The corresponding TASKSH_* variables will be combined with CMAKE_INSTALL_PREFIX to
+get absolute installation directories:
+
+  CMAKE_INSTALL_PREFIX/TASKSH_BINDIR   /usr/local/bin
+  CMAKE_INSTALL_PREFIX/TASKSH_DOCDIR   /usr/local/share/doc/tasksh
+  CMAKE_INSTALL_PREFIX/TASKSH_MAN1DIR  /usr/local/share/man/man1
+
 
 Uninstallation
 --------------
 
+To uninstall tasksh, you need the Makefiles, so if you deleted them in
+step 7 above, they must first be regenerated by following steps [1], [2] and
+[3].  Then simply run:
+
+  $ sudo make uninstall TODO TODO TODO -- cmake doesn't include uninstall
+
+
 Tasksh Build Notes
 -----------------------
 
+If tashsh will not build on your system, first take a look at the Operating
+System notes below.  If this doesn't help, then go to the Troubleshooting
+section, which includes instructions on how to contact us for help.
+
+
 Operating System Notes
 ----------------------
 
+Cygwin
+  If 'make install' fails when writing to the /usr/local/share/ directory,
+  this may be because your current login doesn't have permission to write
+  to the Windows directory containing your Cygwin installation. Either
+  login to Windows as an Administrator and try the 'make install' process
+  again, or reinstall Cygwin under your normal Windows login.
+
+
 Troubleshooting
 ---------------
 
+If you've recently made changes to dependencies (by reinstalling them, for
+example) be sure to rerun 'cmake .' before trying to execute 'make' again.
+
+CMake will run and locate all the necessary pieces for the build, and create
+a Makefile.  There may be errors and warnings when running CMake, or there
+may be compiler errors and warnings when running 'make'.  Sometimes you will run
+CMake with no reported problems, and the build will fail later.  This is
+almost always because CMake is mistaken about some assumption.
+
+If a build does not succeed, please send the contents of the 'CMakeCache.txt'
+and 'CMakeFiles/CMakeOutput.log' files to support@taskwarrior.org.
+
+If CMake runs but tasksh does not build, please send the contents of the above
+files as well as a transcript from the build, which is not written to a file
+and must be captured from the terminal.
+
 ---