Fix bug #18636 with documentation of multi-monitor displays.

 doc/lispref/frames.texi (Multiple Terminals): Improve the description of X
 display names.  Add index entries.
 (Basic Parameters): Add a cross-reference to where X display names
 are described.
 (Position Parameters): Mention that positional parameters of the
 form (+ POS) can be negative if they are on a non-primary monitor
 of a multi-monitor display.
 (Creating Frames): Mention that on multi-monitor displays the
 frame might be positioned differently than specified by the frame
 parameters alist.

 lisp/faces.el (display-grayscale-p): Mention in the doc string that
 the argument can be either a display name or a frame.
 lisp/frame.el (display-pixel-height, display-pixel-width)
 (display-mm-height, display-mm-width, display-backing-store)
 (display-save-under, display-planes, display-color-cells)
 (display-visual-class, display-monitor-attributes-list)
 (display-screens): Mention in the doc string that the argument can
 be either a display name or a frame.  Improve the docs of the
 monitor attributes.

5 files changed, 116 insertions, 22 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index babcc22959e..36497470705 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,16 @@
+2014-10-08  Eli Zaretskii  <eliz@gnu.org>
+
+        * frames.texi (Multiple Terminals): Improve the description of X
+        display names.  Add index entries.
+        (Basic Parameters): Add a cross-reference to where X display names
+        are described.
+        (Position Parameters): Mention that positional parameters of the
+        form (+ POS) can be negative if they are on a non-primary monitor
+        of a multi-monitor display.  (Bug#18636)
+        (Creating Frames): Mention that on multi-monitor displays the
+        frame might be positioned differently than specified by the frame
+        parameters alist.
+
 2014-10-04  Glenn Morris  <rgm@gnu.org>
 
         * commands.texi (Generic Commands): Copyedits.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index afbace34575..cb3fefd7115 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -131,6 +131,13 @@ applies any parameters listed in @code{frame-inherited-parameters}
 (see below) and not present in the argument, taking the values from
 the frame that was selected when @code{make-frame} was called.
 
+Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
+window manager might position the frame differently than specified by
+the positional parameters in @var{alist} (@pxref{Position
+Parameters}).  For example, some window managers have a policy of
+displaying the frame on the monitor that contains the largest part of
+the window (a.k.a.@: the @dfn{dominating} monitor).
+
 This function itself does not make the new frame the selected frame.
 @xref{Input Focus}.  The previously selected frame remains selected.
 On graphical terminals, however, the windowing system may select the
@@ -258,13 +265,27 @@ of those frames is ``@emph{the} selected frame'' at any given moment
 terminals, by interacting with the @command{emacsclient} program.
 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
 
+@cindex X display names
+@cindex display name on X
   A single X server can handle more than one display.  Each X display
-has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
-The first two parts, @var{host} and @var{server}, identify the X
-server; the third part, @var{screen}, identifies a screen number on
-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.
+has a three-part name,
+@samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}.  The
+first part, @var{hostname}, specifies the name of the machine to which
+the display is physically connected.  The second part,
+@var{displaynumber}, is a zero-based number that identifies one or
+more monitors connected to that machine that share a common keyboard
+and pointing device (mouse, tablet, etc.).  The third part,
+@var{screennumber}, identifies a zero-based screen number (a separate
+monitor) that is part of a single monitor collection on 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.
+
+  Systems that don't use the X window system, such as MS-Windows,
+don't support the notion of X displays, and have only one display on
+each host.  The display name on these systems doesn't follow the above
+3-part format; for example, the display name on MS-Windows systems is
+a constant string @samp{w32}, and exists for compatibility, so that
+you could pass it to functions that expect a display name.
 
 @deffn Command make-frame-on-display display &optional parameters
 This function creates and returns a new frame on @var{display}, taking
@@ -320,19 +341,27 @@ to obtain information about such setups.
 
 @defun display-monitor-attributes-list &optional display
 This function returns a list of physical monitor attributes on
-@var{display}, which defaults to that of the selected frame.
-Each element of the list is an association list, representing the
-attributes of a physical monitor.  The first element corresponds to
-the primary monitor.  The attribute keys and values are:
+@var{display}, which can be a display name (a string), a terminal, or
+a frame; if omitted or @code{nil}, it defaults to the selected frame's
+display.  Each element of the list is an association list,
+representing the attributes of a physical monitor.  The first element
+corresponds to the primary monitor.  The attribute keys and values
+are:
 
 @table @samp
 @item geometry
