doc: various updates

* Don't use 'smart typography' when generating man page
* Document PATTERN and PATH
* Capitalise place-holder names consistently
* Add note about PATH overriding glob/ignore rules
* Update args.rs for new PATH capitalisation

Fixes #725

doc/convert-to-man

@@ -1,5 +1,5 @@
 #!/bin/sh -e
 
-pandoc -s -t man rg.1.md -o rg.1
+pandoc -s -f markdown-smart -t man rg.1.md -o rg.1
 sed -i.bak 's/\.TH.*/.TH "rg" "1"/g' rg.1
 rm -f rg.1.bak # BSD `sed` requires the creation of a back-up file

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

src/app.rs

@@ -18,10 +18,10 @@ Project home page: https://github.com/BurntSushi/ripgrep
 Use -h for short descriptions and --help for more details.";
 
 const USAGE: &str = "
-    rg [options] PATTERN [path ...]
-    rg [options] [-e PATTERN ...] [-f FILE ...] [path ...]
-    rg [options] --files [path ...]
-    rg [options] --type-list";
+    rg [OPTIONS] PATTERN [PATH ...]
+    rg [OPTIONS] [-e PATTERN ...] [-f FILE ...] [PATH ...]
+    rg [OPTIONS] --files [PATH ...]
+    rg [OPTIONS] --type-list";
 
 const TEMPLATE: &str = "\
 {bin} {version}
@@ -67,7 +67,7 @@ pub fn app() -> App<'static, 'static> {
                 "file", "files", "help-short", "help", "regexp", "type-list",
                 "ripgrep-version",
              ]))
-        .arg(arg("path").multiple(true))
+        .arg(arg("PATH").multiple(true))
         .arg(flag("regexp").short("e")
              .takes_value(true).multiple(true).number_of_values(1)
              .set(ArgSettings::AllowLeadingHyphen)
@@ -247,10 +247,11 @@ lazy_static! {
              "Use pattern to search. This option can be provided multiple \
              times, where all patterns given are searched. This is also \
              useful when searching for patterns that start with a dash.");
-        doc!(h, "path",
+        doc!(h, "PATH",
              "A file or directory to search.",
              "A file or directory to search. Directories are searched \
-              recursively.");
+              recursively. Paths specified on the command line override glob \
+              and ignore rules.");
         doc!(h, "files",
              "Print each file that would be searched.",
              "Print each file that would be searched without actually \

src/args.rs

@@ -371,7 +371,7 @@ impl<'a> ArgMatches<'a> {
 
     /// Return all file paths that ripgrep should search.
     fn paths(&self) -> Vec<PathBuf> {
-        let mut paths: Vec<PathBuf> = match self.values_of_os("path") {
+        let mut paths: Vec<PathBuf> = match self.values_of_os("PATH") {
             None => vec![],
             Some(vals) => vals.map(|p| Path::new(p).to_path_buf()).collect(),
         };