Hi Branden, > Date: 2026-09-17 07:38:45-0500 > From: "G. Branden Robinson" > > Hi Alex, > > At 2026-09-17T13:00:30+0200, Alejandro Colomar wrote: > > > Date: 2026-09-17 07:04:37+0000 > > > From: astian > > > 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. --