ioperm(2): confusing terminology

ioperm(2): confusing terminology

[astian]

ioperm(2) says:

  int ioperm(unsigned long from, unsigned long num, int turn_on);

  ioperm() sets the port access permission bits for the calling thread
  for num bits starting from port address from.  If turn_on is nonzero,
  then permission for the specified bits is enabled; otherwise it is
  disabled. [...]

The use of "bits" here is confusing/sloppy.

ioperm is supposed to enable or disable permission to access IO ports
for the calling thread.  In this API, the "permission bit" (singular) is
really "turn_on": 0 to disable access, non-zero to enable.  However this
description refers also "num bits starting from port address from" and
"the specified bits".  That seems to suggest that IO ports somehow refer
to "bits" and this API controls access permission to them, which is
bewildering.

Searching around I have seen that other versions of this manpage used to
say "bytes" instead of "bits", which is only slightly less bewildering.
Ports/addresses in the IO space refer neither to bits nor to bytes per
se, they are an abstract interface, like a syscall number/index.
(Architecturally, in some cases, these indices may in fact map to
processor registers which may in fact be portions of a contiguous
internal memory, so in some cases one could correctly say that the ports
refer to "bytes" in such memory, but this is obviously all very
low-level and microarchitecture-specific.  I think being aware of such
details actually makes this description more confusing.)

Apparently the reason for this confusing description is that for Linux
ioperm is a syscall and the kernel implements this syscall using a
bitmap with 1 bit (permitted/denied) for each port, in a contiguous
sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".

Thus "num bits starting from port address from" actually refers to the
bits of that bitmap: the bits [from, from+num) are set according to
turn_on.

This kind of implicit reference to implementation details is wicked.

Suggested change:

  ioperm() sets the calling thread's access permission for num ports
  starting from port address from.  If turn_on is nonzero, then
  permission for the specified ports is enabled; otherwise it is
  disabled. [...]

PS: Oh, also, maybe the title should say "set input/output port
permissions" instead of "set port input/output permissions".

Re: ioperm(2): confusing terminology

[Alejandro Colomar]

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

Hi astian,

> Date: 2026-09-12 22:00:57+0000
> From: astian <astian@memeware.net>
>
> ioperm(2) says:
> 
>   int ioperm(unsigned long from, unsigned long num, int turn_on);
> 
>   ioperm() sets the port access permission bits for the calling thread
>   for num bits starting from port address from.  If turn_on is nonzero,
>   then permission for the specified bits is enabled; otherwise it is
>   disabled. [...]
> 
> The use of "bits" here is confusing/sloppy.
> 
> ioperm is supposed to enable or disable permission to access IO ports
> for the calling thread.  In this API, the "permission bit" (singular) is
> really "turn_on": 0 to disable access, non-zero to enable.  However this
> description refers also "num bits starting from port address from" and
> "the specified bits".  That seems to suggest that IO ports somehow refer
> to "bits" and this API controls access permission to them, which is
> bewildering.
> 
> Searching around I have seen that other versions of this manpage used to
> say "bytes" instead of "bits", which is only slightly less bewildering.
> Ports/addresses in the IO space refer neither to bits nor to bytes per
> se, they are an abstract interface, like a syscall number/index.
> (Architecturally, in some cases, these indices may in fact map to
> processor registers which may in fact be portions of a contiguous
> internal memory, so in some cases one could correctly say that the ports
> refer to "bytes" in such memory, but this is obviously all very
> low-level and microarchitecture-specific.  I think being aware of such
> details actually makes this description more confusing.)
> 
> Apparently the reason for this confusing description is that for Linux
> ioperm is a syscall and the kernel implements this syscall using a
> bitmap with 1 bit (permitted/denied) for each port, in a contiguous
> sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".
> 
> Thus "num bits starting from port address from" actually refers to the
> bits of that bitmap: the bits [from, from+num) are set according to
> turn_on.
> 
> This kind of implicit reference to implementation details is wicked.
> 
> Suggested change:
> 
>   ioperm() sets the calling thread's access permission for num ports
>   starting from port address from.  If turn_on is nonzero, then
>   permission for the specified ports is enabled; otherwise it is
>   disabled. [...]

