Re: [PATCH 1/1] rseq.2: New man page for the rseq(2) API

[Alejandro Colomar]

Hi Branden,

On 2/15/23 02:20, G. Branden Robinson wrote:
> [CC list violently trimmed; for those who remain, this is mostly man
> page style issues]

Ironically, you trimmed linux-man@  :D

> 
> At 2023-02-14T23:29:37+0100, Alejandro Colomar wrote:
>> On 2/14/23 20:54, Mathieu Desnoyers wrote:
>>> +per-thread data structure shared between kernel and user-space.
>>
>> This last 'user-space' is not adjectivated, so it should go without
>> a hyphen, according to common English rules.
> 
> +1
> 
> Also I like your coinage.  "Adjectivated yeast" is reflexive and
> tautological!

:D

I didn't even think about it.  "adjetivado" is an actual word in Spanish,
so I just guessed that it would exist in English.  But yes, it's a nice
word for this case :)

> 
>>> +.RB ( "struct rseq" )
>>
>> We format types in italics, so this should be '.RI'.
> 
> +1
> 
>>> +Only one
>>> +.BR rseq ()
>>> +ABI can be registered per thread, so user-space libraries and
>>> +applications must follow a user-space ABI defining how to share this
>>> +resource.
>>
>> Please use semantic newlines.  See man-pages(7):
>>
>>    Use semantic newlines
>>        In  the source of a manual page, new sentences should be started on new
>>        lines, long sentences should be split into lines at clause breaks (com‐
>>        mas, semicolons, colons, and so on), and long clauses should  be  split
>>        at  phrase  boundaries.   This convention, sometimes known as "semantic
>>        newlines", makes it easier to see the effect of  patches,  which  often
>>        operate at the level of individual sentences, clauses, or phrases.
> 
> I think I've said this before, but, strictly, commas in particular can
> separate things that are not clauses.  Clauses have subjects and
> predicates.
> 
> Might it be better to say simply:
> 
>   Start each sentence on a new line.  Split long sentences where
>   punctuated by commas, semicolons, and colons.
> 
> With this there is not even any need to discuss "phrase boundaries".

I still disagree with that;
punctuation is not enough
(see below).

> 
>> In the above lines, that would mean breaking after the comma,
>> and not leaving resource in a line of its own.
> 
> The latter is inevitably going to happen from time to time simply due to
> sentence length and structure and the line length used by one's text
> editor.

That's if you only break at sentence and clause boundaries,
and then adjust at 80 columns...

>  I don't think an "orphan word" (what typographers call this) is
> symptomatic of anything in *roff source when filling is enabled.

but if you also break at phrase boundaries
(when/where convenient)
you'll find that you get rid of those "orphan words",
because you'll never have to adjust at 80 columns
(or rather,
you'll try to find a way to break it
that also happens to be a phrase boundary
because breaking at phrase boundaries is _better_
than breaking at random points which may happen to be
in the middle of a compound noun).

> 
>>> +The ABI defining how to share this resource between applications and
>>> +libraries is defined by the C library.
>>> +Allocation of the per-thread
>>> +.BR rseq ()
>>> +ABI and its registration to the kernel is handled by glibc since version
>>> +2.35.
>>> +.PP
>>> +The
>>> +.BR rseq ()
>>> +ABI per-thread data structure contains a
>>> +.I rseq_cs
>>> +field which points to the currently executing critical section.
>>
>> currently-executing should probably use a hyphen
>> (if I understood the line correctly).
> 
> This is not the case, according to some style authorities.  Dave Kemper
> convinced me of this on the groff list.
> 
> Here is one resource.
> 
> https://www.editorgroup.com/blog/to-hyphenate-or-not-to-hyphenate/

Hmm, interesting.  I didn't think about it, but it makes sense
to not hyphenate here.

> 
>> See an interesting discussion in the groff@ mailing list:
>> <https://lists.gnu.org/archive/html/groff/2022-10/msg00015.html>
> 
> That's not _squarely_ on point, as none of "block", "device", or "based"
> is an adverb.  "Currently" is.

You're right.

> 
>>> +For each thread, a single rseq critical section can run at any given
>>> +point.
>>> +Each critical section need to be implemented in assembly.
>>
>> needs?
> 
> +1
> 
>>> +.TP
>>> +.B Structure alignment
>>
>> Let's remove the bold here.  It's not necessary for marking a constant
>> or something that needs bold.  And the indentation is already making
>> it stand out, so bold is a bit too much aggressive to the reader.
> 
> I agree; if it wouldn't be styled in running text, it doesn't need
> styling as a paragraph tag; it already stands out by dint of its
> placement as a tag.
> 
>>> +Its value should always be confirmed by reading the cpu_id field before
>>
>> cpu_id should be formatted (.I).
> 
> +1
> 
>>> +user-space performs any side-effect
>>> +(e.g. storing to memory).
>>> +.IP
>>> +This field is always guaranteed to hold a valid CPU number in the range
>>> +[ 0 ..  nr_possible_cpus - 1 ].
>>
>> Please use interval notation:
>> 	[0, nr_possible_cpus)
>> or
>> 	[0, nr_possible_cpus - 1]
>> whichever looks better to you.
>>
>> We did some consistency fix recently:
>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=147a60d792a5db8f3cb93ea16eefb73e16c1fb91>
>>
>> Also, do we have a more standard way of saying nr_possible_cpus?
>> Should we say nproc?
> 
> Apropos of a separate discussion we had weeks ago, Alex, I remembered
> where I saw "nitems" as a variable name.
> 
> _UNIX Programming_, second edition, by Kernighan and Ritchie!
> 
> https://wolfram.schneider.org/bsd/7thEdManVol2/uprog/uprog.pdf
> 
> Plop _that_ down on the desk of the person who claimed it was a stupid
> variable name that no good programmer would ever use.

ROFL.  I'm bookmarking this!

> 
> (I think appeals to authority are just fine as long as one is being
> mean.  ;-P

Indeed ;-P

>  And as regards variable naming, Kernighan is a _legitimate_
> authority: a subject matter expert with multiple well-regarded books on
> coding style to his credit.  Ritchie's strengths were more esoteric,
> enough that he put up specimens of his own youthful hubris as, I think,
> an effort to discourage his many admirers from copying his mistakes as
> slavishly as his successes[1]--apart from their humor value.)
> 
>> Branden, IIRC, this seems to be the reason why I didn't want .RS for
>> indenting code examples.  It doesn't fit nicely right after TP.
>>
>> Why is there a blank line?  I'm not even sure that's reasonable.  Is
>> it a (minor) bug in man(7)?  (FWIW, mandoc(1) is consistent with
>> groff(1).)
> 
> Right, I'll take this up in the separate thread you started for it on
> the groff list.

Sure.

> 
> Regards,
> Branden
> 
> [1] https://www.bell-labs.com/usr/dmr/www/odd.html
> 
>     See particularly "Comments I do feel guilty about".

Yep, that page is always funny :)

Cheers,

Alex


-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

Attachment: OpenPGP_signature
Description: OpenPGP digital signature