[Emacs-diffs] master 0440c74: Add Quick Start Guide to Tramp manual

[Michael Albinus]

branch: master
commit 0440c748aaec9b8b32c8cb268f6e24e874fedc75
Author: Michael Albinus <address@hidden>
Commit: Michael Albinus <address@hidden>

    Add Quick Start Guide to Tramp manual
    
    * doc/misc/tramp.texi: Use consequently "@value{tramp}" and
    "MS Windows".
    (Quick Start Guide): New node.
    
    * doc/misc/trampver.texi:
    * lisp/net/trampver.el: Change version to "2.3.3-pre".
---
 doc/misc/tramp.texi    | 263 ++++++++++++++++++++++++++++++++++++++-----------
 doc/misc/trampver.texi |   2 +-
 lisp/net/trampver.el   |   6 +-
 3 files changed, 208 insertions(+), 63 deletions(-)

diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 6209e02..1b751a0 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -43,7 +43,7 @@ copy and modify this GNU manual.''
 @c Entries for @command{install-info} to use
 @dircategory Emacs network features
 @direntry
-* TRAMP: (tramp).               Transparent Remote Access, Multiple Protocol
+* @value{tramp}: (tramp).               Transparent Remote Access, Multiple 
Protocol
                                   Emacs remote file access via ssh and scp.
 @end direntry
 
@@ -77,8 +77,8 @@ You can find the latest version of this document on the web at
 @ifhtml
 The latest release of @value{tramp} is available for
 @uref{https://ftp.gnu.org/gnu/tramp/, download}, or you may see
address@hidden Tramp} for more details, including the Git server
-details.
address@hidden @value{tramp}} for more details, including the Git
+server details.
 
 @value{tramp} also has a @uref{https://savannah.gnu.org/projects/tramp/,
 Savannah Project Page}.
@@ -97,11 +97,12 @@ There is a mailing list for @value{tramp}, available at
 
 For the end user:
 
-* Obtaining Tramp::             How to obtain @value{tramp}.
+* Obtaining @value{tramp}::             How to obtain @value{tramp}.
 * History::                     History of @value{tramp}.
 @ifset installchapter
 * Installation::                Installing @value{tramp} with your Emacs.
 @end ifset
+* Quick Start Guide::           Short introduction how to use @value{tramp}.
 * Configuration::               Configuring @value{tramp} for use.
 * Usage::                       An overview of the operation of @value{tramp}.
 * Bug Reports::                 Reporting Bugs and Problems.
@@ -192,7 +193,7 @@ and related programs.  If these programs can successfully 
pass
 more secure alternative to @command{ftp} and other older access
 methods.
 
address@hidden on Windows operating systems is integrated with the
address@hidden on MS Windows operating systems is integrated with the
 PuTTY package, and uses the @command{plink} program.
 
 @value{tramp} mostly operates transparently in the background using
@@ -207,7 +208,7 @@ benefit of direct integration of @value{tramp} in Emacs.
 
 @value{tramp} can transfer files using any number of available host
 programs for remote files, such as @command{rcp}, @command{scp},
address@hidden or (under Windows) @command{pscp}.  @value{tramp}
address@hidden or (under MS Windows) @command{pscp}.  @value{tramp}
 provides easy ways to specify these programs and customize them to
 specific files, hosts, or access methods.
 
@@ -314,9 +315,9 @@ behind the scenes when you open a file with @value{tramp}.
 
 
 @c For the end user
address@hidden Obtaining Tramp
address@hidden Obtaining @value{tramp}
 @chapter Obtaining @value{tramp}
address@hidden obtaining Tramp
address@hidden obtaining @value{tramp}
 
 @value{tramp} is included as part of Emacs (since Emacs version 22.1).
 
@@ -354,7 +355,7 @@ From behind a firewall:
 @end example
 
 @noindent
-Tramp developers:
address@hidden developers:
 
 @example
 ] @strong{git clone login@@git.sv.gnu.org:/srv/git/tramp.git}
