specs: convert protocol geproto.txt to DocBook XML

Signed-off-by: Gaetan Nadon <memsize@videotron.ca>

3 files changed, 99 insertions, 85 deletions

diff --git a/specs/Makefile.am b/specs/Makefile.am
index a1acb2e..3e631a1 100644
--- a/specs/Makefile.am
+++ b/specs/Makefile.am
@@ -27,6 +27,7 @@ doc_sources =		\
 	dbe.xml		\
 	dpms.xml	\
 	evi.xml		\
+	geproto.xml	\
 	multibuf.xml	\
 	security.xml	\
 	shape.xml	\
@@ -35,7 +36,7 @@ doc_sources =		\
 	tog-cup.xml	\
 	xtest.xml
 
-dist_doc_DATA = $(doc_sources) geproto.txt
+dist_doc_DATA = $(doc_sources)
 
 if HAVE_XMLTO
 doc_DATA = $(doc_sources:.xml=.html)
diff --git a/specs/geproto.txt b/specs/geproto.txt
deleted file mode 100644
index 1054def..0000000
--- a/specs/geproto.txt
+++ /dev/null
@@ -1,84 +0,0 @@
-                        X Generic Event Extension
-                              Peter Hutterer
-                          peter.hutterer@who-t.net
-
-
-1. Introduction
-2. Extension Initialization
-3. Events
-4. Notes
-
-_____________________________________________________________________________
-1. Introduction
-
-X was designed to provide 64 event opcodes for all extensions. These events
-are limited to 32 bytes.
-
-The Generic Event Extension provides a template event for extensions to re-use
-a single event opcode. GE only provide headers and the most basic
-functionality, leaving the extensions to interpret the events in their
-specific context.
-
-GenericEvents may be longer than 32 bytes. If so, the number of 4 byte units
-following the initial 32 bytes must be specified in the length field of the
-event.
-_____________________________________________________________________________
-2. Extension Initialization
-
-The name of this extension is "Generic Event Extension"
-
-┌───
-    GEQueryVersion
-	client-major-version:	CARD16
-	client-minor-version:	CARD16
-      ▶
-	major-version:		CARD16
-	minor-version:		CARD16
-└───
-
-	The client sends the highest supported version to the server
-	and the server sends the highest version it supports, but no
-	higher than the requested version. Major versions changes can
-	introduce incompatibilities in existing functionality, minor
-	version changes introduce only backward compatible changes.
-	It is the clients responsibility to ensure that the server
-	supports a version which is compatible with its expectations.
-
-
-        As of version 1.0, no other requests are provided by this extension.
-_____________________________________________________________________________
-3. Events
-
-GE defines a single event, to be used by all extensions. The event's structure
-is similar to a reply.  This is a core protocol event, ID 35, and is not itself
-an extension event.
-
-┌───
-    GenericEvent
-	type: BYTE;			always GenericEvent (35)
-	extension: CARD8;		extension offset
-	sequenceNumber: CARD16		low 16 bits of request seq. number
-	length: CARD32			length
-	evtype: CARD16			event type
-└───
-
-	The field 'extension' is to be set to the major opcode of the
-	extension. The 'evtype' field is the actual opcode of the event. 
-	The length field specifies the number of 4-byte blocks after the
-	initial 32 bytes. If length is 0, the event is 32 bytes long.
-_____________________________________________________________________________
-4. Notes
-
-Although the wire event is of arbitrary length, the actual size of an XEvent
-is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an extension
-converts a wire event to an XEvent > 96 bytes, it will overwrite the space
-allocated for the event. See struct _XSQEvent in Xlibint.h for details.
-
-Extensions need to malloc additional data and fill the XEvent structure with
-pointers to the malloc'd data. The client then needs to free the data, only
-the XEvent structure will be released by Xlib.
-
-The server must not send GenericEvents longer than 32 bytes until it has
-verified that the client is able to interpret these events. If a long event is
-sent to a client unable to process GenericEvents, future interpretation of
-replies and events by this client will fail.
diff --git a/specs/geproto.xml b/specs/geproto.xml
new file mode 100644
index 0000000..7bba357
--- /dev/null
+++ b/specs/geproto.xml
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<book>
+  <bookinfo>
+    <title>X Generic Event Extension</title>
+
+    <author>
+      <firstname>Peter</firstname>
+
+      <surname>Hutterer</surname>
+
+      <affiliation>
+        <orgname>peter.hutterer@who-t.net</orgname>
+      </affiliation>
+    </author>
+  </bookinfo>
+
+  <chapter>
+    <title>Introduction</title>
+
+    <para>X was designed to provide 64 event opcodes for all extensions. These
+    events are limited to 32 bytes.</para>
+
+    <para>The Generic Event Extension provides a template event for extensions
+    to re-use a single event opcode. GE only provide headers and the most
+    basic functionality, leaving the extensions to interpret the events in
+    their specific context.</para>
+
+    <para>GenericEvents may be longer than 32 bytes. If so, the number of 4
+    byte units following the initial 32 bytes must be specified in the length
+    field of the event.</para>
+  </chapter>
+
+  <chapter>
+    <title>Extension Initialization</title>
+
+    <para>The name of this extension is "Generic Event Extension"</para>
+
+    <programlisting>GEQueryVersion
+    client-major-version: CARD16
+    client-minor-version: CARD16
+==&gt;
+    major-version:        CARD16
+    minor-version:        CARD16</programlisting>
+
+    <para>The client sends the highest supported version to the server and the
+    server sends the highest version it supports, but no higher than the
+    requested version. Major versions changes can introduce incompatibilities
+    in existing functionality, minor version changes introduce only backward
+    compatible changes. It is the clients responsibility to ensure that the
+    server supports a version which is compatible with its
+    expectations.</para>
+
+    <para>As of version 1.0, no other requests are provided by this extension.
+    </para>
+  </chapter>
+
+  <chapter>
+    <title>Events</title>
+
+    <para>GE defines a single event, to be used by all extensions. The event's
+    structure is similar to a reply. This is a core protocol event, ID 35, and
+    is not itself an extension event.</para>
+
+    <programlisting>GenericEvent
+    type:           BYTE       always GenericEvent (35)
+    extension:      CARD8      extension offset
+    sequenceNumber: CARD16     low 16 bits of request seq. number
+    length:         CARD32     length
+    evtype:         CARD16     event type</programlisting>
+
+    <para>The field 'extension' is to be set to the major opcode of the
+    extension. The 'evtype' field is the actual opcode of the event. The
+    length field specifies the number of 4-byte blocks after the initial 32
+    bytes. If length is 0, the event is 32 bytes long.</para>
+  </chapter>
+
+  <chapter>
+    <title>Notes</title>
+
+    <para>Although the wire event is of arbitrary length, the actual size of
+    an XEvent is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an
+    extension converts a wire event to an XEvent &gt; 96 bytes, it will
+    overwrite the space allocated for the event. See struct _XSQEvent in
+    Xlibint.h for details.</para>
+
+    <para>Extensions need to malloc additional data and fill the XEvent
+    structure with pointers to the malloc'd data. The client then needs to
+    free the data, only the XEvent structure will be released by Xlib.</para>
+
+    <para>The server must not send GenericEvents longer than 32 bytes until it
+    has verified that the client is able to interpret these events. If a long
+    event is sent to a client unable to process GenericEvents, future
+    interpretation of replies and events by this client will fail.</para>
+  </chapter>
+</book>