Merge from emacs-24; up to 2014-07-20T16:14:58Z!dmantipov@yandex.ru

18 files changed, 133 insertions, 118 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index f13879eaa08..9115b514871 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,13 @@
+2014-10-04  Glenn Morris  <rgm@gnu.org>
+
+        * cmdargs.texi (Misc X):
+        * display.texi (Optional Mode Line):
+        * misc.texi (emacsclient Options):
+        * vc1-xtra.texi (VC Delete/Rename): Small fixes re @var usage.
+
+        * killing.texi (Rectangles): Copyedits re rectangle-mark-mode.
+        (CUA Bindings): Mention rectangle-mark-mode.
+
 2014-10-03  Martin Rudalics  <rudalics@gmx.at>
 
         * frames.texi (Frame Commands):
diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index 3443f0b1627..b438281b2a2 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -1106,8 +1106,8 @@ rectangle containing the frame's title.
 @c Enable horizontal scroll bars.  Since horizontal scroll bars
 @c are not yet implemented, this actually does nothing.
 
-@item --parent-id @var{ID}
-Open Emacs as a client X window via the XEmbed protocol, with @var{ID}
+@item --parent-id @var{id}
+Open Emacs as a client X window via the XEmbed protocol, with @var{id}
 as the parent X window id.  Currently, this option is mainly useful
 for developers.
 
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index bdcb185a5f3..0a77e722d32 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1245,11 +1245,11 @@ Size Indication mode.  The size will be displayed immediately
 following the buffer percentage like this:
 
 @example
-@var{POS} of @var{SIZE}
+@var{pos} of @var{size}
 @end example
 
 @noindent
-Here @var{SIZE} is the human readable representation of the number of
+Here @var{size} is the human readable representation of the number of
 characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
 for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.
 
diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi
index 45dbd5727ac..f4b1752643d 100644
--- a/doc/emacs/killing.texi
+++ b/doc/emacs/killing.texi
@@ -754,6 +754,10 @@ Replace rectangle contents with @var{string} on each line
 (@code{string-rectangle}).
 @item M-x string-insert-rectangle @key{RET} @var{string} @key{RET}
 Insert @var{string} on each line of the rectangle.
+@item C-x @key{SPC}
+Toggle Rectangle Mark mode (@code{rectangle-mark-mode}).
+When this mode is active, the region-rectangle is highlighted and can
+be shrunk/grown, and the standard kill and yank commands operate on it.
 @end table
 
   The rectangle operations fall into two classes: commands to erase or
@@ -840,11 +844,13 @@ rectangle shifts right.
 shifting the original text to the right.
 
 @findex rectangle-mark-mode
-@cindex rectangular region
-  The command @kbd{C-x @key{SPC}} (@code{rectangle-mark-mode}) makes a
-@dfn{rectangular region}.  It is a new feature introduced in GNU Emacs
-24.4, and most commands now are still unaware of it, but kill and yank
-(@pxref{Killing}) do work on the rectangle.
+  The command @kbd{C-x @key{SPC}} (@code{rectangle-mark-mode}) toggles
+whether the region-rectangle or the standard region is highlighted
+(first activating the region if necessary).  When this mode is enabled,
+commands that resize the region (@kbd{C-f}, @kbd{C-n} etc.) do
+so in a rectangular fashion, and killing and yanking operate on the
+rectangle.  @xref{Killing}.  The mode persists only as long as the
+region is active.
 
 @node CUA Bindings
 @section CUA Bindings
@@ -887,7 +893,8 @@ any direction.  Normal text you type is inserted to the left or right
 of each line in the rectangle (on the same side as the cursor).
 
   You can use this rectangle support without activating CUA by calling the
