Markdown as a "less hairy" source format for man pages (was: ioperm(2): confusing terminology)

[G. Branden Robinson]

Hi Alex,

At 2026-09-14T14:56:21+0200, Alejandro Colomar wrote:
> > Date: 2026-09-13 06:29:43+0000
> > From: astian <astian@xxxxxxxxxxxx>
> > Sorry, I've never written *roff before
> 
> I've never written roff(7) myself, but luckily, man(7) is much simpler
> than roff(7).
> 
> > and I don't think I want to spend my time learning that... although,
> > I might be able do this by just blindly replacing words without
> > touching the escapes...
> 
> Indeed, that's how I learnt man(7).  Replacing words blindly is quite
> easier than it seems.  I was also scared the first time I wanted to
> fix a bug in a manual page, but I found it was easier than I thought.
> 
> > Which bring up the question, why not moving to a less hairy source
> > format?
> 
> This question comes up every now and then.  TL;DR: other formats are
> worse.
> 
> man(7) is pretty simple, and easy to learn exactly by editing words
> blindly.  There are very few macros, and their behavior is trivial
> once you use them a few times.
> 
> One thing that is very important is that we use semantic newlines.
> That discards .md and .rst, since they are meant to be written with
> paragraphs as they'd be read by humans.  mdoc(7) is more complex than
> man(7), and thus we don't want that.  There are other formats, also
> inappropriate, for the same or other reasons.
[...]

Another reason to not underestimate the "hairiness" of "plain text"
markup languages relative to man(7) is revealed by the sorts of trouble
that people get into with at least some of its dialects.

Here's an example from the util-linux project, which maintains its man
pages in AsciiDoc.

commit 36e1fb5802c0948f13ba0ec4ac68c94cb24856db
Author: Thomas Weißschuh <thomas@xxxxxxxx>
Date:   Mon Apr 27 15:24:47 2026 +0200

    lastlog2: (man) fix example syntax

    The examples are not using the right syntax for literal blocks,
    leading to errors from asciidoctor.

    Use the correct syntax.

    Fixes: cd112d860bf6 ("lastlog2: add --journal option to manage SQLite journal mode")
    Signed-off-by: Thomas Weißschuh <thomas@xxxxxxxx>

diff --git a/misc-utils/lastlog2.8.adoc b/misc-utils/lastlog2.8.adoc
index b8fcb055c..20a971242 100644
--- a/misc-utils/lastlog2.8.adoc
+++ b/misc-utils/lastlog2.8.adoc
@@ -91,19 +91,19 @@
 == EXAMPLES

 Display the current journal mode:
-----
+....
 lastlog2 -j
-----
+....

 Enable WAL mode for better concurrency (recommended for high-traffic servers):
-----
+....
 lastlog2 -j WAL
-----
+....

 Switch back to the default DELETE mode:
-----
+....
 lastlog2 -j DELETE
-----
+....

 == FILES
---end snip; there was much more in the same vein after this---

Not long ago I diagnosed our industry's collective, and persistent,
refusal to believe that writing worthwhile documentation could ever be a
more demanding task than the simplest computer program one can code.

https://lore.kernel.org/linux-man/20260710195854.ud4riftmhrfzu54d@illithid/

Regards,
Branden

Attachment: signature.asc
Description: PGP signature