Hello Pedro, On 20 October 2017 at 12:12, Pedro Alves <palves@xxxxxxxxxx> 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/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
