136
It Took 6+ Years For Linux's "New" Mount API To Be Properly Documented In Man Pages (www.phoronix.com)
submitted 3 months ago by cm0002@lemy.lol to c/linux@programming.dev
23 comments fedilink hide all child comments

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.

you are viewing a single comment's thread
view the rest of the comments
[-] onlinepersona@programming.dev 39 points 3 months ago

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.

[-] linuxPIPEpower@discuss.tchncs.de 2 points 3 months ago

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:

  • shell completion can be generated automatically from the man pages.
  • a website like mankier.com which renders man pages in HTML and adds hyperlinks every time an option or argument
load more comments (17 replies)
this post was submitted on 30 Dec 2025
136 points (97.9% liked)

Linux

13347 readers
249 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
Ategon@programming.dev
anzo@programming.dev
dwraf_of_ignorance@programming.dev