Update help and man pages

Formatting of rg.1.md. Remove backticks from already indented code.
Add missing italic to some arguments, Replace -n by --line-number in
--pretty for better clarity. Add explicit example of `*.foo` instead of
`<glob>` in examples. Add vim information to --vimgrep.

In src/app.rs, also changed help text for pattern and regexp. Actually,
"multiple patterns may be given" was not true for the standalone
pattern.

doc/rg.1

@@ -7,12 +7,12 @@
 rg \- recursively search current directory for lines matching a pattern
 .SH SYNOPSIS
 .PP
-rg [\f[I]options\f[]] <\f[I]pattern\f[]> [\f[I]<\f[]path\f[I]> ...\f[]]
+rg [\f[I]options\f[]] \f[I]PATTERN\f[] [\f[I]path\f[] ...]
 .PP
-rg [\f[I]options\f[]] (\-e PATTERN | \-f FILE) ...
+rg [\f[I]options\f[]] [\-e \f[I]pattern\f[] ...] [\-f \f[I]file\f[] ...]
-[\f[I]<\f[]path\f[I]> ...\f[]]
+[\f[I]path\f[] ...]
 .PP
-rg [\f[I]options\f[]] \-\-files [\f[I]<\f[]path\f[I]> ...\f[]]
+rg [\f[I]options\f[]] \-\-files [\f[I]path\f[] ...]
 .PP
 rg [\f[I]options\f[]] \-\-type\-list
 .PP
@@ -71,22 +71,23 @@ Multiple glob flags may be used.
 Globbing rules match .gitignore globs.
 Precede a glob with a \[aq]!\[aq] to exclude it.
 .RS
-.RE
 .PP
 The \-\-glob flag subsumes the functionality of both the \-\-include and
 \-\-exclude flags commonly found in other tools.
+.PP
+Values given to \-g must be quoted or your shell will expand them and
+result in unexpected behavior.
+.PP
+Combine with the \-\-files flag to return matched filenames (i.e., to
+replicate ack/ag\[aq]s \-g flag).
+For example:
 .IP
 .nf
 \f[C]
-Values\ given\ to\ \-g\ must\ be\ quoted\ or\ your\ shell\ will\ expand\ them\ and\ result
+rg\ \-g\ \[aq]*.foo\[aq]\ \-\-files
-in\ unexpected\ behavior.
-
-Combine\ with\ the\ \-\-files\ flag\ to\ return\ matched\ filenames
-(i.e.,\ to\ replicate\ ack/ag\[aq]s\ \-g\ flag).
-
-For\ example:\ rg\ \-g\ \[aq]\\<glob\\>\[aq]\ \-\-files
 \f[]
 .fi
+.RE
 .TP
 .B \-h, \-\-help
 Show this usage message.
@@ -134,14 +135,15 @@ Reduce the level of \[aq]smart\[aq] searching.
 A single \-u doesn\[aq]t respect .gitignore (etc.) files.
 Two \-u flags will search hidden files and directories.
 Three \-u flags will search binary files.
-\-uu is equivalent to grep \-r, and \-uuu is equivalent to grep \-a \-r.
+\-uu is equivalent to \f[C]grep\ \-r\f[], and \-uuu is equivalent to
+\f[C]grep\ \-a\ \-r\f[].
 .RS
 .PP
 Note that the \-u flags are convenient aliases for other combinations of
 flags.
-\-u aliases \[aq]\-\-no\-ignore\[aq].
+\-u aliases \-\-no\-ignore.
-\-uu aliases \[aq]\-\-no\-ignore \-\-hidden\[aq].
+\-uu aliases \-\-no\-ignore \-\-hidden.
-\-uuu aliases \[aq]\-\-no\-ignore \-\-hidden \-\-text\[aq].
+\-uuu aliases \-\-no\-ignore \-\-hidden \-\-text.
 .RE
 .TP
 .B \-v, \-\-invert\-match
