Document remote file name syntax change

* doc/emacs/files.texi (Remote Files, Quoted File Names):
* doc/misc/org.texi (dir): Change examples to use a method.

* doc/misc/tramp.texi (Top) [trampf]: Remove macro.  Add
`Testing' menu entry.
(History): Fix typos.  Mention syntax change.
(Configuration, Default Host, File name Syntax)
(File name completion, Frequently Asked Questions):
Change examples to use a method.
(External methods, Default Host, Multi-hops, Remote processes):
Fix typos.
(Default Method): Mention pseudo method "-".
(External packages): Rewrite intention of `non-essential'.

* etc/NEWS: Mark recent Tramp entries as documented.

4 files changed, 97 insertions, 105 deletions

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 2b09c69945c..1a85f96df48 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1777,9 +1777,7 @@ syntax:
 
 @example
 @group
-/@var{host}:@var{filename}
-/@var{user}@@@var{host}:@var{filename}
-/@var{user}@@@var{host}#@var{port}:@var{filename}
+/@var{method}:@var{host}:@var{filename}
 /@var{method}:@var{user}@@@var{host}:@var{filename}
 /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
 @end group
@@ -1788,11 +1786,11 @@ syntax:
 @noindent
 To carry out this request, Emacs uses a remote-login program such as
 @command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}.
-You can always specify in the file name which method to use---for
+You must always specify in the file name which method to use---for
 example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP,
 whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses
-@command{ssh}.  When you don't specify a method in the file name,
-Emacs chooses the method as follows:
+@command{ssh}.  When you specify the pseudo method @var{-} in the file
+name, Emacs chooses the method as follows:
 
 @enumerate
 @item
@@ -1884,7 +1882,7 @@ can refer to that file in Emacs as @samp{/:/foo:/bar}.
 
   If you want to quote only special characters in the local part of a
 remote file name, you can quote just the local part.
-@samp{/baz:/:/foo:/bar} refers to the file @file{bar} of directory
+@samp{/ssh:baz:/:/foo:/bar} refers to the file @file{bar} of directory
 @file{/foo:} on the host @file{baz}.
 
   @samp{/:} can also prevent @samp{~} from being treated as a special
diff --git a/doc/misc/org.texi b/doc/misc/org.texi
index 596300e5ed8..21c8758b802 100644
--- a/doc/misc/org.texi
+++ b/doc/misc/org.texi
@@ -15090,7 +15090,7 @@ A directory on a remote machine can be specified using tramp file syntax, in
 which case the code will be evaluated on the remote machine.  An example is
 
 @example
-#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu:
+#+BEGIN_SRC R :file plot.png :dir /scp:dand@@yakuba.princeton.edu:
 plot(1:10, main=system("hostname", intern=TRUE))
 #+END_SRC
 @end example
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 9c295a49a69..26b0915c0d9 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -24,13 +24,6 @@
 \userhost\@value{postfix}\localname\
 @end macro
 
-@c Similar, but without a method prefix.
-
-@macro trampf {userhost, localname}
-@value{prefix}@c
-\userhost\@value{postfix}\localname\
-@end macro
-
 @copying
 Copyright @copyright{} 1999--2017 Free Software Foundation, Inc.
 
@@ -133,8 +126,8 @@ For the developer:
 Installing @value{tramp} with your Emacs
 
 * Installation parameters::     Parameters in order to control installation.
+* Testing::                     A test suite for @value{tramp}.
 * Load paths::                  How to plug-in @value{tramp} into your environment.
-
 @end ifset
 
 Configuring @value{tramp} for use
@@ -398,12 +391,12 @@ Run @command{autoconf} as follows to generate an up-to-date
 @value{tramp} development started at the end of November 1998 as
 @file{rssh.el}.  It provided only one method of access.  It used
 @command{ssh} for login and @command{scp} to transfer file contents.
-The name was changed to @file{rcp.el} before it got its preset name
+The name was changed to @file{rcp.el} before it got its present name
 @value{tramp}.  New methods of remote access were added, so was support
 for version control.
 
 April 2000 was the first time when multi-hop methods were added.  In
