Re: [PATCH] xdg-shell: add draw states for xdg_surface

[Matthias Clasen]

To me, 'draw states' sounds a lot like 'mwm hints' - which would be a
180 degree reversal from semantic states back to presentation states.
Do we really want to go down that road ?
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: Accessibility considerations

[Matthias Clasen]

>
> Btw. Matthias guessed an implementation would belong in xkbcommon, but
> that is also used client-side. How does that fit in with server-side
> accessibility implementation?

This is where I would really hope for Daniel Stone to chime in...
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: Accessibility considerations

[Matthias Clasen]

On Fri, Mar 11, 2016 at 12:51 AM, Timofonic  wrote:
> Please consider mandatory high contrast option with custom colors. I prefer
> black background and green foreground, it's a lie better for Mr eyes because
> clear colors really tire me.
>
> Text-To-Speech and braille devices should be very seriously very taken in
> consideration too, please. I know many people work degenerative vision
> issues that will eventually very totally blind, some of them are Linux
> enthusiasts.
>
> Let the the client side decide isn't a good option at all! Not homogeneous
> behavior and many lazy efforts would make accessibility broken very often.
> I've seen that lots of times!
>
> And please consider to involve developers having related disabilities:They
> would know how to implement an usable accessibility, because they use it all
> time and as users know what's right or wrong on many software.
>

No doubt, high-contrast, braille, screen reading are all important
aspects of accessibility too. But as I said in my initial mail, I'd
like to keep this discussion focused on just the keyboard-related
aspects.
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel

Accessibility considerations

[Matthias Clasen]

Hi,

I would like to discuss strategies for implementing accessibility
features in Wayland that will be needed for a fully featured desktop.
There's a whole list of individual items, but for now I'd like to
focus on keyboard accessibility features, ie roughly the feature that
traditionally labeled AccessX:

- slow keys (only accept key presses after a delay)
- sticky keys (support one-key-at-a-time operation by latching and
locking modifiers)
- bounce keys (reject quick key presses of the same key)
- toggle keys (special key bindings to enable the aforementioned
features: hold-shift-for-8-seconds for slow keys,
shift-5-times-in-a-row for sticky keys)

The following two are not technically AccessX, but are close enough to
include them:
- key repeat
- visual bell (all of the AccessX features have configurable bells;
the visual bell can be configured to be per-window or global)

Under X, all of these features are implemented in the XKB code in the
server (the visual bell gets handled by a client that selects for for
XkbBellNotify. In GNOME, that is mutter).

Wayland uses libxkbcommon to implement xkb-like keyboard handling, but
as far as I know, no Wayland compositor currently implements any of
the features I listed above. xwayland inherited the X server
implementation and thus, X clients do get AccessX features, but
Wayland clients don't. Not an ideal situation.