Hmmm, sounds reasonable.  Do you want to send a patch?  Or should
I write it?  (I don't mind; just asking in case you want to do it.)

> PS: Oh, also, maybe the title should say "set input/output port
> permissions" instead of "set port input/output permissions".

Same here.

BTW, the manual page also says:

     This  call  is  mostly for the i386 architecture.  On many
     other architectures it does not exist or will  always  re‐
     turn an error.

Is this still true?

Another issue:

     EIO    (on PowerPC) This call is not supported.

Is this really true?  Where this is not supported, I expect ENOSYS.

And yet another thing: should we document the parameters as being
uintptr_t instead of unsigned long?  They are the same exact type
always, AFAIK.  Or is there any system where they aren't?  If they are
the same, uintptr_t will better document that they are addresses.


Have a lovely night!
Alex

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

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

Re: ioperm(2): confusing terminology

[Alejandro Colomar]

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

Oops; I've fixed the mailing list address now.


Cheers,
Alex

> Date: 2026-09-13 00:24:17+0200
> From: Alejandro Colomar <alx@kernel.org>
>
> Hi astian,
> 
> > Date: 2026-09-12 22:00:57+0000
> > From: astian <astian@memeware.net>
> >
> > ioperm(2) says:
> > 
> >   int ioperm(unsigned long from, unsigned long num, int turn_on);
> > 
> >   ioperm() sets the port access permission bits for the calling thread
> >   for num bits starting from port address from.  If turn_on is nonzero,
> >   then permission for the specified bits is enabled; otherwise it is
> >   disabled. [...]
> > 
> > The use of "bits" here is confusing/sloppy.
> > 
> > ioperm is supposed to enable or disable permission to access IO ports
> > for the calling thread.  In this API, the "permission bit" (singular) is
> > really "turn_on": 0 to disable access, non-zero to enable.  However this
> > description refers also "num bits starting from port address from" and
> > "the specified bits".  That seems to suggest that IO ports somehow refer
> > to "bits" and this API controls access permission to them, which is
> > bewildering.
> > 
> > Searching around I have seen that other versions of this manpage used to
> > say "bytes" instead of "bits", which is only slightly less bewildering.
> > Ports/addresses in the IO space refer neither to bits nor to bytes per
> > se, they are an abstract interface, like a syscall number/index.
> > (Architecturally, in some cases, these indices may in fact map to
> > processor registers which may in fact be portions of a contiguous
> > internal memory, so in some cases one could correctly say that the ports
> > refer to "bytes" in such memory, but this is obviously all very
> > low-level and microarchitecture-specific.  I think being aware of such
> > details actually makes this description more confusing.)
> > 
> > Apparently the reason for this confusing description is that for Linux
> > ioperm is a syscall and the kernel implements this syscall using a
> > bitmap with 1 bit (permitted/denied) for each port, in a contiguous
> > sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".
> > 
> > Thus "num bits starting from port address from" actually refers to the
> > bits of that bitmap: the bits [from, from+num) are set according to
> > turn_on.
> > 
> > This kind of implicit reference to implementation details is wicked.
> > 
> > Suggested change:
> > 
> >   ioperm() sets the calling thread's access permission for num ports
> >   starting from port address from.  If turn_on is nonzero, then
> >   permission for the specified ports is enabled; otherwise it is
> >   disabled. [...]
> 
> Hmmm, sounds reasonable.  Do you want to send a patch?  Or should
> I write it?  (I don't mind; just asking in case you want to do it.)
> 
> > PS: Oh, also, maybe the title should say "set input/output port
> > permissions" instead of "set port input/output permissions".
> 
> Same here.
> 
> BTW, the manual page also says:
> 
>      This  call  is  mostly for the i386 architecture.  On many
>      other architectures it does not exist or will  always  re‐
>      turn an error.
> 
> Is this still true?
> 
> Another issue:
> 
>      EIO    (on PowerPC) This call is not supported.
> 
> Is this really true?  Where this is not supported, I expect ENOSYS.
> 
> And yet another thing: should we document the parameters as being
> uintptr_t instead of unsigned long?  They are the same exact type
> always, AFAIK.  Or is there any system where they aren't?  If they are
> the same, uintptr_t will better document that they are addresses.
> 
> 
> Have a lovely night!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es>



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

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

Re: ioperm(2): confusing terminology

[astian]

On 13 Sep 2026 00:24 +0200, Alejandro Colomar wrote:
> Hi astian,

Hi.

>> Date: 2026-09-12 22:00:57+0000
>> From: astian <astian@memeware.net>
>>
>> ioperm(2) says:
>>
>>   int ioperm(unsigned long from, unsigned long num, int turn_on);
>>
>>   ioperm() sets the port access permission bits for the calling thread
>>   for num bits starting from port address from.  If turn_on is nonzero,
>>   then permission for the specified bits is enabled; otherwise it is
>>   disabled. [...]
>>
>> The use of "bits" here is confusing/sloppy.
>>
>> ioperm is supposed to enable or disable permission to access IO ports
>> for the calling thread.  In this API, the "permission bit" (singular) is
>> really "turn_on": 0 to disable access, non-zero to enable.  However this
>> description refers also "num bits starting from port address from" and
>> "the specified bits".  That seems to suggest that IO ports somehow refer
>> to "bits" and this API controls access permission to them, which is
>> bewildering.
>>
>> Searching around I have seen that other versions of this manpage used to
>> say "bytes" instead of "bits", which is only slightly less bewildering.
>> Ports/addresses in the IO space refer neither to bits nor to bytes per
>> se, they are an abstract interface, like a syscall number/index.
>> (Architecturally, in some cases, these indices may in fact map to
>> processor registers which may in fact be portions of a contiguous
>> internal memory, so in some cases one could correctly say that the ports
>> refer to "bytes" in such memory, but this is obviously all very
>> low-level and microarchitecture-specific.  I think being aware of such
>> details actually makes this description more confusing.)
>>
>> Apparently the reason for this confusing description is that for Linux
>> ioperm is a syscall and the kernel implements this syscall using a
>> bitmap with 1 bit (permitted/denied) for each port, in a contiguous
>> sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".
>>
>> Thus "num bits starting from port address from" actually refers to the
>> bits of that bitmap: the bits [from, from+num) are set according to
>> turn_on.
>>
>> This kind of implicit reference to implementation details is wicked.

To complete the picture: this is not a mere Linux-specific
implementation detail.  At least for x86 (IA-32) it is inherited from
the processor architecture: the port permission bitmap is linked from
the structure pointed to by the "Task State Segment" (TSS) and checked
by the processor.

It is still an implicit reference to an implementation detail.  I think
not mentioning this bits-and-bitmaps business is better but
alternatively the reference should be made explicit and the kernel
bitmap should be mentioned (and for x86 perhaps also the TSS).

>> Suggested change:
>>
>>   ioperm() sets the calling thread's access permission for num ports
>>   starting from port address from.  If turn_on is nonzero, then
>>   permission for the specified ports is enabled; otherwise it is
>>   disabled. [...]
>
> Hmmm, sounds reasonable.  Do you want to send a patch?  Or should
> I write it?  (I don't mind; just asking in case you want to do it.)
>
>> PS: Oh, also, maybe the title should say "set input/output port
>> permissions" instead of "set port input/output permissions".
>
> Same here.

Sorry, I've never written *roff before 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...

Which bring up the question, why not moving to a less hairy source
format?

> BTW, the manual page also says:
>
>      This  call  is  mostly for the i386 architecture.  On many
>      other architectures it does not exist or will  always  re‐
>      turn an error.
>
> Is this still true?
>
> Another issue:
>
>      EIO    (on PowerPC) This call is not supported.
>
> Is this really true?  Where this is not supported, I expect ENOSYS.

I'll let others answer these.

> And yet another thing: should we document the parameters as being
> uintptr_t instead of unsigned long?  They are the same exact type
> always, AFAIK.  Or is there any system where they aren't?  If they are
> the same, uintptr_t will better document that they are addresses.

I suppose it depends on the architecture, but for x86 these are actually
supposed to be 16-bit integers.  I guess they are longs for generality
within syscall ABI constraints.

Re: ioperm(2): confusing terminology

[Alejandro Colomar]

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

Hi astian,

> Date: 2026-09-13 06:29:43+0000
> From: astian <astian@memeware.net>
>
> On 13 Sep 2026 00:24 +0200, Alejandro Colomar wrote:
> >> Date: 2026-09-12 22:00:57+0000
> >> From: astian <astian@memeware.net>
> >>
> >> ioperm(2) says:
> >>
> >>   int ioperm(unsigned long from, unsigned long num, int turn_on);
> >>
> >>   ioperm() sets the port access permission bits for the calling thread
> >>   for num bits starting from port address from.  If turn_on is nonzero,
> >>   then permission for the specified bits is enabled; otherwise it is
> >>   disabled. [...]
> >>
> >> The use of "bits" here is confusing/sloppy.
> >>
> >> ioperm is supposed to enable or disable permission to access IO ports
> >> for the calling thread.  In this API, the "permission bit" (singular) is
> >> really "turn_on": 0 to disable access, non-zero to enable.  However this
> >> description refers also "num bits starting from port address from" and
> >> "the specified bits".  That seems to suggest that IO ports somehow refer
> >> to "bits" and this API controls access permission to them, which is
> >> bewildering.
> >>
> >> Searching around I have seen that other versions of this manpage used to
> >> say "bytes" instead of "bits", which is only slightly less bewildering.
> >> Ports/addresses in the IO space refer neither to bits nor to bytes per
> >> se, they are an abstract interface, like a syscall number/index.
> >> (Architecturally, in some cases, these indices may in fact map to
> >> processor registers which may in fact be portions of a contiguous
> >> internal memory, so in some cases one could correctly say that the ports
> >> refer to "bytes" in such memory, but this is obviously all very
> >> low-level and microarchitecture-specific.  I think being aware of such
> >> details actually makes this description more confusing.)
> >>
> >> Apparently the reason for this confusing description is that for Linux
> >> ioperm is a syscall and the kernel implements this syscall using a
> >> bitmap with 1 bit (permitted/denied) for each port, in a contiguous
> >> sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".
> >>
> >> Thus "num bits starting from port address from" actually refers to the
> >> bits of that bitmap: the bits [from, from+num) are set according to
> >> turn_on.
> >>
> >> This kind of implicit reference to implementation details is wicked.
> 
> To complete the picture: this is not a mere Linux-specific
> implementation detail.  At least for x86 (IA-32) it is inherited from
> the processor architecture: the port permission bitmap is linked from
> the structure pointed to by the "Task State Segment" (TSS) and checked
> by the processor.
> 
> It is still an implicit reference to an implementation detail.  I think
> not mentioning this bits-and-bitmaps business is better but
> alternatively the reference should be made explicit and the kernel
> bitmap should be mentioned (and for x86 perhaps also the TSS).
> 
> >> Suggested change:
> >>
> >>   ioperm() sets the calling thread's access permission for num ports
> >>   starting from port address from.  If turn_on is nonzero, then
> >>   permission for the specified ports is enabled; otherwise it is
> >>   disabled. [...]
> >
> > Hmmm, sounds reasonable.  Do you want to send a patch?  Or should
> > I write it?  (I don't mind; just asking in case you want to do it.)
> >
> >> PS: Oh, also, maybe the title should say "set input/output port
> >> permissions" instead of "set port input/output permissions".
> >
> > Same here.
> 
> 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.

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

> > BTW, the manual page also says:
> >
> >      This  call  is  mostly for the i386 architecture.  On many
> >      other architectures it does not exist or will  always  re‐
> >      turn an error.
> >
> > Is this still true?
> >
> > Another issue:
> >
> >      EIO    (on PowerPC) This call is not supported.
> >
> > Is this really true?  Where this is not supported, I expect ENOSYS.
> 
> I'll let others answer these.
> 
> > And yet another thing: should we document the parameters as being
> > uintptr_t instead of unsigned long?  They are the same exact type
> > always, AFAIK.  Or is there any system where they aren't?  If they are
> > the same, uintptr_t will better document that they are addresses.
> 
> I suppose it depends on the architecture, but for x86 these are actually
> supposed to be 16-bit integers.  I guess they are longs for generality
> within syscall ABI constraints.

Ahh, sorry, it's a port address, not an address.


Have a lovely day!
Alex

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

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

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

[G. Branden Robinson]

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

Hi Alex,

At 2026-09-14T14:56:21+0200, Alejandro Colomar wrote:
> > Date: 2026-09-13 06:29:43+0000
> > From: astian <astian@memeware.net>
> > 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@t-8ch.de>
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@t-8ch.de>

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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH 1/2] man/man2/ioperm.2: Reword slightly for clarity

[astian]

Replace unexplained mention of "bits" (implicit reference to a
kernel-maintained permissions bitmap) with "ports".

Link: <https://lore.kernel.org/linux-man/aqfsMbQWdqq_TG_b@devuan/T/>
Signed-off-by: astian <astian@memeware.net>
---
Didn't address your questions about general arch support and the
EIO/ENOSYS on PowerPC.

 man/man2/ioperm.2 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2
index cb2c48652b5d..e4a058164f6f 100644
--- a/man/man2/ioperm.2
+++ b/man/man2/ioperm.2
@@ -16,13 +16,13 @@ .SH SYNOPSIS
 .fi
 .SH DESCRIPTION
 .BR ioperm ()
-sets the port access permission bits for the calling thread for
+sets the calling thread's access permission for
 .I num
-bits starting from port address
+ports starting from port address
 .IR from .
 If
 .I turn_on
-is nonzero, then permission for the specified bits is enabled;
+is nonzero, then permission for the specified ports is enabled;
 otherwise it is disabled.
 If
 .I turn_on
-- 
2.55.0

[PATCH 2/2] man/man2/ioperm.2: wfix

[astian]

Signed-off-by: astian <astian@memeware.net>
---
 man/man2/ioperm.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2
index e4a058164f6f..9b9aaf3840e2 100644
--- a/man/man2/ioperm.2
+++ b/man/man2/ioperm.2
@@ -4,7 +4,7 @@
 .\"
 .TH ioperm 2 (date) "Linux man-pages (unreleased)"
 .SH NAME
-ioperm \- set port input/output permissions
+ioperm \- set input/output port permissions
 .SH LIBRARY
 Standard C library
 .RI ( libc ,\~ \-lc )
-- 
2.55.0

Re: ioperm(2): confusing terminology

[astian]

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?
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).

> 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.

Re: Markdown as a "less hairy" source format for man pages

[astian]

On 15 Sep 2026 10:39 -0500, G. Branden Robinson wrote:
[...]
> 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/

Interesting recap, specially the history of man/mdoc/mandoc/groff.  Thanks.

Re: ioperm(2): confusing terminology

[Alejandro Colomar]

[-- 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 --]

Re: [PATCH 2/2] man/man2/ioperm.2: wfix

[Alejandro Colomar]

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

> Date: 2026-09-17 06:16:01+0000
> From: astian <astian@memeware.net>
>
> Signed-off-by: astian <astian@memeware.net>
> ---

Hi astian, Branden,

>  man/man2/ioperm.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2
> index e4a058164f6f..9b9aaf3840e2 100644
> --- a/man/man2/ioperm.2
> +++ b/man/man2/ioperm.2
> @@ -4,7 +4,7 @@
>  .\"
>  .TH ioperm 2 (date) "Linux man-pages (unreleased)"
>  .SH NAME
> -ioperm \- set port input/output permissions
> +ioperm \- set input/output port permissions

If I'm understanding this proposal correctly, the fix is because I/O
is an adjective of port, not of permissions.  And then 'I/O port' would
be modifying permissions.

If my interpretation is correct, then I believe I/O would be separated
from 'port' by a hyphen, not a space.

Is this the correct interpretation of the proposed fix?

BTW, should we contract to I/O?

	ioperm \- set I/O-port permissions


Have a lovely day!
Alex

>  .SH LIBRARY
>  Standard C library
>  .RI ( libc ,\~ \-lc )
> -- 
> 2.55.0
> 
> 

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

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

Re: [PATCH 1/2] man/man2/ioperm.2: Reword slightly for clarity

[Alejandro Colomar]

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

Hi astian,

> Date: 2026-09-17 06:16:00+0000
> From: astian <astian@memeware.net>
>
> Replace unexplained mention of "bits" (implicit reference to a
> kernel-maintained permissions bitmap) with "ports".
> 
> Link: <https://lore.kernel.org/linux-man/aqfsMbQWdqq_TG_b@devuan/T/>
> Signed-off-by: astian <astian@memeware.net>
> ---
> Didn't address your questions about general arch support and the
> EIO/ENOSYS on PowerPC.


Thanks!  I've applied patch 1/2.


Cheers,
Alex

> 
>  man/man2/ioperm.2 | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2
> index cb2c48652b5d..e4a058164f6f 100644
> --- a/man/man2/ioperm.2
> +++ b/man/man2/ioperm.2
> @@ -16,13 +16,13 @@ .SH SYNOPSIS
>  .fi
>  .SH DESCRIPTION
>  .BR ioperm ()
> -sets the port access permission bits for the calling thread for
> +sets the calling thread's access permission for
>  .I num
> -bits starting from port address
> +ports starting from port address
>  .IR from .
>  If
>  .I turn_on
> -is nonzero, then permission for the specified bits is enabled;
> +is nonzero, then permission for the specified ports is enabled;
>  otherwise it is disabled.
>  If
>  .I turn_on
> -- 
> 2.55.0
> 
> 

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

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

Re: ioperm(2): confusing terminology

[G. Branden Robinson]

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

Hi Alex,

At 2026-09-17T13:00:30+0200, Alejandro Colomar wrote:
> > Date: 2026-09-17 07:04:37+0000
> > From: astian <astian@memeware.net>
> > On 14 Sep 2026 14:56 +0200, Alejandro Colomar wrote:
> > [...]
> > > 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.

I wouldn't go that far.

Like TeX, *roff uses newlines, _in context_, to help it automatically
decide where sentence boundaries are.

Because the formatter, not the macro package, makes that decision, the
rules are documented not in groff_man_(7), but roff(7) and groff's
Texinfo manual.  If a person follows the "semantic newline" guidance
from man-pages(7), they can worry less often about what the rules for
automatic sentence boundary detection are.

roff(7):

Input conventions
     Since a roff formatter fills text automatically, its experienced
     users tend to avoid visual composition of text in input files: the
     esthetic appeal of the formatted output is what matters.
     Therefore, roff input should be arranged such that it is easy for
     authors and maintainers to compose and develop the document,
     understand the syntax of roff requests, macro calls, and
     preprocessor languages used, and predict the behavior of the
     formatter.  Several traditions have accrued in service of these
     goals.

     •  Follow sentence endings in the input with newlines to ease their
        recognition.  It is frequently convenient to end text lines
        after colons and semicolons as well, as these typically precede
        independent clauses.  Consider doing so after commas; they often
        occur in lists that become easy to scan when itemized by line,
        or constitute supplements to the sentence that are added,
        deleted, or updated to clarify it.  Parenthetical and quoted
        phrases are also good candidates for placement on text lines by
        themselves.

Following this practice also helps keep document revisions from
"bleeding" into unaltered adjacent sentences in a diff.  (I think it's
worth studying why the Markdown/AsciiDoc/"plain text markup" communities
have not independently re-created this practice.)

> > diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2
> > index e4a058164f6f..9b9aaf3840e2 100644
> > --- a/man/man2/ioperm.2
> > +++ b/man/man2/ioperm.2
> > @@ -4,7 +4,7 @@
> >  .\"
> >  .TH ioperm 2 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -ioperm \- set port input/output permissions
> > +ioperm \- set input/output port permissions
> 
> If I'm understanding this proposal correctly, the fix is because I/O
> is an adjective of port, not of permissions.  And then 'I/O port'
> would be modifying permissions.

The parse is not quite that rigid, but the proposed change helps steer
the reader to the correct one.

> If my interpretation is correct, then I believe I/O would be separated
> from 'port' by a hyphen, not a space.

Not the case!

One does not say:

  *I am a Linux-kernel programmer.

but rather this.

   I am a Linux kernel programmer.

Generally, in English, you can chain nouns that function as adjectives
to an almost silly degree.  I recall a favorite example from
alt.usage.english on Usenet many years ago.  Here is a noun phrase.

  sump pump backup alarm silencer switch

What kind of switch is it?  A silencer.

A silencer for what?  The alarm.

An alarm for what condition?  Backup.

Backup of what?  A pump.

What sort of pump?  A sump pump.[1]

> Is this the correct interpretation of the proposed fix?
> 
> BTW, should we contract to I/O?
> 
> 	ioperm \- set I/O-port permissions

I have no strong opinion on the ordering, but a hyphen does not belong
there.

Regards,
Branden

[1]  The word "sump" is almost never seen in isolation in general usage.
     One doesn't typically say the following.

       My basement flooded in the storm.  I'm standing in the sump and
       water is up to my ankles.

    It parses, and is grammatical and meaningful, but it would sound
    odd.  Maybe not to a plumber, though.

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

Re: ioperm(2): confusing terminology

[Alejandro Colomar]

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

Hi Branden,

> Date: 2026-09-17 07:38:45-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> Hi Alex,
> 
> At 2026-09-17T13:00:30+0200, Alejandro Colomar wrote:
> > > Date: 2026-09-17 07:04:37+0000
> > > From: astian <astian@memeware.net>
> > > On 14 Sep 2026 14:56 +0200, Alejandro Colomar wrote:
> > > [...]
> > > > 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.
> 
> I wouldn't go that far.
> 
> Like TeX, *roff uses newlines, _in context_, to help it automatically
> decide where sentence boundaries are.

Oh, yeah, I was comparing two spaces vs a newline.  If one doesn't use
two spaces, then it would indeed be a problem.

> Because the formatter, not the macro package, makes that decision, the
> rules are documented not in groff_man_(7), but roff(7) and groff's
> Texinfo manual.  If a person follows the "semantic newline" guidance
> from man-pages(7), they can worry less often about what the rules for
> automatic sentence boundary detection are.
> 
> roff(7):
> 
> Input conventions
>      Since a roff formatter fills text automatically, its experienced
>      users tend to avoid visual composition of text in input files: the
>      esthetic appeal of the formatted output is what matters.
>      Therefore, roff input should be arranged such that it is easy for
>      authors and maintainers to compose and develop the document,
>      understand the syntax of roff requests, macro calls, and
>      preprocessor languages used, and predict the behavior of the
>      formatter.  Several traditions have accrued in service of these
>      goals.
> 
>      •  Follow sentence endings in the input with newlines to ease their
>         recognition.  It is frequently convenient to end text lines
>         after colons and semicolons as well, as these typically precede
>         independent clauses.  Consider doing so after commas; they often
>         occur in lists that become easy to scan when itemized by line,
>         or constitute supplements to the sentence that are added,
>         deleted, or updated to clarify it.  Parenthetical and quoted
>         phrases are also good candidates for placement on text lines by
>         themselves.
> 
> Following this practice also helps keep document revisions from
> "bleeding" into unaltered adjacent sentences in a diff.  (I think it's
> worth studying why the Markdown/AsciiDoc/"plain text markup" communities
> have not independently re-created this practice.)
> 
> > > diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2
> > > index e4a058164f6f..9b9aaf3840e2 100644
> > > --- a/man/man2/ioperm.2
> > > +++ b/man/man2/ioperm.2
> > > @@ -4,7 +4,7 @@
> > >  .\"
> > >  .TH ioperm 2 (date) "Linux man-pages (unreleased)"
> > >  .SH NAME
> > > -ioperm \- set port input/output permissions
> > > +ioperm \- set input/output port permissions
> > 
> > If I'm understanding this proposal correctly, the fix is because I/O
> > is an adjective of port, not of permissions.  And then 'I/O port'
> > would be modifying permissions.
> 
> The parse is not quite that rigid, but the proposed change helps steer
> the reader to the correct one.

Thanks!

> > If my interpretation is correct, then I believe I/O would be separated
> > from 'port' by a hyphen, not a space.
> 
> Not the case!
> 
> One does not say:
> 
>   *I am a Linux-kernel programmer.
> 
> but rather this.
> 
>    I am a Linux kernel programmer.
> 
> Generally, in English, you can chain nouns that function as adjectives
> to an almost silly degree.  I recall a favorite example from
> alt.usage.english on Usenet many years ago.  Here is a noun phrase.
> 
>   sump pump backup alarm silencer switch

Would you mind clarifying when you should put hyphens and when not?
This is more weird than I thought.

> 
> What kind of switch is it?  A silencer.
> 
> A silencer for what?  The alarm.
> 
> An alarm for what condition?  Backup.
> 
> Backup of what?  A pump.
> 
> What sort of pump?  A sump pump.[1]
> 
> > Is this the correct interpretation of the proposed fix?
> > 
> > BTW, should we contract to I/O?
> > 
> > 	ioperm \- set I/O-port permissions
> 
> I have no strong opinion on the ordering, but a hyphen does not belong
> there.

Thanks!


Have a lovely day!
Alex

> 
> Regards,
> Branden
> 
> [1]  The word "sump" is almost never seen in isolation in general usage.
>      One doesn't typically say the following.
> 
>        My basement flooded in the storm.  I'm standing in the sump and
>        water is up to my ankles.
> 
>     It parses, and is grammatical and meaningful, but it would sound
>     odd.  Maybe not to a plumber, though.



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

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

Re: ioperm(2): confusing terminology

[astian]

On 17 Sep 2026 07:38 -0500, G. Branden Robinson wrote:
> Hi Alex,
>
> At 2026-09-17T13:00:30+0200, Alejandro Colomar wrote:
>> > Date: 2026-09-17 07:04:37+0000
>> > From: astian <astian@memeware.net>
>> > On 14 Sep 2026 14:56 +0200, Alejandro Colomar wrote:
>> > [...]
>> > > 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.
>
> I wouldn't go that far.
>
> Like TeX, *roff uses newlines, _in context_, to help it automatically
> decide where sentence boundaries are.
>
> Because the formatter, not the macro package, makes that decision, the
> rules are documented not in groff_man_(7), but roff(7) and groff's
> Texinfo manual.  If a person follows the "semantic newline" guidance
> from man-pages(7), they can worry less often about what the rules for
> automatic sentence boundary detection are.
>
> roff(7):
>
> Input conventions
>      Since a roff formatter fills text automatically, its experienced
>      users tend to avoid visual composition of text in input files: the
>      esthetic appeal of the formatted output is what matters.
>      Therefore, roff input should be arranged such that it is easy for
>      authors and maintainers to compose and develop the document,
>      understand the syntax of roff requests, macro calls, and
>      preprocessor languages used, and predict the behavior of the
>      formatter.  Several traditions have accrued in service of these
>      goals.
>
>      •  Follow sentence endings in the input with newlines to ease their
>         recognition.  It is frequently convenient to end text lines
>         after colons and semicolons as well, as these typically precede
>         independent clauses.  Consider doing so after commas; they often
>         occur in lists that become easy to scan when itemized by line,
>         or constitute supplements to the sentence that are added,
>         deleted, or updated to clarify it.  Parenthetical and quoted
>         phrases are also good candidates for placement on text lines by
>         themselves.

Thanks.

So, if I'm understanding this right, the newlines are semantic only
insofar as letting the formatter know that it should insert an
additional space if the character before the newline is a dot.  Right?

(PS: More or less:
https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html)

> Following this practice also helps keep document revisions from
> "bleeding" into unaltered adjacent sentences in a diff.  (I think it's
> worth studying why the Markdown/AsciiDoc/"plain text markup" communities
> have not independently re-created this practice.)

I don't find this surprising.  The whole point of those formats is that
they look nice enough and read smoothly enough in their source form
(insert small-letter caveats here).  If we start putting in line breaks
for the purpose of nicer diffs we soon lose the smoothness and get some
of the *roff-like hairiness ;).

Regarding the delimiting of sentences, it doesn't seem like the most
typical rendered outputs for those formats (HTML, PDF) cares about
putting the correct number of spaces after a dot ;).

