[Emacs-diffs] master 265a5d9: Document remote file name syntax change

[Michael Albinus]

branch: master
commit 265a5d9791bf42da0bab7bdbef4352e8d734ef31
Author: Michael Albinus <address@hidden>
Commit: Michael Albinus <address@hidden>

    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.
---
 doc/emacs/files.texi |  12 ++--
 doc/misc/org.texi    |   2 +-
 doc/misc/tramp.texi  | 184 ++++++++++++++++++++++++---------------------------
 etc/NEWS             |   4 +-
 4 files changed, 97 insertions(+), 105 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 2b09c69..1a85f96 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}@@@address@hidden:@var{filename}
+/@var{method}:@var{host}:@var{filename}
 /@var{method}:@var{user}@@@var{host}:@var{filename}
 /@var{method}:@var{user}@@@address@hidden:@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
address@hidden  When you don't specify a method in the file name,
-Emacs chooses the method as follows:
address@hidden  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.
address@hidden/baz:/:/foo:/bar} refers to the file @file{bar} of directory
address@hidden/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 596300e..21c8758 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 9c295a4..26b0915 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -24,13 +24,6 @@
 address@hidden
 @end macro
 
address@hidden Similar, but without a method prefix.
-
address@hidden trampf {userhost, localname}
address@hidden@c
address@hidden
address@hidden 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 address@hidden  In July
+July 2002, @value{tramp} unified file names with Ange address@hidden  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,
address@hidden 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 @address@hidden@@host,/path/to/file}}.  For details,
+file name @address@hidden,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
address@hidden when specifying those shares to avoid environment variable
-substitutions.
+Since some SMB share names end in the @code{$} character,
address@hidden 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
address@hidden format (where user is username, @code{%} is the
address@hidden 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, @address@hidden,,}} will connect
address@hidden to John's home directory on @code{target}.
-
address@hidden @samp{/::} won't work, because @samp{/:} is the prefix
-for quoted file names.
address@hidden
address@hidden File Names, , , emacs}.
address@hidden ifinfo
+With all defaults set, @address@hidden,,}} 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 @address@hidden,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
 
address@hidden@trampf{host,localfilename}} opens file @var{localfilename} on
-the remote host @var{host}, using the default method.  @xref{Default
-Method}.
address@hidden@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
address@hidden @address@hidden
address@hidden @address@hidden@value{postfix}.emacs
 For the file @file{.emacs} located in the home directory, on the host
address@hidden
address@hidden, using method @code{ssh}.
 
address@hidden @address@hidden
address@hidden @address@hidden@value{postfix}.emacs
 For the file @file{.emacs} specified using the fully qualified domain name of
 the host.
 
address@hidden @address@hidden/.emacs
address@hidden @address@hidden@value{postfix}~/.emacs
 For the file @file{.emacs} specified using the @file{~}, which is expanded.
 
address@hidden @address@hidden/.emacs
address@hidden @address@hidden@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.
 
address@hidden @address@hidden/etc/squid.conf
address@hidden @address@hidden@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
address@hidden@trampf{127.0.0.1,.emacs}} or
address@hidden@address@hidden::address@hidden,.emacs}}.
address@hidden@trampfn{ssh,127.0.0.1,.emacs}} or
address@hidden@trampfn{ssh,@value{ipv6prefix}::address@hidden,.emacs}}.
 @ifset unified
 For syntactical reasons, IPv6 addresses must be embedded in square
 brackets @address@hidden and @address@hidden
@@ -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
address@hidden@@host,path/to/file}
address@hidden,user@@host,path/to/file}
 @end example
 
address@hidden@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},
address@hidden methods}) as part of the file name.
-
-Method name comes before user name, as in
address@hidden@address@hidden@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
address@hidden method for @file{.emacs} in @code{daniel}'s home
-directory, the full specification is:
address@hidden@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.
address@hidden@trampfn{ssh,daniel@@melancholia,.emacs}} is for file
address@hidden in @code{daniel}'s home directory on the host,
address@hidden, accessing via method @code{ssh}.
 
 For specifying port numbers, affix @file{#<port>} to the host
 name.  For example: @address@hidden,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}.