-@code{cua-rectangle-mark-mode} command.
+@code{cua-rectangle-mark-mode} command.  But see also the standard
+@code{rectangle-mark-mode}.  @xref{Rectangles}.
 
   With CUA you can easily copy text and rectangles into and out of
 registers by providing a one-digit numeric prefix to the kill, copy,
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index ae1aefcee76..1a865c70cdd 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -1610,9 +1610,9 @@ all server buffers are finished.  You can take as long as you like to
 edit the server buffers within Emacs, and they are @emph{not} killed
 when you type @kbd{C-x #} in them.
 
-@item --parent-id @var{ID}
+@item --parent-id @var{id}
 Open an @command{emacsclient} frame as a client frame in the parent X
-window with id @var{ID}, via the XEmbed protocol.  Currently, this
+window with id @var{id}, via the XEmbed protocol.  Currently, this
 option is mainly useful for developers.
 
 @item -q
diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi
index 07f956c488d..dd52d97780d 100644
--- a/doc/emacs/vc1-xtra.texi
+++ b/doc/emacs/vc1-xtra.texi
@@ -113,7 +113,7 @@ Prompt for a file name, delete the file from the working tree, and
 schedule the deletion for committing.
 
 @item M-x vc-rename-file
-Prompt for two file names, @var{VAR} and @var{OLD}, rename them in the
+Prompt for two file names, @var{var} and @var{old}, rename them in the
 working tree, and schedule the renaming for committing.
 @end table
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 2cb9970f5fd..f3fce93dd53 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,18 @@
+2014-10-04  Glenn Morris  <rgm@gnu.org>
+
+        * commands.texi (Generic Commands): Copyedits.
+
+        * display.texi (Scroll Bars):
+        * modes.texi (Header Lines): Copyedits.
+
+        * buffers.texi (Buffer List):
+        * display.texi (Image Descriptors, Defining Images):
+        * functions.texi (Core Advising Primitives): Small fixes re @var usage.
+
+        * windows.texi (Window Sizes, Resizing Windows): Copyedits.
+
+        * frames.texi (Multiple Terminals): Copyedits re multiple monitors.
+
 2014-10-03  Martin Rudalics  <rudalics@gmx.at>
 
         * frames.texi (Size Parameters, Size and Position): Mention that
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1293a03082c..5ac2d6786e8 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -863,7 +863,7 @@ If no suitable buffer exists, the buffer @file{*scratch*} is returned
 
 @defun last-buffer &optional buffer visible-ok frame
 This function returns the last buffer in @var{frame}'s buffer list other
-than @var{BUFFER}.  If @var{frame} is omitted or @code{nil}, it uses the
+than @var{buffer}.  If @var{frame} is omitted or @code{nil}, it uses the
 selected frame's buffer list.
 
 The argument @var{visible-ok} is handled as with @code{other-buffer},
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 58e903918bf..e5db4d87539 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -589,31 +589,26 @@ Put them into three windows, selecting the last one."
 @cindex alternatives, defining
 
 The macro @code{define-alternatives} can be used to define
-@dfn{generic commands}.  Generic commands are interactive functions
-whose implementation can be selected among several alternatives, as a
-matter of user preference.
+@dfn{generic commands}.  These are interactive functions whose
+implementation can be selected from several alternatives, as a matter
+of user preference.
 
 @defmac define-alternatives command &rest customizations
-Define the new command `COMMAND'.
+Define the new command @var{command}, a symbol.
 
-The argument `COMMAND' should be a symbol.
+When a user runs @kbd{M-x @var{command} @key{RET}} for the first time,
+Emacs prompts for which real form of the command to use, and records
+the selection by way of a custom variable.  Using a prefix argument
+repeats this process of choosing an alternative.
 
-When a user runs @kbd{M-x COMMAND @key{RET}} for the first time, Emacs
-will prompt for which alternative to use and record the selected
-command as a custom variable.
+The variable @code{@var{command}-alternatives} should contain an alist
+with alternative implementations of @var{command}.
+Until this variable is set, @code{define-alternatives} has no effect.
 
-Running @kbd{C-u M-x COMMAND @key{RET}} prompts again for an
-alternative and overwrites the previous choice.
-
-The variable @code{COMMAND-alternatives} contains an alist
-(@pxref{Association Lists}) with alternative implementations of
-`COMMAND'.  @code{define-alternatives} does not have any effect until
-this variable is set.
-
-If @var{customizations} is non-@var{nil}, it should be composed of
-alternating @code{defcustom} keywords and values to add to the
-declaration of @code{COMMAND-alternatives} (typically :group and
-:version).
+If @var{customizations} is non-@code{nil}, it should consist of
+alternating @code{defcustom} keywords (typically @code{:group} and
+@code{:version}) and values to add to the declaration of
+@code{@var{command}-alternatives}.
 @end defmac
 
 @node Interactive Call
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index e88eadb5ca7..46be5ecf3f0 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3925,9 +3925,9 @@ bar actually occupies.
 @end defun
 
 @defun window-scroll-bar-width &optional window
-This function returns the width of @var{window}'s vertical scrollbar,
-in pixels.  @var{window} must be a live window.  If @var{window} is
-@code{nil} or omitted, it will be the selected window.
+This function returns the width in pixels of @var{window}'s vertical
+scrollbar.  @var{window} must be a live window, and defaults to the
+selected window.
 @end defun
 
 If you don't specify these values for a window with
@@ -4503,7 +4503,7 @@ functions to insert images into buffers.
 
   Each image descriptor has the form @code{(image . @var{props})},
 where @var{props} is a property list of alternating keyword symbols
-and values, including at least the pair @code{:type @var{TYPE}} which
+and values, including at least the pair @code{:type @var{type}} that
 specifies the image type.
 
   The following is a list of properties that are meaningful for all
@@ -4995,7 +4995,7 @@ of a list of image specifications @var{specs}.
 Each specification in @var{specs} is a property list with contents
 depending on image type.  All specifications must at least contain the
 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
-or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
+or @w{@code{:data @var{data}}}, where @var{type} is a symbol specifying
 the image type, e.g., @code{xbm}, @var{file} is the file to load the
 image from, and @var{data} is a string containing the actual image data.
 The first specification in the list whose @var{type} is supported, and
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index fdb995f2399..c8e0fff6cd0 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -314,57 +314,50 @@ on that display (@pxref{Deleting Frames}).
 
 @cindex multi-monitor
   On some ``multi-monitor'' setups, a single X display outputs to more
-than one physical monitor.  @code{display-monitor-attributes-list} and
-@code{frame-monitor-attributes} can be used to obtain information
-about each physical monitor on multi-monitor setups.
+than one physical monitor.  You can use the functions
+@code{display-monitor-attributes-list} and @code{frame-monitor-attributes}
+to obtain information about such setups.
 
 @defun display-monitor-attributes-list &optional display
 This function returns a list of physical monitor attributes on
-@var{display}.  Each element of the list is an association list,
-representing the attributes of each physical monitor.  The first
-element corresponds to the primary monitor.
-
-Attributes for a physical monitor are:
+@var{display}, which defaults to that of the selected frame.
+Each element of the list is an association list, representing the
+attributes of a physical monitor.  The first element corresponds to
+the primary monitor.  The attribute keys and values are:
 
 @table @samp
 @item geometry
-Position and size in pixels in the form of @samp{(X Y WIDTH HEIGHT)}
+Position and size in pixels as @samp{(@var{x} @var{y}
+@var{width} @var{height})}.
 
 @item workarea
-Position and size of the workarea in pixels in the form of @samp{(X Y
-WIDTH HEIGHT)}
+Position and size of the work area in pixels as
+@samp{(@var{x} @var{y} @var{width} @var{height})}.
 
 @item mm-size
-Width and height in millimeters in the form of @samp{(WIDTH HEIGHT)}
+Width and height in millimeters as @samp{(@var{width} @var{height})}
 
 @item frames
-List of frames dominated by the physical monitor
+List of frames that this physical monitor dominates (see below).
 
 @item name
-Name of the physical monitor as a string
+Name of the physical monitor as @var{string}.
 @end table
 
-where X, Y, WIDTH, and HEIGHT are integers.  @samp{name} is optional.
-
-A frame is dominated by a physical monitor when either the
-largest area of the frame resides in the monitor, or the monitor
-is the closest to the frame if the frame does not intersect any
-physical monitors.  Every non-tip frame (including invisible one)
-in a graphical display is dominated by exactly one physical
-monitor at a time, though it can span multiple (or no) physical
-monitors.
+@var{x}, @var{y}, @var{width}, and @var{height} are integers.
+@samp{name} may not be present.
 
-@var{display} defaults to the selected frame's display.
+A frame is @dfn{dominated} by a physical monitor when either the
+largest area of the frame resides in that monitor, or (if the frame
+does not intersect any physical monitors) that monitor is the closest
+to the frame.  Every (non-tooltip) frame (whether visible or not) in a
+graphical display is dominated by exactly one physical monitor at a
+time, though the frame can span multiple (or no) physical monitors.
 @end defun
 
 @defun frame-monitor-attributes &optional frame
 This function returns the attributes of the physical monitor
-dominating @var{frame}, which defaults to the selected frame.
-
-A frame is dominated by a physical monitor when either the
-largest area of the frame resides in the monitor, or the monitor
-is the closest to the frame if the frame does not intersect any
-physical monitors.
+dominating (see above) @var{frame}, which defaults to the selected frame.
 @end defun
 
 @node Frame Parameters
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 3049660159a..023175e3632 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1232,7 +1232,7 @@ global value of @var{place}.  Whereas if @var{place} is of the form
 @code{(local @var{symbol})}, where @var{symbol} is an expression which returns
 the variable name, then @var{function} will only be added in the
 current buffer.  Finally, if you want to modify a lexical variable, you will
-have to use @code{(var @var{VARIABLE})}.
+have to use @code{(var @var{variable})}.
 
 Every function added with @code{add-function} can be accompanied by an
 association list of properties @var{props}.  Currently only two of those
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index e23e2685a7c..d67bac63b15 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2221,13 +2221,10 @@ is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
 It is normally @code{nil}, so that ordinary buffers have no header line.
 @end defvar
 
-The function @code{window-header-line-height} returns the height of
-the header line:
-
 @defun window-header-line-height &optional window
-Return the height of @var{window}'s header line, in pixels.
-@var{window} must be a live window.  If @var{window} is @code{nil} or
-omitted, it will be the selected window.
+This function returns the height in pixels of @var{window}'s header
+line.  @var{window} must be a live window, and defaults to the
+selected window.
 @end defun
 
   A window that is just one line tall never displays a header line.  A
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index f2fe5c85a93..f5122a39f8c 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -451,7 +451,7 @@ This function returns the total height, in lines, of the window
 the selected window.  If @var{window} is an internal window, the return
 value is the total height occupied by its descendant windows.
 
-   If a window's pixel height is not an integral multiple of its frame's
+  If a window's pixel height is not an integral multiple of its frame's
 default character height, the number of lines occupied by the window is
 rounded internally.  This is done in a way such that, if the window is a
 parent window, the sum of the total heights of all its child windows
@@ -462,13 +462,12 @@ vertically combined and has a right sibling, the topmost row of that
 sibling can be calculated as the sum of this window's topmost row and
 total height (@pxref{Coordinates and Windows})
 
-   If the optional argument @var{round} equals @code{ceiling}, this
+  If the optional argument @var{round} is @code{ceiling}, this
 function returns the smallest integer larger than @var{window}'s pixel
-height divided by the character height of @var{window}'s frame; if it is
-@code{floor}, it returns the largest integer smaller than @var{window}'s
-pixel height divided by the character height of @var{window}'s frame.
-Any other value of @var{round} means to return the internal value of the
-total height of @var{window}.
+height divided by the character height of its frame; if it is
+@code{floor}, it returns the largest integer smaller than said value;
+with any other @var{round} it returns the internal value of
+@var{windows}'s total height.
 @end defun
 
 @cindex window width
@@ -484,7 +483,7 @@ This function returns the total width, in columns, of the window
 the selected window.  If @var{window} is internal, the return value is
 the total width occupied by its descendant windows.
 
-   If a window's pixel width is not an integral multiple of its frame's
+  If a window's pixel width is not an integral multiple of its frame's
 character width, the number of lines occupied by the window is rounded
 internally.  This is done in a way such that, if the window is a parent
 window, the sum of the total widths of all its children internally
@@ -493,15 +492,9 @@ windows have the same pixel width, their internal total widths may
 differ by one column.  This means also, that if this window is
 horizontally combined and has a right sibling, the leftmost column of
 that sibling can be calculated as the sum of this window's leftmost
-column and total width (@pxref{Coordinates and Windows}).
-
-If the optional argument @var{round} is @code{ceiling}, this function
-will return the smallest integer larger than @var{window}'s pixel width
-divided by the character width of @var{window}'s frame; if it is
-@code{floor}, it returns the largest integer smaller than @var{window}'s
-pixel width divided by the character width of @var{window}'s frame.  Any
-other value of @var{round} means to return the internal total width of
-@var{window}.
+column and total width (@pxref{Coordinates and Windows}).  The
+optional argument @var{round} behaves as it does for
+@code{window-total-height}.
 @end defun
 
 @defun window-total-size &optional window horizontal round
@@ -510,8 +503,7 @@ width in columns of the window @var{window}.  If @var{horizontal} is
 omitted or @code{nil}, this is equivalent to calling
 @code{window-total-height} for @var{window}; otherwise it is equivalent
 to calling @code{window-total-width} for @var{window}.  The optional
-argument @code{ROUND} is handled as for @code{window-total-height} and
-@code{window-total-width}.
+argument @var{round} behaves as it does for @code{window-total-height}.
 @end defun
 
 The following two functions can be used to return the total size of a
@@ -754,8 +746,8 @@ tall; and a minimum-width window as one consisting of fringes, margins,
 a scroll bar and a right divider (if any), plus a text area two columns
 wide.
 
-If the optional argument @code{pixelwise} is non-@code{nil},
-@var{delta} will be interpreted as pixels.
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} is interpreted as pixels.
 @end defun
 
 @defun window-resize window delta &optional horizontal ignore pixelwise
@@ -779,7 +771,7 @@ values of the option @code{window-combination-resize} and the
 combination limits of the involved windows; in some cases, it may alter
 both edges.  @xref{Recombining Windows}.  To resize by moving only the
 bottom or right edge of a window, use the function
-@code{adjust-window-trailing-edge}, below.
+@code{adjust-window-trailing-edge}.
 @end defun
 
 @c The commands enlarge-window, enlarge-window-horizontally,
@@ -792,8 +784,8 @@ If optional argument @var{horizontal} is non-@code{nil}, it instead
 moves the right edge by @var{delta} columns.  If @var{window} is
 @code{nil}, it defaults to the selected window.
 
-If the optional argument @code{pixelwise} is non-@code{nil},
-@var{delta} will be interpreted as pixels.
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} is interpreted as pixels.
 
 A positive @var{delta} moves the edge downwards or to the right; a
 negative @var{delta} moves it upwards or to the left.  If the edge
@@ -807,17 +799,16 @@ window is fixed-size), it may resize other windows.
 
 @cindex pixelwise, resizing windows
 @defopt window-resize-pixelwise
-If the value of this option is non-@code{nil}, windows are resized in
+If the value of this option is non-@code{nil}, Emacs resizes windows in
 units of pixels.  This currently affects functions like
 @code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
 @code{minimize-window}, @code{fit-window-to-buffer},
 @code{shrink-window-if-larger-than-buffer} (all listed below) and
 @code{fit-frame-to-buffer} (@pxref{Size and Position}).
 
-Note that when a frame's pixel size is not a multiple of the frame's
-character size, at least one window may get resized pixelwise even if
-this option is @code{nil}.  The default value of this option is
-@code{nil}.
+Note that when a frame's pixel size is not a multiple of its character
+size, at least one window may get resized pixelwise even if this
+option is @code{nil}.  The default value is @code{nil}.
 @end defopt
 
   The following commands resize windows in more specific ways.  When
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 270ab48bcda..7ce5941d282 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,7 @@
+2014-10-04  Glenn Morris  <rgm@gnu.org>
+
+        * vip.texi (Other Vi Commands): Markup fix.
+
 2014-10-03  Bastien Guerry  <bzg@gnu.org>
 
         * org.texi (Key bindings and useful functions): Fix typo.
diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi
index 2b255eefcca..a6c6d3067ea 100644
--- a/doc/misc/vip.texi
+++ b/doc/misc/vip.texi
@@ -1561,7 +1561,7 @@ assigned to a function that just beeps (@code{vip-nil}).
 @end example
 
 VIP uses a special local keymap to interpret key strokes you enter in vi
-mode.  The following keys are bound to @var{nil} in the keymap.  Therefore,
+mode.  The following keys are bound to @code{nil} in the keymap.  Therefore,
 these keys are interpreted by the global keymap of Emacs.  We give below a
 short description of the functions bound to these keys in the global
 keymap.  See GNU Emacs Manual for details.
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 75dac546c0f..375bfcf45db 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+2014-10-04  Glenn Morris  <rgm@gnu.org>
+
+        * frame.el (frame-monitor-attributes)
+        (display-monitor-attributes-list): Doc fixes.
+
 2014-10-04  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         Merge trivially safe differences from standalone CC-mode.
diff --git a/lisp/frame.el b/lisp/frame.el
index 0b26e356f07..19c878b59e3 100644
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -1276,7 +1276,7 @@ bars (top, bottom, or nil)."
 
 (defun frame-monitor-attributes (&optional frame)
   "Return the attributes of the physical monitor dominating FRAME.
-If FRAME is omitted, describe the currently selected frame.
+If FRAME is omitted or nil, describe the currently selected frame.
 
 A frame is dominated by a physical monitor when either the
 largest area of the frame resides in the monitor, or the monitor
@@ -1554,16 +1554,15 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defun display-monitor-attributes-list (&optional display)
   "Return a list of physical monitor attributes on DISPLAY.
-Each element of the list represents the attributes of each
-physical monitor.  The first element corresponds to the primary
-monitor.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display.
+Each element of the list represents the attributes of a physical
+monitor.  The first element corresponds to the primary monitor.
 
-Attributes for a physical monitor is represented as an alist of
-attribute keys and values as follows:
+The attributes for a physical monitor are represented as an alist
+of attribute keys and values as follows:
 
- geometry -- Position and size in pixels in the form of
-             (X Y WIDTH HEIGHT)
- workarea -- Position and size of the workarea in pixels in the
+ geometry -- Position and size in pixels in the form of (X Y WIDTH HEIGHT)
+ workarea -- Position and size of the work area in pixels in the
              form of (X Y WIDTH HEIGHT)
  mm-size  -- Width and height in millimeters in the form of
              (WIDTH HEIGHT)
@@ -1576,11 +1575,10 @@ with (*) are optional.
 A frame is dominated by a physical monitor when either the
 largest area of the frame resides in the monitor, or the monitor
 is the closest to the frame if the frame does not intersect any
-physical monitors.  Every non-tip frame (including invisible one)
+physical monitors.  Every (non-tooltip) frame (including invisible ones)
 in a graphical display is dominated by exactly one physical
 monitor at a time, though it can span multiple (or no) physical
-monitors.
-If DISPLAY is omitted or nil, it defaults to the selected frame's display."
+monitors."
   (let ((frame-type (framep-on-display display)))
     (cond
      ((eq frame-type 'x)