-July 2002, @value{tramp} unified file names with Ange-FTP@.  In July
+July 2002, @value{tramp} unified file names with Ange FTP@.  In July
 2004, proxy hosts replaced multi-hop methods.  Running commands on
 remote hosts was introduced in December 2005.  Support for gateways
 since April 2007 (and removed in December 2016).  GVFS integration
@@ -412,7 +405,8 @@ September 2011.  Ad-hoc multi-hop methods (with a changed syntax)
 re-enabled in November 2011.  In November 2012, added Juergen
 Hoetzel's @file{tramp-adb.el}.
 
-XEmacs support has been stopped in January 2016.
+XEmacs support has been stopped in January 2016.  Since March 2017,
+@value{tramp} syntax requires a method mandatorily.
 
 @c Installation chapter is necessary only in case of standalone
 @c installation.  Text taken from trampinst.texi.
@@ -428,7 +422,7 @@ XEmacs support has been stopped in January 2016.
 
 @value{tramp} is initially configured to use the @command{scp} program
 to connect to the remote host.  Just type @kbd{C-x C-f} and then enter
-file name @file{@trampf{user@@host,/path/to/file}}.  For details,
+file name @file{@trampfn{scp,user@@host,/path/to/file}}.  For details,
 @xref{Default Method}, @xref{Default User}, @xref{Default Host}.
 
 For problems related to the behavior of the remote shell, @xref{Remote
@@ -819,9 +813,9 @@ Using @command{smbclient} requires a few tweaks when working with
 The first directory in the localname must be a share name on the
 remote host.
 
-Since SMB shares end in the @code{$} character, @value{tramp} must use
-@code{$$} when specifying those shares to avoid environment variable
-substitutions.
+Since some SMB share names end in the @code{$} character,
+@value{tramp} must use @code{$$} when specifying those shares to avoid
+environment variable substitutions.
 
 When @value{tramp} is not specific about the share name or uses the
 generic remote directory @file{/}, @command{smbclient} returns all
@@ -834,7 +828,7 @@ handling}.
 
 To accommodate user name/domain name syntax required by MS Windows
 authorization, @value{tramp} provides for an extended syntax in
