Re: ioperm(2): confusing terminology

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 2134 bytes --]

Hi astian,

> Date: 2026-09-17 07:04:37+0000
> From: astian <astian@memeware.net>
>
> On 14 Sep 2026 14:56 +0200, Alejandro Colomar wrote:
> [...]
> >> 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.
> 
> Sorry, I didn't read groff_man fully, but I'm curious: what is the
> meaning of newlines in man that gets lost in those other formats?

They have no meaning.

> Looking at some source pages now and it seems most newlines are about as
> (non) meaningful as in those formats (i.e., the paragraph is reflowed
> during rendering).

I don't know how you read .md or .rst, but I read them in the terminal,
usually with less(1), which doesn't reflow them.  Is there any program
for reading these in the terminal reflowed?

> > 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.
> >
> > A summary that will serve for 95%+ of the text written in manual pages:
> >
> > 		.SH section heading
> > 		.SS sub section
> > 		.B bold
> > 		.I italics
> >
> > 	Alternating per word (spaces removed):
> > 		.BI bold italics
> > 		.IB italics bold
> > 		.BR bold roman
> > 		.RB roman bold
> > 		.IR italics roman
> > 		.RI roman italics
> > 	(roman means normal)
> >
> > 	paragraph separator:
> > 		.P
> > 	Indented paragraph:
> > 		.IP
> > 	Tagged paragraph:
> > 		.TP
> > 		tag
> >
> > 	Examples:
> > 		.EX
> > 		this is an example (monospace, no fill)
> > 		.EE
> 
> Thanks for the synopsis.

You're welcome!


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]