; Improve wording of last Tramp commit, suggested by Robert Pluim

2 files changed, 26 insertions, 19 deletions

diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 1440521df56..ba0545c38de 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -805,8 +805,8 @@ behavior.
 
 Works like @option{ssh} but without the extra authentication prompts.
 @option{sshx} uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh}
-to open a connection with a ``standard'' login shell.  It supports to
-change the remote login shell @command{/bin/sh}.
+to open a connection with a ``standard'' login shell.  It supports
+changing the remote login shell @command{/bin/sh}.
 
 @strong{Note} that @option{sshx} does not bypass authentication
 questions.  For example, if the host key of the remote host is not
@@ -842,8 +842,7 @@ This is another method from the Kerberos suite.  It behaves like @option{su}.
 
 @option{plink} method is for MS Windows users with the PuTTY
 implementation of SSH@.  It uses @samp{plink -ssh} to log in to the
-remote host.  It supports to change the remote login shell
-@command{/bin/sh}.
+remote host.  It supports changing the remote login shell @command{/bin/sh}.
 
 Check the @samp{Share SSH connections if possible} control for that
 session.
@@ -857,7 +856,7 @@ session.
 Another method using PuTTY on MS Windows with session names instead of
 host names.  @option{plinkx} calls @samp{plink -load @var{session}
 -t}.  User names and port numbers must be defined in the session.  It
-supports to change the remote login shell @command{/bin/sh}.
+supports changing the remote login shell @command{/bin/sh}.
 
 Check the @samp{Share SSH connections if possible} control for that
 session.
@@ -932,7 +931,7 @@ This method supports the @samp{-p} argument.
 @option{scpx} is useful to avoid login shell questions.  It is similar
 in performance to @option{scp}.  @option{scpx} uses @samp{ssh -t -t
 @var{host} -l @var{user} /bin/sh} to open a connection.  It supports
-to change the remote login shell @command{/bin/sh}.
+changing the remote login shell @command{/bin/sh}.
 
 @option{scpx} is useful for MS Windows users when @command{ssh}
 triggers an error about allocating a pseudo tty.  This happens due to
@@ -956,7 +955,7 @@ use the @command{plink} command to connect to the remote host, and
 they use @command{pscp} or @command{psftp} for transferring the files.
 These programs are part of PuTTY, an SSH implementation for MS Windows.
 
-They support to change the remote login shell @command{/bin/sh}.
+They support changing the remote login shell @command{/bin/sh}.
 
 Check the @samp{Share SSH connections if possible} control for that
 session.
@@ -3776,7 +3775,7 @@ you want to use another value for @env{TERM}, change
 @code{tramp-terminal-type} and this line accordingly.
 
 Alternatively, you could set the remote login shell explicitly.  See
-@ref{Remote shell setup} for discussing this technique,
+@ref{Remote shell setup} for discussion of this technique,
 
 When using fish shell on remote hosts, disable fancy formatting by
 adding the following to @file{~/.config/fish/config.fish}:
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index 934b5dd9d9f..b044762b70d 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -211,27 +211,35 @@ pair of the form (KEY VALUE).  The following KEYs are defined:
     or the name of telnet or a workalike, or the name of su or a workalike.
 
   * `tramp-login-args'
-    This specifies the list of arguments to pass to the above
-    mentioned program.  Please note that this is a list of list
-    of arguments, that is, normally you don't want to put \"-a
-    -b\" or \"-f foo\" here.  Instead, you want a list (\"-a\"
-    \"-b\"), or (\"-f\" \"foo\").  There are some patterns:
+    This specifies a list of lists of arguments to pass to the
+    above mentioned program.  You normally want to put each
+    argument in an individual string, i.e.
+    (\"-a\" \"-b\") rather than (\"-a -b\").
 
-    - \"%h\" in this list is replaced by the host name
+    \"%\" followed by a letter are expanded in the arguments as
+    follows:
+
+    - \"%h\" is replaced by the host name
     - \"%u\" is replaced by the user name
     - \"%p\" is replaced by the port number
     - \"%%\" can be used to obtain a literal percent character.
 
-    If a list containing \"%h\", \"%u\" or \"%p\" is unchanged
-    during expansion (i.e. no host, no user or no port
-    specified), this list is not used as argument.  By this,
-    arguments like (\"-l\" \"%u\") are optional.
+    If a sub-list containing \"%h\", \"%u\" or \"%p\" is
+    unchanged after expansion (i.e. no host, no user or no port
+    were specified), that sublist is not used.  For e.g.
+
+    '((\"-a\" \"-b\") (\"-l\" \"%u\"))
+
+    that means that (\"-l\" \"%u\") is used only if the user was
+    specified, and it is thus effectively optional.
+
+    Other expansions are:
 
     - \"%l\" is replaced by the login shell `tramp-remote-shell'
       and its parameters.
     - \"%t\" is replaced by the temporary file name produced with
       `tramp-make-tramp-temp-file'.
-    - \"%k\" indicates the keep-date parameter of a program, if exists
+    - \"%k\" indicates the keep-date parameter of a program, if exists.
     - \"%c\" adds additional `tramp-ssh-controlmaster-options'
       options for the first hop.