Re: ioperm(2): confusing terminology

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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