And yet it turns out this exists:

  https://asciidoctor.org/docs/asciidoc-recommended-practices/

  One Sentence Per Line

  Don't wrap text at a fixed column width.  Instead, put each sentence
  on its own line, a technique called sentence per line.  This technique
  is similar to how you write and organize source code.  The result can
  be spectacular.

Kinda defeats the goal of having a nicely formatted source, but if one
were to consistently use that convention, then whatever program is used
to turn adoc into man already has the sentence problem solved at the
source, and whatever program is used to turn adoc into final
presentation format can know where a double-space sentence separator
needs to go, if so desired.

Re: ioperm(2): confusing terminology

[astian]

On 17 Sep 2026 13:00 +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.

But you read the rendered manpage, the output of running groff (and co.)
on the manpage source, right?  If you were to read manpage sources with
less in the terminal there wouldn't be reflowing either, naturally.

The point I was making is that newlines in groff_man pages did not seem
to be more semantic than those in adoc/md/rst/whatever.  Upon rendering,
paragraph lines are reflowed.  After Robinson's explanation I can see 1
bit of meaning to them (sentence delimiters).

> Is there any program for reading these in the terminal reflowed?

I guess there are although I don't personally use one (of course, that's
the point of these "light markup" formats: they mostly look like plain
text so you don't much need a renderer).  For example, there are plenty
of tools to convert these formats to HTML which can then be viewed in a
terminal browser.  Or one could use pandoc to convert them to *roff
and... haha ;).

