Make Xkb{Get,Set}NamedIndicator spec & manpages match code

The XKB Library spec and the man pages for XkbGetNamedIndicator &
XkbSetNamedIndicator included a device_spec argument neither function
takes, and do not include the XkbGetNamedDeviceIndicator &
XkbSetNamedDeviceIndicator variants that do take it (along with two
other arguments).

This updates them to match the interfaces the code has provided for
decades.

This has been reported multiple times, so this fixes:
https://bugs.freedesktop.org/show_bug.cgi?id=251
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=729812
Sun Bug 4528016 XkbSetNamedIndicator & XkbGetNamedIndicator man pages are wrong
  (filed: alan.coopersmith@sun.com 2001-11-15 - now aka Oracle bug 15087506)
X.Org Group Defect Id #9418

Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
Reviewed-by: Adam Jackson <ajax@redhat.com>

5 files changed, 118 insertions, 25 deletions

diff --git a/man/xkb/Makefile.am b/man/xkb/Makefile.am
index 484a85a9..7632faa3 100644
--- a/man/xkb/Makefile.am
+++ b/man/xkb/Makefile.am
@@ -111,6 +111,7 @@ libman_PRE = \
 	XkbGetKeyboardByName.man                \
 	XkbGetMap.man                           \
 	XkbGetNameChanges.man                   \
+	XkbGetNamedDeviceIndicator.man          \
 	XkbGetNamedGeometry.man                 \
 	XkbGetNamedIndicator.man                \
 	XkbGetNames.man                         \
@@ -191,6 +192,7 @@ libman_PRE = \
 	XkbSetIndicatorMap.man                  \
 	XkbSetMap.man                           \
 	XkbSetModActionVMods.man                \
+	XkbSetNamedDeviceIndicator.man          \
 	XkbSetNamedIndicator.man                \
 	XkbSetNames.man                         \
 	XkbSetPtrActionX.man                    \
diff --git a/man/xkb/XkbGetNamedDeviceIndicator.man b/man/xkb/XkbGetNamedDeviceIndicator.man
new file mode 100644
index 00000000..ebe427e1
--- /dev/null
+++ b/man/xkb/XkbGetNamedDeviceIndicator.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/XkbGetNamedIndicator.__libmansuffix__
diff --git a/man/xkb/XkbGetNamedIndicator.man b/man/xkb/XkbGetNamedIndicator.man
index 803d656a..be65056b 100644
--- a/man/xkb/XkbGetNamedIndicator.man
+++ b/man/xkb/XkbGetNamedIndicator.man
@@ -1,4 +1,4 @@
-.\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
+.\" Copyright 1999, 2017, Oracle and/or its affiliates. All rights reserved.
 .\"
 .\" Permission is hereby granted, free of charge, to any person obtaining a
 .\" copy of this software and associated documentation files (the "Software"),
@@ -25,9 +25,19 @@ XkbGetNamedIndicator \- Look up the indicator map and other information for an
 indicator by name
 .SH SYNOPSIS
 .HP
-.B Bool XkbGetNamedIndicator
+.B Bool XkbGetNamedDeviceIndicator
 .BI "(\^Display *" "dpy" "\^,"
 .BI "unsigned int " "dev_spec" "\^,"
+.BI "unsigned int " "led_class" "\^,"
+.BI "unsigned int " "led_id" "\^,"
+.BI "Atom " "name" "\^,"
+.BI "int *" "ndx_rtrn" "\^,"
+.BI "Bool *" "state_rtrn" "\^,"
+.BI "XkbIndicatorMapPtr " "map_rtrn" "\^,"
+.BI "Bool *" "real_rtrn" "\^);"
+.HP
+.B Bool XkbGetNamedIndicator
+.BI "(\^Display *" "dpy" "\^,"
 .BI "Atom " "name" "\^,"
 .BI "int *" "ndx_rtrn" "\^,"
 .BI "Bool *" "state_rtrn" "\^,"
@@ -43,6 +53,12 @@ connection to the X server
 .I \- dev_spec
 keyboard device ID, or XkbUseCoreKbd
 .TP
