Re: ioperm(2): confusing terminology

["astian" <astian@memeware.net>]

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.