doc: fix and clarify pointer image behaviour

Signed-off-by: Yann Dirson <ydirson@free.fr>

diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index 69edd2c..a472f1d 100644 (file)
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -401,10 +401,11 @@
       set the pointer image.
     </para>
     <para>
+      Setting the pointer image to NULL causes the cursor to be hidden.
+    </para>
+    <para>
       The compositor will revert the pointer image back to a default image
-      when no surface has the pointer focus for that device.  Clients can
-      revert the pointer image back to the default image by setting a NULL
-      image.
+      when no surface has the pointer focus for that device.
     </para>
     <para>
       What if the pointer moves from one window which has set a special
@@ -412,7 +413,10 @@
       the motion event?  The new surface will be stuck with the special
       pointer image.  We can't just revert the pointer image on leaving a
       surface, since if we immediately enter a surface that sets a different
-      image, the image will flicker.  Broken app, I suppose.
+      image, the image will flicker.  If a client does not set a pointer image
+      when the pointer enters a surface, the pointer stays with the image set
+      by the last surface that changed it, possibly even hidden.  Such a client
+      is likely just broken.
     </para>
   </section>
   <section id="sect-Protocol-Output">