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

[Alan Coopersmith]

I thought XKeycodeToKeysym was still the correct function to use in the rare
case you found yourself running without XKB - it certainly doesn't seem like
we should recommend people reinvent it with XGetKeyboardMapping on their own,
especially not by doing a round trip to grab the table each time, lookup one
keysym and then discarding it.

	-alan-

On 06/30/13 06:15 AM, Christophe wrote:
> 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__)
>


-- 
	-Alan Coopersmith-              alan.coopersmith at oracle.com
	 Oracle Solaris Engineering - http://blogs.oracle.com/alanc