Re: Draft pthread_spin_lock(3) manual page

[Pedro Alves <palves at redhat dot com>]

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

Thanks,
Pedro Alves