Release xcb-proto 1.10

[free-sw/xcb/proto] / doc / xml-xcb.txt

diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
index feb9984..7311911 100644 (file)
--- a/doc/xml-xcb.txt
+++ b/doc/xml-xcb.txt
@@ -128,7 +128,8 @@ Top-Level Elements
   requests of the same type may be combined into a single request without
   affecting the semantics of the requests.
 
-<event name="identifier" number="integer" [no-sequence-number="true"]>
+<event name="identifier" number="integer"
+       [[no-sequence-number="true"] | [xge="true"]]>
   structure contents
 </event>
 
@@ -142,6 +143,11 @@ Top-Level Elements
   include a sequence number.  This is a special-case for the KeymapNotify
   event in the core protocol, and should not be used in any other event.
 
+  If the optional xge attribute is true, the event is an X Generic Event and
+  will be treated as such.
+
+  The no-sequence-number and xge attribute can not be combined.
+
 <error name="identifier" number="integer">
   structure contents
 </error>
@@ -225,8 +231,22 @@ enum; the value is restricted to one of the constants named in the enum.
   defining the set of values included, and a list containing these values.
   value-mask-type gives the type of the bitmask; this must be CARD16 or
   CARD32.  value-mask-name gives the field name of the bitmask, and
-  value-list-name gives the field name of the list of values.
+  value-list-name gives the field name of the list of values. Please use
+  <switch> instead for new protocol definitions.
+
+<switch name="identifier"> switch expression
+    <bitcase> bitcase expression(s), fields </bitcase> </switch>
+
+  This element represents conditional inclusion of fields. It can be viewed
+  as sequence of multiple ifs: if ( switch expression & bitcase expression )
+  is non-zero, bitcase fields are included in structure.  It can be used only
+  as the last field of a structure.
 
+  When a bitcase includes multiple <enumref> clauses, the contents of the
+  bitcase are only present once regardless of the number of bitcase expressions
+  that match.
+
+  New protocol definitions should prefer to use this instead of <valueparam>.
 
 Expressions
 -----------
@@ -256,3 +276,57 @@ Expressions
 
   The bit element represents a literal bitmask value in an expression.
   The integer must be in the range 0..31, expanding to (1<<n) in C.
+
+<enumref ref="identifier">enum item identifier</enumref>
+
+  This element represents a reference to item of enum.
+
+<unop op="operator">expression</unop>
+
+  This element represents a unary operator, with the op attribute specifying
+  which operator. The only supported operation so far is ~, and its semantic
+  is identical to the corresponding operator in C.
+
+<sumof ref="identifier" />
+
+  This element represents a sumation of the elements of the referenced list.
+
+<popcount>expression</popcount>
+
+  This element represents the number of bits set in the expression.
+
+Documentation
+-------------
+
+  Documentation for each request, reply or event is stored in the appropriate
+  element using a <doc> element. The <doc> element can contain the following
+  elements:
+
+<brief>brief description</brief>
+
+  A short description of the request, reply or event. For example "makes a
+  window visible" for MapWindow. This will end up in the manpage NAME section
+  and in the doxygen @brief description.
+
+<description><![CDATA[longer description]]></description>
+
+  The full description. Use `` to highlight words, such as "Draws
+  `points_len`-1 lines between each pair of points…"
+
+<example><![CDATA[example code]]</description>
+
+  Example C code illustrating the usage of the particular request, reply or
+  event.
+
+<field name="name">field description</field>
+
+  The full description for the specified field. Depending on the context, this
+  is either a request parameter or a reply/event datastructure field.
+
+<error type="type">error description</field>
+
+  The full description for an error which can occur due to this request.
+
+<see type="request" name="name" />
+
+  A reference to another relevant program, function, request or event.