Re: 1.9d

[Dan Winship <danw mit edu>]

Hi. I'm new here, so so apologies if I complain about something you
decided not to fix 10 revisions ago...

Overall, there's too much of an assumption that the reader already knows
exactly what the document is about. The intro jumps right into a definition
of terms, without ever mentioning what we're talking about. You might also
want to define what "pager"s and "taskbar"s are in the section where you
say that you're going to refer to both of them as "Pager"s. ("Pager" at
least is completely non-obvious to anyone who doesn't use a "modern" window
manager. To me, "pager" means either something that beeps and tells you
you need to go into work, or a program like "more" or "less".) Other
non-X-standard words you use without defining include "desktop", "viewport",
and "dock".

You occasionally misuse the RFC 2119 words. They should always imply
conformance/non-conformance with the spec. For example, the sentence:

	If a Pager wants to delete/insert a certain desktop, it MUST send a
	_NET_{INSERT/DELETE}_DESKTOP to the root window

means

	A Pager that inserts or deletes a desktop without sending a
	_NET_{INSERT/DELETE}_DESKTOP to the root window is not in
	compliance with this specification.

which isn't at all what you mean. I think you want to say "can" rather than
"MUST". There are other cases where you use "MUST" or "SHOULD" where it's
not explicitly made clear whose behavior you're restricting. E.g:

	_NET_WM_STATE_STICKY indicates that a window SHOULD have a fixed
	position on the screen, even when the virtual desktop scrolls.

should be something like:

	_NET_WM_STATE_STICKY indicates that the window manager SHOULD keep
	the window's position fixed on the screen, even when the virtual
	desktop scrolls.


It might make sense to split the root window properties and the corresponding
messages Pagers can send to modify them into separate sections.

There should be an explicit list somewhere of exactly which properties
can/should/must be listed in _NET_SUPPORTED and _NET_PROPERTIES.

In the comment on _NET_CLIENT_LIST, the parts about ordering need
clarification. Does "mapping order" mean "the order in which the windows
were first mapped", or "the order in which they were most recentlymapped"?
(ie, if I unmap and then remap a window, does it move to the end of the
list?) For stacking order, you should specify if the first window in the
list is the top or the bottom. I have no idea what the "Z order" mentioned
in the comment means if it's not the same as stacking order.

The _NET_NUMBER_OF_DESKTOPS and _NET_DESKTOP_GEOMETRY sections are each
missing a close paren after the protocol description.

In the description of _NET_DESKTOP_GEOMETRY, "the width and height of each
desktop" sounds like each desktop could have a different size, which doesn't
appear to be true.

The description of _NET_DESKTOP_VIEWPORT (or the introduction) should
explain "paged desktops". Also, I suspect you mean to require that Pagers
can only set the viewport to x,y pairs that are specified in the root
_NET_DESKTOP_VIEWPORT property, but you don't say that. (If not, and the
wm doesn't want to allow arbitrary viewports, then there needs to be
some way for the Pager to know that it failed, particularly in the case
where the wm doesn't support any viewport other than 0,0.)

It's not clear what "active" means in _NET_ACTIVE_WINDOW. I would have
guessed "has the keyboard focus", except that apparently a Pager can make
a window "active" without setting the keyboard focus...

If you can't set more than one of _NET_ACTIVATE_VISIBLE_ON_VIEWPORT,
_NET_ACTIVATE_VISIBLE_ON_DESKTOP, and _NET_ACTIVATE_VISIBLE_EVERYWHERE,
it might be better to make them be two bits rather than three, with values
01, 10, and 11 respectively.

_NET_WORKAREA: The text implies the ordering of the array elements is
"left, right, top, bottom", but isn't explicit. I think normal X ordering
is "left, top, right/width, bottom/height", like _NET_WM_ICON_GEOMETRY
uses. But _NET_WM_STRUT seems to explicitly specify the same ordering that
_NET_WORKAREA implies. This needs to be cleaned up.

If the "SHOULD" in _NET_WM_MOVERESIZE is really a "SHOULD", the spec should
clarify what other value the app can set x_root and y_root to other than the
position of the click. (I suspect you don't really mean "SHOULD" though.)

The sentence starting "When being in another state" in the _NET_WM_DESKTOP
section is very confusing.

_NET_WM_STATE_SHADED: What does "shaded" mean?

_NET_WM_STATE_SKIP_TASKBAR: Should TASKBAR be PAGER? At any rate, a more
generic description (and possibly name) is probably in order. ("indicates
that this window should not be included on lists of active windows"?)

If the wm has to watch out for _NET_WM_STRUT changes, why can't it watch
out for _NET_WM_STATE changes too rather than requiring the client to send
messages to the root window?

_NET_WM_ICON: The sentence ending "may do" should probably say "may do so".

Is there any reason NET_WM_PING doesn't have an underscore before its name
like everything else?

-- Dan