* tramp.texi (Version Control): Remove.

(Obtaining Tramp): Update cvs checkout command. Remove nightly tarballs
reference.
(External methods): Correct `scpc' concept index entries.  New method
`rsyncc'.
(External packages): New subsections "Filename completion" and "File
attributes cache".

2 files changed, 52 insertions, 173 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 0b07c43a408..87efed613e5 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,13 @@
+2009-08-28  Michael Albinus  <michael.albinus@gmx.de>
+
+        * tramp.texi (Version Control): Remove.
+        (Obtaining Tramp): Update cvs checkout command. Remove nightly tarballs
+        reference.
+        (External methods): Correct `scpc' concept index entries.  New method
+        `rsyncc'.
+        (External packages): New subsections "Filename completion" and "File
+        attributes cache".
+
 2009-08-27  Jay Belanger  <jay.p.belanger@gmail.com>
 
         * calc.texi (Rewrite Rules): Improve the example.
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 1536bd49553..20be7a2870f 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -157,7 +157,6 @@ For the end user:
 
 For the developer:
 
-* Version Control::             The inner workings of remote version control.
 * Files directories and localnames::  How file names, directories and localnames are mangled and managed.
 * Traces and Profiles::         How to Customize Traces.
 * Issues::                      Debatable Issues and What Was Decided.
@@ -208,19 +207,6 @@ Using @value{tramp}
 * Remote processes::            Integration with other @value{emacsname} packages.
 * Cleanup remote connections::  Cleanup remote connections.
 
-The inner workings of remote version control
-
-* Version Controlled Files::    Determining if a file is under version control.
-* Remote Commands::             Executing the version control commands on the remote machine.
-* Changed workfiles::           Detecting if the working file has changed.
-* Checking out files::          Bringing the workfile out of the repository.
-* Miscellaneous Version Control::  Things related to Version Control that don't fit elsewhere.
-
-Things related to Version Control that don't fit elsewhere
-
-* Remote File Ownership::       How VC determines who owns a workfile.
-* Back-end Versions::           How VC determines what release your RCS is.
-
 How file names, directories and localnames are mangled and managed
 
 * Localname deconstruction::    Breaking a localname into its components.
@@ -416,7 +402,7 @@ Or follow the example session below:
 @example
 ] @strong{cd ~/@value{emacsdir}}
 ] @strong{export CVS_RSH="ssh"}
-] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
+] @strong{cvs -z3 -d:pserver:anonymous@@cvs.savannah.gnu.org:/sources/tramp co tramp}
 @end example
 
 @noindent
@@ -440,11 +426,6 @@ script:
 ] @strong{autoconf}
 @end example
 
-People who have no direct CVS access (maybe because sitting behind a
-blocking firewall), can try the
-@uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
-CVS Tree Tarball} instead of.
-
 
 @node History
 @chapter History of @value{tramp}
@@ -896,10 +877,10 @@ This method supports the @samp{-p} argument.
 
 
 @item @option{scpc} --- @command{ssh} and @command{scp}
-@cindex method scpx
-@cindex scpx method
-@cindex scp (with scpx method)
-@cindex ssh (with scpx method)
+@cindex method scpc
+@cindex scpc method
+@cindex scp (with scpc method)
+@cindex ssh (with scpc method)
 
 Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
 @option{ControlMaster}.  This allows @option{scp} to reuse an existing
@@ -915,6 +896,20 @@ ssh localhost -o ControlMaster=yes
 This method supports the @samp{-p} argument.
 
 
+@item @option{rsyncc}  ---  @command{ssh} and @command{rsync}
+@cindex method rsyncc
+@cindex rsyncc method
+@cindex rsync (with rsyncc method)
+@cindex ssh (with rsyncc method)
+
+Like the @option{scpc} method, @option{rsyncc} improves the underlying
+@command{ssh} connection by the option @option{ControlMaster}.  This
+allows @command{rsync} to reuse an existing @command{ssh} channel,
+which increases performance.
+
+This method supports the @samp{-p} argument.
+
+
 @item @option{pscp} --- @command{plink} and @command{pscp}
 @cindex method pscp
 @cindex pscp method
@@ -2302,7 +2297,8 @@ Filename completion works with @value{tramp} for completion of method
 names, of user names and of machine names as well as for completion of
 file names on remote machines.
 @ifset emacs
-In order to enable this, Partial Completion mode must be set on.
+In order to enable this, partial completion must be activated in your
+@file{.emacs}.
 @ifinfo
 @xref{Completion Options, , , @value{emacsdir}}.
 @end ifinfo
@@ -3257,153 +3253,6 @@ This resets also the @value{ftppackagename} plugins.
 
 
 @c For the developer