@@ -403,7 +404,7 @@ July 2002, @value{tramp} unified file names with Ange 
address@hidden  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
-started in February 2009.  Remote commands on Windows hosts since
+started in February 2009.  Remote commands on MS Windows hosts since
 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}.
@@ -418,6 +419,147 @@ XEmacs support was stopped in January 2016.  Since March 
2017,
 @end ifset
 
 
address@hidden Quick Start Guide
address@hidden Short introduction how to use @value{tramp}
address@hidden quick start guide
+
address@hidden extends the Emacs file name syntax by a remote
+component.  A remote file name looks always like
address@hidden@trampfn{method,user@@host,/path/to/file}}.
+
+You can use remote files exactly like ordinary files, that means you
+could open a file or directory by @kbd{C-x C-f
address@hidden,user@@host,/path/to/file} @key{RET}}, edit the file,
+and save it.  You can also mix local files and remote files in file
+operations with two arguments, like @code{copy-file} or
address@hidden  And finally, you can run even processes on a
+remote host, when the buffer you call the process from has a remote
address@hidden
+
+
address@hidden Start Guide: File name syntax}
address@hidden File name syntax
address@hidden file name syntax
+
+Remote file names are prepended by the @code{method}, @code{user} and
address@hidden parts.  All of them, and also the local file name part,
+are optional, in case of a missing part a default value is assumed.
+The default value for an empty local file name part is the remote
+user's home directory.  The shortest remote file name is
address@hidden@trampfn{-,,}}, therefore.  The @samp{-} notation for the
+default host is used for syntactical reasons, @ref{Default Host}.
+
+The @code{method} part describes the connection method used to reach
+the remote host, see below.
+
+The @code{user} part is the user name for accessing the remote host.
+For the @option{smb} method, this could also require a domain name, in
+this case it is written as @code{user%domain}.
+
+The @code{host} part must be a host name which could be resolved on
+your local host.  It could be a short host name, a fully qualified
+domain name, an IPv4 or IPv6 address, @ref{File name syntax}.  Some
+connection methods support also a notation of the port to be used, in
+this case it is written as @code{host#port}.
+
+
address@hidden Start Guide: @option{ssh} and @option{plink} methods}
address@hidden Using @option{ssh} and @option{plink}
address@hidden method ssh
address@hidden ssh method
address@hidden method plink
address@hidden plink method
+
+If your local host runs an SSH client, and the remote host runs an SSH
+server, the most simple remote file name is
address@hidden@trampfn{ssh,user@@host,/path/to/file}}.  The remote file name
address@hidden@trampfn{ssh,,}} opens a remote connection to yourself on the
+local host, and is taken often for testing @value{tramp}.
+
+On MS Windows, PuTTY is often used as SSH client.  Its @command{plink}
+method can be used there to open a connection to a remote host running
+an @command{ssh} server:
address@hidden@trampfn{plink,user@@host,/path/to/file}}.
+
+
address@hidden Start Guide: @option{su}, @option{sudo} and @option{sg} methods}
address@hidden Using @option{su}, @option{sudo} and @option{sg}
address@hidden method su
address@hidden su method
address@hidden method sudo
address@hidden sudo method
address@hidden method sg
address@hidden sg method
+
+Sometimes, it is necessary to work on your local host under different
+permissions.  For this, you could use the @option{su} or @option{sudo}
+connection method.  Both methods use @samp{root} as default user name
+and the return value of @code{(system-name)} as default host name.
+Therefore, it is convenient to open a file as
address@hidden@trampfn{sudo,,/path/to/file}}.
+
+The method @option{sg} stands for ``switch group''; the changed group
+must be used here as user name.  The default host name is the same.
+
+
address@hidden Start Guide: @option{smb} method}
address@hidden Using @command{smbclient}
address@hidden method smb
address@hidden smb method
address@hidden ms windows (with smb method)
address@hidden smbclient
+
+In order to access a remote MS Windows host or Samba server, the
address@hidden client is used.  The remote file name syntax is
address@hidden@trampfn{smb,user%domain@@host,/path/to/file}}.  The first part
+of the local file name is the share exported by the remote host,
address@hidden in this example.
+
+
address@hidden Start Guide: GVFS-based methods}
address@hidden Using GVFS-based methods
address@hidden methods, gvfs
address@hidden gvfs based methods
address@hidden method sftp
address@hidden sftp method
address@hidden method afp
address@hidden afp method
address@hidden method dav
address@hidden method davs
address@hidden dav method
address@hidden davs method
+
+On systems, which have installed the virtual file system for the Gnome
+Desktop (GVFS), its offered methods could be used by @value{tramp}.
+Examples are @address@hidden,user@@host,/path/to/file}},
address@hidden@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP
+file system), @address@hidden,user@@host,/path/to/file}} and
address@hidden@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares).
+
+
address@hidden Start Guide: Google Drive}
address@hidden Using Google Drive
address@hidden method gdrive
address@hidden gdrive method
address@hidden google drive
+
+Another GVFS-based method allows to access a Google Drive file system.
+The file name syntax is here always
address@hidden@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}.
address@hidden@@gmail.com} stands here for your Google Drive account.
+
+
address@hidden Start Guide: Android}
address@hidden Using Android
address@hidden method adb
address@hidden adb method
address@hidden android
+
+An Android device, which is connected via USB to your local host, can
+be accessed via the @command{adb} command.  No user or host name is
+needed.  The file name syntax is @address@hidden,,/path/to/file}}.
+
+
 @node Configuration
 @chapter Configuring @value{tramp}
 @cindex configuration
