Draft pthread_spin_lock(3) manual page

[Carlos O'Donell]

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@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.

I will endeavour to adopt such a distinction in my future writing.
I appreciate that feedback :-)

-- 
Cheers,
Carlos.