4 files changed, 787 insertions, 406 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9e9f8e3ca45..ae59bbbdefa 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1897,9 +1897,9 @@ to or less than the display width of @var{ellipsis}.  If
 
 The following function returns the size in pixels of text as if it were
 displayed in a given window.  This function is used by
-@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and
-@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window
-exactly as large as the text it contains.
+@code{fit-window-to-buffer} and @code{fit-frame-to-buffer}
+(@pxref{Resizing Windows}) to make a window exactly as large as the text
+it contains.
 
 @defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
 This function returns the size of the text of @var{window}'s buffer in
@@ -1952,12 +1952,12 @@ height of both, if present, in the return value.
 contents of the line, plus optional additional vertical line spacing
 above or below the display line.
 
-  The height of the line contents is the maximum height of any
-character or image on that display line, including the final newline
-if there is one.  (A display line that is continued doesn't include a
-final newline.)  That is the default line height, if you do nothing to
-specify a greater height.  (In the most common case, this equals the
-height of the default frame font.)
+  The height of the line contents is the maximum height of any character
+or image on that display line, including the final newline if there is
+one.  (A display line that is continued doesn't include a final
+newline.)  That is the default line height, if you do nothing to specify
+a greater height.  (In the most common case, this equals the height of
+the corresponding frame's default font, see @ref{Frame Font}.)
 
   There are several ways to explicitly specify a larger line height,
 either by specifying an absolute height for the display line, or by
@@ -5406,12 +5406,11 @@ This removes only images that were put into @var{buffer} the way
 @cindex size of image
 This function returns the size of an image as a pair
 @w{@code{(@var{width} . @var{height})}}.  @var{spec} is an image
-specification.  @var{pixels} non-@code{nil} means return sizes
-measured in pixels, otherwise return sizes measured in canonical
-character units (fractions of the width/height of the frame's default
-font).  @var{frame} is the frame on which the image will be displayed.
-@var{frame} null or omitted means use the selected frame (@pxref{Input
-Focus}).
+specification.  @var{pixels} non-@code{nil} means return sizes measured
+in pixels, otherwise return sizes measured in the default character size
+of @var{frame} (@pxref{Frame Font}).  @var{frame} is the frame on which
+the image will be displayed.  @var{frame} null or omitted means use the
+selected frame (@pxref{Input Focus}).
 @end defun
 
 @defvar max-image-size
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index a32c69c1c2f..9044fbaec56 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1041,6 +1041,7 @@ Frames
 
 * Creating Frames::         Creating additional frames.
 * Multiple Terminals::      Displaying on several different devices.
+* Frame Geometry::          Geometric properties of frames.
 * Frame Parameters::        Controlling frame size, position, font, etc.
 * Terminal Parameters::     Parameters common for all frames on terminal.
 * Frame Titles::            Automatic updating of frame titles.
@@ -1064,12 +1065,18 @@ Frames
 * Resources::               Getting resource values from the server.
 * Display Feature Testing:: Determining the features of a terminal.
 
+Frame Geometry
+
+* Frame Layout::            Basic layout of frames.
+* Frame Font::              The default font of a frame and how to set it.
+* Size and Position::       Changing the size and position of a frame.
+* Implied Frame Resizing::  Implied resizing of frames and how to prevent it.
+
 Frame Parameters
 
 * Parameter Access::        How to change a frame's parameters.
 * Initial Parameters::      Specifying frame parameters when you make a frame.
 * Window Frame Parameters:: List of frame parameters for window systems.
-* Size and Position::       Changing the size and position of a frame.
 * Geometry::                Parsing geometry specifications.
 
 Window Frame Parameters
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 79b5172ae0b..28e6fbdfef4 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -80,6 +80,7 @@ for @code{framep} above.
 @menu
 * Creating Frames::             Creating additional frames.
 * Multiple Terminals::          Displaying on several different devices.
+* Frame Geometry::              Geometric properties of frames.
 * Frame Parameters::            Controlling frame size, position, font, etc.
 * Terminal Parameters::         Parameters common for all frames on terminal.
 * Frame Titles::                Automatic updating of frame titles.
@@ -416,6 +417,545 @@ This function returns the attributes of the physical monitor
 dominating (see above) @var{frame}, which defaults to the selected frame.
 @end defun
 
+
+@node Frame Geometry
+@section Frame Geometry
+@cindex frame geometry
+@cindex frame position
+@cindex position of frame
+@cindex frame size
+@cindex size of frame
+
+The geometry of a frame depends on the toolkit that was used to build
+this instance of Emacs and the terminal that displays the frame.  This
+chapter describes these dependencies and some of the functions to deal
+with them.  Note that the @var{frame} argument of all of these functions
+has to specify a live frame (@pxref{Deleting Frames}).  If omitted or
+@code{nil}, it specifies the selected frame (@pxref{Input Focus}).
+
+@menu
+* Frame Layout::            Basic layout of frames.
+* Frame Font::              The default font of a frame and how to set it.
+* Size and Position::       Changing the size and position of a frame.
+* Implied Frame Resizing::  Implied resizing of frames and how to prevent it.
+@end menu
+
+
+@node Frame Layout
+@subsection Frame Layout
+@cindex frame layout
+@cindex layout of frame
+
+The drawing below sketches the layout of a frame on a graphical
+terminal:
+@smallexample
+@group
+
+        <------------ Outer Frame Width ----------->
+        ___________________________________________
+     ^(0)  ___________ External Border __________   |
+     | |  |_____________ Title Bar ______________|  |
+     | | (1)_____________ Menu Bar ______________|  | ^
+     | | (2)_____________ Tool Bar ______________|  | ^
+     | | (3) _________ Internal Border ________  |  | ^
+     | |  | |   ^                              | |  | |
+     | |  | |   |                              | |  | |
+Outer  |  | | Inner                            | |  | Native
+Frame  |  | | Frame                            | |  | Frame
+Height |  | | Height                           | |  | Height
+     | |  | |   |                              | |  | |
+     | |  | |<--+--- Inner Frame Width ------->| |  | |
+     | |  | |   |                              | |  | |
+     | |  | |___v______________________________| |  | |
+     | |  |___________ Internal Border __________|  | v
+     v |______________ External Border _____________|
+           <-------- Native Frame Width -------->
+
+@end group
+@end smallexample
+
+In practice not all of the areas shown in the drawing will or may be
+present.  The meaning of these areas is:
+
+@table @samp
+@item Outer Frame
+@cindex outer frame
+@cindex outer edges
+@cindex outer width
+@cindex outer height
+The @dfn{outer frame} is a rectangle comprising all areas shown in the
+drawing.  The edges of that rectangle are called the @dfn{outer edges}
+of the frame.  The @dfn{outer width} and @dfn{outer height} of the frame
+specify the size of that rectangle.
+
+@cindex outer position
+The upper left corner of the outer frame (indicated by ``(0)'' in the
+drawing above) is the @dfn{outer position} or the frame.  It is
+specified by and settable via the @code{left} and @code{top} frame
+parameters (@pxref{Position Parameters}) as well as the functions
+@code{frame-position} and @code{set-frame-position} (@pxref{Size and
+Position}).
+
+@item External Border
+@cindex external border
+The @dfn{external border} is part of the decorations supplied by the
+window manager.  It's typically used for resizing the frame with the
+mouse.  The external border is normally not shown on ``fullboth'' and
+maximized frames (@pxref{Size Parameters}) and doesn't exist for text
+terminal frames.
+
+   The external border should not be confused with the @dfn{outer
+border} specified by the @code{border-width} frame parameter
+(@pxref{Layout Parameters}).  Since the outer border is usually ignored
+on most platforms it is not covered here.
+
+@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.  The title
+bar is usually not displayed on ``fullboth'' (@pxref{Size Parameters})
+or tooltip frames.  Title bars don't exist for text terminal frames.
+
+@item Menu Bar
+@cindex internal menu bar
+@cindex external menu bar
+The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs
+itself) or external (drawn by a toolkit).  Most builds (GTK+, Lucid,
+Motif and Windows) rely on an external menu bar.  NS also uses an
+external menu bar which, however, is not part of the outer frame.
+Non-toolkit builds can provide an internal menu bar.  On text terminal
+frames, the menu bar is part of the frame's root window (@pxref{Windows
+and Frames}).
+
+@item Tool Bar
+@cindex internal tool bar
+@cindex external tool bar
+Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either
+internal (drawn by Emacs itself) or external (drawn by a toolkit).  The
+GTK+ and NS builds have the tool bar drawn by the toolkit.  The
+remaining builds use internal tool bars.  With GTK+ the tool bar can be
+located on either side of the frame, immediately outside the internal
+border, see below.
+
+@item Native Frame
+@cindex native frame
+@cindex native edges
+@cindex native width
+@cindex native height
+@cindex display area
+The @dfn{native frame} is a rectangle located entirely within the outer
+frame.  It excludes the areas occupied by the external border, the title
+bar and any external menu or external tool bar.  The area enclosed by
+the native frame is sometimes also referred to as the @dfn{display area}
+of the frame.  The edges of the native frame are called the @dfn{native
+edges} of the frame.  The @dfn{native width} and @dfn{native height} of
+the frame specify the size of the rectangle.
+
+@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:
+
+@itemize @w
+@item (1) non-toolkit and terminal frames
+
+@item (2) Lucid, Motif and Windows frames
+
+@item (3) GTK+ and NS frames
+@end itemize
+
+Accordingly, the native height of a frame includes the height of the
+tool bar but not that of the menu bar (Lucid, Motif, Windows) or those
+of the menu bar and the tool bar (non-toolkit and text terminal frames).
+
+The native position of a frame is the reference position of functions
+that set or return the current position of the mouse (@pxref{Mouse
+Position}) and for functions dealing with the position of windows like
+@code{window-edges}, @code{window-at} or @code{coordinates-in-window-p}
+(@pxref{Coordinates and Windows}).
+
+@item Internal Border
+The internal border (@pxref{Layout Parameters}) is a border drawn by
+Emacs around the inner frame (see below).
+
+@item Inner Frame
+@cindex inner frame
+@cindex inner edges
+@cindex inner width
+@cindex inner height
+The @dfn{inner frame} is the rectangle reserved for the frame's windows.
+It's enclosed by the internal border which, however, is not part of the
+inner frame.  Its edges are called the @dfn{inner edges} of the frame.
+The @dfn{inner width} and @dfn{inner height} specify the size of the
+rectangle.
+
+@cindex non-minibuffer frame
+@cindex minibuffer-only frame
+As a rule, the inner frame is subdivided into the frame's root window
+(@pxref{Windows and Frames}) and the frame's minibuffer window
+(@pxref{Minibuffer Windows}).  There are two notable exceptions to this
+rule: A @dfn{non-minibuffer frame} contains a root window only and does
+not contain a minibuffer window.  A @dfn{minibuffer-only frame} contains
+only a minibuffer window which also serves as that frame's root window.
+See @ref{Initial Parameters} for how to create such frame
+configurations.
+
+@item Text Area
+@cindex text area
+The @dfn{text area} of a frame is a somewhat fictitious area located
+entirely within the native frame.  It can be obtained by removing from
+the native frame any internal borders, one vertical and one horizontal
+scroll bar, and one left and one right fringe as specified for this
+frame, see @ref{Layout Parameters}.
+@end table
+
+@cindex absolute position
+The @dfn{absolute position} of a frame or its edges is usually given in
+terms of pixels counted from an origin at position (0, 0) of the frame's
+display.  Note that with multiple monitors the origin does not
+necessarily coincide with the top left corner of the entire usable
+display area.  Hence the absolute outer position of a frame or the
+absolute positions of the edges of the outer, native or inner frame can
+be negative in such an environment even when that frame is completely
+visible.
+
+  For a frame on a graphical terminal the following function returns the
+sizes of the areas described above:
+
+@defun x-frame-geometry &optional frame
+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.
+
+@table @code
+@item outer-position
+A cons of the absolute X- and Y-coordinates of the outer position of
+@var{frame}, relative to the origin at position (0, 0) of @var{frame}'s
+display.
+
+@item outer-size
+A cons of the outer width and height of @var{frame}.
+
+@item external-border-size
+A cons of the horizontal and vertical width of @var{frame}'s external
+borders as supplied by the window manager.  If the window manager
+doesn't supply these values, Emacs will try to guess them from the
+coordinates of the outer and inner frame.
+
+@item title-bar-size
+A cons of the width and height of the title bar of @var{frame} as
+supplied by the window manager or operating system.  If both of them are
+zero, the frame has no title bar.  If only the width is zero, Emacs was
+not able to retrieve the width information.
+
+@item menu-bar-external
+If non-@code{nil}, this means the menu bar is external (not part of the
+native frame of @var{frame}).
+
+@item menu-bar-size
+A cons of the width and height of the menu bar of @var{frame}.
+
+@item tool-bar-external
+If non-@code{nil}, this means the tool bar is external (not part of the
+native frame of @var{frame}).
+
+@item tool-bar-position
+This tells on which side the tool bar on @var{frame} is and can be one
+of @code{left}, @code{top}, @code{right} or @code{bottom}.  The only
+toolkit that currently supports a value other than @code{top} is GTK+.
+
+@item tool-bar-size
+A cons of the width and height of the tool bar of @var{frame}.
+
+@item internal-border-width
+The width of the internal border of @var{frame}.
+@end table
+@end defun
+
+The following function can be used to retrieve the edges of the outer,
+native and inner frame.
+
+@defun frame-edges &optional frame type
+This function returns the 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
+position (0, 0) of @var{frame}'s display.  For terminal frames
+@var{left} and @var{top} are both zero.
+
+Optional argument @var{type} specifies the type of the edges to return:
+@var{type} @code{outer-edges} means to return the outer edges of
+@var{frame}, @code{native-edges} (or @code{nil}) means to return its
+native edges and @code{inner-edges} means to return its inner edges.
+
+Notice that the ``pixels at the positions'' @var{bottom} and @var{right}
+lie immediately outside the corresponding 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 ``representing'' that edge are part
+of the frame on the right.
+@end defun
+
+
+@node Frame Font
+@subsection Frame Font
+@cindex default font
+@cindex default character size
+@cindex default character width
+@cindex default width of character
+@cindex default character height
+@cindex default height of character
+Each frame has a @dfn{default font} which specifies the default
+character size for that frame.  This size is meant when retrieving or
+changing the size of a frame in terms of ``columns'' or ``lines''
+(@pxref{Size Parameters}).  It is also used when resizing (@pxref{Window
+Sizes}) or splitting (@pxref{Splitting Windows}) windows.
+
+@cindex line height
+@cindex column width
+The term @dfn{line height} is sometimes used instead of ``default
+character height''.  Similarly, the term @dfn{column width} is used as
+shorthand for ``default character width''.
+
+@defun frame-char-height &optional frame
+@defunx frame-char-width &optional frame
+These functions return the default height and width of a character in
+@var{frame}, measured in pixels.  Together, these values establish the
+size of the default font on @var{frame}.  The values depend on the
+choice of font for @var{frame}, see @ref{Font and Color Parameters}.
+@end defun
+
+The default font can be also set directly with the following function:
+
+@deffn Command set-frame-font font &optional keep-size frames
+This sets the default font to @var{font}.  When called interactively, it
+prompts for the name of a font, and uses that font on the selected
+frame.  When called from Lisp, @var{font} should be a font name (a
+string), a font object, font entity, or a font spec.
+
+If the optional argument @var{keep-size} is @code{nil}, this keeps the
+number of frame lines and columns fixed.  (If non-@code{nil}, the option
+@code{frame-inhibit-implied-resize} described in the next section will
+override this.)  If @var{keep-size} is non-@code{nil} (or with a prefix
+argument), it tries to keep the size of the display area of the current
+frame fixed by adjusting the number of lines and columns.
+
+If the optional argument @var{frames} is @code{nil}, this applies the
+font to the selected frame only.  If @var{frames} is non-@code{nil}, it
+should be a list of frames to act upon, or @code{t} meaning all existing
+graphical frames.
+@end deffn
+
+
+@node Size and Position
+@subsection Size and Position
+@cindex frame size
+@cindex frame position
+@cindex position of frame
+
+You can read or change the position of a frame using the frame
+parameters @code{left} and @code{top} (@pxref{Position Parameters}) and
+its size using the @code{height} and @code{width} parameters
+(@pxref{Size Parameters}).  Here are some special features for working
+with sizes and positions.  For all of these functions the argument
+@var{frame} must denote a live frame and defaults to the selected frame.
+
+@defun frame-position &optional Lisp_Object &optional frame
+This function returns the outer position (@pxref{Frame Layout}) of
+@var{frame} in pixels.  The value is a cons giving the coordinates of
+the top left corner of the outer frame of @var{frame} relative to an
+origin at the position (0, 0) of the frame's display.  On a text
+terminal frame both values are zero.
+@end defun
+
+@defun set-frame-position frame X Y
+This function sets the outer frame position of @var{frame} to @var{X}
+and @var{Y}.  The latter arguments specify pixels and normally count
+from an origin at the position (0, 0) of @var{frame}'s display.
+
+A negative parameter value positions the right edge of the outer frame
+by @var{-x} pixels left from the right edge of the screen or the bottom
+edge by @var{-y} pixels up from the bottom edge of the screen.
+
+This function has no effect on text terminal frames.
+@end defun
+
+@defun frame-pixel-height &optional frame
+@defunx frame-pixel-width &optional frame
+   These functions return the inner height and width (the height and
+width of the display area, see @ref{Frame Layout}) of @var{frame} in
+pixels.  For a text terminal, the results are in characters rather than
+pixels.
+@end defun
+
+@defun frame-text-height &optional frame
+@defunx frame-text-width &optional frame
+These functions return the height and width of the text area of
+@var{frame} (@pxref{Frame Layout}), measured in pixels.  For a text
+terminal, the results are in characters rather than pixels.
+
+The value returned by @code{frame-text-height} differs from that
+returned by @code{frame-pixel-height} by not including the heights of
+any internal tool bar or menu bar, the height of one horizontal scroll
+bar and the widths of the internal border.
+
+The value returned by @code{frame-text-width} differs from that returned
+by @code{frame-pixel-width} by not including the width of one vertical
+scroll bar, the widths of one left and one right fringe and the widths
+of the internal border.
+@end defun
+
+@defun frame-height &optional frame
+@defunx frame-width &optional frame
+These functions return the height and width of the text area of
+@var{frame}, measured in units of the default font height and width of
+@var{frame} (@pxref{Frame Font}).  These functions are plain shorthands
+for writing @code{(frame-parameter frame 'height)} and
+@code{(frame-parameter frame 'width)}.
+
+If the text area of @var{frame} measured in pixels is not a multiple of
+its default font size, the values returned by these functions are
+rounded down to the number of characters of the default font that fully
+fit into the text area.
+@end defun
+
+@defopt frame-resize-pixelwise
+If this option is @code{nil}, a frame's 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.
+
+Setting this variable usually causes the next resize operation to pass
+the corresponding size hints to the window manager.  This means that
+this variable should be set only in a user's initial file; applications
+should never bind it temporarily.
+
+The precise meaning of a value of @code{nil} for this option depends on
+the toolkit used.  Dragging the external border with the mouse is done
+character-wise provided the window manager is willing to process the
+corresponding size hints.  Calling @code{set-frame-size} (see below)
+with arguments that do not specify the frame size as an integer multiple
+of its character size, however, may: be ignored, cause a rounding
+(GTK+), or be accepted (Lucid, Motif, MS-Windows).
+
+With some window managers you may have to set this to non-@code{nil} in
+order to make a frame appear truly ``maximized'' or ``fullscreen''.
+@end defopt
+
+@defun set-frame-size frame width height pixelwise
+This function sets the size of the text area of @var{frame}, measured in
+terms of the canonical height and width of a character on @var{frame}
+(@pxref{Frame Font}).
+
+The optional argument @var{pixelwise} non-@code{nil} means to measure
+the new width and height in units of pixels instead.  Note that if
+@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
+fully honor the request if it does not increase/decrease the frame size
+to a multiple of its character size.
+@end defun
+
+@defun set-frame-height frame height &optional pretend pixelwise
+This function resizes the text area of @var{frame} to a height of
+@var{height} lines.  The sizes of existing windows in @var{frame} are
+altered proportionally to fit.
+
+If @var{pretend} is non-@code{nil}, then Emacs displays @var{height}
+lines of output in @var{frame}, but does not change its value for the
+actual height of the frame.  This is only useful on text terminals.
+Using a smaller height than the terminal actually implements may be
+useful to reproduce behavior observed on a smaller screen, or if the
+terminal malfunctions when using its whole screen.  Setting the frame
+height ``for real'' does not always work, because knowing the correct
+actual size may be necessary for correct cursor positioning on
+text terminals.
+
+The optional fourth argument @var{pixelwise} non-@code{nil} means that
+@var{frame} should be @var{height} pixels high.  Note that if
+@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
+fully honor the request if it does not increase/decrease the frame
+height to a multiple of its character height.
+@end defun
+
+@defun set-frame-width frame width &optional pretend pixelwise
+This function sets the width of the text area of @var{frame}, measured
+in characters.  The argument @var{pretend} has the same meaning as in
+@code{set-frame-height}.
+
+The optional fourth argument @var{pixelwise} non-@code{nil} means that
+@var{frame} should be @var{width} pixels wide.  Note that if
+@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
+fully honor the request if it does not increase/decrease the frame width
+to a multiple of its character width.
+@end defun
+
+None of these three functions will make a frame smaller than needed to
+display all of its windows together with their scroll bars, fringes,
+margins, dividers, mode and header lines.  This contrasts with requests
+by the window manager triggered, for example, by dragging the external
+border of a frame with the mouse.  Such requests are always honored by
+clipping, if necessary, portions that cannot be displayed at the right,
+bottom corner of the frame.
+
+
+@node Implied Frame Resizing
+@subsection Implied Frame Resizing
+@cindex implied frame resizing
+@cindex implied resizing of frame
+
+By default, Emacs tries to keep the number of lines and columns of a
+frame's text area unaltered when, for example, adding or removing the
+menu bar, changing the default font or setting the width of the frame's
+scroll bars.  This means, however, that in such case Emacs must ask the
+window manager to resize the outer frame in order to accommodate the
+size change.  Note that wrapping a menu or tool bar usually does not
+resize the frame's outer size, hence this will alter the number of
+displayed lines.
+
+   Occasionally, such @dfn{implied frame resizing} may be unwanted, for
+example, when the frame is maximized or made fullscreen (where it's
+turned off by default).  In other cases you can disable implied resizing
+with the following option:
+
+@defopt frame-inhibit-implied-resize
+If this option is @code{nil}, changing font, menu bar, tool bar,
+internal borders, fringes or scroll bars of a specific frame may
+implicitly resize the frame's display area in order to preserve the
+number of columns or lines the frame displays.  If this option is
+non-@code{nil}, no implied resizing is done.
+
+The value of this option can be also be a list of frame parameters.  In
+that case, implied resizing is inhibited when changing a parameter that
+appears in this list.  The frame parameters currently handled by this
+option are: @code{font}, @code{font-backend},
+@code{internal-border-width}, @code{menu-bar-lines} and
+@code{tool-bar-lines}.
+
+Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height},
+@code{vertical-scroll-bars}, @code{horizontal-scroll-bars},
+@code{left-fringe} and @code{right-fringe} frame parameters is handled
+as if the frame contained just one live window.  This means, for
+example, that removing vertical scroll bars on a frame containing
+several side by side windows will shrink the outer frame width by the
+width of one scroll bar provided this option is @code{nil} and keep it
+unchanged if this option is either @code{t} or a list containing
+@code{vertical-scroll-bars}.
+
+The default value is @code{'(tool-bar-lines)} for Lucid, Motif and
+Windows (which means that adding/removing a tool bar there does not
+change the outer frame height), @code{nil} on all other window systems
+including GTK+ (which means that changing any of the parameters listed
+above may change the size of the outer frame), and @code{t} otherwise
+(which means the outer frame size never changes implicitly when there's
+no window system support).
+
+Note that when a frame is not large enough to accommodate a change of
+any of the parameters listed above, Emacs may try to enlarge the frame
+even if this option is non-@code{nil}.
+@end defopt
+
+
 @node Frame Parameters
 @section Frame Parameters
 @cindex frame parameters
@@ -438,7 +978,6 @@ frame transparency, the parameter @code{alpha} is also meaningful.
 * Parameter Access::       How to change a frame's parameters.
 * Initial Parameters::     Specifying frame parameters when you make a frame.
 * Window Frame Parameters:: List of frame parameters for window systems.
-* Size and Position::      Changing the size and position of a frame.
 * Geometry::               Parsing geometry specifications.
 @end menu
 
@@ -723,12 +1262,12 @@ pixel sizes of these character units (@pxref{Face Attributes}).
 @table @code
 @vindex height, a frame parameter
 @item height
-The height of the frame's text area (@pxref{Size and Position}), in
+The height of the frame's text area (@pxref{Frame Geometry}), in
 characters.
 
 @vindex width, a frame parameter
 @item width
-The width of the frame's text area (@pxref{Size and Position}), in
+The width of the frame's text area (@pxref{Frame Geometry}), in
 characters.
 
 @vindex user-size, a frame parameter
@@ -1183,309 +1722,6 @@ equivalent to the @code{:background} attribute of the
 @end table
 
 
-@node Size and Position
-@subsection Frame Size and Position
-@cindex size of frame
-@cindex screen size
-@cindex frame size
-@cindex resize frame
-
-You can read or change the size and position of a frame using the frame
-parameters @code{left}, @code{top}, @code{height}, and @code{width}.
-Whatever geometry parameters you don't specify are chosen by the window
-manager in its usual fashion.
-
-  Here are some special features for working with sizes and positions.
-Most of the functions described below use a @var{frame} argument which
-has to specify a live frame.  If omitted or @code{nil}, it specifies the
-selected frame, see @ref{Input Focus}.
-
-@defun set-frame-position frame left top
-This function sets the position of the top left corner of @var{frame} to
-@var{left} and @var{top}.  These arguments are measured in pixels, and
-normally count from the top left corner of the screen to the top left
-corner of the rectangle allotted to the frame by the window manager.
-
-Negative parameter values position the bottom edge of that rectangle up
-from the bottom edge of the screen, or the right rectangle edge to the
-left of the right edge of the screen.  It would probably be better if
-the values were always counted from the left and top, so that negative
-arguments would position the frame partly off the top or left edge of
-the screen, but it seems inadvisable to change that now.
-@end defun
-
-@cindex frame default font
-@cindex default font of a frame
-Each frame has a @dfn{default font} which specifies the canonical height
-and width of a character on that frame.  The default font is used when
-retrieving or changing the size of a frame in terms of columns or lines.
-It is also used when resizing (@pxref{Window Sizes}) or splitting
-(@pxref{Splitting Windows}) windows.
-
-@defun frame-char-height &optional frame
-@defunx frame-char-width &optional frame
-These functions return the canonical height and width of a character in
-@var{frame}, measured in pixels.  Together, these values establish the
-size of the default font on @var{frame}.  The values depend on the
-choice of font for @var{frame}, see @ref{Font and Color Parameters}.
-@end defun
-
-The default font can be also set directly with the following function:
-
-@deffn Command set-frame-font font &optional keep-size frames
-This sets the default font to @var{font}.  When called interactively, it
-prompts for the name of a font, and uses that font on the selected
-frame.  When called from Lisp, @var{font} should be a font name (a
-string), a font object, font entity, or a font spec.
-
-If the optional argument @var{keep-size} is @code{nil}, this keeps the
-number of frame lines and columns fixed.  (If non-@code{nil}, the option
-@code{frame-inhibit-implied-resize} described below will override this.)
-If @var{keep-size} is non-@code{nil} (or with a prefix argument), it
-tries to keep the size of the display area of the current frame fixed by
-adjusting the number of lines and columns.
-
-If the optional argument @var{frames} is @code{nil}, this applies the
-font to the selected frame only.  If @var{frames} is non-@code{nil}, it
-should be a list of frames to act upon, or @code{t} meaning all existing
-graphical frames.
-@end deffn
-
-@cindex frame display area
-@cindex display area of a frame
-The @dfn{display area} of a frame is a rectangular area within the area
-allotted to the frame by the window manager.  The display area neither
-includes the title bar (@pxref{Frame Titles}) nor any other decorations
-provided by the window manager (like an external border used for
-resizing frames via mouse dragging).
-
-   The actual height of the display area depends on the window-system
-and toolkit in use.  With GTK+, the display area does not include any
-tool bar or menu bar.  With the Motif or Lucid toolkits and with
-Windows, the display area includes the tool bar but not the menu bar.
-In a graphical version with no toolkit, it includes both the tool bar
-and menu bar.  On a text terminal, the display area includes the menu
-bar.
-
-@defun frame-pixel-height &optional frame
-@defunx frame-pixel-width &optional frame
-   These functions return the height and width of the display area of
-@var{frame}, measured in pixels.  For a text terminal, the results are
-in characters rather than pixels.
-@end defun
-
-@cindex frame text area
-@cindex text area of a frame
-   The @dfn{text area} of a frame is a concept implicitly used by all
-functions that change a frame's height or width.  It is a rectangle
-located within the display area.  Its size is obtained from that of the
-display area by subtracting the sizes of any tool or menu bars that are
-part of the display area, any internal borders, one vertical and one
-horizontal scroll bar, and one left and one right fringe as specified
-for this frame, see @ref{Layout Parameters}.
-
-@defun frame-text-height &optional frame
-@defunx frame-text-width &optional frame
-These functions return the height and width of the text area of
-@var{frame}, measured in pixels.  For a text terminal, the results are
-in characters rather than pixels.
-
-The value returned by @code{frame-text-height} differs from that
-returned by @code{frame-pixel-height} by not including the heights of
-any tool bar or menu bar, the height of one horizontal scroll bar and
-the widths of the internal border.
-
-The value returned by @code{frame-text-width} differs from that returned
-by @code{frame-pixel-width} by not including the width of one vertical
-scroll bar, the widths of one left and one right fringe and the widths
-of the internal border.
-@end defun
-
-@defun frame-height &optional frame
-@defunx frame-width &optional frame
-These functions return the height and width of the text area of
-@var{frame}, measured in units of the default font height and width of
-@var{frame}.  These functions are plain shorthands for writing
-@code{(frame-parameter frame 'height)} and @code{(frame-parameter frame
-'width)}.
-
-If the text area of @var{frame} measured in pixles is not a multiple of
-its default font size, the values returned by this functions are rounded
-down to the number of characters of the default font that fully fit into
-the text area.
-@end defun
-
-@defopt frame-resize-pixelwise
-If this option is @code{nil}, a frame's size is usually rounded to a
-multiple of the current values of that frame's @code{frame-char-height}
-and @code{frame-char-width}.  If this is non-@code{nil}, no rounding
-occurs, hence frame sizes can increase/decrease by one pixel.
-
-Setting this causes the next resize operation to pass the corresponding
-size hints to the window manager.  This means that this variable should
-be set only in a user's initial file; applications should never bind it
-temporarily.
-
-The precise meaning of a value of @code{nil} for this option depends
-on the toolkit used.  Dragging the frame border with the mouse is usually
-done character-wise.  Calling @code{set-frame-size} (see below)
-with arguments that do not specify the frame size as an integer multiple
-of its character size, however, may: be ignored, cause a
-rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows).
-
-With some window managers you may have to set this to non-@code{nil} in
-order to make a frame appear truly ``maximized'' or ``fullscreen''.
-@end defopt
-
-@defun set-frame-size frame width height pixelwise
-This function sets the size of the text area of @var{frame}, measured in
-characters; @var{width} and @var{height} specify the new width in
-columns and the new height in lines.
-
-The optional argument @var{pixelwise} non-@code{nil} means to measure
-the new width and height in units of pixels instead.  Note that if
-@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
-fully honor the request if it does not increase/decrease the frame size
-to a multiple of its character size.
-@end defun
-
-@defun set-frame-height frame height &optional pretend pixelwise
-This function resizes the text area of @var{frame} to a height of
-@var{height} lines.  The sizes of existing windows in @var{frame} are
-altered proportionally to fit.
-
-If @var{pretend} is non-@code{nil}, then Emacs displays @var{height}
-lines of output in @var{frame}, but does not change its value for the
-actual height of the frame.  This is only useful on text terminals.
-Using a smaller height than the terminal actually implements may be
-useful to reproduce behavior observed on a smaller screen, or if the
-terminal malfunctions when using its whole screen.  Setting the frame
-height ``for real'' does not always work, because knowing the correct
-actual size may be necessary for correct cursor positioning on
-text terminals.
-
-The optional fourth argument @var{pixelwise} non-@code{nil} means that
-@var{frame} should be @var{height} pixels high.  Note that if
-@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
-fully honor the request if it does not increase/decrease the frame
-height to a multiple of its character height.
-@end defun
-
-@defun set-frame-width frame width &optional pretend pixelwise
-This function sets the width of the text area of @var{frame}, measured
-in characters.  The argument @var{pretend} has the same meaning as in
-@code{set-frame-height}.
-
-The optional fourth argument @var{pixelwise} non-@code{nil} means that
-@var{frame} should be @var{width} pixels wide.  Note that if
-@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
-fully honor the request if it does not increase/decrease the frame width
-to a multiple of its character width.
-@end defun
-
-None of these three functions will make a frame smaller than needed to
-display all of its windows together with their scroll bars, fringes,
-margins, dividers, mode and header lines.  This contrasts with requests
-by the window manager triggered, for example, by dragging the external
-border of a frame with the mouse.  Such requests are always honored by
-clipping, if necessary, portions that cannot be displayed at the right,
-bottom corner of the frame.
-
-   By default, Emacs tries to keep the number of lines and columns of a
-frame's text area unaltered when, for example, adding or removing a menu
-bar, changing the default font or setting the width of the frame's
-scroll bars.  This means, however, that in such case Emacs must ask the
-window manager to resize the display area of the frame in order to
-accommodate the size change.  Note that wrapping a menu or tool bar
-usually does not resize the frame's display area, hence this will alter
-the number of displayed lines.
-
-   Occasionally, such implied resizing of the display area may be
-unwanted, for example, when the frame is maximized or made fullscreen
-where it's turned off by default.  In other cases you can disable
-implied resizing with the following option:
-
-@defopt frame-inhibit-implied-resize
-If this option is @code{nil}, changing font, menu bar, tool bar,
-internal borders, fringes or scroll bars of a specific frame may
-implicitly resize the frame's display area in order to preserve the
-number of columns or lines the frame displays.  If this option is
-non-@code{nil}, no implied resizing is done.
-
-The value of this option can be also be a list of frame parameters.  In
-that case, implied resizing is inhibited when changing a parameter that
-appears in this list.  The frame parameters currently handled by this
-option are: @code{font}, @code{font-backend},
-@code{internal-border-width}, @code{menu-bar-lines} and
-@code{tool-bar-lines}.
-
-Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height},
-@code{vertical-scroll-bars}, @code{horizontal-scroll-bars},
-@code{left-fringe} and @code{right-fringe} frame parameters is handled
-as if the frame contained just one live window.  This means, for
-example, that removing vertical scroll bars on a frame containing
-several side by side windows will shrink the frame width by the width of
-one scroll bar provided this option is @code{nil} and keep it unchanged
-if this option is either @code{t} or a list containing
-@code{vertical-scroll-bars}.
-
-The default value is @code{'(tool-bar-lines)} for Lucid, Motif and
-Windows (which means that adding/removing a tool bar there does not
-change the frame height), @code{nil} on all other window systems
-including GTK+ (which means that changing any of the parameters listed
-above may change the size of the frame), and @code{t} otherwise (which
-means the frame size never changes implicitly when there's no window
-system support).
-
-Note that when a frame is not large enough to accommodate a change of
-any of the parameters listed above, Emacs may try to enlarge the frame
-even if this option is non-@code{nil}.
-@end defopt
-
-@c FIXME?  Belongs more in Emacs manual than here?
-@c But, e.g., fit-window-to-buffer is in this manual.
-If you have a frame that displays only one window, you can fit that
-frame to its buffer using the command @code{fit-frame-to-buffer}.
-
-@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
-This command adjusts the size of @var{frame} to display the contents of
-its buffer exactly.  @var{frame} can be any live frame and defaults to
-the selected one.  Fitting is done only if @var{frame}'s root window is
-live.  The arguments @var{max-height}, @var{min-height}, @var{max-width}
-and @var{min-width} specify bounds on the new total size of
-@var{frame}'s root window.  @var{min-height} and @var{min-width} default
-to the values of @code{window-min-height} and @code{window-min-width}
-respectively.
-
-If the optional argument @var{only} is @code{vertically}, this function
-may resize the frame vertically only.  If @var{only} is
-@code{horizontally}, it may resize the frame horizontally only.
-@end deffn
-
-The behavior of @code{fit-frame-to-buffer} can be controlled with the
-help of the two options listed next.
-
-@defopt fit-frame-to-buffer-margins
-This option can be used to specify margins around frames to be fit by
-@code{fit-frame-to-buffer}.  Such margins can be useful to avoid, for
-example, that such frames overlap the taskbar.
-
-It specifies the numbers of pixels to be left free on the left, above,
-the right, and below a frame that shall be fit.  The default specifies
-@code{nil} for each which means to use no margins.  The value specified
-here can be overridden for a specific frame by that frame's
-@code{fit-frame-to-buffer-margins} parameter, if present.
-@end defopt
-
-@defopt fit-frame-to-buffer-sizes
-This option specifies size boundaries for @code{fit-frame-to-buffer}.
-It specifies the total maximum and minimum lines and maximum and minimum
-columns of the root window of any frame that shall be fit to its buffer.
-If any of these values is non-@code{nil}, it overrides the corresponding
-argument of @code{fit-frame-to-buffer}.
-@end defopt
-
-
 @node Geometry
 @subsection Geometry
 
@@ -2088,8 +2324,10 @@ give access to the current position of the mouse.
 @defun mouse-position
 This function returns a description of the position of the mouse.  The
 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
-and @var{y} are integers giving the position in characters relative to
-the top left corner of the inside of @var{frame}.
+and @var{y} are integers giving the (possibly rounded) position in
+multiples of the default character size of @var{frame} (@pxref{Frame
+Font}) relative to the native position of @var{frame} (@pxref{Frame
+Geometry}).
 @end defun
 
 @defvar mouse-position-function
@@ -2105,9 +2343,13 @@ This abnormal hook exists for the benefit of packages like
 @defun set-mouse-position frame x y
 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
 frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
-giving the position in characters relative to the top left corner of the
-inside of @var{frame}.  If @var{frame} is not visible, this function
-does nothing.  The return value is not significant.
+giving the position in multiples of the default character size of
+@var{frame} (@pxref{Frame Font}) relative to the native position of
+@var{frame} (@pxref{Frame Geometry}).
+
+The resulting mouse position is constrained to the native frame of
+@var{frame}.  If @var{frame} is not visible, this function does nothing.
+The return value is not significant.
 @end defun
 
 @defun mouse-pixel-position
@@ -2118,12 +2360,31 @@ coordinates in units of pixels rather than units of characters.
 @defun set-mouse-pixel-position frame x y
 This function warps the mouse like @code{set-mouse-position} except that
 @var{x} and @var{y} are in units of pixels rather than units of
-characters.  These coordinates are not required to be within the frame.
+characters.
 
-If @var{frame} is not visible, this function does nothing.  The return
-value is not significant.
+The resulting mouse position is not constrained to the native frame of
+@var{frame}.  If @var{frame} is not visible, this function does nothing.
+The return value is not significant.
 @end defun
 
+On a graphical terminal the following two functions allow to retrieve
+and set the absolute position of the mouse cursor.
+
+@defun x-mouse-absolute-pixel-position
+This function returns a cons cell (@var{x} . @var{y}) of the coordinates
+of the mouse cursor position in pixels, relative to a position (0, 0) of
+the selected frame's display.
+@end defun
+
+@defun x-set-mouse-absolute-pixel-position x y
+This function moves the mouse cursor to the position (@var{x}, @var{y}).
+The coordinates @var{x} and @var{y} are interpreted in pixels relative
+to a position (0, 0) of the selected frame's display.
+@end defun
+
+The following function can tell whether the mouse cursor is currently
+visible on a frame:
+
 @defun frame-pointer-visible-p &optional frame
 This predicate function returns non-@code{nil} if the mouse pointer
 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index ccfe7ffb7bc..b55a139a334 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -432,8 +432,8 @@ specified either in units of pixels or in units of lines and columns.
 On a graphical display, the latter actually correspond to the height and
 width of a ``default'' character specified by the frame's default font
 as returned by @code{frame-char-height} and @code{frame-char-width}
-(@pxref{Size and Position}).  Thus, if a window is displaying text with
-a different font or size, the reported line height and column width for
+(@pxref{Frame Font}).  Thus, if a window is displaying text with a
+different font or size, the reported line height and column width for
 that window may differ from the actual number of text lines or columns
 displayed within it.
 
@@ -791,8 +791,8 @@ 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}).
+@code{fit-frame-to-buffer} and
+@code{shrink-window-if-larger-than-buffer} (all listed below).
 
 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
@@ -836,8 +836,7 @@ resize operations (@pxref{Preserving Window Sizes}).
 
 If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
 this function will try to resize the frame of @var{window} to fit its
-contents by calling @code{fit-frame-to-buffer} (@pxref{Size and
-Position}).
+contents by calling @code{fit-frame-to-buffer} (see below).
 @end deffn
 
 @defopt fit-window-to-buffer-horizontally
@@ -858,6 +857,47 @@ live window and this option is non-@code{nil}.  If this is
 non-@code{nil} value means frames can be resized in both dimensions.
 @end defopt
 
+If you have a frame that displays only one window, you can fit that
+frame to its buffer using the command @code{fit-frame-to-buffer}.
+
+@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
+This command adjusts the size of @var{frame} to display the contents of
+its buffer exactly.  @var{frame} can be any live frame and defaults to
+the selected one.  Fitting is done only if @var{frame}'s root window is
+live.  The arguments @var{max-height}, @var{min-height}, @var{max-width}
+and @var{min-width} specify bounds on the new total size of
+@var{frame}'s root window.  @var{min-height} and @var{min-width} default
+to the values of @code{window-min-height} and @code{window-min-width}
+respectively.
+
+If the optional argument @var{only} is @code{vertically}, this function
+may resize the frame vertically only.  If @var{only} is
+@code{horizontally}, it may resize the frame horizontally only.
+@end deffn
+
+The behavior of @code{fit-frame-to-buffer} can be controlled with the
+help of the two options listed next.
+
+@defopt fit-frame-to-buffer-margins
+This option can be used to specify margins around frames to be fit by
+@code{fit-frame-to-buffer}.  Such margins can be useful to avoid, for
+example, that such frames overlap the taskbar.
+
+It specifies the numbers of pixels to be left free on the left, above,
+the right, and below a frame that shall be fit.  The default specifies
+@code{nil} for each which means to use no margins.  The value specified
+here can be overridden for a specific frame by that frame's
+@code{fit-frame-to-buffer-margins} parameter, if present.
+@end defopt
+
+@defopt fit-frame-to-buffer-sizes
+This option specifies size boundaries for @code{fit-frame-to-buffer}.
+It specifies the total maximum and minimum lines and maximum and minimum
+columns of the root window of any frame that shall be fit to its buffer.
+If any of these values is non-@code{nil}, it overrides the corresponding
+argument of @code{fit-frame-to-buffer}.
+@end defopt
+
 @deffn Command shrink-window-if-larger-than-buffer &optional window
 This command attempts to reduce @var{window}'s height as much as
 possible while still showing its full buffer, but no less than
@@ -3622,33 +3662,28 @@ is off the screen due to horizontal scrolling:
 @end group
 @end example
 
+
 @node Coordinates and Windows
 @section Coordinates and Windows
 @cindex frame-relative coordinate
 @cindex coordinate, relative to frame
 @cindex window position
 
-  This section describes functions that report the position of a
-window.  Most of these functions report positions relative to the
-window's frame.  In this case, the coordinate origin @samp{(0,0)} lies
-near the upper left corner of the frame.  For technical reasons, on
-graphical displays the origin is not located at the exact corner of
-the graphical window as it appears on the screen.  If Emacs is built
-with the GTK+ toolkit, the origin is at the upper left corner of the
-frame area used for displaying Emacs windows, below the title-bar,
-GTK+ menu bar, and tool bar (since these are drawn by the window
-manager and/or GTK+, not by Emacs).  But if Emacs is not built with
-GTK+, the origin is at the upper left corner of the tool bar (since in
-this case Emacs itself draws the tool bar).  In both cases, the X and
-Y coordinates increase rightward and downward respectively.
-
-  Except where noted, X and Y coordinates are reported in integer
-character units, i.e., numbers of lines and columns respectively.  On a
-graphical display, each ``line'' and ``column'' corresponds to the
-height and width of a default character specified by the frame's
-default font.
-
-@defun window-edges &optional window
+This section describes functions that report the position of a window.
+Most of these functions report positions relative to an origin at the
+native position of the window's frame (@pxref{Frame Geometry}).  Some
+functions report positions relative to the origin of the display of the
+window's frame.  In any case, the origin has the coordinates (0, 0) and
+X and Y coordinates increase ``rightward'' and ``downward''
+respectively.
+
+  For the following functions, X and Y coordinates are reported in
+integer character units, i.e., numbers of lines and columns
+respectively.  On a graphical display, each ``line'' and ``column''
+corresponds to the height and width of a default character specified by
+the frame's default font (@pxref{Frame Font}).
+
+@defun window-edges &optional window body absolute pixelwise
 This function returns a list of the edge coordinates of @var{window}.
 If @var{window} is omitted or @code{nil}, it defaults to the selected
 window.
@@ -3665,44 +3700,73 @@ header line, mode line, scroll bar, fringes, window divider and display
 margins.  On a text terminal, if the window has a neighbor on its right,
 its right edge includes the separator line between the window and its
 neighbor.
-@end defun
 
-@defun window-inside-edges &optional window
-This function is similar to @code{window-edges}, but the returned edge
-values are for the text area of the window.  They exclude any header
-line, mode line, scroll bar, fringes, window divider, display margins,
-and vertical separator.
+If the optional argument @var{body} is @code{nil}, this means to
+return the edges corresponding to the total size of @var{window}.
+@var{body} non-@code{nil} means to return the edges of @var{window}'s
+body (aka text area).  If @var{body} is non-@code{nil}, @var{window}
+must specify a live window.
+
+If the optional argument @var{absolute} is @code{nil}, this means to
+return edges relative to the native position of @var{window}'s frame.
+@var{absolute} non-@code{nil} means to return coordinates relative to
+the origin (0, 0) of @var{window}'s display.  On non-graphical systems
+this argument has no effect.
+
+If the optional argument @var{pixelwise} is @code{nil}, this means to
+return the coordinates in terms of the default character width and
+height of @var{window}'s frame (@pxref{Frame Font}), rounded if
+necessary.  @var{pixelwise} non-@code{nil} means to return the
+coordinates in pixels.  Note that the pixel specified by @var{right} and
+@var{bottom} is immediately outside of these edges.  If @var{absolute}
+is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too.
 @end defun
 
-@defun window-top-line &optional window
-This function returns the Y coordinate of the topmost row of
-@var{window}, equivalent to the @var{top} entry in the list returned
-by @code{window-edges}.
+@defun window-body-edges &optional window
+This function returns the edges of @var{window}'s body (@pxref{Window
+Sizes}).  Calling @code{(window-body-edges window)} is equivalent to
+calling @code{(window-edges window t)}, see above.
 @end defun
 
+@comment The following two functions are confusing and hardly used.
+@ignore
 @defun window-left-column &optional window
-This function returns the X coordinate of the leftmost column of
-@var{window}, equivalent to the @var{left} entry in the list returned
-by @code{window-edges}.
+This function returns the leftmost column of @var{window}.  This value
+equals the @var{left} entry in the list returned by @code{(window-edges
+window)} minus the number of columns occupied by the internal border of
+@var{window}'s frame.
 @end defun
 
+@defun window-top-line &optional window
+This function returns the topmost row of @var{window}.  This value is
+equal to the @var{top} entry in the list returned by @code{(window-edges
+window)} minus the number of lines occupied by the internal border of
+@var{window}'s frame.
+@end defun
+@end ignore
+
   The following functions can be used to relate a set of
 frame-relative coordinates to a window:
 
 @defun window-at x y &optional frame
-This function returns the live window at the frame-relative
-coordinates @var{x} and @var{y}, on frame @var{frame}.  If there is no
-window at that position, the return value is @code{nil}.  If
-@var{frame} is omitted or @code{nil}, it defaults to the selected
+This function returns the live window at the coordinates @var{x} and
+@var{y} given in default character sizes (@pxref{Frame Font}) relative
+to the native position of @var{frame} (@pxref{Frame Geometry}).
+
+If there is no window at that position, the return value is @code{nil}.
+If @var{frame} is omitted or @code{nil}, it defaults to the selected
 frame.
 @end defun
 
 @defun coordinates-in-window-p coordinates window
-This function checks whether a window @var{window} occupies the
-frame-relative coordinates @var{coordinates}, and if so, which part of
-the window that is.  @var{window} should be a live window.
+This function checks whether a window @var{window} occupies the frame
+relative coordinates @var{coordinates}, and if so, which part of the
+window that is.  @var{window} should be a live window.
+
 @var{coordinates} should be a cons cell of the form @code{(@var{x}
-. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
+. @var{y})}, where @var{x} and @var{y} are given in default character
+sizes (@pxref{Frame Font}) relative to the native position of
+@var{window}'s frame (@pxref{Frame Geometry}).
 
 If there is no window at the specified position, the return value is
 @code{nil} .  Otherwise, the return value is one of the following:
@@ -3757,46 +3821,96 @@ each text character is taken to be ``one pixel''.
 
 @defun window-pixel-edges &optional window
 This function returns a list of pixel coordinates for the edges of
-@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
-to the selected window.
+@var{window}.  Calling @code{(window-pixel-edges window)} is equivalent
+to calling @code{(window-edges window nil nil t)}, see above.
+@end defun
 
-The return value has the form @code{(@var{left} @var{top} @var{right}
-@var{bottom})}.  The list elements are, respectively, the X pixel
-coordinate of the left window edge, the Y pixel coordinate of the top
-edge, one more than the X pixel coordinate of the right edge, and one
-more than the Y pixel coordinate of the bottom edge.
+@comment The following two functions are confusing and hardly used.
+@ignore
+@defun window-pixel-left &optional window
+This function returns the left pixel edge of window @var{window}.  This
+value equals the @var{left} entry in the list returned by
+@code{(window-pixel-edges window)} minus the number of pixels occupied
+by the internal border of @var{window}'s frame.  @var{window} must be a
+valid window and defaults to the selected one.
 @end defun
 
-@defun window-inside-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the pixel coordinates for the edges of the window's text area,
-rather than the pixel coordinates for the edges of the window itself.
-@var{window} must specify a live window.
+@defun window-pixel-top &optional window
+This function returns the top pixel edge of window @var{window}.  This
+value is equal to the @var{top} entry in the list returned by
+@code{(window-pixel-edges window)} minus the number of pixels occupied
+by the internal border of @var{window}'s frame.  @var{window} must be a
+valid window and defaults to the selected one.
+@end defun
+@end ignore
+
+@defun window-body-pixel-edges &optional window
+This function returns the pixel edges of @var{window}'s body.  Calling
+@code{(window-body-pixel-edges window)} is equivalent to calling
+@code{(window-edges window t nil t)}, see above.
 @end defun
 
-  The following functions return window positions in pixels, relative
-to the display screen rather than the frame:
+  The following functions return window positions in pixels, relative to
+the origin of the display screen rather than that of the frame:
 
 @defun window-absolute-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the edge pixel coordinates relative to the top left corner of
-the display screen.
+This function returns the pixel coordinates of @var{WINDOW} relative to
+an origin at (0, 0) of the display of @var{window}'s frame.  Calling
+@code{(window-absolute-pixel-edges)} is equivalent to calling
+@code{(window-edges window nil t t)}, see above.
 @end defun
 
-@defun window-inside-absolute-pixel-edges &optional window
-This function is like @code{window-inside-pixel-edges}, except that it
-returns the edge pixel coordinates relative to the top left corner of
-the display screen.  @var{window} must specify a live window.
-@end defun
+@defun window-absolute-body-pixel-edges &optional window
+This function returns the pixel coordinates of @var{WINDOW}'s body
+relative to an origin at (0, 0) of the display of @var{window}'s frame.
+Calling @code{(window-absolute-body-pixel-edges window)} is equivalent
+to calling @code{(window-edges window t t t)}, see above.
 
-@defun window-pixel-left &optional window
-This function returns the left pixel edge of window @var{window}.
-@var{window} must be a valid window and defaults to the selected one.
+Combined with @code{x-set-mouse-absolute-pixel-position}, this function
+can be used to move the mouse pointer to an arbitrary buffer position
+visible in some window:
+
+@example
+@group
+(let ((edges (window-absolute-body-pixel-edges))
+      (position (pos-visible-in-window-p nil nil t)))
+  (x-set-mouse-absolute-pixel-position
+   (+ (nth 0 edges) (nth 0 position))
+   (+ (nth 1 edges) (nth 1 position))))
+@end group
+@end example
+
+On a graphical terminal this form ``warps'' the mouse cursor to the
+upper left corner of the glyph at the selected window's point.  A
+position calculated this way can be also used to show a tooltip window
+there.
 @end defun
 
-@defun window-pixel-top &optional window
-This function returns the top pixel edge of window @var{window}.
-@var{window} must be a valid window and defaults to the selected one.
+The following function returns the screen coordinates of a buffer
+position visible in a window:
+
+@defun window-absolute-pixel-position &optional position window
+If the buffer position @var{position} is visible in window @var{window},
+this function returns the display coordinates of the upper/left corner
+of the glyph at @var{position}.  The return value is a cons of the X-
+and Y-coordinates of that corner, relative to an origin at (0, 0) of
+@var{window}'s display.  It returns @code{nil} if @var{position} is not
+visible in @var{window}.
+
+@var{window} must be a live window and defaults to the selected
+window.  @var{position} defaults to the value of @code{window-point}
+of @var{window}.
+
+This means that in order to move the mouse pointer to the position of
+point in the selected window, it's sufficient to write:
+
+@example
+@group
+(let ((position (window-absolute-pixel-position)))
+  (x-set-mouse-absolute-pixel-position
+   (car position) (cdr position)))
+@end group
+@end example
 @end defun