address@hidden unified
+For syntactical reasons, the default method must be indicated by the
+pseudo method @file{-}.
address@hidden 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
address@hidden @multitable address@hidden,melancholia.danann.net,}} 
address@hidden,192.168.0.1,}}
address@hidden @columnfractions .5 .5
address@hidden @address@hidden @tab tmp/
address@hidden @address@hidden @tab
address@hidden @columnfractions .2 .2 .2 .2 .2
address@hidden @c
+  sbin/ @tab @c
+  @address@hidden @tab @c
+  @address@hidden @tab @c
+  @address@hidden @tab @c
+  @address@hidden
address@hidden @c
+  @address@hidden @tab @c
+  srv/ @tab @c
+  @address@hidden @tab @c
+  @address@hidden @tab @c
+  @address@hidden
address@hidden @c
+  @address@hidden @tab @c
+  sys/
 @end multitable
 @end group
 @end example
 
address@hidden@address@hidden is a possible
-completion for the respective method, @samp{tmp/} stands for the
-directory @file{/tmp} on your local host, and
address@hidden@address@hidden might be a host
address@hidden has detected in your @file{~/.ssh/known_hosts} file
-(when using @option{ssh} as default method).
address@hidden@address@hidden 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
address@hidden@address@hidden  Typing @address@hidden
-shows host names @value{tramp} from @file{/etc/hosts} file, for example.
+Type @kbd{s h @value{postfixhop}} for the minibuffer completion to
address@hidden@address@hidden  Typing @address@hidden
+shows host names @value{tramp} extracts from @file{~/.ssh/config}
+file, for example.
 
 @example
 @group
 @multitable @columnfractions .5 .5
address@hidden @multitable address@hidden,melancholia.danann.net,}} 
address@hidden,192.168.0.1,}}
address@hidden @trampfn{telnet,127.0.0.1,} @tab @trampfn{telnet,192.168.0.1,}
address@hidden @item @trampfn{telnet,@value{ipv6prefix}::address@hidden,} @tab 
@trampfn{telnet,localhost,}
address@hidden @address@hidden@value{ipv6prefix}::address@hidden@value{postfix} 
@tab @trampfn{telnet,localhost,}
address@hidden @trampfn{telnet,melancholia.danann.net,} @tab 
@trampfn{telnet,melancholia,}
address@hidden @c
+  @address@hidden@value{postfix} @tab @c
+  @address@hidden@value{postfix}
address@hidden @c
+  @address@hidden@value{ipv6prefix}::address@hidden@value{postfix} @tab @c
+  @address@hidden@value{postfix}
address@hidden @c
+  @address@hidden@value{postfix} @tab @c
+  @address@hidden@value{postfix}
 @end multitable
 @end group
 @end example
@@ -2288,13 +2286,13 @@ Example:
 
 @example
 @group
address@hidden C-f @trampfn{telnet,melancholia,/usr/local/bin//etc} @key{TAB}}
-     @print{} @trampfn{telnet,melancholia,/etc}
address@hidden C-f @trampfn{ssh,melancholia,/usr/local/bin//etc} @key{TAB}}
+     @print{} @trampfn{ssh,melancholia,/etc}
 
address@hidden C-f @trampfn{telnet,melancholia,//etc} @key{TAB}}
address@hidden C-f @trampfn{ssh,melancholia,//etc} @key{TAB}}
      @print{} /etc
 
address@hidden C-f @trampfn{telnet,melancholia,/usr/local/bin///etc} @key{TAB}}
address@hidden 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
address@hidden  Here's a sample interaction after opening
address@hidden 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
address@hidden@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
address@hidden 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
address@hidden 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 address@hidden value.
 
 @lisp
 @group
diff --git a/etc/NEWS b/etc/NEWS
index e1b6249..88ae7cf 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:address@hidden:".
 
-*** 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.
 
 +++