Re: [PATCH 2/2] man/man2/ioperm.2: wfix

[astian]

On 17 Sep 2026 13:59 +0200, Alejandro Colomar wrote:
[...]
>> diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2
>> index e4a058164f6f..9b9aaf3840e2 100644
>> --- a/man/man2/ioperm.2
>> +++ b/man/man2/ioperm.2
>> @@ -4,7 +4,7 @@
>>  .\"
>>  .TH ioperm 2 (date) "Linux man-pages (unreleased)"
>>  .SH NAME
>> -ioperm \- set port input/output permissions
>> +ioperm \- set input/output port permissions
>
> If I'm understanding this proposal correctly, the fix is because I/O
> is an adjective of port, not of permissions.  And then 'I/O port' would
> be modifying permissions.
>
> If my interpretation is correct, then I believe I/O would be separated
> from 'port' by a hyphen, not a space.
>
> Is this the correct interpretation of the proposed fix?
>
> BTW, should we contract to I/O?
>
> 	ioperm \- set I/O-port permissions

Yes, grepping around I see all other pages use "I/O port", except for
proc_ioports(5) which contains "Input-Output port" in the body (and "I/O
port" in the title).

Leaving the hyphen out, per Robinson's explanation.

Re: ioperm(2): confusing terminology

[Alejandro Colomar]

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

Hi astian,

> Date: 2026-09-17 19:09:41+0000
> From: astian <astian@memeware.net>
>
[...]
> > 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.
> 
> But you read the rendered manpage, the output of running groff (and co.)
> on the manpage source, right?  If you were to read manpage sources with
> less in the terminal there wouldn't be reflowing either, naturally.
> 
> The point I was making is that newlines in groff_man pages did not seem
> to be more semantic than those in adoc/md/rst/whatever.  Upon rendering,
> paragraph lines are reflowed.  After Robinson's explanation I can see 1
> bit of meaning to them (sentence delimiters).

Yeah, if we used it exclusively as source for formatted manual pages
--just like man(7) is used now--, then I'd be fine reading the formatted
pages.

However, as you said in another email, that would delete the unique
advantage of .md/.rst, and the source would read as bad as man(7) source
(IMO, worse, because the formatting macros would be replaced by weird
 pubctuation, which is more difficult to control --as we've seen in a
 recent mail too--).

I believe kernel maintainers would run away fro .rst if they used
semantic newlines and thus had to format them to read them nicely.

> > Is there any program for reading these in the terminal reflowed?
> 
> I guess there are although I don't personally use one (of course, that's
> the point of these "light markup" formats: they mostly look like plain
> text so you don't much need a renderer).  For example, there are plenty
> of tools to convert these formats to HTML which can then be viewed in a
> terminal browser.  Or one could use pandoc to convert them to *roff
> and... haha ;).

