master 228fd92: * doc/misc/tramp.texi: Grammar/style fixes

[Robert Pluim]

branch: master
commit 228fd92fb389eeaf2ec0bbca51da0569fce28ee7
Author: Robert Pluim <rpluim@gmail.com>
Commit: Robert Pluim <rpluim@gmail.com>

    * doc/misc/tramp.texi: Grammar/style fixes
    
    * doc/misc/tramp.texi (Overview):
    (Obtaining @value{tramp}):
    (Quick Start Guide):
    (Configuration):
    (Connection types):
    (Inline methods):
    (External methods):
    (Password handling):
    (Predefined connection information):
    (Remote shell setup):
    (Remote processes):
    (Frequently Asked Questions):
    (External packages):
    (Traces and Profiles): Grammar/style fixes.
---
 doc/misc/tramp.texi | 202 ++++++++++++++++++++++++++--------------------------
 1 file changed, 102 insertions(+), 100 deletions(-)

diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index e745af2..53f67b1 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -223,7 +223,7 @@ presented here to illustrate the steps involved:
 
 @kbd{C-x C-f} to initiate find-file, enter part of the @value{tramp}
 file name, then hit @kbd{@key{TAB}} for completion.  If this is the
-first time connection to that host, here's what happens:
+first time connecting to that host, here's what happens:
 
 @itemize
 @item
@@ -250,17 +250,17 @@ message.
 
 If @value{tramp} does not receive any messages within a timeout period
 (a minute, for example), then @value{tramp} responds with an error
-message about not finding the remote shell prompt.  If any messages
-from the remote host, @value{tramp} displays them in the buffer.
+message about not finding the remote shell prompt.  If there are any
+messages from the remote host, @value{tramp} displays them in the
+buffer.
 
 For any @samp{login failed} message from the remote host,
-@value{tramp} aborts the login attempt, and repeats the login steps
-again.
+@value{tramp} aborts the login attempt, and repeats the login steps.
 
 @item
-Upon successful login and @value{tramp} recognizes the shell prompt
+Upon successful login, if @value{tramp} recognizes the shell prompt
 from the remote host, @value{tramp} prepares the shell environment by
-turning off echoing, setting shell prompt, and other housekeeping
+turning off echoing, setting the shell prompt, and other housekeeping
 chores.
 
 @strong{Note} that for the remote shell, @value{tramp} invokes
@@ -282,8 +282,8 @@ contents from the remote host.
 
 For inline transfers, @value{tramp} sends a command, such as
 @samp{mimencode -b /path/to/remote/file}, waits until the output has
-accumulated in the buffer, decodes that output to produce the file's
-contents.
+accumulated in the buffer, then decodes that output to produce the
+file's contents.
 
 For external transfers, @value{tramp} sends a command as follows:
 @example
@@ -335,7 +335,7 @@ versions packaged with Emacs can be retrieved by
 @end lisp
 
 @value{tramp} is also available as @uref{https://elpa.gnu.org, GNU
-ELPA} package.  Besides the standalone releases, further minor version
+ELPA} package.  Besides the standalone releases, further minor versions
 of @value{tramp} will appear on GNU ELPA, until the next @value{tramp}
 release appears.  These minor versions have a four-number string, like
 ``2.4.5.1''.
@@ -345,7 +345,7 @@ Development versions contain new and incomplete features.  
The
 development version of @value{tramp} is always the version number of
 the next release, plus the suffix ``-pre'', like ``2.4.4-pre''.
 
-One way to obtain @value{tramp} from Git server is to visit the
+One way to obtain @value{tramp} from the Git server is to visit the
 Savannah project page at the following URL and then clicking on the
 Git link in the navigation bar at the top.
 
@@ -363,7 +363,7 @@ $ git clone git://git.savannah.gnu.org/tramp.git
 @end example
 
 @noindent
-From behind a firewall:
+From behind a proxy:
 
 @example
 @group
@@ -411,7 +411,7 @@ $ autoconf
 @end ifset
 @ifclear installchapter
 See the file @file{INSTALL} in that directory for further information
-how to install @value{tramp}.
+on how to install @value{tramp}.
 @end ifclear
 
 
@@ -419,16 +419,16 @@ how to install @value{tramp}.
 @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
