gist-logs: add proper documentation, improve error handling (#217)

2 files changed, 24 insertions, 2 deletions

diff --git a/share/doc/homebrew/brew.1.html b/share/doc/homebrew/brew.1.html
index fa5a1e9bb..bd6f9f5cf 100644
--- a/share/doc/homebrew/brew.1.html
+++ b/share/doc/homebrew/brew.1.html
@@ -157,6 +157,15 @@ bottle.</p>
 
 <p>If <code>--force-bottle</code> is passed, download a bottle if it exists for the current
 version of OS X, even if it would not be used during installation.</p></dd>
+<dt><code>gist-logs</code> [<code>--new-issue</code>|<code>-n</code>] <var>formula</var></dt><dd><p> Upload logs for a failed build of <var>formula</var> to a new Gist.</p>
+
+<p> <var>formula</var> is usually the name of the formula to install, but it can be specified
+ in several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p>
+
+<p> If <code>--new-issue</code> is passed, automatically create a new issue in the appropriate
+ GitHub repository as well as creating the Gist.</p>
+
+<p> If no logs are found, an error message is presented.</p></dd>
 <dt class="flush"><code>home</code></dt><dd><p>Open Homebrew's own homepage in a browser.</p></dd>
 <dt><code>home</code> <var>formula</var></dt><dd><p>Open <var>formula</var>'s homepage in a browser.</p></dd>
 <dt><code>info</code> <var>formula</var></dt><dd><p>Display information about <var>formula</var>.</p></dd>
@@ -174,7 +183,7 @@ information on all installed formulae.</p>
 <dt><code>install</code> [<code>--debug</code>] [<code>--env=</code><var>std</var>|<var>super</var>] [<code>--ignore-dependencies</code>] [<code>--only-dependencies</code>] [<code>--cc=</code><var>compiler</var>] [<code>--build-from-source</code>|<code>--force-bottle</code>] [<code>--devel</code>|<code>--HEAD</code>] [<code>--keep-tmp</code>] <var>formula</var></dt><dd><p>Install <var>formula</var>.</p>
 
 <p><var>formula</var> is usually the name of the formula to install, but it can be specified
-several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p>
+in several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p>
 
 <p>If <code>--debug</code> is passed and brewing fails, open an interactive debugging
 session with access to IRB or a shell inside the temporary build directory.</p>
diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index badfa86ca..9db7b58c4 100644
--- a/share/man/man1/brew.1
+++ b/share/man/man1/brew.1
@@ -211,6 +211,19 @@ If \fB\-\-build\-from\-source\fR is passed, download the source rather than a bo
 If \fB\-\-force\-bottle\fR is passed, download a bottle if it exists for the current version of OS X, even if it would not be used during installation\.
 .
 .TP
+\fBgist\-logs\fR [\fB\-\-new\-issue\fR|\fB\-n\fR] \fIformula\fR
+Upload logs for a failed build of \fIformula\fR to a new Gist\.
+.
+.IP
+\fIformula\fR is usually the name of the formula to install, but it can be specified in several different ways\. See \fISPECIFYING FORMULAE\fR\.
+.
+.IP
+If \fB\-\-new\-issue\fR is passed, automatically create a new issue in the appropriate GitHub repository as well as creating the Gist\.
+.
+.IP
+If no logs are found, an error message is presented\.
+.
+.TP
 \fBhome\fR
 Open Homebrew\'s own homepage in a browser\.
 .
@@ -244,7 +257,7 @@ See the docs for examples of using the JSON: \fIhttps://github\.com/Homebrew/bre
 Install \fIformula\fR\.
 .
 .IP
-\fIformula\fR is usually the name of the formula to install, but it can be specified several different ways\. See \fISPECIFYING FORMULAE\fR\.
+\fIformula\fR is usually the name of the formula to install, but it can be specified in several different ways\. See \fISPECIFYING FORMULAE\fR\.
 .
 .IP
 If \fB\-\-debug\fR is passed and brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory\.