Yeah, it ain't going to work.  Luckily, we've got man(7).  :-)


Have a lovely night!
Alex

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

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

[PATCH v2] man/man2/ioperm.2: wfix

[astian]

Signed-off-by: astian <astian@memeware.net>
---
 man/man2/ioperm.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2
index e4a058164f6f..a0d7bcb1c99b 100644
--- a/man/man2/ioperm.2
+++ b/man/man2/ioperm.2
@@ -4,7 +4,7 @@
 .\"
 .TH ioperm 2 (date) "Linux man-pages (unreleased)"
 .SH NAME
-ioperm \- set port input/output permissions
+ioperm \- set I/O port permissions
 .SH LIBRARY
 Standard C library
 .RI ( libc ,\~ \-lc )
-- 
2.55.0

[PATCH] man/man5/proc_ioports.5: wfix

[astian]

Signed-off-by: astian <astian@memeware.net>
---
 man/man5/proc_ioports.5 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man5/proc_ioports.5 b/man/man5/proc_ioports.5
index 10d03f5aae7a..54854755c0a3 100644
--- a/man/man5/proc_ioports.5
+++ b/man/man5/proc_ioports.5
@@ -10,7 +10,7 @@ .SH NAME
 .SH DESCRIPTION
 .TP
 .I /proc/ioports
