Re: [PATCH v2] mctp.7: Add man page for Linux MCTP support

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

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

Hi, Alex!

At 2021-11-12T19:45:16+0100, Alejandro Colomar (man-pages) wrote:
> man-pages(7) recommends breaking long lines at clause boundaries
> (commas, semicolons, and so on), but somethimes clauses (if you don't
> know the difference between phrases and clauses, which you don't need
> to, basically clauses are made up of phrases)

Slightly more formally, a clause is a grammatical unit containing a
subject and a predicate: "allocation fails" is a near-minimal example.
I wouldn't be surprised if caveats exist for "non-standard" speech, but
man pages are written in a fairly formal register so the rule should
apply reliably.  A moment's attention to clause boundaries can help one
clarify or recast complex constructions to aid readability and accuracy.

> "the source and destination EIDs" is a single phrase, so it's a bit
> weird to break the line in the middle of it.  I avoid breaking
> phrases, which makes reading the source code a bit more difficult.
> Hopefully, it will also make diffs easier to read in the future.

My only gripe about list-related phrase breaks, and it's a minor one, is
that in English grammar they nearly always require a conjunction ("and",
"or") somewhere, and no matter where I place it, it feels wrong, because
it's neither an item of the list I'm itemizing, nor part of an item.

I mention this because I suspect there is a point of diminishing returns
in our prescriptive advice, because English is an unwieldy beast that
was not formally designed as any respectable system would be.

Forget killing baby Hitler--if I ever get a time machine, I'm going to
go back and teach Shakespeare Haskell.

> Also, we prevent some crazy programmers from relying on that padding
> byte being actually padding and not something else, even if it "must"
> be zero.  I've seen too much crazy stuff; programmers relying on
> undefined behavior just because "we don't plan to move from C++17 to
> C++20, so this is safe".

+1.  One can almost see them producing a cowboy hat from an
extradimensional space in their cubicle.  Strap in--the UB bronco is
gonna start bucking.

Regards,
Branden

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