Bug 251 - Xkb{Get,Set}NamedIndicator spec & implementation don't match
Xkb{Get,Set}NamedIndicator spec & implementation don't match
Status: ASSIGNED
Product: XStandards
Classification: Unclassified
Component: XKB
X11R6.6
All All
: medium normal
Assigned To: Daniel Stone
Xorg Project Team
:
Depends on:
Blocks: xorg-xkb
  Show dependency treegraph
 
Reported: 2004-03-01 16:16 UTC by Alan Coopersmith
Modified: 2007-07-26 16:01 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Alan Coopersmith 2004-03-01 16:16:15 UTC
The XKB Library Spec (Library Version 1.0 / Document Revision 1.1)
in xc/docs/spec/XKB/XKBlib gives the following function definitions:

Bool XkbGetNamedIndicator(dpy, dev_spec, name, ndx_rtrn, state_rtrn,
	map_rtrn, real_rtrn) [Section 8.3.3]
Bool XkbSetNamedIndicator(dpy, device_spec, name, change_state, state,
	create_new, map) [Section 8.4.3]

However, in the X.org libX11 implementation, neither function takes a
device_spec argument - instead, variants named XkbGetNamedDeviceIndicator
and XkbSetNamedDeviceIndicator are provided that add arguments device,
class, and id to the above functions.

Additionally, section 8.4.3 states:
    If change_state is True, and the optional parameter, state, is not
    NULL, XkbSetNamedIndicator tells the server to change the state of
    the named indicator to the value specified by state.

However, state is a Bool, so can only be True or False, not NULL, so the
phrase \""and the optional parameter, state, is not NULL\"" should be removed
from the description.
Comment 1 Daniel Stone 2006-03-05 08:06:11 UTC
we really need to fix the documentation; i'll be needing to do some big updates
as well.  alan, do you know if we ever managed to get the framemaker stuff
converted to something sensible?
Comment 2 Daniel Stone 2006-03-05 08:06:32 UTC
my kingdon for a fix for #874
Comment 3 Alan Coopersmith 2006-03-05 17:58:17 UTC
http://people.freedesktop.org/~alanc/xkb/ has the conversions to MIF, HTML & XML
(not sure what DTD) I did a few months ago when this last came up.
Unfortunately, while I have access to a licensed version of Framemaker, I don't
know how to use it, so this was the best I could figure out quickly on my own.
If there's something better I can do, and you can point me to instructions for
how to do it, let me know.   (At least the HTML version seems to have questionable
formatting.)
Comment 4 Daniel Stone 2006-03-05 20:25:06 UTC
thanks.  i'll see what I can do with the XML.
Comment 5 Alan Coopersmith 2007-07-26 16:00:49 UTC
The XkbSetNamedIndicator & XkbGetNamedIndicator man pages recently committed to
libX11 also share this problem, since they were based on the library spec.

The bug in the Sun bug database for those notes:

The man page for XkbSetNamedIndicator lists a device_spec argument that
XkbSetNamedIndicator does not take, and does not document the XkbSetNamedDeviceIndicator variant that does take the device_spec.

The man page should be updated to correctly cover both forms of this function:

XkbSetNamedIndicator(dpy,name,changeState,state,createNewMap,pMap)
    Display *           dpy;
    Atom                name;
    Bool                changeState;
    Bool                state;
    Bool                createNewMap;
    XkbIndicatorMapPtr  pMap;

XkbSetNamedDeviceIndicator(dpy,device,class,id,name,changeState,
                                                        state,createNewMap,pMap)
    Display *           dpy;
    unsigned            device;
    unsigned            class;
    unsigned            id;
    Atom                name;
    Bool                changeState;
    Bool                state;
    Bool                createNewMap;
    XkbIndicatorMapPtr  pMap;


It should note that calling
	XkbSetNamedIndicator(dpy,name,changeState,state,createNewMap,pMap)
is equivalent to calling 
	XkbSetNamedDeviceIndicator(dpy,XkbUseCoreKbd,
                                   XkbDfltXIClass,XkbDfltXIId,
                                   name,changeState,state,
                                   createNewMap,pMap);

Additionally, in the description section, the phrase "and the optional parameter,  state, is not NULL" should be removed from the second paragraph.
The state parameter is not optional and since it's not a pointer, can't be NULL.

The XkbGetNamedIndicator man page has a similar problem - the correct function
definitions for it are:

XkbGetNamedIndicator(   Display *               dpy,
                        Atom                    name,
                        int     *               pNdxRtrn,
                        Bool *                  pStateRtrn,
                        XkbIndicatorMapPtr      pMapRtrn,
                        Bool *                  pRealRtrn)


XkbGetNamedDeviceIndicator(     Display *               dpy,
                                unsigned                device,
                                unsigned                class,
                                unsigned                id,
                                Atom                    name,
                                int     *               pNdxRtrn,
                                Bool *                  pStateRtrn,
                                XkbIndicatorMapPtr      pMapRtrn,
                                Bool *                  pRealRtrn)

XkbGetNamedIndicator(dpy,name,pNdxRtrn,pStateRtrn,pMapRtrn,pRealRtrn)
	is equivalent to
XkbGetNamedDeviceIndicator(dpy,XkbUseCoreKbd, XkbDfltXIClass,XkbDfltXIId,
                           name,pNdxRtrn,pStateRtrn,pMapRtrn,pRealRtrn)

<http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=4528016>