[PATCH 1/2] wm-spec: Move _NET_WM_SYNC_REQUEST to a separate section

[otaylor redhat com]

From: "Owen W. Taylor" <otaylor fishsoup net>

Move the discussion of _NET_WM_SYNC_REQUEST to a separate section,
which will also be used for application/compositing manager
synchronization protocols.
---
 wm-spec/wm-spec.xml | 129 +++++++++++++++++++++++++++++++---------------------
 1 file changed, 77 insertions(+), 52 deletions(-)

diff --git a/wm-spec/wm-spec.xml b/wm-spec/wm-spec.xml
index 87dc02d..8d83a94 100644
--- a/wm-spec/wm-spec.xml
+++ b/wm-spec/wm-spec.xml
@@ -1625,58 +1625,8 @@ See also the implementation notes on <link linkend="KILLINGWINDOWS">killing hung
     </sect2>
     <sect2>
 		<title>_NET_WM_SYNC_REQUEST</title>
-		<para>
-This protocol uses the XSync extension (see <ulink
-url="http://freedesktop.org/cgi-bin/viewcvs.cgi/xorg/xc/doc/hardcopy/Xext/sync.PS.gz";>the
-protocol specification</ulink> and <ulink
-url="http://freedesktop.org/cgi-bin/viewcvs.cgi/xorg/xc/doc/hardcopy/Xext/synclib.PS.gz";>
-the library documentation</ulink>) to let client and window manager
-synchronize the repaint of the window manager frame and the client
-window. A client indicates that it is willing to participate in the
-protocol by listing _NET_WM_SYNC_REQUEST in the WM_PROTOCOLS property
-of the client window and storing the XID of an XSync counter in the
-property _NET_WM_SYNC_REQUEST_COUNTER. The initial value of this
-counter is not defined by this specification.
-		</para>
-		<para>
-A window manager uses this protocol by preceding a ConfigureNotify
-event sent to a client by a client message as follows:
-		</para>
-		<programlisting><![CDATA[
-type = ClientMessage
-window = the respective client window
-message_type = WM_PROTOCOLS
-format = 32
-data.l[0] = _NET_WM_SYNC_REQUEST
-data.l[1] = timestamp
-data.l[2] = low 32 bits of the update request number
-data.l[3] = high 32 bits of the update request number
-other data.l[] elements = 0
-]]></programlisting>
-    
-		<para>
-After receiving one or more such message/ConfigureNotify pairs, and
-having handled all repainting associated with the ConfigureNotify
-events, the client MUST set the _NET_WM_SYNC_REQUEST_COUNTER to the 64
-bit number indicated by the data.l[2] and data.l[3] fields of the last
-client message received.
-		</para>
-		<para>
-By using either the Alarm or the Await mechanisms of the XSync
-extension, the window manager can know when the client has finished
-handling the ConfigureNotify events. The window manager SHOULD not
-resize the window faster than the client can keep up.
-		</para>
-		<para>
-The update request number in the client message is determined by the
-window manager subject to the restriction that it MUST NOT be 0. The
-number is generally intended to be incremented by one for each message
-sent. Since the initial value of the XSync counter is not defined by
-this specification, the window manager MAY set the value of the XSync
-counter at any time, and MUST do so when it first manages a new
-window.
-		</para>
-	</sect2>
+                <para>See <xref linkend="NET_WM_SYNC_REQUEST"/></para>
+    </sect2>
     <sect2>
 		<title>_NET_WM_FULLSCREEN_MONITORS</title>
 		<programlisting><![CDATA[
@@ -1810,6 +1760,81 @@ to the toplevel application window that contains the menubar.
     </sect2>
 </sect1>
 <sect1>
+  <title>Frame Synchronization</title>
+  <para>
+The final scene visible to the user is a combination of elements drawn by
+the application, the window manager, and the compositing manager. For optimum
+appearance and performance, the drawing done by the different processes
+should be properly synchronized. Examples: the window manager frame should only
+be drawn at a new size after the application contents are also resized to the
+new size. If the application is making several related changes to its window,
+such as scrolling and redrawing, the compositor should only redraw the
+window when all updates are done. The application should not be generating many
+frames of content when only one of them is drawn to the output device.
+  </para>
+  <para>
+Limited synchronization of window manager and client drawing during resizing
+is possible without a compositing manager, and is briefly described below,
+but the remaining protocols only make sense when there is a compositing
+manager. These protocols are additionally designed with the assumption that
+the window manager and the compositing manager are the same process, and are
+not applicable to the case of a stand-alone compositing manager.
+  </para>
+  <sect2 id="NET_WM_SYNC_REQUEST">
+    <title>_NET_WM_SYNC_REQUEST</title>
+    <para>
+This protocol uses the XSync extension (see <ulink
+url="http://freedesktop.org/cgi-bin/viewcvs.cgi/xorg/xc/doc/hardcopy/Xext/sync.PS.gz";>the
+protocol specification</ulink> and <ulink
+url="http://freedesktop.org/cgi-bin/viewcvs.cgi/xorg/xc/doc/hardcopy/Xext/synclib.PS.gz";>
+the library documentation</ulink>) to let client and window manager
+synchronize the repaint of the window manager frame and the client
+window. A client indicates that it is willing to participate in the
+protocol by listing _NET_WM_SYNC_REQUEST in the WM_PROTOCOLS property
+of the client window and storing the XID of an XSync counter in the
+property _NET_WM_SYNC_REQUEST_COUNTER. The initial value of this
+counter is not defined by this specification.
+    </para>
+    <para>
+A window manager uses this protocol by preceding a ConfigureNotify
+event sent to a client by a client message as follows:
+    </para>
+    <programlisting><![CDATA[
+type = ClientMessage
+window = the respective client window
+message_type = WM_PROTOCOLS
+format = 32
+data.l[0] = _NET_WM_SYNC_REQUEST
+data.l[1] = timestamp
+data.l[2] = low 32 bits of the update request number
+data.l[3] = high 32 bits of the update request number
+other data.l[] elements = 0
+]]></programlisting>
+    <para>
+After receiving one or more such message/ConfigureNotify pairs, and
+having handled all repainting associated with the ConfigureNotify
+events, the client MUST set the _NET_WM_SYNC_REQUEST_COUNTER to the 64
+bit number indicated by the data.l[2] and data.l[3] fields of the last
+client message received.
+    </para>
+    <para>
+By using either the Alarm or the Await mechanisms of the XSync
+extension, the window manager can know when the client has finished
+handling the ConfigureNotify events. The window manager SHOULD not
+resize the window faster than the client can keep up.
+    </para>
+    <para>
+The update request number in the client message is determined by the
+window manager subject to the restriction that it MUST NOT be 0. The
+number is generally intended to be incremented by one for each message
+sent. Since the initial value of the XSync counter is not defined by
+this specification, the window manager MAY set the value of the XSync
+counter at any time, and MUST do so when it first manages a new
+window.
+    </para>
+  </sect2>
+</sect1>
+<sect1>
 	<title>Implementation notes</title>
 	<sect2>
 		<title>Desktop/workspace model</title>
-- 
1.8.0.2