In GNOME, we have a client-side implementation of key repeat, which
has some issues that we recently worked around by introducing an extra
roundtrip before synthesizing repeat presses. I recently spent an
evening trying to see how far I can get in implementing AccessX
client-side (see
https://git.gnome.org/browse/gtk+/log/?h=matthiasc/wayland/slowkeys).
The results were mixed, I would say. While I have mostly working code
for all of the AccessX features, there are some limitations:

- For 'true' slow keys, the modifier keys should be delayed as well.
My client-side implementation does not do that, since the modifier
processing happens compositor-side, and I can only delay the events
that already have modifiers applied.

- I did not attempt to implement the visual bell client-side; flashing
the screen by mapping a fullscreen window temporarily would just be
too much of a hack. More recently, Jonas added a bell request to the
private gtk_shell interface between gtk+ and mutter, so we can now
reuse the existing (visual and audible) bell handling code in mutter.

- Handling the toggle keys client-side means that you can only enable
AccessX features if a client has focus; this needs to be handled in
the compositor so using one of these shortcuts can be the first thing
you do after stepping up to the computer, regardless if a client has
focus or not. We also loose a feature compared to the X session: under
X, we show a notification asking for confirmation ("Did you mean to
turn on SlowKeys?") when the toggle keys features are triggered from
the keyboard, to keep users from accidentally 'breaking' their
keyboard by resting their finger on the shift key. We can really send
notifications from deep inside a GDK backend.

- Doing this client-side implementation in GTK+ does not help one bit
for SDL or Qt or E or toytoolkit clients.

I know that one of the guiding principles of the Wayland architecure
is 'client-side', but I think the limitations listed
here are significant enough to argue for a compositor side
implementation of keyboard a11y. I don't think that this needs (a lot
of) new protocol, except for maybe a way to query and monitor state
related to these features.

One small complication with implementing AccessX compositor-side is
that we have one client that currently does it client-side: xwayland.
It would need a patch to force-disable AccessX there. This is also why
I think there should be project-wide agreement on whether these
features belong in the compositor or not. It would be really
unfortunate and bad for interoperability if we end up in a future
where these features are implemented server-side in GNOME, but
client-side in KDE or the other way around.

For the implementation itself, I guess it really belongs into
libxkbcommon, although that means it needs timers (or hooking up to a
mainloop). I find it intriguing that libxkbcommon/src/state.c has this
comment:

/*
 * This is a bastardised version of xkbActions.c from the X server which
 * does not support, for the moment:
 *   - AccessX sticky/debounce/etc (will come later)
...

Daniel, do you still have plans in this area, or did 'later' turn out
to be 'never' ?
If not, any pointers for where somebody else would start digging into this ?

Anyway, I'd like to hear people's thoughts about this topic.


Matthias
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [RFC] Implementing Wayland Security Module

[Matthias Clasen]

On Mon, Mar 9, 2015 at 1:38 AM, Manuel Bachmann
manuel.bachm...@open.eurogiciel.org wrote:

 Any comments on this ?


I don't think it makes sense to develop a specific solution just for
the portion of application sandboxing that happens to overlap with
wayland protocol requests. The same questions need to be answered when
a third-party application e.g. wants to open a file or send an email.
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

xdg shell status and gaps

[Matthias Clasen]

Hi,

so yesterday we released what we described as a day-to-day usable
GNOME/Wayland. Congratulations to everybody involved in defining
xdg-shell on getting us this far.

But... (I wouldn't write if there wasn't a but) we are not yet calling
it a '100% complete port' because there are still a number of things
that don't work, compared to X.

It is quite possible that some of these should be done differently
under Wayland, or not at all. It is also possible that there are
already plans for supporting these things that I don't know about. In
that case, please set me straight.

Anyway, here's the list:

1) Marking dialogs as modal (needed so we can implement the 'attached
modal' visuals of gnome-shell

2) Lowering windows (used e.g. by GtkInspector to get out of the way
when picking a window

3) Raising or activating windows (needed e.g when activating a
pre-existing window of a single-window application)

4) Learning about output characteristics - is this display the
'primary' / builtin / projector ? (needed e.g. when deciding which
output to show a presentation on)

5) Finding out if there is desktop chrome that should be avoided (ie.
'workarea') ? (Useful e.g. for window size heuristics)

Outside of xdg-shell, we found that there's currently no protocol
support for handling some traditional aspects of DND:

6) Snap-back animation if a drag ends unsuccessfully

7) Root window drop


Matthias
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: xdg shell status and gaps

[Matthias Clasen]

On Thu, Sep 25, 2014 at 10:32 AM, Jasper St. Pierre
jstpie...@mecheye.net wrote:


 Anyway, here's the list:

 1) Marking dialogs as modal (needed so we can implement the 'attached
 modal' visuals of gnome-shell

What about this one ?

 2) Lowering windows (used e.g. by GtkInspector to get out of the way
 when picking a window

 I'm not comfortable adding this. You can hide briefly the inspector by
 giving it a 1x1 blank surface and emptying the input region. Perhaps we
 should make this equivalent to what the NULL surface semantics are.

Might work - I chose lowering here instead of hiding since hiding
breaks the grabs we use under X.


 4) Learning about output characteristics - is this display the
 'primary' / builtin / projector ? (needed e.g. when deciding which
 output to show a presentation on)

 5) Finding out if there is desktop chrome that should be avoided (ie.
 'workarea') ? (Useful e.g. for window size heuristics)


 This will be handled by the probe extension, but I'm not really sure why you
 need this. You can't manually place your window with global coordinates.
 Avoiding anything doesn't make too much sense to me.

As I said, we currently use the workarea in
gtk_window_guess_default_size() when figuring out which size to give
the window initially. Thats somewhat useful, even if we have no
control of the placement.


 7) Root window drop


 When is this useful?

One place where it is used is when dragging tabs out of a window to
create a new window. gnome-terminal, gedit, nautilus, all do this. But
looking closer, the way it is implemented is not actually as a root
window drop, specifically, but just any failed drop - if you don't
drop on a notebook in the same app that is hooked up to accept the
tab, we just treat any failed drop as a change to create a new window.
So, what we need is a signal that a drop failed. Not sure we get that,
currently ?
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [PATCH 0/6] Add weston randr protocol

[Matthias Clasen]

For comparison, here is the dbus API that gnome-shell is exposing for
display configuration under both X and wayland:

https://wiki.gnome.org/Initiatives/Wayland/Gaps/DisplayConfig
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [Accessibility] Need to be able to sythesize mouse events

[Matthias Clasen]

On Wed, Dec 11, 2013 at 2:15 PM, Piñeiro apinhe...@igalia.com wrote:


 On 12/11/2013 07:09 PM, Giulio Camuffo wrote:
  Wayland doesn't have a way to inject mouse events currently. Some
  protocol must be written, which would be presumably implemented as a
  private protocol which only trusted clients can use, given the
  security implications.

 I was guessing about that. While reading about Wayland, I found this
 extension:
 https://github.com/01org/wayland-fits

 And as you can read on the description:

 The first protocol is a interface for generating input events
 on the server-side (e.g. mouse, keyboard, touch).


 What I was not sure if that would the one to go for accessibility needs,
 and also if implemented as a private protocol, how at-spi2 could use it.
 Or in other words, how declare at-spi2 as a trusted client


A trusted client has to effectively be launched by the compositor, it
cannot just be started by the user or another application in the session.
It could be stored in compositor configuration that is not changeable at
runtime.

Of course, if at-spi2 is launched as a trusted client, and then just
exports the capability of the private protocol (injecting arbitrary input)
over its own d-bus api, then the trust is misplaced because all apps can
then inject input just by talking d-bus to at-spi2 instead of talking
directly to the compositor...

So I think the trusted client will have to be orca itself.
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [Accessibility] Need to be able to register for key events globally

[Matthias Clasen]

On Tue, Dec 10, 2013 at 3:29 PM, Piñeiro apinhe...@igalia.com wrote:

 GNOME Assistive Technologies need to be able to listen to key events
 globally and have the possibility of consuming them. Example use
 cases:

 * Orca's presentation of navigation (Events not consumed)
   - Right Arrow: Speak character moved to (right of cursor)
   - Shift Right Arrow: Speak character selected (left of cursor)
   - Down Arrow: Speak next line
   - Etc.
 * Orca's navigational commands (Events consumed)
   - H/Shift + H: Move amongst headings
   - NumPad 8: Speak the current line
   - NumPad 5: Speak the current word
   - NumPad 2: Speak the current character
   - Etc.

 Current solution: The Orca screen reader calls AT-SPI2's
 atspi_register_keystroke_listener(). AT-SPI2 then notifies Orca of key
 events it receives from the toolkit implementation of ATK method
 atk_add_key_event_listener(). Applications then have to wait for Orca
 to consume the event or not. This requires two DBUS messages. Toolkit
 authors want to abolish this. That's fine, *if* we have an
 alternative. Do we?


As Bill says, input methods already have a private protocol for
intercepting and processing input events on the server side, and a similar
facility could be added to the private protocol for ATs. And again, having
at-spi using that private protocol and then offering key snooping to
everybody over dbus would negate an advantage of Wayland, so the user of
the private protocol should be the actual AT, not some multiplexing
intermediate layer.
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Making Wayland accessible

[Matthias Clasen]

As part of the ongoing GNOME Wayland porting effort, the GNOME
accessibility (a11y) team has been looking into what it would take to make
our existing a11y tools (ATs) and infrastructure work under Wayland.

Most a11y features will probably end up being implemented in the
compositor:

- input tweaks like slow keys or bounce keys or hover-to-click naturally
fit in the event dispatching in the compositor

- display changes like zoom or color adjustments are already handled in
gnome-shell under X

- the text protocol should be sufficient to make on-screen keyboards and
similar tools  work

The remaining AT of concern is orca, our screen reader, which does not
easily fit into the compositor. Here are some examples of the kinds of
things orca needs to do to support its users:

- Identify the surface that is currently under the pointer (and the
corresponding application that is registered as an accessible client)

- Warp the pointer to a certain position (see
https://bugzilla.gnome.org/show_bug.cgi?id=70 for a description of how
this is used)

- Filter out certain key events and use them for navigation purposes. This
is currently done by capturing key events client-side and sending them out
again via at-spi, which will probably continue to work, even if it is
awkward and toolkit authors would really like to get rid of it

All of these features violate the careful separation between clients that
Wayland maintains, so that probably calls for some privileged interface for
ATs. I would appreciate feedback and discussion on this.

Has anybody else thought about these problems already ?

Are there better ways to do these things under Wayland ?


Matthias
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [PATCH] selection: send selection events to all connected clients

[Matthias Clasen]

On Fri, Apr 12, 2013 at 1:33 PM, Yichao Yu yyc1...@gmail.com wrote:
 A lot of useful features require clipboard access and monitoring
 without having a keyboard focus, e.g. clipboard action (klipper[1] and
 some download agents), command line access (IPython's %paste magic).
 This patch sends out selection events to all clients when the
 selection owner changes no matter whether the client has a focus or
 not in order to support these features.

Clipboard managers are pretty specialized clients, and you usually
only run at most one of them in your session - why confuse all other
clients with the extra events ?
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH] Add api to obtain min/max keycode

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Users of libxkbcommon need these values to iterate over all
keycodes in the keymap.
---
 src/keymap.c  | 12 
 xkbcommon/xkbcommon.h | 20 
 2 files changed, 32 insertions(+)

diff --git a/src/keymap.c b/src/keymap.c
index 55000f4..14ec25f 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -484,6 +484,18 @@ err:
 return 0;
 }
 
+XKB_EXPORT xkb_keycode_t
+xkb_keymap_get_min_keycode (struct xkb_keymap *keymap)
+{
+return keymap-min_key_code;
+}
+
+XKB_EXPORT xkb_keycode_t
+xkb_keymap_get_max_keycode (struct xkb_keymap *keymap)
+{
+return keymap-max_key_code;
+}
+
 /**
  * Simple boolean specifying whether or not the key should repeat.
  */
diff --git a/xkbcommon/xkbcommon.h b/xkbcommon/xkbcommon.h
index a2aecfb..412f429 100644
--- a/xkbcommon/xkbcommon.h
+++ b/xkbcommon/xkbcommon.h
@@ -974,6 +974,26 @@ xkb_led_index_t
 xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name);
 
 /**
+ * Get the minimum keycode of the keymap
+ *
+ * @returns The minimum keycode of the keymap.
+ *
+ * @memberof xkb_keymap
+ */
+xkb_keycode_t
+xkb_keymap_get_min_keycode (struct xkb_keymap *keymap);
+
+/**
+ * Get the maximum keycode of the keymap
+ *
+ * @returns The maximum keycode of the keymap.
+ *
+ * @memberof xkb_keymap
+ */
+xkb_keycode_t
+xkb_keymap_get_max_keycode (struct xkb_keymap *keymap);
+
+/**
  * Determine whether a key should repeat or not.
  *
  * A keymap may specify different repeat behaviors for different keys.
-- 
1.8.2

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [patches] Add a color management framework to weston

[Matthias Clasen]

On Thu, Apr 4, 2013 at 2:58 AM, John Kåre Alsaker
john.kare.alsa...@gmail.com wrote:

 I don't see a GLib event loop, so I'm curious to how the signals work.

Just ftr (and without actually looking at the patch): glib signals
don't need an event loop, they're entirely synchronous.
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [PATCH 00/21] Documentation improvements

[Matthias Clasen]

On Mon, Apr 1, 2013 at 10:43 AM, Jason Ekstrand ja...@jlekstrand.net wrote:
 Matthias,
 First, I would like to apologize for a) being a bit harsh and
 overbearing in my comments and b) getting too caught up in stylistic
 issues.  I really should have read through it for content first and
 just kept a tally for style things.  At some point here (probably not
 till at least the weekend) I will try to go through and do a thorough
 content-only review of the wayland.xml changes.  I will leave the
 style discussion here and we can figure out how we want to handle each
 of these issues in one place.  Disagreements about style really
 shouldn't be handled inline anyway.

No worries, I didn't take it personally. Stylistic editing and patch
review are not easy to marry. On some level, it would be best if krh
just did an editing pass and committed a version of the docs that he
is happy with. I was hoping my patches could serve as a basis for
that.



 For judging formatting questions like this, I recommend proof-reading
 the generated docs. That's what I looked at when making those changes.

 Allow me to explain my perspective on this a bit more.  I am not only
 looking at the HTML generated by publican (as given on the webpage)
 but my own XML protocol parser that I have written to dump out Java
 classes for wayland-java generates JavaDoc comments for each
 event/request/interface as per the XML documentation flags.  I also
 think it would be a good idea to, at some point, make the C scanner
 dump out doxygen comments.  Later this week I'll try to get publican
 installed so I can understand the documentation pipeline a bit better.

Interesting. I didn't know that there are other consumers than what's
in the wayland repo.



 References to arguments or events/requests:
 One thing Matthias pulled out was some @ characters before arguments
 or event/request names.  I agree that the @ isn't really doing
 anything for us.  That said, I'm not sure we just want to get rid of
 it.  It would be nice if we had something some sort of flag that
 publican could turn into function and other things could turn into
 whatever type of reference it requires.  I realize going through and
 adding that would be a lot of work.  Some times this can be easily
 fixed by simply moving pieces of the doc comment to argument comments.

Yeah, what annoyed me about the @ was that it doesn't do anything, is
inconsistently used, and makes it into the formatted document. I had
thought about using function markup, or some other suitable docbook
tag. It does create some nicer output. But I didn't want to disrupt
the text with too much markup. So far, it is really nicely readable
even in the xml.
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: protocol questions

[Matthias Clasen]

On Sat, Mar 30, 2013 at 7:56 AM, Daniel Stone dan...@fooishbar.org wrote:




 - Various input events have a time field. The spec doesn't really say
 anything about this. What is it good for, and what units are these -
 monotonic time ?


 Monotonic (ideally) time in an undefined domain, i.e. they're only
 meaningful on relation to each other.



What can you do with them ? For the use case that Giulio mentioned
(double-click detection), I'd need to know at least if the difference
between two times is seconds or milliseconds or microseconds...


- Still on popups, I don't see a way for the client to dismiss the
 popup, or is that handled by just destroying the surface ?


 Indeed, just destroy the surface or attach a NULL buffer.


Good to know. I don't think the spec mentions at all that 'attach NULL
buffer' == unmap.


- Buffer transformations - fun. How do these relate to each of the
 following ?
- resize edges
- transient offset
- buffer attach x/y
- input/opaque/damage regions
- surface x/y in motion events


 All the latter occur on surfaces rather than buffers, so are unaffected.
  Buffer transforms are meant to support situations like where your screen
 is rotated 90°, and your client can also render rotated in order to avoid
 that extra blit.  So it doesn't affect the event pipeline at all, only the
 display pipeline.


That sounds right for resize edgets and motion events, certainly. For some
of the others, at least the wording of the spec is not always very clear on
this point. E.g. for buffer attach x/y, the wl_surface.attach docs say:

The x and y arguments specify the location of the new pending
buffer's upper left corner, relative to the current buffer's
upper left corner.

See how it talks about the current buffer's upper left corner. Should that
say 'the surface's upper left corner, then ?
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [PATCH 21/21] docs: Add details about grabs

[Matthias Clasen]

You are right, thanks.


On Sat, Mar 30, 2013 at 9:16 AM, renoX reno...@gmail.com wrote:

 I think that there is a typo in the text, you wrote But there is way for
 clients to take an explicit grab. Instead, instead of But there is NO
 way..

 BR,
 renoX

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 0/2] More documentation additions

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

I've received some clarifications on questions I asked
about the protocol. These patches add that information
to the docs, so it isn't lost.

Matthias Clasen (2):
  docs: Document granularity of timestamps
  docs: Add information about serials and timestamps

 doc/Wayland/en_US/Protocol.xml | 16 
 protocol/wayland.xml   | 20 
 2 files changed, 28 insertions(+), 8 deletions(-)

-- 
1.8.2

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: [PATCH 00/21] Documentation improvements

[Matthias Clasen]

On Sat, Mar 30, 2013 at 6:32 PM, Jason Ekstrand ja...@jlekstrand.net wrote


 1. I said this in one of the e-mails, but avoid unneeded
 documentation.  The documentation as is is fairly sparse and needs to
 be filled in.  However, too much documentation can sometimes be a bad
 thing too.  For example, on events called destroy it's pretty
 obvious what it does: It destroys the object.  Adding a comment really
 doesn't help and just makes for more to wade through.  Also, you have
 a lot of the serial of the X event comments.  Again, these don't
 really add anything.  If there is something special or noteworthy
 about the serial argument on a particular event, go ahead and document
 it.

No doubt, there can be too much verbiage in docs.

But I don't think the wayland protocol docs are even close the point
of 'too much documentation'. And since the spec that needs to be
precise enough to guarantee interoperatibility, you shouldn't assume
that anything is obvious. Your example proves the point: an event does
not do anything, it just informs you about something. You thought it
was obvious and got it wrong...


 2. There are several places where you add a one-line summary at the
 beginning of the documentation block.  This is what the summary tag is
 for.  Having it as a single line at the top of the block as well will
 simply make people more confused.  Particularly if the wayland XML is
 used go generate comments that are to be parsed by something like
 doxygen or javadoc.  That said, fixing capitalization in the summaries
 wouldn't be bad.

For judging formatting questions like this, I recommend proof-reading
the generated docs. That's what I looked at when making those changes.

 I have a few more general comments at the tops of the reply e-mails I
 sent out.  Keeping all this in mind, I'd like you to go back through
 and make a second version.  Looks good so far!

Sure. It might be a while before I find another chunk of time to sink
into this, though.


Thanks for the review
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 01/21] docs: Reorder some sections

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Move the 'Types of Compositors' section right after the Overview,
and move the 'Client API' part after the protocol spec.
---
 doc/Wayland/en_US/Wayland.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/Wayland/en_US/Wayland.xml b/doc/Wayland/en_US/Wayland.xml
index 30fa3f2..44ccc1d 100644
--- a/doc/Wayland/en_US/Wayland.xml
+++ b/doc/Wayland/en_US/Wayland.xml
@@ -6,10 +6,10 @@
 book
   xi:include href=Book_Info.xml xmlns:xi=http://www.w3.org/2001/XInclude; 
/
   xi:include href=Overview.xml xmlns:xi=http://www.w3.org/2001/XInclude; /
+  xi:include href=Compositors.xml 
xmlns:xi=http://www.w3.org/2001/XInclude; /
   xi:include href=Architecture.xml 
xmlns:xi=http://www.w3.org/2001/XInclude; /
   xi:include href=Protocol.xml xmlns:xi=http://www.w3.org/2001/XInclude; /
-  xi:include href=Library.xml xmlns:xi=http://www.w3.org/2001/XInclude; /
-  xi:include href=Compositors.xml 
xmlns:xi=http://www.w3.org/2001/XInclude; /
   xi:include href=ProtocolSpec.xml 
xmlns:xi=http://www.w3.org/2001/XInclude; /
+  xi:include href=Library.xml xmlns:xi=http://www.w3.org/2001/XInclude; /
 /book
 
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 02/21] docs: Slight rewording

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

The Wayland Protocol - Wayland Protocol Overview, to align
better with the subsequent Wayland Protocol Specification.
---
 doc/Wayland/en_US/Protocol.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
index b5cd7a1..cab68a8 100644
--- a/doc/Wayland/en_US/Protocol.xml
+++ b/doc/Wayland/en_US/Protocol.xml
@@ -4,7 +4,7 @@
 %BOOK_ENTITIES;
 ]
 chapter id=chap-Protocol
-  titleThe Wayland Protocol/title
+  titleWayland Protocol Overview/title
   section id=sect-Protocol-Basic-Principles
 titleBasic Principles/title
 para
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 03/21] docs: Improve the 'Types of Compositors' section

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Turn the bullet-point lists into full paragraphs.
---
 doc/Wayland/en_US/Compositors.xml | 119 +++---
 1 file changed, 46 insertions(+), 73 deletions(-)

diff --git a/doc/Wayland/en_US/Compositors.xml 
b/doc/Wayland/en_US/Compositors.xml
index d5311fa..f674776 100644
--- a/doc/Wayland/en_US/Compositors.xml
+++ b/doc/Wayland/en_US/Compositors.xml
@@ -5,57 +5,53 @@
 ]
 chapter id=chap-Compositors
   titleTypes of Compositors/title
+
+  para
+Compositors come in different types, depending on which
+role they play in the overall architecture of the OS.
+  /para
+
   section id=sect-Compositors-System-Compositor
 titleSystem Compositor/title
 para
-  itemizedlist
-   listitem
- para
-   ties in with graphical boot
- /para
-   /listitem
-   listitem
- para
-   hosts different types of session compositors
- /para
-   /listitem
-   listitem
- para
-   lets us switch between multiple sessions (fast user switching,
-   secure/personal desktop switching)
- /para
-   /listitem
-   listitem
- para
-   multiseat
- /para
-   /listitem
-   listitem
- para
-   linux implementation using libudev, egl, kms, evdev, cairo
- /para
-   /listitem
-   listitem
- para
-   for fullscreen clients, the system compositor can reprogram the
-   video scanout address to source from the client provided buffer.
- /para
-   /listitem
-  /itemizedlist
+  A system compositor can run from early boot until shutdown.
+  It effectively replaces the kernel vt system, and can tie in
+  with the systems graphical boot setup and multiseat support.
+/para
+para
+  A system compositor can host different types of session
+  compositors, and let us switch between multiple sessions
+  (fast user switching, or secure/personal desktop switching).
+/para
+para
+  A linux implementation of a system compositor will typically
+  use libudev, egl, kms, evdev and cairo.
+/para
+para
+  For fullscreen clients, the system compositor can reprogram the
+  video scanout address to read directly from the client provided
+  buffer.
 /para
   /section
   section id=sect-Compositors-Session-Compositor
 titleSession Compositor/title
 para
+  A session compositor is responsible for a single user session.
+  If a system compositor is present, the session compositor will
+  run nested under the system compositor. Nesting is feasible because
+  the protocol is asynchronous; roundtrips would be too expensive
+  when nesting is involved. If no system compositor is present, a
+  session compositor can run directly on the hw.
+ /para
+ para
+  X applications can continue working under a session compositor
+  by means of a root less X server that is activated on demand.
+ /para
+para
+   Possible examples for session compositors include
   itemizedlist
-   listitem
- para
-   nested under the system compositor.  nesting is feasible because
-   protocol is async, roundtrip would break nesting
- /para
-   /listitem
-   listitem
- para
+listitem
+  para
gnome-shell
  /para
/listitem
@@ -66,17 +62,12 @@
/listitem
listitem
  para
-   compiz?
- /para
-   /listitem
-   listitem
- para
-   kde compositor?
+   kwin
  /para
/listitem
listitem
  para
-   text mode using vte
+   kmscon
  /para
/listitem
listitem
@@ -89,29 +80,17 @@
fullscreen X session under wayland
  /para
/listitem
-   listitem
- para
-   can run without system compositor, on the hw where it makes
-   sense
- /para
-   /listitem
-   listitem
- para
-   root window less X server, bridging X windows into a wayland
-   session compositor
- /para
-   /listitem
   /itemizedlist
 /para
   /section
   section id=sect-Compositors-Embedding-Compositor
 titleEmbedding Compositor/title
 para
-  X11 lets clients embed windows from other clients, or lets client copy
-  pixmap contents rendered by another client into their window.  This is
-  often used for applets in a panel, browser plugins and similar.
+  X11 lets clients embed windows from other clients, or lets clients
+  copy pixmap contents rendered by another client into their window.
+  This is often used for applets in a panel, browser plugins and similar.
   Wayland doesn't directly allow this, but clients can communicate GEM
-  buffer names out-of-band

[PATCH 04/21] docs: Improve the 'Connect time' section

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Turn the bullet-point list into complete sentences.
---
 doc/Wayland/en_US/Protocol.xml | 19 ---
 1 file changed, 4 insertions(+), 15 deletions(-)

diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
index cab68a8..955b054 100644
--- a/doc/Wayland/en_US/Protocol.xml
+++ b/doc/Wayland/en_US/Protocol.xml
@@ -73,7 +73,7 @@
   itemizedlist
listitem
  para
-   The first word is the sender's object id (32-bit).
+   The first word is the sender's object ID (32-bit).
  /para
/listitem
listitem
@@ -167,20 +167,9 @@
   section id=sect-Protocol-Connect-Time
 titleConnect Time/title
 para
-  itemizedlist
-   listitem
- para
-   no fixed format connect block, the server emits a bunch of
-   events at connect time
- /para
-   /listitem
-   listitem
- para
-   presence events for global objects: output, compositor, input
-   devices
- /para
-   /listitem
-  /itemizedlist
+  There is no fixed connection setup information, the server emits
+  multiple events at connect time, to indicate the presence and
+  properties of global objects: outputs, compositor, input devices.
 /para
   /section
   section id=sect-Protocol-Security-and-Authentication
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 05/21] doc: Improve various sections of the documentation

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

---
 doc/Wayland/en_US/Protocol.xml | 71 ++
 1 file changed, 31 insertions(+), 40 deletions(-)

diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
index 955b054..9bc8232 100644
--- a/doc/Wayland/en_US/Protocol.xml
+++ b/doc/Wayland/en_US/Protocol.xml
@@ -196,19 +196,10 @@
   section id=sect-Protocol-Creating-Objects
 titleCreating Objects/title
 para
-  itemizedlist
-   listitem
- para
-   client allocates object ID, uses range protocol
- /para
-   /listitem
-   listitem
- para
-   server tracks how many IDs are left in current range, sends
-   new range when client is about to run out.
- /para
-   /listitem
-  /itemizedlist
+  Each object has a unique ID. The IDs are allocated by the
+  client, from a range of IDs. The server tracks how many
+  IDs are left in the current range and sends a new range
+  when the client is about to run out.
 /para
   /section
   section id=sect-Protocol-Compositor
@@ -222,24 +213,22 @@
 /para
   /section
   section id=sect-Protocol-Surface
-titleSurface/title
+titleSurfaces/title
 para
-  Created by the client.
+  Surfaces are created by the client.
 /para
 para
   See xref linkend=protocol-spec-interface-wl_surface/ for the protocol
   description.
 /para
-para
-  Needs a way to set input region, opaque region.
-/para
   /section
   section id=sect-Protocol-Input
 titleInput/title
 para
-  Represents a group of input devices, including mice, keyboards.  Has a
-  keyboard and pointer focus.  Global object.  Pointer events are
-  delivered in both screen coordinates and surface local coordinates.
+  A seat represents a group of input devices including mice,
+  keyboards and touchscreens. It has a keyboard and pointer
+  focus. Seats are global objects. Pointer events are delivered
+  in surface local coordinates.
 /para
 para
   See xref linkend=protocol-spec-interface-wl_seat/ for the
@@ -331,21 +320,23 @@
 /itemizedlist
   /section
   section id=sect-Protocol-data-sharing
-titleData sharing between client (selection and drag and drop)/title
+titleData sharing between clients/title
 para
-  The Wayland 1.0 protocol provides its clients a mechanism for sharing
-  data that allows the implementation of selection and drag and drop.
-  The client providing the data creates a wl_data_source object and the
-  clients obtaining the data will see it as wl_data_offer object. This
-  interface allows the clients to agree on a mutually supported mime type
-  and transfer the data through an fd that is passed through the protocol.
+  The Wayland protocol provides clients a mechanism for sharing
+  data that allows the implementation of copy-paste and
+  drag-and-drop. The client providing the data creates a
+  functionwl_data_source/function object and the clients
+  obtaining the data will see it as functionwl_data_offer/function
+  object. This interface allows the clients to agree on a mutually
+  supported mime type and transfer the data via a file descriptor
+  that is passed through the protocol.
 /para
 para
-  The next section explains the negotiation between data source and data
-  offer objects. xref linkend=sect-Protocol-data-sharing-devices/
-  explains how these objects are created and passed to different client
-  using the wl_data_device interface, that implements selection and drag
-  and drop support.
+  The next section explains the negotiation between data source and
+  data offer objects. xref linkend=sect-Protocol-data-sharing-devices/
+  explains how these objects are created and passed to different
+  clients using the functionwl_data_device/function interface
+  that implements copy-paste and drag-and-drop support.
 /para
 para
   See xref linkend=protocol-spec-interface-wl_data_offer/,
@@ -363,7 +354,7 @@
 section
   titleData negotiation/title
   para
-   A client providing data to other clients will create a wl_data_source
+   A client providing data to other clients will create a 
functionwl_data_source/function
object and advertise the mime types for the formats it supports for
that data through the functionwl_data_source.offer/function
request. On the receiving end, the data offer object will generate one
@@ -373,18 +364,18 @@
   para
The actual data transfer happens when the receiving client sends a
functionwl_data_offer.receive/function request. This request takes
-   a mime type and an fd as arguments. This request will generate a
+   a mime type and a file descriptor as arguments. This request will 
generate

[PATCH 06/21] docs: Consistency fixes

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Say 'object ID' throughout.
---
 doc/Wayland/en_US/Protocol.xml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
index 9bc8232..58a5962 100644
--- a/doc/Wayland/en_US/Protocol.xml
+++ b/doc/Wayland/en_US/Protocol.xml
@@ -9,15 +9,15 @@
 titleBasic Principles/title
 para
   The wayland protocol is an asynchronous object oriented protocol.  All
-  requests are method invocations on some object.  The request include
-  an object id that uniquely identifies an object on the server.  Each
+  requests are method invocations on some object.  The requests include
+  an object ID that uniquely identifies an object on the server.  Each
   object implements an interface and the requests include an opcode that
   identifies which method in the interface to invoke.
 /para
 para
   The server sends back events to the client, each event is emitted from
   an object.  Events can be error conditions.  The event includes the
-  object id and the event opcode, from which the client can determine
+  object ID and the event opcode, from which the client can determine
   the type of event.  Events are generated both in response to requests
   (in which case the request and the event constitutes a round trip) or
   spontaneously when the server state changes.
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 07/21] docs: Improve wl_display protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

This adds a bit of information about in-order event delivery,
removes extraneous formatting, and adds a missing period.
---
 protocol/wayland.xml | 17 +
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 9d276f8..8587b8f 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -36,9 +36,10 @@
 request name=sync
   description summary=asynchronous roundtrip
The sync request asks the server to emit the 'done' event
-   on the provided wl_callback object.  Since requests are
-   handled in-order, this can be used as a barrier to ensure all
-   previous requests have been handled.
+   on the returned wl_callback object.  Since requests are
+   handled in-order and events are delivered in-order, this can
+   used as a barrier to ensure all previous requests and the
+   resulting events have been handled.
   /description
   arg name=callback type=new_id interface=wl_callback/
 /request
@@ -55,11 +56,11 @@
 event name=error
   description summary=fatal error event
The error event is sent out when a fatal (non-recoverable)
-   error has occurred.  The @object_id argument is the object
+   error has occurred.  The object_id argument is the object
where the error occurred, most often in response to a request
-   to that object.  The @code identifies the error and is defined
+   to that object.  The code identifies the error and is defined
by the object interface.  As such, each interface defines its
-   own set of error codes.  The @message is an brief description
+   own set of error codes.  The message is an brief description
of the error, for (debugging) convenience.
   /description
   arg name=object_id type=object/
@@ -81,12 +82,12 @@
 /enum
 
 event name=delete_id
-  description summary=acknowledge object id deletion
+  description summary=acknowledge object ID deletion
This event is used internally by the object ID management
logic.  When a client deletes an object, the server will send
this event to acknowledge that it has seen the delete request.
When the client receive this event, it will know that it can
-   safely reuse the object ID
+   safely reuse the object ID.
   /description
   arg name=id type=uint /
 /event
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 09/21] docs: Improve wl_callback protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Add some information about wl_callback and its done event.
---
 protocol/wayland.xml | 9 -
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index ad72fd1..cc009eb 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -157,8 +157,15 @@
   /interface
 
   interface name=wl_callback version=1
+description summary=callback object
+  Clients can handle the 'done' event to get notified when
+  the related request is done.
+/description
 event name=done
-  arg name=serial type=uint/
+  description summary=done event
+   Notify the client when the related request is done.
+  /description
+  arg name=serial type=uint summary=serial of the event/
 /event
   /interface
 
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 10/21] docs: Improve wl_shm and wl_shm_pool protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Reword some paragraphs, and spell out 'file descriptor'.
---
 protocol/wayland.xml | 73 +++-
 1 file changed, 49 insertions(+), 24 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index cc009eb..31d7ce8 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -196,20 +196,21 @@
   The wl_shm_pool object encapsulates a piece of memory shared
   between the compositor and client.  Through the wl_shm_pool
   object, the client can allocate shared memory wl_buffer objects.
-  The objects will share the same underlying mapped memory.
-  Reusing the mapped memory avoids the setup/teardown overhead and
-  is useful when interactively resizing a surface or for many
-  small buffers.
+  All objects created through the same pool share the same
+  underlying mapped memory. Reusing the mapped memory avoids the
+  setup/teardown overhead and is useful when interactively resizing
+  a surface or for many small buffers.
 /description
 
 request name=create_buffer
-  description summary=create wl_buffer from pool
-   Create a wl_buffer from the pool.  The buffer is created a
-   offset bytes into the pool and has width and height as
-   specified.  The stride arguments specifies the number of bytes
-   from beginning of one row to the beginning of the next.  The
-   format is the pixel format of the buffer and must be one of
-   those advertised through the wl_shm.format event.
+  description summary=create a buffer from the pool
+   Create a wl_buffer object from the pool.
+
+   The buffer is created offset bytes into the pool and has
+   width and height as specified.  The stride arguments specifies
+   the number of bytes from beginning of one row to the beginning
+   of the next.  The format is the pixel format of the buffer and
+   must be one of those advertised through the wl_shm.format event.
 
A buffer will keep a reference to the pool it was created from
so it is valid to destroy the pool immediately after creating
@@ -226,15 +227,19 @@
 
 request name=destroy type=destructor
   description summary=destroy the pool
-   Destroy the pool.
+   Destroy the shared memory pool.
+
+   The mmapped memory will be released when all
+   buffers that have been created from this pool
+   are gone.
   /description
 /request
 
 request name=resize
   description summary=change the size of the pool mapping
This request will cause the server to remap the backing memory
-   for the pool from the fd passed when the pool was creating but
-   using the new size.
+   for the pool from the file descriptor passed when the pool was
+   created, but using the new size.
   /description
 
   arg name=size type=int/
@@ -243,26 +248,41 @@
 
   interface name=wl_shm version=1
 description summary=shared memory support
-  Support for shared memory buffers.
+  A global singleton object that provides support for shared
+  memory.
+
+  Clients can create wl_shm_pool objects using the create_pool
+  request.
+
+  At connection setup time, the wl_shm object emits one or more
+  format events to inform clients about the valid pixel formats
+  that can be used for buffers.
 /description
 
 enum name=error
-  entry name=invalid_format value=0/
-  entry name=invalid_stride value=1/
-  entry name=invalid_fd value=2/
+  description summary=wl_shm error values
+   These errors can be emitted in response to wl_shm requests.
+  /description
+  entry name=invalid_format value=0 summary=buffer format is not 
known/
+  entry name=invalid_stride value=1 summary=invalid size or stride 
during pool or buffer creation/
+  entry name=invalid_fd value=2 summary=mmapping the file descriptor 
failed/
 /enum
 
 enum name=format
-  entry name=argb value=0/
-  entry name=xrgb value=1/
+  description summary=pixel formats
+   This describes the memory layout of an individual pixel.
+  /description
+  entry name=argb value=0 summary=32-bit ARGB format/
+  entry name=xrgb value=1 summary=32-bit RGB format/
 /enum
 
 request name=create_pool
   description summary=create a shm pool
-   This creates wl_shm_pool object, which can be used to create
-   shared memory based wl_buffer objects.  The server will mmap
-   size bytes of the passed fd, to use as backing memory for then
-   pool.
+   Create a new wl_shm_pool object.
+
+   The pool can be used to create shared memory based buffer
+   objects.  The server will mmap size bytes of the passed file
+descriptor, to use as backing memory for the pool.
   /description
 
   arg name=id type=new_id interface=wl_shm_pool/
@@ -271,6

[PATCH 11/21] docs: Improve the wl_data_* procol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Add a few missing summaries and descriptions, spell out file
descriptor, use hyphens in drag-and-drop, don't use hyphens in
'mime type', and reword a few things.
---
 protocol/wayland.xml | 95 +++-
 1 file changed, 65 insertions(+), 30 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 31d7ce8..2417c0e 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -348,22 +348,26 @@
 /description
 
 request name=accept
-  description summary=accept one of the offered mime-types
-   Indicate that the client can accept the given mime-type, or
-   NULL for not accepted.  Use for feedback during drag and drop.
+  description summary=accept one of the offered mime types
+   Indicate that the client can accept the given mime type, or
+   NULL for not accepted.
+
+   Used for feedback during drag-and-drop.
   /description
 
   arg name=serial type=uint/
-  arg name=type type=string allow-null=true/
+  arg name=mime_type type=string allow-null=true/
 /request
 
 request name=receive
   description summary=request that the data is transferred
To transfer the offered data, the client issues this request
-   and indicates the mime-type it wants to receive.  The transfer
-   happens through the passed fd (typically a pipe(7) file
-   descriptor).  The source client writes the data in the
-   mime-type representation requested and then closes the fd.
+   and indicates the mime type it wants to receive.  The transfer
+   happens through the passed file descriptor (typically created
+   with the pipe system call).  The source client writes the data
+   in the mime type representation requested and then closes the
+   file descriptor.
+
The receiving client reads from the read end of the pipe until
EOF and the closes its end, at which point the transfer is
complete.
@@ -372,15 +376,19 @@
   arg name=fd type=fd/
 /request
 
-request name=destroy type=destructor/
+request name=destroy type=destructor
+  description summary=destroy data offer
+   Destroy the data offer.
+  /description
+/request
 
 event name=offer
-  description summary=advertise offered mime-type
+  description summary=advertise offered mime type
Sent immediately after creating the wl_data_offer object.  One
event per offered mime type.
   /description
 
-  arg name=type type=string/
+  arg name=mime_type type=string/
 /event
   /interface
 
@@ -394,11 +402,11 @@
 
 request name=offer
   description summary=add an offered mime type
-   This request adds a mime-type to the set of mime-types
+   This request adds a mime type to the set of mime types
advertised to targets.  Can be called several times to offer
multiple types.
   /description
-  arg name=type type=string/
+  arg name=mime_type type=string/
 /request
 
 request name=destroy type=destructor
@@ -408,9 +416,11 @@
 /request
 
 event name=target
-  description summary=a target accepts an offered mime-type
+  description summary=a target accepts an offered mime type
Sent when a target accepts pointer_focus or motion events.  If
a target does not accept any of the offered types, type is NULL.
+
+   Used for feedback during drag-and-drop.
   /description
 
   arg name=mime_type type=string allow-null=true/
@@ -418,8 +428,9 @@
 
 event name=send
   description summary=send the data
-   Request for data from another client.  Send the data as the
-   specified mime-type over the passed fd, then close the fd.
+   Request for data from the client.  Send the data as the
+   specified mime type over the passed file descriptor, then
+   close it.
   /description
 
   arg name=mime_type type=string/
@@ -436,9 +447,16 @@
   /interface
 
   interface name=wl_data_device version=1
+description summary=data transfer device
+  There is one wl_data_device per seat which can be obtained
+  from the global wl_data_device_manager singleton.
+
+  A wl_data_device provides access to inter-client data transfer
+  mechanisms such as copy-and-paste and drag-and-drop.
+/description
 request name=start_drag
-  description summary=start drag and drop operation
-   This request asks the compositor to start a drag and drop
+  description summary=start drag-and-drop operation
+   This request asks the compositor to start a drag-and-drop
operation on behalf of the client.
 
The source argument is the data source that provides the data
@@ -451,7 +469,7 @@
the client must have an active implicit grab that matches the
serial.
 
-   The icon surface is an optional (can be nil) surface that
+   The icon

[PATCH 12/21] docs: Improve wl_shell/wl_shell_surface docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Add missing summaries, expand descriptions.
---
 protocol/wayland.xml | 233 ---
 1 file changed, 149 insertions(+), 84 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 2417c0e..a3599f0 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -597,7 +597,20 @@
   /interface
 
   interface name=wl_shell version=1
+description summary=create desktop-style surfaces
+  This interface is implemented by servers that provide
+  desktop-style user interfaces.
+
+  It allows clients to associate a wl_shell_surface with
+  a basic surface.
+/description
+
 request name=get_shell_surface
+  description summary=create a shell surface from a surface
+   Create a shell surface for an existing surface.
+
+   Only one shell surface can be associated with a given surface.
+  /description
   arg name=id type=new_id interface=wl_shell_surface/
   arg name=surface type=object interface=wl_surface/
 /request
@@ -605,11 +618,18 @@
 
   interface name=wl_shell_surface version=1
 
-description summary=desktop style meta data interface
-  An interface implemented by a wl_surface.  On server side the
-  object is automatically destroyed when the related wl_surface is
-  destroyed.  On client side, wl_shell_surface_destroy() must be
-  called before destroying the wl_surface object.
+description summary=desktop-style metadata interface
+  An interface that may be implemented by a wl_surface, for
+  implementations that provide a desktop-style user interface.
+
+  It provides requests to treat surfaces like toplevel, fullscreen
+  or popup windows, move, resize or maximize them, associate
+  metadata like title and class, etc.
+
+  On the server side the object is automatically destroyed when
+  the related wl_surface is destroyed.  On client side,
+  wl_shell_surface_destroy() must be called before destroying
+  the wl_surface object.
 /description
 
 request name=pong
@@ -617,15 +637,28 @@
A client must respond to a ping event with a pong request or
the client may be deemed unresponsive.
   /description
-  arg name=serial type=uint/
+  arg name=serial type=uint summary=serial of the ping event/
 /request
 
 request name=move
-  arg name=seat type=object interface=wl_seat/
-  arg name=serial type=uint/
+  description summary=start an interactive move
+   Start a pointer-driven move of the surface.
+
+   This request must be used in response to a button press event.
+   The server may ignore move requests depending on the state of
+   the surface (e.g. fullscreen or maximized).
+  /description
+  arg name=seat type=object interface=wl_seat summary=the wl_seat 
whose pointer is used/
+  arg name=serial type=uint summary=serial of the implicit grab on 
the pointer/
 /request
 
 enum name=resize
+  description summary=edge values for resizing
+   These values are used to indicate which edge of a surface
+   is being dragged in a resize operation. The server may
+   use this information to adapt its behavior, e.g. choose
+   an appropriate cursor image.
+  /description
   entry name=none value=0/
   entry name=top value=1/
   entry name=bottom value=2/
@@ -638,31 +671,43 @@
 /enum
 
 request name=resize
-  arg name=seat type=object interface=wl_seat/
-  arg name=serial type=uint/
-  arg name=edges type=uint/
+  description summary=start an interactive resize
+   Start a pointer-driven resizing of the surface.
+
+   This request must be used in response to a button press event.
+   The server may ignore resize requests depending on the state of
+   the surface (e.g. fullscreen or maximized).
+  /description
+  arg name=seat type=object interface=wl_seat summary=the wl_seat 
whose pointer is used/
+  arg name=serial type=uint summary=serial of the implicit grab on 
the pointer/
+  arg name=edges type=uint summary=which edge or corner is being 
dragged/
 /request
 
 request name=set_toplevel
-  description summary=make the surface a top level surface
-   Make the surface a toplevel window.
+  description summary=make the surface a toplevel surface
+   Map the surface as a toplevel surface.
+
+   A toplevel surface is not fullscreen, maximized or transient.
   /description
 /request
 
 enum name=transient
+  description summary=details of transient behaviour
+   These flags specify details of the expected behaviour
+   of transient surfaces. Used in the set_transient request.
+  /description
   entry name=inactive value=0x1 summary=do not set keyboard focus/
 /enum
 
 request name=set_transient
   description summary=make the surface a transient surface

[PATCH 13/21] docs: Improve wl_surface protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Use NULL consistently. And add some more information in a few
places.
---
 protocol/wayland.xml | 123 +--
 1 file changed, 69 insertions(+), 54 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index a3599f0..3e674f3 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -874,48 +874,54 @@
 
   interface name=wl_surface version=2
 description summary=an onscreen surface
-  A surface.  This is an image that is displayed on the screen.
+  A surface is a rectangular area that is displayed on the screen.
   It has a location, size and pixel contents.
+
+  Surfaces are also used for some special purposes, e.g. as
+  cursor images for pointers, drag icons, etc.
 /description
 
 request name=destroy type=destructor
   description summary=delete surface
-   Deletes the surface and invalidates its object id.
+   Deletes the surface and invalidates its object ID.
   /description
 /request
 
 request name=attach
   description summary=set the surface contents
-   Set the contents of a buffer into this surface. The x and y
-   arguments specify the location of the new pending buffer's upper
-   left corner, relative to the current buffer's upper left corner. In
-   other words, the x and y, and the width and height of the wl_buffer
-   together define in which directions the surface's size changes.
+   Set a buffer as the content of this surface.
+
+   The x and y arguments specify the location of the new pending
+   buffer's upper left corner, relative to the current buffer's
+   upper left corner. In other words, the x and y, and the width
+   and height of the wl_buffer together define in which directions
+   the surface's size changes.
 
Surface contents are double-buffered state, see wl_surface.commit.
 
The initial surface contents are void; there is no content.
-   wl_surface.attach assigns the given wl_buffer as the pending wl_buffer.
-   wl_surface.commit makes the pending wl_buffer the new
+   wl_surface.attach assigns the given wl_buffer as the pending
+   wl_buffer. wl_surface.commit makes the pending wl_buffer the new
surface contents, and the size of the surface becomes the size of
-   the wl_buffer. After commit, there is no pending buffer until the
-   next attach.
+   the wl_buffer, as described above. After commit, there is no
+   pending buffer until the next attach.
 
Committing a pending wl_buffer allows the compositor to read the
-   pixels in the wl_buffer. The compositor may access the pixels at any
-   time after the wl_surface.commit request. When the compositor will
-   not access the pixels anymore, it will send the wl_buffer.release
-   event. Only after receiving wl_buffer.release, the client may re-use
-   the wl_buffer. A wl_buffer, that has been attached and then replaced
-   by another attach instead of committed, will not receive a release
-   event, and is not used by the compositor.
-
-   Destroying the wl_buffer after wl_buffer.release does not change the
-   surface contents. However, if the client destroys the wl_buffer
-   before receiving wl_buffer.release, the surface contents become
-   undefined immediately.
-
-   Only if wl_surface.attach is sent with a nil wl_buffer, the
+   pixels in the wl_buffer. The compositor may access the pixels at
+   any time after the wl_surface.commit request. When the compositor
+   will not access the pixels anymore, it will send the
+   wl_buffer.release event. Only after receiving wl_buffer.release,
+   the client may re-use the wl_buffer. A wl_buffer that has been
+   attached and then replaced by another attach instead of committed
+   will not receive a release event, and is not used by the
+   compositor.
+
+   Destroying the wl_buffer after wl_buffer.release does not change
+   the surface contents. However, if the client destroys the
+   wl_buffer before receiving wl_buffer.release, the surface
+   contents become undefined immediately.
+
+   Only if wl_surface.attach is sent with a NULL wl_buffer, the
following wl_surface.commit will remove the surface content.
   /description
 
@@ -928,18 +934,20 @@
   description summary=mark part of the surface damaged
This request is used to describe the regions where the pending
buffer is different from the current surface contents, and where
-   the surface therefore needs to be repainted. The pending buffer must
-   be set by wl_surface.attach before sending damage. The compositor
-   ignores the parts of the damage that fall outside of the surface.
+   the surface therefore needs to be repainted. The pending buffer
+   must be set by wl_surface.attach before

[PATCH 14/21] docs: Improve the wl_seat protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Expand the main description and tell if requests don't have
an effect.
---
 protocol/wayland.xml | 35 ++-
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 3e674f3..442862d 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1105,28 +1105,28 @@
/interface
 
   interface name=wl_seat version=1
-description summary=seat
-  A group of keyboards, pointer (mice, for example) and touch
-  devices . This object is published as a global during start up,
-  or when such a device is hot plugged.  A seat typically has a
-  pointer and maintains a keyboard_focus and a pointer_focus.
+description summary=group of input devices
+  A seat is a group of keyboards, pointer (mice, for example) and
+  touch devices. This object is published as a global during
+  start up, or when such a device is hot plugged.  A seat typically
+  has a pointer and maintains a keyboard focus, a pointer focus and
+  a touch focus.
 /description
 
 enum name=capability
   description summary=seat capability bitmask
 This is a bitmask of capabilities this seat has; if a member is
-   set, then it is present on the seat.
+set, then it is present on the seat.
   /description
-  entry name=pointer value=1 summary=wl_pointer/
-  entry name=keyboard value=2 summary=wl_keyboard/
-  entry name=touch value=4 summary=wl_touch/
+  entry name=pointer value=1 summary=The seat has pointer devices/
+  entry name=keyboard value=2 summary=The seat has one or more 
keyboards/
+  entry name=touch value=4 summary=The seat has touch devices/
 /enum
 
-
 event name=capabilities
   description summary=seat capabilities changed
 This is emitted whenever a seat gains or loses the pointer,
-   keyboard or touch capabilities.  The argument is a wl_seat_caps_mask
+   keyboard or touch capabilities.  The argument is a capability
enum containing the complete set of capabilities this seat has.
   /description
   arg name=capabilities type=uint/
@@ -1136,22 +1136,31 @@
   description summary=return pointer object
 The ID provided will be initialized to the wl_pointer interface
for this seat.
+
+This request only takes effect if the seat has the pointer
+capability.
   /description
   arg name=id type=new_id interface=wl_pointer/
 /request
 
 request name=get_keyboard
-  description summary=return pointer object
+  description summary=return keyboard object
 The ID provided will be initialized to the wl_keyboard interface
for this seat.
+
+This request only takes effect if the seat has the keyboard
+capability.
   /description
   arg name=id type=new_id interface=wl_keyboard/
 /request
 
 request name=get_touch
-  description summary=return pointer object
+  description summary=return touch object
 The ID provided will be initialized to the wl_touch interface
for this seat.
+
+This request only takes effect if the seat has the touch
+capability.
   /description
   arg name=id type=new_id interface=wl_touch/
 /request
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 15/21] docs: Improve wl_pointer protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Some descriptions were missing here.
---
 protocol/wayland.xml | 43 +--
 1 file changed, 33 insertions(+), 10 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 442862d..87e3d5f 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1167,6 +1167,17 @@
   /interface
 
   interface name=wl_pointer version=1
+description summary=pointer input device
+  The wl_pointer interface represents one or more input devices,
+  such as mice, which control the pointer location and pointer_focus
+  of a seat.
+
+  The wl_pointer interface generates motion, enter and leave
+  events for the surfaces that the pointer is located over,
+  and button and axis events for button presses, button releases
+  and scrolling.
+/description
+
 request name=set_cursor
   description summary=set the pointer surface
Set the pointer surface, i.e., the surface that contains the
@@ -1197,7 +1208,7 @@
undefined, and the wl_surface is unmapped.
   /description
 
-  arg name=serial type=uint/
+  arg name=serial type=uint summary=serial of the enter event/
   arg name=surface type=object interface=wl_surface 
allow-null=true/
   arg name=hotspot_x type=int/
   arg name=hotspot_y type=int/
@@ -1206,9 +1217,11 @@
 event name=enter
   description summary=enter event
Notification that this seat's pointer is focused on a certain
-   surface. When an seat's focus enters a surface, the pointer image
+   surface.
+
+   When an seat's focus enters a surface, the pointer image
is undefined and a client should respond to this event by setting
-   an appropriate pointer image.
+   an appropriate pointer image with the set_cursor request.
   /description
 
   arg name=serial type=uint/
@@ -1219,6 +1232,11 @@
 
 event name=leave
   description summary=leave event
+   Notification that this seat's pointer is no longer focused on
+   a certain surface.
+
+   The leave notification is sent before the enter notification
+   for the new focus.
   /description
   arg name=serial type=uint/
   arg name=surface type=object interface=wl_surface/
@@ -1226,8 +1244,9 @@
 
 event name=motion
   description summary=pointer motion event
-   Notification of pointer location change. The arguments surface_[xy]
-   are the location relative to the focused surface.
+   Notification of pointer location change. The arguments
+   surface_x and surface_y are the location relative to the
+   focused surface.
   /description
 
   arg name=time type=uint/
@@ -1240,14 +1259,16 @@
 Describes the physical state of a button which provoked the button
event.
   /description
-  entry name=released value=0 summary=button is not pressed/
-  entry name=pressed value=1 summary=button is pressed/
+  entry name=released value=0 summary=The button is not pressed/
+  entry name=pressed value=1 summary=The button is pressed/
 /enum
 
 event name=button
   description summary=pointer button event
-   Mouse button click and release notifications.  The location
-   of the click is given by the last motion or pointer_focus event.
+   Mouse button click and release notifications.
+
+   The location of the click is given by the last motion or
+   enter event.
   /description
 
   arg name=serial type=uint/
@@ -1257,7 +1278,9 @@
 /event
 
 enum name=axis
-  description summary=axis types/
+  description summary=axis types
+   Describes the axis types of scroll events.
+  /description
   entry name=vertical_scroll value=0/
   entry name=horizontal_scroll value=1/
 /enum
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 16/21] docs: Improve wl_keyboard protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Some descriptions were missing here.
---
 protocol/wayland.xml | 25 +++--
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 87e3d5f..52bc98f 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1313,19 +1313,21 @@
 
   interface name=wl_keyboard version=1
 description summary=keyboard input device
+  The wl_keyboard interface represents one or more keyboards
+  associated with a seat.
 /description
 
 enum name=keymap_format
   description summary=keyboard mapping format
-This enum specifies the format of the keymap provided to the client
-   with the wl_keyboard::keymap event.
+   This specifies the format of the keymap provided to the
+   client with the wl_keyboard.keymap event.
   /description
   entry name=xkb_v1 value=1 description=libxkbcommon compatible/
 /enum
 
 event name=keymap
   description summary=keyboard mapping
-This event provides a file descriptor to the client which can be
+   This event provides a file descriptor to the client which can be
memory-mapped to provide a keyboard mapping description.
   /description
   arg name=format type=uint/
@@ -1334,19 +1336,30 @@
 /event
 
 event name=enter
+  description summary=enter event
+   Notification that this seat's keyboard focus is on a certain
+   surface.
+  /description
   arg name=serial type=uint/
   arg name=surface type=object interface=wl_surface/
-  arg name=keys type=array/
+  arg name=keys type=array summary=the currently pressed keys/
 /event
 
 event name=leave
+  description summary=leave event
+   Notification that this seat's keyboard focus is no longer on
+   a certain surface.
+
+   The leave notification is sent before the enter notification
+   for the new focus.
+  /description
   arg name=serial type=uint/
   arg name=surface type=object interface=wl_surface/
 /event
 
 enum name=key_state
   description summary=physical key state
-Describes the physical state of a key which provoked the key event.
+   Describes the physical state of a key which provoked the key event.
   /description
   entry name=released value=0 summary=key is not pressed/
   entry name=pressed value=1 summary=key is pressed/
@@ -1365,7 +1378,7 @@
 
 event name=modifiers
   description summary=modifier and group state
-Notifies clients that the modifier and/or group state has
+   Notifies clients that the modifier and/or group state has
changed, and it should update its local state.
   /description
 
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 17/21] docs: Improve wl_touch protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Some descriptions were missing here.
---
 protocol/wayland.xml | 36 +++-
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 52bc98f..a53cb71 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1391,29 +1391,48 @@
   /interface
 
   interface name=wl_touch version=1
-description summary=touch screen input device
+description summary=touchscreen input device
+  The wl_touch interface represents a touchscreen
+  associated with a seat.
+
+  Touch interactions can consist of one or more contacts.
+  For each contact, a series of events is generated, starting
+  with a down event, followed by one or more motion events,
+  and ended with an up event. Events relating to the same
+  contact point can be identified by the ID of the sequence.
 /description
 
 event name=down
+  description summary=touch down event
+Notifies the client of a new contact point on one
+of its surfaces.
+  /description
   arg name=serial type=uint/
   arg name=time type=uint/
   arg name=surface type=object interface=wl_surface/
-  arg name=id type=int /
-  arg name=x type=fixed /
-  arg name=y type=fixed /
+  arg name=id type=int summary=ID of the touch sequence/
+  arg name=x type=fixed/
+  arg name=y type=fixed/
 /event
 
 event name=up
+  description summary=touch up event
+Notifies the client that a touch has ended.
+  /description
   arg name=serial type=uint/
   arg name=time type=uint/
-  arg name=id type=int /
+  arg name=id type=int/
 /event
 
 event name=motion
+  description summary=touch motion event
+Notifies the client that the position of a contact point
+has changed.
+  /description
   arg name=time type=uint/
-  arg name=id type=int /
-  arg name=x type=fixed /
-  arg name=y type=fixed /
+  arg name=id type=int summary=ID of the touch sequence/
+  arg name=x type=fixed/
+  arg name=y type=fixed/
 /event
 
 event name=frame
@@ -1431,7 +1450,6 @@
 /event
   /interface
 
-
   interface name=wl_output version=1
 description summary=compositor output region
   An output describes part of the compositor geometry.  The
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 18/21] docs: Improve the wl_output protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Some descriptions were missing.
---
 protocol/wayland.xml | 24 ++--
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index a53cb71..34a1bbf 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1453,14 +1453,18 @@
   interface name=wl_output version=1
 description summary=compositor output region
   An output describes part of the compositor geometry.  The
-  compositor work in the 'compositor coordinate system' and an
+  compositor works in the 'compositor coordinate system' and an
   output corresponds to rectangular area in that space that is
   actually visible.  This typically corresponds to a monitor that
   displays part of the compositor space.  This object is published
-  as global during start up, or when a screen is hot plugged.
+  as global during start up, or when a monitor is hotplugged.
 /description
 
 enum name=subpixel
+  description summary=subpixel geometry information
+   This enumeration describes how the physical
+   pixels on an output are layed out.
+  /description
   entry name=unknown value=0/
   entry name=none value=1/
   entry name=horizontal_rgb value=2/
@@ -1495,7 +1499,11 @@
 /enum
 
 event name=geometry
-  description summary=properties of the output/
+  description summary=properties of the output
+   The geometry event describes geometric properties of the output.
+   The event is sent when binding to the output object and whenever
+   any of the properties change.
+  /description
   arg name=x type=int
   summary=x position within the global compositor space/
   arg name=y type=int
@@ -1515,23 +1523,27 @@
 /event
 
 enum name=mode
-  description summary=values for the flags bitfield in the mode event/
+  description summary=mode information
+   These flags describe properties of an output mode.
+   They are used in the flags bitfield of the mode event.
+  /description
   entry name=current value=0x1
 summary=indicates this is the current mode/
   entry name=preferred value=0x2
 summary=indicates this is the preferred mode/
 /enum
-  
+
 event name=mode
   description summary=advertise available modes for the output
The mode event describes an available mode for the output.
+
The event is sent when binding to the output object and there
will always be one mode, the current mode.  The event is sent
again if an output changes mode, for the mode that is now
current.  In other words, the current mode is always the last
mode that was received with the current flag set.
   /description
-  arg name=flags type=uint summary=mask of wl_output_mode flags/
+  arg name=flags type=uint summary=bitfield of mode flags/
   arg name=width type=int summary=width of the mode in pixels/
   arg name=height type=int summary=height of the mode in pixels/
   arg name=refresh type=int summary=vertical refresh rate in mHz/
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 19/21] docs: Improve wl_region protocol docs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Just cosmetic changes, a few missing periods, and ID was
not capitalized.
---
 protocol/wayland.xml | 11 +++
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 34a1bbf..2a27b1b 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1552,18 +1552,21 @@
 
   interface name=wl_region version=1
 description summary=region interface
-  Region.
+  A region object describes an area.
+
+  Region objects are used to describe the opaque and input
+  regions of a surface.
 /description
 
 request name=destroy type=destructor
   description summary=destroy region
-   Destroy the region.  This will invalidate the object id.
+   Destroy the region.  This will invalidate the object ID.
   /description
 /request
 
 request name=add
   description summary=add rectangle to region
-   Add the specified rectangle to the region
+   Add the specified rectangle to the region.
   /description
 
   arg name=x type=int/
@@ -1574,7 +1577,7 @@
 
 request name=subtract
   description summary=subtract rectangle from region
-   Subtract the specified rectangle from the region
+   Subtract the specified rectangle from the region.
   /description
 
   arg name=x type=int/
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 20/21] docs: Add details about surfaces

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Mention some of the characteristic differences to X:
no global positions, no access to foreign windows.
---
 doc/Wayland/en_US/Protocol.xml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
index 58a5962..a645409 100644
--- a/doc/Wayland/en_US/Protocol.xml
+++ b/doc/Wayland/en_US/Protocol.xml
@@ -216,6 +216,8 @@
 titleSurfaces/title
 para
   Surfaces are created by the client.
+  Clients don't know the global position of their surfaces, and
+  cannot access other clients surfaces.
 /para
 para
   See xref linkend=protocol-spec-interface-wl_surface/ for the protocol
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 21/21] docs: Add details about grabs

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Mention implicit grabs, (lack of) explicit grabs, and popup
windows.
---
 doc/Wayland/en_US/Protocol.xml | 8 
 1 file changed, 8 insertions(+)

diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
index a645409..b94e9ca 100644
--- a/doc/Wayland/en_US/Protocol.xml
+++ b/doc/Wayland/en_US/Protocol.xml
@@ -233,6 +233,14 @@
   in surface local coordinates.
 /para
 para
+  The compositor maintains an implicit grab when a button is
+  pressed, to ensure that the corresponding button release
+  event gets delivered to the same surface. But there is way
+  for clients to take an explicit grab. Instead, surfaces can
+  be mapped as 'popup', which combines transient window semantics
+  with a pointer grab.
+/para
+para
   See xref linkend=protocol-spec-interface-wl_seat/ for the
   protocol description.
 /para
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

protocol questions

[Matthias Clasen]

Here are a few questions/observations I had while studying the protocol docs:

- The use of serials in events seems a bit inconsistent. Most
wl_pointer events have serials, but axis doesn't. wl_keyboard
enter/leave events do. wl_data_offer.enter does, but the corresponding
leave/motion events don't. Is there a rationale for this ?

- Various input events have a time field. The spec doesn't really say
anything about this. What is it good for, and what units are these -
monotonic time ?

- It looks like I can't trigger a popup from a key or touch event,
because set_popup requires a serial that corresponds to an implicit
pointer grab. That is sad, I like the menu key...

- Still on popups, I don't see a way for the client to dismiss the
popup, or is that handled by just destroying the surface ?

- Buffer transformations - fun. How do these relate to each of the following ?
   - resize edges
   - transient offset
   - buffer attach x/y
   - input/opaque/damage regions
   - surface x/y in motion events

- What is a wl_touch.frame event ? Weston doesn't seem to generate those...

- Various strings in the protocol: title, class, output model/make.
Are all of these required/known to be UTF-8 ? The class is documented
as being a file path, which is bad news wrt to encodings...

- The wl_pointer interface seems to be a bit weak wrt to device
properties. I would at least expect to learn about the number of
buttons and right-handed vs left-handed, etc.


Thanks for any insights you can share about these questions.


Matthias
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 0/2] Fix the documentation build

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Trying to write some review comments on the Wayland docs, I found
that the docs wouldn't build here, with publican 3.1.5. These two
patches make things work for me.

Matthias Clasen (2):
  docs: Add a revision history
  docs: Fix the documentation build

 doc/Wayland/Makefile.am| 3 ++-
 doc/Wayland/en_US/Revision_History.xml | 7 +++
 2 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 doc/Wayland/en_US/Revision_History.xml

-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 1/2] docs: Add a revision history

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

Publican complains if it can't find this file.
---
 doc/Wayland/Makefile.am| 1 +
 doc/Wayland/en_US/Revision_History.xml | 7 +++
 2 files changed, 8 insertions(+)
 create mode 100644 doc/Wayland/en_US/Revision_History.xml

diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
index 1d27b1a..4de2f83 100644
--- a/doc/Wayland/Makefile.am
+++ b/doc/Wayland/Makefile.am
@@ -8,6 +8,7 @@ publican_sources = \
$(srcdir)/en_US/Library.xml \
$(srcdir)/en_US/Compositors.xml \
$(srcdir)/en_US/Overview.xml \
+   $(srcdir)/en_US/Revision_History.xml \
$(srcdir)/en_US/images/icon.svg  \
$(srcdir)/en_US/images/wayland-architecture.png \
$(srcdir)/en_US/images/wayland.png  \
diff --git a/doc/Wayland/en_US/Revision_History.xml 
b/doc/Wayland/en_US/Revision_History.xml
new file mode 100644
index 000..2c540fe
--- /dev/null
+++ b/doc/Wayland/en_US/Revision_History.xml
@@ -0,0 +1,7 @@
+revhistory
+  revision
+revnumber1-0/revnumber
+authorinitialskrh/authorinitials
+revremarkInitial version/revremark
+  /revision
+/revhistory
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[PATCH 2/2] docs: Fix the documentation build

[matthias . clasen]

From: Matthias Clasen mcla...@redhat.com

The publican man page says that the options are actually called
--formats and --langs, and with this, the doc build succeeds.
---
 doc/Wayland/Makefile.am | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
index 4de2f83..a7e1b54 100644
--- a/doc/Wayland/Makefile.am
+++ b/doc/Wayland/Makefile.am
@@ -64,7 +64,7 @@ Wayland: $(publican_targets)
$(AM_V_GEN)$(PUBLICAN) rename --name Wayland \
--version $(WAYLAND_VERSION_MAJOR).$(WAYLAND_VERSION_MINOR) \
--config $(builddir)/publican-copy.cfg
-   $(AM_V_GEN)$(PUBLICAN) build --quiet --lang en-US --format html,pdf \
+   $(AM_V_GEN)$(PUBLICAN) build --quiet --langs en-US --formats html,pdf \
--config $(builddir)/publican-copy.cfg
@touch Wayland
 
-- 
1.8.1.4

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Re: I feel configure events and requests are messed up

[Matthias Clasen]

On Thu, 2011-09-08 at 22:35 +0200, Giovanni Campagna wrote:

 
 Probably I forgot to mention, but at the Desktop Summit it was agreed
 that client-side decorations won't happen, neither in KWin nor Mutter,
 so the client does not need to worry about what edges it should draw.

I think it is time for you to slow down and reconsider a bit. 
Whether client-side decorations happen in gtk and/or mutter is not for
you or the kwin maintainers to decide.

Matthias 

___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel