Merge pull request #675 from github/config_man_page

Replace man page configurations with the ones from README.md

README.md

@@ -297,27 +297,41 @@ Configuration
 Hub will prompt for GitHub username & password the first time it needs to access
 the API and exchange it for an OAuth token, which it saves in "~/.config/hub".
 
+To avoid being prompted, use **GITHUB_USER** and **GITHUB_PASSWORD** environment
+variables.
+
 ### HTTPS instead of git protocol
 
-If you prefer the HTTPS protocol for GitHub repositories, you can
-set "hub.protocol" to "https". This will affect clone, fork, remote add and
-other operations that expand references to GitHub repositories 
-that otherwise use git and ssh protocols.
+If you prefer the HTTPS protocol for GitHub repositories, you can set
+"hub.protocol" to "https". This will affect `clone`, `fork`, `remote add`
+and other operations that expand references to GitHub repositories as full
+URLs that otherwise use git and ssh protocols.
 
 "hub.protocol" only applies when the "OWNER/REPO" shorthand is used instead of
 a full git URL.
 
-~~~ sh
-# default behavior
-$ git clone defunkt/repl
-< git clone >
-
-# opt into HTTPS:
-$ git config --global hub.protocol https
-$ git clone defunkt/repl
-< https clone >
-~~~
+    # default behavior
+    $ git clone defunkt/repl
+    < git clone >
+
+    # opt into HTTPS:
+    $ git config --global hub.protocol https
+    $ git clone defunkt/repl
+    < https clone >
+
+### GitHub Enterprise
+
+By default, hub will only work with repositories that have remotes which
+point to github.com. GitHub Enterprise hosts need to be whitelisted to
+configure hub to treat such remotes same as github.com:
+
+    $ git config --global --add hub.host my.git.org
+
+The default host for commands like `init` and `clone` is still
+github.com, but this can be affected with the <GITHUB_HOST> environment
+variable:
 
+    $ GITHUB_HOST=my.git.org git clone myproject
 
 Meta
 ----

Rakefile

@@ -6,36 +6,50 @@ end
 desc "Build man pages"
 task "man:build" => ["man/hub.1", "man/hub.1.html"]
 
