On Mon, Sep 06, 2021 at 04:12:19PM +0200, Marc Espie wrote: > On Sat, Sep 04, 2021 at 09:28:14PM +0200, Ingo Schwarze wrote: > > Hi Wilfried, > > > > [email protected] wrote on Sat, Sep 04, 2021 at 08:20:59PM +0200: > > > > > Synopsis: Maverick word in the sort(1) manpage > > > Category: documentation > > [...] > > > There is a superfluous word in the description of the --random-source > > > option of the sort(1) manpage. The second sentence contains > > > "will use produce" which probably should just be "will produce". > > > > Committed, thanks for reporting. > > > > While there, i also deleted the word "will". Manuals usually do not > > need future tense, except in unusual situations. > > > > Yours, > > Ingo > > > > > > The paragraph now reads: > > > > --random-source=filename > > For random sort, the contents of filename are used as the source > > of the `seed' data for the hash function. Two invocations of > > random sort with the same seed data produce the same result if > > the input is also identical. By default, the arc4random_buf(3) > > function is used instead. > > > > > Hum... I've looked around at my own manpages. Actually, careful use of > tenses tend to make documentation feel slightly less "dry" in a lot of > cases, thus actually making it MORE readable in the end. > > I'm not sure removing that specific "will" is a good idea. It's not future > tense. It's (whatever it's called in English ?) that modal that says that > this WILL predictably happen (instead of SHOULD or MAY) thus adding > welcome emphasis instead of just saying things dryly like you do. >
hi. there is an element of preference in these choices, that's true. but i am confident many people (native and non-native) find it easier to read without modals, and with fewer words. i totaly back ingo's change in this bit of text. that's not to lessen your preference, i just think it's a good rule of thumb for us to keep text simple and clear. modals really wreck people's heads. jmc
