In demonstrating one of the gaps of man pages in modern times and likely having hindered the adoption of the Linux kernel’s new mount API, it took more than six years for those system calls to be properly documented within man pages. The Linux “new” mount API was introduced back in mid-2019 with Linux 5.2 and since supported by key file-systems after several years but not until weeks ago was this file descriptor based mount API scoped out within man pages.
The “new” mount API for Linux is a set of system calls like fsopen and fsconfig for offering more flexibility than the Linux kernel’s long-used mount system call that is a one-shot approach compared to this modern multi-step design for better flexibility. In the kernels since Linux 5.2, various file-systems have transitioned to supporting the modern mount API. It was only earlier this year that F2FS added support for it as one of the last major file-systems without it.
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.
My personal bias is being pro markdown. I do not know groff so below is based on some inferences on my part.
But I don’t think markdown is suitable for man pages, which contain specific kinds of information structured in a prescribed way. Markdown doesn’t and can’t know about these.
As I understand it, because of using a more sophisticated structure than MD, its possible to do things like:
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.
Missing features in Markdown:
I’m not saying not to use md (vs. asciidoc/tor, restex or orgmode) but to add the features please.
Someone can correct this but iirc some implementations of markdown have image options like this:
Others put the size in
{ }after the main image item.Rich text is contrary to the structural focus of markdown. Why should it be added?
Guess we have a semantics problem here. I understand under “rich text” text with formatting, not the long since dead file format. Markup is the language used to add richness to the plain text, no?
Sorry I was trying to follow your meaning, because the example of absent rich text you gave was underlines. There is already basic text formatting support such as strong, emphasis, headings and links.
You could style any, all or none of those to have underlining. Whatever chosen rendering, they all have meaning independent from the applied style. What you are asking for is to have something that is purely a display style without any structural value. This is not coming to markdown any time soon. Hardly anyone uses underline as its own thing in html anymore, for good reasons.
Maybe this article will help to further explain.
Native SVG handling would be completely out of scope. The point of markdown is that it is supposed to be understandable in its plain text format. SVG is incompatible with that. The closest thing would be like mermaid charts but I think it’s quite a stretch even then.
I think you should just use HTML, it has a much larger array of tools that would suit your needs. Markdown is purposely constrained because it enables much more portability.
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.
That’s not rich text. Rich text is when a format is applied without structural reason.
You could have a markdown interpreter that displayed
**this***this*or_this_using any arbitrary format. You could change the color, weight, border, drop shadow, opacity, mouse over effects, font face… Any attribute.Lemmy has conventions but all
*really means is emphasis.No, like the mentioned
<u>underline</u>(this is how you write it inmarkdownhtml).This is from wanting to use markdown for more than tech. documentation, like saving some simple websites.
If you want to save a website use html
It’s only formatted text anyway, so why would i want to save it in a hard-to-read format with scripts and inline style noise and with frames and headers and footers in the way even if rendered? I care for the info only, it should look how i as the reader want it to look.
Typora has a convenient convert-on-paste feature. Sadly, there’s no such tool for asciidoctor and pandoc does noisy convert (lots of artifacts).
I used to use typora; it does have a really nice convert web->markdown. I think that it is done by some javascript or something because the other tools that have comparable quality I can think of off the top of my head are obsidian, joplin clipper and a couple of firefox extensions. I agree that in my experience pandoc and a couple other cli tools didn’t produce such nice results.
I also think in all those cases the browser is doing some of the work because it renders the page, discards a lot of irrelevant stuff, then you copy/convert just a selection portion of what’s visible. Whereas if you, for example, grab a raw html page through curl and send it to pandoc, none of that is done. You probably aren’t using Select All when you copy a page to typora, but pandoc would be faced with the entire page. I don’t know if there is a way to access the Reader View from the terminal but it would go a distance to cleaning up your pandoc conversion if you could start from there (for those sites on which it’s available).
I tried and failed to do the same thing but it’s not markdown’s fault. No matter how many bells and whistles markdown would get, the issue is in the conversion from html part.
True, but my points above are things i found lacking in comparison to asciidoctor, while there the desktop tooling is lacking (yes there’s asciidoc.js).