-@code{user%domain} format (where user is username, @code{%} is the
+@code{user%domain} format (where user is user name, @code{%} is the
 percent symbol, and domain is the windows domain name).  An example:
 
 @example
@@ -1002,6 +996,9 @@ Other methods to include are: @option{ftp} and @option{smb}.
 @section Selecting a default method
 @cindex default method
 
+In a remote file name, the use of a default method is indicated by the
+pseudo method @option{-}, @ref{File name Syntax}.
+
 @defopt tramp-default-method
 Default method is for transferring files.  The user option
 @option{tramp-default-method} sets it.  @value{tramp} uses this user
@@ -1145,25 +1142,21 @@ for catch-all or most often used login.
 @defopt tramp-default-host
 When host name is omitted, @value{tramp} substitutes the value from
 the @option{tramp-default-host} user option.  It is initially
-populated with the local hostname where Emacs is running.  Both the
-default user and default host can be overridden as follows:
+populated with the local host name where Emacs is running.  The
+default method, default user and default host can be overridden as
+follows:
 
 @lisp
 @group
 (custom-set-variables
+ '(tramp-default-method "ssh" nil (tramp))
  '(tramp-default-user "john" nil (tramp))
  '(tramp-default-host "target" nil (tramp)))
 @end group
 @end lisp
 
-With both defaults set, @samp{@trampfn{ssh,,}} will connect
-@value{tramp} to John's home directory on @code{target}.
-
-@strong{Note} @samp{/::} won't work, because @samp{/:} is the prefix
-for quoted file names.
-@ifinfo
-@pxref{Quoted File Names, , , emacs}.
-@end ifinfo
+With all defaults set, @samp{@trampfn{-,,}} will connect @value{tramp}
+to John's home directory on @code{target} via @code{ssh}.
 @end defopt
 
 @defopt tramp-default-host-alist
@@ -1248,7 +1241,7 @@ access, then use this alist entry:
 
 Opening @file{@trampfn{sudo,randomhost.your.domain,}} first connects
 to @samp{randomhost.your.domain} via @code{ssh} under your account
-name, and then perform @code{sudo -u root} on that host.
+name, and then performs @code{sudo -u root} on that host.
 
 It is key for the sudo method in the above example to be applied on
 the host after reaching it and not on the local host.
@@ -2151,35 +2144,34 @@ is a feature of Emacs that may cause missed prompts when using
 @cindex file name syntax
 @cindex file name examples
 
-@file{@trampf{host,localfilename}} opens file @var{localfilename} on
-the remote host @var{host}, using the default method.  @xref{Default
-Method}.
+@file{@trampfn{method,host,/path/to/file}} opens file @var{/path/to/file}
+on the remote host @var{host}, using the method @var{method}.
 
 @table @file
-@item @value{prefix}melancholia@value{postfix}.emacs
+@item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}.emacs
 For the file @file{.emacs} located in the home directory, on the host
-@code{melancholia}.
+@code{melancholia}, using method @code{ssh}.
 
-@item @value{prefix}melancholia.danann.net@value{postfix}.emacs
+@item @value{prefix}ssh@value{postfixhop}melancholia.danann.net@value{postfix}.emacs
 For the file @file{.emacs} specified using the fully qualified domain name of
 the host.
 
-@item @value{prefix}melancholia@value{postfix}~/.emacs
+@item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}~/.emacs
 For the file @file{.emacs} specified using the @file{~}, which is expanded.
 
-@item @value{prefix}melancholia@value{postfix}~daniel/.emacs
+@item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}~daniel/.emacs
 For the file @file{.emacs} located in @code{daniel}'s home directory
 on the host, @code{melancholia}.  The @file{~<user>} construct is
 expanded to the home directory of that user on the remote host.
 
-@item @value{prefix}melancholia@value{postfix}/etc/squid.conf
+@item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}/etc/squid.conf
 For the file @file{/etc/squid.conf} on the host @code{melancholia}.
 
 @end table
 
 @var{host} can take IPv4 or IPv6 address, as in
-@file{@trampf{127.0.0.1,.emacs}} or
-@file{@trampf{@value{ipv6prefix}::1@value{ipv6postfix},.emacs}}.
+@file{@trampfn{ssh,127.0.0.1,.emacs}} or
+@file{@trampfn{ssh,@value{ipv6prefix}::1@value{ipv6postfix},.emacs}}.
 @ifset unified
 For syntactical reasons, IPv6 addresses must be embedded in square
 brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
@@ -2190,31 +2182,23 @@ remote user name for log in to the remote host.  Specifying a different
 name using the proper syntax will override this default behavior:
 
 @example
-@trampf{user@@host,path/to/file}
+@trampfn{method,user@@host,path/to/file}
 @end example
 
