Re: New optional Eshell module: em-elecslash

[Sean Whitton <spwhitton@spwhitton.name>]

Hello,

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?

>> +*** 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.

>> +;;;###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.

-- 
Sean Whitton