85
It Took 6+ Years For Linux's "New" Mount API To Be Properly Documented In Man Pages
(www.phoronix.com)
this post was submitted on 30 Dec 2025
85 points (97.8% liked)
Linux
10813 readers
446 users here now
A community for everything relating to the GNU/Linux operating system (except the memes!)
Also, check out:
Original icon base courtesy of lewing@isc.tamu.edu and The GIMP
founded 2 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
Groff is indeed such a crap format to write documentation in. It nearly reads like zalgo.
I can't wait for the anti markdown people to come out of the woodwork though and complain that it's "the progressivist agenda" to be more user friendly because devs aren't users.
"If you can't write Groff, maybe you dont deserve to read the output"
"The markdown evangelists are so annoying. You can't just rewrite everything in markdown"
"When will this markdown craze stop??? I can't hear it anymore!"
Identity politics entered the developer arena.
Missing features in Markdown:
I'm not saying not to use md (vs. asciidoc/tor, restex or orgmode) but to add the features please.
Description lists?
Richtext? Like this or this ?
SVG handling? I've never seen a manpage with SVGs nor have I seen a manpage with images, much less image captions.
This is from wanting to use markdown for more than tech. documentation, like saving some simple websites.
No, like the mentioned
<u>underline</u>(this is how you write it in ~~markdown~~ html).These days there's scdoc, you can see the source for a man page written in it here, and the output here.
Honestly this is the first I've heard of groff, but I'd be surprised if it's not easy to transpile a Markdown document into the format. Have written only Markdown-based docs for a decade
By hand—if you have experience writing roff typesetting—it is.
Having a program do it for you... you're going to get something, but it won't be correct and you will need to fix most of it.
A few problems come to mind:
It's a macro-based typesetting language. As a consequence, there's a one-to-many association between representations in Markdown with some equivalent in
roff. A Markdown paragraph is just a paragraph, but inroffit could be an un-indented paragraph, a paragraph with first-line indentation, a paragraph with line-wrap indentation, or a paragraph with a left margin.Rendering a man page, you have multiple different implementations of
manand multiple different implementations of *roff(roff,troff,groff,nroff). The set of macros and features that are available differ depending on which implementation, resulting in one-size-fits-all solutions targeting the lowest common denominator.Ironically, the one-to-many association goes both ways. With Markdown, you have code fences, quotes, italic text, bold text, and tables. With lowest-common-denominator manpage
roff, you have paragraphs and emphasis that will either be shown as bold or inverted. If you're lucky, you might also be able to use underlines. If Markdown tables are no wider than 80 characters, you could preprocess those into plain characters, at least.Despite being more structured with its typesetting, the contents of a manpage are mostly still unstructured. The individual sections within the page and its use of indentation and emphasis are entirely convention, and not represented in the source code by anything more than just typesetting macro primitives.
It could work out if you generate both the Markdown and
manpage from something with more explicit structure. If the plan is to go from a loose Markdown document into a manpage, you're going to end up having to write your Markdown document almost exactly like a manpage.Pandoc actually does a reasonable job at turning (Pandoc flavored) markdown into man-roff. Sure it doesn't work for arbitrary markdown but it's good enough to avoid writing roff by hand.
The main reason I see for not doing that (and using something like scdoc instead) is that you end up with a Haskell toolchain in your dependency graph.
I love groff! But i don't write documentation, so that may be why.