Improve consistency in UNICODEMAP code and docs, update docs/understanding_qmk (#4774)

* Remove unused UNICODE(n) macro, update docs

* Add note about max length of unicode_map to docs

* QK_UNICODE_MAP → QK_UNICODEMAP

* Refactor process_unicode_map

* process_unicode_map → process_unicodemap

This is done for consistency: UNICODEMAP is the method (hence UNICODEMAP_ENABLE, process_unicodemap), whereas unicode_map is the mapping table itself.

* Update references and ordering in docs/understanding_qmk

* Add additional note to docs/understanding_qmk

* &unicode_map[index] → unicode_map + index

This avoids the issue of the compiler sometimes complaining about the array index being out of range

* Update docs/getting_started_make_guide

* Update method sections in docs/feature_unicode

docs/getting_started_make_guide.md

@@ -93,19 +93,17 @@ This enables MIDI sending and receiving with your keyboard. To enter MIDI send m
 
 `UNICODE_ENABLE`
 
-This allows you to send unicode symbols via `UC(<unicode>)` in your keymap. Only codes up to 0x7FFF are currently supported.
+This allows you to send Unicode characters using `UC(<code point>)` in your keymap. Code points up to `0x7FFF` are supported. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji.
 
 `UNICODEMAP_ENABLE`
 
-This allows sending unicode symbols using `X(<unicode>)` in your keymap. Codes
-up to 0xFFFFFFFF are supported, including emojis. You will need to maintain
-a separate mapping table in your keymap file.
+This allows you to send Unicode characters using `X(<map index>)` in your keymap. You will need to maintain a mapping table in your keymap file. All possible code points (up to `0x10FFFF`) are supported. 
 
-Known limitations:
-- Under Mac OS, only codes up to 0xFFFF are supported.
-- Under Linux ibus, only codes up to 0xFFFFF are supported (but anything important is still under this limit for now).
+`UCIS_ENABLE`
 
-Characters out of range supported by the OS will be ignored.
+This allows you to send Unicode characters by inputting a mnemonic corresponding to the character you want to send. You will need to maintain a mapping table in your keymap file. All possible code points (up to `0x10FFFF`) are supported.
+
+For further details, as well as limitations, see the [Unicode page](feature_unicode.md).
 
 `BLUETOOTH_ENABLE`
 
@@ -117,7 +115,7 @@ This allows you output audio on the C6 pin (needs abstracting). See the [audio p
 
 `FAUXCLICKY_ENABLE`
 
-Uses buzzer to emulate clicky switches. A cheap imitation of the Cherry blue switches. By default, uses the C6 pin, same as AUDIO_ENABLE.
+Uses buzzer to emulate clicky switches. A cheap imitation of the Cherry blue switches. By default, uses the C6 pin, same as `AUDIO_ENABLE`.
 
 `VARIABLE_TRACE`
 

docs/keycodes.md

@@ -454,7 +454,7 @@ This is a reference only. Each group of keys links to the page documenting their
 
 ## [Unicode Support](feature_unicode.md)
 
-|Key         |Aliases|                                                 |
-|------------|-------|-------------------------------------------------|
-|`UNICODE(n)`|`UC(n)`|Send Unicode character `n`                       |
-|`X(n)`      |       |Send Unicode character `n` via a different method|
+|Key    |Description                                                                |
+|-------|---------------------------------------------------------------------------|
+|`UC(c)`|Send Unicode code point `c` (`UNICODE_ENABLE`)                             |
+|`X(i)` |Send Unicode code point at index `i` in `unicode_map` (`UNICODEMAP_ENABLE`)|

quantum/process_keycode/process_unicode_common.c

@@ -216,7 +216,7 @@ bool process_unicode_common(uint16_t keycode, keyrecord_t *record) {
 #if   defined(UNICODE_ENABLE)
   return process_unicode(keycode, record);
 #elif defined(UNICODEMAP_ENABLE)
-  return process_unicode_map(keycode, record);
+  return process_unicodemap(keycode, record);
 #elif defined(UCIS_ENABLE)
   return process_ucis(keycode, record);
 #else

quantum/process_keycode/process_unicodemap.c

@@ -18,8 +18,7 @@
 #include "process_unicode_common.h"
 
 __attribute__((weak))
-const uint32_t PROGMEM unicode_map[] = {
-};
+const uint32_t PROGMEM unicode_map[] = {};
 
 void register_hex32(uint32_t hex) {
   bool onzerostart = true;
@@ -42,26 +41,26 @@ void register_hex32(uint32_t hex) {
 }
 
 __attribute__((weak))
-void unicode_map_input_error() {}
+void unicodemap_input_error() {}
 
-bool process_unicode_map(uint16_t keycode, keyrecord_t *record) {
-  uint8_t input_mode = get_unicode_input_mode();
-  if ((keycode & QK_UNICODE_MAP) == QK_UNICODE_MAP && record->event.pressed) {
-    const uint32_t* map = unicode_map;
-    uint16_t index = keycode - QK_UNICODE_MAP;
-    uint32_t code = pgm_read_dword(&map[index]);
-    if (code > 0xFFFF && code <= 0x10ffff && input_mode == UC_OSX) {
+bool process_unicodemap(uint16_t keycode, keyrecord_t *record) {
+  if ((keycode & QK_UNICODEMAP) == QK_UNICODEMAP && record->event.pressed) {
+    uint16_t index = keycode - QK_UNICODEMAP;
+    uint32_t code = pgm_read_dword(unicode_map + index);
+    uint8_t input_mode = get_unicode_input_mode();
+
+    if (code > 0xFFFF && code <= 0x10FFFF && input_mode == UC_OSX) {
       // Convert to UTF-16 surrogate pair
       code -= 0x10000;
-      uint32_t lo = code & 0x3ff;
-      uint32_t hi = (code & 0xffc00) >> 10;
+      uint32_t lo = code & 0x3FF, hi = (code & 0xFFC00) >> 10;
+
       unicode_input_start();
-      register_hex32(hi + 0xd800);
-      register_hex32(lo + 0xdc00);
+      register_hex32(hi + 0xD800);
+      register_hex32(lo + 0xDC00);
       unicode_input_finish();
-    } else if ((code > 0x10ffff && input_mode == UC_OSX) || (code > 0xFFFFF && input_mode == UC_LNX)) {
-      // when character is out of range supported by the OS
-      unicode_map_input_error();
+    } else if ((code > 0x10FFFF && input_mode == UC_OSX) || (code > 0xFFFFF && input_mode == UC_LNX)) {
+      // Character is out of range supported by the OS
+      unicodemap_input_error();
     } else {
       unicode_input_start();
       register_hex32(code);

quantum/process_keycode/process_unicodemap.h

@@ -19,5 +19,5 @@
 #include "quantum.h"
 #include "process_unicode_common.h"
 
-void unicode_map_input_error(void);
-bool process_unicode_map(uint16_t keycode, keyrecord_t *record);
+void unicodemap_input_error(void);
+bool process_unicodemap(uint16_t keycode, keyrecord_t *record);

quantum/quantum_keycodes.h

@@ -86,8 +86,8 @@ enum quantum_keycodes {
     QK_UNICODE_MAX        = 0xFFFF,
 #endif
 #ifdef UNICODEMAP_ENABLE
-    QK_UNICODE_MAP        = 0x8000,
-    QK_UNICODE_MAP_MAX    = 0x83FF,
+    QK_UNICODEMAP         = 0x8000,
+    QK_UNICODEMAP_MAX     = 0x83FF,
 #endif
 
     // Loose keycodes - to be used directly
@@ -679,15 +679,12 @@ enum quantum_keycodes {
 #define KC_MEH  MEH(KC_NO)
 
 #ifdef UNICODE_ENABLE
-    // For sending unicode codes.
-    // You may not send codes over 7FFF -- this supports most of UTF8.
-    // To have a key that sends out Œ, go UC(0x0152)
-    #define UNICODE(n) (QK_UNICODE | (n))
-    #define UC(n) UNICODE(n)
+  // Allows Unicode input up to 0x7FFF
+  #define UC(c) (QK_UNICODE | (c))
 #endif
-
 #ifdef UNICODEMAP_ENABLE
-    #define X(n) (QK_UNICODE_MAP | (n))
+  // Allows Unicode input up to 0x10FFFF, requires unicode_map
+  #define X(i) (QK_UNICODEMAP | (i))
 #endif
 
 #define UC_MOD  UNICODE_MODE_FORWARD