man: generate Markdown man page.

The existing `brew.1.html` wasn't particularly pleasant to read and
given everything else in `docs/` is a Markdown file it makes sense to
generate a post-processed Markdown file that can in turn be used by
Jekyll to generate a nicely themed HTML file.

Library/Homebrew/dev-cmd/man.rb

@@ -27,7 +27,7 @@ module Homebrew
 
     regenerate_man_pages
 
-    if system "git", "-C", HOMEBREW_REPOSITORY, "diff", "--quiet", "docs/brew.1.html", "manpages"
+    if system "git", "-C", HOMEBREW_REPOSITORY, "diff", "--quiet", "docs/Manpage.md", "manpages"
       puts "No changes to manpage output detected."
     elsif ARGV.include?("--fail-if-changed")
       Homebrew.failed = true
@@ -38,7 +38,7 @@ module Homebrew
     Homebrew.install_gem_setup_path! "ronn"
 
     markup = build_man_page
-    convert_man_page(markup, TARGET_DOC_PATH/"brew.1.html")
+    convert_man_page(markup, TARGET_DOC_PATH/"Manpage.md")
     convert_man_page(markup, TARGET_MAN_PATH/"brew.1")
 
     cask_markup = (SOURCE_PATH/"brew-cask.1.md").read
@@ -53,8 +53,7 @@ module Homebrew
                  .grep(/^#:/)
                  .map { |line| line.slice(2..-1) }
                  .join
-    end
-            .reject { |s| s.strip.empty? || s.include?("@hide_from_man_page") }
+    end.reject { |s| s.strip.empty? || s.include?("@hide_from_man_page") }
   end
 
   def build_man_page
@@ -113,7 +112,7 @@ module Homebrew
 
   def target_path_to_format(target)
     case target.basename
-    when /\.html?$/ then ["--fragment", "HTML fragment"]
+    when /\.md$/    then ["--markdown", "markdown"]
     when /\.\d$/    then ["--roff", "man page"]
     else
       odie "Failed to infer output format from '#{target.basename}'."

docs/README.md

 # Documentation
 
 ## Users
+- [`brew` man-page (command documentation)](Manpage.md)
 - [Troubleshooting](Troubleshooting.md)
 - [Installation](Installation.md)
 - [Frequently Asked Questions](FAQ.md)