Merge from origin/emacs-26

8d45000 (origin/emacs-26) Fix some issues in the emacs/lispref manuals
194ded5 Fix multiple spaces in Emacs manual
57a5461 * lisp/files.el (save-some-buffers): Doc fix.  (Bug#30215)
231474f Adjudicate comments to "International" chapter of Emacs manual

7 files changed, 26 insertions, 27 deletions

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 212b5a45dc6..0e39866d349 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -527,7 +527,7 @@ string for details.
 @vindex byte-compile-error-on-warn
   Sometimes you may wish the byte-compiler warnings to be reported
 using @code{error}.  If so, set @code{byte-compile-error-on-warn} to a
-non-nil value.
+non-@code{nil} value.
 
 @node Byte-Code Objects
 @section Byte-Code Function Objects
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 307bba6e69b..e69f95b9d1a 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -619,7 +619,7 @@ was called.  The convention for arguments is detailed in the description
 of @code{debug} (@pxref{Invoking the Debugger}).
 @end defvar
 
-@deffn Command backtrace
+@defun backtrace
 @cindex run time stack
 @cindex call stack
 This function prints a trace of Lisp function calls currently active.
@@ -669,9 +669,9 @@ forms are elided.
 ----------- Buffer: backtrace-output ------------
 @end group
 @end smallexample
-@end deffn
+@end defun
 
-@defvar debugger-stack-frame-as-list
+@defopt debugger-stack-frame-as-list
 If this variable is non-@code{nil}, every stack frame of the backtrace
 is displayed as a list.  This aims at improving the backtrace
 readability at the cost of special forms no longer being visually
@@ -700,7 +700,7 @@ example would look as follows:
 ----------- Buffer: backtrace-output ------------
 @end group
 @end smallexample
-@end defvar
+@end defopt
 
 @defvar debug-on-next-call
 @cindex @code{eval}, and debugging
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 921fd104547..fbf943a08c7 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1980,7 +1980,7 @@ height of both, if present, in the return value.
 whole and does not care about the size of individual lines.  The
 following function does.
 
-@defun window-lines-pixel-dimensions &optional window first last body inverse
+@defun window-lines-pixel-dimensions &optional window first last body inverse left
 This function calculates the pixel dimensions of each line displayed in
 the specified @var{window}.  It does so by walking @var{window}'s
 current glyph matrix---a matrix storing the glyph (@pxref{Glyphs}) of
@@ -2775,15 +2775,15 @@ This sets the @code{:slant} attribute of @var{face} to @var{normal} if
 @var{italic-p} is @code{nil}, and to @var{italic} otherwise.
 @end defun
 
-@defun set-face-underline face underline &optional frame
+@deffn Command set-face-underline face underline &optional frame
 This sets the @code{:underline} attribute of @var{face} to
 @var{underline}.
-@end defun
+@end deffn
 
-@defun set-face-inverse-video face inverse-video-p &optional frame
+@deffn Command set-face-inverse-video face inverse-video-p &optional frame
 This sets the @code{:inverse-video} attribute of @var{face} to
 @var{inverse-video-p}.
-@end defun
+@end deffn
 
 @deffn Command invert-face face &optional frame
 This swaps the foreground and background colors of face @var{face}.
@@ -7362,7 +7362,7 @@ have their own frame parameters (@pxref{Frame Parameters}).  Unlike
 other frames, the default parameters for tooltip frames are stored in a
 special variable.
 
-@defvar tooltip-frame-parameters
+@defopt tooltip-frame-parameters
 This customizable option holds the default frame parameters used for
 displaying tooltips.  Any font and color parameters are ignored, and the
 corresponding attributes of the @code{tooltip} face are used instead.
@@ -7372,7 +7372,7 @@ absolute frame-relative coordinates where the tooltip should be shown.
 variables described in @ref{Tooltips,,, emacs, The GNU Emacs Manual}.)
 Note that the @code{left} and @code{top} parameters, if present,
 override the values of mouse-relative offsets.
-@end defvar
+@end defopt
 
 @vindex tooltip@r{ face}
 The @code{tooltip} face determines the appearance of text shown in
@@ -7547,7 +7547,7 @@ for its paragraphs.  For example, buffers containing program source
 code should force all paragraphs to be displayed left-to-right.  You
 can use following variable to do this:
 
-@defvar bidi-paragraph-direction
+@defopt bidi-paragraph-direction
 If the value of this buffer-local variable is the symbol
 @code{right-to-left} or @code{left-to-right}, all paragraphs in the
 buffer are assumed to have that specified direction.  Any other value
@@ -7558,7 +7558,7 @@ the base direction of each paragraph from its contents.
 Modes for program source code should set this to @code{left-to-right}.
 Prog mode does this by default, so modes derived from Prog mode do not
 need to set this explicitly (@pxref{Basic Major Modes}).
-@end defvar
+@end defopt
 
 @defun current-bidi-paragraph-direction &optional buffer
 This function returns the paragraph direction at point in the named
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 9c25f4da4d4..43fdd8f9d54 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -2201,13 +2201,13 @@ The @code{cursor-type} frame parameter may be overridden by the
 variables @code{cursor-type} and
 @code{cursor-in-non-selected-windows}:
 
