Merge commit 'de238b39e335c6814283faa171b35145f124edf2'

5 files changed, 102 insertions, 77 deletions

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 7edc1a5fae1..58ec3730299 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -1484,7 +1484,7 @@ Stevens, Andy Stewart, Jonathan Stigelman, Martin Stjernholm, Kim F.
 Storm, Steve Strassmann, Christopher Suckling, Olaf Sylvester, Naoto
 Takahashi, Steven Tamm, Jan Tatarik, Luc Teirlinck, Jean-Philippe Theberge, Jens
 T. Berger Thielemann, Spencer Thomas, Jim Thompson, Toru Tomabechi,
-David O'Toole, Markus Triska, Tom Tromey, Enami Tsugutomo, Eli
+David O'Toole, Markus Triska, Tom Tromey, Eli
 Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswarran, Neil
 W. Van Dyke, Didier Verna, Joakim Verona, Ulrik Vieth, Geoffrey
 Voelker, Johan Vromans, Inge Wallin, John Paul Wallington, Colin
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 86f9fa0e5f5..1ef836b8f94 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2577,11 +2577,11 @@ The quick brown fox jum  @point{}ped.
 @end example
 @end deffn
 
-@deffn Command indent-relative-maybe
+@deffn Command indent-relative-first-indent-point
 @comment !!SourceFile indent.el
 This command indents the current line like the previous nonblank line,
 by calling @code{indent-relative} with @code{t} as the
-@var{unindented-ok} argument.  The return value is unpredictable.
+@var{first-only} argument.  The return value is unpredictable.
 
 If the previous nonblank line has no indent points beyond the current
 column, this command does nothing.
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/doc/misc/eieio.texi b/doc/misc/eieio.texi
index d03ee79f18b..f56b2b67a40 100644
--- a/doc/misc/eieio.texi
+++ b/doc/misc/eieio.texi
@@ -88,11 +88,11 @@ framework for writing object-oriented applications in Emacs.
 use @eieio{} to create classes, methods for those classes, and
 instances of classes.
 
-Here is a simple example of a class named @code{record}, containing
+Here is a simple example of a class named @code{person}, containing
 three slots named @code{name}, @code{birthday}, and @code{phone}:
 
 @example
-(defclass record () ; No superclasses
+(defclass person () ; No superclasses
   ((name :initarg :name
          :initform ""
          :type string
@@ -106,23 +106,23 @@ three slots named @code{name}, @code{birthday}, and @code{phone}:
    (phone :initarg :phone
           :initform ""
           :documentation "Phone number."))
-  "A single record for tracking people I know.")
+  "A class for tracking people I know.")
 @end example
 
 Each class can have methods, which are defined like this:
 
 @example
-(cl-defmethod call-record ((rec record) &optional scriptname)
-  "Dial the phone for the record REC.
+(cl-defmethod call-person ((pers person) &optional scriptname)
+  "Dial the phone for the person PERS.
 Execute the program SCRIPTNAME to dial the phone."
-  (message "Dialing the phone for %s"  (oref rec name))
+  (message "Dialing the phone for %s"  (oref pers name))
   (shell-command (concat (or scriptname "dialphone.sh")
                          " "
-                         (oref rec phone))))
+                         (oref pers phone))))
 @end example
 
 @noindent
-In this example, the first argument to @code{call-record} is a list,
+In this example, the first argument to @code{call-person} is a list,
 of the form (@var{varname} @var{classname}).  @var{varname} is the
 name of the variable used for the first argument; @var{classname} is
 the name of the class that is expected as the first argument for this
@@ -130,17 +130,17 @@ method.
 
 @eieio{} dispatches methods based on the type of the first argument.
 You can have multiple methods with the same name for different classes
-of object.  When the @code{call-record} method is called, the first
+of object.  When the @code{call-person} method is called, the first
 argument is examined to determine the class of that argument, and the
 method matching the input type is then executed.
 
 Once the behavior of a class is defined, you can create a new
-object of type @code{record}.  Objects are created by calling the
+object of type @code{person}.  Objects are created by calling the
 constructor.  The constructor is a function with the same name as your
 class which returns a new instance of that class.  Here is an example:
 
 @example
