doc: overhaul documentation

This commit cleans up the README and splits portions of it out into
a user guide (GUIDE.md) and a FAQ (FAQ.md). The README now provides a
small list of documentation "quick" links to various parts of the docs.

This commit also does a few other minor touchups.

1 files changed, 20 insertions, 2 deletions

diff --git a/doc/rg.1.txt.tpl b/doc/rg.1.txt.tpl
index a1068c09..911cba71 100644
--- a/doc/rg.1.txt.tpl
+++ b/doc/rg.1.txt.tpl
@@ -10,7 +10,9 @@ Synopsis
 --------
 *rg* [_OPTIONS_] _PATTERN_ [_PATH_...]
 
-*rg* [_OPTIONS_] [*-e* _PATTERN_...] [*-f* _PATH_...] [_PATH_...]
+*rg* [_OPTIONS_] *-e* _PATTERN_... [_PATH_...]
+
+*rg* [_OPTIONS_] *-f* _PATH_... [_PATH_...]
 
 *rg* [_OPTIONS_] *--files* [_PATH_...]
 
@@ -32,6 +34,20 @@ searching. Because of this, features like backreferences and arbitrary
 lookaround are not supported.
 
 
+REGEX SYNTAX
+------------
+ripgrep uses Rust's regex engine, which documents its syntax:
+https://docs.rs/regex/0.2.5/regex/#syntax
+
+ripgrep uses byte-oriented regexes, which has some additional documentation:
+https://docs.rs/regex/0.2.5/regex/bytes/index.html#syntax
+
+To a first approximation, ripgrep uses Perl-like regexes without look-around or
+backreferences. This makes them very similar to the "extended" (ERE) regular
+expressions supported by `egrep`, but with a few additional features like
+Unicode character classes.
+
+
 POSITIONAL ARGUMENTS
 --------------------
 _PATTERN_::
@@ -105,11 +121,13 @@ SHELL COMPLETION
 Shell completion files are included in the release tarball for Bash, Fish, Zsh
 and PowerShell.
 
-For *bash*, move `rg.bash-completion` to `$XDG_CONFIG_HOME/bash_completion`
+For *bash*, move `rg.bash` to `$XDG_CONFIG_HOME/bash_completion`
 or `/etc/bash_completion.d/`.
 
 For *fish*, move `rg.fish` to `$HOME/.config/fish/completions`.
 
+For *zsh*, move `_rg` to one of your `$fpath` directories.
+
 
 CAVEATS
 -------