@@ -610,16 +752,16 @@ continue connecting?''.  @value{tramp} cannot handle such 
questions.
 Connections will have to be setup where logins can proceed without
 such questions.
 
address@hidden is useful for Windows users when @command{ssh} triggers
-an error about allocating a pseudo tty.  This happens due to missing
-shell prompts that confuses @value{tramp}.
address@hidden is useful for MS Windows users when @command{ssh}
+triggers an error about allocating a pseudo tty.  This happens due to
+missing shell prompts that confuses @value{tramp}.
 
 @option{sshx} supports the @samp{-p} argument.
 
 @item @option{krlogin}
 @cindex method krlogin
 @cindex krlogin method
address@hidden Kerberos (with krlogin method)
address@hidden kerberos (with krlogin method)
 
 This method is also similar to @option{ssh}.  It uses the
 @command{krlogin -x} command only for remote host login.
@@ -627,7 +769,7 @@ This method is also similar to @option{ssh}.  It uses the
 @item @option{ksu}
 @cindex method ksu
 @cindex ksu method
address@hidden Kerberos (with ksu method)
address@hidden kerberos (with ksu method)
 
 This is another method from the Kerberos suite.  It behaves like @option{su}.
 
@@ -635,7 +777,7 @@ This is another method from the Kerberos suite.  It behaves 
like @option{su}.
 @cindex method plink
 @cindex plink method
 
address@hidden method is for Windows users with the PuTTY
address@hidden method is for MS Windows users with the PuTTY
 implementation of address@hidden  It uses @samp{plink -ssh} to log in to the
 remote host.
 
@@ -648,9 +790,9 @@ session.
 @cindex method plinkx
 @cindex plinkx method
 
-Another method using PuTTY on Windows with session names instead of
-host names.  @option{plinkx} calls @samp{plink -load @var{session} -t}.
-User names and port numbers must be defined in the session.
+Another method using PuTTY on MS Windows with session names instead of
+host names.  @option{plinkx} calls @samp{plink -load @var{session}
+-t}.  User names and port numbers must be defined in the session.
 
 Check the @samp{Share SSH connections if possible} control for that
 session.
@@ -730,9 +872,9 @@ This method supports the @samp{-p} argument.
 in performance to @option{scp}.  @option{scpx} uses @samp{ssh -t -t
 @var{host} -l @var{user} /bin/sh} to open a connection.
 
