Add new warning for deprecated keysyms

Guard deprecated keysym test with verbositoty level ≥5.

doc/message-registry.md

@@ -6,7 +6,7 @@ NOTE: This file has been generated automatically by “update-message-registry.p
 -->
 
 This page lists the warnings and errors generated by xkbcommon.
-There are currently 55 entries.
+There are currently 56 entries.
 
 @todo The documentation of the log messages is a work in progress.
 
@@ -34,6 +34,7 @@ There are currently 55 entries.
 | [XKB-254] | `invalid-set-default-statement` | Invalid statement setting default values | Error |
 | [XKB-266] | `conflicting-key-type-map-entry` | Conflicting “map” entries in type definition | Warning |
 | [XKB-286] | `undefined-key-type` | Warn if using an undefined key type | Warning |
+| [XKB-301] | `deprecated-keysym` | A keysym has been deprecated: use the corresponding canonical keysym instead | Warning |
 | [XKB-305] | `non-base-group-name` | Warn if a group name was defined for group other than the first one | Warning |
 | [XKB-312] | `unsupported-shift-level` | Warn when a shift level is not supported | Error |
 | [XKB-338] | `included-file-not-found` | Could not find a file used in an include statement | Error |
@@ -284,6 +285,14 @@ xkbcommon supports group index in the range (1..4).
   <dt>Summary</dt><dd>Warn if using an undefined key type</dd>
 </dl>
 
+### XKB-301 – Deprecated keysym {#XKB-301}
+
+<dl>
+  <dt>Since</dt><dd>1.8.0</dd>
+  <dt>Type</dt><dd>Warning</dd>
+  <dt>Summary</dt><dd>A keysym has been deprecated: use the corresponding canonical keysym instead</dd>
+</dl>
+
 ### XKB-305 – Non base group name {#XKB-305}
 
 <dl>
@@ -705,6 +714,7 @@ The modifiers used in `map` or `preserve` entries should be declared using the e
 [XKB-254]: @ref XKB-254
 [XKB-266]: @ref XKB-266
 [XKB-286]: @ref XKB-286
+[XKB-301]: @ref XKB-301
 [XKB-305]: @ref XKB-305
 [XKB-312]: @ref XKB-312
 [XKB-338]: @ref XKB-338

doc/message-registry.yaml

@@ -152,6 +152,11 @@
   added: ALWAYS
   type: warning
   description: "Warn if using an undefined key type"
+- id: "deprecated-keysym"
+  code: 301
+  added: 1.8.0
+  type: warning
+  description: "A keysym has been deprecated: use the corresponding canonical keysym instead"
 - id: "non-base-group-name"
   code: 305
   added: ALWAYS
@@ -410,5 +415,4 @@
     The modifiers used in `map` or `preserve` entries should be declared using the entry
     `modifiers` in the key type.
 
-# TODO: deprecated keysym
 # TODO: unicode keysym when named and recommended keysym exists

src/compose/parser.c

@@ -62,6 +62,7 @@ OR PERFORMANCE OF THIS SOFTWARE.
 #include "paths.h"
 #include "utf8.h"
 #include "parser.h"
