On Fri, Jul 30, 2021 at 12:35 AM G. Branden Robinson
<g.branden.robinson@xxxxxxxxx> wrote:
>
> Hi, Eugene!
>
> I thought I'd offer some style suggestions since Alex hasn't yet.
Thanks, it seems like my sense of English grammar was absent on the
day the patch was conceived more than usual.
> At 2021-07-29T17:44:01+0200, Eugene Syromyatnikov wrote:
> > +The corresponding infinity value constant is provided in
> > +.I <linux/resource.h>
> > +as
> > +.BR RLIM64_INFINITY.
> > +.PP
> > +Original Linux implementation used signed types for limits; that was changed
>
> Grammatically, you need an article at the beginning of this sentence.
> More broadly, however, what constitutes "*the* original Linux
> implementation" may not be well-defined and is not as relevant to the
> discussion as Linux kernels that were widely deployed. The earliest
> conveivable Linux attested, what Torvalds produced on his 80386 in 1991
> ("Freax") is less important than Linux 2.4.
>
> So I would recast and use semantic newlines [see man-pages(7)]:
>
> Linux 2.4 and earlier used signed types for limits;
> that was changed
>
> Alex will surely direct you to the semantic newline advice in
> man-pages(7).
>
> Use semantic newlines
> In the source of a manual page, new sentences should be started
> on new lines, and long sentences should split into lines at
> clause breaks (commas, semicolons, colons, and so on). 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 or sentence clauses.
>
> I won't point out every instance where a semantic newline is preferred.
>
> > +(along with the value of the
> > +.B RLIM_INFINITY
> > +constant)
>
> I see there is some precedent in the Linux man-pages to call a
> preprocessor symbol that is replaced with a C language literal a
> "constant". I would not employ this usage myself, since C has the
> "const" type qualifier that suggests, and is is widely interpreted, as
> "constant". I think it would be helpful if we referred to as "constant"
> only C objects bearing such a declaration. Does anyone think this would
> be a worthwhile shift in usage? (The most important virtue that
> constants in the sense I'm using them have over preprocessor symbols is
> that the former survive the translation process into executable format,
> and (if not optimized out) will appear in a symbol table, which means a
> debugger can know about them.)
I'd stick with the current "constant" usage for brevity: system
headers do not tend to employ const symbols, especially
kernel-provided ones, for reasons, so "constant" meaning is more or
less clear in the section 2 with that regard, albeit not totally
technically sound with respect to the C language.
> > +.\" http://repo.or.cz/davej-history.git/blobdiff/129f8758d8c41e0378ace0b6e2f56bbb8a1ec694..15305d2e69c3a838bacd78962c07077d2821f255:/include/linux/resource.h
> > +during 2.4 development cycle, as it wasn't compatible
>
> s/during/& the/
>
> > +with Single UNIX Specification.
>
> s/with/& the/
>
> > +However, in order to preserve backward compatibility, the routine
>
> s/routine/function/ ?
I followed syscalls(2) naming convention here.
>
> > +.IR sys_old_getrlimit
> > +has been implemented under
>
> s/has been/was/
> s/under/using the/
>
> > +.B __NR_getrlimit
> > +syscall slot, with infinity checks being performed against hard-coded 0x7fffffff
>
> s/hard-coded/a literal/
>
> > +value, and the routine
>
> s/the routine//
> (it will be clear from context that this is another function)
>
> > +.I sys_getrlimit
> > +has been exposed under a new name,
>
> s/has been/was/
> s/exposed/made available/
>
> > +.BR ugetrlimit ().
> > +Note that most newer architectures don't have the latter, with
>
> s/Note that most/Most/
>
> I call this a "Kemper notectomy", after my colleague in groff
> development, Dave Kemper, who has pointed out that we tend to massively
> overuse the phrase "note that" in software documentation. We write for
> impatient readers. Everything we say in a manual should be worthy of
> note; if it is not, it should be deleted or moved to a place in the text
> reserved for supplemental commentary (a footnote; a (sub)section entitled
> "Background", "History", or "Notes"; or similar).
This is literally the "Notes" section, though.
> > +.BR getrlimit ()
> > +providing proper implementation.
>
> What's "proper" about it? That it's unsigned, or that it's conforming?
> Say so. Again, an article is needed.
>
> s/proper/a conforming/
>
> > +Also worth noting that several architectures decided not to change
>
> I'd condense this.
>
> s/Also worth noting that/However,
> /
>
> > +.B RLIM_INFINITY
> > +value: 32-bit mips and sparc (but not 64-bit variants, that switched
>
> s/mips/MIPS/
>
> The Linux man-pages are mostly consistent about this casing[1], and it
> is normative[2].
>
> s/sparc/SPARC/
>
> The Linux man-pages are mostly consistent about this casing[3], and it
> is normative[4].
>
> > +to the new value of (~0UL)) retained the old 0x7fffffff value,
> > +and alpha retained 0x7ffffffffffffffful.
>
> s/alpha/Alpha/
>
> You can probably guess what I'm going to say. ;-)
>
> > +.\" ...along with a request to call when one runs into it:
> > +.\" https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/alpha/include/uapi/asm/resource.h#n15
> > .SH BUGS
> > In older Linux kernels, the
> > .B SIGXCPU
>
> Thank you for your patience with my comments. I hope they've been
> helpful.
They indeed are.
> Regards,
> Branden
>
> [1] vdso(7) may be an exception.
> [2] https://booksite.elsevier.com/9780124077263/downloads/historial%20perspectives/section_4.16.pdf
> [3] clone(2), syscall(2), and exec(3) may be exceptions.
> [4] https://sparc.org/timeline/
--
Eugene Syromyatnikov
mailto:evgsyr@xxxxxxxxx
xmpp:esyr@jabber.{ru|org}