@@ -188,9 +190,12 @@ A special format, {type}:none, will clear all color settings for {type}.
 .PP
 For example, the following command will change the match color to
 magenta and the background color for line numbers to yellow:
-.PP
+.IP
-rg \-\-colors \[aq]match:fg:magenta\[aq] \-\-colors
+.nf
-\[aq]line:bg:yellow\[aq] foo.
+\f[C]
+rg\ \-\-colors\ \[aq]match:fg:magenta\[aq]\ \-\-colors\ \[aq]line:bg:yellow\[aq]\ foo.
+\f[]
+.fi
 .RE
 .TP
 .B \-\-column
@@ -223,7 +228,7 @@ https://encoding.spec.whatwg.org/#concept\-encoding\-get
 .RS
 .RE
 .TP
-.B \-f, \-\-file FILE ...
+.B \-f, \-\-file \f[I]FILE\f[] ...
 Search for patterns from the given file, with one pattern per line.
 When this flag is used or multiple times or in combination with the
 \-e/\-\-regexp flag, then all patterns provided are searched.
@@ -237,8 +242,12 @@ Print each file that would be searched (but don\[aq]t search).
 .RS
 .PP
 Combine with the \-g flag to return matched paths, for example:
-.PP
+.IP
-rg \-g \[aq]<glob>\[aq] \-\-files
+.nf
+\f[C]
+rg\ \-g\ \[aq]*.foo\[aq]\ \-\-files
+\f[]
+.fi
 .RE
 .TP
 .B \-l, \-\-files\-with\-matches
@@ -284,7 +293,7 @@ Search hidden directories and files.
 .RS
 .RE
 .TP
-.B \-\-ignore\-file FILE ...
+.B \-\-ignore\-file \f[I]FILE\f[] ...
 Specify additional ignore files for filtering file paths.
 Ignore files should be in the gitignore format and are matched relative
 to the current working directory.
@@ -387,7 +396,7 @@ A path separator is limited to a single byte.
 .RE
 .TP
 .B \-p, \-\-pretty
-Alias for \-\-color=always \-\-heading \-n.
+Alias for \-\-color=always \-\-heading \-\-line\-number.
 .RS
 .RE
 .TP
@@ -446,9 +455,21 @@ Show the version number of ripgrep and exit.
 .B \-\-vimgrep
 Show results with every match on its own line, including line numbers
 and column numbers.
-(With this option, a line with more than one match of the regex will be
+With this option, a line with more than one match will be printed more
-printed more than once.)
+than once.
 .RS
+.PP
+Recommended .vimrc configuration:
+.IP
+.nf
+\f[C]
+\ \ set\ grepprg=rg\\\ \-\-vimgrep
+\ \ set\ grepformat^=%f:%l:%c:%m
+\f[]
+.fi
+.PP
+Use :grep to grep for something, then :cn and :cp to navigate through
+the matches.
 .RE
 .SH FILE TYPE MANAGEMENT OPTIONS
 .TP
@@ -465,11 +486,12 @@ Unless \-\-type\-clear is used, globs are added to any existing globs
 inside of ripgrep.
 Note that this must be passed to every invocation of rg.
 Type settings are NOT persisted.
+Example:
 .RS
 .IP
 .nf
 \f[C]
-\ \ Example:\ `rg\ \-\-type\-add\ \[aq]foo:*.foo\[aq]\ \-tfoo\ PATTERN`
+\ \ rg\ \-\-type\-add\ \[aq]foo:*.foo\[aq]\ \-tfoo\ PATTERN
 \f[]
 .fi
 .PP
@@ -483,7 +505,7 @@ Markdown files, one can use:
 .IP
 .nf
 \f[C]
-\ \ `\-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]`
+\ \ \-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]
 \f[]
 .fi
 .PP
@@ -492,7 +514,7 @@ Additional glob rules can still be added to the src type by using the
 .IP
 .nf
 \f[C]
