Comment by masto | Hacker News Reader

Comment by masto | Hacker News Reader

I don't know why this particular thing set off my pedanticism. Someone is slightly wrong on the Internet! Maybe because it started right off being needlessly Linux-centric. Or that I thought it would be one thing but it turned out to be a brief demo of content negotiation in NGINX.

In any case, a few pointless things that I seem compelled to say:

* It's not returning roff, as such. Those things like `.TH` are not part of roff, they are part of the macro package for writing man pages. * I was disappointed that there was no markdown-to-roff conversion, which seemed like it was going to be the interesting part of this post. At least use one of the existing ones. * On a similar note, this means that the text isn't really formatted correctly. roff is meant for one sentence per line of input, to distinguish between `.` to end a sentence vs. other uses. * Also also wik, this means that any line starting with a `.` will be interpreted as a command, potentially wreaking havoc.

Or maybe I'm just a grumpy old man.

I appreciate you sharing this! I wasn't aware of the exact ontology of how roff vs. man relate, and I went through several iterations of this post trying to get this right. There being other tools -- groff, nroff, etc. -- added to my confusion. A blog post unto itself is "here is what roff/man page/nroff/other variants are, here's how to use them." I would have appreciated a succinct description; I'm sure others would, too.

As for markdown to roff, I thought about it as a v2. As I started to think about implementing a parser, someone shared https://github.com/sunaku/md2man with me, which appears to solve the problem.

I'd need to figure out how to integrate this into my (Python) site that is built on GitHub Pages; a bit of tinkering would be required :D

> * I was disappointed that there was no markdown-to-roff conversion

I found this rather surprising too. Pandoc can trivially convert markdown to man-page roff. Insert that into the given template and it looks like more like an actual man page.

Good suggestion!

Context: All man pages are generated on the fly on GitHub Pages. My site generates ~2500 pages, for which 826 are eligible for a man page. I didn't want to introduce another parser since I just got my site build times down :D

I can counter increased build times with caching, but it gets a bit icky since some blog pages are evergreen (i.e. my blogroll). [insert cache invalidation complaint here] But there's certainly a way!

I feel that, build times can be a pain. I'm calling out to pandoc to build a static site and I've had to parallelize it to get build times down, and that's with far fewer pages.

Reply on news.ycombinator.com