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

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:

quoted

On 2/14/23 20:54, Mathieu Desnoyers wrote:

quoted

+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 :)

quoted

quoted

+.RB ( "struct rseq" )

We format types in italics, so this should be '.RI'.

+1

quoted

quoted

+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).

quoted

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).

quoted

quoted

+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.

quoted

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.

quoted

quoted

+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

quoted

quoted

+.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.

quoted

quoted

+Its value should always be confirmed by reading the cpu_id field before

cpu_id should be formatted (.I).

+1

quoted

quoted

+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.)

quoted

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