At 2021-07-30T02:14:56+0200, Eugene Syromyatnikov wrote: > On Fri, Jul 30, 2021 at 12:35 AM G. Branden Robinson > 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. That's fair. I don't expect all my reformist suggestions to be adopted. :) > > > +However, in order to preserve backward compatibility, the routine > > > > s/routine/function/ ? > > I followed syscalls(2) naming convention here. Also a fair point. Yes, I see that usage is fairly thick in the "NOTES" section. > > 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. True--I wasn't aware of that before. But by that token, you could say that the "note that" phrase is now redundant for a different reason. ;-) It's not a big deal--I mention it because I've found it a useful prompt to myself when writing: when I want to say, "note that", what am I _really_ trying to say? "Pay attention here"? "Danger, Will Robinson!"? Usually I wind up either dropping "note that" or recasting the sentence to more clearly motivate why a statement is worthy of special attention. Regards, Branden
Attachment:
signature.asc
Description: PGP signature
