Add description of new protocol elements

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

diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
index f428493..3c6a155 100644 (file)
--- a/doc/xml-xcb.txt
+++ b/doc/xml-xcb.txt
@@ -1,53 +1,25 @@
-                                   XML-XCB
+                                  xcb/proto
 
 Description
 ===========
 
-XML-XCB generates C bindings to the X Window System protocol based on XML
-descriptions of the protocol.  It is designed for use with XCB, the X C
-binding <http://xcb.freedesktop.org>.  XML-XCB consists of:
+xcb/proto is a set of XML files describing the  X Window System protocol
+It is designed for use with libxcb, the X C binding
+<http://xcb.freedesktop.org/>.  xcb/proto consists of:
 
 xcb.xsd      An XML Schema defining the data format for describing the X
-             protocol.  Included in xcb-proto.
+             protocol.
 
-c-client.xsl An XSLT code generator that transforms the protocol descriptions
-             into C bindings.  Included in xcb.
+*.py         Code generator helpers that read the protocol descriptions
+             into python structures. See libxcb for example usage.
 
 *.xml        XML descriptions of the core X protocol and many extensions.
-             Included in xcb-proto.
-
-
-Dependencies
-============
-
-c-client.xsl requires an XSLT processor that supports XSLT 1.0
-<http://www.w3.org/TR/1999/REC-xslt-19991116> and the EXSLT node-set extension
-<http://www.exslt.org/exsl/functions/node-set/index.html>.  The XCB build
-system currently uses xsltproc.  You can get xsltproc through your
-distribution's packaging system, or from <http://xmlsoft.org/XSLT/>.
 
 
 Generating C bindings
 =====================
 
-The C bindings for the core protocol and all the currently supported
-extensions are built as part of the xcb build system.  However, for the
-purposes of creating and debugging new protocol descriptions, it can be useful
-to generate the bindings directly by invoking c-client.xsl to the XML protocol
-description.
-
-You must provide several parameters to c-client.xsl:
-
-mode: header or source; specifies which part of the C bindings to generate.
-base-path: path to the core X protocol descriptions.
-extension-path: path to the extension descriptions.
-
-For example, using xsltproc, you can generate the header for a protocol
-description "protocol.xml" with the command:
-
-xsltproc --stringparam base-path /path/to/xcb-proto/src \
-         --stringparam extension-path /path/to/xcb-proto/src/extensions \
-         --stringparam mode header /path/to/xcb/src/c-client.xsl protocol.xml
+See libxcb <http://cgit.freedesktop.org/xcb/libxcb/>.
 
 
 Protocol Description Format
@@ -206,6 +178,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
+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.
+
 <pad bytes="integer" />
 
   This element declares some padding in a data structure.  The bytes
@@ -247,8 +225,17 @@ than type="PIXMAP".
   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, 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 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>.
 
 Expressions
 -----------
@@ -278,3 +265,22 @@ 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.
+