-This is a list of currently registered Input-Output port regions that
+This is a list of currently registered Input/Output port regions that
 are in use.
 .SH SEE ALSO
 .BR proc (5)
-- 
2.55.0

Re: ioperm(2): confusing terminology

[G. Branden Robinson]

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

Hi astian,

At 2026-09-17T19:08:44+0000, astian wrote:
> On 17 Sep 2026 07:38 -0500, G. Branden Robinson wrote:
> > At 2026-09-17T13:00:30+0200, Alejandro Colomar wrote:
> >> > Date: 2026-09-17 07:04:37+0000
> >> > From: astian <astian@memeware.net>
> >> > On 14 Sep 2026 14:56 +0200, Alejandro Colomar wrote:
> >> > > 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.
> >
> > I wouldn't go that far.
> >
> > Like TeX, *roff uses newlines, _in context_, to help it automatically
> > decide where sentence boundaries are.
> >
> > Because the formatter, not the macro package, makes that decision, the
> > rules are documented not in groff_man_(7), but roff(7) and groff's
> > Texinfo manual.  If a person follows the "semantic newline" guidance
> > from man-pages(7), they can worry less often about what the rules for
> > automatic sentence boundary detection are.
[...]
> Thanks.
> 
> So, if I'm understanding this right, the newlines are semantic only
> insofar as letting the formatter know that it should insert an
> additional space if the character before the newline is a dot.  Right?

