libX11 git update 14 sep 2011

1 files changed, 216 insertions, 0 deletions

diff --git a/libX11/specs/XKB/ch22.xml b/libX11/specs/XKB/ch22.xml
new file mode 100644
index 000000000..ba16bffbc
--- /dev/null
+++ b/libX11/specs/XKB/ch22.xml
@@ -0,0 +1,216 @@
+<chapter id='debugging_aids'>
+<title>Debugging Aids</title>
+
+<para>
+The debugging aids are intended for use primarily by Xkb implementors and are
+optional in any implementation.
+</para>
+
+
+<para>
+There are two bitmasks that may be used to control debugging. One bitmask
+controls the output of debugging information, and the other controls behavior.
+Both bitmasks are initially all zeros.
+</para>
+
+
+<para>
+To change the values of any of the debug controls, use <emphasis>
+XkbSetDebuggingFlags</emphasis>
+.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbSetDebuggingFlags</emphasis>
+(<emphasis>
+display, mask, flags, msg, ctrls_mask, ctrls, ret_flags, ret_ctrls</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display * <emphasis>
+            display</emphasis>
+;            /* connection to X server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int <emphasis>
+            mask</emphasis>
+;            /* mask selecting debug output flags to change */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int <emphasis>
+            flags</emphasis>
+;            /* values for debug output flags selected by <emphasis>
+mask</emphasis>
+ */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+char * <emphasis>
+            msg</emphasis>
+;            /* message to print right now */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int            <emphasis>
+ctrls_mask</emphasis>
+;            /* mask selecting debug controls to change */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int            <emphasis>
+ctrls</emphasis>
+;            /* values for debug controls selected by <emphasis>
+ctrls_mask</emphasis>
+ */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int * <emphasis>
+            ret_flags</emphasis>
+;            /* resulting state of all debug output flags */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int *            <emphasis>
+ret_ctrls</emphasis>
+;            /* resulting state of all debug controls */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbSetDebuggingFlags</emphasis>
+ modifies the debug output flags as specified by <emphasis>
+mask</emphasis>
+ and <emphasis>
+flags</emphasis>
+, modifies the debug controls flags as specified by <emphasis>
+ctrls_mask</emphasis>
+ and <emphasis>
+ctrls</emphasis>
+, prints the message <emphasis>
+msg</emphasis>
+, and backfills <emphasis>
+ret_flags</emphasis>
+ and <emphasis>
+ret_ctrls</emphasis>
+ with the resulting debug output and debug controls flags.
+</para>
+
+
+<para>
+When bits are set in the debug output masks, <emphasis>
+mask</emphasis>
+ and <emphasis>
+flags</emphasis>
+, Xkb prints debug information corresponding to each bit at appropriate points
+during its processing. The device to which the output is written is
+implementation-dependent, but is normally the same device to which X server
+error messages are directed; thus the bits that can be set in <emphasis>
+mask</emphasis>
+ and <emphasis>
+flags</emphasis>
+ is implementation-specific. To turn on a debug output selection, set the bit
+for the output in the <emphasis>
+mask</emphasis>
+ parameter and set the corresponding bit in the <emphasis>
+flags</emphasis>
+ parameter. To turn off event selection for an event, set the bit for the
+output in the <emphasis>
+mask</emphasis>
+ parameter and do not set the corresponding bit in the <emphasis>
+flags</emphasis>
+ parameter.
+</para>
+
+
+<para>
+When bits are set in the debug controls masks, <emphasis>
+ctrls_mask</emphasis>
+ and <emphasis>
+ctrls</emphasis>
+, Xkb modifies its behavior according to each controls bit. <emphasis>
+ctrls_mask</emphasis>
+ and <emphasis>
+ctrls</emphasis>
+ are related in the same way that <emphasis>
+mask</emphasis>
+ and <emphasis>
+flags</emphasis>
+ are. The valid controls bits are defined in Table 22.1.
+</para>
+
+<table frame='none'>
+<title>Debug Control Masks</title>
+<tgroup cols='3'>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<thead>
+<row rowsep='0'>
+  <entry>Debug Control Mask</entry>
+  <entry>Value</entry>
+  <entry>Meaning</entry>
+</row>
+</thead>
+<tbody>
+<row rowsep='0'>
+    <entry>XkbDF_DisableLocks</entry>
+    <entry>(1 &lt;&lt; 0)</entry>
+    <entry>Disable actions that lock modifiers</entry>
+  </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+<emphasis>
+XkbSetDebuggingFlags</emphasis>
+ returns <emphasis>
+True</emphasis>
+ if successful and <emphasis>
+False</emphasis>
+ otherwise. The only protocol error it may generate is <emphasis>
+BadAlloc</emphasis>
+, if for some reason it is unable to allocate storage.
+</para>
+
+
+<para>
+<emphasis>
+XkbSetDebuggingFlags</emphasis>
+ is intended for developer use and may be disabled in production X servers. If
+it is disabled, <emphasis>
+XkbSetDebuggingFlags</emphasis>
+ has no effect and does not generate any protocol errors.
+</para>
+
+
+<para>
+The message in <emphasis>
+msg</emphasis>
+ is written immediately. The device to which it is written is implementation
+dependent but is normally the same device where X server error messages are
+directed.
+</para>
+</chapter>