+#include "keysym.h"
 
 /*
  * Grammar adapted from libX11/modules/im/ximcp/imLcPrs.c.
@@ -630,6 +631,8 @@ parse(struct xkb_compose_table *table, struct scanner *s,
                         val.string.str);
             goto error;
         }
+        check_deprecated_keysyms(scanner_warn_with_code, s, s->ctx,
+                                 keysym, val.string.str, val.string.str, "%s", "\n");
         if (production.len + 1 > MAX_LHS_LEN) {
             scanner_warn(s, "too many keysyms (%d) on left-hand side; skipping line",
                          MAX_LHS_LEN + 1);
@@ -703,6 +706,8 @@ lhs_mod_list_tok: {
                         val.string.str);
             goto error;
         }
+        check_deprecated_keysyms(scanner_warn_with_code, s, s->ctx,
+                                 keysym, val.string.str, val.string.str, "%s", "\n");
         if (production.has_keysym) {
             scanner_warn(s, "right-hand side can have at most one keysym; skipping line");
             goto skip;

src/keysym.h

@@ -113,6 +113,19 @@ xkb_keysym_is_deprecated(xkb_keysym_t keysym,
                          const char *name,
                          const char **reference_name);
 
+#define XKB_MIN_VERBOSITY_DEPRECATED_KEYSYM 5
+#define check_deprecated_keysyms(log_func, log_param, ctx, keysym, name, token, format, end) \
+    if (unlikely((ctx)->log_verbosity >= XKB_MIN_VERBOSITY_DEPRECATED_KEYSYM)) {             \
+        const char *ref_name = NULL;                                                         \
+        if (xkb_keysym_is_deprecated(keysym, name, &ref_name)) {                             \
+            log_func(log_param, XKB_WARNING_DEPRECATED_KEYSYM,                               \
+                     "deprecated keysym \"" format "\"%s%s%s" end, token,                    \
+                     (ref_name != NULL) ? "; please use \"" : "",                            \
+                     (ref_name != NULL) ? ref_name : "",                                     \
+                     (ref_name != NULL) ? "\" instead." : ".");                              \
+        }                                                                                    \
+    }
+
 bool
 xkb_keysym_is_lower(xkb_keysym_t keysym);
 

src/keysym.h.jinja

@@ -113,6 +113,19 @@ xkb_keysym_is_deprecated(xkb_keysym_t keysym,
                          const char *name,
                          const char **reference_name);
 
+#define XKB_MIN_VERBOSITY_DEPRECATED_KEYSYM 5
+#define check_deprecated_keysyms(log_func, log_param, ctx, keysym, name, token, format, end) \
+    if (unlikely((ctx)->log_verbosity >= XKB_MIN_VERBOSITY_DEPRECATED_KEYSYM)) {             \
+        const char *ref_name = NULL;                                                         \
+        if (xkb_keysym_is_deprecated(keysym, name, &ref_name)) {                             \
+            log_func(log_param, XKB_WARNING_DEPRECATED_KEYSYM,                               \
+                     "deprecated keysym \"" format "\"%s%s%s" end, token,                    \
+                     (ref_name != NULL) ? "; please use \"" : "",                            \
+                     (ref_name != NULL) ? ref_name : "",                                     \
+                     (ref_name != NULL) ? "\" instead." : ".");                              \
+        }                                                                                    \
+    }
+
 bool
 xkb_keysym_is_lower(xkb_keysym_t keysym);
 

src/messages-codes.h

@@ -56,6 +56,8 @@ enum xkb_message_code {
     XKB_WARNING_CONFLICTING_KEY_TYPE_MAP_ENTRY = 266,
     /** Warn if using an undefined key type */
     XKB_WARNING_UNDEFINED_KEY_TYPE = 286,
+    /** A keysym has been deprecated: use the corresponding canonical keysym instead */
+    XKB_WARNING_DEPRECATED_KEYSYM = 301,
     /** Warn if a group name was defined for group other than the first one */
     XKB_WARNING_NON_BASE_GROUP_NAME = 305,
     /** Warn when a shift level is not supported */

src/xkbcomp/expr.c

@@ -710,17 +710,20 @@ ExprResolveKeySym(struct xkb_context *ctx, const ExprDef *expr,
     if (expr->expr.op == EXPR_IDENT) {
         const char *str = xkb_atom_text(ctx, expr->ident.ident);
         *sym_rtrn = xkb_keysym_from_name(str, 0);
-        if (*sym_rtrn != XKB_KEY_NoSymbol)
+        if (*sym_rtrn != XKB_KEY_NoSymbol) {
+            check_deprecated_keysyms(log_warn, ctx, ctx,
+                                     *sym_rtrn, str, str, "%s", "\n");
             return true;
+        }
     }
 
     if (!ExprResolveInteger(ctx, expr, &val))
         return false;
 
     if (val < XKB_KEYSYM_MIN) {
         log_warn(ctx, XKB_WARNING_UNRECOGNIZED_KEYSYM,
-                           "unrecognized keysym \"-0x%x\" (%d)\n",
-                           (unsigned int) -val, val);
+                 "unrecognized keysym \"-0x%x\" (%d)\n",
+                 (unsigned int) -val, val);
         return false;
     }
 
