Hello Zack, On 19 October 2017 at 20:06, Zack Weinberg <zackw@xxxxxxxxx> wrote: > On Thu, Oct 19, 2017 at 1:46 PM, Michael Kerrisk (man-pages) > <mtk.manpages@xxxxxxxxx> wrote: >> On 18 October 2017 at 17:07, Carlos O'Donell <carlos@xxxxxxxxxx> wrote: >> >>>> pthread_spin_trylock() can fail with the following errors: >>>> >>>> EBUSY The spin lock is currently locked by another thread. >>> >>> I always find the 'can fail' wording a bit wishy-washy for my tastes >>> and prefer: 'shall fail', along with a statement that defines the >>> conditions for failure. I say this only because English is not as >>> precise as I'd like so using 'shall' instead of 'can' makes this >>> failure mode clearer, indicating to the reader that it will happen >>> (here it's a bit obvious from the semantics of the function, since >>> otherwise trylock would be useless). >> >> Changed to "shall fail" (but this is not the only page with that problem :-} ). > > I meant to reply earlier. This is a pet English grammar peeve of > mine: "shall" is a _directive_. Specifications use it because they > are directing the implementors to make things happen, but in > documentation aimed at people _using_ an interface, the appropriate > word is "will". The function _will_ fail and set errno under the > following conditions yada yada. That's what it does. You, the reader > of this manpage, do not have to do anything to make that happen. Yes, it's true. s/shall/will/. Done. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
