Merge pull request #1036 from reitermarkus/cask-man

Update `brew-cask` man page and simplify `brew man`.

6 files changed, 32 insertions, 59 deletions

diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb
index 0627241a3..871fbf46c 100644
--- a/Library/Homebrew/dev-cmd/man.rb
+++ b/Library/Homebrew/dev-cmd/man.rb
@@ -52,17 +52,12 @@ module Homebrew
     variables[:commands] = path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}")
     variables[:developer_commands] = path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/dev-cmd/*.{rb,sh}")
     readme = HOMEBREW_REPOSITORY/"README.md"
-    variables[:lead_maintainer] = readme
-                                  .read[/Homebrew's lead maintainer is (.*)\./, 1]
-                                  .scan(/\[([^\]]*)\]/).flatten.first
-    variables[:maintainers] = readme
-                              .read[/Homebrew's current maintainers are (.*)\./, 1]
-                              .scan(/\[([^\]]*)\]/).flatten
-    former_maintainers = readme
-                         .read[/Former maintainers with significant contributions include (.*)\./, 1]
-                         .scan(/\[([^\]]*)\]/).flatten
-    variables[:former_maintainers] = former_maintainers[0...-1]
-    variables[:creator] = former_maintainers.last
+    variables[:lead_maintainer] = readme.read[/(Homebrew's lead maintainer .*\.)/, 1]
+                                        .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
+    variables[:maintainers] = readme.read[/(Homebrew's current maintainers .*\.)/, 1]
+                                    .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
+    variables[:former_maintainers] = readme.read[/(Former maintainers .*\.)/, 1]
+                                           .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
 
     ERB.new(template, nil, ">").result(variables.instance_eval { binding })
   end
diff --git a/Library/Homebrew/manpages/brew-cask.1.md b/Library/Homebrew/manpages/brew-cask.1.md
index fc14d54d1..4e160b527 100644
--- a/Library/Homebrew/manpages/brew-cask.1.md
+++ b/Library/Homebrew/manpages/brew-cask.1.md
@@ -19,10 +19,10 @@ names, and other aspects of this manual are still subject to change.
 
 ## FREQUENTLY USED COMMANDS
 
-  * `install [--force] [--skip-cask-deps] [--require-sha]` <token> [ <token> ... ]:
+  * `install` [--force] [--skip-cask-deps] [--require-sha] <token> [ <token> ... ]:
     Install Cask identified by <token>.
 
-  * `uninstall [--force]` <token> [ <token> ... ]:
+  * `uninstall` [--force] <token> [ <token> ... ]:
     Uninstall Cask identified by <token>.
 
   * `search` <text> | /<regexp>/:
@@ -69,7 +69,7 @@ names, and other aspects of this manual are still subject to change.
   * `info` or `abv` <token> [ <token> ... ]:
     Display information about the given Cask.
 
-  * `install [--force] [--skip-cask-deps] [--require-sha]` <token> [ <token> ... ]:
+  * `install` [--force] [--skip-cask-deps] [--require-sha] <token> [ <token> ... ]:
     Install the given Cask. With `--force`, re-install even if the Cask
     appears to be already present. With `--skip-cask-deps`, skip any Cask
     dependencies. `--require-sha` will abort installation if the Cask does not
@@ -78,42 +78,29 @@ names, and other aspects of this manual are still subject to change.
     <token> is usually the ID of a Cask as returned by `brew cask search`,
     but see [OTHER WAYS TO SPECIFY A CASK][] for variations.
 
-  * `list` or `ls` [-1 | -l] [ <token> ... ]:
+  * `list` or `ls` [-1] [--versions] [ <token> ... ]:
     Without any arguments, list all installed Casks. With `-1`, always
-    format the output in a single column. With `-l`, give a more detailed
-    listing.
+    format the output in a single column. With `--versions`, show all installed
+    versions.
 
     If <token> is given, summarize the staged files associated with the
     given Cask.
 
-  * `search` or `-S`:
-    Display all Casks available for install.
-
-  * `search` or `-S` <text> | /<regexp>/:
-    Perform a substring search of known Cask tokens for <text>. If the text
-    is delimited by slashes, it is interpreted as a Ruby regular expression.
+  * `search` or `-S` [<text> | /<regexp>/]:
+    Without argument, display all Casks available for install, otherwise
+    perform a substring search of known Cask tokens for <text> or, if the
+    text is delimited by slashes (/<regexp>/), it is interpreted as a
+    Ruby regular expression.
 
   * `style` [--fix] [ <token> ... ]:
    Check the given Casks for correct style using [RuboCop Cask](https://github.com/caskroom/rubocop-cask).
    If no tokens are given on the command line, all Casks are checked.
    With `--fix`, auto-correct any style errors if possible.
 
-  * `uninstall [--force]` or `rm` or `remove` <token> [ <token> ... ]:
+  * `uninstall` or `rm` or `remove` [--force] <token> [ <token> ... ]:
     Uninstall the given Cask. With `--force`, uninstall even if the Cask
     does not appear to be present.
 
-    Note that `uninstall --force` is currently imperfect. It will follow
-    the `uninstall` instructions from *newest* Cask definition, even if
-    the given Cask has changed since you installed it. The result is that
-    `uninstall --force` will always succeed in removing relevant files
-    under `<Caskroom_path>`, but will sometimes fail to remove relevant
-    installed files outside of it. This issue is being
-    addressed.
-
-    `uninstall` without `--force` is also imperfect. It may be unable to
-    perform an `uninstall` operation if the given Cask has changed since you
-    installed it. This issue is being addressed.
-
   * `update`:
     For convenience. `brew cask update` is a synonym for `brew update`.
 
diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
index e44dc2658..bc2140b40 100644
--- a/Library/Homebrew/manpages/brew.1.md.erb
+++ b/Library/Homebrew/manpages/brew.1.md.erb
@@ -255,11 +255,11 @@ Homebrew Documentation: <https://github.com/Homebrew/brew/blob/master/docs/>
 
 ## AUTHORS
 
-Homebrew's lead maintainer is <%= lead_maintainer %>.
+<%= lead_maintainer.concat("\n") %>
 
-Homebrew's current maintainers are <%= maintainers[0...-1].join(", ") %> and <%= maintainers[-1] %>.
+<%= maintainers.concat("\n") %>
 
-Former maintainers with significant contributions include <%= former_maintainers.join(", ") %> and Homebrew's creator: <%= creator %>.
+<%= former_maintainers.concat("\n") %>
 
 ## BUGS
 
diff --git a/docs/brew.1.html b/docs/brew.1.html
index b6c4be718..c7b9de125 100644
--- a/docs/brew.1.html
+++ b/docs/brew.1.html
@@ -731,7 +731,7 @@ your shell profile, or you can use it before a brew command:</p>
 
 <p>Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Tomasz Pajor, Baptiste Fontaine, Zhiming Wang, Brett Koonce, ilovezfs, Martin Afanasjew, Uladzislau Shablinski, Dominyk Tiller, Tim Smith and Alex Dunn.</p>
 
-<p>Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg, Max Howell and Homebrew's creator: Max Howell.</p>
+<p>Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell.</p>
 
 <h2 id="BUGS">BUGS</h2>
 
diff --git a/manpages/brew-cask.1 b/manpages/brew-cask.1
index dd2bc133c..b447c6285 100644
--- a/manpages/brew-cask.1
+++ b/manpages/brew-cask.1
@@ -18,11 +18,11 @@ Homebrew\-Cask works robustly enough that we welcome new users, but the project
 .SH "FREQUENTLY USED COMMANDS"
 .
 .TP
-\fBinstall [\-\-force] [\-\-skip\-cask\-deps] [\-\-require\-sha]\fR \fItoken\fR [ \fItoken\fR \.\.\. ]
+\fBinstall\fR [\-\-force] [\-\-skip\-cask\-deps] [\-\-require\-sha] \fItoken\fR [ \fItoken\fR \.\.\. ]
 Install Cask identified by \fItoken\fR\.
 .
 .TP
-\fBuninstall [\-\-force]\fR \fItoken\fR [ \fItoken\fR \.\.\. ]
+\fBuninstall\fR [\-\-force] \fItoken\fR [ \fItoken\fR \.\.\. ]
 Uninstall Cask identified by \fItoken\fR\.
 .
 .TP
@@ -74,41 +74,31 @@ With no arguments, display the project page \fIhttp://caskroom\.io\fR\.
 Display information about the given Cask\.
 .
 .TP
-\fBinstall [\-\-force] [\-\-skip\-cask\-deps] [\-\-require\-sha]\fR \fItoken\fR [ \fItoken\fR \.\.\. ]
+\fBinstall\fR [\-\-force] [\-\-skip\-cask\-deps] [\-\-require\-sha] \fItoken\fR [ \fItoken\fR \.\.\. ]
 Install the given Cask\. With \fB\-\-force\fR, re\-install even if the Cask appears to be already present\. With \fB\-\-skip\-cask\-deps\fR, skip any Cask dependencies\. \fB\-\-require\-sha\fR will abort installation if the Cask does not have a checksum defined\.
 .
 .IP
 \fItoken\fR is usually the ID of a Cask as returned by \fBbrew cask search\fR, but see \fIOTHER WAYS TO SPECIFY A CASK\fR for variations\.
 .
 .TP
-\fBlist\fR or \fBls\fR [\-1 | \-l] [ \fItoken\fR \.\.\. ]
-Without any arguments, list all installed Casks\. With \fB\-1\fR, always format the output in a single column\. With \fB\-l\fR, give a more detailed listing\.
+\fBlist\fR or \fBls\fR [\-1] [\-\-versions] [ \fItoken\fR \.\.\. ]
+Without any arguments, list all installed Casks\. With \fB\-1\fR, always format the output in a single column\. With \fB\-\-versions\fR, show all installed versions\.
 .
 .IP
 If \fItoken\fR is given, summarize the staged files associated with the given Cask\.
 .
 .TP
-\fBsearch\fR or \fB\-S\fR
-Display all Casks available for install\.
-.
-.TP
-\fBsearch\fR or \fB\-S\fR \fItext\fR | /\fIregexp\fR/
-Perform a substring search of known Cask tokens for \fItext\fR\. If the text is delimited by slashes, it is interpreted as a Ruby regular expression\.
+\fBsearch\fR or \fB\-S\fR [\fItext\fR | /\fIregexp\fR/]
+Without argument, display all Casks available for install, otherwise perform a substring search of known Cask tokens for \fItext\fR or, if the text is delimited by slashes (/\fIregexp\fR/), it is interpreted as a Ruby regular expression\.
 .
 .TP
 \fBstyle\fR [\-\-fix] [ \fItoken\fR \.\.\. ]
 Check the given Casks for correct style using RuboCop Cask \fIhttps://github\.com/caskroom/rubocop\-cask\fR\. If no tokens are given on the command line, all Casks are checked\. With \fB\-\-fix\fR, auto\-correct any style errors if possible\.
 .
 .TP
-\fBuninstall [\-\-force]\fR or \fBrm\fR or \fBremove\fR \fItoken\fR [ \fItoken\fR \.\.\. ]
+\fBuninstall\fR or \fBrm\fR or \fBremove\fR [\-\-force] \fItoken\fR [ \fItoken\fR \.\.\. ]
 Uninstall the given Cask\. With \fB\-\-force\fR, uninstall even if the Cask does not appear to be present\.
 .
-.IP
-Note that \fBuninstall \-\-force\fR is currently imperfect\. It will follow the \fBuninstall\fR instructions from \fInewest\fR Cask definition, even if the given Cask has changed since you installed it\. The result is that \fBuninstall \-\-force\fR will always succeed in removing relevant files under \fB<Caskroom_path>\fR, but will sometimes fail to remove relevant installed files outside of it\. This issue is being addressed\.
-.
-.IP
-\fBuninstall\fR without \fB\-\-force\fR is also imperfect\. It may be unable to perform an \fBuninstall\fR operation if the given Cask has changed since you installed it\. This issue is being addressed\.
-.
 .TP
 \fBupdate\fR
 For convenience\. \fBbrew cask update\fR is a synonym for \fBbrew update\fR\.
diff --git a/manpages/brew.1 b/manpages/brew.1
index c4a650335..25b1b80b7 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -1001,7 +1001,7 @@ Homebrew\'s lead maintainer is Mike McQuaid\.
 Homebrew\'s current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Tomasz Pajor, Baptiste Fontaine, Zhiming Wang, Brett Koonce, ilovezfs, Martin Afanasjew, Uladzislau Shablinski, Dominyk Tiller, Tim Smith and Alex Dunn\.
 .
 .P
-Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg, Max Howell and Homebrew\'s creator: Max Howell\.
+Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg and Homebrew\'s creator: Max Howell\.
 .
 .SH "BUGS"
 See our issues on GitHub:
@@ -1013,3 +1013,4 @@ Homebrew/brew \fIhttps://github\.com/Homebrew/brew/issues\fR
 Homebrew/homebrew\-core \fIhttps://github\.com/Homebrew/homebrew\-core/issues\fR
 .
 .IP "" 0
+