3 ms·
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 Li
by masto 3y ago
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.
- zerojames 3y agoI 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 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
- deleted 3y ago[deleted]
- jorams 3y ago> * 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.
- zerojames 3y agoGood 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!
- jorams 3y agoI 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.