@@ -731,16 +734,17 @@ ExprResolveKeySym(struct xkb_context *ctx, const ExprDef *expr,
     }
 
     if (val <= XKB_KEYSYM_MAX) {
+        check_deprecated_keysyms(log_warn, ctx, ctx, val, NULL, val, "0x%x", "\n");
         log_warn(ctx, XKB_WARNING_NUMERIC_KEYSYM,
-                           "numeric keysym \"0x%x\" (%d)",
-                           (unsigned int) val, val);
+                 "numeric keysym \"0x%x\" (%d)",
+                 (unsigned int) val, val);
         *sym_rtrn = (xkb_keysym_t) val;
         return true;
     }
 
     log_warn(ctx, XKB_WARNING_UNRECOGNIZED_KEYSYM,
-                       "unrecognized keysym \"0x%x\" (%d)\n",
-                       (unsigned int) val, val);
+             "unrecognized keysym \"0x%x\" (%d)\n",
+             (unsigned int) val, val);
     return false;
 
 }

src/xkbcomp/parser.y

@@ -59,7 +59,7 @@ _xkbcommon_error(struct parser_param *param, const char *msg)
 }
 
 static bool
-resolve_keysym(const char *name, xkb_keysym_t *sym_rtrn)
+resolve_keysym(struct parser_param *param, const char *name, xkb_keysym_t *sym_rtrn)
 {
     xkb_keysym_t sym;
 
@@ -76,6 +76,8 @@ resolve_keysym(const char *name, xkb_keysym_t *sym_rtrn)
     sym = xkb_keysym_from_name(name, XKB_KEYSYM_NO_FLAGS);
     if (sym != XKB_KEY_NoSymbol) {
         *sym_rtrn = sym;
+        check_deprecated_keysyms(parser_warn, param, param->ctx,
+                                 sym, name, name, "%s", "");
         return true;
     }
 
@@ -726,7 +728,7 @@ KeySyms         :       OBRACE KeySymList CBRACE
 
 KeySym          :       IDENT
                         {
-                            if (!resolve_keysym($1, &$$)) {
+                            if (!resolve_keysym(param, $1, &$$)) {
                                 parser_warn(
                                     param,
                                     XKB_WARNING_UNRECOGNIZED_KEYSYM,
@@ -750,12 +752,15 @@ KeySym          :       IDENT
                                 $$ = XKB_KEY_NoSymbol;
                             }
                             /* Special case for digits 0..9 */
-                            else if ($1 < 10) {      /* XKB_KEY_0 .. XKB_KEY_9 */
+                            else if ($1 < 10) {     /* XKB_KEY_0 .. XKB_KEY_9 */
                                 $$ = XKB_KEY_0 + (xkb_keysym_t) $1;
                             }
                             else {
                                 if ($1 <= XKB_KEYSYM_MAX) {
                                     $$ = (xkb_keysym_t) $1;
+                                    check_deprecated_keysyms(
+                                        parser_warn, param, param->ctx,
+                                        $$, NULL, $$, "0x%"PRIx32, "");
                                 } else {
                                     parser_warn(
                                         param, XKB_WARNING_UNRECOGNIZED_KEYSYM,

tools/messages.c

@@ -58,6 +58,7 @@ static const struct xkb_message_entry xkb_messages[] = {
     {XKB_ERROR_INVALID_SET_DEFAULT_STATEMENT, "Invalid set default statement"},
     {XKB_WARNING_CONFLICTING_KEY_TYPE_MAP_ENTRY, "Conflicting key type map entry"},
     {XKB_WARNING_UNDEFINED_KEY_TYPE, "Undefined key type"},
+    {XKB_WARNING_DEPRECATED_KEYSYM, "Deprecated keysym"},
     {XKB_WARNING_NON_BASE_GROUP_NAME, "Non base group name"},
     {XKB_ERROR_UNSUPPORTED_SHIFT_LEVEL, "Unsupported shift level"},
     {XKB_ERROR_INCLUDED_FILE_NOT_FOUND, "Included file not found"},