@end ifset
@ifhtml
-This manual is also available as a @uref{tramp_ja.html, Japanese
-translation}.
+@ifset jamanual
+This manual is also available as a @uref{@value{japanese-manual},
+Japanese translation}.
+@end ifset
The latest release of @tramp{} is available for
@uref{http://savannah.gnu.org/download/tramp/,
* Usage:: An overview of the operation of @tramp{}.
* Bug Reports:: Reporting Bugs and Problems.
* Frequently Asked Questions:: Questions and answers from the mailing list.
-* Concept Index:: An item for each concept
+* Concept Index:: An item for each concept.
For the developer:
* Installation parameters:: Parameters in order to control installation.
* Load paths:: How to plug-in @tramp{} into your environment.
+* Japanese manual:: Japanese manual.
@end ifset
* Windows setup hints:: Issues with Cygwin ssh.
* Auto-save and Backup:: Auto-save and Backup.
-Using @tramp
+Using @tramp{}
* Filename Syntax:: @tramp{} filename conventions.
* Multi-hop filename syntax:: Multi-hop filename conventions.
@end menu
@node Overview
-@chapter An overview of @tramp
+@chapter An overview of @tramp{}
@cindex overview
After the installation of @tramp{} into your @value{emacs-name}, you
Your access to the remote machine can be with the @command{rsh},
@command{rlogin}, @command{telnet} programs or with any similar
-connection method. This connection must pass @acronym{ASCII} successfully to be
-usable but need not be 8-bit clean.
+connection method. This connection must pass @acronym{ASCII}
+successfully to be usable but need not be 8-bit clean.
The package provides support for @command{ssh} connections out of the
box, one of the more common uses of the package. This allows
@c For the end user
@node Obtaining @tramp{}
@chapter Obtaining @tramp{}.
-@cindex obtaining Tramp
+@cindex obtaining @tramp{}
@tramp{} is freely available on the Internet and the latest release
may be downloaded from
@cindex configuration
@cindex default configuration
-@tramp{} is (normally) fully functional when it is initially
-installed. It is initially configured to use the @command{ssh} program
-to connect to the remote host and to use base-64 encoding (on the
-remote host, via @command{mimencode}, and on the local host via the
-built-in support for base-64 encoding in Emacs).
+@tramp{} is (normally) fully functional when it is initially installed.
+It is initially configured to use the @command{ssh} program to connect
+to the remote host and to use base64 or uu encoding to transfer the
+files through that shell connection. So in the easiest case, you just
+type @kbd{C-x C-f} and then enter the filename
+@file{@value{tramp-prefix}@var{user}@@@var{machine}@value{tramp-postfix}@var{/path/to.file}}.
On some hosts, there are problems with opening a connection. These are
related to the behavior of the remote shell. See @xref{Remote shell
If you do not wish to use these commands to connect to the remote
host, you should change the default connection and transfer method
-that @tramp uses. There are several different methods that @tramp{}
+that @tramp{} uses. There are several different methods that @tramp{}
can use to connect to remote machines and transfer files
(@pxref{Connection types}).
+If you don't know which method is right for you, see @xref{Default
+Method}.
+
@menu
* Connection types:: Types of connections made to remote machines.
* External transfer methods:: External transfer methods.
* Multi-hop Methods:: Connecting to a remote host using multiple hops.
* Default Method:: Selecting a default method.
+ Here we also try to help those who
+ don't have the foggiest which method
+ is right for them.
* Customizing Methods:: Using Non-Standard Methods.
* Customizing Completion:: Selecting config files for user/host name completion.
* Remote Programs:: How @tramp{} finds and uses programs on the remote machine.
remote shell access program such as @command{rsh}, @command{ssh} or
@command{telnet} to connect to the remote machine.
-This connection is used to perform many of the operations that @tramp
+This connection is used to perform many of the operations that @tramp{}
requires to make the remote file system transparently accessible from
the local machine. It is only when visiting files that the methods
differ.
explicitly select whether you want to use the SSH protocol version 1
or 2 to connect to the remote host. (You can also specify in
@file{~/.ssh/config}, the SSH configuration file, which protocol
-should be used, and use the regular @option{ssh} method.)
+should be used, and use the regular @option{scp} method.)
Two other variants, @option{scp1_old} and @option{scp2_old}, use the
@command{ssh1} and @command{ssh2} commands explicitly. If you don't
@vindex tramp-default-method
When you select an appropriate transfer method for your typical usage
-you should set the variable @var{tramp-default-method} to reflect that
+you should set the variable @code{tramp-default-method} to reflect that
choice. This variable controls which method will be used when a method
is not specified in the @tramp{} file name. For example:
@vindex tramp-default-method-alist
You can also specify different methods for certain user/host
-combinations, via the variable @var{tramp-default-method-alist}. For
+combinations, via the variable @code{tramp-default-method-alist}. For
example, the following two lines specify to use the @option{ssh}
method for all user names matching @samp{john} and the @option{rsync}
method for all host names matching @samp{lily}. The third line
@noindent
See the documentation for the variable
-@var{tramp-default-method-alist} for more details.
+@code{tramp-default-method-alist} for more details.
External transfer methods are normally preferable to inline transfer
methods, giving better performance. They may not be useful if you use
making it a non-trivial exercise for someone to obtain your password or
read the content of the files you are editing.
+
+@subsection Which method is the right one for me?
+@cindex choosing the right method
+
+Given all of the above, you are probably thinking that this is all fine
+and good, but it's not helping you to choose a method! Right you are.
+As a developer, we don't want to boss our users around but give them
+maximum freedom instead. However, the reality is that some users would
+like to have some guidance, so here I'll try to give you this guidance
+without bossing you around. You tell me whether it works @dots{}
+
+My suggestion is to use an inline method. For large files, out-of-band
+methods might be more efficient, but I guess that most people will want
+to edit mostly small files.
+
+I guess that these days, most people can access a remote machine by
+using @code{ssh}. So I suggest that you use the @code{ssh} method.
+So, type @kbd{C-x C-f /ssh:root@@otherhost:/etc/motd @key{RET}} to
+edit the @file{/etc/motd} file on the other host.
+
+If you can't use @code{ssh} to log in to the remote host, then select a
+method that uses a program that works. For instance, Windows users
+might like the @code{plink} method which uses the PuTTY implementation
+of @code{ssh}. Or you use Kerberos and thus like @code{krlogin}.
+
+For the special case of editing files on the local host as another
+user, see the @code{su} or @code{sudo} method.
+
+People who edit large files may want to consider @code{scp} instead of
+@code{ssh}, or @code{pscp} instead of @code{plink}. These out-of-band
+methods are faster than inline methods for large files. Note, however,
+that out-of-band methods suffer from some limitations. Please try
+first whether you really get a noticeable speed advantage from using an
+out-of-band method! Maybe even for large files, inline methods are
+fast enough.
+
+The reason why I'm suggesting to use inline methods is that they work
+even if the remote end is asking you for a password. Out-of-band
+methods don't work in this situation. Also, multi-hop methods are
+inherently inline.
+
+
@node Customizing Methods
@section Using Non-Standard Methods
@cindex customizing methods
the variables @code{tramp-actions-before-shell} and
@code{tramp-multi-actions} (for multi-hop connections).
+
+@item Environment variables named like users in @file{.profile}
+
+If you have a user named frumple and set the variable @code{FRUMPLE} in
+your shell environment, then this might cause trouble. Maybe rename
+the variable to @code{FRUMPLE_DIR} or the like.
+
+This weird effect was actually reported by a @tramp{} user!
+
+
@item Non-Bourne commands in @file{.profile}
After logging in to the remote host, @tramp{} issues the command
do not occur.
If you wish to customize the variable, the workaround is to include
-special settings for Tramp files. For example, the following statement
+special settings for @tramp{} files. For example, the following statement
effectively `turns off' the effect of @code{backup-directory-alist} for
@tramp{} files:
@node Usage
-@chapter Using @tramp
-@cindex using @tramp
+@chapter Using @tramp{}
+@cindex using @tramp{}
Once you have installed @tramp{} it will operate fairly transparently. You
will be able to access files on any remote machine that you can log in
The user, machine and file specification remain the same.
So, to connect to the machine @code{melancholia} as @code{daniel},
-using the @option{su} method to transfer files, and edit @file{.emacs}
+using the @option{ssh} method to transfer files, and edit @file{.emacs}
in my home directory I would specify the filename
-@file{@value{tramp-prefix}su@value{tramp-postfix-single-hop}daniel@@melancholia@value{tramp-postfix}.emacs}.
+@file{@value{tramp-prefix}ssh@value{tramp-postfix-single-hop}daniel@@melancholia@value{tramp-postfix}.emacs}.
@node Multi-hop filename syntax
machine,
@end ifset
and @samp{@value{tramp-prefix-single-hop}toto@value{tramp-postfix}}
-might be a host @tramp has detected in your @file{~/.ssh/known_hosts}
+might be a host @tramp{} has detected in your @file{~/.ssh/known_hosts}
file (given you're using default method @option{ssh}).
If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to