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".

3 files changed, 208 insertions, 63 deletions

diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 6209e02ebc5..1b751a01db6 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
-@ref{Obtaining Tramp} for more details, including the Git server
-details.
+@ref{Obtaining @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.
 
-@value{tramp} on Windows operating systems is integrated with the
+@value{tramp} 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},
-@command{rsync} or (under Windows) @command{pscp}.  @value{tramp}
+@command{rsync} 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
-@node Obtaining Tramp
+@node Obtaining @value{tramp}
 @chapter Obtaining @value{tramp}
-@cindex obtaining Tramp
+@cindex 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:
+@value{tramp} 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 FTP@.  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
 
 
+@node Quick Start Guide
+@chapter Short introduction how to use @value{tramp}
+@cindex quick start guide
+
+@value{tramp} extends the Emacs file name syntax by a remote
+component.  A remote file name looks always like
+@file{@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
+@trampfn{method,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
+@code{rename-file}.  And finally, you can run even processes on a
+remote host, when the buffer you call the process from has a remote
+@code{default-directory}.
+
+
+@anchor{Quick Start Guide: File name syntax}
+@section File name syntax
+@cindex file name syntax
+
+Remote file names are prepended by the @code{method}, @code{user} and
+@code{host} 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
+@file{@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}.
+
+
+@anchor{Quick Start Guide: @option{ssh} and @option{plink} methods}
+@section Using @option{ssh} and @option{plink}
+@cindex method ssh
+@cindex ssh method
+@cindex method plink
+@cindex 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
+@file{@trampfn{ssh,user@@host,/path/to/file}}.  The remote file name
+@file{@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:
+@file{@trampfn{plink,user@@host,/path/to/file}}.
+
+
+@anchor{Quick Start Guide: @option{su}, @option{sudo} and @option{sg} methods}
+@section Using @option{su}, @option{sudo} and @option{sg}
+@cindex method su
+@cindex su method
+@cindex method sudo
+@cindex sudo method
+@cindex method sg
+@cindex 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
+@file{@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.
+
+
+@anchor{Quick Start Guide: @option{smb} method}
+@section Using @command{smbclient}
+@cindex method smb
+@cindex smb method
+@cindex ms windows (with smb method)
+@cindex smbclient
+
+In order to access a remote MS Windows host or Samba server, the
+@command{smbclient} client is used.  The remote file name syntax is
+@file{@trampfn{smb,user%domain@@host,/path/to/file}}.  The first part
+of the local file name is the share exported by the remote host,
+@samp{path} in this example.
+
+
+@anchor{Quick Start Guide: GVFS-based methods}
+@section Using GVFS-based methods
+@cindex methods, gvfs
+@cindex gvfs based methods
+@cindex method sftp
+@cindex sftp method
+@cindex method afp
+@cindex afp method
+@cindex method dav
+@cindex method davs
+@cindex dav method
+@cindex 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 @file{@trampfn{sftp,user@@host,/path/to/file}},
+@file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP
+file system), @file{@trampfn{dav,user@@host,/path/to/file}} and
+@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares).
+
+
+@anchor{Quick Start Guide: Google Drive}
+@section Using Google Drive
+@cindex method gdrive
+@cindex gdrive method
+@cindex google drive
+
+Another GVFS-based method allows to access a Google Drive file system.
+The file name syntax is here always
+@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}.
+@samp{john.doe@@gmail.com} stands here for your Google Drive account.
+
+
+@anchor{Quick Start Guide: Android}
+@section Using Android
+@cindex method adb
+@cindex adb method
+@cindex 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 @file{@trampfn{adb,,/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.
 
-@option{sshx} 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}.
+@option{sshx} 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
-@cindex Kerberos (with krlogin method)
+@cindex 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
-@cindex Kerberos (with ksu method)
+@cindex 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
 
-@option{plink} method is for Windows users with the PuTTY
+@option{plink} method is for MS Windows users with the PuTTY
 implementation of SSH@.  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.
 
-@option{scpx} 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}.
+@option{scpx} 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)
-@cindex PuTTY (with pscp method)
+@cindex putty (with pscp method)
 @cindex method psftp
 @cindex psftp method
 @cindex pscp (with psftp method)
 @cindex plink (with psftp method)
-@cindex PuTTY (with psftp method)
+@cindex 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
+@cindex ms windows (with smb method)
+@cindex 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
-@code{user%domain} format (where user is user name, @code{%} is the
-percent symbol, and domain is the windows domain name).  An example:
+@code{user%domain} format (where @code{user} is the user name,
+@code{%} 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
-@code{melancholia} in the windows domain @code{BIZARRE} to edit
+@code{melancholia} 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
+@cindex 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
-@cindex Google Drive
+@cindex 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
 
-@option{synce} method allows connecting to Windows Mobile devices.  It
-uses GVFS for mounting remote files and directories via FUSE and
+@option{synce} 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
-@cindex HTTP tunnel
-@cindex proxy hosts, HTTP tunnel
+@cindex http tunnel
+@cindex 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
-@cindex Unix command tset
-@cindex tset Unix command
+@cindex unix command tset
+@cindex 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 [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then
    PS1="[\u@@\h \w]$ "
 fi
@@ -1859,8 +2005,8 @@ fi
 @end ifinfo
 
 @item @command{busybox} / @command{nc}
-@cindex Unix command nc
-@cindex nc Unix command
+@cindex unix command nc
+@cindex 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
-@cindex android shell setup
+@cindex 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
-@cindex Cygwin, issues
+@cindex cygwin, issues
 
 This section is incomplete.  Please share your solutions.
 
-@cindex method sshx with Cygwin
-@cindex sshx method with Cygwin
+@cindex method sshx with cygwin
+@cindex 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.
 
-@cindex Cygwin and fakecygpty
-@cindex fakecygpty and Cygwin
+@cindex cygwin and fakecygpty
+@cindex 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.
 
-@cindex method scpx with Cygwin
-@cindex scpx method with Cygwin
+@cindex method scpx with cygwin
+@cindex scpx method with cygwin
 
 When using the @option{scpx} access method, Emacs may call
-@command{scp} with Windows file naming, such as @code{c:/foo}.  But
+@command{scp} 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.
 
-@cindex Cygwin and ssh-agent
-@cindex SSH_AUTH_SOCK and Emacs on Windows
+@cindex cygwin and ssh-agent
+@cindex 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.
 
 
-@subsection Running remote processes on Windows hosts
+@subsection Running remote processes on MS Windows hosts
 @cindex winexe
 @cindex powershell
 
-@command{winexe} runs processes on a remote Windows host, and
+@command{winexe} 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.
-@c * Make a unique declaration of @trampfn.
diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi
index 05b577da005..5d9dcc5635d 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.
-@set trampver 2.3.2
+@set 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 4be487e1f4f..527630d747c 100644
--- a/lisp/net/trampver.el
+++ b/lisp/net/trampver.el
@@ -7,7 +7,7 @@
 ;; Maintainer: Michael Albinus <michael.albinus@gmx.de>
 ;; 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)))