+@value{tramp} extends the Emacs file name syntax by adding a remote
+component.  A remote file name always looks 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
+can 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
+@code{rename-file}.  And finally, you can even run processes on a
 remote host, when the buffer you call the process from has a remote
 @code{default-directory}.
 
@@ -437,26 +437,26 @@ remote host, when the buffer you call the process from 
has a remote
 @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 method is used for syntactical reasons, @ref{Default Method}.
+Remote file names have @code{method}, @code{user} and @code{host}
+parts prepended.  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 thus
+@file{@trampfn{-,,}}.  The @samp{-} notation for the default method is
+used for syntactical reasons, @ref{Default Method}.
 
 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}.
+which case it is written as @code{user%domain}.
 
-The @code{host} part must be a host name which could be resolved on
+The @code{host} part must be a host name which can 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}.
+connection methods also support a notation for the port to be used, in
+which case it is written as @code{host#port}.
 
 
 @anchor{Quick Start Guide: @option{ssh} and @option{plink} methods}
@@ -470,9 +470,9 @@ If your local host runs an SSH client, and the remote host 
runs an SSH
 server, the simplest 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}.
+local host, and is often used for testing @value{tramp}.
 
-On MS Windows, PuTTY is often used as SSH client.  Its @command{plink}
+On MS Windows, PuTTY is often used as the 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}}.
@@ -488,14 +488,14 @@ an @command{ssh} server:
 @cindex @option{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}
+permissions.  For this, you can 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.
+The method @option{sg} stands for ``switch group''; here the username
+is used as the group to change to.  The default host name is the same.
 
 
 @anchor{Quick Start Guide: @option{ssh}, @option{plink}, @option{su}, 
@option{sudo} and @option{sg} methods}
@@ -509,9 +509,9 @@ must be used here as user name.  The default host name is 
the same.
 @cindex method @option{sudo}
 @cindex @option{sudo} method
 
-If the @option{su} or @option{sudo} option shall be performed on
-another host, it could be comnbined with a leading @option{ssh} or
-@option{plink} option.  That means, @value{tramp} connects first to
+If the @option{su} or @option{sudo} option should be performed on
+another host, it can be comnbined with a leading @option{ssh} or
+@option{plink} option.  That means that @value{tramp} connects first to
 the other host with non-administrative credentials, and changes to
 administrative credentials on that host afterwards.  In a simple case,
 the syntax looks like
@@ -527,8 +527,8 @@ the syntax looks like
 The @option{sudoedit} method is similar to the @option{sudo} method.
 However, it is a different implementation: it does not keep an open
 session running in the background.  This is for security reasons; on
-the backside this method is less performant than the @option{sudo}
-method, it is restricted to the @samp{localhost} only, and it does not
+the backside this method has worse performance than the @option{sudo}
+method, it is restricted to @samp{localhost} only, and it does not
 support external processes.
 
 
@@ -561,9 +561,9 @@ of the local file name is the share exported by the remote 
host,
 @cindex method @option{mtp}
 @cindex @option{mtp} method
 
-On systems, which have installed @acronym{GVFS, the GNOME Virtual File
-System}, its offered methods could be used by @value{tramp}.  Examples
-are @file{@trampfn{sftp,user@@host,/path/to/file}},
+On systems which have @acronym{GVFS, the GNOME Virtual File System}
+installed , its offered methods can 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}},
 @file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares) and
@@ -580,10 +580,10 @@ file system), 
@file{@trampfn{dav,user@@host,/path/to/file}},
 @cindex @option{nextcloud} method
 @cindex nextcloud
 
-@acronym{GVFS}-based methods include also @acronym{GNOME} Online
+@acronym{GVFS}-based methods also include @acronym{GNOME} Online
 Accounts, which support the @option{Files} service.  These are the
 Google Drive file system, and the OwnCloud/NextCloud file system.  The