Insufficiently general, but yes.

s/a dot/a sentence-ending punctuation mark/

In GNU troff, the set of sentence-ending punctuation marks is
configurable.

https://www.gnu.org/software/groff/manual/groff.html.node/Characters-and-Glyphs.html

(See the `cflags` request.)

s/an additional space/supplementary inter-sentence space/

In GNU troff, the amount of supplementary inter-sentence space is
configurable, and can be zero, which is the default for non-English
languages.

https://www.gnu.org/software/groff/manual/groff.html.node/Manipulating-Filling-and-Adjustment.html

(See the `ss` request.)

Some English speakers dislike supplementary inter-sentence space.  In
GNU troff, there is a way to configure the man(7) package _locally_ to
suppress it.

groff_man_style(7)
...
Files
...
     /.../groff/site-tmac/man.local
            Put site‐local changes and customizations into this file.

                   .\" Put only one space after the end of a sentence.
                   .ss 12 0 \" See groff(7).
                   .\" Keep pages narrow even on wide terminals.
                   .if n .if \n[LL]>80n .nr LL 80n

> (PS: More or less:
> https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html)

Right.  If you see any problems in the manual, please report them!

https://savannah.gnu.org/bugs/?group=groff

*roff might be hairy, but we intend for the manual to equip you with a
nice, big paddle brush to style the hair nicely with minimal effort. ;-)

