Minor doc tweaks for display-*-width, height

* lisp/frame.el (display-pixel-height, display-pixel-width)
(display-mm-dimensions-alist, display-mm-height)
(display-mm-width): Doc tweaks.

* doc/lispref/frames.texi: Remove FIXME comments.  The x- versions of
these functions are internal details that do not need documenting.

* etc/NEWS: Related markup.

4 files changed, 36 insertions, 21 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 403d9f6884e..439f9686733 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -2421,7 +2421,6 @@ 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.
@@ -2440,7 +2439,6 @@ 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.
diff --git a/etc/NEWS b/etc/NEWS
index ce98be2dda2..a5919069000 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -142,10 +142,11 @@ entries of a file.
 `frame-monitor-attributes' can be used to obtain information about
 each physical monitor on multi-monitor setups.
 
++++
 *** The functions `display-pixel-width' and `display-pixel-height' now
 behave consistently among the platforms: they return the pixel width
 or height for all physical monitors associated with the given display
-as if they were on X11.  To get information for each physical
+as if they were on X.  To get information for each physical
 monitor, use the new functions above.  Similar notes also apply to
 `x-display-pixel-width', `x-display-pixel-height', `display-mm-width',
 `display-mm-height', `x-display-mm-width', and `x-display-mm-height'.
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a2a88f4b86b..9c3a7ac9945 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2014-03-03  Glenn Morris  <rgm@gnu.org>
+
+        * frame.el (display-pixel-height, display-pixel-width)
+        (display-mm-dimensions-alist, display-mm-height)
+        (display-mm-width): Doc tweaks.
+
 2014-03-02  Barry O'Reilly <gundaetiapo@gmail.com>
 
         * simple.el (undo-elt-in-region): Fix buffer corruption for edge
diff --git a/lisp/frame.el b/lisp/frame.el
index 4f189a82289..b62c939d536 100644
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -1393,12 +1393,14 @@ 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.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display.
+
 For character terminals, each character counts as a single pixel.
+
 For graphical terminals, note that on \"multi-monitor\" setups this
 refers to the pixel height for all physical monitors associated
 with DISPLAY.  To get information for each physical monitor, use
-`display-monitor-attributes-list'.
-If DISPLAY is omitted or nil, it defaults to the selected frame's display."
+`display-monitor-attributes-list'."
   (let ((frame-type (framep-on-display display)))
     (cond
      ((memq frame-type '(x w32 ns))
@@ -1410,12 +1412,14 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defun display-pixel-width (&optional display)
   "Return the width of DISPLAY's screen in pixels.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display.
+
 For character terminals, each character counts as a single pixel.
+
 For graphical terminals, note that on \"multi-monitor\" setups this
 refers to the pixel width for all physical monitors associated
 with DISPLAY.  To get information for each physical monitor, use
-`display-monitor-attributes-list'.
-If DISPLAY is omitted or nil, it defaults to the selected frame's display."
+`display-monitor-attributes-list'."
   (let ((frame-type (framep-on-display display)))
     (cond
      ((memq frame-type '(x w32 ns))
@@ -1425,14 +1429,14 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defcustom display-mm-dimensions-alist nil
   "Alist for specifying screen dimensions in millimeters.
-The dimensions will be used for `display-mm-height' and
-`display-mm-width' if defined for the respective display.
+The functions `display-mm-height' and `display-mm-width' consult
+this list before asking the system.
 
-Each element of the alist has the form (display . (width . height)),
-e.g. (\":0.0\" . (287 . 215)).
+Each element has the form (DISPLAY . (WIDTH . HEIGHT)), e.g.
+\(\":0.0\" . (287 . 215)).
 
-If `display' equals t, it specifies dimensions for all graphical
-displays not explicitly specified."
+If `display' is t, it specifies dimensions for all graphical displays
+not explicitly specified."
   :version "22.1"
   :type '(alist :key-type (choice (string :tag "Display name")
                                   (const :tag "Default" t))
@@ -1445,13 +1449,16 @@ displays not explicitly specified."
 
 (defun display-mm-height (&optional display)
   "Return the height of DISPLAY's screen in millimeters.
-System values can be overridden by `display-mm-dimensions-alist'.
-If the information is unavailable, value is nil.
+If the information is unavailable, this function returns nil.
+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
+adding an entry to `display-mm-dimensions-alist'.
+
 For graphical terminals, note that on \"multi-monitor\" setups this
 refers to the height in millimeters for all physical monitors
 associated with DISPLAY.  To get information for each physical
-monitor, use `display-monitor-attributes-list'.
-If DISPLAY is omitted or nil, it defaults to the selected frame's display."
+monitor, use `display-monitor-attributes-list'."
   (and (memq (framep-on-display display) '(x w32 ns))
        (or (cddr (assoc (or display (frame-parameter nil 'display))
                         display-mm-dimensions-alist))
@@ -1462,13 +1469,16 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display."
 
 (defun display-mm-width (&optional display)
   "Return the width of DISPLAY's screen in millimeters.
-System values can be overridden by `display-mm-dimensions-alist'.
-If the information is unavailable, value is nil.
+If the information is unavailable, this function returns nil.
+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
+adding an entry to `display-mm-dimensions-alist'.
+
 For graphical terminals, note that on \"multi-monitor\" setups this
 refers to the width in millimeters for all physical monitors
 associated with DISPLAY.  To get information for each physical
-monitor, use `display-monitor-attributes-list'.
-If DISPLAY is omitted or nil, it defaults to the selected frame's display."
+monitor, use `display-monitor-attributes-list'."
   (and (memq (framep-on-display display) '(x w32 ns))
        (or (cadr (assoc (or display (frame-parameter nil 'display))
                         display-mm-dimensions-alist))