[PATCH wayland 3/3] doc: document new enum attributes and use such data in generated docs

[Auke Booij]

The newly introduced "enum" and "bitfield" protocol XML attributes give
additional semantic information, which we can use when generating the
documentation.
---
 doc/publican/protocol-to-docbook.xsl |  9 +++++++++
 doc/publican/sources/Protocol.xml    | 23 +++++++++++++++++------
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/doc/publican/protocol-to-docbook.xsl b/doc/publican/protocol-to-docbook.xsl
index 7b45969..fad207a 100644
--- a/doc/publican/protocol-to-docbook.xsl
+++ b/doc/publican/protocol-to-docbook.xsl
@@ -102,6 +102,12 @@
     <term><xsl:value-of select="@name"/></term>
     <listitem>
         <simpara>
+          <xsl:if test="@enum">
+            <link linkend="protocol-spec-{../../@name}-enum-{@enum}">
+              <xsl:value-of select="@enum"/>
+            </link>
+	    <xsl:text> </xsl:text>
+          </xsl:if>
           <xsl:value-of select="@type"/>
           <xsl:if test="@summary" >
             - <xsl:value-of select="@summary"/>
@@ -171,6 +177,9 @@
   <section id="protocol-spec-{../@name}-{name()}-{@name}">
     <title>
       <xsl:value-of select="../@name"/>::<xsl:value-of select="@name" />
+      <xsl:if test="@bitfield">
+        - bitfield
+      </xsl:if>
       <xsl:if test="description/@summary">
         - <xsl:value-of select="description/@summary" />
       </xsl:if>
diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index 477063b..facdcdc 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -15,6 +15,20 @@
       identifies which method in the interface to invoke.
     </para>
     <para>
+      The protocol is message-based.  A message sent by a client to the server
+      is called request.  A message from the server to a client is called event.
+      A message has a number of arguments, each of which has a certain type (see
+      <xref linkend="sect-Protocol-Wire-Format"/> for a list of argument types).
+      Additionally, the protocol can specify <type>enum</type>s.  These are used
+      to list options for <type>int</type> and <type>uint</type> type arguments.
+      For documentation purposes, arguments can refer to the specific
+      enumeration that is semantically implied.  Only in the case that the
+      argument is of type <type>uint</type>, it can specify that the values that
+      are passed around are to be thought of as <emphasis>bitfields</emphasis>,
+      for example when arbitrarily many choices of the enum can be ORed
+      together.
+    </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
@@ -62,14 +76,11 @@
       The protocol is sent over a UNIX domain stream socket, where the endpoint
       usually is named <systemitem class="service">wayland-0</systemitem>
       (although it can be changed via <emphasis>WAYLAND_DISPLAY</emphasis>
-      in the environment).  The protocol is message-based.  A
-      message sent by a client to the server is called request.  A message
-      from the server to a client is called event.  Every message is
-      structured as 32-bit words, values are represented in the host's
-      byte-order.
+      in the environment).
     </para>
     <para>
-      The message header has 2 words in it:
+      Every message is structured as 32-bit words, values are represented in the
+      host's byte-order.  The message header has 2 words in it:
       <itemizedlist>
 	<listitem>
 	  <para>
--
2.4.4