-file name syntax is here always
+file name syntax here is always
 @file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}
 (@samp{john.doe@@gmail.com} stands here for your Google Drive
 account), or @file{@trampfn{nextcloud,user@@host#8081,/path/to/file}}
@@ -608,7 +608,7 @@ needed.  The file name syntax is 
@file{@trampfn{adb,,/path/to/file}}.
 
 A convenient way to access system storages is the @command{rclone}
 program.  If you have configured a storage in @command{rclone} under a
-name @samp{storage} (for example), you could access it via the remote
+name @samp{storage} (for example), you can access it via the remote
 file name syntax @file{@trampfn{rclone,storage,/path/to/file}}.  User
 names are not needed.
 
@@ -630,7 +630,7 @@ For changing the connection type and file access method 
from the
 defaults to one of several other options, @xref{Connection types}.
 
 @strong{Note} that some user options described in these examples are
-not auto loaded by Emacs.  All examples require @value{tramp} is
+not auto loaded by Emacs.  All examples require @value{tramp} to be
 installed and loaded:
 
 @lisp
@@ -638,7 +638,7 @@ installed and loaded:
 @end lisp
 
 For functions used to configure @value{tramp}, the following clause
-might be used in your init file:
+may be used in your init file:
 
 @lisp
 (with-eval-after-load 'tramp (tramp-change-syntax 'simplified))
@@ -693,13 +693,13 @@ methods.  While these methods do see better performance 
when actually
 transferring files, the overhead of the cryptographic negotiation at
 startup may drown out the improvement in file transfer times.
 
-External methods should be configured such a way that they don't
-require a password (with @command{ssh-agent}, or such alike).  Modern
+External methods should be configured in such a way that they don't
+require a password (with @command{ssh-agent}, or similar).  Modern
 @command{scp} implementations offer options to reuse existing
-@command{ssh} connections, which will be enabled by default if
-available.  If it isn't possible, you should consider @ref{Password
-handling}, otherwise you will be prompted for a password every copy
-action.
+@command{ssh} connections, which @value{tramp} enables by default if
+available.  If that is not possible, you should consider @ref{Password
+handling}, otherwise you will be prompted for a password for every
+copy action.
 
 
 @node Inline methods
@@ -727,17 +727,17 @@ usability of one of the commands defined in
 reliable command it finds.  @value{tramp}'s search path can be
 customized, see @ref{Remote programs}.
 
-In case none of the commands are unavailable, @value{tramp} first
-transfers a small Perl program to the remote host, and then tries that
-program for encoding and decoding.
+In case none of the commands are available, @value{tramp} first
+transfers a small Perl program to the remote host, and then tries to
+use that program for encoding and decoding.
 
 @vindex tramp-inline-compress-start-size
 @vindex tramp-inline-compress-commands
-To increase transfer speeds for large text files, use compression
-before encoding.  The user option
-@code{tramp-inline-compress-start-size} specifies the file size for
-such optimization.  This feature depends on the availability and
-usability of one of the commands defined in
+To increase transfer speeds for large text files, @value{tramp} can
+use compression before encoding.  The user option
+@code{tramp-inline-compress-start-size} specifies the file size above
+which to use this optimization.  This feature depends on the
+availability and usability of one of the commands defined in
 @code{tramp-inline-compress-commands}.
 
 @table @asis
@@ -747,6 +747,8 @@ usability of one of the commands defined in
 
 @command{rsh} is an option for connecting to hosts within local
 networks since @command{rsh} is not as secure as other methods.
+There should be no reason to use it, as @command{ssh} is a both a
+complete replacement and ubiquitous.
 
 @item @option{ssh}
 @cindex method @option{ssh}
@@ -784,7 +786,7 @@ Similar to @option{su} method, @option{sudo} uses 
@command{sudo}.
 @command{sudo} must have sufficient rights to start a shell.
 
 For security reasons, a @option{sudo} connection is disabled after a
-predefined timeout (5 minutes per default).  This can be changed, see
+predefined timeout (5 minutes by default).  This can be changed, see
 @ref{Predefined connection information}.
 
 @item @option{doas}
@@ -1183,7 +1185,7 @@ information}.  Supported properties are @t{"mount-args"},
 @t{"copyto-args"} and @t{"moveto-args"}.
 
 Access via @option{rclone} is slow.  If you have an alternative method
-for accessing the system storage, you shall prefer this.
+for accessing the system storage, you should use it.
 @ref{GVFS-based methods} for example, methods @option{gdrive} and
 @option{nextcloud}.
 
