[Emacs-diffs] trunk r116634: Minor doc tweaks for display-*-width, height

[Glenn Morris]

------------------------------------------------------------
revno: 116634
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sun 2014-03-02 17:00:27 -0800
message:
  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.
modified:
  doc/lispref/frames.texi        
frames.texi-20091113204419-o5vbwnq5f7feedwu-6180
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/frame.el                  frame.el-20091113204419-o5vbwnq5f7feedwu-275

=== modified file 'doc/lispref/frames.texi'
--- a/doc/lispref/frames.texi   2014-02-27 10:15:52 +0000
+++ b/doc/lispref/frames.texi   2014-03-03 01:00:27 +0000
@@ -2421,7 +2421,6 @@
 This function returns the number of screens associated with the display.
 @end defun
 
address@hidden 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 @@
 @var{display}.  @xref{Multiple Terminals}.
 @end defun
 
address@hidden 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.

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-03-02 08:54:32 +0000
+++ b/etc/NEWS  2014-03-03 01:00:27 +0000
@@ -142,10 +142,11 @@
 `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'.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-03-02 17:37:32 +0000
+++ b/lisp/ChangeLog    2014-03-03 01:00:27 +0000
@@ -1,3 +1,9 @@
+2014-03-03  Glenn Morris  <address@hidden>
+
+       * 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 <address@hidden>
 
        * simple.el (undo-elt-in-region): Fix buffer corruption for edge

=== modified file 'lisp/frame.el'
--- a/lisp/frame.el     2014-03-01 01:32:42 +0000
+++ b/lisp/frame.el     2014-03-03 01:00:27 +0000
@@ -1393,12 +1393,14 @@
 
 (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 @@
 
 (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 @@
 
 (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.
-
-Each element of the alist 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."
+The functions `display-mm-height' and `display-mm-width' consult
+this list before asking the system.
+
+Each element has the form (DISPLAY . (WIDTH . HEIGHT)), e.g.
+\(\":0.0\" . (287 . 215)).
+
+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 @@
 
 (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 @@
 
 (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))