-Position and size in pixels as @samp{(@var{x} @var{y}
-@var{width} @var{height})}.
+Position of the top-left corner of the monitor's screen and its size,
+in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}.  Note
+that, if the monitor is not the primary monitor, some of the
+coordinates might be negative.
 
 @item workarea
-Position and size of the work area in pixels as
-@samp{(@var{x} @var{y} @var{width} @var{height})}.
+Position of the top-left corner and size of the work area in pixels as
+@samp{(@var{x} @var{y} @var{width} @var{height})}.  This is different
+from @samp{geometry} in that the various system windows, such as the
+task bar and side bar, are excluded from the work area.  Note that, if
+the monitor is not the primary monitor, some of the coordinates might
+be negative.
 
 @item mm-size
 Width and height in millimeters as @samp{(@var{width} @var{height})}
@@ -353,6 +382,27 @@ does not intersect any physical monitors) that monitor is the closest
 to the frame.  Every (non-tooltip) frame (whether visible or not) in a
 graphical display is dominated by exactly one physical monitor at a
 time, though the frame can span multiple (or no) physical monitors.
+
+Here's an example of the data produced by this function on a 2-monitor
+display:
+
+@smalllisp
+  (display-monitor-attributes-list)
+  @result{}
+  (((geometry 0 0 1920 1080)   ;; Left hand monitor
+    (workarea 0 0 1920 1050)   ;; Bottom of screen used for task bar
+    task bar
+    (mm-size 677 381)
+    (name . "\\\\.\\DISPLAY1")
+    (frames #<frame emacs@@host *foo* 0000000005BBDC48>
+            #<frame emacs@@host *scratch* 000000008179D370>))
+   ((geometry 1920 0 1680 1050) ;; Right hand monitor
+    (workarea 1920 0 1680 1050) ;; Whole screen can be used
+    (mm-size 593 370)
+    (name . "\\\\.\\DISPLAY2")
+    (frames)))
+@end smalllisp
+
 @end defun
 
 @defun frame-monitor-attributes &optional frame
@@ -529,8 +579,9 @@ frame.  @code{title} and @code{name} are meaningful on all terminals.
 @vindex display, a frame parameter
 @item display
 The display on which to open this frame.  It should be a string of the
-form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
-@env{DISPLAY} environment variable.
+form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the
+@env{DISPLAY} environment variable.  @xref{Multiple Terminals}, for
+more details about display names.
 
 @vindex display-type, a frame parameter
 @item display-type
@@ -586,12 +637,14 @@ right screen edge.
 @item @code{(+ @var{pos})}
 This specifies the position of the left frame edge relative to the left
 screen edge.  The integer @var{pos} may be positive or negative; a
-negative value specifies a position outside the screen.
+negative value specifies a position outside the screen or on a monitor
+other than the primary one (for multi-monitor displays).
 
 @item @code{(- @var{pos})}
 This specifies the position of the right frame edge relative to the right
 screen edge.  The integer @var{pos} may be positive or negative; a
-negative value specifies a position outside the screen.
+negative value specifies a position outside the screen or on a monitor
+other than the primary one (for multi-monitor displays).
 @end table
 
 Some window managers ignore program-specified positions.  If you want to
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5045e5d1469..e8fd37925fa 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,16 @@
+2014-10-08  Eli Zaretskii  <eliz@gnu.org>
+
+        * faces.el (display-grayscale-p): Mention in the doc string that
+        the argument can be either a display name or a frame.
+
+        * frame.el (display-pixel-height, display-pixel-width)
+        (display-mm-height, display-mm-width, display-backing-store)
+        (display-save-under, display-planes, display-color-cells)
+        (display-visual-class, display-monitor-attributes-list)
+        (display-screens): Mention in the doc string that the argument can
+        be either a display name or a frame.  Improve the docs of the
+        monitor attributes.  (Bug#18636)
+
 2014-10-06  Martin Rudalics  <rudalics@gmx.at>
 
         * term.el (term-window-width): Subtract 1 from the width when
diff --git a/lisp/faces.el b/lisp/faces.el
index f316245d165..20665286b4f 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -1814,7 +1814,9 @@ If omitted or nil, that stands for the selected frame's display."
 (declare-function x-display-grayscale-p "xfns.c" (&optional terminal))
 
 (defun display-grayscale-p (&optional display)
-  "Return non-nil if frames on DISPLAY can display shades of gray."
+  "Return non-nil if frames on DISPLAY can display shades of gray.
+DISPLAY should be either a frame or a display name (a string).
+If omitted or nil, that stands for the selected frame's display."
   (let ((frame-type (framep-on-display display)))
     (cond
      ((memq frame-type '(x w32 ns))
diff --git a/lisp/frame.el b/lisp/frame.el
index f4d7622e662..9ab24cefc0f 100644
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -1381,6 +1381,7 @@ frame's display)."
 
 (defun display-screens (&optional display)
   "Return the number of screens associated with DISPLAY.
+DISPLAY should be either a frame or a display name (a string).
 If DISPLAY is omitted or nil, it defaults to the selected frame's display."
   (let ((frame-type (framep-on-display display)))
     (cond
@@ -1393,6 +1394,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defun display-pixel-height (&optional display)
   "Return the height of DISPLAY's screen in pixels.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display.
 
 For character terminals, each character counts as a single pixel.
@@ -1412,6 +1414,7 @@ with DISPLAY.  To get information for each physical monitor, use
 
 (defun display-pixel-width (&optional display)
   "Return the width of DISPLAY's screen in pixels.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display.
 
 For character terminals, each character counts as a single pixel.
@@ -1450,6 +1453,7 @@ not explicitly specified."
 (defun display-mm-height (&optional display)
   "Return the height of DISPLAY's screen in millimeters.
 If the information is unavailable, this function returns nil.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display.
 
 You can override what the system thinks the result should be by
@@ -1470,6 +1474,7 @@ monitor, use `display-monitor-attributes-list'."
 (defun display-mm-width (&optional display)
   "Return the width of DISPLAY's screen in millimeters.
 If the information is unavailable, this function returns nil.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display.
 
 You can override what the system thinks the result should be by
@@ -1493,6 +1498,7 @@ monitor, use `display-monitor-attributes-list'."
   "Return the backing store capability of DISPLAY's screen.
 The value may be `always', `when-mapped', `not-useful', or nil if
 the question is inapplicable to a certain kind of display.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display."
   (let ((frame-type (framep-on-display display)))
     (cond
@@ -1505,6 +1511,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defun display-save-under (&optional display)
   "Return non-nil if DISPLAY's screen supports the SaveUnder feature.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display."
   (let ((frame-type (framep-on-display display)))
     (cond
@@ -1517,6 +1524,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defun display-planes (&optional display)
   "Return the number of planes supported by DISPLAY.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display."
   (let ((frame-type (framep-on-display display)))
     (cond
@@ -1531,6 +1539,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defun display-color-cells (&optional display)
   "Return the number of color cells supported by DISPLAY.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display."
   (let ((frame-type (framep-on-display display)))
     (cond
@@ -1547,6 +1556,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
   "Return the visual class of DISPLAY.
 The value is one of the symbols `static-gray', `gray-scale',
 `static-color', `pseudo-color', `true-color', or `direct-color'.
+DISPLAY can be a display name or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display."
   (let ((frame-type (framep-on-display display)))
     (cond
@@ -1567,6 +1577,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defun display-monitor-attributes-list (&optional display)
   "Return a list of physical monitor attributes on DISPLAY.
+DISPLAY can be a display name, a terminal name, or a frame.
 If DISPLAY is omitted or nil, it defaults to the selected frame's display.
 Each element of the list represents the attributes of a physical
 monitor.  The first element corresponds to the primary monitor.
@@ -1576,14 +1587,16 @@ of attribute keys and values as follows:
 
  geometry -- Position and size in pixels in the form of (X Y WIDTH HEIGHT)
  workarea -- Position and size of the work area in pixels in the
-             form of (X Y WIDTH HEIGHT)
+             form of (X Y WIDTH HEIGHT); this excludes task bar etc.
  mm-size  -- Width and height in millimeters in the form of
              (WIDTH HEIGHT)
  frames   -- List of frames dominated by the physical monitor
  name (*) -- Name of the physical monitor as a string
 
-where X, Y, WIDTH, and HEIGHT are integers.  Keys labeled
-with (*) are optional.
+where X, Y, WIDTH, and HEIGHT are integers, which might be negative
+for monitors other than the primary one.  X and Y are coordinates
+of the top-left corner of the rectange.  Keys labeled with (*) are
+optional.
 
 A frame is dominated by a physical monitor when either the
 largest area of the frame resides in the monitor, or the monitor