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
