[Emacs-diffs] Changes to emacs/man/tramp.texi

[Kai Großjohann]

Index: emacs/man/tramp.texi
diff -c emacs/man/tramp.texi:1.18 emacs/man/tramp.texi:1.19
*** emacs/man/tramp.texi:1.18   Fri Feb 28 13:29:33 2003
--- emacs/man/tramp.texi        Sat Mar 29 10:16:57 2003
***************
*** 8,19 ****
  @c This is *so* much nicer :)
  @footnotestyle end
  
! @c In the Tramp CVS, the version number is auto-frobbed from the
! @c Makefile, so you should edit the top-level Makefile to change
! @c the version number.
! @macro trampver{}
! 2.0.30
! @end macro
  
  @c Entries for @command{install-info} to use
  @dircategory Emacs
--- 8,17 ----
  @c This is *so* much nicer :)
  @footnotestyle end
  
! @c In the Tramp CVS, the version number is auto-frobbed from
! @c configure.ac, so you should edit that file and run
! @c "autoconf && ./configure" to change the version number.
! @include trampver.texi
  
  @c Entries for @command{install-info} to use
  @dircategory Emacs
***************
*** 27,41 ****
  @sc{tramp}
  @end macro
  
- @c Distinguish between GNU Emacs and XEmacs.  Derived from the
- @c Makefile variable $(EMACS-ID).  Valid values are `emacs' and `xemacs'.
- @set emacs
- 
  @c Some flags which make the text independent on the (X)Emacs flavor.
  @c GNU Emacs values.
  @ifset emacs
! @set emacs-name               Emacs
  @set emacs-dir                emacs
  @set ftp-package-name         Ange-FTP
  @set tramp-prefix             /
  @set tramp-prefix-single-hop
--- 25,40 ----
  @sc{tramp}
  @end macro
  
  @c Some flags which make the text independent on the (X)Emacs flavor.
+ @c "emacs" resp "xemacs" are set in the Makefile.
+ 
  @c GNU Emacs values.
  @ifset emacs
! @set emacs-name               GNU Emacs
  @set emacs-dir                emacs
+ @set emacs-other-name         XEmacs
+ @set emacs-other-dir          xemacs
+ @set emacs-other-file-name    tramp-xemacs.html
  @set ftp-package-name         Ange-FTP
  @set tramp-prefix             /
  @set tramp-prefix-single-hop
***************
*** 48,53 ****
--- 47,55 ----
  @ifset xemacs
  @set emacs-name               XEmacs
  @set emacs-dir                xemacs
