Re: Draft pthread_spin_lock(3) manual page

[Zack Weinberg <zackw at panix dot com>]

On Thu, Oct 19, 2017 at 1:46 PM, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> On 18 October 2017 at 17:07, Carlos O'Donell <carlos@redhat.com> 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.

zw