+.I \- led_class
+feedback class, or XkbDfltXIClass
+.TP
+.I \- led_id
+feedback ID, or XkbDfltXIId
+.TP
 .I \- name
 name of the indicator to be retrieved
 .TP
@@ -65,16 +81,16 @@ to get the indicator names. Using names eliminates the need for hard-coding
 bitmask values for particular keyboards. For example, instead of using 
 vendor-specific constants such as WSKBLed_ScrollLock mask on Digital 
 workstations or XLED_SCROLL_LOCK on Sun workstations, you can instead use
-.I XkbGetNamedIndicator 
+.I XkbGetNamedDeviceIndicator
 to look up information on the indicator named "Scroll Lock." 
 
 If the device specified by 
 .I device_spec 
 has an indicator named 
-.I name, XkbGetNamedIndicator 
+.IR name ", " XkbGetNamedDeviceIndicator
 returns True and populates the rest of the parameters with information about the 
 indicator. Otherwise, 
-.I XkbGetNamedIndicator 
+.I XkbGetNamedDeviceIndicator
 returns False.
 
 The 
@@ -95,22 +111,42 @@ Each of the "
 " arguments is optional; you can pass NULL for any unneeded "
 .I _rtrn
 " arguments.
+
+.LP
+.I XkbGetNamedIndicator
+is a convenience function that calls
+.I XkbGetNamedDeviceIndicator
+with a
+.I device_spec
+of
+.BR XkbUseCoreKbd ,
+a
+.I led_class
+of
+.BR XkbDfltXIClass ,
+and a
+.I led_id
+of
+.BR XkbDfltXIId .
+It returns the return value from
+.IR XkbGetNamedDeviceIndicator .
+
 .SH "RETURN VALUES"
 .TP 15
 True
 The 
-.I XkbGetNamedIndicator 
-function returns True if the device specified by 
+.IR XkbGetNamedIndicator " and " XkbGetNamedDeviceIndicator
+functions return True if the device specified by
 .I device_spec 
 has an indicator named 
-.I name.
+.IR name .
 .TP 15
 False
 The 
-.I XkbGetNamedIndicator 
-function returns False if the device specified by 
+.IR XkbGetNamedIndicator " and " XkbGetNamedDeviceIndicator
+functions return False if the device specified by
 .I device_spec 
 does not have an indicator named 
-.I name.
+.IR name .
 .SH "SEE ALSO"
 .BR XkbGetNames (__libmansuffix__)
diff --git a/man/xkb/XkbSetNamedDeviceIndicator.man b/man/xkb/XkbSetNamedDeviceIndicator.man
new file mode 100644
index 00000000..65b5e9d8
--- /dev/null
+++ b/man/xkb/XkbSetNamedDeviceIndicator.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/XkbSetNamedIndicator.__libmansuffix__
diff --git a/man/xkb/XkbSetNamedIndicator.man b/man/xkb/XkbSetNamedIndicator.man
index 5cd558d5..52716b0f 100644
--- a/man/xkb/XkbSetNamedIndicator.man
+++ b/man/xkb/XkbSetNamedIndicator.man
@@ -1,4 +1,4 @@
-.\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
+.\" Copyright 1999, 2017, Oracle and/or its affiliates. All rights reserved.
 .\"
 .\" Permission is hereby granted, free of charge, to any person obtaining a
 .\" copy of this software and associated documentation files (the "Software"),
@@ -26,9 +26,19 @@ the state of the indicator; sets the indicator to a specified state and sets the
 indicator map for the indicator
 .SH SYNOPSIS
 .HP
-.B Bool XkbSetNamedIndicator
+.HP
+.B Bool XkbSetNamedDeviceIndicator
 .BI "(\^Display *" "dpy" "\^,"
 .BI "unsigned int " "device_spec" "\^,"