-\ \ `\-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]\ \-\-type\-add\ \[aq]src:*.foo\[aq]`
+\ \ \-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]\ \-\-type\-add\ \[aq]src:*.foo\[aq]
 \f[]
 .fi
 .PP

doc/rg.1.md

@@ -4,11 +4,11 @@ rg - recursively search current directory for lines matching a pattern
 
 # SYNOPSIS
 
-rg [*options*] <*pattern*> [*<*path*> ...*]
+rg [*options*] *PATTERN* [*path* ...]
 
-rg [*options*] (-e PATTERN | -f FILE) ... [*<*path*> ...*]
+rg [*options*] [-e *pattern* ...] [-f *file* ...] [*path* ...]
 
-rg [*options*] --files [*<*path*> ...*]
+rg [*options*] --files [*path* ...]
 
 rg [*options*] --type-list
 
@@ -61,9 +61,9 @@ Project home page: https://github.com/BurntSushi/ripgrep
     in unexpected behavior.
 
     Combine with the --files flag to return matched filenames
-    (i.e., to replicate ack/ag's -g flag).
+    (i.e., to replicate ack/ag's -g flag). For example:
 
-    For example: rg -g '\<glob\>' --files
+        rg -g '*.foo' --files
 
 -h, --help
 : Show this usage message.
@@ -91,12 +91,12 @@ Project home page: https://github.com/BurntSushi/ripgrep
 -u, --unrestricted ...
 : Reduce the level of 'smart' searching. A single -u doesn't respect .gitignore
   (etc.) files. Two -u flags will search hidden files and directories. Three
-  -u flags will search binary files. -uu is equivalent to grep -r, and -uuu is
+  -u flags will search binary files. -uu is equivalent to `grep -r`, and -uuu
-  equivalent to grep -a -r.
+  is equivalent to `grep -a -r`.
 
     Note that the -u flags are convenient aliases for other combinations of
-    flags. -u aliases '--no-ignore'. -uu aliases '--no-ignore --hidden'.
+    flags. -u aliases --no-ignore. -uu aliases --no-ignore --hidden.
-    -uuu aliases '--no-ignore --hidden --text'.
+    -uuu aliases --no-ignore --hidden --text.
 
 -v, --invert-match
 : Invert matching.
@@ -152,7 +152,7 @@ Project home page: https://github.com/BurntSushi/ripgrep
   Other supported values can be found in the list of labels here:
   https://encoding.spec.whatwg.org/#concept-encoding-get
 
--f, --file FILE ...
+-f, --file *FILE* ...
 : Search for patterns from the given file, with one pattern per line. When this
   flag is used or multiple times or in combination with the -e/--regexp flag,
   then all patterns provided are searched. Empty pattern lines will match all
@@ -163,7 +163,7 @@ Project home page: https://github.com/BurntSushi/ripgrep
 
     Combine with the -g flag to return matched paths, for example:
 
-    rg -g '\<glob\>' --files
+        rg -g '*.foo' --files
 
 -l, --files-with-matches
 : Only show path of each file with matches.
@@ -192,7 +192,7 @@ Project home page: https://github.com/BurntSushi/ripgrep
 : Search hidden directories and files. (Hidden directories and files are
   skipped by default.)
 
---ignore-file FILE ...
+--ignore-file *FILE* ...
 : Specify additional ignore files for filtering file paths.
   Ignore files should be in the gitignore format and are matched
   relative to the current working directory. These ignore files
@@ -260,7 +260,7 @@ Project home page: https://github.com/BurntSushi/ripgrep
   cygwin). A path separator is limited to a single byte.
 
 -p, --pretty
-: Alias for --color=always --heading -n.
+: Alias for --color=always --heading --line-number.
 
 -r, --replace *ARG*
 : Replace every match with the string given when printing search results.
@@ -295,9 +295,17 @@ Project home page: https://github.com/BurntSushi/ripgrep
 : Show the version number of ripgrep and exit.
 
 --vimgrep
-: Show results with every match on its own line, including line
+: Show results with every match on its own line, including
-  numbers and column numbers. (With this option, a line with more
+  line numbers and column numbers. With this option, a line with
-  than one match of the regex will be printed more than once.)
+  more than one match will be printed more than once.
+
+      Recommended .vimrc configuration:
+
+          set grepprg=rg\ --vimgrep
+          set grepformat^=%f:%l:%c:%m
+
+      Use :grep to grep for something, then :cn and :cp to navigate through the
+      matches.
 
 # FILE TYPE MANAGEMENT OPTIONS
 
@@ -309,9 +317,9 @@ Project home page: https://github.com/BurntSushi/ripgrep
   at a time. Multiple --type-add flags can be provided. Unless --type-clear
   is used, globs are added to any existing globs inside of ripgrep. Note that
   this must be passed to every invocation of rg. Type settings are NOT
-  persisted.
+  persisted. Example:
 
-          Example: `rg --type-add 'foo:*.foo' -tfoo PATTERN`
+          rg --type-add 'foo:*.foo' -tfoo PATTERN
 
       --type-add can also be used to include rules from other types
       with the special include directive. The include directive
@@ -321,12 +329,12 @@ Project home page: https://github.com/BurntSushi/ripgrep
       type called src that matches C++, Python and Markdown files, one
       can use:
 
-          `--type-add 'src:include:cpp,py,md'`
+          --type-add 'src:include:cpp,py,md'
 
       Additional glob rules can still be added to the src type by
       using the --type-add flag again:
 
-          `--type-add 'src:include:cpp,py,md' --type-add 'src:*.foo'`
+          --type-add 'src:include:cpp,py,md' --type-add 'src:*.foo'
 
       Note that type names must consist only of Unicode letters or
       numbers. Punctuation characters are not allowed.

src/app.rs

@@ -14,10 +14,10 @@ Project home page: https://github.com/BurntSushi/ripgrep
 Use -h for short descriptions and --help for more details.";
 
 const USAGE: &'static str = "
-    rg [OPTIONS] <pattern> [<path> ...]
+    rg [options] PATTERN [path ...]
-    rg [OPTIONS] [-e PATTERN | -f FILE ]... [<path> ...]
+    rg [options] [-e pattern ...] [-f file ...] [path ...]
-    rg [OPTIONS] --files [<path> ...]
+    rg [options] --files [path ...]
-    rg [OPTIONS] --type-list";
+    rg [options] --type-list";
 
 const TEMPLATE: &'static str = "\
 {bin} {version}
@@ -203,12 +203,13 @@ lazy_static! {
 
         doc!(h, "pattern",
              "A regular expression used for searching.",
-             "A regular expression used for searching. Multiple patterns \
+             "A regular expression used for searching. To match a pattern \
-              may be given. To match a pattern beginning with a -, use [-].");
+             beginning with a dash, use the -e/--regexp option.");
         doc!(h, "regexp",
-             "A regular expression used for searching.",
+             "Use pattern to search.",
-             "A regular expression used for searching. Multiple patterns \
+             "Use pattern to search. This option can be provided multiple \
-              may be given. To match a pattern beginning with a -, use [-].");
+             times, where all patterns given are searched. This is also \
+             useful when searching for patterns that start with a dash.");
         doc!(h, "path",
              "A file or directory to search.",
              "A file or directory to search. Directories are searched \
@@ -447,7 +448,7 @@ lazy_static! {
               default when the environment demands it (e.g., cygwin). A path \
               separator is limited to a single byte.");
         doc!(h, "pretty",
-             "Alias for --color always --heading -n.");
+             "Alias for --color always --heading --line-number.");
         doc!(h, "replace",
              "Replace matches with string given.",
              "Replace every match with the string given when printing \