Optional Eshell modules -- to emacs.git or ELPA?

Optional Eshell modules -- to emacs.git or ELPA?

[Sean Whitton]

Hello,

I have a useful Eshell thing that I would like to make more broadly
available but which should definitely not be turned on by default.  The
final implementation will be as an Eshell module which makes an addition
to post-self-insert-hook.

I notice that there aren't any Eshell modules in GNU ELPA.  So, should I
propose this for inclusion in lisp/eshell/em-*.el, or as something new
in GNU ELPA?

One advantage of the former option is that the extension could be
documented in the Eshell manual, whereas otherwise all there can be is
docstrings and the package description, which is markedly less
discoverable.

Thanks!

-- 
Sean Whitton

Re: Optional Eshell modules -- to emacs.git or ELPA?

[Philip Kaludercic]

Sean Whitton <spwhitton@spwhitton.name> writes:

> Hello,
>
> I have a useful Eshell thing that I would like to make more broadly
> available but which should definitely not be turned on by default.  The
> final implementation will be as an Eshell module which makes an addition
> to post-self-insert-hook.

Could you give any details on what the feature is? 

> I notice that there aren't any Eshell modules in GNU ELPA.  So, should I
> propose this for inclusion in lisp/eshell/em-*.el, or as something new
> in GNU ELPA?
>
> One advantage of the former option is that the extension could be
> documented in the Eshell manual, whereas otherwise all there can be is
> docstrings and the package description, which is markedly less
> discoverable.

Without any further information, I would appreciate it if more features
would be added directly to eshell, but adding it to ELPA first so that
it can "ripen" isn't a bad approach either.

> Thanks!

-- 
	Philip Kaludercic

New optional Eshell module: em-elecslash

[Sean Whitton]

[-- Attachment #1: Type: text/plain, Size: 519 bytes --]

Hello,

On Sat 29 Jan 2022 at 11:51AM GMT, Philip Kaludercic wrote:

> Sean Whitton <spwhitton@spwhitton.name> writes:
>
>> Hello,
>>
>> I have a useful Eshell thing that I would like to make more broadly
>> available but which should definitely not be turned on by default.  The
>> final implementation will be as an Eshell module which makes an addition
>> to post-self-insert-hook.
>
> Could you give any details on what the feature is?

Here is my new module, which I'd like to install on master.

-- 
Sean Whitton

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-electric-forward-slash-Eshell-module.patch --]
[-- Type: text/x-patch, Size: 9006 bytes --]

From c915c51cd32b6354b951f10fb4d2d3666b3480d2 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Sat, 16 Apr 2022 08:23:14 -0700
Subject: [PATCH] New electric forward slash Eshell module

* lisp/eshell/em-elecslash.el: New module.
* etc/NEWS:
* doc/misc/eshell.texi (Electric forward slash): Document the module.
---
 doc/misc/eshell.texi        |  59 +++++++++++++++++++
 etc/NEWS                    |   8 +++
 lisp/eshell/em-elecslash.el | 113 ++++++++++++++++++++++++++++++++++++
 3 files changed, 180 insertions(+)
 create mode 100644 lisp/eshell/em-elecslash.el

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 372e4c3ffb..61db05c4e3 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -1241,6 +1241,7 @@ Extension modules
 * Key rebinding::
 * Smart scrolling::
 * Terminal emulation::
+* Electric forward slash::
 @end menu
 
 @node Writing a module
@@ -1273,6 +1274,64 @@ Terminal emulation
 
 This section is not yet written.
 
+@node Electric forward slash
+@section Electric forward slash
+
+This optional module tries to help with passing absolute paths to
+commands when @code{default-directory} is remote.  When using Eshell's
+Tramp support, it is easy to accidentally refer to a local path when
+you meant a remote path.  The problem arises because absolute paths
+passed to Lisp functions must have Tramp's @code{/method:host:}
+prefix, but absolute paths passed to external commands must not have
+this prefix.  Typically, one does not think about whether a command is
+a Lisp function or an external command while inputting command line
+arguments.  For example, suppose you execute
+
+@example
+ cd /ssh:root@@example.com:
+ find /etc -name "*gnu*"
+@end example
+
+@noindent and in reviewing the output of the command, you identify a
+file @code{/etc/gnugnu} that should be moved somewhere else.  So you
+type
+
+@example
+ mv /etc/gnugnu /tmp
+@end example
+
+@noindent But since @code{mv} refers to the local Lisp function
+@code{eshell/mv}, not a remote shell command, to say this is to
+request that the local file @code{/etc/gnugnu} be moved into the local
+@code{/tmp} directory.  What you should have typed is
+
+@example
+ mv /ssh:root@@example.com:/etc/gnugnu /ssh:root@@example.com:/tmp
+@end example
+
+@noindent but it is easy to forget to do that, and it takes much
+longer to type.
+
+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{~/}.
+
+The code that determines whether or not the Tramp prefix should be
+inserted uses simple heuristics.  A limitation of the current
+implementation is that only the status as Lisp function or external
+program of the command at the very beginning of input can be
+considered.  Thus when chaining commands with the operators @code{&&},
+@code{||}, @code{|} and @code{;}, the electric forward slash is active
+only within the first command.
+
 @node Bugs and ideas
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
diff --git a/etc/NEWS b/etc/NEWS
index 79c27da549..696c3ff844 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1165,6 +1165,14 @@ support for pipelines which will move a lot of data.  See section
 "Running Shell Pipelines Natively" in the Eshell manual, node
 "(eshell) Input/Output".
 
