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
_______________________________________________
wayland-devel mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
