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