@@ -1908,10 +1910,10 @@ machine melancholia#4711 port davs login daniel%BIZARRE 
password geheim
 @end example
 
 @vindex auth-source-save-behavior
-If there doesn't exist a proper entry, the password is read
+If no proper entry exists, the password is read
 interactively.  After successful login (verification of the password),
-it is offered to save a corresponding entry for further use by
-@code{auth-source} backends which support this.  This could be changed
+Emacs offers to save a corresponding entry for further use by
+@code{auth-source} backends which support this.  This can be changed
 by setting the user option @code{auth-source-save-behavior} to @code{nil}.
 
 @vindex auth-source-debug
@@ -2037,10 +2039,10 @@ properties are listed here:
 @itemize
 @item @t{"login-program"}
 
-The property @t{"login-program"} keeps the program to be called in
-order to connect the remote host.  Sometimes, the program might have
-another name on your host, or it is located on another path.  In this
-case, you can overwrite the default value, which is special for every
+The property @t{"login-program"} stores the program to be used to
+connect to the remote host.  Sometimes, the program might have another
+name on your host, or it might be located in another path.  In this case,
+you can overwrite the default value, which is special for every
 connection method.  It is used in all connection methods of
 @file{tramp-sh.el}.
 
@@ -2093,12 +2095,12 @@ Connections using the @option{smb} method check, 
whether the remote
 host supports posix commands.  If the remote host runs Samba, it
 confirms this capability.  However, some very old Samba versions have
 errors in their implementation.  In order to suppress the posix
-commands for those hosts, the property @t{"posix"} shall be set to
+commands for those hosts, the property @t{"posix"} should be set to
 @code{nil}.
 
 The default value of this property is @code{t} (not specified in
 @code{tramp-methods}).  If the remote host runs native MS Windows,
-there is no effect of this property.
+this propery has no effect.
 
 @item @t{"mount-args"}@*
 @t{"copyto-args"}@*
@@ -2207,7 +2209,7 @@ be recomputed.  To force @value{tramp} to recompute 
afresh, call
 @subsection Changing the default remote or local shell
 @cindex zsh setup
 
-Per default, @value{tramp} uses the command @command{/bin/sh} for
+By default, @value{tramp} uses the command @command{/bin/sh} for
 starting a shell on the remote host.  This can be changed by setting
 the connection property @t{"remote-shell"}; see @pxref{Predefined
 connection information}.  If you want, for example, use
@@ -2232,7 +2234,7 @@ This approach has also the advantage, that settings in
 trouble with the shell prompt due to set zle options will be avoided.
 
 Similar problems can happen with the local shell Tramp uses to create
-a process.  Per default, it uses the command @command{/bin/sh} for
+a process.  By default, it uses the command @command{/bin/sh} for
 this, which could also be a link to another shell.  In order to
 overwrite this, you might apply
 
@@ -2332,7 +2334,7 @@ prompts, for which @value{tramp} uses 
@code{tramp-wrong-passwd-regexp}.
 
 @value{tramp} uses the user option @code{tramp-terminal-type} to set
 the remote environment variable @env{TERM} for the shells it runs.
-Per default, it is @t{"dumb"}, but this could be changed.  A dumb
+By default, it is @t{"dumb"}, but this could be changed.  A dumb
 terminal is best suited to run the background sessions of
 @value{tramp}.  However, running interactive remote shells might
 require a different setting.  This could be achieved by tweaking the
@@ -3216,19 +3218,19 @@ host when the variable @code{default-directory} is 
remote:
 @end lisp
 
 @vindex process-file-return-signal-string
-@code{process-file} shall return either the exit code of the process,
-or a string describing the signal, when the process has been
-interrupted.  Since it cannot be determined reliably whether a remote
-process has been interrupted, @code{process-file} returns always the
-exit code.  When the user option
+For a local process, @code{process-file} returns either the exit code
+of the process, or a string describing a signal, when the process has
+been interrupted.  Since it cannot be determined reliably whether a
+remote process has been interrupted, @code{process-file} will always
+returns the exit code for it.  When the user option
 @code{process-file-return-signal-string} is non-@code{nil},
-@code{process-file} regards all exit codes greater than 128 as an
+@code{process-file} treats all exit codes greater than 128 as an
 indication that the process has been interrupted, and returns a
-respective string.
+corresponding string.
 
