Update PATTERN/PATH descriptions in man page

Fixes BurntSushi#725 (sort of)

* Capitalise place-holder names consistently
* Document PATTERN and PATH
* Add note about PATH overriding glob/ignore rules

doc/rg.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.19.2.1
+.\" Automatically generated by Pandoc 2.0.6
 .\"
 .TH "rg" "1"
 .hy
@@ -7,18 +7,18 @@
 rg \- recursively search current directory for lines matching a pattern
 .SH SYNOPSIS
 .PP
-rg [\f[I]options\f[]] \f[I]PATTERN\f[] [\f[I]path\f[] ...]
+rg [\f[I]OPTIONS\f[]] \f[I]PATTERN\f[] [\f[I]PATH\f[] ...]
 .PP
-rg [\f[I]options\f[]] [\-e \f[I]PATTERN\f[] ...] [\-f \f[I]FILE\f[] ...]
-[\f[I]path\f[] ...]
+rg [\f[I]OPTIONS\f[]] [\-e \f[I]PATTERN\f[] ...] [\-f \f[I]FILE\f[] ...]
+[\f[I]PATH\f[] ...]
 .PP
-rg [\f[I]options\f[]] \-\-files [\f[I]path\f[] ...]
+rg [\f[I]OPTIONS\f[]] \-\-files [\f[I]PATH\f[] ...]
 .PP
-rg [\f[I]options\f[]] \-\-type\-list
+rg [\f[I]OPTIONS\f[]] \-\-type\-list
 .PP
-rg [\f[I]options\f[]] \-\-help
+rg [\f[I]OPTIONS\f[]] \-\-help
 .PP
-rg [\f[I]options\f[]] \-\-version
+rg [\f[I]OPTIONS\f[]] \-\-version
 .SH DESCRIPTION
 .PP
 ripgrep (rg) combines the usability of The Silver Searcher (an ack
@@ -34,6 +34,21 @@ it searches a file that is simultaneously truncated.
 This behavior can be avoided by passing the \-\-no\-mmap flag.
 .PP
 Project home page: https://github.com/BurntSushi/ripgrep
+.SH POSITIONAL ARGUMENTS
+.TP
+.B \f[I]PATTERN\f[]
+A regular expression used for searching.
+To match a pattern beginning with a dash, use the \-e/\-\-regexp option.
+.RS
+.RE
+.TP
+.B \f[I]PATH\f[]
+A file or directory to search.
+Directories are searched recursively.
+Paths specified expicitly on the command line override glob and ignore
+rules.
+.RS
+.RE
 .SH COMMON OPTIONS
 .TP
 .B \-a, \-\-text

doc/rg.1.md

@@ -4,17 +4,17 @@ 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
+rg [*OPTIONS*] --type-list
 
-rg [*options*] --help
+rg [*OPTIONS*] --help
 
-rg [*options*] --version
+rg [*OPTIONS*] --version
 
 # DESCRIPTION
 
@@ -31,6 +31,16 @@ by passing the --no-mmap flag.
 
 Project home page: https://github.com/BurntSushi/ripgrep
 
+# POSITIONAL ARGUMENTS
+
+*PATTERN*
+: A regular expression used for searching. To match a pattern beginning with a
+  dash, use the -e/--regexp option.
+
+*PATH*
+: A file or directory to search. Directories are searched recursively. Paths
+  specified expicitly on the command line override glob and ignore rules.
+
 # COMMON OPTIONS
 
 -a, --text