* doc/lispref/frames.texi (Multiple Terminals): Document

`display-monitor-attributes-list' and `display-monitor-attributes'.
(Display Feature Testing): Add some notes about multi-monitor.

* etc/NEWS: Related edit.

doc/lispref/ChangeLog

+2014-02-27  Xue Fuqiao  <xfq@gnu.org>
+
+	* frames.texi (Multiple Terminals): Document
+	`display-monitor-attributes-list' and `display-monitor-attributes'.
+	(Display Feature Testing): Add some notes about multi-monitor.
+
 2014-02-27  Glenn Morris  <rgm@gnu.org>
 
 	* minibuf.texi (Programmed Completion):

doc/lispref/frames.texi

@@ -266,10 +266,6 @@ that X server.  When you use two or more screens belonging to one
 server, Emacs knows by the similarity in their names that they share a
 single keyboard.
 
-  On some ``multi-monitor'' setups, a single X display outputs to more
-than one physical monitor.  Currently, there is no way for Emacs to
-distinguish between the different physical monitors.
-
 @deffn Command make-frame-on-display display &optional parameters
 This function creates and returns a new frame on @var{display}, taking
 the other frame parameters from the alist @var{parameters}.
@@ -316,6 +312,61 @@ you can do this, you must first delete all the frames that were open
 on that display (@pxref{Deleting Frames}).
 @end defun
 
+@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.
+
+@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:
+
+@table @samp
+@item geometry
+Position and size in pixels in the form of @samp{(X Y WIDTH HEIGHT)}
+
+@item workarea
+Position and size of the workarea in pixels in the form of @samp{(X Y
+WIDTH HEIGHT)}
+
+@item mm-size
+Width and height in millimeters in the form of @samp{(WIDTH HEIGHT)}
+
+@item frames
+List of frames dominated by the physical monitor
+
+@item name
+Name of the physical monitor as a 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{display} defaults to the selected frame's display.
+@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.
+@end defun
+
 @node Frame Parameters
 @section Frame Parameters
 @cindex frame parameters
@@ -2370,12 +2421,13 @@ images, Emacs cannot display a tool bar.
 This function returns the number of screens associated with the display.
 @end defun
 
+@c FIXME: Document `x-display-pixel-{width, height}'?
 @defun display-pixel-height &optional display
 This function returns the height of the screen in pixels.
 On a character terminal, it gives the height in characters.
 
 For graphical terminals, note that on ``multi-monitor'' setups this
-refers to the pixel width for all physical monitors associated with
+refers to the pixel height for all physical monitors associated with
 @var{display}.  @xref{Multiple Terminals}.
 @end defun
 
@@ -2388,14 +2440,23 @@ refers to the pixel width for all physical monitors associated with
 @var{display}.  @xref{Multiple Terminals}.
 @end defun
 
+@c FIXME: Document `x-display-mm-{width, height}'?
 @defun display-mm-height &optional display
 This function returns the height of the screen in millimeters,
 or @code{nil} if Emacs cannot get that information.
+
+For graphical terminals, note that on ``multi-monitor'' setups this
+refers to the height for all physical monitors associated with
+@var{display}.  @xref{Multiple Terminals}.
 @end defun
 
 @defun display-mm-width &optional display
 This function returns the width of the screen in millimeters,
 or @code{nil} if Emacs cannot get that information.
+
+For graphical terminals, note that on ``multi-monitor'' setups this
+refers to the width for all physical monitors associated with
+@var{display}.  @xref{Multiple Terminals}.
 @end defun
 
 @defopt display-mm-dimensions-alist