Enhanced keymap support

[lee-dohm]

One bone of contention from users of platforms other than OS X is that key maps exclusively use Mac bindings. See https://discuss.atom.io/t/dumb-question-why-is-control-denoted-cmd-in-the-docs/10737 and linked posts.

In that topic I mention a system whereby the appropriate key binding for the OS of the viewer of the document could be determined. This might be complicated given that Atlas generates documentation for more than just the web (i.e. ePub, Kindle, PDF) but I did see plans to create multiple language versions of the documentation ... could we have a multivariate customized version? Like French for Windows or German for OS X?

Thoughts?

[abe33]

In that topic I mention a system whereby the appropriate key binding for the OS of the viewer of the document could be determined.

UserAgent sniffing might be a good option for once. But I would not use it to generate the keymap, but rather to hide the irrelevant ones using CSS. I like the idea of not being burdened writing the keybinding for each OS when writing the docs, but rather than substituting your <span class="keyboard">...</span> at runtime I see something at the generation phase.

So, let's say we end up with the following markup:

<kbd data-os='mac'>cmd-shift-a</kbd>
<kbd data-os='linux'>ctrl-shift-a</kbd>
<kbd data-os='win'>ctrl-shift-a</kbd>

We could have something like that in the page script:

html = document.querySelector('html')
if /Macintosh/.test navigator.userAgent
  html.classList.add('mac')
else if /Linux/.test navigator.userAgent
  html.classList.add('linux')
else if /Windows/.test navigator.userAgent
  html.classList.add('win')

And then CSS rules like below that hides the irrelevant element:

html.mac [data-os='linux'], 
html.mac [data-os='win'] {
  display: none;
}

html.win [data-os='linux'], 
html.win [data-os='mac'] {
  display: none;
}

html.linux [data-os='win'], 
html.linux [data-os='mac'] {
  display: none;
}

The good thing with that trick is that it doesn't apply only to kbd tags. You can have whole sections in the documentation that is OS specific and by putting a data-os attribute on them you can display only the relevant ones. Also, it doesn't prevent from switching the displayed OS at runtime, just switch the class on the html element and you'll display the Windows-specific documentation on OSX and Linux.

[lee-dohm]

That's a great system, @abe33. I vote for that!

[olmokramer]

I vote against a system that hides documentation. I work on multiple OSes and I'd like to read all documentation that's relevant to me at once.

Maybe instead of being hidden, sections irrelevant to your OS could be collapsed? Their title could indicate that the content isn't relevant to your OS, but when clicked it expands the section anyway. For stuff that is not an entire section on itself - keybindings for example - the relevant ones could be highlighted.

[lee-dohm]

If we had a dropdown then there could simply be a fourth option "All". I'd really rather not have to see the Windows/Linux bindings most of the time ... but it would be useful when providing support. Whether the default is "All" or the OS as detected by user-agent is an additional question.

[olmokramer]

That sounds great! In that case I would prefer OS detection as the default

[abe33]

@olmokramer I understand your point, but you also have to consider how documentation are written.

Here's an example from the current docs:

If you hit cmd-shift-P while focused in an editor pane, the command palette will pop up.

Does putting every os bindings in this sentence make it more readable? I believe it doesn't.
We can consider adding some extra markup to specify for which os a kbd applies, i.e. by displaying an icon in a :before or :after rule, as linux/windows bindings may look similar. But even with that I'm not sure, from a reader POV, that it make things more readable.

The solution I propose offer the possibility to switch the reference OS at runtime. We can even add some extra controls to every element with a [data-os] attribute to display the alternatives. Or as @lee-dohm suggests we can have a select to choose how to display OS-specific stuffs.

But as always it's just a proposal, I've probably omitted some use cases where this trick won't be as effective as I think it is.

[olmokramer]

@abe33 That's why I voted for detect OS by default. When you select "all" OSes you give up a little bit of readability.

I like the idea of extra controls. An idea: on hovering a [data-os] a popup could show the info for other OSes

[mnquintana]

Now that the docs come in ebook formats, how would this approach translate to ebook exports? Would it mean listing all the keybindings inline? Having separate ebook exports for each platform?

[izuzak]

I'd ❤️ to see this happen as well, I think it would be really helpful for new users. We already do something similar (visually) in the Help docs for github.com (e.g. here):

So, your OS is auto-detected, but you can switch between them as well.

Not sure how hard this would be to do, but here's how I'm thinking about it on a high level:

1. Have a way to automatically collect all keybindings across Atom core and all core packages. Anything that's discussed in the flight manual, basically.
2. Replace all keystrokes in the book with Atom command references.
3. Have a way to automatically replace the command references with keystrokes, using the collected keybindings from step 1.
4. Have a way to show one or more keystrokes for each reference based on the selected OS. For different output formats, this will probably work differently. For example, in the HTML version we might to a selector, but for the PDF version we might do something else.

[gjtorikian]

That seems like a great idea. I'd be up for contributing some time to making that happen (as I also ported it for the Help site 😜).

For the Help docs, we write OS specific content like this:

