Minor copyedits of recent changes in documentation

* doc/lispref/frames.texi (Frame Layout, Frame Position)
(Frame Size, Frame Interaction Parameters, Input Focus)
(Raising and Lowering, Child Frames): Improve wording and indexing.
* doc/emacs/cmdargs.texi (Borders X): Improve indexing.

3 files changed, 96 insertions, 85 deletions

diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index 721a2cebb22..6c39fe7b644 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -1077,6 +1077,7 @@ frame's text area), in pixels.
 @itemx --border-width=@var{width}
 @opindex --border-width
 @cindex main border width, command-line argument
+@cindex outer border width, command-line argument
 Specify @var{width} as the width of the outer border, in pixels.
 @end table
 
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 2fac8020ffb..b8f42578111 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -505,17 +505,17 @@ two frames adjacent to each other on the screen.  Usually, the outer
 size of a frame is available only after the frame has been mapped (made
 visible, @pxref{Visibility of Frames}) at least once.  For the initial
 frame or a frame that has not been created yet, the outer size can be
-estimated only or must be calculated from the window-system's or window
-manager defaults.  One workaround is to obtain the differences of the
+only estimated or must be calculated from the window-system's or window
+manager's defaults.  One workaround is to obtain the differences of the
 outer and native (see below) sizes of a mapped frame and use them for
 calculating the outer size of the new frame.
 
 @cindex outer position
-The upper left corner of the outer frame (indicated by @samp{(0)} in the
-drawing above) is the @dfn{outer position} of the frame.  The outer
-position of a graphical frame is also referred to as ``the position'' of
-the frame because it usually remains unchanged on its display whenever
-the frame is resized or its layout is changed.
+The position of the upper left corner of the outer frame (indicated by
+@samp{(0)} in the drawing above) is the @dfn{outer position} of the
+frame.  The outer position of a graphical frame is also referred to as
+``the position'' of the frame because it usually remains unchanged on
+its display whenever the frame is resized or its layout is changed.
 
 The outer position is specified by and can be set via the @code{left}
 and @code{top} frame parameters (@pxref{Position Parameters}).  For a
@@ -551,22 +551,24 @@ frames (@pxref{Child Frames}) and @code{undecorated} or
 @code{override-redirect} frames (@pxref{Management Parameters}).
 
 Outer borders are never shown on text terminal frames and on frames
-generated by GTK+ routines.  On Windows, the outer border is emulated
+generated by GTK+ routines.  On MS-Windows, the outer border is emulated
 with the help of a one pixel wide external border.  Non-toolkit builds
-allow to change the color of the outer border by setting the
+on X allow to change the color of the outer border by setting the
 @code{border-color} frame parameter (@pxref{Layout Parameters}).
 
 @item Title Bar
 @cindex title bar
-The @dfn{title bar} is also part of the window manager's decorations and
-typically displays the title of the frame (@pxref{Frame Titles}) as well
-as buttons for minimizing, maximizing and deleting the frame.  It can be
-also used for dragging the frame with the mouse.  The title bar is
-usually not displayed for fullboth (@pxref{Size Parameters}), tooltip
-(@pxref{Tooltips}) and child frames (@pxref{Child Frames}) and doesn't
-exist for terminal frames.  Display of the title bar can be suppressed
-by setting the @code{override-redirect} or the @code{undecorated} frame
-parameters (@pxref{Management Parameters}).
+@cindex caption bar
+The @dfn{title bar}, a.k.a.@ @dfn{caption bar}, is also part of the
+window manager's decorations and typically displays the title of the
+frame (@pxref{Frame Titles}) as well as buttons for minimizing,
+maximizing and deleting the frame.  It can be also used for dragging
+the frame with the mouse.  The title bar is usually not displayed for
+fullboth (@pxref{Size Parameters}), tooltip (@pxref{Tooltips}) and
+child frames (@pxref{Child Frames}) and doesn't exist for terminal
+frames.  Display of the title bar can be suppressed by setting the
+@code{override-redirect} or the @code{undecorated} frame parameters
+(@pxref{Management Parameters}).
 
 @item Menu Bar
 @cindex internal menu bar
@@ -582,11 +584,12 @@ and Frames}).  As a rule, menu bars are never shown on child frames
 setting the @code{menu-bar-lines} parameter (@pxref{Layout Parameters})
 to zero.
 
