From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#18636: 24.4.50; doc of `display-monitor-attributes-list' - DISPLAY? FRAME? Date: Wed, 08 Oct 2014 13:24:01 +0300 Message-ID: <83oatmkgfy.fsf@gnu.org> References: <2cb10ab0-7eb3-43a8-9fc2-72374602b55f@default> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1412763871 24273 80.91.229.3 (8 Oct 2014 10:24:31 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 8 Oct 2014 10:24:31 +0000 (UTC) Cc: 18636-done@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Oct 08 12:24:23 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1XboPo-000647-U3 for geb-bug-gnu-emacs@m.gmane.org; Wed, 08 Oct 2014 12:24:17 +0200 Original-Received: from localhost ([::1]:35249 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XboPo-0007uZ-DH for geb-bug-gnu-emacs@m.gmane.org; Wed, 08 Oct 2014 06:24:16 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44229) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XboPg-0007uK-DI for bug-gnu-emacs@gnu.org; Wed, 08 Oct 2014 06:24:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XboPb-000818-DH for bug-gnu-emacs@gnu.org; Wed, 08 Oct 2014 06:24:08 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:45863) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XboPb-000814-AF for bug-gnu-emacs@gnu.org; Wed, 08 Oct 2014 06:24:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1XboPa-0001Xe-VI for bug-gnu-emacs@gnu.org; Wed, 08 Oct 2014 06:24:03 -0400 Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-To: bug-gnu-emacs@gnu.org Resent-Date: Wed, 08 Oct 2014 10:24:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: cc-closed 18636 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Mail-Followup-To: 18636@debbugs.gnu.org, eliz@gnu.org, drew.adams@oracle.com Original-Received: via spool by 18636-done@debbugs.gnu.org id=D18636.14127638345906 (code D ref 18636); Wed, 08 Oct 2014 10:24:02 +0000 Original-Received: (at 18636-done) by debbugs.gnu.org; 8 Oct 2014 10:23:54 +0000 Original-Received: from localhost ([127.0.0.1]:37426 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1XboPR-0001XB-8T for submit@debbugs.gnu.org; Wed, 08 Oct 2014 06:23:53 -0400 Original-Received: from mtaout23.012.net.il ([80.179.55.175]:62975) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1XboPN-0001Wz-Vz for 18636-done@debbugs.gnu.org; Wed, 08 Oct 2014 06:23:51 -0400 Original-Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0ND400500F8HG700@a-mtaout23.012.net.il> for 18636-done@debbugs.gnu.org; Wed, 08 Oct 2014 13:23:48 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0ND4005A6FJNBQ90@a-mtaout23.012.net.il>; Wed, 08 Oct 2014 13:23:48 +0300 (IDT) In-reply-to: <2cb10ab0-7eb3-43a8-9fc2-72374602b55f@default> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:94280 > Date: Sun, 5 Oct 2014 19:41:21 -0700 (PDT) > From: Drew Adams > Cc: 18636@debbugs.gnu.org > > > > I find it unclear that the optional parameter of > > > `display-monitor-attributes-list' is named DISPLAY, and is > > > referred to as a display in the doc string, and yet in > > > `frame-monitor-attributes' it is arg FRAME that is passed > > > to `display-monitor-attributes-list'. > > > > > > Is the argument of `display-monitor-attributes-list' a > > > display or a frame? > > > > It can be either. > > OK. Then the doc should say so. Done on the emacs-24 branch (revision 117559). > And it should call out the > relation between the two. For example, if a frame is passed > and its display is used (= its `display' frame parameter), > then say so. That's not what happens, though. Each function extracts the info it needs from whatever kind of argument it is passed, and then uses that info. > > > What about other functions, such as `display-pixel-height', which > > > call `display-monitor-attributes-list'? They seem to pass their > > > DISPLAY arg to it. Is this arg too something that can be (or > > > is always?) a frame? The doc string of `display-pixel-height' > > > (for example) says: > > > > > > "If DISPLAY is omitted or nil, it defaults to the selected > > > frame's display." > > > > > > That would seem to suggest that a frame is not a display, but > > > rather it _has_ a display. > > > > A frame is not a display, but these functions accept either one. > > Their doc should say so. Done. > > If you make a list of the functions where the doc string is not > > explicit about this fact, I will fix them. > > Thank you. I think this is the case for all of the 20 functions > described in (elisp) `Display Feature Testing', but there might > be others as well. Done. > > > In (elisp) `Basic Parameters' I see this description of frame > > > parameter `display': > > > > > > The display on which to open this frame. It should be a string > > > of the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' > > > environment variable. > > > > > > But if I evaluate `(frame-parameters)' on MS Windows I see this > > > value for parameter `display': "w32". > > > > > > "w32" does not seem to fit the form `"HOST:DPY.SCREEN"'. What > > > gives? > > > > Emacs on MS-Windows doesn't support the notion of 'display', so all > > frames return the same value of that parameter. > > OK, then the doc should mention this, or at least say that the > string might not take the form "HOST:DPY.SCREEN" on some platforms, > and preferably say something about what to expect on the > exceptional platforms (and perhaps give some idea of what use the > exceptional value is - what it can be used for, or what info it > conveys). Done. > > > And why is that string surrounded by `...'? > > > > An artifact of Texinfo markup. > > I see. Is that then correct, or should the `...' be absent? > There are strings in the manual that are not surrounded by `...'. I fixed the markup. > > > And why aren't the components of that "form" described: What are > > > acceptable values for HOST, DPY, and SCREEN? > > > > Users on X already know what they are; users on other systems don't > > need to know, because this is not supported. Either way, this > > notion is not an Emacs invention, it is a feature of the X > > window system. > > Then please say that. E.g., say that the value is useful only for > X Window, or only relevant for it. If the function itself has no > use beyond X Window, then please make that clear. Done, and also improved the description of the X form. > From: Andy Moreton > Date: Tue, 07 Oct 2014 19:35:28 +0100 > > > Oh, and I think this is no longer about the docs, so probably a new > > bug report is in order, specifically about restoring frames on > > multi-monitor displays. > True, as long as the meaning of geometry/workarea and the coordinate > system are given a little more detail in the docs. Done. I'm closing this bug.