> I don't find this surprising.  The whole point of those formats is
> that they look nice enough and read smoothly enough in their source
> form (insert small-letter caveats here).  If we start putting in line
> breaks for the purpose of nicer diffs we soon lose the smoothness and
> get some of the *roff-like hairiness ;).

Right.  But you refill the paragraph after an edit to keep it looking
nice, that can lead to (semantically) spurious reports of change by
diff(1).  One _can_ use wdiff(1) or `git diff --word-diff`, though.

> Regarding the delimiting of sentences, it doesn't seem like the most
> typical rendered outputs for those formats (HTML, PDF) cares about
> putting the correct number of spaces after a dot ;).

HTML generally doesn't, because it "normalizes" whitespace between
words, except within <pre> elements.  PDF certainly _does_ care; or,
rather, by the a time PDF document is prepared from *roff (or TeX)
source, inter-sentence space has already been applied and any
alterations to the amount _will_ be visible.

Of course CSS makes HTML more complicated, potentially in this area too.

> And yet it turns out this exists:
> 
>   https://asciidoctor.org/docs/asciidoc-recommended-practices/
> 
>   One Sentence Per Line
> 
>   Don't wrap text at a fixed column width.  Instead, put each sentence
>   on its own line, a technique called sentence per line.  This
>   technique is similar to how you write and organize source code.  The
>   result can be spectacular.

Two cheers for asciidoc!

> Kinda defeats the goal of having a nicely formatted source, but if one
> were to consistently use that convention, then whatever program is
> used to turn adoc into man already has the sentence problem solved at
> the source, and whatever program is used to turn adoc into final
> presentation format can know where a double-space sentence separator
> needs to go, if so desired.

Yes!  Some documentation formats transform to man(7) straightforwardly,
and over the past few years I've worked with the maintainers of most of
the popular tools that do so, including pandoc (Haskell), docutils
(Python), asciidoctor (Ruby), and perlpod (Perl) to improve the quality
of the man(7) they produce.  Ingo Schwarze, a fellow groff developer and
the mandoc(1) maintainer, has also worked with some of these same folks.

I'd say the man(7) output quality of all these tools shows an upward
trend.

Regards,
Branden

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

Re: [PATCH] man/man5/proc_ioports.5: wfix

[G. Branden Robinson]

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

At 2026-09-17T19:58:16+0000, astian wrote:
> Signed-off-by: astian <astian@memeware.net>
> ---
>  man/man5/proc_ioports.5 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man/man5/proc_ioports.5 b/man/man5/proc_ioports.5
> index 10d03f5aae7a..54854755c0a3 100644
> --- a/man/man5/proc_ioports.5
> +++ b/man/man5/proc_ioports.5
> @@ -10,7 +10,7 @@ .SH NAME
>  .SH DESCRIPTION
>  .TP
>  .I /proc/ioports
> -This is a list of currently registered Input-Output port regions that
> +This is a list of currently registered Input/Output port regions that
>  are in use.
>  .SH SEE ALSO
>  .BR proc (5)

There is no reason for "Input" and "Output" to be capitalized here, so
I'd fix that as well.  I don't know if Alex would insist that change be
a separate commit.

Regards,
Branden

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

Re: [PATCH] man/man5/proc_ioports.5: wfix

[Alejandro Colomar]

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

Hi Branden,

> Date: 2026-09-17 18:09:17-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> At 2026-09-17T19:58:16+0000, astian wrote:
> > Signed-off-by: astian <astian@memeware.net>
> > ---
> >  man/man5/proc_ioports.5 | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/man/man5/proc_ioports.5 b/man/man5/proc_ioports.5
> > index 10d03f5aae7a..54854755c0a3 100644
> > --- a/man/man5/proc_ioports.5
> > +++ b/man/man5/proc_ioports.5
> > @@ -10,7 +10,7 @@ .SH NAME
> >  .SH DESCRIPTION
> >  .TP
> >  .I /proc/ioports
> > -This is a list of currently registered Input-Output port regions that
> > +This is a list of currently registered Input/Output port regions that
> >  are in use.
> >  .SH SEE ALSO
> >  .BR proc (5)
> 
> There is no reason for "Input" and "Output" to be capitalized here, so
> I'd fix that as well.  I don't know if Alex would insist that change be
> a separate commit.

Being part of the wording fix of how to word I/O, I think it can go in
the same commit.  :)


Have a lovely night!
Alex

> 
> Regards,
> Branden



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

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

[PATCH v2] man/man5/proc_ioports.5: wfix

[astian]

Signed-off-by: astian <astian@memeware.net>
---
 man/man5/proc_ioports.5 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man5/proc_ioports.5 b/man/man5/proc_ioports.5
index 10d03f5aae7a..6729a7b98054 100644
--- a/man/man5/proc_ioports.5
+++ b/man/man5/proc_ioports.5
@@ -10,7 +10,7 @@ .SH NAME
 .SH DESCRIPTION
 .TP
 .I /proc/ioports
-This is a list of currently registered Input-Output port regions that
+This is a list of currently registered input/output port regions that
 are in use.
 .SH SEE ALSO
 .BR proc (5)
-- 
2.55.0