Remove xcl and CVSROOT.

1 files changed, 275 insertions, 0 deletions

diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
new file mode 100644
index 0000000..fecee31
--- /dev/null
+++ b/doc/xml-xcb.txt
@@ -0,0 +1,275 @@
+                                   XML-XCB
+
+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.xsd      An XML Schema defining the data format for describing the X
+             protocol.  Included in xcb-proto.
+
+c-client.xsl An XSLT code generator that transforms the protocol descriptions
+             into C bindings.  Included in xcb.
+
+*.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
+
+
+Protocol Description Format
+===========================
+
+Root element
+------------
+
+<xcb header="string" extension-name="string" extension-xname="string">
+  top-level elements
+</xcb>
+
+  This is the root element of a protocol description.  The attributes are all
+  various forms of the extension name.  header is the basename of the XML
+  protocol description file, which will be used as the basename for generated
+  bindings as well.  extension-name is the name of the extension in InterCaps,
+  which will be used in the names of functions.  extension-xname is the name
+  of the extension as passed to QueryExtension.
+
+  As an example, the XML-XCB description for the GO-FASTER extension would use
+  the root element <xcb header="gofaster" extension-name="GoFaster"
+  extension-xname="GO-FASTER">; as a result, C bindings will be put in
+  gofaster.h and gofaster.c, extension functions will be named
+  XCBGoFasterFunctionName, and the extension initialization will call
+  QueryExtension with the name "GO-FASTER".
+
+  This element can contain any number of the elements listed in the section
+  "Top-Level Elements" below.
+
+
+Top-Level Elements
+------------------
+
+<import>header_name</import>
+
+  The import element allows the protocol description to reference types
+  declared in another extension.  The content is be the basename of the
+  extension XML file, which is also the header attribute of the extension's
+  root node.  Note that types from xcb_types and xproto are automatically
+  available, without explicitly importing them.
+
+<struct name="identifier">structure contents</struct>
+
+  This element represents a data structure.  The name attribute gives the name
+  of the structure.  The content represents the fields of the structure, and
+  consists of one or more of the field, pad, and list elements described in
+  the section "Structure Contents" below.
+
+<union name="identifier">structure contents</union>
+
+  This element represents a union of data types, which can hold one value of
+  any of those types.  The name attribute gives the name of the union.  The
+  content represents the fields of the union, and consists of one or more of
+  the field and pad elements described in the section "Structure Contents
+  below".
+
+<xidtype name="identifier" />
+
+  This element represents an identifier for a particular type of resource.
+  The name attribute gives the name of the new type.
+
+<enum name="identifier">
+  <item name="identifier">[optional expression]</item>
+  ...
+</enum>
+
+  The enum element represents an enumeration type, which can take on any of
+  the values given by the contained item elements.  The name attribute on the
+  enum gives the name of the enumerated type.
+
+  The item element represents one possible value of an enumerated type.  The
+  name attribute on the item gives the name of that value, and the optional
+  content is an expression giving the numeric value.  If the expression is
+  omitted, the value will be one more than that of the previous item, or 0 for
+  the first item.
+
+<typedef oldname="identifier" newname="identifier" />
+
+  The typedef element declares the type given by the newname attribute to be
+  an alias for the type given by the oldname attribute.
+
+<request name="identifier" opcode="integer" [combine-adjacent="true"]>
+  structure contents
+  [<reply>structure contents</reply>]
+</request>
+
+  The request element represents an X protocol request.  The name attribute
+  gives the name of the request, and the opcode attribute gives the numeric
+  request code.  The content of the request element represents the fields in
+  the request, and consists of one or more of any of the elements listed in
+  the "Structure Contents" section below.  Note that for requests in the core
+  protocol, the first field in the request goes into the one-byte gap between
+  the major opcode and the length; if the request does not have any data in
+  that gap, put a one byte pad as the first element.  Extension requests
+  always have this gap filled with the minor opcode.
+
+  The optional reply element is present if the request has a reply.  The
+  content of the reply element represents the fields in the reply, and
+  consists of zero or more of the field, pad, and list elements listed in the
+  "Structure Contents" section below.  Note that the first field in the reply
+  always goes into the one-byte gap between the response type and the sequence
+  number; if the reply does not have any data in that gap, put a one byte pad
+  as the first element.
+
+  If the optional combine-adjacent attribute is true, multiple adjacent
+  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"]>
+  structure contents
+</event>
+
+  This element represents an X protocol event.  The name attribute gives the
+  name of the event, and the number attribute gives the event number.  The
+  content of the event element represents the fields in the event, and
+  consists of zero or more of the field, pad, and list elements listed in the
+  "Structure Contents" section below.
+
+  If the optional no-sequence-number attribute is true, the event does not
+  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.
+
+<error name="identifier" number="integer">
+  structure contents
+</error>
+
+  This element represents an X protocol error.  The name attribute gives the
+  name of the error, and the number attribute gives the error number.  The
+  content of the error element represents the fields in the error, and
+  consists of zero or more of the field, pad, and list elements listed in the
+  "Structure Contents" section below.
+
+<eventcopy name="identifier" number="identifier" ref="identifier" />
+
+  This element creates an alias for the event named in the ref attribute, with
+  the new name given in the name attribute, and the new event number given in
+  the number attribute.
+
+<eventcopy name="identifier" number="identifier" ref="identifier" />
+
+  This element creates an alias for the error named in the ref attribute, with
+  the new name given in the name attribute, and the new error number given in
+  the number attribute.
+
+
+Structure Contents
+------------------
+
+Note: "type" attributes below refer to types defined by previous elements,
+either in the current extension, xproto, xcb_types, or one of the imported
+extensions.  The type name must refer to only one possible type; if more than
+one type matches, an error occurs.  To avoid this, the type may be explicitly
+prefixed with a namespace, which should be the value of the header attribute
+on the protocol description containing the desired type.  The namespace and
+type are separated by a single colon.  For example, to refer to the PIXMAP
+type defined in glx rather than the one defined in xcb_types, use
+type="glx:PIXMAP" rather than type="PIXMAP".
+
+<pad bytes="integer" />
+
+  This element declares some padding in a data structure.  The bytes
+  attribute declares the number of bytes of padding.
+
+<field type="identifier" name="identifier" />
+
+  This element represents a field in a data structure.  The type attribute
+  declares the data type of the field, and the name attribute gives the name
+  of the field.
+
+<list type="identifier" name="identifier">expression</list>
+
+  This element represents an array or list of fields in a data structure.  The
+  type attribute declares the data type of the field, and the name attribute
+  gives the name of the field.  The content is an expression giving the length
+  of the list in terms of other fields in the structure.  See the section
+  "Expressions" for details on the expression representation.
+
+<localfield type="identifier" name="identifier" />
+
+  This element represents a parameter in a request that is not sent over the
+  wire.  The field can be referenced in the length expressions of lists or in
+  an exprfield.  The type attribute declares the data type of the field, and
+  the name attribute gives the name of the field.
+
+<exprfield type="identifier" name="identifier">expression</exprfield>
+
+  This element represents a field in a request that is calculated rather than
+  supplied by the caller.  The type attribute declares the data type of the
+  field, and the name attribute gives the name of the field.  The content is
+  the expression giving the value of the field.  See the section "Expressions"
+  for details on the expression representation.
+
+<valueparam value-mask-type="identifier" value-mask-name="identifier"
+            value-list-name="identifier" />
+
+  This element represents a BITMASK/LISTofVALUE parameter pair: a bitmask
+  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.
+
+
+Expressions
+-----------
+
+  Expressions consist of a tree of <op> elements with leaves consisting of
+  <fieldref> or <value> elements.
+
+<op op="operator">expression expression</op>
+
+  The op element represents an operator, with the op attribute specifying
+  which operator.  The supported operations are *, /, &amp;, and &lt;&lt;, and
+  their semantics are identical to the corresponding operators in C.  The two
+  operand expressions may be fieldref, value, or op elements.
+
+<fieldref>identifier</fieldref>
+
+  The fieldref element represents a reference to the value of another field in
+  the structure containing this expression.  The identifier is the value of
+  the "name" attribute on the referenced field.
+
+<value>integer</value>
+
+  The value element represents a literal integer value in an expression.  The
+  integer may be expressed in decimal or hexadecimal.