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.

3 files changed, 32 insertions, 4 deletions

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