This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: Draft pthread_spin_lock(3) manual page
- From: "Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>
- To: Zack Weinberg <zackw at panix dot com>
- Cc: "Carlos O'Donell" <carlos at redhat dot com>, linux-man <linux-man at vger dot kernel dot org>, "libc-alpha at sourceware dot org" <libc-alpha at sourceware dot org>, Thomas Gleixner <tglx at linutronix dot de>, Peter Zijlstra <peterz at infradead dot org>, Ingo Molnar <mingo at kernel dot org>
- Date: Thu, 19 Oct 2017 21:27:20 +0200
- Subject: Re: Draft pthread_spin_lock(3) manual page
- Authentication-results: sourceware.org; auth=none
- References: <CAKgNAkigca=v31L0hDMR7PdNEHgS8mhB6KWR0qZew-jhYD8dwg@mail.gmail.com> <fe6d752e-60a1-c8de-698c-ddd19d432110@redhat.com> <CAKgNAkjTZZWQpAwgg-m7Z-W=CQfS39CU5F+rr1B3msgf4SEBww@mail.gmail.com> <CAKCAbMjZK6BwJeh37TyJkwogD05GdvQod6LkJmvy4R+ad1w7fw@mail.gmail.com>
- Reply-to: mtk dot manpages at gmail dot com
Hello Zack,
On 19 October 2017 at 20:06, Zack Weinberg <zackw@panix.com> 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.
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/