On 10/19/2017 11:06 AM, Zack Weinberg 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. I will endeavour to adopt such a distinction in my future writing. I appreciate that feedback :-) -- Cheers, Carlos. -- 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
