Re: New optional Eshell module: em-elecslash

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: emacs-devel@gnu.org, philipk@posteo.net
> Date: Sat, 16 Apr 2022 13:04:26 -0700
> 
> On Sat 16 Apr 2022 at 10:18PM +03, Eli Zaretskii wrote:
> 
> >> +If the @code{eshell-elecslash} module has been added to
> >> +@code{eshell-modules-list}, and @code{default-directory} is remote,
> >> +then when you type the first forward slash of an argument to a Lisp
> >> +function, the Tramp prefix will be filled in for you.  A second
> >> +forward slash can be used to undo the insertion, for when you really
> >> +do want to pass a local absolute path, such as when you want to copy a
> >> +remote file to the local machine.  And when typing arguments to
> >> +external commands, the Tramp prefix is not filled in.  The result is
> >> +that you don't have to think about inserting the Tramp prefix and can
> >> +just type absolute paths in the same way for both types of command.
> >> +The Tramp prefix is additionally filled in when you type @code{~/}.
> >
> > You use passive tense a lot (here and elsewhere), which in many cases
> > makes the text longer, more complicated, and harder to understand.
> > Please try rephrasing without using passive tense so much.
> 
> I'm happy to try to make it clearer, but in the U.K. we don't have this
> idea that the passive voice is worse than the active -- I didn't learn
> the distinction until after finishing a humanities degree -- so could
> you be more specific, please?

IME, use of passive tense is not the "disease", it's a symptom.  The
"disease" is overly complicated sentences that make the text hard to
understand.  Using passive tense is a good indicator that the
structure of the text is sub-optimal and needs to be rethought.
Trying to use active tense as much as possible in many cases leads to
such rethinking and makes the text more clear.

For example, here's how I'd rephrase the above paragraph:

  To help you type file-name arguments to remote commands, add the
  @code{eshell-elecslash} module to @code{eshell-modules-list}.  Then
  typing the first @kbd{/} character of a command-line argument will
  automatically insert the Tramp prefix if the
  @code{default-directory} is remote.  If this is not what you want
  (e.g., you want to type a local absolute file name instead), type
  another @kbd{/} to undo this automatic prefix insertion.  Typing
  @kbd{~/} also inserts the Tramp prefix.  By contrast, typing
  arguments to external commands, which always run locally, doesn't
  insert the prefix.  The result is that in most cases you get the
  Tramp prefix inserted automatically only when you should reasonably
  expect it.

Do you see how using the active tense makes the text more clear?
Another thing to remember for writing clear documentation is not to
put the important parts too far near the end of a sentence; the above
rewording fixed a few instances of that in your original text.

> >> +*** New optional Eshell module to help avoid mistakes when supplying
> >
> > The first line of a NEWS entry is a heading, so it should be a
> > complete sentence, to facilitate reading the outlines.
> 
> Hmm interesting.  I found continuing sentences from the outline heading
> to the next line strange, but noticed that many NEWS entries did it, so
> thought it was how outline-mode is meant to be used.

No, the NEWS entries where the first line is not a complete sentence
ending in a period are in error and should be fixed.  (We usually fix
that close to starting a pretest, if not earlier.)

> >> +;;;###autoload
> >> +(progn
> >> +(defgroup eshell-elecslash nil
> >> +  "When `default-directory' is remote thanks to Eshell's TRAMP
> >
> > the first line of a doc string should be a complete sentence, because
> > some Help commands only show that single line.
> >
> >> +(defun eshell-electric-forward-slash ()
> >> +  "Electric insertion of TRAMP part of `default-directory' in
> >> +remote Eshells.  Added to `post-self-insert-hook' when the
> >
> > Likewise.
> 
> I'll try to come up with something.  This rule can be very difficult to
> satisfy given line length restrictions.

We all bump into that from time to time.  Some techniques for dealing
with the difficulties:

  . omit some less important parts, like "the" etc.
  . rearrange the text to make it shorter (for example, say "buffer
    text" instead of "the text of the buffer")
  . omit less important details from the first sentence, and describe
    them in the following parts of the doc string

Thanks.