-@node Version Control
-@chapter The inner workings of remote version control
-@cindex Version Control
-
-Unlike @value{ftppackagename}, @value{tramp} has full shell access to the
-remote machine.  This makes it possible to provide version control for
-files accessed under @value{tramp}.
-
-The actual version control binaries must be installed on the remote
-machine, accessible in the directories specified in
-@code{tramp-remote-path}.
-
-This transparent integration with the version control systems is one of
-the most valuable features provided by @value{tramp}, but it is far from perfect.
-Work is ongoing to improve the transparency of the system.
-
-@menu
-* Version Controlled Files::    Determining if a file is under version control.
-* Remote Commands::             Executing the version control commands on the remote machine.
-* Changed workfiles::           Detecting if the working file has changed.
-* Checking out files::          Bringing the workfile out of the repository.
-* Miscellaneous Version Control::  Things related to Version Control that don't fit elsewhere.
-@end menu
-
-
-@node Version Controlled Files
-@section Determining if a file is under version control
-
-The VC package uses the existence of on-disk revision control master
-files to determine if a given file is under revision control.  These file
-tests happen on the remote machine through the standard @value{tramp} mechanisms.
-
-
-@node Remote Commands
-@section Executing the version control commands on the remote machine
-
-There are no hooks provided by VC to allow intercepting of the version
-control command execution.  The calls occur through the
-@code{call-process} mechanism, a function that is somewhat more
-efficient than the @code{shell-command} function but that does not
-provide hooks for remote execution of commands.
-
-To work around this, the functions @code{vc-do-command} and
-@code{vc-simple-command} have been advised to intercept requests for
-operations on files accessed via @value{tramp}.
-
-In the case of a remote file, the @code{shell-command} interface is
-used, with some wrapper code, to provide the same functionality on the
-remote machine as would be seen on the local machine.
-
-
-@node Changed workfiles
-@section Detecting if the working file has changed
-
-As there is currently no way to get access to the mtime of a file on a
-remote machine in a portable way, the @code{vc-workfile-unchanged-p}
-function is advised to call an @value{tramp} specific function for remote files.
-
-The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC
-diff functionality to determine if any changes have occurred between the
-workfile and the version control master.
-
-This requires that a shell command be executed remotely, a process that
-is notably heavier-weight than the mtime comparison used for local
-files.  Unfortunately, unless a portable solution to the issue is found,
-this will remain the cost of remote version control.
-
-
-@node Checking out files
-@section Bringing the workfile out of the repository
-
-VC will, by default, check for remote files and refuse to act on them
-when checking out files from the repository.  To work around this
-problem, the function @code{vc-checkout} knows about @value{tramp} files and
-allows version control to occur.
-
-
-@node Miscellaneous Version Control
-@section Things related to Version Control that don't fit elsewhere
-
-Minor implementation details, &c.
-
-@menu
-* Remote File Ownership::       How VC determines who owns a workfile.
-* Back-end Versions::           How VC determines what release your RCS is.
-@end menu
-
-
-@node Remote File Ownership
-@subsection How VC determines who owns a workfile
-
-@value{emacsname} provides the @code{user-login-name} function to
-return the login name of the current user as well as mapping from
-arbitrary user id values back to login names.  The VC code uses this
-functionality to map from the uid of the owner of a workfile to the
-login name in some circumstances.
-
-This will not, for obvious reasons, work if the remote system has a
-different set of logins.  As such, it is necessary to delegate to the
-remote machine the job of determining the login name associated with a
-uid.
-
-Unfortunately, with the profusion of distributed management systems such
-as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple,
-reliable and portable method for performing this mapping.
-
-Thankfully, the only place in the VC code that depends on the mapping of
-a uid to a login name is the @code{vc-file-owner} function.  This returns
-the login of the owner of the file as a string.
-
-This function has been advised to use the output of @command{ls} on the
-remote machine to determine the login name, delegating the problem of
-mapping the uid to the login to the remote system which should know more
-about it than I do.
-
-
-@node Back-end Versions
-@subsection How VC determines what release your RCS is
-
-VC needs to know what release your revision control binaries you are
-running as not all features VC supports are available with older
-versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}.
-
-The default implementation of VC determines this value the first time it
-is needed and then stores the value globally to avoid the overhead of
-executing a process and parsing its output each time the information is
-needed.
-
-Unfortunately, life is not quite so easy when remote version control
-comes into the picture.  Each remote machine may have a different version
-of the version control tools and, while this is painful, we need to
-ensure that unavailable features are not used remotely.
-
-To resolve this issue, @value{tramp} currently takes the sledgehammer
-approach of making the release values of the revision control tools
-local to each @value{tramp} buffer, forcing VC to determine these values
-again each time a new file is visited.
-
-This has, quite obviously, some performance implications.  Thankfully,
-most of the common operations performed by VC do not actually require
-that the remote version be known.  This makes the problem far less
-apparent.
-
-Eventually these values will be captured by @value{tramp} on a system by
-system basis and the results cached to improve performance.
-
-
 @node Files directories and localnames
 @chapter How file names, directories and localnames are mangled and managed.
 
@@ -3434,6 +3283,7 @@ effect while preserving the @value{tramp} file name information.
 @ifset emacs
 @node External packages
 @section Integration with external Lisp packages.
+@subsection Filename completion.
 
 While reading filenames in the minibuffer, @value{tramp} must decide
 whether it completes possible incomplete filenames, or not.  Imagine
@@ -3449,12 +3299,31 @@ remote host @option{ssh}.
 External packages, which use other characters for completing filenames
 in the minibuffer, must signal this to @value{tramp}.  For this case,
 the variable @code{tramp-completion-mode} can be bound temporarily to
-a non-nil value.
+a non-@code{nil} value.
 
 @lisp
 (let ((tramp-completion-mode t))
   ...)
 @end lisp
+
+
+@subsection File attributes cache.
+
+When @value{tramp} runs remote processes, files on the remote host
+could change their attributes.  Consequently, @value{tramp} must flush
+its complete cache keeping attributes for all files of the remote host
+it has seen so far.
+
+This is a performance degradation, because the lost file attributes
+must be recomputed, when needed again.  In cases the caller of
+@code{process-file} knows that there are file attribute changes, it
+shall let-bind the variable @code{process-file-side-effects} to
+@code{nil}.  @value{tramp} wouldn't flush the file attributes cache then.
+
+@lisp
+(let (process-file-side-effects)
+  ...)
+@end lisp
 @end ifset