Generate man pages using Go instead of Ruby

.gitignore

@@ -4,7 +4,7 @@
 .bundle
 bundle/
 share/man/*
-!share/man/man1/hub.1.ronn
+!share/man/man1/hub.1.md
 tmp/
 *.test
 target

Gemfile

@@ -3,4 +3,3 @@ source 'https://rubygems.org'
 gem 'aruba', '~> 0.5.3'
 gem 'cucumber', '~> 1.3.9'
 gem 'sinatra'
-gem 'ronn'

Gemfile.lock

@@ -21,20 +21,12 @@ GEM
       multi_json (~> 1.3)
     gherkin (2.12.2-java)
       multi_json (~> 1.3)
-    hpricot (0.8.4)
-    hpricot (0.8.4-java)
     multi_json (1.13.1)
     multi_test (0.1.2)
-    mustache (0.99.4)
     mustermann (1.0.2)
     rack (2.0.5)
     rack-protection (2.0.3)
       rack
-    rdiscount (1.6.8)
-    ronn (0.7.3)
-      hpricot (>= 0.8.2)
-      mustache (>= 0.7.0)
-      rdiscount (>= 1.5.8)
     rspec-expectations (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
@@ -53,8 +45,7 @@ PLATFORMS
 DEPENDENCIES
   aruba (~> 0.5.3)
   cucumber (~> 1.3.9)
-  ronn
   sinatra
 
 BUNDLED WITH
-   1.16.0
+   1.17.1

Gopkg.toml

@@ -30,6 +30,10 @@
   name = "github.com/ogier/pflag"
   version = "0.0.1"
 
+[[constraint]]
+  branch = "v2"
+  name = "github.com/russross/blackfriday"
+
 [[constraint]]
   branch = "master"
   name = "golang.org/x/crypto"

Makefile

@@ -1,4 +1,6 @@
 SOURCES = $(shell script/build files)
+TODAY_DATE = $(shell date '+%d %b %Y')
+HUB_VERSION = $(shell hub version | tail -1)
 
 MIN_COVERAGE = 89.4
 
@@ -47,26 +49,29 @@ else
 	script/test
 endif
 
-bin/ronn bin/cucumber:
+bin/cucumber:
 	script/bootstrap
 
 fmt:
 	go fmt ./...
 
-man-pages: $(HELP_ALL:=.ronn) $(HELP_ALL) $(HELP_ALL:=.txt)
+man-pages: $(HELP_ALL:=.md) $(HELP_ALL) $(HELP_ALL:=.txt)
 
-%.txt: %.ronn
+%.txt: %
 	groff -Wall -mtty-char -mandoc -Tutf8 -rLL=$(TEXT_WIDTH)n $< | col -b >$@
 
 $(HELP_ALL): share/man/.man-pages.stamp
-share/man/.man-pages.stamp: bin/ronn $(HELP_ALL:=.ronn)
-	bin/ronn --organization=GITHUB --manual="Hub Manual" share/man/man1/*.ronn
+share/man/.man-pages.stamp: $(HELP_ALL:=.md) ./man-template.html
+	go run md2roff-bin/cmd.go --manual="hub manual" \
+		--date="$(TODAY_DATE)" --version="$(HUB_VERSION)" \
+		--template=./man-template.html \
+		share/man/man1/*.md
 	touch $@
 
-%.1.ronn: bin/hub
-	bin/hub help $(*F) --plain-text | script/format-ronn $(*F) $@
+%.1.md: bin/hub
+	bin/hub help $(*F) --plain-text >$@
 
-share/man/man1/hub.1.ronn:
+share/man/man1/hub.1.md:
 	true
 
 install: bin/hub man-pages

commands/commands.go

@@ -2,6 +2,7 @@ package commands
 
 import (
 	"fmt"
+	"regexp"
 	"strings"
 
 	"github.com/github/hub/ui"
@@ -107,9 +108,28 @@ func (c *Command) Synopsis() string {
 }
 
 func (c *Command) HelpText() string {
-	return fmt.Sprintf("%s\n\n%s",
-		strings.Replace(c.Synopsis(), "-^", "`-^`", 1),
-		strings.Replace(c.Long, "'", "`", -1))
+	usage := strings.Replace(c.Usage, "-^", "`-^`", 1)
+	usageRe := regexp.MustCompile(`(?m)^([a-z-]+)(.*)$`)
+	usage = usageRe.ReplaceAllString(usage, "`hub $1`$2  ")
+	usage = strings.TrimSpace(usage)
+
+	var desc string
+	long := strings.TrimSpace(c.Long)
+	if lines := strings.Split(long, "\n"); len(lines) > 1 {
+		desc = lines[0]
+		long = strings.Join(lines[1:], "\n")
+	}
+
+	long = strings.Replace(long, "'", "`", -1)
+	headingRe := regexp.MustCompile(`(?m)^(## .+):$`)
+	long = headingRe.ReplaceAllString(long, "$1")
+
+	indentRe := regexp.MustCompile(`(?m)^\t`)
+	long = indentRe.ReplaceAllLiteralString(long, "")
+	definitionListRe := regexp.MustCompile(`(?m)^(\* )?([^#\s][^\n]*?):?\n\t`)
+	long = definitionListRe.ReplaceAllString(long, "$2\n:\t")
+
+	return fmt.Sprintf("hub-%s(1) -- %s\n===\n\n## Synopsis\n\n%s\n%s", c.Name(), desc, usage, long)
 }
 
 func (c *Command) Name() string {

commands/help.go

@@ -29,15 +29,15 @@ help hub-<COMMAND> [--plain-text]
 	--plain-text
 		Skip man page lookup mechanism and display plain help text.
 
-## Man lookup mechanism:
+## Lookup mechanism:
 
 On systems that have 'man', help pages are looked up in these directories
-relative to 'hub' install prefix:
+relative to the hub install prefix:
 
-* 'man/<command>.1'
-* 'share/man/man1/<command>.1'
+* man/<command>.1
+* share/man/man1/<command>.1
 
-On systems without 'man', same help pages are looked up with a '.txt' suffix.
+On systems without 'man', help pages are looked up using the ".txt" extension.
 
 ## See also:
 

commands/issue.go

@@ -155,6 +155,10 @@ With no arguments, show a list of open issues.
 
 	--color
 		Enable colored output for labels list.
+
+## See also:
+
+hub-pr(1), hub(1)
 `,
 	}
 

commands/release.go

@@ -51,10 +51,10 @@ With '--exclude-prereleases', exclude non-stable releases from the listing.
 		and body unchanged, pass '-m ""'.
 
 	* _download_:
-	  Download the assets attached to release for the specified <TAG>.
+		Download the assets attached to release for the specified <TAG>.
 
 	* _delete_:
-	  Delete the release and associated assets for the specified <TAG>.
+		Delete the release and associated assets for the specified <TAG>.
 
 ## Options:
 	-L, --limit

features/help.feature

@@ -15,4 +15,4 @@ Feature: hub help
 
   Scenario: Shows help for a subcommand
     When I successfully run `hub help hub-help`
-    Then the output should contain "Usage: hub help"
+    Then the output should contain "`hub help` hub-<COMMAND>"

man-template.html

@@ -0,0 +1,91 @@
+<!doctype html>
+<title>{{.Name}}({{.Section}}) - {{.Title}}</title>
+<meta charset="utf-8">
+
+<style>
+body {
+  margin: 0;
+  font: 15px/1.4 -apple-system,Segoe UI,Helvetica,Arial,sans-serif;
+}
+pre, code, var, dt, .man-head {
+  font-family: SFMono-Regular,Consolas,Liberation Mono,Menlo,Courier,monospace;
+}
+header, footer {
+  padding: .5em 2em;
+}
+.man-head {
+  color: #999;
+  padding: 0;
+  width: 100%;
+  float: left;
+  list-style-type: none;
+}
+header .man-head {
+  text-transform: uppercase;
+}
+.man-head li {
+  width: 33%;
+  float: left;
+}
+.tl { text-align: left }
+.tc { text-align: center }
+.tr { text-align: right; float: right }
+article {
+  max-width: 110ex;
+  margin: 4em auto 2em;
+}
+h1 {
+  font-size: 1em;
+  font-weight: normal;
+}
+h2 {
+  text-transform: uppercase;
+}
+code {
+  color: darkslategray;
+  font-weight: bold;
+}
+var {
+  color: orangered;
+  font-weight: normal;
+  font-style: normal;
+}
+dt {
+  margin: .5em 0;
+}
+dd {
+  margin-bottom: 1em;
+}
+pre {
+  background: #eee;
+  padding: 1em 1.5em;
+}
+pre code {
+  color: inherit;
+  font-weight: inherit;
+}
+var::before { content: "<" }
+var::after { content: ">" }
+a:link, a:hover, a:visited { color: blue }
+</style>
+
+<header>
+  <ol class="man-head">
+    <li class="tl">{{.Name}}({{.Section}})</li>
+    <li class="tc">{{.Manual}}</li>
+    <li class="tr">{{.Name}}({{.Section}})</li>
+  </ol>
+</header>
+
+<article>
+  <h1>{{.Title}}</h1>
+  {{.Contents}}
+</article>
+
+<footer>
+  <ol class="man-head">
+    <li class="tl">{{.Version}}</li>
+    <li class="tc">{{.Date}}</li>
+    <li class="tr"></li>
+  </ol>
+</footer>