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: Pedro Alves <palves at redhat dot com>
- Cc: Zack Weinberg <zackw at panix dot com>, "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: Fri, 20 Oct 2017 16:55:55 +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> <2d177560-7725-066a-7fff-bac06b9d153a@redhat.com>
- Reply-to: mtk dot manpages at gmail dot com
Hello Pedro,
On 20 October 2017 at 12:12, Pedro Alves <palves@redhat.com> wrote:
> On 10/19/2017 07:06 PM, Zack Weinberg wrote:
>> On Thu, Oct 19, 2017 at 1:46 PM, Michael Kerrisk (man-pages)
>
>> 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.
>
> Technical writing guidelines usually suggest staying in the
> present tense, and avoid future tense though, because with "will"
> it's not clear whether you're describing how things behave as
> currently implemented or whether you're talking about how things
> will be implemented in the future.
>
> I.e.:
> ... foo fails and sets errno if/when ...
> instead of:
> ... foo will fail and set errno if/when ...
>
> Here's an example:
>
>
> http://www.datacenterjournal.com/technically-write-advice-technical-writing/
>
> And here's Sandra applying that same rule throughout GCC's manual:
>
> [[doc] extend.texi copy-editing, 1/N (verb tenses)]
> https://gcc.gnu.org/ml/gcc-patches/2012-10/msg02688.html
>
> (I recalled that whole series of Sandra's as I found
> it quite instructive back then.)
Fair enough, I've fixed "will fail" in a number of pages!
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/