address@hidden is useful for Windows users when @command{ssh} triggers
-an error about allocating a pseudo tty.  This happens due to missing
-shell prompts that confuses @value{tramp}.
address@hidden is useful for MS Windows users when @command{ssh}
+triggers an error about allocating a pseudo tty.  This happens due to
+missing shell prompts that confuses @value{tramp}.
 
 This method supports the @samp{-p} argument.
 
@@ -742,17 +884,17 @@ This method supports the @samp{-p} argument.
 @cindex pscp method
 @cindex pscp (with pscp method)
 @cindex plink (with pscp method)
address@hidden PuTTY (with pscp method)
address@hidden putty (with pscp method)
 @cindex method psftp
 @cindex psftp method
 @cindex pscp (with psftp method)
 @cindex plink (with psftp method)
address@hidden PuTTY (with psftp method)
address@hidden putty (with psftp method)
 
 These methods are similar to @option{scp} or @option{sftp}, but they
 use the @command{plink} command to connect to the remote host, and
 they use @command{pscp} or @command{psftp} for transferring the files.
-These programs are part of PuTTY, an SSH implementation for Windows.
+These programs are part of PuTTY, an SSH implementation for MS Windows.
 
 Check the @samp{Share SSH connections if possible} control for that
 session.
@@ -805,6 +947,8 @@ capable of servicing requests from @value{tramp}.
 @item @option{smb}
 @cindex method smb
 @cindex smb method
address@hidden ms windows (with smb method)
address@hidden smbclient
 
 This non-native @value{tramp} method connects via the Server Message
 Block (SMB) networking protocol to hosts running file servers that are
@@ -831,15 +975,16 @@ handling}.
 
 To accommodate user name/domain name syntax required by MS Windows
 authorization, @value{tramp} provides for an extended syntax in
address@hidden format (where user is user name, @code{%} is the
-percent symbol, and domain is the windows domain name).  An example:
address@hidden format (where @code{user} is the user name,
address@hidden is the percent symbol, and @code{domain} is the MS Windows
+domain name).  An example:
 
 @example
 @trampfn{smb,daniel%BIZARRE@@melancholia,/daniel$$/.emacs}
 @end example
 
 where user @code{daniel} connects as a domain user to the SMB host
address@hidden in the windows domain @code{BIZARRE} to edit
address@hidden in the MS Windows domain @code{BIZARRE} to edit
 @file{.emacs} located in the home directory (share @code{daniel$}).
 
 Alternatively, for local WINS users (as opposed to domain users),
@@ -876,6 +1021,7 @@ can.
 @item @option{adb}
 @cindex method adb
 @cindex adb method
address@hidden android (with adb method)
 
 This method uses Android Debug Bridge program for accessing Android
 devices.  The Android Debug Bridge must be installed locally for
@@ -949,7 +1095,7 @@ but with SSL encryption.  Both methods support the port 
numbers.
 @item @option{gdrive}
 @cindex method gdrive
 @cindex gdrive method
address@hidden Google Drive
address@hidden google drive
 
 Via the @option{gdrive} method it is possible to access your Google
 Drive online storage.  User and host name of the remote file name are
@@ -981,8 +1127,8 @@ that for security reasons refuse @command{ssh} connections.
 @cindex method synce
 @cindex synce method
 
address@hidden method allows connecting to Windows Mobile devices.  It
-uses GVFS for mounting remote files and directories via FUSE and
address@hidden method allows connecting to MS Windows Mobile devices.
+It uses GVFS for mounting remote files and directories via FUSE and
 requires the SYNCE-GVFS plugin.
 
 @end table
@@ -1070,7 +1216,7 @@ access and it has the most reasonable security protocols, 
use
 @end example
 
 If @option{ssh} is unavailable for whatever reason, look for other
-obvious options.  For Windows, try the @option{plink} method.  For
+obvious options.  For MS Windows, try the @option{plink} method.  For
 Kerberos, try @option{krlogin}.
 
 For editing local files as @option{su} or @option{sudo} methods, try
