* bug#14801: 24.3.50; Document monitor attributes (e.g., `workarea' and `mm-size')
@ 2013-07-05 20:30 Drew Adams
2013-07-05 23:29 ` YAMAMOTO Mitsuharu
2013-07-06 2:49 ` Glenn Morris
0 siblings, 2 replies; 5+ messages in thread
From: Drew Adams @ 2013-07-05 20:30 UTC (permalink / raw)
To: 14801
Monitor attributes are partially documented in
`C-h f display-monitor-attributes-list'. They should also be (fully)
documented in the Elisp manual.
Even in the doc string of d-m-a-l, the description is incomplete and
needs to be filled out.
Attribute `workareas' is described only in terms of "the workarea".
There is no explanation of what is meant by "workarea" (which should
presumably be two words, BTW).
Attribute `mm-size' is described only as "the width and height in
millimeters". It's all very nice to say what the units are, but what is
it that is being measured? The width & height of what? If it is the
"work area" (whatever that might be) then say so explicitly.
Beyond all this, what on Earth IS a monitor "attribute"? Is it supposed
to be the same thing as a frame parameter? The Elisp manual covers file
attributes and face attributes. And it mentions terminal attributes (in
passing - there is no explanation or description of them), but it is
silent about monitor attributes.
The doc for this feature or collection of features (?) is hopelessly
incomplete and confused. One can only make wild guesses as to what is
meant and what this is all about.
In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
of 2013-07-01 on LEG570
Bzr revision: 113246 lekktu@gmail.com-20130701165437-ea20s94hqwp3ttaj
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --prefix=/c/usr --enable-checking CFLAGS='-O0 -g3'
CPPFLAGS='-DGLYPH_DEBUG=1 -I/c/usr/include''
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#14801: 24.3.50; Document monitor attributes (e.g., `workarea' and `mm-size')
2013-07-05 20:30 bug#14801: 24.3.50; Document monitor attributes (e.g., `workarea' and `mm-size') Drew Adams
@ 2013-07-05 23:29 ` YAMAMOTO Mitsuharu
2013-07-06 1:39 ` Drew Adams
2013-07-06 8:47 ` martin rudalics
2013-07-06 2:49 ` Glenn Morris
1 sibling, 2 replies; 5+ messages in thread
From: YAMAMOTO Mitsuharu @ 2013-07-05 23:29 UTC (permalink / raw)
To: Drew Adams; +Cc: 14801
>>>>> On Fri, 5 Jul 2013 13:30:53 -0700 (PDT), Drew Adams <drew.adams@oracle.com> said:
> Monitor attributes are partially documented in `C-h f
> display-monitor-attributes-list'. They should also be (fully)
> documented in the Elisp manual.
Actually I was preparing for that. See the bottom of this mail.
> Even in the doc string of d-m-a-l, the description is incomplete and
> needs to be filled out.
> Attribute `workareas' is described only in terms of "the workarea".
> There is no explanation of what is meant by "workarea" (which should
> presumably be two words, BTW).
While I was creating the docstring, I actually looked for the
definition of "workarea" in EWMH on which the implementation is based.
Unfortunately, it only says as "work area".
http://standards.freedesktop.org/wm-spec/1.3/ar01s03.html#id3075721
But I've just found the GDK documentation has some explanation: "The
work area should be considered when positioning menus and similar
popups, to avoid placing them below panels, docks or other desktop
components."
https://developer.gnome.org/gdk3/3.8/GdkScreen.html#gdk-screen-get-monitor-workarea
If it is allowed to use "panels", "docks" or "desktop components"
without their definitions, probably similar explanation of "work area"
can be provided.
> Attribute `mm-size' is described only as "the width and height in
> millimeters". It's all very nice to say what the units are, but
> what is it that is being measured? The width & height of what? If
> it is the "work area" (whatever that might be) then say so
> explicitly.
Of the monitor. I thought it was obvious from the context. But I can
add "of the physical monitor" for clarity.
> Beyond all this, what on Earth IS a monitor "attribute"? Is it
> supposed to be the same thing as a frame parameter?
No. It is an alist describing some kinds of information about current
configuration of each physical monitor. I named it after "file
attributes".
> The Elisp manual covers file attributes and face attributes. And it
> mentions terminal attributes (in passing - there is no explanation
> or description of them), but it is silent about monitor attributes.
> The doc for this feature or collection of features (?) is hopelessly
> incomplete and confused. One can only make wild guesses as to what
> is meant and what this is all about.
The current draft of the Elisp manual begins like this:
@node Multiple Physical Monitors
@section Multiple Physical Monitors
@cindex multiple physical monitors
On some ``multi-monitor'' setups, a single graphical display outputs
to more than one physical monitor. You can get some kinds of
information on each physical monitor to examine the current monitor
configuration. Because the monitor configuration can be changed
dynamically in general, you should avoid reusing the information
obtained some time ago.
Information on each physical monitor is represented as
``attributes'', an alist of attribute keys and values as follows:
@table @code
@item geometry
...
YAMAMOTO Mitsuharu
mituharu@math.s.chiba-u.ac.jp
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#14801: 24.3.50; Document monitor attributes (e.g., `workarea' and `mm-size')
2013-07-05 23:29 ` YAMAMOTO Mitsuharu
@ 2013-07-06 1:39 ` Drew Adams
2013-07-06 8:47 ` martin rudalics
1 sibling, 0 replies; 5+ messages in thread
From: Drew Adams @ 2013-07-06 1:39 UTC (permalink / raw)
To: YAMAMOTO Mitsuharu; +Cc: 14801
> > Monitor attributes are partially documented in `C-h f
> > display-monitor-attributes-list'. They should also be (fully)
> > documented in the Elisp manual.
>
> Actually I was preparing for that.
Great. Thanks for working on it.
> See the bottom of this mail.
>
> > Even in the doc string of d-m-a-l, the description is incomplete and
> > needs to be filled out.
>
> > Attribute `workareas' is described only in terms of "the workarea".
> > There is no explanation of what is meant by "workarea" (which should
> > presumably be two words, BTW).
>
> While I was creating the docstring, I actually looked for the
> definition of "workarea" in EWMH on which the implementation is based.
> Unfortunately, it only says as "work area".
>
> http://standards.freedesktop.org/wm-spec/1.3/ar01s03.html#id3075721
>
> But I've just found the GDK documentation has some explanation: "The
> work area should be considered when positioning menus and similar
> popups, to avoid placing them below panels, docks or other desktop
> components."
>
> https://developer.gnome.org/gdk3/3.8/GdkScreen.html#gdk-screen-get-
> monitor-workarea
>
> If it is allowed to use "panels", "docks" or "desktop components"
> without their definitions, probably similar explanation of "work area"
> can be provided.
Thanks for trying to find out what it is. I don't understand, myself,
but I'm not going to spend the time necessary to study this. What you
might want to do, especially if things will remain only partly explained,
is to refer readers to some such external reference for more info.
I had no idea, for example, that this involved something called a work
area that is defined externally (e.g. as part of a standard or similar).
I thought it was just an Emacs thing. If it is only Emacs then we really
need to specify it. But if it is defined elsewhere then we can just
summarize and point to the external description for more information.
> > Attribute `mm-size' is described only as "the width and height in
> > millimeters". It's all very nice to say what the units are, but
> > what is it that is being measured? The width & height of what? If
> > it is the "work area" (whatever that might be) then say so
> > explicitly.
>
> Of the monitor. I thought it was obvious from the context. But I can
> add "of the physical monitor" for clarity.
Yes, thanks.
> > Beyond all this, what on Earth IS a monitor "attribute"? Is it
> > supposed to be the same thing as a frame parameter?
>
> No. It is an alist describing some kinds of information about current
> configuration of each physical monitor. I named it after "file
> attributes".
That's fine. Please just say that then: it is an alist of... And
give a little more information to give a better idea. Just substituting
"some kinds of information" for "attribute" won't get us very far.
> The current draft of the Elisp manual begins like this:
>
> @node Multiple Physical Monitors
> @section Multiple Physical Monitors
> @cindex multiple physical monitors
>
> On some ``multi-monitor'' setups, a single graphical display outputs
> to more than one physical monitor. You can get some kinds of
> information on each physical monitor to examine the current monitor
> configuration. Because the monitor configuration can be changed
> dynamically in general, you should avoid reusing the information
> obtained some time ago.
>
> Information on each physical monitor is represented as
> ``attributes'', an alist of attribute keys and values as follows:
Sounds better already. Call them "monitor attributes", to be even
clearer. Thx.
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#14801: 24.3.50; Document monitor attributes (e.g., `workarea' and `mm-size')
2013-07-05 23:29 ` YAMAMOTO Mitsuharu
2013-07-06 1:39 ` Drew Adams
@ 2013-07-06 8:47 ` martin rudalics
1 sibling, 0 replies; 5+ messages in thread
From: martin rudalics @ 2013-07-06 8:47 UTC (permalink / raw)
To: YAMAMOTO Mitsuharu; +Cc: 14801
> The current draft of the Elisp manual begins like this:
>
> @node Multiple Physical Monitors
> @section Multiple Physical Monitors
> @cindex multiple physical monitors
Since to my knowledge the Elisp manual does nowhere talk about single
physical monitors I'd suggest to drop the term "multiple" here.
Moreover, the terms "screen" and "display" should be related to
"monitors".
martin
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#14801: 24.3.50; Document monitor attributes (e.g., `workarea' and `mm-size')
2013-07-05 20:30 bug#14801: 24.3.50; Document monitor attributes (e.g., `workarea' and `mm-size') Drew Adams
2013-07-05 23:29 ` YAMAMOTO Mitsuharu
@ 2013-07-06 2:49 ` Glenn Morris
1 sibling, 0 replies; 5+ messages in thread
From: Glenn Morris @ 2013-07-06 2:49 UTC (permalink / raw)
To: 14801-done
No need for bug reports about documenting new features that are in
NEWS without +++/--- markup.
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2013-07-06 8:47 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-07-05 20:30 bug#14801: 24.3.50; Document monitor attributes (e.g., `workarea' and `mm-size') Drew Adams
2013-07-05 23:29 ` YAMAMOTO Mitsuharu
2013-07-06 1:39 ` Drew Adams
2013-07-06 8:47 ` martin rudalics
2013-07-06 2:49 ` Glenn Morris
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).