-extract_examples = lambda { |readme_file|
-  # split readme in sections
-  examples = File.read(readme_file).split(/^-{4,}$/)[3].strip
+# split readme in sections
+# and return the specified section
+def split_readme(file, index)
+  File.read(file).split(/^-{4,}$/)[index].strip
+end
+
+def extract_configs(readme_file)
+  configs = split_readme(readme_file, 4)
+  configs.gsub!(/\*\*(.+?)\*\*/, '<\1>')      # replace **xx** with <xx>
+  configs.sub!(/\n+.+\Z/, '')                 # remove last line
+  configs
+end
+
+def extract_examples(readme_file)
+  examples = split_readme(readme_file, 3)
   examples.sub!(/^.+?(###)/m, '\1')  # strip intro paragraph
   examples.sub!(/\n+.+\Z/, '')       # remove last line
   examples
-}
+end
 
-# inject examples from README file to .ronn source
-source_with_examples = lambda { |source, readme|
-  examples = extract_examples.call(readme)
+# inject configs and examples from README file to .ronn source
+def compiled_source(source, readme)
+  configs = extract_configs(readme)
+  examples = extract_examples(readme)
   compiled = File.read(source)
+  compiled.sub!('{{CONFIGS}}', configs)
   compiled.sub!('{{README}}', examples)
   compiled
-}
+end
 
 # generate man page with ronn
-compile_ronn = lambda { |destination, type, contents|
+def compile_ronn(destination, type, contents)
   File.popen("ronn --pipe --#{type} --organization=GITHUB --manual='Hub Manual'", 'w+') { |io|
     io.write contents
     io.close_write
     File.open(destination, 'w') { |f| f << io.read }
   }
   abort "ronn --#{type} conversion failed" unless $?.success?
-}
+end
 
 file "man/hub.1" => ["man/hub.1.ronn", "README.md"] do |task|
-  contents = source_with_examples.call(*task.prerequisites)
-  compile_ronn.call(task.name, 'roff', contents)
-  compile_ronn.call("#{task.name}.html", 'html', contents)
+  contents = compiled_source(*task.prerequisites)
+  compile_ronn(task.name, 'roff', contents)
+  compile_ronn("#{task.name}.html", 'html', contents)
 end
 
 file "man/hub.1.html" => ["man/hub.1.ronn", "README.md"] do |task|

man/hub.1

@@ -171,19 +171,31 @@ success (0), error (1), failure (1), pending (2), no status (3)
 If \fB\-v\fR is given, additionally print the URL to CI build results\.
 .
 .SH "CONFIGURATION"
+.
+.SS "GitHub OAuth authentication"
 Hub will prompt for GitHub username & password the first time it needs to access the API and exchange it for an OAuth token, which it saves in "~/\.config/hub"\.
 .
 .P
 To avoid being prompted, use \fIGITHUB_USER\fR and \fIGITHUB_PASSWORD\fR environment variables\.
 .
+.SS "HTTPS instead of git protocol"
+If you prefer the HTTPS protocol for GitHub repositories, you can set "hub\.protocol" to "https"\. This will affect \fBclone\fR, \fBfork\fR, \fBremote add\fR and other operations that expand references to GitHub repositories as full URLs that otherwise use git and ssh protocols\.
+.
 .P
-If you prefer the HTTPS protocol for GitHub repositories, you can set "hub\.protocol" to "https"\. This will affect \fBclone\fR, \fBfork\fR, \fBremote add\fR and other operations that expand references to GitHub repositories as full URLs that otherwise use git and ssh protocols\. "hub\.protocol" only applies when the "OWNER/REPO" shorthand is used instead of a full git URL\.
+"hub\.protocol" only applies when the "OWNER/REPO" shorthand is used instead of a full git URL\.
 .
 .IP "" 4
 .
 .nf
 
+# default behavior
+$ git clone defunkt/repl
+< git clone >
+
+# opt into HTTPS:
 $ git config \-\-global hub\.protocol https
+$ git clone defunkt/repl
+< https clone >
 .
 .fi
 .

man/hub.1.html

@@ -211,19 +211,32 @@ success (0), error (1), failure (1), pending (2), no status (3)</p>
 
 <h2 id="CONFIGURATION">CONFIGURATION</h2>
 
+<h3 id="GitHub-OAuth-authentication">GitHub OAuth authentication</h3>
+
 <p>Hub will prompt for GitHub username &amp; password the first time it needs to access
 the API and exchange it for an OAuth token, which it saves in "~/.config/hub".</p>
 
 <p>To avoid being prompted, use <var>GITHUB_USER</var> and <var>GITHUB_PASSWORD</var> environment
 variables.</p>
 
+<h3 id="HTTPS-instead-of-git-protocol">HTTPS instead of git protocol</h3>
+
 <p>If you prefer the HTTPS protocol for GitHub repositories, you can set
 "hub.protocol" to "https". This will affect <code>clone</code>, <code>fork</code>, <code>remote add</code>
 and other operations that expand references to GitHub repositories as full
-URLs that otherwise use git and ssh protocols. "hub.protocol" only applies
-when the "OWNER/REPO" shorthand is used instead of a full git URL.</p>
+URLs that otherwise use git and ssh protocols.</p>
+
+<p>"hub.protocol" only applies when the "OWNER/REPO" shorthand is used instead of
+a full git URL.</p>
+
+<pre><code># default behavior
+$ git clone defunkt/repl
+&lt; git clone >
 
-<pre><code>$ git config --global hub.protocol https
+# opt into HTTPS:
+$ git config --global hub.protocol https
+$ git clone defunkt/repl
+&lt; https clone >
 </code></pre>
 
 <h3 id="GitHub-Enterprise">GitHub Enterprise</h3>

man/hub.1.ronn

@@ -170,33 +170,7 @@ hub also adds some custom commands that are otherwise not present in git:
 
 ## CONFIGURATION
 
-Hub will prompt for GitHub username & password the first time it needs to access
-the API and exchange it for an OAuth token, which it saves in "~/.config/hub".
-
-To avoid being prompted, use <GITHUB_USER> and <GITHUB_PASSWORD> environment
-variables.
-
-If you prefer the HTTPS protocol for GitHub repositories, you can set
-"hub.protocol" to "https". This will affect `clone`, `fork`, `remote add`
-and other operations that expand references to GitHub repositories as full
-URLs that otherwise use git and ssh protocols. "hub.protocol" only applies
-when the "OWNER/REPO" shorthand is used instead of a full git URL.
-
-    $ git config --global hub.protocol https
-
-### GitHub Enterprise
-
-By default, hub will only work with repositories that have remotes which
-point to github.com. GitHub Enterprise hosts need to be whitelisted to
-configure hub to treat such remotes same as github.com:
-
-    $ git config --global --add hub.host my.git.org
-
-The default host for commands like `init` and `clone` is still
-github.com, but this can be affected with the <GITHUB_HOST> environment
-variable:
-
-    $ GITHUB_HOST=my.git.org git clone myproject
+{{CONFIGS}}
 
 ## EXAMPLES