-Remote processes do not apply to @acronym{GVFS} (see @ref{GVFS-based
-methods}) because the remote file system is mounted on the local host
-and @value{tramp} just accesses by changing the
+This remote process handling does not apply to @acronym{GVFS} (see
+@ref{GVFS-based methods}) because the remote file system is mounted on
+the local host and @value{tramp} accesses it by changing the
 @code{default-directory}.
 
 @value{tramp} starts a remote process when a command is executed in a
@@ -3239,7 +3241,7 @@ integrated to work with @value{tramp}: @file{shell.el},
 
 @vindex INSIDE_EMACS@r{, environment variable}
 @value{tramp} always modifies the @env{INSIDE_EMACS} environment
-variable for remote processes.  Per default, this environment variable
+variable for remote processes.  By default, this environment variable
 shows the Emacs version.  @value{tramp} adds its own version string,
 so it looks like @samp{27.2,tramp:2.4.5.1}.  However, other packages
 might also add their name to this environment variable, like
@@ -3294,8 +3296,8 @@ local @file{.emacs} file:
 
 @vindex ENV@r{, environment variable}
 Setting the @env{ENV} environment variable instructs some shells to
-read an initialization file.  Per default, @value{tramp} has disabled
-this.  You could overwrite this behavior by evaluating
+read an initialization file.  By default, @value{tramp} disables
+this.  You can override this behavior by evaluating
 
 @lisp
 @group
@@ -4385,7 +4387,7 @@ this @code{nil} setting:
 
 @vindex ProxyCommand@r{, ssh option}
 @vindex ProxyJump@r{, ssh option}
-This shall also be set to @code{nil} if you use the
+This should also be set to @code{nil} if you use the
 @option{ProxyCommand} or @option{ProxyJump} options in your
 @command{ssh} configuration.
 
@@ -4955,9 +4957,9 @@ I get an error @samp{Remote file error: Forbidden 
reentrant call of Tramp}
 Timers, process filters and sentinels, and other event based functions
 can run at any time, when a remote file operation is still running.
 This can cause @value{tramp} to block.  When such a situation is
-detected, this error is triggered.  It shall be fixed in the
-respective function (an error report will help), but for the time
-being you can suppress this error by the following code in your
+detected, this error is triggered.  It should be fixed in the
+respective function (sending an error report will help), but for the
+time being you can suppress this error by the following code in your
 @file{~/.emacs}:
 
 @lisp
@@ -5140,9 +5142,9 @@ sending a string to a process, or waiting for process 
output.  They
 can run any remote file operation, which would conflict with the
 already running remote file operation, if the same connection is
 affected.  @value{tramp} detects this situation, and raises the
-@code{remote-file-error} error.  A timer function shall avoid this
-situation.  At least, it shall protect itself against this error, by
-wrapping the timer function body with
+@code{remote-file-error} error.  A timer function should avoid this
+situation.  As a minimum, it should protect itself against this error, by
+wrapping the timer function body as follows:
 
 @lisp
 @group
@@ -5194,8 +5196,8 @@ Other navigation keys are described in
 @ref{Outline Visibility, , , emacs}.
 @end ifinfo
 
-@value{tramp} handles errors internally.  But to get a Lisp backtrace,
-both the error and the signal have to be set as follows:
+@value{tramp} handles errors internally.  Hence, to get a Lisp backtrace,
+the following settings are required:
 
 @lisp
 @group
@@ -5209,15 +5211,15 @@ backtraces are also added to the @value{tramp} debug 
buffer in case of
 errors.
 
 In very rare cases it could happen, that @value{tramp} blocks Emacs.
-Killing Emacs does not allow to inspect the debug buffer.  In that
-case, you might instruct @value{tramp} to mirror the debug buffer to
-file:
+Killing Emacs does not allow inspecting the debug buffer.  In that
+case, you can instruct @value{tramp} to mirror the debug buffer to
+a file:
 
 @lisp
 (customize-set-variable 'tramp-debug-to-file t)
 @end lisp
 
-The debug buffer is written as file in your
+The debug buffer is written as a file in your
 @code{temporary-file-directory}, which is usually @file{/tmp/}.  Use
 this option with care, because it could decrease the performance of
 @value{tramp} actions.