mirror of
https://github.com/felt/tippecanoe.git
synced 2026-10-02 16:35:40 +02:00
Erica FischerandClaude Opus 5
905fe84459
* 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>