-It depends on the toolkit whether to wrap or truncate the menu bar
-whenever it becomes too long to fit on its frame.  Usually, only Motif
-and Windows builds can wrap the menu bar.  When they (un-)wrap the menu
-bar, they try to keep the outer height of the frame unchanged, so the
-native height of the frame (see below) will change instead.
+Whether the menu bar is wrapped or truncated whenever its width
+becomes too large to fit on its frame depends on the toolkit .
+Usually, only Motif and MS-Windows builds can wrap the menu bar.  When
+they (un-)wrap the menu bar, they try to keep the outer height of the
+frame unchanged, so the native height of the frame (see below) will
+change instead.
 
 @item Tool Bar
 @cindex internal tool bar
@@ -602,12 +605,13 @@ setting the @code{tool-bar-lines} parameter (@pxref{Layout
 Parameters}) to zero.
 
 If the variable @code{auto-resize-tool-bars} is non-@code{nil}, Emacs
-wraps the internal tool bar when it becomes too long for its frame.  If
-and when Emacs (un-)wraps the internal tool bar, it by default keeps the
-outer height of the frame unchanged, so the native height of the frame
-(see below) will change instead.  Emacs built with GTK+, on the other
-hand, never wraps the tool bar but may automatically increase the outer
-width of a frame in order to accommodate an overlong tool bar.
+wraps the internal tool bar when its width becomes too large for its
+frame.  If and when Emacs (un-)wraps the internal tool bar, it by
+default keeps the outer height of the frame unchanged, so the native
+height of the frame (see below) will change instead.  Emacs built with
+GTK+, on the other hand, never wraps the tool bar but may
+automatically increase the outer width of a frame in order to
+accommodate an overlong tool bar.
 
 @item Native Frame
 @cindex native frame
@@ -631,14 +635,14 @@ button in the title bar or when dragging its external border with the
 mouse.
 
 @cindex native position
-The top left corner of the native frame specifies the @dfn{native
-position} of the frame.  (1)--(3) in the drawing above indicate that
-position for the various builds:
+The position of the top left corner of the native frame specifies the
+@dfn{native position} of the frame.  (1)--(3) in the drawing above
+indicate that position for the various builds:
 
 @itemize @w{}
 @item (1) non-toolkit and terminal frames
 
-@item (2) Lucid, Motif and Windows frames
+@item (2) Lucid, Motif and MS-Windows frames
 
 @item (3) GTK+ and NS frames
 @end itemize
@@ -697,11 +701,11 @@ The @dfn{text area} of a frame is a somewhat fictitious area that can be
 embedded in the native frame.  Its position is unspecified.  Its width
 can be obtained by removing from that of the native width the widths of
 the internal border, one vertical scroll bar, and one left and one right
-fringe as specified for this frame, see @ref{Layout Parameters}.  Its
-height can be obtained by removing from that of the native height the
-widths of the internal border and the heights of the frame's internal
-menu and tool bars and one horizontal scroll bar as specified for this
-frame.
+fringe if they are specified for this frame, see @ref{Layout
+Parameters}.  Its height can be obtained by removing from that of the
+native height the widths of the internal border and the heights of the
+frame's internal menu and tool bars and one horizontal scroll bar if
+specified for this frame.
 @end table
 
 @cindex absolute position
@@ -715,7 +719,7 @@ horizontal and vertical pixel offsets relative to an origin (0, 0) of
 the frame's display.  Correspondingly, the @dfn{absolute edges} of a
 frame are given as pixel offsets from that origin.
 
-  Note that with multiple monitors the origin of the display does not
+  Note that with multiple monitors, the origin of the display does not
 necessarily coincide with the top-left corner of the entire usable
 display area of the terminal.  Hence the absolute position of a frame
 can be negative in such an environment even when that frame is
@@ -724,7 +728,7 @@ completely visible.
   By convention, vertical offsets increase ``downwards''.  This means
 that the height of a frame is obtained by subtracting the offset of its
 top edge from that of its bottom edge.  Horizontal offsets increase
-``leftwards'' as expected so a frame's width is calculated by
+``rightwards'', as expected, so a frame's width is calculated by
 subtracting the offset of its left edge from that of its right edge.
 
   For a frame on a graphical terminal the following function returns the
@@ -734,9 +738,10 @@ sizes of the areas described above:
 This function returns geometric attributes of @var{frame}.  The return
 value is an association list of the attributes listed below.  All
 coordinate, height and width values are integers counting pixels.  Note
