From 910599f7667577937e7804a96d829ba98881c538 Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Sun, 10 Nov 2024 08:14:00 +0100 Subject: [PATCH 01/10] docs: mention host_language in Language-specific Keycodes --- docs/reference_keymap_extras.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index d45183b6c6a1..739988884e5f 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -4,7 +4,7 @@ Keyboards are able to support a wide range of languages. However, this support i Obviously, this can get confusing, so QMK provides language-specific keycode aliases for many keyboard layouts. These won't do much on their own - you still have to set the matching keyboard layout in your OS settings. Think of them more as keycap labels for your keymap. -Simply `#include` one of the keycode headers below at the top of your `keymap.c`, and assign the keycodes defined in the header in place of the `KC_` prefixed ones. +Simply `#include` one of the keycode headers below at the top of your `keymap.c`, or set the `host_language` field in your `keymap.json` to the corresponding language. Then assign the keycodes defined in the header in place of the `KC_` prefixed ones. ## Sendstring Support From bbe17cfebb8653bb40769d25155b6716a86542f4 Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Sun, 10 Nov 2024 19:34:27 +0100 Subject: [PATCH 02/10] docs: move language example from macros over to host language page --- docs/feature_macros.md | 33 +-------------------------------- docs/reference_keymap_extras.md | 23 +++++++++++++++++++++-- 2 files changed, 22 insertions(+), 34 deletions(-) diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 055bb3ff8f72..8a48361d4de3 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -42,38 +42,7 @@ You can define up to 32 macros in a `keymap.json` file, as used by [Configurator ### Selecting Your Host Keyboard Layout -If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros - you may need to type different keys to get the same letters! To address this you can add the `host_language` key to your `keymap.json`, like so: - -```json -{ - "keyboard": "handwired/my_macropad", - "keymap": "my_keymap", - "host_language": "dvorak", - "macros": [ - ["Hello, World!"] - ], - "layout": "LAYOUT_all", - "layers": [ - ["QK_MACRO_0"] - ] -} -``` - -The current list of available languages is: - -| belgian | bepo | br_abnt2 | canadian_multilingual | -|:-------:|:----:|:--------:|:---------------------:| -| **colemak** | **croatian** | **czech** | **danish** | -| **dvorak_fr** | **dvorak** | **dvp** | **estonian** | -| **finnish** | **fr_ch** | **french_afnor** | **french** | -| **french_osx** | **german_ch** | **german** | **german_osx** | -| **hungarian** | **icelandic** | **italian** | **italian_osx_ansi** | -| **italian_osx_iso** | **jis** | **latvian** | **lithuanian_azerty** | -| **lithuanian_qwerty** | **norman** | **norwegian** | **portuguese** | -| **portuguese_osx_iso** | **romanian** | **serbian_latin** | **slovak** | -| **slovenian** | **spanish_dvorak** | **spanish_latin_america** | **spanish** | -| **swedish** | **turkish_f** | **turkish_q** | **uk** | -| **us_international** | **workman** | **workman_zxcvm** | +If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros - you may need to type different keys to get the same letters! To address this you can use [language-specific keycodes](./reference_keymap_extras.md). ### Macro Basics diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index 739988884e5f..0ffa331226d5 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -2,9 +2,28 @@ Keyboards are able to support a wide range of languages. However, this support is not actually achieved within the keyboard itself - instead, it sends numerical codes, which the operating system maps to the appropriate characters depending on the user's configured keyboard layout. By default (and per the HID spec), this is the US ANSI layout. For example, when a Swedish person presses the key with the `å` character printed on it, the keyboard is *actually* sending the keycode for `[`. -Obviously, this can get confusing, so QMK provides language-specific keycode aliases for many keyboard layouts. These won't do much on their own - you still have to set the matching keyboard layout in your OS settings. Think of them more as keycap labels for your keymap. +Obviously, this can get confusing, so QMK provides language-specific keycode aliases for many keyboard layouts. These are used in place of the `KC_` prefixed ones. They won't do much on their own - you still have to set the matching keyboard layout in your OS settings. Think of them more as keycap labels for your keymap. The language-specific keycode aliases are defined in the files listed in the [Keycodes Header](#header-files) column below. -Simply `#include` one of the keycode headers below at the top of your `keymap.c`, or set the `host_language` field in your `keymap.json` to the corresponding language. Then assign the keycodes defined in the header in place of the `KC_` prefixed ones. +## Selecting Your Host Keyboard Layout + +To select a host keyboard layout, simply `#include` one of the [keycode headers](#header-files) below at the top of your `keymap.c`. + +Alternatively, if using `keymap.json`, add the `host_language` key as shown in the following example. The available languages are those with a _Sendstring LUT Header_ entry in one of the [Header Files](#header-files) tables. + +```json +{ + "keyboard": "handwired/my_macropad", + "keymap": "my_keymap", + "host_language": "dvorak", + "macros": [ + ["Hello, World!"] + ], + "layout": "LAYOUT_all", + "layers": [ + ["QK_MACRO_0"] + ] +} +``` ## Sendstring Support From 53c4a0b6bb2276400c8df480b77aa48e67329754 Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Mon, 11 Nov 2024 06:11:12 +0100 Subject: [PATCH 03/10] docs: fix hyphen MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: フィルターペーパー <76888457+filterpaper@users.noreply.github.com> --- docs/feature_macros.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 8a48361d4de3..7f4771481f58 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -42,7 +42,7 @@ You can define up to 32 macros in a `keymap.json` file, as used by [Configurator ### Selecting Your Host Keyboard Layout -If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros - you may need to type different keys to get the same letters! To address this you can use [language-specific keycodes](./reference_keymap_extras.md). +If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros — you may need to type different keys to get the same letters! To address this you can use [language-specific keycodes](./reference_keymap_extras.md). ### Macro Basics From a41bb6f1804c5426a2cdd7daef6b0ac3966a33bb Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Mon, 11 Nov 2024 06:11:44 +0100 Subject: [PATCH 04/10] docs: improve host_language example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: フィルターペーパー <76888457+filterpaper@users.noreply.github.com> --- docs/reference_keymap_extras.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index 0ffa331226d5..c9b36b7645fb 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -14,13 +14,10 @@ Alternatively, if using `keymap.json`, add the `host_language` key as shown in t { "keyboard": "handwired/my_macropad", "keymap": "my_keymap", - "host_language": "dvorak", - "macros": [ - ["Hello, World!"] - ], + "host_language": "swedish", "layout": "LAYOUT_all", "layers": [ - ["QK_MACRO_0"] + ["SE_A"] ] } ``` From 236cab55bc9ab5ece6cf0e1a0a9951896a7a9d94 Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Mon, 11 Nov 2024 06:13:56 +0100 Subject: [PATCH 05/10] docS: include keymap.c example --- docs/reference_keymap_extras.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index c9b36b7645fb..83b7f5cfabf6 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -6,7 +6,11 @@ Obviously, this can get confusing, so QMK provides language-specific keycode ali ## Selecting Your Host Keyboard Layout -To select a host keyboard layout, simply `#include` one of the [keycode headers](#header-files) below at the top of your `keymap.c`. +To select a host keyboard layout, simply `#include` one of the [keycode headers](#header-files) below at the top of your `keymap.c`. Example: + +```c +#include keymap_japanese.h +``` Alternatively, if using `keymap.json`, add the `host_language` key as shown in the following example. The available languages are those with a _Sendstring LUT Header_ entry in one of the [Header Files](#header-files) tables. From 762d343f1f11be578f27d4065d4d4c60bdb9fa82 Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Mon, 11 Nov 2024 06:18:08 +0100 Subject: [PATCH 06/10] docs: use SE_ARNG (a with ring over) in code example as well --- docs/reference_keymap_extras.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index 83b7f5cfabf6..dd19a643df66 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -21,7 +21,7 @@ Alternatively, if using `keymap.json`, add the `host_language` key as shown in t "host_language": "swedish", "layout": "LAYOUT_all", "layers": [ - ["SE_A"] + ["SE_ARNG"] ] } ``` From af42fed4805fde64e8ecebb6ed3bee9a21aab6cb Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Wed, 13 Nov 2024 10:10:42 +0100 Subject: [PATCH 07/10] docs: fix md ref Co-authored-by: Joel Challis --- docs/feature_macros.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 7f4771481f58..b4e37a1ba96f 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -42,7 +42,7 @@ You can define up to 32 macros in a `keymap.json` file, as used by [Configurator ### Selecting Your Host Keyboard Layout -If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros — you may need to type different keys to get the same letters! To address this you can use [language-specific keycodes](./reference_keymap_extras.md). +If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros — you may need to type different keys to get the same letters! To address this you can use [language-specific keycodes](reference_keymap_extras). ### Macro Basics From 8fde3023561765ebcd0a71e537632a1f21e8258e Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Wed, 13 Nov 2024 16:26:52 +0100 Subject: [PATCH 08/10] docs: fix c example include Co-authored-by: Ryan --- docs/reference_keymap_extras.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index dd19a643df66..48b56ae713a3 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -9,7 +9,7 @@ Obviously, this can get confusing, so QMK provides language-specific keycode ali To select a host keyboard layout, simply `#include` one of the [keycode headers](#header-files) below at the top of your `keymap.c`. Example: ```c -#include keymap_japanese.h +#include "keymap_japanese.h" ``` Alternatively, if using `keymap.json`, add the `host_language` key as shown in the following example. The available languages are those with a _Sendstring LUT Header_ entry in one of the [Header Files](#header-files) tables. From e6ecf19dedd65c066831bb3bdd55093c4b98018f Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Wed, 13 Nov 2024 16:27:31 +0100 Subject: [PATCH 09/10] docs: focus example on relevant host_language line Co-authored-by: Ryan --- docs/reference_keymap_extras.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index 48b56ae713a3..4ff974eaf621 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -18,7 +18,7 @@ Alternatively, if using `keymap.json`, add the `host_language` key as shown in t { "keyboard": "handwired/my_macropad", "keymap": "my_keymap", - "host_language": "swedish", + "host_language": "swedish", // [!code focus] "layout": "LAYOUT_all", "layers": [ ["SE_ARNG"] From 42ab287977d3b234e88a782bfe354f7e39a4dc12 Mon Sep 17 00:00:00 2001 From: Amund Tenstad Date: Thu, 14 Nov 2024 06:13:20 +0100 Subject: [PATCH 10/10] docs: QMK_KEYBOARD_H Co-authored-by: Ryan --- docs/reference_keymap_extras.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index 4ff974eaf621..f6b4b8faf688 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -9,7 +9,9 @@ Obviously, this can get confusing, so QMK provides language-specific keycode ali To select a host keyboard layout, simply `#include` one of the [keycode headers](#header-files) below at the top of your `keymap.c`. Example: ```c -#include "keymap_japanese.h" +#include QMK_KEYBOARD_H + +#include "keymap_japanese.h" // [!code focus] ``` Alternatively, if using `keymap.json`, add the `host_language` key as shown in the following example. The available languages are those with a _Sendstring LUT Header_ entry in one of the [Header Files](#header-files) tables.