[Emacs-diffs] emacs/doc/misc tramp.texi

[Michael Albinus]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael Albinus <albinus>       09/08/28 14:36:41

Modified files:
        doc/misc       : tramp.texi 

Log message:
        * 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".

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/tramp.texi?cvsroot=emacs&r1=1.28&r2=1.29

Patches:
Index: tramp.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/tramp.texi,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -b -r1.28 -r1.29
--- tramp.texi  1 Jul 2009 15:09:21 -0000       1.28
+++ tramp.texi  28 Aug 2009 14:36:41 -0000      1.29
@@ -157,7 +157,6 @@
 
 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 @@
 * 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 @@
 @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 @@
 ] @strong{autoconf}
 @end example
 
-People who have no direct CVS access (maybe because sitting behind a
-blocking firewall), can try the
address@hidden://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 @@
 
 
 @item @option{scpc} --- @command{ssh} and @command{scp}
address@hidden method scpx
address@hidden scpx method
address@hidden scp (with scpx method)
address@hidden ssh (with scpx method)
address@hidden method scpc
address@hidden scpc method
address@hidden scp (with scpc method)
address@hidden 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 @@
 This method supports the @samp{-p} argument.
 
 
address@hidden @option{rsyncc}  ---  @command{ssh} and @command{rsync}
address@hidden method rsyncc
address@hidden rsyncc method
address@hidden rsync (with rsyncc method)
address@hidden ssh (with rsyncc method)
+
+Like the @option{scpc} method, @option{rsyncc} improves the underlying
address@hidden 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 @@
 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
address@hidden
 @ifinfo
 @xref{Completion Options, , , @value{emacsdir}}.
 @end ifinfo
@@ -3257,153 +3253,6 @@
 
 
 @c For the developer
address@hidden Version Control
address@hidden The inner workings of remote version control
address@hidden 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
address@hidden
-
-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.
-
address@hidden
-* 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.
address@hidden menu
-
-
address@hidden Version Controlled Files
address@hidden 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.
-
-
address@hidden Remote Commands
address@hidden 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
address@hidden 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
address@hidden 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.
-
-
address@hidden Changed workfiles
address@hidden 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.
-
-
address@hidden Checking out files
address@hidden 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.
-
-
address@hidden Miscellaneous Version Control
address@hidden Things related to Version Control that don't fit elsewhere
-
-Minor implementation details, &c.
-
address@hidden
-* Remote File Ownership::       How VC determines who owns a workfile.
-* Back-end Versions::           How VC determines what release your RCS is.
address@hidden menu
-
-
address@hidden Remote File Ownership
address@hidden How VC determines who owns a workfile
-
address@hidden 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.
-
-
address@hidden Back-end Versions
address@hidden 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 @@
 @ifset emacs
 @node External packages
 @section Integration with external Lisp packages.
address@hidden 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 @@
 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 address@hidden value.
 
 @lisp
 (let ((tramp-completion-mode t))
   ...)
 @end lisp
+
+
address@hidden 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
address@hidden knows that there are file attribute changes, it
+shall let-bind the variable @code{process-file-side-effects} to
address@hidden  @value{tramp} wouldn't flush the file attributes cache then.
+
address@hidden
+(let (process-file-side-effects)
+  ...)
address@hidden lisp
 @end ifset