Future tense considered ungood?

[Karl O. Pinc]

Hi,

I hope this is helpful, and not just bikeshedding.

As a rule, I don't like future tense in docs.  E.g. in doc/rluser.texi:

@item enable-bracketed-paste
@vindex enable-bracketed-paste
When set to @samp{On}, Readline will configure the terminal in a way
that will enable it to insert each paste into the editing buffer as a
single string of characters, instead of treating each character as if
it had been read from the keyboard.  This can prevent pasted characters
from being interpreted as editing commands.  The default is @samp{On}.


Thing is, when enable-bracketed-paste is `on', Readline _does_ configure
the terminal and inserts pastes..., etc.  It does not do it eventually,
it does it right then.

And eliminating future tense makes for fewer words and clearer
sentences.  As does switching from passive to active voice.  Compare:

  When set to On, Readline will configure the terminal in a way that
  will enable it to insert each paste into the editing buffer...

with

  When set to On, Readline configures the terminal in a way that enables
  it to insert each paste into the editing buffer...

/rant


While I'm thinking about this, even better/shorter is:

   When set to On, Readline configures the terminal so it can insert
   each paste into the editing buffer...

But this is a bit ambiguous as to what's doing the inserting, so:

   When set to On, Readline enables terminal features and thereafter
   inserts each paste into the editing buffer...

Perhaps it is necessary to elaborate on what terminal features are used,
so the user knows what to do to if the terminal winds up in a strange
state.  So then write:

   When set to On, Readline enables bracketed-paste mode in the terminal
   and thereafter inserts each paste into the editing buffer...

This is about as long as the original, but I believe it presents more
information and is more clear.


And finally, in the spirit of eliminating words, I'd change:

   This can prevent...

to

   This prevents...

Regards,

Karl <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein