Merge from origin/emacs-26

a5da653 * src/editfns.c (Fnarrow_to_region): Doc fix.  (Bug#35163)
646d33d Fix doc strings of 'vc-version-diff' and 'vc-version-ediff'
a30a6c3 Improve documentation of set-window-start
92ce2dd Improve documentation of window parameters
6dc42c5 Improve commentary in frame.el
a8cffcf Fix typo in a doc string
9e79f19 (emacs-26) ; * src/fontset.c (set-fontset-font): Use uppercas...

# Conflicts:
#	lisp/vc/vc.el

7 files changed, 99 insertions, 57 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 6b716323357..32e8c2afa31 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1951,7 +1951,13 @@ The optional argument @var{all-frames} has the same meaning as in
 @code{next-window}.
 
 This function does not select a window that has a non-@code{nil}
-@code{no-other-window} window parameter (@pxref{Window Parameters}).
+@code{no-other-window} window parameter (@pxref{Window Parameters}),
+provided that @code{ignore-window-parameters} is @code{nil}.
+
+If the @code{other-window} parameter of the selected window is a
+function, and @code{ignore-window-parameters} is @code{nil}, that
+function will be called with the arguments @var{count} and
+@var{all-frames} instead of the normal operation of this function.
 @end deffn
 
 @defun walk-windows fun &optional minibuf all-frames
@@ -3936,8 +3942,33 @@ described next to deal with the window and its buffer.
 This function handles @var{window} and its buffer after quitting.  The
 optional argument @var{window} must be a live window and defaults to
 the selected one. The function's behavior is determined by the four
-elements of the @code{quit-restore} window parameter (@pxref{Window
-Parameters}), which is set to @code{nil} afterwards.
+elements of the list specified by the @code{quit-restore} window
+parameter (@pxref{Window Parameters}), which is set to @code{nil}
+afterwards.
+
+The first element of the @code{quit-restore} parameter is one of the
+symbols @code{window}, meaning that the window has been specially
+created by @code{display-buffer}; @code{frame}, a separate frame has
+been created; @code{same}, the window has only ever displayed this
+buffer; or @code{other}, the window showed another buffer before.
+@code{frame} and @code{window} affect how the window is quit, while
+@code{same} and @code{other} affect the redisplay of buffers
+previously shown in this window.
+
+The second element is either one of the symbols @code{window} or
+@code{frame}, or a list whose elements are the buffer shown in the
+window before, that buffer's window start and window point positions,
+and the window's height at that time.  If that buffer is still live
+when the window is quit, then the function @code{quit-restore-window}
+reuses the window to display the buffer.
+
+The third element is the window selected at the time the parameter was
+created.  If @code{quit-restore-window} deletes the window passed to
+it as argument, it then tries to reselect this window.
+
+The fourth element is the buffer whose display caused the creation of
+this parameter.  @code{quit-restore-window} deletes the specified window
+only if it still shows that buffer.
 
 The window is deleted entirely if: 1) the first element of the
 @code{quit-restore} parameter is one of 'window or 'frame, 2) the
@@ -4627,13 +4658,14 @@ This function sets the display-start position of @var{window} to
 @var{position} in @var{window}'s buffer.  It returns @var{position}.
 
 The display routines insist that the position of point be visible when a
-buffer is displayed.  Normally, they change the display-start position
-(that is, scroll the window) whenever necessary to make point visible.
-However, if you specify the start position with this function using
-@code{nil} for @var{noforce}, it means you want display to start at
-@var{position} even if that would put the location of point off the
-screen.  If this does place point off screen, the display routines move
-point to the left margin on the middle line in the window.
+buffer is displayed.  Normally, they select the display-start position
+according to their internal logic (and scroll the window if necessary)
+to make point visible.  However, if you specify the start position
+with this function using @code{nil} for @var{noforce}, it means you
+want display to start at @var{position} even if that would put the
+location of point off the screen.  If this does place point off
+screen, the display routines attempt to move point to the left margin
+on the middle line in the window.
 
 For example, if point @w{is 1} and you set the start of the window
 @w{to 37}, the start of the next line, point will be above the top
@@ -4680,6 +4712,13 @@ it is still 1 when redisplay occurs.  Here is an example:
 @end group
 @end example
 
+If the attempt to make point visible (i.e., in a fully-visible screen
+line) fails, the display routines will disregard the requested
+window-start position and compute a new one anyway.  Thus, for
+reliable results Lisp programs that call this function should always
+move point to be inside the window whose display starts at
+@var{position}.
+
 If @var{noforce} is non-@code{nil}, and @var{position} would place point
 off screen at the next redisplay, then redisplay computes a new window-start
 position that works well with point, and thus @var{position} is not used.
@@ -5796,8 +5835,8 @@ and heights, if possible.  Frames are not resized by this function.
 @section Window Parameters
 @cindex window parameters
 
-This section describes how window parameters can be used to associate
-additional information with windows.
+This section describes the window parameters that can be used to
+associate additional information with windows.
 
 @defun window-parameter window parameter
 This function returns @var{window}'s value for @var{parameter}.  The
@@ -5930,44 +5969,21 @@ parameter is installed and updated by the function
 @vindex quit-restore@r{, a window parameter}
 This parameter is installed by the buffer display functions
 (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
-(@pxref{Quitting Windows}).  It contains four elements:
-
-The first element is one of the symbols @code{window}, meaning that
-the window has been specially created by @code{display-buffer};
-@code{frame}, a separate frame has been created; @code{same}, the
-window has only ever displayed this buffer; or @code{other}, the
-window showed another buffer before.  @code{frame} and @code{window}
-affect how the window is quit, while @code{same} and @code{other}
-affect the redisplay of buffers previously shown in this window.
+(@pxref{Quitting Windows}).  It is a list of four elements, see the
+description of @code{quit-restore-window} in @ref{Quitting Windows}
+for details.
 
-The second element is either one of the symbols @code{window} or
-@code{frame}, or a list whose elements are the buffer shown in the
-window before, that buffer's window start and window point positions,
-and the window's height at that time.  If that buffer is still live
-when the window is quit, then the function @code{quit-restore-window}
-reuses the window to display the buffer.
-
-The third element is the window selected at the time the parameter was
-created.  If @code{quit-restore-window} deletes the window passed to
-it as argument, it then tries to reselect this window.
-
-The fourth element is the buffer whose display caused the creation of
-this parameter.  @code{quit-restore-window} deletes the specified window
-only if it still shows that buffer.
-
-See the description of @code{quit-restore-window} in @ref{Quitting
-Windows} for details.
-
-@item window-side window-slot
+@item window-side
+@itemx window-slot
 @vindex window-side@r{, a window parameter}
 @vindex window-slot@r{, a window parameter}
-These parameters are used for implementing side windows (@pxref{Side
-Windows}).
+These parameters are used internally for implementing side windows
+(@pxref{Side Windows}).
 
 @item window-atom
 @vindex window-atom@r{, a window parameter}
-This parameter is used for implementing atomic windows, see @ref{Atomic
-Windows}.
+This parameter is used internally for implementing atomic windows, see
+@ref{Atomic Windows}.
 
 @item mode-line-format
 @vindex mode-line-format@r{, a window parameter}
@@ -5989,11 +6005,12 @@ affected.
 
 @item min-margins
 @vindex min-margins@r{, a window parameter}
-The value of this parameter is a cons cell whose @sc{car} and @sc{cdr},
-if non-@code{nil}, specify the minimum values (in columns) for the left
-and right margin of this window.  When present, Emacs will use these
-values instead of the actual margin widths for determining whether a
-window can be split or shrunk horizontally.
+The value of this parameter is a cons cell whose @sc{car} and
+@sc{cdr}, if non-@code{nil}, specify the minimum values (in columns)
+for the left and right margin of this window (@pxref{Display Margins}.
+When present, Emacs will use these values instead of the actual margin
+widths for determining whether a window can be split or shrunk
+horizontally.
 
 Emacs never auto-adjusts the margins of any window after splitting or
 resizing it.  It is the sole responsibility of any application setting
diff --git a/lisp/autorevert.el b/lisp/autorevert.el
index e6dfafca2a5..4fb865e8adb 100644
--- a/lisp/autorevert.el
+++ b/lisp/autorevert.el
@@ -465,7 +465,7 @@ If `global-auto-revert-non-file-buffers' is non-nil, this mode
 may also revert some non-file buffers, as described in the
 documentation of that variable.  It ignores buffers with modes
 matching `global-auto-revert-ignore-modes', and buffers with a
-non-nil vale of `global-auto-revert-ignore-buffer'.
+non-nil value of `global-auto-revert-ignore-buffer'.
 
 When a buffer is reverted, a message is generated.  This can be
 suppressed by setting `auto-revert-verbose' to nil.
diff --git a/lisp/frame.el b/lisp/frame.el
index b39891cd142..b5c936a51eb 100644
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -1855,6 +1855,14 @@ for FRAME."
 
 ;;;; Frame/display capabilities.
 
+;; These functions should make the features they test explicit in
+;; their names, so that when capabilities or the corresponding Emacs
+;; features change, it will be easy to find all the tests for such
+;; capabilities by a simple text search.  See more about the history
+;; and the intent of these functions in
+;; http://lists.gnu.org/archive/html/bug-gnu-emacs/2019-04/msg00004.html
+;; or in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=35058#17.
+
 (declare-function msdos-mouse-p "dosfns.c")
 
 (defun display-mouse-p (&optional display)
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index e6f30c9f804..b992a8ebe09 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -1806,7 +1806,12 @@ Return t if the buffer had changes, nil otherwise."
 
 ;;;###autoload
 (defun vc-version-diff (_files rev1 rev2)
-  "Report diffs between REV1 and REV2 revisions of the fileset."
+  "Report diffs between revisions REV1 and REV2 in the repository history.
+This compares two revisions of the current fileset.
+If REV1 is nil, it defaults to the current revision, i.e. revision
+of the last commit.
+If REV2 is nil, it defaults to the work tree, i.e. the current
+state of each file in the fileset."
   (interactive (vc-diff-build-argument-list-internal))
   ;; All that was just so we could do argument completion!
   (when (and (not rev1) rev2)
@@ -1891,8 +1896,14 @@ The merge base is a common ancestor between REV1 and REV2 revisions."
 
 ;;;###autoload
 (defun vc-version-ediff (files rev1 rev2)
-  "Show differences between revisions of the fileset in the
-repository history using ediff."
+  "Show differences between REV1 and REV2 of FILES using ediff.
+This compares two revisions of the files in FILES.  Currently,
+only a single file's revisions can be compared, i.e. FILES can
+specify only one file name.
+If REV1 is nil, it defaults to the current revision, i.e. revision
+of the last commit.
+If REV2 is nil, it defaults to the work tree, i.e. the current
+state of each file in FILES."
   (interactive (vc-diff-build-argument-list-internal))
   ;; All that was just so we could do argument completion!
   (when (and (not rev1) rev2)
diff --git a/src/editfns.c b/src/editfns.c
index bfffadc733d..6fb43af4e9c 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -2686,8 +2686,9 @@ but is not deleted; if you save the buffer in a file, the invisible
 text is included in the file.  \\[widen] makes all visible again.
 See also `save-restriction'.
 
-When calling from a program, pass two arguments; positions (integers
-or markers) bounding the text that should remain visible.  */)
+When calling from Lisp, pass two arguments START and END:
+positions (integers or markers) bounding the text that should
+remain visible.  */)
   (register Lisp_Object start, Lisp_Object end)
 {
   CHECK_FIXNUM_COERCE_MARKER (start);
diff --git a/src/fontset.c b/src/fontset.c
index 2729fae6ee9..eec1e0da4cc 100644
--- a/src/fontset.c
+++ b/src/fontset.c
@@ -1444,7 +1444,7 @@ or t for the default fontset.
 
 TARGET may be a single character to use FONT-SPEC for.
 
-Target may be a cons (FROM . TO), where FROM and TO are characters.
+TARGET may be a cons (FROM . TO), where FROM and TO are characters.
 In that case, use FONT-SPEC for all the characters in the range
 between FROM and TO (inclusive).
 
diff --git a/src/window.c b/src/window.c
index f911c0c7d44..ef2ed638508 100644
--- a/src/window.c
+++ b/src/window.c
@@ -1796,7 +1796,12 @@ DEFUN ("set-window-start", Fset_window_start, Sset_window_start, 2, 3, 0,
        doc: /* Make display in WINDOW start at position POS in WINDOW's buffer.
 WINDOW must be a live window and defaults to the selected one.  Return
 POS.  Optional third arg NOFORCE non-nil inhibits next redisplay from
-overriding motion of point in order to display at this exact start.  */)
+overriding motion of point in order to display at this exact start.
+
+For reliable setting of WINDOW start position, make sure point is
+at a position that will be visible when that start is in effect,
+otherwise there's a chance POS will be disregarded, e.g., if point
+winds up in a partially-visible line.  */)
   (Lisp_Object window, Lisp_Object pos, Lisp_Object noforce)
 {
   register struct window *w = decode_live_window (window);