+ @set emacs-other-name         GNU Emacs
+ @set emacs-other-dir          emacs
+ @set emacs-other-file-name    tramp-emacs.html
  @set ftp-package-name         EFS
  @set tramp-prefix             /[
  @set tramp-prefix-single-hop  [
***************
*** 122,127 ****
--- 124,139 ----
  You can find the latest version of this document on the web at
  @uref{http://www.freesoftware.fsf.org/tramp/}.
  
+ The manual has been generated for @value{emacs-name}.
+ @ifinfo
+ If you want to read the info pages for @value{emacs-other-name}, you
+ should read in @ref{Installation} how to create them.
+ @end ifinfo
+ @ifhtml
+ If you're using the other Emacs flavour, you should read the
+ @address@hidden, @value{emacs-other-name}} pages.
+ @end ifhtml
+ 
  @ifhtml
  This manual is also available as a @uref{tramp_ja.html, Japanese
  translation}.
***************
*** 176,181 ****
--- 188,194 ----
  * Remote Programs::             How @tramp{} finds and uses programs on the 
remote machine.
  * Remote shell setup::          Remote shell setup hints.
  * Windows setup hints::         Issues with Cygwin ssh.
+ * Auto-save and Backup::        Auto-save and Backup.
  
  Using @tramp
  
***************
*** 199,205 ****
  
  How file names, directories and localnames are mangled and managed.
  
! * Localname deconstruction::         Breaking a localname into its components.
  
  @end detailmenu
  @end menu
--- 212,218 ----
  
  How file names, directories and localnames are mangled and managed.
  
! * Localname deconstruction::    Breaking a localname into its components.
  
  @end detailmenu
  @end menu
***************
*** 368,390 ****
  @chapter Obtaining @tramp{}.
  @cindex obtaining Tramp
  
! @tramp{} is freely available on the Internet and the latest release may be
! downloaded from
! @uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz}. This
! release includes the full documentation and code for @tramp{}, suitable
! for installation.  But Emacs (21.4 or later) includes @tramp{}
! already, and there is a @tramp{} package for XEmacs, as well.  So
! maybe it is easier to just use those.  But if you want the bleeding
  edge, read address@hidden
  
! For the especially brave, @tramp{} is available from CVS.  The CVS version
! is the latest version of the code and may contain incomplete features or
! new issues. Use these versions at your own risk.
  
  Instructions for obtaining the latest development version of @tramp{}
  from CVS can be found by going to the Savannah project page at the
! following URL and then clicking on the CVS link in the navigation bar at
! the top.
  
  @noindent
  @uref{http://savannah.gnu.org/projects/tramp/}
--- 381,403 ----
  @chapter Obtaining @tramp{}.
  @cindex obtaining Tramp
  
! @tramp{} is freely available on the Internet and the latest release
! may be downloaded from
! @uref{http://savannah.nongnu.org/download/tramp/}. This
! release includes the full documentation and code for @tramp{},
! suitable for installation.  But Emacs (21.4 or later) includes
! @tramp{} already, and there is a @tramp{} package for XEmacs, as well.
! So maybe it is easier to just use those.  But if you want the bleeding
  edge, read address@hidden
  
! For the especially brave, @tramp{} is available from CVS.  The CVS
! version is the latest version of the code and may contain incomplete
! features or new issues. Use these versions at your own risk.
  
  Instructions for obtaining the latest development version of @tramp{}
  from CVS can be found by going to the Savannah project page at the
! following URL and then clicking on the CVS link in the navigation bar
! at the top.
  
  @noindent
  @uref{http://savannah.gnu.org/projects/tramp/}
***************
*** 404,418 ****
  @end example
  
  @noindent
! You should now have a directory @file{~/@value{emacs-dir}/tramp} containing 
the latest
! version of @tramp{}. You can fetch the latest updates from the repository
! by issuing the command:
  
  @example
  ] @strong{cd ~/@value{emacs-dir}/tramp}
  ] @strong{cvs update -d}
  @end example
  
  
  @node History
  @chapter History of @tramp{}
--- 417,441 ----
  @end example
  
  @noindent
! You should now have a directory @file{~/@value{emacs-dir}/tramp}
! containing the latest version of @tramp{}. You can fetch the latest
! updates from the repository by issuing the command:
  
  @example
  ] @strong{cd ~/@value{emacs-dir}/tramp}
  ] @strong{cvs update -d}
  @end example
  
+ @noindent
+ Once you've got updated files from the CVS repository, you need to run
+ @command{autoconf} in order to get an up-to-date @file{configure}
+ script:
+ 
+ @example
+ ] @strong{cd ~/@value{emacs-dir}/tramp}
+ ] @strong{autoconf}
+ @end example
+ 
  
  @node History
  @chapter History of @tramp{}
***************
*** 442,474 ****
  to rebuilding your machine from scratch. ;)
  
  Seriously though, the installation should be a fairly simple matter.
- 
  The easiest way to proceed is as follows:
  
  @itemize @bullet
  @item
  Choose a directory, say @file{~/@value{emacs-dir}/}.  Change into that
  directory and unpack the tarball.  This will give you a directory
! @file{~/@value{emacs-dir}/tramp/} which contains subdirectories
! @file{lisp} for the Lisp code and @file{texi} for the documentation.
! 
! @item
! Optionally byte-compile all files in the Lisp directory,
! @file{~/@value{emacs-dir}/tramp/lisp/}, by issuing a command like the
! following from the top level directory
! @file{~/@value{emacs-dir}/tramp/}:
  
  @example
