xdg-activation: rewrite and move description of token forwarding

After a requesting client receives a new token, the client usually forwards the
token string to another client by a different process, which then uses the
token in an activate request. For that the token string must be transferred to
the other process.

Two default ways of doing that were described in the done event, but the
description had some issues and it makes more sense to describe them in the
protocol description itself, which talks about the protocol in a more general
way. Therefore rewrite the paragraphs about token forwarding between clients
and place them in the protocol description.

Signed-off-by: Roman Gilg <subdiff@gmail.com>

1 files changed, 16 insertions, 13 deletions

diff --git a/staging/xdg-activation/xdg-activation-v1.xml b/staging/xdg-activation/xdg-activation-v1.xml
index df40629..4994298 100644
--- a/staging/xdg-activation/xdg-activation-v1.xml
+++ b/staging/xdg-activation/xdg-activation-v1.xml
@@ -30,8 +30,22 @@
 
     The client that intends to activate another toplevel uses the
     xdg_activation_v1.get_activation_token request to get an activation token.
-    This token is then passed to the client to be activated through a separate
-    band of communication. The client to be activated will then pass the token
+    This token is then forwarded to the client, which is supposed to activate
+    one of its surfaces, through a separate band of communication.
+
+    One established way of doing this is through the XDG_ACTIVATION_TOKEN
+    environment variable of a newly launched child process. The child process
+    should unset the environment variable again right after reading it out in
+    order to avoid propagating it to other child processes.
+
+    Another established way exists for Applications implementing the D-Bus
+    interface org.freedesktop.Application, which should get their token under
+    XDG_ACTIVATION_TOKEN on their platform_data.
+
+    In general activation tokens may be transferred across clients through
+    means not described in this protocol.
+
+    The client to be activated will then pass the token
     it received to the xdg_activation_v1.activate request. The compositor can
     then use this token to decide how to react to the activation request.
 
@@ -172,17 +186,6 @@
       <description summary="the exported activation token">
         The 'done' event contains the unique token of this activation request
         and notifies that the provider is done.
-
-        Applications will typically receive the token through the
-        XDG_ACTIVATION_TOKEN environment variable as set by its launcher, and
-        should unset the environment variable right after this request, in
-        order to avoid propagating it to child processes.
-
-        Applications implementing the D-Bus interface org.freedesktop.Application
-        should get their token under XDG_ACTIVATION_TOKEN on their platform_data.
-
-        Activation tokens may be transferred across clients through means not
-        described in this protocol.
       </description>
       <arg name="token" type="string" summary="the exported activation token"/>
     </event>