-that if @var{frame} has not been mapped (@pxref{Visibility of Frames})
-yet, some of the return values may only represent approximations of the
-actual values---those that can be seen after the frame has been mapped.
+that if @var{frame} has not been mapped yet, (@pxref{Visibility of
+Frames}) some of the return values may only represent approximations of
+the actual values---those that can be seen after the frame has been
+mapped.
 
 @table @code
 @item outer-position
@@ -792,10 +797,10 @@ native and inner frame.
 @defun frame-edges &optional frame type
 This function returns the absolute edges of the outer, native or inner
 frame of @var{frame}.  @var{frame} must be a live frame and defaults to
-the selected one.  The list returned has the form (@var{left} @var{top}
-@var{right} @var{bottom}) where all values are in pixels relative to the
-origin of @var{frame}'s display.  For terminal frames the values
-returned for @var{left} and @var{top} are always zero.
+the selected one.  The returned list has the form @w{@code{(@var{left}
+@var{top} @var{right} @var{bottom})}} where all values are in pixels
+relative to the origin of @var{frame}'s display.  For terminal frames
+the values returned for @var{left} and @var{top} are always zero.
 
 Optional argument @var{type} specifies the type of the edges to return:
 @code{outer-edges} means to return the outer edges of @var{frame},
@@ -803,14 +808,15 @@ Optional argument @var{type} specifies the type of the edges to return:
 @code{inner-edges} means to return its inner edges.
 
 By convention, the pixels of the display at the values returned for
-@var{left} and @var{top} are inside (part of) @var{frame}.  Hence, if
-@var{left} and @var{top} are both zero, the pixel at the display's
-origin is part of @var{frame}.  The pixels at @var{bottom} and
-@var{right}, on the other hand, lie immediately outside @var{frame}.
-This means that if you have, for example, two side-by-side frames
-positioned such that the right outer edge of the frame on the left
-equals the left outer edge of the frame on the right, the pixels at that
-edge show a part of the frame on the right.
+@var{left} and @var{top} are considered to be inside (part of)
+@var{frame}.  Hence, if @var{left} and @var{top} are both zero, the
+pixel at the display's origin is part of @var{frame}.  The pixels at
+@var{bottom} and @var{right}, on the other hand, are considered to lie
+immediately outside @var{frame}.  This means that if you have, for
+example, two side-by-side frames positioned such that the right outer
+edge of the frame on the left equals the left outer edge of the frame on
+the right, the pixels at that edge show a part of the frame on the
+right.
 @end defun
 
 
@@ -878,21 +884,21 @@ Geometry}).  The position of a child frame (@pxref{Child Frames}) is
 specified via pixel offsets of its outer edges relative to the native
 position of its parent frame.
 
-  You can read or change the position of a frame using the frame
+  You can access or change the position of a frame using the frame
 parameters @code{left} and @code{top} (@pxref{Position Parameters}).
 Here are two additional functions for working with the positions of an
 existing, visible frame.  For both functions, the argument @var{frame}
 must denote a live frame and defaults to the selected frame.
 
 @defun frame-position &optional frame
-For a normal, non-child frame this function returns a cons of the (X, Y)
-pixel coordinates of its outer position (@pxref{Frame Layout}) with
-respect to the origin (0, 0) of its display.  For a child frame
+For a normal, non-child frame this function returns a cons of the pixel
+coordinates of its outer position (@pxref{Frame Layout}) with respect to
+the origin @code{(0, 0)} of its display.  For a child frame
 (@pxref{Child Frames}) this function returns the pixel coordinates of
-its outer position with respect to an origin (0, 0) at the native
+its outer position with respect to an origin @code{(0, 0)} at the native
 position of @var{frame}'s parent.
 
-Negative return values never indicate an offset from the right or bottom
+Negative values never indicate an offset from the right or bottom
 edge of @var{frame}'s display or parent frame.  Rather, they mean that
 @var{frame}'s outer position is on the left and/or above the origin of
 its display or the native position of its parent frame.  This usually
@@ -907,7 +913,7 @@ On a text terminal frame both values are zero.
 @defun set-frame-position frame x y
 This function sets the outer frame position of @var{frame} to (@var{x},
 @var{y}).  The latter arguments specify pixels and normally count from
-an origin at the position (0, 0) of @var{frame}'s display.  For child
+the origin at the position (0, 0) of @var{frame}'s display.  For child
 frames, they count from the native position of @var{frame}'s parent
 frame.
 
@@ -921,14 +927,15 @@ edge of @var{frame} exactly at the right or bottom edge of its display
 or parent frame.  Neither do they allow to specify a position that does
 not lie within the edges of the display or parent frame.  The frame
 parameters @code{left} and @code{top} (@pxref{Position Parameters})
-allow to do that but may still fail to provide good results for the
+allow to do that, but may still fail to provide good results for the
 initial or a new frame.
 
 This function has no effect on text terminal frames.
 @end defun
 
 @defvar move-frame-functions
-This hook specifies the functions run when an Emacs frame is moved
+@cindex frame position changes, a hook
+This hook specifies the functions that are run when an Emacs frame is moved
 (assigned a new position) by the window-system or window manager.  The
 functions are run with one argument, the frame that moved.  For a child
 frame (@pxref{Child Frames}), the functions are run only when the
@@ -954,8 +961,8 @@ This means that in general you cannot use the native size to specify the
 initial size of a frame.  As soon as you know the native size of a
 visible frame, you can calculate its outer size (@pxref{Frame Layout})
 by adding in the remaining components from the return value of
-@code{frame-geometry} .  For invisible frames or for frames that have
-yet to be created, however, the outer size can be estimated only.  This
+@code{frame-geometry}.  For invisible frames or for frames that have
+yet to be created, however, the outer size can only be estimated.  This
 also means that calculating an exact initial position of a frame
 specified via offsets from the right or bottom edge of the screen
 (@pxref{Frame Position}) is impossible.
@@ -1006,8 +1013,8 @@ leaving some empty space below and/or on the right of the frame.  The
 following option may help in that case.
 
 @defopt frame-resize-pixelwise
-If this option is @code{nil}, a frame's text pixel size is usually
-rounded to a multiple of the current values of that frame's
+If this option is @code{nil} (the default), a frame's text pixel size is
+usually rounded to a multiple of the current values of that frame's
 @code{frame-char-height} and @code{frame-char-width} whenever the frame
 is resized.  If this is non-@code{nil}, no rounding occurs, hence frame
 sizes can increase/decrease by one pixel.
@@ -1747,6 +1754,8 @@ If non-@code{nil}, this frame's window is never split automatically.
 
 @node Frame Interaction Parameters
 @subsubsection Frame Interaction Parameters
+@cindex frame interaction parameters
+@cindex interaction parameters between frames
 
 These parameters supply forms of interactions between different frames.
 
@@ -1754,7 +1763,7 @@ These parameters supply forms of interactions between different frames.
 @vindex parent-frame, a frame parameter
 @item parent-frame
 If non-@code{nil}, this means that this frame is a child frame
-(@pxref{Child Frames}) and this parameter specifies its parent frame.
+(@pxref{Child Frames}), and this parameter specifies its parent frame.
 If nil, this means that this frame is a normal, top-level frame.
 
 @vindex delete-before, a frame parameter
@@ -1852,13 +1861,13 @@ display bugs or pine for that retro, flicker-y feeling.
 If non-@code{nil}, this tells the window manager to remove the frame's
 icon from the taskbar associated with the frame's display and inhibit
 switching to the frame's window via the combination @kbd{Alt-@key{TAB}}.
-On Windows, iconifying such a frame will "roll in" its window-system
+On MS-Windows, iconifying such a frame will "roll in" its window-system
 window at the bottom of the desktop.  Some window managers may not honor
 this parameter.
 
 @vindex no-focus-on-map, a frame parameter
 @item no-focus-on-map
-If non-@code{nil}, this means that the frame dos not want to receive
+If non-@code{nil}, this means that the frame does not want to receive
 input focus when it is mapped (@pxref{Visibility of Frames}).  Some
 window managers may not honor this parameter.
 
@@ -1875,8 +1884,8 @@ this parameter.
 @vindex undecorated, a frame parameter
 @item undecorated
 If non-@code{nil}, this frame's window-system window is drawn without
-decorations like title, minimize/maximize boxes and external borders.
-This usually means that the window cannot be dragged, resized,
+decorations, like the title, minimize/maximize boxes and external
+borders.  This usually means that the window cannot be dragged, resized,
 iconified, maximized or deleted with the mouse.  If nil, the frame's
 window is usually drawn with all the elements listed above unless their
 display has been suspended via window manager settings.
@@ -2266,8 +2275,8 @@ frame.
 It first deletes any child frame of @var{frame} (@pxref{Child Frames})
 and any frame whose @code{delete-before} frame parameter (@pxref{Frame
 Interaction Parameters}) specifies @var{frame}.  All such deletions are
-performed recursively; so this step makes sure that there will not exist
-any other frames with @var{frame} as their ancestor.  Then, unless
+performed recursively; so this step makes sure that there no other
+frames with @var{frame} as their ancestor will exist.  Then, unless
 @var{frame} specifies a tooltip, this function runs the hook
 @code{delete-frame-functions} (each function getting one argument,
 @var{frame}) before actually killing the frame.
@@ -2468,7 +2477,7 @@ non-@code{nil}, means to avoid making @var{frame}'s window-system window
 the ``active'' window which should insist a bit more on avoiding to
 raise @var{frame} above other frames.
 
-On Windows the @var{noactivate} argument has no effect.  However, if
+On MS-Windows the @var{noactivate} argument has no effect.  However, if
 @var{frame} is a child frame (@pxref{Child Frames}), this function
 usualy does focus @var{frame} without raising it above other child
 frames.
@@ -2593,7 +2602,7 @@ Note that this option does not distinguish ``sloppy'' focus (where the
 frame that previously had focus retains focus as long as the mouse
 pointer does not move into another window manager window) from
 ``strict'' focus (where a frame immediately loses focus when it's left
-by the mouse pointer).  It neither recognizes whether your window
+by the mouse pointer).  Neither does it recognize whether your window
 manager supports delayed focusing or auto-raising where you can
 explicitly specify the time until a new frame gets focus or is
 auto-raised.
@@ -2656,7 +2665,7 @@ you can do that with @code{raise-frame} if you wish (@pxref{Raising and
 Lowering}).
 
 Making a frame visible usually makes all its child frames (and their
-descendants) visible too (@pxref{Child Frames}).
+descendants) visible as well (@pxref{Child Frames}).
 @end deffn
 
 @deffn Command make-frame-invisible &optional frame force
@@ -2691,6 +2700,7 @@ selected frame.
 @cindex restacking a frame
 @cindex frame stacking order
 @cindex frame Z-order
+@cindex Z-order
   Most window systems use a desktop metaphor.  Part of this metaphor is
 the idea that system-level windows (representing, e.g., Emacs frames)
 are stacked in a notional third dimension perpendicular to the screen
@@ -2865,8 +2875,8 @@ frame does not show a menu or tool bar, any other of the frame's borders
 (@pxref{Layout Parameters}) can be used instead of the external borders.
 
   In particular, under X (but not when building with GTK+), the frame's
-outer border can be used.  On Windows, specifying a non-zero outer
-border width will show a one pixel wide external border.  Under all
+outer border can be used.  On MS-Windows, specifying a non-zero outer
+border width will show a one-pixel wide external border.  Under all
 window-systems, the internal border can be used.  In either case, it's
 advisable to disable a child frame's window manager decorations with the
 @code{undecorated} frame parameter @pxref{Management Parameters}).
@@ -2902,9 +2912,9 @@ policy to child frames.  Customizing @code{mouse-autoselect-window} can
 help in this regard (@pxref{Mouse Window Auto-selection}).
 
 @item
-Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed too
+Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed to
 work on all window-systems.  Some will drop the object on the parent
-frame or some ancestor instead.
+frame or on some ancestor instead.
 @end itemize
 
   The following two functions may be useful when working with child and
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 931d1060d5d..fed2dea7572 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1752,9 +1752,9 @@ whenever a window gets selected more ``permanently''.
 not related to window management, it will usually make sense to save the
 value of the selected window somewhere and compare it with the value of
 @code{selected-window} while running that hook.  Also, to avoid false
-positives when using @code{buffer-list-update-hook} it is good practice
+positives when using @code{buffer-list-update-hook}, it is good practice
 that every @code{select-window} call supposed to select a window only
-temporarily, passes a non-@code{nil} @var{norecord} argument.  If
+temporarily passes a non-@code{nil} @var{norecord} argument.  If
 possible, the macro @code{with-selected-window} (see below) should be
 used in such cases.
 
@@ -4623,7 +4623,7 @@ Any other non-@code{nil} value means to select a window instantaneously
 as soon as the mouse pointer enters it.
 @end table
 
-In either case the mouse pointer must enter the text area of a window in
+In either case, the mouse pointer must enter the text area of a window in
 order to trigger its selection.  Dragging the scroll bar slider or the
 mode line of a window conceptually should not cause its auto-selection.