~glacambre/firenvim

bebe6aa0badb3cf0506b4e7c9371dbe56bbe5793 — glacambre 23 days ago 0ea1328 master
Fix README encoding
1 files changed, 4 insertions(+), 16 deletions(-)

M README.md
M README.md => README.md +4 -16
@@ 229,29 229,17 @@ let g:firenvim_config = {

### Special characters on MacOS

On MacOS, the default keyboard layouts emit special characters when the alt (i.e. option) key is held down. From the perspective of the browser, these special characters replace the underlying "main" character of a keystroke event while retaining the modifier. For example, in the standard US layout the key chord alt-o is received in the browser as alt-� rather than alt-o. Further, certain alt-chords represent "dead keys", which apply a diacritic to the next character entered. Pressing alt-e followed by a produces the single character "� while alt-u followed by a produces "�". To produce this behavior, diacritic-mapped strokes like alt-e and alt-u are themselves mapped to a ["Dead key" character](https://en.wikipedia.org/wiki/Dead_key). 
On MacOS, the default keyboard layouts emit special characters when the alt (i.e. option) key is held down. From the perspective of the browser, these special characters replace the underlying "main" character of a keystroke event while retaining the modifier. For example, in the standard US layout the key chord alt-o is received in the browser as alt-ø rather than alt-o. Further, certain alt-chords represent "dead keys", which apply a diacritic to the next character entered. Pressing alt-e followed by a produces the single character "á" while alt-u followed by a produces "ä". To produce this behavior, diacritic-mapped strokes like alt-e and alt-u are themselves mapped to a ["Dead key" character](https://en.wikipedia.org/wiki/Dead_key). 

These behaviors complicate the support of special character and alt/meta (A- or M-) vim mappings on MacOS in two ways:

1. There is no way to generate unmodified special character key events. For example, since the only way to generate the character "�" via the keyboard is by holding down alt, any key event with the "�" character will also have an alt modifier. If we forward this directly to Vim, it will be received as `<M-�>`.
1. There is no way to generate unmodified special character key events. For example, since the only way to generate the character "ø" via the keyboard is by holding down alt, any key event with the "ø" character will also have an alt modifier. If we forward this directly to Vim, it will be received as `<M-ø>`.

2. There is no way to generate alt-modified plain alphanumeric characters. For example, an `<M-o>` mapping won't work because pressing alt-o generates `<M-�>` rather than `<M-o>`.
2. There is no way to generate alt-modified plain alphanumeric characters. For example, an `<M-o>` mapping won't work because pressing alt-o generates `<M-ø>` rather than `<M-o>`.

Terminal and standalone GUI applications can solve these problems by changing the interpretation of the alt key at the application level. `Terminal.app` and `iTerm2`, for instance, both provide a "use Option as Meta key" preference that converts incoming alt-chords at the application level. Firenvim, however, is a browser extension that operates off of browser keystroke events rather than application-level events. At present, we are unsure how to implement this "use option as meta" functionality at the browser event level (help here is welcome!). However, there are some workarounds.

For problem (1), Firenvim will by default drop the alt key on MacOS for any special character, defined here as non-alphanumeric (not matching `/[a-zA-Z0-9]/`). This means alt-o will be forwarded to NeoVim as "�" rather than "M-�". Note that this behavior can be changed by setting the `alt` setting of the `globalSettings` configuration to `all`, like this:

```vim
let g:firenvim_config = {
	\ "globalSettings": {
		\ "alt": "all"
	\}
\}
```

Non-macOS users can get the default macOS behavior by setting the `alt` setting to `alphanum` (but they shouldn't ever need to do that).

For problem 2, the only known workaround is to disable the special-character functionality of alt/opt at an OS level. You can do this by using a keyboard layout that does not generate special characters when alt/opt is depressed. You can easily "fork" an existing keyboard layout to create one without special characters using the free application [Ukelele](https://software.sil.org/ukelele/).
For problem (1), Firenvim will by default drop the alt key on MacOS for any special character, defined here as non-alphanumeric (not matching `/[a-zA-Z0-9]/`). This means alt-o will be forwarded to NeoVim as "ø" rather than "M-ø". Note that this behavior can be changed by setting the `alt` setting of the `globalSettings` configuration to `all`, like this:

### Interacting with the page