Re: ioperm(2): confusing terminology

[Alejandro Colomar <alx@kernel.org>]

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