+.BI "unsigned int " "led_class" "\^,"
+.BI "unsigned int " "led_id" "\^,"
+.BI "Atom " "name" "\^,"
+.BI "Bool " "change_state" "\^,"
+.BI "Bool " "state" "\^,"
+.BI "Bool " "create_new" "\^,"
+.BI "XkbIndicatorMapPtr " "map" "\^);"
+.B Bool XkbSetNamedIndicator
+.BI "(\^Display *" "dpy" "\^,"
 .BI "Atom " "name" "\^,"
 .BI "Bool " "change_state" "\^,"
 .BI "Bool " "state" "\^,"
@@ -44,6 +54,12 @@ connection to the X server
 .I \- device_spec
 device ID, or XkbUseCoreKbd
 .TP
+.I \- led_class
+feedback class, or XkbDfltXIClass
+.TP
+.I \- led_id
+feedback ID, or XkbDfltXIId
+.TP
 .I \- name
 name of the indicator to change
 .TP
@@ -61,7 +77,7 @@ new map for the indicator
 .SH DESCRIPTION
 .LP
 If a compatible version of the Xkb extension is not available in the server, 
-.I XkbSetNamedIndicator 
+.I XkbSetNamedDeviceIndicator
 returns False. Otherwise, it sends a request to the X server to change the 
 indicator specified by 
 .I name 
@@ -70,12 +86,12 @@ and returns True.
 If 
 .I change_state 
 is True, and the optional parameter, 
-.I state, 
+.IR state ,
 is not NULL, 
-.I XkbSetNamedIndicator 
+.I XkbSetNamedDeviceIndicator
 tells the server to change the state of the named indicator to the value 
 specified by 
-.I state. 
+.IR state .
 
 If an indicator with the name specified by 
 .I name 
@@ -85,26 +101,45 @@ parameter tells the server whether it should create a new named indicator. If
 .I create_new 
 is True, the server finds the first indicator that doesn't have a name and gives 
 it the name specified by 
-.I name. 
+.IR name .
 If the optional parameter, 
-.I map, is not NULL, 
-.I XkbSetNamedIndicator 
+.IR map ,
+is not NULL,
+.I XkbSetNamedDeviceIndicator
 tells the server to change the indicator's map to the values specified in 
-.I map.
+.IR map .
 
 In addition, it can also generate XkbIndicatorStateNotify, 
 XkbIndicatorMapNotify, and XkbNamesNotify events.
+.LP
+.I XkbSetNamedIndicator
+is a convenience function that calls
+.I XkbSetNamedDeviceIndicator
+with a
+.I device_spec
+of
+.BR XkbUseCoreKbd ,
+a
+.I led_class
+of
+.BR XkbDfltXIClass ,
+and a
+.I led_id
+of
+.BR XkbDfltXIId .
+It returns the return value from
+.IR XkbSetNamedDeviceIndicator .
 .SH "RETURN VALUES"
 .TP 15
 True
 The 
-.I XkbSetNamedIndicator 
-function returns True if a compatible version of the Xkb extension is available in the server.
+.IR XkbSetNamedIndicator " and " XkbSetNamedDeviceIndicator
+functions return True if a compatible version of the Xkb extension is available in the server.
 .TP 15
 False
 The 
-.I XkbSetNamedIndicator 
-function returns False if a compatible version of the Xkb extension is not available in the server.
+.IR XkbSetNamedIndicator " and " XkbSetNamedDeviceIndicator
+functions return False if a compatible version of the Xkb extension is not available in the server.
 .SH DIAGNOSTICS
 .TP 15
 .B BadAtom
@@ -112,6 +147,24 @@ A name is neither a valid Atom or None
 .TP 15
 .B BadImplementation
 Invalid reply from server
+.TP 15
+.B BadKeyboard
+.I device_spec
+does not specify a device with indicators.
+.TP 15
+.B BadMatch
+.I led_id
+is not
+.B DfltXIId
+and does not specify a feedback of the class specified by
+.I led_class
+on the device specified by
+.IR device_spec .
+.TP 15
+.B BadValue
+.I led_class
+does not specify
+.BR DfltXIClass ", " LedFeedbackClass ", or " KbdFeedbackClass .
 .SH "SEE ALSO"
 .BR XkbIndicatorMapNotify (__libmansuffix__),
 .BR XkbIndicatorStateNotify (__libmansuffix__),