Merge remote-tracking branch 'origin/master' into feature/package-autosuggest

11 files changed, 225 insertions, 63 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 7663e2b21df..d79bcf3fe0f 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1615,24 +1615,30 @@ your preference, such as @code{ws-butler-mode}.
 @cindex per-connection local variables
 
   Most of the variables reflect the situation on the local machine.
-Often, they must use a different value when you operate in buffers
-with a remote default directory.  Think about the behavior when
-calling @code{shell} -- on your local machine, you might use
-@file{/bin/bash} and rely on termcap, but on a remote machine, it may
-be @file{/bin/ksh} and terminfo.
-
-  This can be accomplished with @dfn{connection-local variables}.
-Directory and file local variables override connection-local
-variables.  Unsafe connection-local variables are handled in the same
-way as unsafe file-local variables (@pxref{Safe File Variables}).
+Often, they must use a different value when you operate in buffers with
+a remote default directory.  Think about the behavior when calling
+@code{shell} --- on your local machine, you might use @file{/bin/bash}
+and rely on termcap, but on a remote machine, it may be @file{/bin/ksh}
+and terminfo.
+
+  This can be accomplished with @dfn{connection-local variables}.  Such
+variables are declared depending on the value of
+@code{default-directory} of the current buffer.  When a buffer has a
+remote @code{default-directory}, and there exist a connection-local
+variable which matches @code{default-directory}, this alternative value
+of the variable is used.  Directory and file local variables override
+connection-local variables.  Unsafe connection-local variables are
+handled in the same way as unsafe file-local variables (@pxref{Safe File
+Variables}).
 
 @findex connection-local-set-profile-variables
 @findex connection-local-set-profiles
-  Connection-local variables are declared as a group of
-variables/value pairs in a @dfn{profile}, using the
+  Connection-local variables are declared as a group of variables/value
+pairs in a @dfn{profile}, using the
 @code{connection-local-set-profile-variables} function.  The function
-@code{connection-local-set-profiles} activates profiles for a given
-criteria, identifying a remote machine:
+@code{connection-local-set-profiles} declares profiles for a given
+criteria (the first argument), identifying a remote machine with respect
+to @code{default-directory} of the current buffer:
 
 @example
 (connection-local-set-profile-variables 'remote-terminfo
@@ -1654,12 +1660,46 @@ criteria, identifying a remote machine:
 
   This code declares three different profiles, @code{remote-terminfo},
 @code{remote-ksh}, and @code{remote-bash}.  The profiles
-@code{remote-terminfo} and @code{remote-ksh} are applied to all
-buffers which have a remote default directory matching the regexp
-@code{"remotemachine"} as host name.  Such a criteria can also
-discriminate for the properties @code{:protocol} (this is the Tramp
-method) or @code{:user} (a remote user name).  The @code{nil} criteria
-matches all buffers with a remote default directory.
+@code{remote-terminfo} and @code{remote-ksh} are applied to all buffers
+which have a remote @code{default-directory} matching the string
+@code{"remotemachine"} as host name.
+
+  Criteria, the first argument of @code{connection-local-set-profiles},
+specifies, how the profiles match @code{default-directory}.  It is a
+plist identifying a connection and the application using this
+connection.  Property names might be @code{:application},
+@code{:protocol}, @code{:user} and @code{:machine}.  The property value
+of @code{:application} is a symbol, all other property values are
+strings.  In general the symbol @code{tramp} should be used as
+@code{:application} value.  Some packages use a different
+@code{:application} (for example @code{eshell} or @code{vc-git}); they
+say it in their documentation then.  All properties are optional.
+
+  The other properties are used for checking @code{default-directory}.
+The propertiy @code{:protocol} is used for the method a remote
+@code{default-directory} uses, the property
+@code{:user} is the remote user name, and the property @code{:machine}
+is the remote host name.  All checks are performed via
+@code{string-equal}.  The @code{nil} criteria matches all buffers
+with a remote default directory.
+
+  Connection-local variables are not activated by default.  A package
+which uses connection-local variables must activate them for a given
+buffer, specifying for which @code{:application} it uses them.
+@xref{Applying Connection Local Variables,,, elisp, The Emacs Lisp
+Reference Manual}, for details.
+
+  After the above definition of profiles and their activation, any
+connection made by Tramp to the @samp{remotemachine} system will use
+
+@itemize
+@item @code{t} as the connection-specific value of @code{system-uses-terminfo},
+@item @samp{dumb-emacs-ansi} as the connection-specific value of
+@code{comint-terminfo-terminal},
+@item @samp{/bin/ksh} as the connection-specific value of as
+@code{shell-file-name},
+@item @samp{-c} as the connection-specific value of @code{shell-command-switch}.
+@end itemize
 
   Be careful when declaring different profiles with the same variable,
 and setting these profiles to criteria which could match in parallel.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 567c1492518..a9bcee0b060 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1835,7 +1835,8 @@ the start of the @var{n}th previous file.
 
 @findex diff-hunk-kill
 @item M-k
-Kill the hunk at point (@code{diff-hunk-kill}).
+Kill the hunk at point (@code{diff-hunk-kill}).  If the region is
+active, kills all hunks the region overlaps.
 
 @findex diff-file-kill
 @item M-K
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index f1090d4b43f..aebe31b478e 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1712,6 +1712,9 @@ Do an incremental regular expression search on the fileset
 Apart from acting on multiple files, these commands behave much like
 their single-buffer counterparts (@pxref{Search}).
 
+@c Outstanding changes commands under 'T' are not mentioned because
+@c these are an advanced feature documented only in vc1-xtra.texi.
+
   The VC Directory buffer additionally defines some branch-related
 commands starting with the prefix @kbd{b}:
 
diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi
index 8ffd6506dbe..2bb695025db 100644
--- a/doc/emacs/vc1-xtra.texi
+++ b/doc/emacs/vc1-xtra.texi
@@ -298,22 +298,31 @@ yet merged into the target branch.
 @cindex outstanding changes
 
 @table @kbd
-@item C-x v o =
+@item C-x v T =
 Display diffs of changes to the VC fileset since the merge base of this
 branch and its upstream counterpart (@code{vc-diff-outgoing-base}).
 
-@item C-x v o D
-Display all changes since the merge base of this branch and its upstream
-counterpart (@code{vc-root-diff-outgoing-base}).
+@item C-x v T D
+Display a diff of all changes since the merge base of this branch and
+its upstream counterpart (@code{vc-root-diff-outgoing-base}).
+
+@item C-x v T l
+Display log messages for changes to the VC fileset since the merge base
+of this branch and its upstream counterpart
+(@code{vc-log-outgoing-base}).
+
+@item C-x v T L
+Display log messages for all changes since the merge base of this branch
+and its upstream counterpart (@code{vc-root-log-outgoing-base}).
 @end table
 
 For decentralized version control systems (@pxref{VCS Repositories}),
-these commands provide specialized versions of @kbd{C-x v M D} (see
-@pxref{Merge Bases}) which also take into account the state of upstream
-repositories.  These commands are useful both when working on a single
-branch and when developing features on a separate branch
-(@pxref{Branches}).  These two cases are conceptually distinct, and so
-we will introduce them separately.
+these commands provide specialized versions of @kbd{C-x v M L} and
+@w{@kbd{C-x v M D}} (see @pxref{Merge Bases}) which also take into
+account the state of upstream repositories.  These commands are useful
+both when working on a single branch and when developing features on a
+separate branch (@pxref{Branches}).  These two cases are conceptually
+distinct, and so we will introduce them separately.
 
 First, consider working on a single branch.  @dfn{Outstanding changes}
 are those which you haven't yet pushed upstream.  This includes both
@@ -321,17 +330,17 @@ unpushed commits and uncommitted changes in your working tree.  In many
 cases the reason these changes are not pushed yet is that they are not
 finished: the changes committed so far don't make sense in isolation.
 
-@kindex C-x v o =
+@kindex C-x v T =
 @findex vc-diff-outgoing-base
-@kindex C-x v o D
+@kindex C-x v T D
 @findex vc-root-diff-outgoing-base
-Type @kbd{C-x v o D} (@code{vc-root-diff-outgoing-base}) to display a
+Type @kbd{C-x v T D} (@code{vc-root-diff-outgoing-base}) to display a
 summary of all these changes, committed and uncommitted.  This summary
 is in the form of a diff of what committing and pushing (@pxref{Pulling
 / Pushing}) all these changes would do to the upstream repository.  You
-can use @kbd{C-x v o =} (@code{vc-diff-outgoing-base}) instead to limit
+can use @kbd{C-x v T =} (@code{vc-diff-outgoing-base}) instead to limit
 the display of changes to the current VC fileset.  (The difference
-between @w{@kbd{C-x v o D}} and @w{@kbd{C-x v o =}} is like the
+between @w{@kbd{C-x v T D}} and @w{@kbd{C-x v T =}} is like the
 difference between @kbd{C-x v D} and @kbd{C-x v =} (@pxref{Old
 Revisions}).)@footnote{Another point of comparison is that these
 commands are like @w{@kbd{C-x v O =}} (@code{vc-fileset-diff-outgoing})
@@ -340,6 +349,16 @@ include uncommitted changes in the reported diffs.  Like those other
 commands, you can use a prefix argument to specify a particular upstream
 location.}
 
+@kindex C-x v T l
+@findex vc-log-outgoing-base
+@kindex C-x v T L
+@findex vc-root-log-outgoing-base
+Type @kbd{C-x v T L} (@code{vc-root-log-outgoing-base}) to display a
+summary of the same changes in the form of a revision log; this does not
+include uncommitted changes.  You can use @kbd{C-x v T l}
+(@code{vc-log-outgoing-base}) instead to limit the display of changes to
+the current VC fileset.
+
 Second, consider developing a feature on a separate branch.  Call this
 the @dfn{topic branch},@footnote{What we mean by a topic branch is any
 shorter-lived branch used for work which will later be merged into a
@@ -359,13 +378,15 @@ upstream repository's development trunk.  That means committed changes
 on the topic branch that haven't yet been merged into the trunk, plus
 uncommitted changes.
 
-When the current branch is a topic branch and you type @kbd{C-x v o D},
+When the current branch is a topic branch and you type @kbd{C-x v T D},
 Emacs displays a summary of all the changes that are outstanding against
 the trunk to which the current branch will be merged.  This summary is
 in the form of a diff of what committing and pushing all the changes,
 @emph{and} subsequently merging the topic branch, would do to the trunk.
-As above, you can use @kbd{C-x v o =} instead to limit the display of
-changes to the current VC fileset.
+As above, you can use @kbd{C-x v T =} instead to limit the display of
+changes to the current VC fileset.  @kbd{C-x v T L} and @kbd{C-x v T l}
+show the corresponding revision logs, excluding uncommitted changes as
+above.
 
 This functionality relies on Emacs correctly detecting whether the
 current branch is a trunk or a topic branch, and in the latter case,
@@ -379,8 +400,8 @@ The variables @code{vc-trunk-branch-regexps} and
 @code{vc-topic-branch-regexps} contain lists of regular expressions
 matching the names of branches that should always be considered trunk
 and topic branches, respectively.  You can also specify prefix arguments
-to @kbd{C-x v o D} and @kbd{C-x v o =}.  Here is a summary of how to use
-these controls:
+to @kbd{C-x v T @dots{}}.  Here is a summary of how to use these
+controls:
 
 @enumerate
 @item
@@ -425,7 +446,7 @@ described.  E.g., if the value of @code{vc-trunk-branch-regexps} is
 branch.
 
 @item
-Supply a double prefix argument, i.e. @w{@kbd{C-u C-u C-x v o @dots{}}},
+Supply a double prefix argument, i.e. @w{@kbd{C-u C-u C-x v T @dots{}}},
 and Emacs will treat the current branch as a trunk, no matter what.
 This is useful when you simply want to obtain a diff of all outgoing
 changes (@pxref{VC Change Log}) plus uncommitted changes.
@@ -433,7 +454,7 @@ changes (@pxref{VC Change Log}) plus uncommitted changes.
 @item
 @cindex outgoing base, version control
 Finally, you can take full manual control by supplying a single prefix
-argument, i.e. @w{@kbd{C-u C-x v o @dots{}}}.  Emacs will prompt you for
+argument, i.e. @w{@kbd{C-u C-x v T @dots{}}}.  Emacs will prompt you for
 the @dfn{outgoing base}, which is the upstream location for which the
 changes are destined once they are no longer outstanding.
 
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 937ea386650..8500e3b7731 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -519,6 +519,8 @@ selected frame, and display the buffer in that new window.
 @vindex split-height-threshold
 @vindex split-width-threshold
 @vindex split-window-preferred-direction
+@cindex portrait frame
+@cindex landscape frame
 The split can be either vertical or horizontal, depending on the
 variables @code{split-height-threshold} and
 @code{split-width-threshold}.  These variables should have integer
@@ -528,8 +530,14 @@ window's height, the split puts the new window below.  Otherwise, if
 split puts the new window on the right.  If neither condition holds,
 Emacs tries to split so that the new window is below---but only if the
 window was not split before (to avoid excessive splitting).  Whether
-Emacs tries first to split vertically or horizontally, is
-determined by the value of @code{split-window-preferred-direction}.
+Emacs tries first to split vertically or horizontally when both
+conditions hold is determined by the value of
+@code{split-window-preferred-direction}.  Its default is @code{longest},
+which means to split vertically if the window's frame is taller than it
+is wide (a @dfn{portrait} frame), and split horizontally if its wider
+than it's tall (a @dfn{landscape} frame).  The values @code{vertical}
+and @code{horizontal} always prefer, respectively, the vertical or the
+horizontal split.
 
 @item
 Otherwise, display the buffer in a window previously showing it.
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index a4776030cf2..7c3f29c7226 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -2344,7 +2344,9 @@ the other usual filtering mechanisms say it should.  @xref{Error Debugging}.
 The macro @code{condition-case-unless-debug} provides another way to
 handle debugging of such forms.  It behaves exactly like
 @code{condition-case}, unless the variable @code{debug-on-error} is
-non-@code{nil}, in which case it does not handle any errors at all.
+non-@code{nil}, in which case it causes Emacs to enter the debugger
+before executing any applicable handler.  (The applicable handler, if
+any, will still run when the debugger exits.)
 @end defmac
 
   Once Emacs decides that a certain handler handles the error, it
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 4211b435db5..464c0badc36 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2243,6 +2243,9 @@ means hide the excess parts of @var{string} with a @code{display} text
 property (@pxref{Display Property}) showing the ellipsis, instead of
 actually truncating the string.
 
+See also the function @code{truncate-string-pixelwise} for pixel-level
+resolution.
+
 @example
 @group
 (truncate-string-to-width "\tab\t" 12 4)
@@ -2440,6 +2443,37 @@ non-@code{nil}, use any face remappings (@pxref{Face Remapping}) from
 that buffer when computing the width of @var{string}.
 @end defun
 
+@defun truncate-string-pixelwise string max-pixels &optional buffer ellipsis ellipsis-pixels
+This is a convenience function that uses @code{window-text-pixel-size}
+to truncate @var{string} to @var{max-pixels} pixels.  Caveat: if you
+call this function to measure the width of a string with embedded
+newlines, it will then return the width of the widest substring that
+does not include newlines.  The meaning of this result is the widest
+line taken by the string if inserted into a buffer.  If @var{buffer} is
+non-@code{nil}, use any face remappings (@pxref{Face Remapping}) from
+that buffer when computing the width of @var{string}.
+
+If @var{ellipsis} is non-@code{nil}, it should be a string which will
+replace the end of @var{string} when it is truncated.  In this case,
+more characters will be removed from @var{string} to free enough space
+for @var{ellipsis} to fit within @var{max-pixels} pixels.  However, if
+the pixel width of @var{string} is less than the pixel width of
+@var{ellipsis}, @var{ellipsis} will not be appended to the result.  If
+@var{ellipsis} is non-@code{nil} and not a string, it stands for the
+value returned by the function @code{truncate-string-ellipsis},
+described above.
+
+If @var{ellipsis-pixels} is non-@code{nil} and @var{ellipsis} is
+non-@code{nil}, it should be the number of pixels of @var{ellipsis} that
+you should precompute using @code{string-pixel-width}, specifying the
+same buffer.  This is useful to avoid the cost of recomputing this value
+repeatedly when you have many strings to truncate using the same
+ellipsis string.
+
+See also the function @code{truncate-string-to-width} for
+character-level resolution.
+@end defun
+
 @defun line-pixel-height
 This function returns the height in pixels of the line at point in the
 selected window.  The value includes the line spacing of the line
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 5bf0bfc8c10..bdd79528cac 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -109,6 +109,7 @@ must be a root frame, which means it cannot be a child frame itself
 descending from it.
 @end defun
 
+@cindex frame identifier
 @defun frame-id &optional frame
 This function returns the unique identifier of a frame, an integer,
 assigned to @var{frame}.  If @var{frame} is @code{nil} or unspecified,
@@ -3187,6 +3188,29 @@ could switch to a different terminal without switching back when
 you're done.
 @end deffn
 
+@deffn Command select-frame-by-id id &optional noerror
+This function searches open and undeletable frames for a matching frame
+identifier @var{id} (@pxref{Frames}).  If found, its frame is undeleted,
+if necessary, then raised, given focus, and made the selected frame.  On
+a text terminal, raising a frame causes it to occupy the entire terminal
+display.
+
+This function returns the selected frame or signals an error if @var{id}
+is not found, unless @var{noerror} is non-@code{nil}, in which case it
+returns @code{nil}.
+@end deffn
+
+@deffn Command undelete-frame-by-id id &optional noerror
+This function searches undeletable frames for a matching frame
+identifier @var{id} (@pxref{Frames}).  If found, its frame is undeleted,
+raised, given focus, and made the selected frame.  On a text terminal,
+raising a frame causes it to occupy the entire terminal display.
+
+This function returns the undeleted frame or signals an error if
+@var{id} is not found, unless @var{noerror} is non-@code{nil}, in which
+case it returns @code{nil}.
+@end deffn
+
 @cindex text-terminal focus notification
 Emacs cooperates with the window system by arranging to select frames
 as the server and window manager request.  When a window system
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 4de739aa915..afee255346c 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -1110,9 +1110,9 @@ instead of the default @code{equal}.
 @cindex sequences, intersection of
 @cindex intersection of sequences
   This function returns a copy of @var{sequence1} from which the
-elements that appear in @var{sequence2} where removed.  If the optional
-argument @var{function} is non-@code{nil}, it is a function of two
-arguments to use to compare elements instead of the default
+elements that do not appear in @var{sequence2} were removed.  If the
+optional argument @var{function} is non-@code{nil}, it is a function of
+two arguments to use to compare elements instead of the default
 @code{equal}.
 
 @example
@@ -1125,10 +1125,11 @@ arguments to use to compare elements instead of the default
 
 
 @defun seq-difference sequence1 sequence2 &optional function
-  This function returns a list of the elements that appear in
-@var{sequence1} but not in @var{sequence2}.  If the optional argument
-@var{function} is non-@code{nil}, it is a function of two arguments to
-use to compare elements instead of the default @code{equal}.
+  This function returns a copy of @var{sequence1} from which the
+elements that appear in @var{sequence2} were removed.  If the optional
+argument @var{function} is non-@code{nil}, it is a function of two
+arguments to use to compare elements instead of the default
+@code{equal}.
 
 @example
 @group
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 29a272eec92..2f5ee037f3e 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -2653,6 +2653,19 @@ This macro returns the connection-local value of @var{symbol} for
 
 If @var{symbol} does not have a connection-local
 binding, the value is the default binding of the variable.
+
+The difference to @code{with-connection-local@{-application@}-variables}
+is, that @code{symbol} is not set buffer-local.  A typical usage pattern
+is to use only the the connection value of a variable if it exists, and
+not to use its default value otherwise (using @code{my-app-variable}
+initialized above):
+
+@lisp
+(if (connection-local-p my-app-variable 'my-app)
+    (connection-local-value my-app-variable 'my-app)
+  ;; Something else.
+  )
+@end lisp
 @end defmac
 
 @defvar enable-connection-local-variables
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 169f15cc898..d804c34250f 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -4122,16 +4122,19 @@ window.  If @var{window} cannot be split, it returns @code{nil}.  If
 @var{window} is omitted or @code{nil}, it defaults to the selected
 window.
 
-This function obeys the usual rules that determine when a window may
-be split (@pxref{Splitting Windows}).  It first tries to split by
-placing the new window below, subject to the restriction imposed by
-@code{split-height-threshold} (see below), in addition to any other
-restrictions.  If that fails, it tries to split by placing the new
-window to the right, subject to @code{split-width-threshold} (see
-below).  If that also fails, and the window is the only window on its
-frame, this function again tries to split and place the new window
-below, disregarding @code{split-height-threshold}.  If this fails as
-well, this function gives up and returns @code{nil}.
+This function obeys the usual rules that determine when a window may be
+split (@pxref{Splitting Windows}).  It first tries either a vertical
+split by placing the new window below, subject to the restriction
+imposed by @code{split-height-threshold} (see below), or a horizontal
+split that places the new window to the right, subject to
+@code{split-width-threshold}, in addition to any other restrictions.
+Whether it tries first to split vertically or horizontally depends on
+the value of the user option @code{split-window-preferred-direction}.
+If splitting along the first dimension fails, it tries to split along
+the other dimension.  If that also fails, and the window is the only
+window on its frame, this function again tries to split and place the
+new window below, disregarding @code{split-height-threshold}.  If this
+fails as well, this function gives up and returns @code{nil}.
 @end defun
 
 @defopt split-height-threshold
@@ -4150,6 +4153,18 @@ window has at least that many columns.  If the value is @code{nil},
 that means not to split this way.
 @end defopt
 
+@defopt split-window-preferred-direction
+This variable determines the first dimension along which
+@code{split-window-sensibly} tries to split the window, if the window
+could be split both vertically and horizontally, as determined by the
+values of @code{split-height-threshold} and
+@code{split-width-threshold}.  The default value is @code{longest},
+which means to split vertically if the height of the window's frame is
+greater or equal to its width, and horizontally otherwise.  The values
+@code{vertical} and @code{horizontal} specify the direction in which to
+attempt the first split.
+@end defopt
+
 @defopt even-window-sizes
 This variable, if non-@code{nil}, causes @code{display-buffer} to even
 window sizes whenever it reuses an existing window, and that window is