Generate the man page with go-md2man instead of md2man-roff (#408)

* Generate the man page with go-md2man instead of md2man-roff

md2man-roff is distributed only as a Ruby gem -- it is in neither Homebrew
nor apt -- so in practice nobody has it installed and man/tippecanoe.1
drifts away from README.md. It was stale again as of #400: the man page
still had the dead All Streets link that commit fixed.

Switch to go-md2man, the maintained Go port of the same converter (it is
what Docker, podman and runc use). It is packaged as a single static
binary for Homebrew, apt, Fedora and Alpine, and it renders inline code as
bold the same way md2man-roff did, so the man page still reads the way it
used to.

It also emits valid roff, which md2man-roff did not. `mandoc -T lint` goes
from 621 errors and warnings to 1 (an empty .TH date, left empty on
purpose so that generation stays reproducible). 590 of those were
`invalid escape sequence: \fC`, from md2man-roff wrapping every inline
code span in `\fB\fC` -- `\fC` is not a font escape.

md2man-roff was losing content, too:

  README:      1/(2^32) of the size of Earth
  md2man-roff: 1/(2 of the size of Earth
  go-md2man:   1/(2^32) of the size of Earth

  README:      '{"attr": "operation", "attr2": "operation2"}'
  md2man-roff: '{"attr": "operation", "attr2", "operation2"}'
  go-md2man:   '{"attr": "operation", "attr2": "operation2"}'

Prepend a title block and a NAME section during generation rather than
adding them to README.md, where they would render as noise on GitHub.
The man page had neither, so its header rendered as "tippecanoe()" with no
section, and `man -k tippecanoe` and `whatis tippecanoe` found nothing.
It now renders as TIPPECANOE(1) and is indexed.

Finally, add a CI job that regenerates the man page and fails if the
committed copy differs, so a README edit that needs `make docs` gets
caught rather than sitting stale until someone notices. This is what
makes the missing-tool problem stop mattering: contributors no longer
need go-md2man installed to keep the man page current, since CI will
tell them when it needs regenerating. The go-md2man version is pinned
there because different versions produce different roff for the same
input.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015B6PcMbNY779iaczo6S6Pu

* Strip the redundant blank lines go-md2man puts between paragraphs

go-md2man separates paragraphs with a blank line as well as a .PP macro.
A blank line is itself a break in roff, so the two together double-space
the page: every paragraph was followed by two blank lines rather than one.
md2man-roff did not do this, so it showed up as a regression -- the source
went from 13 blank lines to 200.

Filter them out after generation. Blank lines inside .EX and .TS blocks
are kept, since there they are part of the example or the table rather
than spacing around it; that is all 13 of the ones md2man-roff emitted.

The rendered page loses 186 blank lines and the source loses 187, with
byte-identical non-blank output under both groff -t -man and mandoc.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015B6PcMbNY779iaczo6S6Pu

* Decouple the man page from version.hpp, and name the first section

Review feedback on #408.

Making man/tippecanoe.1 depend on version.hpp turned the docs job into a
hard CI failure on any release commit that bumps the version without
regenerating -- #406, which is open and moves version.hpp to v2.81.0
without touching the man page, would have tripped it as soon as either
merged. The only thing the dependency bought was the version in the page
footer, so every release would have had to regenerate the whole file to
rewrite that one line, gated by CI. Drop it: the source field is now just
"tippecanoe", and the page depends on README.md alone.

Separately, README.md's own title heading became the second .SH, directly
below the NAME section this branch adds, so the page opened with a stray
"tippecanoe" section. Rename it to DESCRIPTION, which is where that text
belongs and what a reader expects after NAME.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015B6PcMbNY779iaczo6S6Pu

---------

Co-authored-by: Claude <noreply@anthropic.com>

.github/workflows/test.yml

@@ -19,3 +19,20 @@ jobs:
         run: brew install sqlite3
       - run: uname -a; BUILDTYPE=${{ matrix.version }} make
       - run: make test
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      # Pinned, because different go-md2man versions produce different roff
+      # for the same input, which would make this check fail spuriously.
+      - name: Install go-md2man
+        run: go install github.com/cpuguy83/go-md2man/v2@v2.0.7
+      - name: Regenerate the man page
+        run: PATH="$PATH:$(go env GOPATH)/bin" make -B docs
+      - name: Check that the man page is up to date with README.md
+        run: |
+          git diff --exit-code man/tippecanoe.1 || {
+            echo "::error::man/tippecanoe.1 is out of date. Run 'make docs' and commit the result."
+            exit 1
+          }

.gitignore

@@ -38,6 +38,9 @@ tippecanoe-json-tool
 tippecanoe-overzoom
 unit
 
+# Left behind if man page generation fails
+man/tippecanoe.1.tmp
+
 # Tests
 tests/**/*.mbtiles
 tests/**/*.check

Makefile

@@ -48,8 +48,44 @@ install: tippecanoe tippecanoe-enumerate tippecanoe-decode tile-join tippecanoe-
 uninstall:
 	rm $(PREFIX)/bin/tippecanoe $(PREFIX)/bin/tippecanoe-enumerate $(PREFIX)/bin/tippecanoe-decode $(PREFIX)/bin/tile-join $(MANDIR)/tippecanoe.1 $(PREFIX)/bin/tippecanoe-json-tool
 
+# The man page is generated from README.md by go-md2man, which is packaged for
+# most systems (`brew install go-md2man`, `apt-get install go-md2man`) or can be
+# built with `go install github.com/cpuguy83/go-md2man/v2@v2.0.7`. CI checks that
+# the committed man page matches the README, so you don't have to regenerate it
+# yourself if you don't have go-md2man installed.
+#
+# README.md has no .TH or NAME section of its own, since neither would make sense
+# on GitHub, so prepend them here. go-md2man reads the leading "%" line as the
+# man page's title, section, date, and source. The version deliberately doesn't
+# appear there: it would make this page a build product of version.hpp, so every
+# release would have to regenerate it just to rewrite that one line, and the docs
+# CI job would fail on any version bump that forgot to.
+#
+# Two fixups on the way out:
+#
+#   - README.md's own title heading becomes the second .SH, right below the NAME
+#     section added above, which reads as a stray "tippecanoe" section. Rename it
+#     to DESCRIPTION, where the text under it belongs anyway.
+#   - go-md2man separates paragraphs with a blank line in addition to the .PP
+#     macro, and a blank line is itself a break in roff, so the two together
+#     double-space the whole page. Drop them, except within .EX and .TS blocks,
+#     where a blank line is part of the example or table rather than spacing.
 man/tippecanoe.1: README.md
-	md2man-roff README.md > man/tippecanoe.1
+	{ \
+		echo '% TIPPECANOE 1 "" "tippecanoe"'; \
+		echo; \
+		echo '# NAME'; \
+		echo; \
+		echo 'tippecanoe - build vector tilesets from GeoJSON, FlatGeobuf, or CSV features'; \
+		echo; \
+		cat README.md; \
+	} | go-md2man \
+	  | awk ' \
+		/^\.SH / && ++sh == 2 { print ".SH DESCRIPTION"; next } \
+		/^\.(EX|TS)$$/ { lit = 1 } \
+		/^\.(EE|TE)$$/ { lit = 0 } \
+		lit || !/^$$/ \
+	    ' > $@.tmp && mv $@.tmp $@
 
 PG=
 

README.md

@@ -719,8 +719,13 @@ lower resolutions before failing if it still doesn't fit.
 Development
 -----------
 
-Requires sqlite3 and zlib (should already be installed on MacOS). Rebuilding the manpage
+Requires sqlite3 and zlib (should already be installed on MacOS).
-uses md2man (`gem install md2man`).
+
+The manpage is generated from this README by `make docs`, which uses
+[go-md2man](https://github.com/cpuguy83/go-md2man) (`brew install go-md2man` or
+`apt-get install go-md2man`). You don't have to run it yourself: CI regenerates the
+manpage and fails if the committed copy doesn't match, so it will tell you if an
+edit here needs `make docs` run against it.
 
 Linux: