Add more detailed documentation for keylayoutforce

src/excmds.ts

@@ -4322,12 +4322,13 @@ export function bindurl(pattern: string, mode: string, keys: string, ...excmd: s
 }
 
 /**
+ *  Deprecated: use `:set keylayoutforce true` instead.
+ *
  *  Makes one key equivalent to another for the purposes of most of our parsers. Useful for international keyboard layouts. See user-provided examples for various layouts on our wiki: https://github.com/tridactyl/tridactyl/wiki/Internationalisation
  *
  *  e.g,
  *      keymap ę e
  *
- *  See `:help keytranslatemodes` to enable keymaps in modes other than normal mode.
  */
 //#background
 export function keymap(source: string, target: string) {

src/lib/config.ts

@@ -548,8 +548,10 @@ export class default_config {
      * use machine code of a key and convert to character according to keylayoutforcemapping. The default layout mapping
      * is QWERTY, but can be changed with `set keylayoutforcemapping <Code> <Values>`. See [[keylayoutforcemapping]].
      *
+     * There is a much more detailed help page towards the end of `:tutor` under the title "Non-QWERTY layouts".
+     *
      * Recommended for everyone with multiple or/and non-latin keyboard layouts. Make sure usekeytranslatemap is false
-     * if you use it.
+     * if you have previously used `keymap`.
      */
     keylayoutforce: "true" | "false" = "false"
 

src/static/clippy/8-1-i18n.md

@@ -0,0 +1,15 @@
+# Non-QWERTY layouts and Tridactyl ("internationalisation")
+
+Tridactyl's default keybinds are designed to be ergonomic on a QWERTY keyboard layout. On many other layouts - such as DVORAK or BÉPO - they are extremely unergonomic.
+
+If you only use one keyboard layout, you could quite reasonably decide to rebind all of Tridactyl's binds manually to make it more ergonomic, or you could use `:keymap` to make your layout as seen to Tridactyl be more like QWERTY or whatever other layout you desire.
+
+However, if you use multiple keyboard layouts, we recommend that you `:set keylayoutforce true`. This setting intercepts all key presses and checks the keyboard layout-agnostic key codes and then translates those keycodes into the US ANSI QWERTY layout by default. This means that Tridactyl behaviour depends on the physical keys you press rather than the layout you are currently using, except in text fields. The major downside to this is that binding new commands becomes a bit mind bending since when you are writing the bind you must press the key that corresponds in your layout to the forced layout, rather than the physical key.
+
+To counteract this, we have added a binding wizard/helper called `:bindwizard` which starts `gobble`, accepting physical key presses until Enter is pressed, at which point it prefills the command line with the key sequence which corresponds to your keys in the forced layout. Your binds will then be bound to the same keys no matter which software layout you use.
+
+You can change the forced layout key-by-key, see `:help keylayoutforcemapping`, if, for example, you would prefer the forced layout to be more like the UK QWERTY.
+
+At the time of writing, it is not possible to use `:setmode` with `keylayoutforce`, which means it also applies to hint mode and hint characters, which may be surprising.
+
+The [next and final page](./9-help.md) of this tutorial is about getting help. <a href='./8-marks.md' rel="prev"></a>

src/static/clippy/8-marks.md

@@ -1,15 +1,14 @@
 # Marks
 
-Marks allow you to record your current position so that you can go back to it later.
+Marks allow you to record your current position so that you can go back to it later. There are 2 types of marks:
-There are 2 types of marks:
 
--  local
+-   local
-   -  these work only on the page they were added on and are NOT persisted between browser restarts. They allow to you to save a position on a long, scrollable page. You can assign them to lowercase latin letters [a-z].
+    -   these work only on the page they were added on and are NOT persisted between browser restarts. They allow to you to save a position on a long, scrollable page. You can assign them to lowercase latin letters [a-z].
--  global
+-   global
-   -  these work anywhere and are persisted between browser restarts. You can assign them to uppercase latin letters [A-Z].
+    -   these work anywhere and are persisted between browser restarts. You can assign them to uppercase latin letters [A-Z].
 
 You can add a mark with `markadd [key]` or by using the default keybinding `m[key]`. To jump to a previously set mark, use `markjump [key]` or the default keybinding `` `[key] ``. You can also press ` `` ` to jump to the location before the last mark jump.
 
 Try marking this position using `mA`. Switch to another tab and press `` `A `` to come back here. Press ` `` ` to go back to where you came from. You can also try setting a local mark using `ma` in the middle of a scrollable page, press `gg` to move to the top and then press `` `a `` to jump to the mark.
 
-The [next and final page](./9-help.md) of this tutorial is about getting help. <a href='./7-native_messenger.md' rel="prev"></a>
+The [next](./8-1-i18n.md) of this tutorial is about comfortably using Tridactyl with keyboard layouts that are very different from QWERTY. <a href='./7-native_messenger.md' rel="prev"></a>

src/static/newtab.md

@@ -38,6 +38,7 @@ REPLACE_ME_WITH_THE_CHANGE_LOG_USING_SED
 -   [`:help hint`][help-hint] to see all the other useful hint modes (this is the `f` magic. :) ).
 -   `:help <keybinding>` to learn more about what a specific key binding does.
 -   `:colours [dark|quake|...]` to change Tridactyl's theme (and the colour of this page)
+-   `:set keylayoutforce true` to pretend that your keyboard layout is always QWERTY - very useful for, e.g., Cyrillic keyboards
 
 ## Important limitations due to WebExtensions