Merge branch 'docs'

Completely rewrite documentation, in preparation of the new release.
The README.md file was already a little inaccurate and desynced from the
last tagged git-sonar script, but now that the files have been
redesigned, documentation is in need of a complete face lift.

I've opted to move the meat of the user-facing documentation into
manpages, so that the high fidelity documentation is more accessible on
demand.  This also better opens the door for packaging of git-sonar down
the road, providing some form of documentation that will get 'installed'
along with the tool.

The output of --help for each script is removed, and instead --help will
recall that script's manpage using the 'man' command.  This is done to
make it more obvious that more verbose docs exist, as well as to reduce
the number of spots for documentation that need to be kept in sync.

README is stripped down to function as a higher-level project
information file, which is more focused and easier to navigate now that
usage documentation has its own home.

* docs:
  Replace README with new project information
  precheck: Add documentation in new manpage
  Update core documentation as git-sonar manpage

1 files changed, 69 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..d5f7c3e
--- /dev/null
+++ b/README
@@ -0,0 +1,69 @@
+                     _ _      __                        __  
+                __ _(_) |_ _ / /__  ___  _ __   __ _ _ _\ \ 
+               / _` | | __(_) / __|/ _ \| '_ \ / _` | '__| |
+              | (_| | | |_ _| \__ \ (_) | | | | (_| | |  | |
+               \__, |_|\__(_) |___/\___/|_| |_|\__,_|_|  | |
+               |___/         \_\                        /_/ 
+
+git-sonar is a shell prompt git status indicator, add it to your $PS1 prompt to
+see real-time information about the current directory's repository, branch,
+changed files, etc.  git-sonar is forked from the original project git-radar by
+Michael Allen, which is no longer receiving maintenance.
+Ref: https://github.com/michaeldfallen/git-radar
+
+git-sonar also provides git-precheck, a shell utility script which inspects a
+repository and returns machine-parseable results not easily gathered from
+git status.  It is intended for use in other git-related scripts.
+
+
+INSTALLATION
+------------
+For a normal installation, run 'make install', but see the output from 'make'
+for more installation options.  You can run 'git-sonar --version' to confirm
+that the install was successful.
+
+
+GETTING STARTED
+---------------
+Both of the scripts have an accompanying man-page, which can be viewed after
+installation using the 'man' command, or by passing '--help' to either script
+directly.
+
+These are the user-facing documentation and contain more details about usage,
+configuration, and inserting git-sonar into your particular shell's prompt.
+
+Out of the box, git-sonar has a very usable default configuration, and most
+features are enabled.  One can be up and running by just updating their $PS1
+variable - but see the "USAGE" section of git-sonar's man-page for some possible
+$PS1 pitfalls.
+
+
+GETTING SUPPORT
+---------------
+Get in touch on the mailing list to ask questions, report problems, submit
+patches, or discuss the project!
+
+    git-sonar@normalmode.org
+
+For more information, or instructions on subscribing, send an email to:
+
+    git-sonar+help@normalmode.org
+
+
+COMPATIBILITY WITH GIT-RADAR
+----------------------------
+git-sonar is no longer a "drop in" replacement for git-radar.  All of the
+environment variables used for configuration have been either renamed, or
+removed, and several others have been added.  git-sonar does not read from any
+special RC files, just the shell environment.  Furthermore, both tools support
+different command line options.
+
+git-sonar does preserve the original hallmark features of git-radar, and its
+default appearance is very faithful to the original as well.
+
+
+LICENSE
+-------
+For historical reasons, git-sonar, git-precheck, and associated documentation
+are made available under the MIT license - the same license utilized by
+git-radar.