GNU bug report logs -
#18636
24.4.50; doc of `display-monitor-attributes-list' - DISPLAY? FRAME?
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Sun, 5 Oct 2014 19:06:02 UTC
Severity: minor
Found in version 24.4.50
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
Your message dated Wed, 08 Oct 2014 13:24:01 +0300
with message-id <83oatmkgfy.fsf <at> gnu.org>
and subject line Re: bug#18636: 24.4.50; doc of `display-monitor-attributes-list' - DISPLAY? FRAME?
has caused the debbugs.gnu.org bug report #18636,
regarding 24.4.50; doc of `display-monitor-attributes-list' - DISPLAY? FRAME?
to be marked as done.
(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)
--
18636: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=18636
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems
[Message part 2 (message/rfc822, inline)]
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?
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.
And there is a frame parameter `display', whose value is "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.
This suggests that a display is not a frame. So how is it that
`frame-monitor-attributes' passes a FRAME to
`display-monitor-attributes-list', which supposedly expects a display
instead?
Please try to clear up some of this confusion in the doc and doc
strings.
In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
of 2014-09-15 on LEG570
Bzr revision: 117884 dancol <at> dancol.org-20140915050944-sqsajysnwef51f9m
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --enable-checking 'CFLAGS=-O0 -g3' CPPFLAGS=-DGLYPH_DEBUG=1'
[Message part 3 (message/rfc822, inline)]
> Date: Sun, 5 Oct 2014 19:41:21 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 18636 <at> 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 <andrewjmoreton <at> gmail.com>
> 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.
This bug report was last modified 10 years and 286 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.