Merge remote-tracking branch 'origin/master' into develop

docs/feature_caps_word.md

@@ -6,9 +6,9 @@ a modern alternative to Caps Lock:
 
 * Letters are capitalized while active, and Caps Word automatically disables
   itself at the end of the word. That is, it stops by default once a space or
-  any key other than `a`--`z`, `0`--`9`, `-`, `_`, delete, or backspace is
-  pressed. Caps Word also disables itself if the keyboard is idle for 5 seconds.
-  This is configurable, see below.
+  any key other than `KC_A`--`KC_Z`, `KC_0`--`KC_9`, `KC_MINS`, `KC_UNDS`,
+  `KC_DELETE`, or `KC_BACKSPACE` is pressed. Caps Word also disables itself if
+  the keyboard is idle for 5 seconds. This is configurable, see below.
 
 * To avoid requiring a dedicated key for Caps Word, there is an option
   (`BOTH_SHIFTS_TURNS_ON_CAPS_WORD`) to activate Caps Word by simultaneously
@@ -16,7 +16,17 @@ a modern alternative to Caps Lock:
 
 * The implementation does not use the Caps Lock (`KC_CAPS`) keycode. Caps Word
   works even if you're remapping Caps Lock at the OS level to Ctrl or something
-  else, as Emacs and Vim users often do.
+  else, as Emacs and Vim users often do. As a consequence, Caps Word does not
+  follow the typical Caps Lock behaviour and may thus act in potentially
+  unexpected ways, especially when using an *OS* keyboard layout other than US
+  or UK. For example, Dvorak's <kbd>, <</kbd> key (`DV_COMM` aka `KC_W`) will
+  get shifted because Caps Word interprets that keycode as the letter 'W' by
+  default, the Spanish <kbd>Ñ</kbd> key (`ES_NTIL` aka `KC_SCLN`) will not get
+  capitalized because Caps Word interprets it as the semicolon ';' punctuation
+  character, and the US hyphen key (`KC_MINS`), while unaffected by Caps Lock,
+  is shifted by Caps Word. However, this is not really a problem because you can
+  [configure which keys should Caps Word
+  shift](#configure-which-keys-are-word-breaking).
 
 
 ## How do I enable Caps Word :id=how-do-i-enable-caps-word