@@ -1289,8 +1435,8 @@ restricted shell:
 
 @node Firewalls
 @section Passing firewalls
address@hidden HTTP tunnel
address@hidden proxy hosts, HTTP tunnel
address@hidden http tunnel
address@hidden proxy hosts, http tunnel
 
 Sometimes, it is not possible to reach a remote host directly.  A
 firewall might be in the way, which could be passed via a proxy
@@ -1746,8 +1892,8 @@ Similar localization may be necessary for handling wrong 
password
 prompts, for which @value{tramp} uses @option{tramp-wrong-passwd-regexp}.
 
 @item @command{tset} and other questions
address@hidden Unix command tset
address@hidden tset Unix command
address@hidden unix command tset
address@hidden tset unix command
 @vindex tramp-terminal-type
 
 To suppress inappropriate prompts for terminal type, @value{tramp}
@@ -1847,7 +1993,7 @@ Then re-set the prompt string in 
@file{~/.emacs_SHELLNAME} as follows:
 
 @example
 @group
-# Reset the prompt for remote Tramp shells.
+# Reset the prompt for remote @value{tramp} shells.
 if [ "address@hidden/*tramp*/address@hidden" == "tramp" ] ; then
    PS1="[\u@@\h \w]$ "
 fi
@@ -1859,8 +2005,8 @@ fi
 @end ifinfo
 
 @item @command{busybox} / @command{nc}
address@hidden Unix command nc
address@hidden nc Unix command
address@hidden unix command nc
address@hidden nc unix command
 
 @value{tramp}'s @option{nc} method uses the @command{nc} command to
 install and execute a listener as follows (see @code{tramp-methods}):
@@ -1891,7 +2037,7 @@ where @samp{192.168.0.1} is the remote host IP address
 
 @node Android shell setup
 @section Android shell setup hints
address@hidden android shell setup
address@hidden android shell setup for ssh
 
 @value{tramp} uses the @option{adb} method to access Android devices.
 Android devices provide a restricted shell access through an USB
@@ -2072,12 +2218,12 @@ to direct all auto saves to that location.
 
 @node Windows setup hints
 @section Issues with Cygwin ssh
address@hidden Cygwin, issues
address@hidden cygwin, issues
 
 This section is incomplete.  Please share your solutions.
 