-(setq rec (record :name "Eric" :birthday "June" :phone "555-5555"))
+(setq pers (person :name "Eric" :birthday "June" :phone "555-5555"))
 @end example
 
 @noindent
@@ -157,19 +157,19 @@ first argument should be an object of a class which has had this
 method defined for it.  In this example it would look like this:
 
 @example
-(call-record rec)
+(call-person pers)
 @end example
 
 @noindent
 or
 
 @example
-(call-record rec "my-call-script")
+(call-person pers "my-call-script")
 @end example
 
 In these examples, @eieio{} automatically examines the class of
-@code{rec}, and ensures that the method defined above is called.  If
-@code{rec} is some other class lacking a @code{call-record} method, or
+@code{pers}, and ensures that the method defined above is called.  If
+@code{pers} is some other class lacking a @code{call-person} method, or
 some other data type, Emacs signals a @code{cl-no-applicable-method}
 error.  @ref{Signals}.
 
@@ -270,10 +270,18 @@ by a symbol with the name @var{class-name}.  @eieio{} stores the structure of
 the class as a symbol property of @var{class-name} (@pxref{Symbol
 Components,,,elisp,GNU Emacs Lisp Reference Manual}).
 
+When defining a class, @eieio{} overwrites any preexisting variable or
+function bindings for the symbol @var{class-name}, which may lead to
+undesired consequences.  Before naming a new class, you should check
+for name conflicts.  To help avoid cross-package conflicts you should
+choose a name with the same prefix you chose for the rest of your
+package's functions and variables (@pxref{Coding
+Conventions,,,elisp,GNU Emacs Lisp Reference Manual}).
+
 The @var{class-name} symbol's variable documentation string is a
 modified version of the doc string found in @var{options-and-doc}.
 Each time a method is defined, the symbol's documentation string is
-updated to include the methods documentation as well.
+updated to include the method's documentation as well.
 
 The parent classes for @var{class-name} is @var{superclass-list}.
 Each element of @var{superclass-list} must be a class.  These classes
@@ -625,10 +633,10 @@ function of @code{:initform}.
 @node Making New Objects
 @chapter Making New Objects
 
-Suppose we have a simple class is defined, such as:
+Suppose we have defined a simple class, such as:
 
 @example
-(defclass record ()
+(defclass my-class ()
    ( ) "Doc String")
 @end example
 
@@ -636,10 +644,10 @@ Suppose we have a simple class is defined, such as:
 It is now possible to create objects of that class type.
 
 Calling @code{defclass} has defined two new functions.  One is the
-constructor @var{record}, and the other is the predicate,
-@var{record}-p.
+constructor @var{my-class}, and the other is the predicate,
+@var{my-class}-p.
 
-@defun record object-name &rest slots
+@defun my-class object-name &rest slots
 
 This creates and returns a new object.  This object is not assigned to
 anything, and will be garbage collected if not saved.  This object
@@ -657,7 +665,7 @@ can do any valid Lispy thing you want with it, such as
 Example of creating an object from a class:
 
 @example
-(record :value 3 :reference nil)
+(my-class :value 3 :reference nil)
 @end example
 
 @end defun
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 264a64b26ad..e376fc7495e 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -2671,7 +2671,7 @@ name syntax.  Its value changes after every call of
 this variable in external packages, a call of @code{file-remote-p} is
 much more appropriate.
 @ifinfo
-@pxref{Magic File Names, , , elisp}
+@pxref{Magic File Names, , , elisp}.
 @end ifinfo
 @end defvar
 @end ifset
@@ -3010,7 +3010,7 @@ Starting with Emacs 26, you could use connection-local variables for
 setting different values of @code{explicit-shell-file-name} for
 different remote hosts.
 @ifinfo
-@xref{Connection Variables, , , emacs}
+@xref{Connection Variables, , , emacs}.
 @end ifinfo
 
 @lisp
@@ -3720,7 +3720,7 @@ Set @code{file-precious-flag} to @code{t} for files accessed by
 @value{tramp} so the file contents are checked using checksum by
 first saving to a temporary file.
 @ifinfo
-@pxref{Saving Buffers, , , elisp}
+@pxref{Saving Buffers, , , elisp}.
 @end ifinfo
 
 @lisp