Merge from emacs-24; up to 2014-07-22T06:37:31Z!yamaoka@jpl.org

1 files changed, 77 insertions, 19 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 464c5fccc4f..a14702a7ce1 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,29 @@ 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 (``usable''
+space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}.
+This may be different from @samp{geometry} in that space occupied by
+various window manager features (docks, taskbars, etc.) may be
+excluded from the work area.  Whether or not such features actually
+subtract from the work area depends on the platform and environment.
+Again, 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})}
@@ -342,10 +373,14 @@ List of frames that this physical monitor dominates (see below).
 
 @item name
 Name of the physical monitor as @var{string}.
+
+@item source
+Source of the multi-monitor information as @var{string};
+e.g., @samp{XRandr} or @samp{Xinerama}.
 @end table
 
 @var{x}, @var{y}, @var{width}, and @var{height} are integers.
-@samp{name} may not be present.
+@samp{name} and @samp{source} may be absent.
 
 A frame is @dfn{dominated} by a physical monitor when either the
 largest area of the frame resides in that monitor, or (if the frame
@@ -353,6 +388,26 @@ 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:
+
+@lisp
+  (display-monitor-attributes-list)
+  @result{}
+  (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor}
+    (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height}
+    (mm-size 677 381)
+    (name . "DISPLAY1")
+    (frames #<frame emacs@@host *Messages* 0x11578c0>
+            #<frame emacs@@host *scratch* 0x114b838>))
+   ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor}
+    (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used}
+    (mm-size 593 370)
+    (name . "DISPLAY2")
+    (frames)))
+@end lisp
+
 @end defun
 
 @defun frame-monitor-attributes &optional frame
@@ -529,8 +584,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 +642,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