! make address@hidden all
  @end example
  
! If there are missing libraries reported it is likely they are provided
! in the @file{~/@value{emacs-dir}/tramp/contrib/} directory.  This
! case, you need to call @command{make} like this:
  
! @example
! make address@hidden USE_CONTRIB=1 all
! @end example
  
  @item
  NOTE: If you run into problems running the example @command{make}
--- 465,504 ----
  to rebuilding your machine from scratch. ;)
  
  Seriously though, the installation should be a fairly simple matter.
  The easiest way to proceed is as follows:
  
  @itemize @bullet
  @item
  Choose a directory, say @file{~/@value{emacs-dir}/}.  Change into that
  directory and unpack the tarball.  This will give you a directory
! @file{~/@value{emacs-dir}/address@hidden/} which contains
! subdirectories @file{lisp} for the Lisp code and @file{texi} for the
! documentation.  Make a symbolic link:
  
  @example
! ln -s address@hidden tramp
  @end example
  
! @item
! @command{cd} to @file{~/@value{emacs-dir}/tramp/} and type
! @command{./configure} to configure Tramp for your system.
! 
! Running `configure' takes awhile.  While running, it prints some
! messages telling which features it is checking for.
  
! @item
! Type @command{make} to build the byte-compiled Lisp files as well as
! the Info manual.
! 
! @item
! Type @command{make install} to install the Tramp Lisp files and Info
! manual.
! 
! @item
! You can remove the byte-compiled Lisp files and the Info manual from
! the source directory by typing @command{make clean}.  To also remove
! the files that @command{configure} created, type @command{make
! distclean}.
  
  @item
  NOTE: If you run into problems running the example @command{make}
***************
*** 480,490 ****
  Something similar can be done to create the info manual.  Just change
  to directory @file{~/@value{emacs-dir}/tramp/texi} and load the
  @file{tramp.texi} file in @value{emacs-name}.  Then press @kbd{M-x
! texinfo-format-buffer @key{RET}} to generate @file{tramp.info}.
  
! @item
! Tell @value{emacs-name} about the new Lisp directory and the
! @tramp{} package with the following lines in @file{~/.emacs}:
  
  @lisp
  (add-to-list 'load-path "~/@value{emacs-dir}/tramp/lisp/")
--- 510,595 ----
  Something similar can be done to create the info manual.  Just change
  to directory @file{~/@value{emacs-dir}/tramp/texi} and load the
  @file{tramp.texi} file in @value{emacs-name}.  Then press @kbd{M-x
! texinfo-format-buffer @key{RET}} to generate
! @file{~/@value{emacs-dir}/tramp/info/tramp}.
! @end itemize
  
! @menu
! * Installation parameters::     Parameters in order to control installation.
! * Load paths::                  How to plug-in @tramp{} into your environment.
! @end menu
! 
! @node Installation parameters
! @section Parameters in order to control installation.
! @cindex installation
! 
! By default, @command{make install} will install @tramp{}'s files in
! @address@hidden and @address@hidden  You can specify an
! installation prefix other than @address@hidden by giving
! @command{configure} the option @command{--prefix=PATH}.
! 
! If your installed copy of Emacs is named something other than
! @address@hidden, you will need to tell `make' where to find it so
! that it can correctly byte-compile the @tramp{} sources.
! 
! For example, to force the use of @value{emacs-other-name} you might do
! this:
! 
! @example
! ./configure address@hidden
! make
! make install
! @end example
! 
! or this:
! 
! @example
! ./configure
! make EMACS=/usr/bin/@value{emacs-other-dir}-21.4
! make install
! @end example
! 
! The syntax of @tramp{} file names is different for @value{emacs-name}
! and @value{emacs-other-name}.  The Info manual will be generated for
! the Emacs flavor choosen in the @command{configure} phase. If you want
! the Info manual for the other version, you need to set the variable
! @command{EMACS_INFO} to @command{make}:
! 
! @example
! ./configure address@hidden
! make address@hidden
! @end example
! 
! Also, the @command{--prefix=PATH} option to @command{configure} may
! not be general enough to set the paths you want.  If not, you can pass
! variables to the @command{make} command to control the installation.
! For a complete list of tweakable variables, look in the makefile.
! 
! For example, to put the Lisp files in @file{~/elisp} and the Info file
! in @file{~/info}, you would type:
! 
! @example
! ./configure
! make
! make lispdir=~/elisp infodir=~/info install
! @end example
! 
! @tramp{} has some packages in its @file{contrib} directory which are
! missing in older Emacsen.  If you want to use them, you must use the
! @command{USE_CONTRIB} environment variable:
! 
! @example
! make USE_CONTRIB=1
! make USE_CONTRIB=1 install
! @end example
! 
! @node Load paths
! @section How to plug-in @tramp{} into your environment.
! @cindex installation
! 
! If you don't install @tramp{} into the intended directories, but prefer
! to use from the source directory, you need to add the following lines
! into your @file{.emacs}:
  
  @lisp
  (add-to-list 'load-path "~/@value{emacs-dir}/tramp/lisp/")
***************
*** 492,513 ****
  (require 'tramp)
  @end lisp
  
! The second @command{add-to-list} must be used only if you've compiled
! with the @command{USE_CONTRIB} parameter.
  
- @item
  To be able to read the Info documentation, create a file
! @file{~/@value{emacs-dir}/tramp/texi/dir} using the
  @command{install-info} command, and add the directory to the search
  path for Info.
  
  NOTE:
  On systems using the @cite{gnu} version of @command{install-info}, the
  @command{install-info} syntax is very direct and simple.  One can
! change to directory @file{~/@value{emacs-dir}/tramp/texi} and type:
  
  @example
! install-info tramp.info dir
  @end example
  
  and a @file{dir} file will be created with the @tramp{}
--- 597,629 ----
  (require 'tramp)
  @end lisp
  
! The second load-path must be used only if you've applied the
! @command{USE_CONTRIB} parameter.
! 
! @ifset xemacs
! NOTE: For @value{emacs-name}, the package @file{fsf-compat} must be
! installed.  For details on package installation, see @ref{Packages, ,
! ,xemacs}.
! @ifhtml
! (If the previous link doesn't work, try the @value{emacs-name}
! documentation at
! @uref{http://www.xemacs.org/Documentation/packageGuide.html,the
! @value{emacs-name} site}.)
! @end ifhtml
! @end ifset
  
  To be able to read the Info documentation, create a file
! @file{~/@value{emacs-dir}/tramp/info/dir} using the
  @command{install-info} command, and add the directory to the search
  path for Info.
  
  NOTE:
  On systems using the @cite{gnu} version of @command{install-info}, the
  @command{install-info} syntax is very direct and simple.  One can
! change to directory @file{~/@value{emacs-dir}/tramp/info} and type:
  
  @example
! install-info tramp dir
  @end example
  
  and a @file{dir} file will be created with the @tramp{}
***************
*** 522,568 ****
  @value{emacs-name} at @file{/usr/info/dir}.  Copy the top of this file
  down to the first occurrence of @code{* Menu} including that line plus
  one more blank line, to your working directory
! @file{~/@value{emacs-dir}/tramp/texi}, or use the sample
  @file{~/@value{emacs-dir}/tramp/texi/dir_sample}.
  
  Once a @file{dir} file is in place, this command will make the entry:
  
  @example
! install-info --infodir=. tramp.info
  @end example
  
  If you want it in a specific category see @kbd{man install-info} for
  further details.
  
  If the environment variable @env{INFOPATH} is set, add the directory
! @file{~/@value{emacs-dir}/tramp/texi/} to it.  Else, add the directory to
  @ifset emacs
  @code{Info-default-directory-list}, as follows:
  
  @lisp
! (add-to-list 'Info-default-directory-list "~/@value{emacs-dir}/tramp/texi/")
  @end lisp
  @end ifset
  @ifset xemacs
  @code{Info-directory-list}, as follows:
  @lisp
! (add-to-list 'Info-directory-list "~/@value{emacs-dir}/tramp/texi/")
  @end lisp
  @end ifset
  
- @end itemize
- 
- @ifset xemacs
- For @value{emacs-name}, the package @file{fsf-compat} must be installed.
- For details on package installation, see @ref{Packages, , ,xemacs}.
- @ifhtml
- (If the previous link doesn't work, try the @value{emacs-name}
- documentation at
- @uref{http://www.xemacs.org/Documentation/packageGuide.html,the
- @value{emacs-name} site}.)
- @end ifhtml
- @end ifset
- 
  @node Configuration
  @chapter Configuring @tramp{} for use
  @cindex configuration
--- 638,671 ----
  @value{emacs-name} at @file{/usr/info/dir}.  Copy the top of this file
  down to the first occurrence of @code{* Menu} including that line plus
  one more blank line, to your working directory
! @file{~/@value{emacs-dir}/tramp/info}, or use the sample
  @file{~/@value{emacs-dir}/tramp/texi/dir_sample}.
  
  Once a @file{dir} file is in place, this command will make the entry:
  
  @example
! install-info --infodir=. tramp
  @end example
  
  If you want it in a specific category see @kbd{man install-info} for
  further details.
  
  If the environment variable @env{INFOPATH} is set, add the directory
! @file{~/@value{emacs-dir}/tramp/info/} to it.  Else, add the directory to
  @ifset emacs
  @code{Info-default-directory-list}, as follows:
  
  @lisp
! (add-to-list 'Info-default-directory-list "~/@value{emacs-dir}/tramp/info/")
  @end lisp
  @end ifset
  @ifset xemacs
  @code{Info-directory-list}, as follows:
  @lisp
! (add-to-list 'Info-directory-list "~/@value{emacs-dir}/tramp/info/")
  @end lisp
  @end ifset
  
  @node Configuration
  @chapter Configuring @tramp{} for use
  @cindex configuration
***************
*** 596,601 ****
--- 699,705 ----
  * Remote Programs::             How @tramp{} finds and uses programs on the 
remote machine.
  * Remote shell setup::          Remote shell setup hints.
  * Windows setup hints::         Issues with Cygwin ssh.
+ * Auto-save and Backup::        Auto-save and Backup.
  @end menu
  
  
***************
*** 1419,1424 ****
--- 1523,1560 ----
  @end table
  
  
+ @node Auto-save and Backup
+ @section Auto-save and Backup configuration
+ @cindex auto-save
+ @cindex backup
+ @vindex backup-directory-alist
+ 
+ Explaining auto-save is still to do.
+ 
+ Normally, Emacs writes backup files to the same directory as the
+ original files, but this behavior can be changed via the variable
+ @code{backup-directory-alist}.  In connection with @tramp{}, this can
+ have unexpected side effects.  Suppose that you specify that all backups
+ should go to the directory @file{~/.emacs.d/backups/}, and then you edit
+ the file @file{/su:root@@localhost:/etc/secretfile}.  The effect is that
+ the backup file will be owned by you and not by root, thus possibly
+ enabling others to see it even if they were not intended to see it.
+ 
+ When @code{backup-directory-alist} is nil (the default), such problems
+ 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
+ effectively `turns off' the effect of @code{backup-directory-alist} for
+ @tramp{} files:
+ 
+ @lisp
+ (require 'tramp)
+ (add-to-list 'backup-directory-alist
+              (cons tramp-file-name-regexp nil))
+ @end lisp
+ 
+ 
  @node Windows setup hints
  @section Issues with Cygwin ssh
  @cindex Cygwin, issues
***************
*** 1730,1736 ****
  @tramp{} is available under the URL below.
  
  @noindent
! @uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz}
  
  @noindent
  There is also a Savannah project page.
--- 1866,1872 ----
  @tramp{} is available under the URL below.
  
  @noindent
! @uref{http://savannah.nongnu.org/download/tramp/}
  
  @noindent
  There is also a Savannah project page.