address@hidden method sshx with Cygwin
address@hidden sshx method with Cygwin
address@hidden method sshx with cygwin
address@hidden sshx method with cygwin
 
 Cygwin's @command{ssh} works only with a Cygwin version of Emacs.  To
 check for compatibility: type @kbd{M-x eshell}, and start @kbd{ssh
@@ -2091,34 +2237,34 @@ Some older versions of Cygwin's @command{ssh} work with 
the
 @option{sshx} access method.  Consult Cygwin's FAQ at
 @uref{https://cygwin.com/faq/} for details.
 
address@hidden Cygwin and fakecygpty
address@hidden fakecygpty and Cygwin
address@hidden cygwin and fakecygpty
address@hidden fakecygpty and cygwin
 
 On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs
 Wiki} it is explained how to use the helper program @code{fakecygpty}
 to fix this problem.
 
address@hidden method scpx with Cygwin
address@hidden scpx method with Cygwin
address@hidden method scpx with cygwin
address@hidden scpx method with cygwin
 
 When using the @option{scpx} access method, Emacs may call
address@hidden with Windows file naming, such as @code{c:/foo}.  But
address@hidden with MS Windows file naming, such as @code{c:/foo}.  But
 the version of @command{scp} that is installed with Cygwin does not
-know about Windows file naming, which causes it to incorrectly look
+know about MS Windows file naming, which causes it to incorrectly look
 for a host named @code{c}.
 
 A workaround: write a wrapper script for @option{scp} to convert
 Windows file names to Cygwin file names.
 
address@hidden Cygwin and ssh-agent
address@hidden SSH_AUTH_SOCK and Emacs on Windows
address@hidden cygwin and ssh-agent
address@hidden SSH_AUTH_SOCK and emacs on ms windows
 
-When using the @command{ssh-agent} on Windows for password-less
+When using the @command{ssh-agent} on MS Windows for password-less
 interaction, @option{ssh} methods depend on the environment variable
 @env{SSH_AUTH_SOCK}.  But this variable is not set when Emacs is
 started from a Desktop shortcut and authentication fails.
 
-One workaround is to use a Windows based SSH Agent, such as
+One workaround is to use an MS Windows based SSH Agent, such as
 Pageant.  It is part of the Putty Suite of tools.
 
 The fallback is to start Emacs from a shell.
@@ -2716,11 +2862,11 @@ Arguments of the program to be debugged must be 
literal, can take
 relative or absolute paths, but not remote paths.
 
 
address@hidden Running remote processes on Windows hosts
address@hidden Running remote processes on MS Windows hosts
 @cindex winexe
 @cindex powershell
 
address@hidden runs processes on a remote Windows host, and
address@hidden runs processes on a remote MS Windows host, and
 @value{tramp} can use it for @code{process-file} and
 @code{start-file-process}.
 
@@ -2730,7 +2876,7 @@ processes triggered from @value{tramp}.
 
 @option{explicit-shell-file-name} and @option{explicit-*-args} have to
 be set properly so @kbd{M-x shell} can open a proper remote shell on a
-Windows host.  To open @command{cmd}, set it as follows:
+MS Windows host.  To open @command{cmd}, set it as follows:
 
 @lisp
 @group
@@ -3283,7 +3429,7 @@ Redefine another key sequence in Emacs for @kbd{C-x C-f}:
    (interactive)
    (find-file
     (read-file-name
-     "Find Tramp file: "
+     "Find @value{tramp} file: "
      "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))))
 @end group
 @end lisp
@@ -3353,7 +3499,7 @@ The minibuffer expands for further editing.
 
 @item Use bookmarks:
 
-Use bookmarks to save Tramp file names.
+Use bookmarks to save @value{tramp} file names.
 @ifinfo
 @pxref{Bookmarks, , , emacs}.
 @end ifinfo
@@ -3736,4 +3882,3 @@ strings from being written to @file{*trace-output*}.
 @c * Explain how tramp.el works in principle: open a shell on a remote
 @c   host and then send commands to it.
 @c * Consistent small or capitalized words especially in menus.
address@hidden * Make a unique declaration of @trampfn.
diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi
index 05b577d..5d9dcc5 100644
--- a/doc/misc/trampver.texi
+++ b/doc/misc/trampver.texi
@@ -8,7 +8,7 @@
 @c In the Tramp GIT, 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.
address@hidden trampver 2.3.2
address@hidden trampver 2.3.3-pre
 
 @c Other flags from configuration
 @set instprefix /usr/local
diff --git a/lisp/net/trampver.el b/lisp/net/trampver.el
index 4be487e..527630d 100644
--- a/lisp/net/trampver.el
+++ b/lisp/net/trampver.el
@@ -7,7 +7,7 @@
 ;; Maintainer: Michael Albinus <address@hidden>
 ;; Keywords: comm, processes
 ;; Package: tramp
-;; Version: 2.3.2
+;; Version: 2.3.3-pre
 
 ;; This file is part of GNU Emacs.
 
@@ -33,7 +33,7 @@
 ;; should be changed only there.
 
 ;;;###tramp-autoload
-(defconst tramp-version "2.3.2"
+(defconst tramp-version "2.3.3-pre"
   "This version of Tramp.")
 
 ;;;###tramp-autoload
@@ -55,7 +55,7 @@
 ;; Check for Emacs version.
 (let ((x (if (>= emacs-major-version 24)
     "ok"
-  (format "Tramp 2.3.2 is not fit for %s"
+  (format "Tramp 2.3.3-pre is not fit for %s"
          (when (string-match "^.*$" (emacs-version))
            (match-string 0 (emacs-version)))))))
   (unless (string-match "\\`ok\\'" x) (error "%s" x)))