From 265a5d9791bf42da0bab7bdbef4352e8d734ef31 Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Thu, 16 Mar 2017 16:23:07 +0100 Subject: [PATCH] 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 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{~} 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{#} 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. +++ -- 2.39.5