{{#mac}}

Apples

{{/mac}}

{{#windows}}

Oranges

{{/windows}}

The Help docs also detect your OS by default; you're free to choose between them if that's your cup-of-tea (as well as modify the URL hash to provide a hardlink).

[dcarral]

This issue has kind of "spiked" me @ #112 (thanks @lee-dohm for pointing me in the right direction ;)).

I found @mnquintana's question a good one to bear in mind. How would ebook exports be handled? Between the 2 mentioned options I'd definitely go with the platform-specific version approach (vs listing all the keybindings inline).

Besides that, and after having checked the tasks mentioned in atom/atom#7995, it looks like there's not planned work to work on this issue, right?

[Zephilim]

I've just had a topic I raised closed down because it is similar to this one (https://discuss.atom.io/t/keyboard-mapping-for-windows/23220). As a newbie, I'm having a bit of nightmare learning keyboard mappings on Windows. The keyboard mapping documented in the flight manual, doesnt corresponding to what happens in windows, and even the keyboard mapping in Atom itself doesnt always work as expected. What is one supposed to do? Eg, in the flight manual, ctrl-t is documented as transpose characters, which sounds like a useful function. How on earth do I invoke this in Atom on windows? ctrl-t, just opens up the file which is highlighted in the treeview. If I can get this working, it'll be easier to find out how to get the other functions I can't seem to get working as they are listed in the key map in Atom.

[lee-dohm]

@TheNephilim you can use the Keybindings tab in the Settings View in Atom to discover what keybindings are actually used on your platform. You can get here by:

1. Launching Atom
2. Opening the Settings View with Ctrl+, on Windows or Linux
3. Clicking the "Keybindings" tab on the left

Once here, you can search for what command you want by just typing in part of the command name in the search box:

(I'm on OS X, so the keybinding is Ctrl+T for me. Your keybinding probably is different.)

[Zephilim]

Thanks Lee for your help. Actually, that key bindings tab is quite useful. However, when I look up the transpose function, there is no key mapping for it, which makes this particular function totally useless. It's quicker the reverse the characters manually, rather than invoke the keybindings and type in transpose. So to me it looks like, its been implemented for OSX in a useful way, but for everyone else, we're just left dangling. Which makes me wonder, what other functions have been neglected on windows, and why isn't this made more consistent with OSX. There's no reason why ctrl-T can't be the same on windows. And whilst I'm at it, what's the difference between say ctrl-t and ctrl-T. The latter would require the shift key, but that is a different key combination. (Hope that ain't too silly a question)

[lee-dohm]

I don't have a Windows (or Linux) machine handy so I can't comment on why it might not have been implemented for other operating systems. We do try to keep things as consistent as possible across all platforms.

One issue with mapping keybindings on Windows (and to some extent Linux) versus OS X is that OS X has one more modifier key than Windows. OS X has Shift, Ctrl, Alt (also called Option) and finally Cmd. The Cmd key on OS X is the same as the Windows key on Windows ... but whereas Windows reserves the Windows key for OS-level functions, OS X allows the Command key to be used for application-level functions. If we count out the combinations on Windows:

• 73 primary keys (alphanumeric, symbol, Esc, function and navigation keys)
• 3 modifier keys

If I'm remembering my combinatorics correctly that's 73 * 2 * 2 * 2 = 584 possible key combinations. On OS X there is twice as many, 1168. What this means is that it is harder to find a non-conflicting key combination on Windows than on OS X. Which also means that, in order to leave some of the "good keys" for packages ... there may be some functions that don't get mapped on Windows that might get mapped on OS X.

Did you try searching for ctrl-t in the keybindings view to see if it is already mapped to something else?

And whilst I'm at it, what's the difference between say ctrl-t and ctrl-T.

If you're asking what is the difference between the ctrl-t in the screenshot versus my Ctrl+T in my comment, the answer is that there is no difference other than notational styles. Or did I misunderstand your question?

[Zephilim]

Thanks Lee. You understood my question about ctrl-t & ctrl-T correctly. I in fact did think they were the same but I couldn't be sure because I've seen both upper case and lower case specified, and because of the difficulty I've been having invoking some functions by the keyboard, I thought that maybe case should be taken into account.

Since I am using an apple keyboard on bootcamped Windows 7, I am going to try defining a custom keymap that makes use of the fn key. Perhaps that way, I can try and fix the anomolies I'm experienciung, but that's a shame, because I just want to use Atom as close to the standard setup as possible, and without having to jump through hoops, as I do recall being one of the claims in the promotional material for Atom. Looking forward to this being resolved properly.

[ProustIdee]

It would be one thing if transpose was assigned to something else, but "editor:transpose" it is not even in the settings for Windows.

It makes the documentation confusing at best, misleading at worst. I've hit keys expecting one thing to happen, and something totally different happens.

[ghost]

It'd be nice if the Windows version also used Emacs-like bindings... You know, like Emacs for Windows does. Right now, much of the documentation regarding keybindings is confusing and irrelevant for Windows users.

[lee-dohm]

I finally got around to building this. It is live on the site now though I have only built the infrastructure. I still have to go through and update all the key combinations to the new standard.

If you want to see the new system in action, you can see it here:

http://flight-manual.atom.io/using-atom/sections/editing-and-deleting-text/