-@file{@trampf{daniel@@melancholia,.emacs}} is for file @file{.emacs}
-in @code{daniel}'s home directory on the host, @code{melancholia}.
-
-Specify other file access methods (@pxref{Inline methods},
-@pxref{External methods}) as part of the file name.
-
-Method name comes before user name, as in
-@file{@value{prefix}@var{method}@value{postfixhop}} (Note the trailing
-colon).  The syntax specifications for user, host, and file do not
-change.
-
-To connect to the host @code{melancholia} as @code{daniel}, using
-@option{ssh} method for @file{.emacs} in @code{daniel}'s home
-directory, the full specification is:
-@file{@trampfn{ssh,daniel@@melancholia,.emacs}}.
-
-A remote file name containing a host name, which is the same string as
-a method name, is not allowed.
+@file{@trampfn{ssh,daniel@@melancholia,.emacs}} is for file
+@file{.emacs} in @code{daniel}'s home directory on the host,
+@code{melancholia}, accessing via method @code{ssh}.
 
 For specifying port numbers, affix @file{#<port>} to the host
 name.  For example: @file{@trampfn{ssh,daniel@@melancholia#42,.emacs}}.
 
+All method, user name, host name, port number and local name parts are
+optional, @xref{Default Method}, @xref{Default User}, @xref{Default Host}.
+@ifset unified
+For syntactical reasons, the default method must be indicated by the
+pseudo method @file{-}.
+@end ifset
+
 
 @node File name completion
 @section File name completion
@@ -2228,38 +2212,52 @@ in @file{.emacs}.
 @xref{Completion Options, , , emacs}.
 @end ifinfo
 
-For example, type @kbd{C-x C-f @value{prefix}t @key{TAB}},
+For example, type @kbd{C-x C-f @value{prefix}s @key{TAB}},
 @value{tramp} completion choices show up as
 
 @example
 @group
-@c @multitable {@trampfn{telnet,melancholia.danann.net,}} {@trampfn{telnet,192.168.0.1,}}
-@multitable @columnfractions .5 .5
-@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
-@item @value{prefixhop}toto@value{postfix} @tab
+@multitable @columnfractions .2 .2 .2 .2 .2
+@item @c
+  sbin/ @tab @c
+  @value{prefixhop}scp@value{postfix} @tab @c
+  @value{prefixhop}scpx@value{postfix} @tab @c
+  @value{prefixhop}sftp@value{postfix} @tab @c
+  @value{prefixhop}sg@value{postfix}
+@item @c
+  @value{prefixhop}smb@value{postfix} @tab @c
+  srv/ @tab @c
+  @value{prefixhop}ssh@value{postfix} @tab @c
+  @value{prefixhop}sshx@value{postfix} @tab @c
+  @value{prefixhop}su@value{postfix}
+@item @c
+  @value{prefixhop}sudo@value{postfix} @tab @c
+  sys/
 @end multitable
 @end group
 @end example
 
-@samp{@value{prefixhop}telnet@value{postfixhop}} is a possible
-completion for the respective method, @samp{tmp/} stands for the
-directory @file{/tmp} on your local host, and
-@samp{@value{prefixhop}toto@value{postfix}} might be a host
-@value{tramp} has detected in your @file{~/.ssh/known_hosts} file
-(when using @option{ssh} as default method).
+@samp{@value{prefixhop}ssh@value{postfixhop}} is a possible
+completion for the respective method, and @samp{sbin/} stands for the
+directory @file{/sbin} on your local host.
 
-Type @kbd{e @key{TAB}} for the minibuffer completion to
-@samp{@value{prefix}telnet@value{postfixhop}}.  Typing @kbd{@key{TAB}}
-shows host names @value{tramp} from @file{/etc/hosts} file, for example.
+Type @kbd{s h @value{postfixhop}} for the minibuffer completion to
+@samp{@value{prefix}ssh@value{postfixhop}}.  Typing @kbd{@key{TAB}}
+shows host names @value{tramp} extracts from @file{~/.ssh/config}
+file, for example.
 
 @example
 @group
 @multitable @columnfractions .5 .5
-@c @multitable {@trampfn{telnet,melancholia.danann.net,}} {@trampfn{telnet,192.168.0.1,}}
-@item @trampfn{telnet,127.0.0.1,} @tab @trampfn{telnet,192.168.0.1,}
-@c @item @trampfn{telnet,@value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet,localhost,}
-@item @value{prefix}telnet@value{postfixhop}@value{ipv6prefix}::1@value{ipv6postfix}@value{postfix} @tab @trampfn{telnet,localhost,}
-@item @trampfn{telnet,melancholia.danann.net,} @tab @trampfn{telnet,melancholia,}
+@item @c
+  @value{prefixhop}ssh@value{postfixhop}127.0.0.1@value{postfix} @tab @c
+  @value{prefixhop}ssh@value{postfixhop}192.168.0.1@value{postfix}
+@item @c
+  @value{prefixhop}ssh@value{postfixhop}@value{ipv6prefix}::1@value{ipv6postfix}@value{postfix} @tab @c
+  @value{prefixhop}ssh@value{postfixhop}localhost@value{postfix}
+@item @c
+  @value{prefixhop}ssh@value{postfixhop}melancholia.danann.net@value{postfix} @tab @c
+  @value{prefixhop}ssh@value{postfixhop}melancholia@value{postfix}
 @end multitable
 @end group
 @end example
@@ -2288,13 +2286,13 @@ Example:
 
 @example
 @group
-@kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin//etc} @key{TAB}}
-     @print{} @trampfn{telnet,melancholia,/etc}
+@kbd{C-x C-f @trampfn{ssh,melancholia,/usr/local/bin//etc} @key{TAB}}
+     @print{} @trampfn{ssh,melancholia,/etc}
 
-@kbd{C-x C-f @trampfn{telnet,melancholia,//etc} @key{TAB}}
+@kbd{C-x C-f @trampfn{ssh,melancholia,//etc} @key{TAB}}
      @print{} /etc
 
-@kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin///etc} @key{TAB}}
+@kbd{C-x C-f @trampfn{ssh,melancholia,/usr/local/bin///etc} @key{TAB}}
      @print{} /etc
 @end group
 @end example
@@ -2527,9 +2525,9 @@ host.  Example:
 
 @value{tramp} is integrated into @file{eshell.el}, which enables
 interactive eshell sessions on remote hosts at the command prompt.
-You must add the module @code{eshell-tramp} to
-@code{eshell-modules-list}.  Here's a sample interaction after opening
-@kbd{M-x eshell} on a remote host:
+You must add the module @code{em-tramp} to @code{eshell-modules-list}.
+Here's a sample interaction after opening @kbd{M-x eshell} on a remote
+host:
 
 @example
 @group
@@ -3113,7 +3111,7 @@ You can define default methods and user names for hosts,
 @end group
 @end lisp
 
-The reduced typing: @kbd{C-x C-f @trampf{news.my.domain,/opt/news/etc}}.
+The reduced typing: @kbd{C-x C-f @trampfn{-,news.my.domain,/opt/news/etc}}.
 
 @strong{Note} that there are some useful shortcuts already.  Accessing
 your local host as @samp{root} user, is possible just by @kbd{C-x C-f
@@ -3472,18 +3470,12 @@ handlers.
 @section Integrating with external Lisp packages
 @subsection File name completion.
 
-For name completions in the minibuffer, @value{tramp} depends on the
-last input character to decide whether to look for method name
-completion or host name completion.  For example, @kbd{C-x C-f
-@value{prefix}ssh@value{postfixhop} @key{TAB}} is not entirely clear
-if @option{ssh} is a method or a host name.  But if the last input
-character was either @key{TAB}, @key{SPACE} or @kbd{?}, then
-@value{tramp} favors file name completion over host name completion.
-
-What about external packages using other characters to trigger file
-name completions? They must somehow signal this to @value{tramp}.  Use
-the variable @code{non-essential} temporarily and bind it to
-non-@code{nil} value.
+Sometimes, it is not convenient to open a new connection to a remote
+host, including entering the password and alike.  For example, this is
+nasty for packages providing file name completion. Such a package
+could signal to @value{tramp}, that they don't want it to establish a
+new connection.  Use the variable @code{non-essential} temporarily and
+bind it to non-@code{nil} value.
 
 @lisp
 @group
diff --git a/etc/NEWS b/etc/NEWS
index e1b6249d475..88ae7cf1f52 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -634,10 +634,12 @@ header's value.
 
 ** Tramp
 
++++
 *** The method part of remote file names is mandatory now.  A valid
 remote file name starts with "/method:host:" or "/method:user@host:".
 
-*** The new virtual method "-" is a marker for the default method.
++++
+*** The new pseudo method "-" is a marker for the default method.
 "/-::" is the shortest remote file name then.
 
 +++