-@defvar cursor-type
+@defopt cursor-type
 This buffer-local variable controls how the cursor looks in a selected
 window showing the buffer.  If its value is @code{t}, that means to
 use the cursor specified by the @code{cursor-type} frame parameter.
 Otherwise, the value should be one of the cursor types listed above,
 and it overrides the @code{cursor-type} frame parameter.
-@end defvar
+@end defopt
 
 @defopt cursor-in-non-selected-windows
 This buffer-local variable controls how the cursor looks in a window
@@ -2725,7 +2725,7 @@ Ideally, the function described next should focus a frame without also
 raising it above other frames.  Unfortunately, many window-systems or
 window managers may refuse to comply.
 
-@defun x-focus-frame &optional frame noactivate
+@defun x-focus-frame frame &optional noactivate
 This function gives @var{frame} the focus of the X server without
 necessarily raising it.  @var{frame} @code{nil} means use the selected
 frame.  Under X, the optional argument @var{noactivate}, if
@@ -3261,13 +3261,12 @@ exists, @var{frame} is considered a child frame of that frame.
 This function returns @code{nil} if @var{frame} has no parent frame.
 @end defun
 
-@defun frame-ancestor-p &optional ancestor descendant
+@defun frame-ancestor-p ancestor descendant
 This functions returns non-@code{nil} if @var{ancestor} is an ancestor
 of @var{descendant}.  @var{ancestor} is an ancestor of @var{descendant}
 when it is either @var{descendant}'s parent frame or it is an ancestor
 of @var{descendant}'s parent frame.  Both, @var{ancestor} and
-@var{descendant} must specify live frames and default to the selected
-frame.
+@var{descendant} must specify live frames.
 @end defun
 
 Note also the function @code{window-largest-empty-rectangle}
@@ -3279,7 +3278,7 @@ window.
 Customizing the following option can be useful to tweak the behavior of
 @code{iconify-frame} for child frames.
 
-@defvar iconify-child-frame
+@defopt iconify-child-frame
 This option tells Emacs how to proceed when it is asked to iconify a
 child frame.  If it is @code{nil}, @code{iconify-frame} will do nothing
 when invoked on a child frame.  If it is @code{iconify-top-level}, Emacs
@@ -3291,7 +3290,7 @@ Any other value means to try iconifying the child frame.  Since such an
 attempt may not be honored by all window managers and can even lead to
 making the child frame unresponsive to user actions, the default is to
 iconify the top level frame instead.
-@end defvar
+@end defopt
 
 
 @node Mouse Tracking
diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi
index 275b018b15a..fc40f28ded8 100644
--- a/doc/lispref/maps.texi
+++ b/doc/lispref/maps.texi
@@ -51,7 +51,7 @@ A sparse keymap for subcommands of the prefix @kbd{C-x r}.@*
 @xref{Registers,,, emacs, The GNU Emacs Manual}.
 
 @item esc-map
-A full keymap for @kbd{ESC} (or @kbd{Meta}) commands.
+A full keymap for @key{ESC} (or @key{Meta}) commands.
 
 @item facemenu-keymap
 A sparse keymap used for the @kbd{M-o} prefix key.
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 08544688350..1a4e2db44a6 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -699,7 +699,7 @@ inadvertently can lose a lot of work, the
 you have buffers that need saving or subprocesses that are running.
 It also runs the abnormal hook @code{kill-emacs-query-functions}:
 
-@defvar kill-emacs-query-functions
+@defopt kill-emacs-query-functions
 When @code{save-buffers-kill-terminal} is killing Emacs, it calls the
 functions in this hook, after asking the standard questions and before
 calling @code{kill-emacs}.  The functions are called in order of
@@ -708,7 +708,7 @@ confirmation from the user.  If any of them returns @code{nil},
 @code{save-buffers-kill-emacs} does not kill Emacs, and does not run
 the remaining functions in this hook.  Calling @code{kill-emacs}
 directly does not run this hook.
-@end defvar
+@end defopt
 
 @node Suspending Emacs
 @subsection Suspending Emacs
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 170924f6060..3691a2c04f4 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -4701,7 +4701,7 @@ managers that give focus to a frame (and thus trigger its subsequent
 selection) whenever the mouse pointer enters its window-system window
 (@pxref{Input Focus}).
 
-@defvar mouse-autoselect-window
+@defopt mouse-autoselect-window
 If this variable is non-@code{nil}, Emacs will try to automatically
 select the window under the mouse pointer.  The following values are
 meaningful:
@@ -4729,7 +4729,7 @@ mode line of a window conceptually should not cause its auto-selection.
 
 Mouse auto-selection selects the minibuffer window only if it is active,
 and never deselects the active minibuffer window.
-@end defvar
+@end defopt
 
 Mouse auto-selection can be used to emulate a focus follows mouse policy
 for child frames (@pxref{Child Frames}) which usually are not tracked by