[PATCH libX11] man: improved documentation for XKeycoteToKeysym being deprecated

[Christophe]

From: Christophe CURIS <christophe.curis at free.fr>

The original update provided very few information to developper;
this patches describes a bit more how to properly fix the warning,
including an example to help devs fixing the issue properly.

Signed-off-by: Christophe CURIS <christophe.curis at free.fr>
---
 man/XStringToKeysym.man |   51 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/man/XStringToKeysym.man b/man/XStringToKeysym.man
index 3a7fb7b..19f2b1f 100644
--- a/man/XStringToKeysym.man
+++ b/man/XStringToKeysym.man
@@ -142,9 +142,9 @@ If no symbol is defined,
 returns
 .ZN NoSymbol .
 .ZN XKeycodeToKeysym
-predates the XKB extension. If you want to lookup a KeySym while
-using XKB you have to use
-.ZN XkbKeycodeToKeysym .
+is deprecated, please see
+.B NOTES
+below.
 .LP
 If the specified KeySym is not defined for any KeyCode,
 .ZN XKeysymToKeycode
@@ -158,6 +158,51 @@ otherwise, the specified KeySym is returned to both lower_return and
 upper_return.
 Support for conversion of other than Latin and Cyrillic KeySyms is
 implementation-dependent.
+.SH NOTES
+The function
+.ZN XKeysymToKeycode
+does not provide the necessary capability to handle modern multi-language
+environments. It have been marked as deprecated to help removing its use.
+.LP
+If the
+.B Xkb
+extension is present (see
+.ZN XkbQueryExtension ),
+the proper function to use is
+.ZN XkbKeycodeToKeysym .
+If the extension is not present, you may use the function
+.ZN XLookupKeysym
+to retreive the KeySym, or if not applicable you may use
+.ZN XGetKeyboardMapping
+instead. An example of proper usage could be:
+
+.Ds 0
+/* This code should be executed only once after connecting to the display */
+Bool have_xkb;
+have_xkb = XkbQueryExtension(display, NULL, NULL, NULL, NULL, NULL);
+
+/* This code effectively converts a Keycode to KeySym */
+KeySym keysym;
+if (have_xkb) {
+    keysym = XkbKeycodeToKeysym(display, keycode, group, level);
+} else {
+    KeySym *key_table;
+    int keysym_per_keycode;
+
+    key_table = XGetKeyboardMapping(display, keycode, 1, &keysym_per_keycode);
+    if (key_table) {
+        keysym = key_table[level];
+        XFree(key_table);
+    } else {
+        keysym = NoSymbol;
+    }
+}
+.De
+
+.SH HISTORY
+The function
+.ZN XKeysymToKeycode
+have been marked deprecated from X11R7.7 released on 6 June 2012.
 .SH "SEE ALSO"
 XkbKeycodeToKeysym(__libmansuffix__),
 XLookupKeysym(__libmansuffix__)
-- 
1.7.10.4