deps: split and clarify documentation

`brew deps` has three different modes of operation that were not easy to
infer from the existing documentation. Split the help text into three
parts to make this clearer. This also improves on the confusion when
options were silently ignored because they don't apply to a certain mode
of operation. Those are:

1. List the shared dependencies (either intersection or union) of
   explicitly named formulae with options for traversal depth/order.

2. Output separate trees of explicitly listed or all installed formulae.

3. List all available/installed formulae and their direct dependencies
   with one line per formula formatted as `<formula>: <dependencies>`.

Closes #137.

Closes #179.

Signed-off-by: Martin Afanasjew <martin@afanasjew.de>

Library/Homebrew/cmd/deps.rb

@@ -1,7 +1,6 @@
-#:  * `deps` [`--1`] [`-n`] [`--union`] [`--tree`] [`--all`] [`--installed`] [`--include-build`] [`--include-optional`] [`--skip-recommended`] <formulae>:
+#:  * `deps` [`--1`] [`-n`] [`--union`] [`--installed`] [`--include-build`] [`--include-optional`] [`--skip-recommended`] <formulae>:
 #:    Show dependencies for <formulae>. When given multiple formula arguments,
-#:    show the intersection of dependencies for <formulae>, except when passed
+#:    show the intersection of dependencies for <formulae>.
-#:    `--tree`, `--all`, or `--installed`.
 #:
 #:    If `--1` is passed, only show dependencies one level down, instead of
 #:    recursing.
@@ -11,16 +10,30 @@
 #:    If `--union` is passed, show the union of dependencies for <formulae>,
 #:    instead of the intersection.
 #:
-#:    If `--tree` is passed, show dependencies as a tree.
+#:    If `--installed` is passed, only list those dependencies that are
-#:
+#:    currently installed.
-#:    If `--all` is passed, show dependencies for all formulae.
-#:
-#:    If `--installed` is passed, show dependencies for all installed formulae.
 #:
 #:    By default, `deps` shows required and recommended dependencies for
 #:    <formulae>. To include the `:build` type dependencies, pass `--include-build`.
 #:    Similarly, pass `--include-optional` to include `:optional` dependencies.
 #:    To skip `:recommended` type dependencies, pass `--skip-recommended`.
+#:
+#:  * `deps` `--tree` [<filters>] (<formulae>|`--installed`):
+#:    Show dependencies as a tree. When given multiple formula arguments, output
+#:    individual trees for every formula.
+#:
+#:    If `--installed` is passed, output a tree for every installed formula.
+#:
+#:    The <filters> placeholder is any combination of options `--include-build`,
+#:    `--include-optional`, and `--skip-recommended` as documented above.
+#:
+#:  * `deps` [<filters>] (`--installed`|`--all`):
+#:    Show dependencies for installed or all available formulae. Every line of
+#:    output starts with the formula name, followed by a colon and all direct
+#:    dependencies of that formula.
+#:
+#:    The <filters> placeholder is any combination of options `--include-build`,
+#:    `--include-optional`, and `--skip-recommended` as documented above.
 
 # encoding: UTF-8
 require "formula"

share/doc/homebrew/brew.1.html

@@ -90,9 +90,8 @@ will thus not add the SHA256 to the formula for you.</p>
 
 <p>The options <code>--set-name</code> and <code>--set-version</code> each take an argument and allow
 you to explicitly set the name and version of the package you are creating.</p></dd>
-<dt><code>deps</code> [<code>--1</code>] [<code>-n</code>] [<code>--union</code>] [<code>--tree</code>] [<code>--all</code>] [<code>--installed</code>] [<code>--include-build</code>] [<code>--include-optional</code>] [<code>--skip-recommended</code>] <var>formulae</var></dt><dd><p>Show dependencies for <var>formulae</var>. When given multiple formula arguments,
+<dt><code>deps</code> [<code>--1</code>] [<code>-n</code>] [<code>--union</code>] [<code>--installed</code>] [<code>--include-build</code>] [<code>--include-optional</code>] [<code>--skip-recommended</code>] <var>formulae</var></dt><dd><p>Show dependencies for <var>formulae</var>. When given multiple formula arguments,
-show the intersection of dependencies for <var>formulae</var>, except when passed
+show the intersection of dependencies for <var>formulae</var>.</p>
-<code>--tree</code>, <code>--all</code>, or <code>--installed</code>.</p>
 
 <p>If <code>--1</code> is passed, only show dependencies one level down, instead of
 recursing.</p>
@@ -102,16 +101,26 @@ recursing.</p>
 <p>If <code>--union</code> is passed, show the union of dependencies for <var>formulae</var>,
 instead of the intersection.</p>
 
-<p>If <code>--tree</code> is passed, show dependencies as a tree.</p>
+<p>If <code>--installed</code> is passed, only list those dependencies that are
-
+currently installed.</p>
-<p>If <code>--all</code> is passed, show dependencies for all formulae.</p>
-
-<p>If <code>--installed</code> is passed, show dependencies for all installed formulae.</p>
 
 <p>By default, <code>deps</code> shows required and recommended dependencies for
 <var>formulae</var>. To include the <code>:build</code> type dependencies, pass <code>--include-build</code>.
 Similarly, pass <code>--include-optional</code> to include <code>:optional</code> dependencies.
 To skip <code>:recommended</code> type dependencies, pass <code>--skip-recommended</code>.</p></dd>
