X-Git-Url: http://git.demorecorder.com/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fxml-xcb.txt;h=d47b12c9f7ac6dd4078d7da0bf7879cbfda55432;hb=1dabbc999755762dbb910132cbea1bef2ea34bc8;hp=3c6a155194188c6e8e88f1fd70c9000673f8852d;hpb=9d03507afa4354ce402333f94d01f6bcb2cf41e6;p=free-sw%2Fxcb%2Fproto

diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
index 3c6a155..d47b12c 100644
--- 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>
@@ -178,11 +184,12 @@ separated by a single colon.  For example, to refer to the PIXMAP type defined
 in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
 than type="PIXMAP".
 
-Note: Most of the below may optionally contain an enum, altenum, or mask
+Note: Most of the below may optionally contain an enum, altenum, mask or altmask
 attribute, which follows the above rules for "type". "enum" is an exhaustive
 enum; the value is restricted to one of the constants named in the enum.
 "altenum" may be one of the values contained in the enum, but it need not be.
-"mask" refers to an enum to be used as a bitmask.
+"mask" refers to an exhaustive enum to be used as a bitmask.
+"altmask" may be a mask from the referred enum, but it need not be.
 
 <pad bytes="integer" />
 
@@ -195,6 +202,14 @@ enum; the value is restricted to one of the constants named in the enum.
   declares the data type of the field, and the name attribute gives the name
   of the field.
 
+<fd name="identifier" />
+
+  This element represents a file descriptor field passed with the request.  The
+  name attribute gives the name of the field.
+
+  While ordinary fields are encoded as part of the request, file descriptor
+  fields are generally passed via an out-of-band mechanism.
+
 <list type="identifier" name="identifier">expression</list>
 
   This element represents an array or list of fields in a data structure.  The
@@ -229,13 +244,40 @@ enum; the value is restricted to one of the constants named in the enum.
   <switch> instead for new protocol definitions.
 
 <switch name="identifier"> switch expression
-    <bitcase> bitcase expression, fields </bitcase> </switch>
+    <bitcase> bitcase expression(s), fields </bitcase>
+    <case> case expression(s), fields </case>
+</switch>
 
   This element represents conditional inclusion of fields. It can be viewed
-  as sequence of multiple ifs: if ( switch expression & bitcase expression )
-  is equal to bitcase expression, bitcase fields are included in structure.
-  It can be used only as the last field of structure. New protocol definitions
-  should prefer to use this instead of <valueparam>.
+  as sequence of multiple ifs:
+
+  <bitcase>:
+    if ( switch expression & bitcase expression ) is non-zero,
+    bitcase fields are included in structure.
+
+  <case>:
+    if ( switch expression == case expression ) is true,
+    then case fields are included in structure.
+
+  It can be used only as the last field of a structure.
+
+  When a bitcase or case includes multiple <enumref> clauses, the contents
+  of the bitcase or case are only present once regardless of the number of
+  bitcase or case expressions that match.
+
+  <enumref> inside <bitcase> can only refer to an enum's <bit> members.
+  <enumref> inside <case> can only refer to an enum's <value> members.
+
+  A switch may contain multiple <bitcase> or <case> elements.
+  Usually it will only contain <bitcase> elements
+  or only contain <case> elements.
+  That is, mixing of <case> and <bitcase> usually doesn't make any sense.
+
+  The same value may appear in multiple <case> or <bitcase> elements.
+
+  New protocol definitions should prefer to use this instead of <valueparam>
+  and instead of <union>.
+
 
 Expressions
 -----------
@@ -280,7 +322,53 @@ Expressions
 
   This element represents a sumation of the elements of the referenced list.
 
+<sumof ref="identifier" >expression</sumof>
+
+  The expression is evaluated for each element of the referenced list,
+  in the context of this element.
+  This sumof element then represents a sumation of the results of these
+  evaluations.
+
+  expression will usually be a fieldref which references a field of
+  a list-element or an expression containing a fieldref,
+  such as popcount of a fieldref.
+
 <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.