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.

2 files changed, 84 insertions, 18 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