+<dt><code>deps</code> <code>--tree</code> [<var>filters</var>] (<var>formulae</var>|<code>--installed</code>)</dt><dd><p>Show dependencies as a tree. When given multiple formula arguments, output
+individual trees for every formula.</p>
+
+<p>If <code>--installed</code> is passed, output a tree for every installed formula.</p>
+
+<p>The <var>filters</var> placeholder is any combination of options <code>--include-build</code>,
+<code>--include-optional</code>, and <code>--skip-recommended</code> as documented above.</p></dd>
+<dt><code>deps</code> [<var>filters</var>] (<code>--installed</code>|<code>--all</code>)</dt><dd><p>Show dependencies for installed or all available formulae. Every line of
+output starts with the formula name, followed by a colon and all direct
+dependencies of that formula.</p>
+
+<p>The <var>filters</var> placeholder is any combination of options <code>--include-build</code>,
+<code>--include-optional</code>, and <code>--skip-recommended</code> as documented above.</p></dd>
 <dt><code>desc</code> <var>formula</var></dt><dd><p>Display <var>formula</var>'s name and one-line description.</p></dd>
 <dt><code>desc</code> [<code>-s</code>|<code>-n</code>|<code>-d</code>] <var>pattern</var></dt><dd><p>Search both name and description (<code>-s</code>), just the names (<code>-n</code>), or just  the
 descriptions (<code>-d</code>) for <code>&lt;pattern></code>. <code>&lt;pattern></code> is by default interpreted

share/man/man1/brew.1

@@ -123,8 +123,8 @@ If \fB\-\-no\-fetch\fR is passed, Homebrew will not download \fIURL\fR to the ca
 The options \fB\-\-set\-name\fR and \fB\-\-set\-version\fR each take an argument and allow you to explicitly set the name and version of the package you are creating\.
 .
 .TP
-\fBdeps\fR [\fB\-\-1\fR] [\fB\-n\fR] [\fB\-\-union\fR] [\fB\-\-tree\fR] [\fB\-\-all\fR] [\fB\-\-installed\fR] [\fB\-\-include\-build\fR] [\fB\-\-include\-optional\fR] [\fB\-\-skip\-recommended\fR] \fIformulae\fR
+\fBdeps\fR [\fB\-\-1\fR] [\fB\-n\fR] [\fB\-\-union\fR] [\fB\-\-installed\fR] [\fB\-\-include\-build\fR] [\fB\-\-include\-optional\fR] [\fB\-\-skip\-recommended\fR] \fIformulae\fR
-Show dependencies for \fIformulae\fR\. When given multiple formula arguments, show the intersection of dependencies for \fIformulae\fR, except when passed \fB\-\-tree\fR, \fB\-\-all\fR, or \fB\-\-installed\fR\.
+Show dependencies for \fIformulae\fR\. When given multiple formula arguments, show the intersection of dependencies for \fIformulae\fR\.
 .
 .IP
 If \fB\-\-1\fR is passed, only show dependencies one level down, instead of recursing\.
@@ -136,18 +136,29 @@ If \fB\-n\fR is passed, show dependencies in topological order\.
 If \fB\-\-union\fR is passed, show the union of dependencies for \fIformulae\fR, instead of the intersection\.
 .
 .IP
-If \fB\-\-tree\fR is passed, show dependencies as a tree\.
+If \fB\-\-installed\fR is passed, only list those dependencies that are currently installed\.
-.
-.IP
-If \fB\-\-all\fR is passed, show dependencies for all formulae\.
-.
-.IP
-If \fB\-\-installed\fR is passed, show dependencies for all installed formulae\.
 .
 .IP
 By default, \fBdeps\fR shows required and recommended dependencies for \fIformulae\fR\. To include the \fB:build\fR type dependencies, pass \fB\-\-include\-build\fR\. Similarly, pass \fB\-\-include\-optional\fR to include \fB:optional\fR dependencies\. To skip \fB:recommended\fR type dependencies, pass \fB\-\-skip\-recommended\fR\.
 .
 .TP
+\fBdeps\fR \fB\-\-tree\fR [\fIfilters\fR] (\fIformulae\fR|\fB\-\-installed\fR)
+Show dependencies as a tree\. When given multiple formula arguments, output individual trees for every formula\.
+.
+.IP
+If \fB\-\-installed\fR is passed, output a tree for every installed formula\.
+.
+.IP
+The \fIfilters\fR placeholder is any combination of options \fB\-\-include\-build\fR, \fB\-\-include\-optional\fR, and \fB\-\-skip\-recommended\fR as documented above\.
+.
+.TP
+\fBdeps\fR [\fIfilters\fR] (\fB\-\-installed\fR|\fB\-\-all\fR)
+Show dependencies for installed or all available formulae\. Every line of output starts with the formula name, followed by a colon and all direct dependencies of that formula\.
+.
+.IP
+The \fIfilters\fR placeholder is any combination of options \fB\-\-include\-build\fR, \fB\-\-include\-optional\fR, and \fB\-\-skip\-recommended\fR as documented above\.
+.
+.TP
 \fBdesc\fR \fIformula\fR
 Display \fIformula\fR\'s name and one\-line description\.
 .