++++
+*** New optional Eshell module to help avoid mistakes when supplying
+absolute paths to commands in remote Eshells.  When
+'default-directory' is remote thanks to Eshell's TRAMP integration,
+and you are supplying absolute paths to commands, it is easy to
+accidentally refer to a local path instead of a remote path.  See
+"Electric forward slash" in the Eshell manual.
+
 ** Miscellaneous
 
 +++
diff --git a/lisp/eshell/em-elecslash.el b/lisp/eshell/em-elecslash.el
new file mode 100644
index 0000000000..e2585fe2a5
--- /dev/null
+++ b/lisp/eshell/em-elecslash.el
@@ -0,0 +1,113 @@
+;;; em-elecslash.el --- electric forward slashes  -*- lexical-binding:t -*-
+
+;; Copyright (C) 2022 Free Software Foundation, Inc.
+
+;; Author: Sean Whitton <spwhitton@spwhitton.name>
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Electric forward slash in remote Eshells.
+
+;;; Code:
+
+(require 'tramp)
+(require 'thingatpt)
+(require 'esh-cmd)
+(require 'esh-ext)
+(require 'esh-mode)
+
+;; This makes us an option when customizing `eshell-modules-list'.
+;;;###autoload
+(progn
+(defgroup eshell-elecslash nil
+  "When `default-directory' is remote thanks to Eshell's TRAMP
+integration, and you are supplying absolute paths to commands, it
+is easy to accidentally refer to a local path when you meant a
+remote path.  This happens because absolute paths passed to Lisp
+functions must be prefixed with /method:host: but absolute paths
+passed to external commands must not have this prefix; it is easy
+to invoke a built-in command without the prefix by mistake.  This
+module tries to resolve this difficulty by filling in the
+/method:host: electrically just when it's needed."
+  :tag "Electric forward slash"
+  :group 'eshell-module))
+
+;;; Functions:
+
+(defun eshell-elecslash-initialize () ;Called from `eshell-mode' via intern-soft!
+  "Initialize electric forward slash support."
+  (add-hook 'post-self-insert-hook
+            #'eshell-electric-forward-slash nil t))
+
+(defun eshell-electric-forward-slash ()
+  "Electric insertion of TRAMP part of `default-directory' in
+remote Eshells.  Added to `post-self-insert-hook' when the
+Eshell elecslash module is initialized.
+
+Typing a forward slash in a remote Eshell performs the
+completion.  Typing a second forward slash undoes it."
+  (when (eq ?/ (char-before))
+    (delete-char -1)
+    (let ((tilde-before (eq ?~ (char-before)))
+          (command (save-excursion
+                     (eshell-bol)
+                     (skip-syntax-forward " ")
+                     (thing-at-point 'sexp))))
+      (if (and (file-remote-p default-directory)
+               ;; We can't formally parse the input.  But if there is
+               ;; one of these operators behind us, then looking at
+               ;; the first command would not be sensible.  So be
+               ;; conservative: don't insert the Tramp prefix if there
+               ;; are any of these operators behind us.
+               (not (looking-back (regexp-opt '("&&" "|" ";"))
+                                  eshell-last-output-end))
+	       (or (= (point) eshell-last-output-end)
+		   (and tilde-before
+                        (= (1- (point)) eshell-last-output-end))
+		   (and (or tilde-before
+                            (eq ?\s (char-syntax (char-before))))
+		        (or (eshell-find-alias-function command)
+			    (and (fboundp (intern-soft command))
+			         (or eshell-prefer-lisp-functions
+				     (not (eshell-search-path command))))))))
+	  (let ((map (make-sparse-keymap))
+	        (start (if tilde-before (1- (point)) (point)))
+                (localname
+                 (tramp-file-name-localname
+                  (tramp-dissect-file-name default-directory))))
+	    (when tilde-before (delete-char -1))
+	    (insert
+             (substring default-directory 0
+                        (string-search localname default-directory)))
+	    (unless tilde-before (insert "/"))
+	    ;; Typing a second slash undoes the insertion, for when
+	    ;; you really do want to type a local absolute path.
+	    (define-key map "/" (lambda ()
+				  (interactive)
+				  (delete-region start (point))
+				  (insert (if tilde-before "~/" "/"))))
+	    (set-transient-map map))
+        (insert "/")))))
+
+(provide 'em-elecslash)
+
+;; Local Variables:
+;; generated-autoload-file: "esh-groups.el"
+;; End:
+
+;;; esh-elecslash.el ends here
-- 
2.30.2

Re: New optional Eshell module: em-elecslash

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Date: Sat, 16 Apr 2022 11:57:55 -0700
> 
> Here is my new module, which I'd like to install on master.

Thanks, a few comments below regarding the documentation parts.

> >From c915c51cd32b6354b951f10fb4d2d3666b3480d2 Mon Sep 17 00:00:00 2001
> From: Sean Whitton <spwhitton@spwhitton.name>
> Date: Sat, 16 Apr 2022 08:23:14 -0700
> Subject: [PATCH] New electric forward slash Eshell module
> 
> * lisp/eshell/em-elecslash.el: New module.

We use "New file."

> +This optional module tries to help with passing absolute paths to

GNU Coding Standards frown on using "path" for anything but PATH-style
directory lists.  In other cases, we use "file name" instead.  Please
correct this terminology here and elsewhere in the patch.

> +passed to Lisp functions must have Tramp's @code{/method:host:}
                                              ^^^^^^^^^^^^^^^^^^^^
File names should have the @file markup.

> +@noindent and in reviewing the output of the command, you identify a
> +file @code{/etc/gnugnu} that should be moved somewhere else.  So you
        ^^^^^^^^^^^^^^^^^^
Likewise (and elsewhere in the patch).

> +@noindent But since @code{mv} refers to the local Lisp function
                       ^^^^^^^^^
"mv" is a command, so it should use the @command markup.

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

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

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

Re: New optional Eshell module: em-elecslash

[Sean Whitton]

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

Re: New optional Eshell module: em-elecslash

[Sean Whitton]

Hello,

On Sat 16 Apr 2022 at 10:18PM +03, Eli Zaretskii wrote:

>> +passed to Lisp functions must have Tramp's @code{/method:host:}
>                                               ^^^^^^^^^^^^^^^^^^^^
> File names should have the @file markup.
>
>> +@noindent and in reviewing the output of the command, you identify a
>> +file @code{/etc/gnugnu} that should be moved somewhere else.  So you
>         ^^^^^^^^^^^^^^^^^^
> Likewise (and elsewhere in the patch).
>
>> +@noindent But since @code{mv} refers to the local Lisp function
>                        ^^^^^^^^^
> "mv" is a command, so it should use the @command markup.

I'm sorry I didn't figure these out by myself.  I've now found the
relevant section of the texinfo manual so should be able to get them
right myself from now on.

-- 
Sean Whitton

RE: [External] : Re: New optional Eshell module: em-elecslash

[Drew Adams]

(A reply for the list, not necessarily for you.)

> 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

https://en.wikipedia.org/wiki/Talk%3AEnglish_passive_voice#Differences_between_US_and_British_English
___

Guidance about the active/passive choice is generally
more subtle/involved than just one being considered
systematically "worse than" the other.

See https://en.wikipedia.org/wiki/English_passive_voice#Style_advice,
and that whole page, generally.  For example:

 "Use of the passive in English varies with writing
  style and field. It is generally much less used
  than the active voice but is more prevalent in
  scientific writing than in other prose.

  Contemporary style guides discourage excessive
  use of the passive but appropriate use is
  generally accepted, for instance where the
  patient is the topic, the agent is unimportant
  (and therefore omitted), or the agent is to be 
  highlighted (and therefore placed toward the end)."

And see https://www.grammarly.com/blog/passive-voice/.
___

One study of the use of passive voice in scientific writing:

https://jcom.sissa.it/sites/default/files/documents/JCOM_1301_2014_A03.pdf
___

IMO it's more about avoiding a systematic or
habitual overuse of the passive voice, which is
not unknown to writing that's more formalistic in
style. ;-)

There's no formula that applies well absolutely.
Neither active nor passive voice is systematically
"worse than" the other.

But if you have a doubt in some case, read both
and see which you think is clearer.  If still in
doubt, it probably means you see no special
reason for the passive voice there - use active.

Re: New optional Eshell module: em-elecslash

[Stefan Monnier]

> +(defun eshell-elecslash-initialize () ;Called from `eshell-mode' via intern-soft!

Thank you for this comment!! :-)


        Stefan

Re: New optional Eshell module: em-elecslash

[Sean Whitton]

Hello,

On Sat 16 Apr 2022 at 06:58pm -04, Stefan Monnier wrote:

>> +(defun eshell-elecslash-initialize () ;Called from `eshell-mode' via intern-soft!
>
> Thank you for this comment!! :-)

Actually just copy and pasted from other Eshell modules, most of them
have it :)

-- 
Sean Whitton

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.

Re: New optional Eshell module: em-elecslash

[Jim Porter]

On 4/16/2022 11:57 AM, Sean Whitton wrote:
> Here is my new module, which I'd like to install on master.

Cool, this looks like it should be really helpful for making Lisp 
commands and external commands more consistent. This seems similar to an 
entry in Eshell's "Bug and Ideas" section in the manual too:

   @item Make @kbd{/} electric

   So that it automatically expands and corrects pathnames.  Or make
   pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
   @samp{/usr/include/std@key{TAB}}.

The entry is pretty brief, so I'm not sure exactly how it would be 
expected to work in all cases, but it might be some food for thought. If 
nothing else, it'd probably be worth removing (or updating?) that entry.

- Jim

RE: [External] : Re: New optional Eshell module: em-elecslash

[Drew Adams]

> IME, use of passive tense is not the "disease", it's a symptom.

Yes.  Or rather, an indicator/hint that something
can perhaps be improved.

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

+1.

> 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

+1.

Another convention that can be limiting is to
present function parameters in order.

That too can require rewording.  In particular,
it can sometimes mean not mentioning parameters
in the first (one-line) sentence.

The first line is quite important.  It can be
used in contexts as a short description of the
object (e.g. function).  It needs to be short
and yet give a reasonable overall description. 

Re: New optional Eshell module: em-elecslash

[Sean Whitton]

Hello,

On Sat 16 Apr 2022 at 11:24pm -07, Jim Porter wrote:

> On 4/16/2022 11:57 AM, Sean Whitton wrote:
>> Here is my new module, which I'd like to install on master.
>
> Cool, this looks like it should be really helpful for making Lisp
> commands and external commands more consistent. This seems similar to an
> entry in Eshell's "Bug and Ideas" section in the manual too:
>
>    @item Make @kbd{/} electric
>
>    So that it automatically expands and corrects pathnames.  Or make
>    pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
>    @samp{/usr/include/std@key{TAB}}.
>
> The entry is pretty brief, so I'm not sure exactly how it would be
> expected to work in all cases, but it might be some food for thought. If
> nothing else, it'd probably be worth removing (or updating?) that entry.

Thanks, I didn't see this section.

I think that's actually referring to something else -- just general
pathname completion, expansion and correction, not TRAMP prefixes.  I'll
edit it appropriately though.

-- 
Sean Whitton

Re: New optional Eshell module: em-elecslash

[Sean Whitton]

Hello,

On Sun 17 Apr 2022 at 09:20am +03, Eli Zaretskii wrote:

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

Thanks for this, I will read it carefully and revise my patch.

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

Good to know.

> 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

Right, I'll try to be more willing to say less in that first sentence.

-- 
Sean Whitton

Re: New optional Eshell module: em-elecslash

[Sean Whitton]

[-- Attachment #1: Type: text/plain, Size: 174 bytes --]

Hello,

On Tue 19 Apr 2022 at 09:52AM -07, Sean Whitton wrote:

> Thanks for this, I will read it carefully and revise my patch.

Here is my revised patch.

-- 
Sean Whitton

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-New-electric-forward-slash-Eshell-module.patch --]
[-- Type: text/x-patch, Size: 9956 bytes --]

From d85c81577fde949014c2796b44ec8fad18ff7072 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Sat, 16 Apr 2022 08:23:14 -0700
Subject: [PATCH v2] New electric forward slash Eshell module

* lisp/eshell/em-elecslash.el: New file.
* etc/NEWS:
* doc/misc/eshell.texi (Electric forward slash): Document the module.
(Make / electric): Retitle to "Make / more electric" and update.
---
 doc/misc/eshell.texi        |  63 ++++++++++++++++++-
 etc/NEWS                    |  10 +++
 lisp/eshell/em-elecslash.el | 120 ++++++++++++++++++++++++++++++++++++
 3 files changed, 190 insertions(+), 3 deletions(-)
 create mode 100644 lisp/eshell/em-elecslash.el

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 411e696069..68196563b2 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -1560,6 +1560,7 @@ Extension modules
 * Key rebinding::
 * Smart scrolling::
 * Terminal emulation::
+* Electric forward slash::
 @end menu
 
 @node Writing a module
@@ -1592,6 +1593,61 @@ Terminal emulation
 
 This section is not yet written.
 
+@node Electric forward slash
+@section Electric forward slash
+
+To help with supplying absolute file name arguments to remote
+commands, you can add the @code{eshell-elecslash} module to
+@code{eshell-modules-list}.  Then, typing @kbd{/} as the first
+character of a command line argument will automatically insert the
+Tramp prefix @file{/method:host:}.  If this is not what you want
+(e.g.@: because you want to refer to a local file) you can type
+another @kbd{/} to undo the automatic insertion.  Typing @kbd{~/} also
+inserts the Tramp prefix.  The automatic insertion applies only when
+@code{default-directory} is remote and the command is a Lisp function.
+In particular, typing arguments to external commands doesn't insert
+the prefix.
+
+The result is that in most cases of supplying absolute file name
+arguments to commands you should see the Tramp prefix inserted
+automatically only when that's what you'd reasonably expect.  This
+frees you from having to keep track of whether commands are Lisp
+functions or external when typing command line arguments.  For
+example, suppose you execute
+
+@example
+ cd /ssh:root@@example.com:
+ find /etc -name "*gnu*"
+@end example
+
+@noindent and in reviewing the output of the command, you identify a
+file @file{/etc/gnugnu} that should be moved somewhere else.  So you
+type
+
+@example
+ mv /etc/gnugnu /tmp
+@end example
+
+@noindent But since @command{mv} refers to the local Lisp function
+@code{eshell/mv}, not a remote shell command, to say this is to
+request that the local file @file{/etc/gnugnu} be moved into the local
+@file{/tmp} directory.  After you add @code{eshell-elecslash} to
+@code{eshell-modules-list}, then when you type the above @command{mv}
+invocation you will get the following input, which is what you
+intended:
+
+@example
+ mv /ssh:root@@example.com:/etc/gnugnu /ssh:root@@example.com:/tmp
+@end example
+
+The code that determines whether or not the Tramp prefix should be
+inserted uses simple heuristics.  A limitation of the current
+implementation is that only the status as Lisp function or external
+program of the command at the very beginning of input can be
+considered.  Thus when chaining commands with the operators @code{&&},
+@code{||}, @code{|} and @code{;}, the electric forward slash is active
+only within the first command.
+
 @node Bugs and ideas
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
@@ -1995,10 +2051,11 @@ Bugs and ideas
 @item The first keypress after @kbd{M-x watson} triggers
 @code{eshell-send-input}
 
-@item Make @kbd{/} electric
+@item Make @kbd{/} more electric
 
-So that it automatically expands and corrects pathnames.  Or make
-pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
+So that it automatically expands and corrects pathnames, beyond what
+the @code{em-elecslash} module is able to do.  Or make pathname
+completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
 @samp{/usr/include/std@key{TAB}}.
 
 @item Write the @command{pushd} stack to disk along with @code{last-dir-ring}
diff --git a/etc/NEWS b/etc/NEWS
index 3442ebd81b..c8ff155850 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1245,6 +1245,16 @@ support for pipelines which will move a lot of data.  See section
 "Running Shell Pipelines Natively" in the Eshell manual, node
 "(eshell) Input/Output".
 
++++
+*** New module to help supplying absolute file names to remote commands.
+After enabling the new module, typing a forward slash as the first
+character of a command line argument will automatically insert the
+Tramp prefix.  The automatic insertion applies only when
+'default-directory' is remote and the command is a Lisp function.
+This frees you from having to keep track of whether commands are Lisp
+function or external when supplying absolute file name arguments.  See
+"Electric forward slash" in the Eshell manual.
+
 ** Miscellaneous
 
 +++
diff --git a/lisp/eshell/em-elecslash.el b/lisp/eshell/em-elecslash.el
new file mode 100644
index 0000000000..091acb9a86
--- /dev/null
+++ b/lisp/eshell/em-elecslash.el
@@ -0,0 +1,120 @@
+;;; em-elecslash.el --- electric forward slashes  -*- lexical-binding:t -*-
+
+;; Copyright (C) 2022 Free Software Foundation, Inc.
+
+;; Author: Sean Whitton <spwhitton@spwhitton.name>
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Electric forward slash in remote Eshells.
+
+;;; Code:
+
+(require 'tramp)
+(require 'thingatpt)
+(require 'esh-cmd)
+(require 'esh-ext)
+(require 'esh-mode)
+
+;; This makes us an option when customizing `eshell-modules-list'.
+;;;###autoload
+(progn
+(defgroup eshell-elecslash nil
+  "Electric forward slash in remote Eshells.
+
+This module helps with supplying absolute file name arguments to
+remote commands.  After enabling it, typing a forward slash as
+the first character of a command line argument will automatically
+insert the Tramp prefix, /method:host:.  The automatic insertion
+applies only when `default-directory' is remote and the command
+is a Lisp function.
+
+The result is that in most cases of supplying absolute file name
+arguments to commands you should see the Tramp prefix inserted
+automatically only when that's what you'd reasonably expect.
+This frees you from having to keep track of whether commands are
+Lisp functions or external when typing command line arguments."
+  :tag "Electric forward slash"
+  :group 'eshell-module))
+
+;;; Functions:
+
+(defun eshell-elecslash-initialize () ;Called from `eshell-mode' via intern-soft!
+  "Initialize remote Eshell electric forward slash support."
+  (add-hook 'post-self-insert-hook
+            #'eshell-electric-forward-slash nil t))
+
+(defun eshell-electric-forward-slash ()
+  "Implementation of electric forward slash in remote Eshells.
+
+Initializing the `eshell-elecslash' module adds this function to
+`post-self-insert-hook'.  Typing / or ~/ as the first character
+of a command line argument automatically inserts the Tramp prefix
+in the case that `default-directory' is remote and the command is
+a Lisp function.  Typing a second forward slash undoes the
+insertion."
+  (when (eq ?/ (char-before))
+    (delete-char -1)
+    (let ((tilde-before (eq ?~ (char-before)))
+          (command (save-excursion
+                     (eshell-bol)
+                     (skip-syntax-forward " ")
+                     (thing-at-point 'sexp))))
+      (if (and (file-remote-p default-directory)
+               ;; We can't formally parse the input.  But if there is
+               ;; one of these operators behind us, then looking at
+               ;; the first command would not be sensible.  So be
+               ;; conservative: don't insert the Tramp prefix if there
+               ;; are any of these operators behind us.
+               (not (looking-back (regexp-opt '("&&" "|" ";"))
+                                  eshell-last-output-end))
+	       (or (= (point) eshell-last-output-end)
+		   (and tilde-before
+                        (= (1- (point)) eshell-last-output-end))
+		   (and (or tilde-before
+                            (eq ?\s (char-syntax (char-before))))
+		        (or (eshell-find-alias-function command)
+			    (and (fboundp (intern-soft command))
+			         (or eshell-prefer-lisp-functions
+				     (not (eshell-search-path command))))))))
+	  (let ((map (make-sparse-keymap))
+	        (start (if tilde-before (1- (point)) (point)))
+                (localname
+                 (tramp-file-name-localname
+                  (tramp-dissect-file-name default-directory))))
+	    (when tilde-before (delete-char -1))
+	    (insert
+             (substring default-directory 0
+                        (string-search localname default-directory)))
+	    (unless tilde-before (insert "/"))
+	    ;; Typing a second slash undoes the insertion, for when
+	    ;; you really do want to type a local absolute file name.
+	    (define-key map "/" (lambda ()
+				  (interactive)
+				  (delete-region start (point))
+				  (insert (if tilde-before "~/" "/"))))
+	    (set-transient-map map))
+        (insert "/")))))
+
+(provide 'em-elecslash)
+
+;; Local Variables:
+;; generated-autoload-file: "esh-groups.el"
+;; End:
+
+;;; esh-elecslash.el ends here
-- 
2.30.2

Re: New optional Eshell module: em-elecslash

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: philipk@posteo.net
> Date: Tue, 19 Apr 2022 17:36:53 -0700
> 
> Here is my revised patch.

Much better, thanks.  A few comments below.

> +To help with supplying absolute file name arguments to remote
> +commands, you can add the @code{eshell-elecslash} module to
> +@code{eshell-modules-list}.  Then, typing @kbd{/} as the first
> +character of a command line argument will automatically insert the
> +Tramp prefix @file{/method:host:}.  If this is not what you want
> +(e.g.@: because you want to refer to a local file) you can type
                                                     ^
A comma is missing there.

> +                                  A limitation of the current
> +implementation is that only the status as Lisp function or external
> +program of the command at the very beginning of input can be
> +considered.

This sentence is unnecessarily hard to grasp.  Note the passive tense
and the fact that the important part is at the end, which are usually
clear signs of sub-optimal wording.  Please try to reword it, e.g. by
swapping the first and the second parts.

> -@item Make @kbd{/} electric
> +@item Make @kbd{/} more electric
>  
> -So that it automatically expands and corrects pathnames.  Or make
> -pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
> +So that it automatically expands and corrects pathnames, beyond what
> +the @code{em-elecslash} module is able to do.  Or make pathname
> +completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to

This last paragraph needs a @noindent and should start with a
lower-case letter, because it is a continuation of the previous
sentence.  Also, it uses "pathname(s)" where it should use "file
name(s)".

> +*** New module to help supplying absolute file names to remote commands.
> +After enabling the new module, typing a forward slash as the first
> +character of a command line argument will automatically insert the
> +Tramp prefix.  The automatic insertion applies only when
> +'default-directory' is remote and the command is a Lisp function.
> +This frees you from having to keep track of whether commands are Lisp
> +function or external when supplying absolute file name arguments.  See
> +"Electric forward slash" in the Eshell manual.

This NEWS entry should name the module, I think.

Re: New optional Eshell module: em-elecslash

[Sean Whitton]

[-- Attachment #1: Type: text/plain, Size: 2034 bytes --]

Hello,

On Wed 20 Apr 2022 at 09:19AM +03, Eli Zaretskii wrote:

>> +To help with supplying absolute file name arguments to remote
>> +commands, you can add the @code{eshell-elecslash} module to
>> +@code{eshell-modules-list}.  Then, typing @kbd{/} as the first
>> +character of a command line argument will automatically insert the
>> +Tramp prefix @file{/method:host:}.  If this is not what you want
>> +(e.g.@: because you want to refer to a local file) you can type
>                                                      ^
> A comma is missing there.

Thanks.  This is an American English thing I find it hard to remember.

>> -@item Make @kbd{/} electric
>> +@item Make @kbd{/} more electric
>>
>> -So that it automatically expands and corrects pathnames.  Or make
>> -pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
>> +So that it automatically expands and corrects pathnames, beyond what
>> +the @code{em-elecslash} module is able to do.  Or make pathname
>> +completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
>
> This last paragraph needs a @noindent and should start with a
> lower-case letter, because it is a continuation of the previous
> sentence.  Also, it uses "pathname(s)" where it should use "file
> name(s)".

I was thinking that I would touch that paragraph only to the extent I
had to to update it, but why not fix those things, indeed.

>> +*** New module to help supplying absolute file names to remote commands.
>> +After enabling the new module, typing a forward slash as the first
>> +character of a command line argument will automatically insert the
>> +Tramp prefix.  The automatic insertion applies only when
>> +'default-directory' is remote and the command is a Lisp function.
>> +This frees you from having to keep track of whether commands are Lisp
>> +function or external when supplying absolute file name arguments.  See
>> +"Electric forward slash" in the Eshell manual.
>
> This NEWS entry should name the module, I think.

Good point.

-- 
Sean Whitton

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v3-0001-New-electric-forward-slash-Eshell-module.patch --]
[-- Type: text/x-patch, Size: 10059 bytes --]

From 92f0033b8dde194fbc71b945db77712ddad240ee Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Sat, 16 Apr 2022 08:23:14 -0700
Subject: [PATCH v3] New electric forward slash Eshell module

* lisp/eshell/em-elecslash.el: New file.
* etc/NEWS:
* doc/misc/eshell.texi (Electric forward slash): Document the module.
(Make / electric): Retitle to "Make / more electric", update, add
"@noindent", and standardize terminology.
---
 doc/misc/eshell.texi        |  65 +++++++++++++++++--
 etc/NEWS                    |  10 +++
 lisp/eshell/em-elecslash.el | 120 ++++++++++++++++++++++++++++++++++++
 3 files changed, 191 insertions(+), 4 deletions(-)
 create mode 100644 lisp/eshell/em-elecslash.el

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 411e696069..e539206166 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -1560,6 +1560,7 @@ Extension modules
 * Key rebinding::
 * Smart scrolling::
 * Terminal emulation::
+* Electric forward slash::
 @end menu
 
 @node Writing a module
@@ -1592,6 +1593,61 @@ Terminal emulation
 
 This section is not yet written.
 
+@node Electric forward slash
+@section Electric forward slash
+
+To help with supplying absolute file name arguments to remote
+commands, you can add the @code{eshell-elecslash} module to
+@code{eshell-modules-list}.  Then, typing @kbd{/} as the first
+character of a command line argument will automatically insert the
+Tramp prefix @file{/method:host:}.  If this is not what you want
+(e.g.@: because you want to refer to a local file), you can type
+another @kbd{/} to undo the automatic insertion.  Typing @kbd{~/} also
+inserts the Tramp prefix.  The automatic insertion applies only when
+@code{default-directory} is remote and the command is a Lisp function.
+In particular, typing arguments to external commands doesn't insert
+the prefix.
+
+The result is that in most cases of supplying absolute file name
+arguments to commands you should see the Tramp prefix inserted
+automatically only when that's what you'd reasonably expect.  This
+frees you from having to keep track of whether commands are Lisp
+functions or external when typing command line arguments.  For
+example, suppose you execute
+
+@example
+ cd /ssh:root@@example.com:
+ find /etc -name "*gnu*"
+@end example
+
+@noindent and in reviewing the output of the command, you identify a
+file @file{/etc/gnugnu} that should be moved somewhere else.  So you
+type
+
+@example
+ mv /etc/gnugnu /tmp
+@end example
+
+@noindent But since @command{mv} refers to the local Lisp function
+@code{eshell/mv}, not a remote shell command, to say this is to
+request that the local file @file{/etc/gnugnu} be moved into the local
+@file{/tmp} directory.  After you add @code{eshell-elecslash} to
+@code{eshell-modules-list}, then when you type the above @command{mv}
+invocation you will get the following input, which is what you
+intended:
+
+@example
+ mv /ssh:root@@example.com:/etc/gnugnu /ssh:root@@example.com:/tmp
+@end example
+
+The code that determines whether or not the Tramp prefix should be
+inserted uses simple heuristics.  A limitation of the current
+implementation is that it inspects whether only the command at the
+very beginning of input is a Lisp function or external program.  Thus
+when chaining commands with the operators @code{&&}, @code{||},
+@code{|} and @code{;}, the electric forward slash is active only
+within the first command.
+
 @node Bugs and ideas
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
@@ -1995,11 +2051,12 @@ Bugs and ideas
 @item The first keypress after @kbd{M-x watson} triggers
 @code{eshell-send-input}
 
-@item Make @kbd{/} electric
+@item Make @kbd{/} more electric
 
-So that it automatically expands and corrects pathnames.  Or make
-pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
-@samp{/usr/include/std@key{TAB}}.
+@noindent so that it automatically expands and corrects file names,
+beyond what the @code{em-elecslash} module is able to do.  Or make
+file name completion for Pcomplete auto-expand
+@samp{/u/i/std@key{TAB}} to @samp{/usr/include/std@key{TAB}}.
 
 @item Write the @command{pushd} stack to disk along with @code{last-dir-ring}
 
diff --git a/etc/NEWS b/etc/NEWS
index 3442ebd81b..21d27a856b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1245,6 +1245,16 @@ support for pipelines which will move a lot of data.  See section
 "Running Shell Pipelines Natively" in the Eshell manual, node
 "(eshell) Input/Output".
 
++++
+*** New module to help supplying absolute file names to remote commands.
+After enabling the new 'eshell-elecslash' module, typing a forward
+slash as the first character of a command line argument will
+automatically insert the Tramp prefix.  The automatic insertion
+applies only when 'default-directory' is remote and the command is a
+Lisp function.  This frees you from having to keep track of whether
+commands are Lisp function or external when supplying absolute file
+name arguments.  See "Electric forward slash" in the Eshell manual.
+
 ** Miscellaneous
 
 +++
diff --git a/lisp/eshell/em-elecslash.el b/lisp/eshell/em-elecslash.el
new file mode 100644
index 0000000000..091acb9a86
--- /dev/null
+++ b/lisp/eshell/em-elecslash.el
@@ -0,0 +1,120 @@
+;;; em-elecslash.el --- electric forward slashes  -*- lexical-binding:t -*-
+
+;; Copyright (C) 2022 Free Software Foundation, Inc.
+
+;; Author: Sean Whitton <spwhitton@spwhitton.name>
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Electric forward slash in remote Eshells.
+
+;;; Code:
+
+(require 'tramp)
+(require 'thingatpt)
+(require 'esh-cmd)
+(require 'esh-ext)
+(require 'esh-mode)
+
+;; This makes us an option when customizing `eshell-modules-list'.
+;;;###autoload
+(progn
+(defgroup eshell-elecslash nil
+  "Electric forward slash in remote Eshells.
+
+This module helps with supplying absolute file name arguments to
+remote commands.  After enabling it, typing a forward slash as
+the first character of a command line argument will automatically
+insert the Tramp prefix, /method:host:.  The automatic insertion
+applies only when `default-directory' is remote and the command
+is a Lisp function.
+
+The result is that in most cases of supplying absolute file name
+arguments to commands you should see the Tramp prefix inserted
+automatically only when that's what you'd reasonably expect.
+This frees you from having to keep track of whether commands are
+Lisp functions or external when typing command line arguments."
+  :tag "Electric forward slash"
+  :group 'eshell-module))
+
+;;; Functions:
+
+(defun eshell-elecslash-initialize () ;Called from `eshell-mode' via intern-soft!
+  "Initialize remote Eshell electric forward slash support."
+  (add-hook 'post-self-insert-hook
+            #'eshell-electric-forward-slash nil t))
+
+(defun eshell-electric-forward-slash ()
+  "Implementation of electric forward slash in remote Eshells.
+
+Initializing the `eshell-elecslash' module adds this function to
+`post-self-insert-hook'.  Typing / or ~/ as the first character
+of a command line argument automatically inserts the Tramp prefix
+in the case that `default-directory' is remote and the command is
+a Lisp function.  Typing a second forward slash undoes the
+insertion."
+  (when (eq ?/ (char-before))
+    (delete-char -1)
+    (let ((tilde-before (eq ?~ (char-before)))
+          (command (save-excursion
+                     (eshell-bol)
+                     (skip-syntax-forward " ")
+                     (thing-at-point 'sexp))))
+      (if (and (file-remote-p default-directory)
+               ;; We can't formally parse the input.  But if there is
+               ;; one of these operators behind us, then looking at
+               ;; the first command would not be sensible.  So be
+               ;; conservative: don't insert the Tramp prefix if there
+               ;; are any of these operators behind us.
+               (not (looking-back (regexp-opt '("&&" "|" ";"))
+                                  eshell-last-output-end))
+	       (or (= (point) eshell-last-output-end)
+		   (and tilde-before
+                        (= (1- (point)) eshell-last-output-end))
+		   (and (or tilde-before
+                            (eq ?\s (char-syntax (char-before))))
+		        (or (eshell-find-alias-function command)
+			    (and (fboundp (intern-soft command))
+			         (or eshell-prefer-lisp-functions
+				     (not (eshell-search-path command))))))))
+	  (let ((map (make-sparse-keymap))
+	        (start (if tilde-before (1- (point)) (point)))
+                (localname
+                 (tramp-file-name-localname
+                  (tramp-dissect-file-name default-directory))))
+	    (when tilde-before (delete-char -1))
+	    (insert
+             (substring default-directory 0
+                        (string-search localname default-directory)))
+	    (unless tilde-before (insert "/"))
+	    ;; Typing a second slash undoes the insertion, for when
+	    ;; you really do want to type a local absolute file name.
+	    (define-key map "/" (lambda ()
+				  (interactive)
+				  (delete-region start (point))
+				  (insert (if tilde-before "~/" "/"))))
+	    (set-transient-map map))
+        (insert "/")))))
+
+(provide 'em-elecslash)
+
+;; Local Variables:
+;; generated-autoload-file: "esh-groups.el"
+;; End:
+
+;;; esh-elecslash.el ends here
-- 
2.30.2

Re: New optional Eshell module: em-elecslash

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: emacs-devel@gnu.org, philipk@posteo.net
> Date: Wed, 20 Apr 2022 13:14:04 -0700
> 
> > A comma is missing there.
> 
> Thanks.  This is an American English thing I find it hard to remember.
> 
> >> -@item Make @kbd{/} electric
> >> +@item Make @kbd{/} more electric
> >>
> >> -So that it automatically expands and corrects pathnames.  Or make
> >> -pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
> >> +So that it automatically expands and corrects pathnames, beyond what
> >> +the @code{em-elecslash} module is able to do.  Or make pathname
> >> +completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to
> >
> > This last paragraph needs a @noindent and should start with a
> > lower-case letter, because it is a continuation of the previous
> > sentence.  Also, it uses "pathname(s)" where it should use "file
> > name(s)".
> 
> I was thinking that I would touch that paragraph only to the extent I
> had to to update it, but why not fix those things, indeed.
> 
> >> +*** New module to help supplying absolute file names to remote commands.
> >> +After enabling the new module, typing a forward slash as the first
> >> +character of a command line argument will automatically insert the
> >> +Tramp prefix.  The automatic insertion applies only when
> >> +'default-directory' is remote and the command is a Lisp function.
> >> +This frees you from having to keep track of whether commands are Lisp
> >> +function or external when supplying absolute file name arguments.  See
> >> +"Electric forward slash" in the Eshell manual.
> >
> > This NEWS entry should name the module, I think.
> 
> Good point.

Thanks, the patch LGTM.