Keyboard shortcuts

[sujato]

idea

Can be cool, right? Hit ctrl + k, a dialog pops up with some common actions: search maybe? Or something else?

There's a thing called that does this, and it's lit!

~https://ssleptsov.github.io/ninja-keys/~ https://github.com/ssleptsov/ninja-keys

Are there good use cases for this, or is it just a fancy dream? :thinking:

others

Some uses out there:

• slack: unread, channels
• notion: search in your content
• linear.app: search, support, feedback, invite, log out, create workspace etc., jump to things, lots of other stuff
• oh yeah, and now, right here on Github!
  • https://twitter.com/hey_sergei/status/1453392498756292629

for SC

We should look to solving an existing problem. I don't think access to search is a big deal; it's there in the toolbar on every page.

With our current navigation, however, I can see a few problems that this might address.

cost

Before starting, let's consider the cost. To make this useful we must pay the following costs:

• developer time, and consequently not doing other things
• clients must download and execute js.

To use it, people must:

• know it exists
• know the shortcuts
• do the following steps:
  • activate the shortcut
  • select the command
  • execute the command

So to justify it, we have to be confident that it offers a substantial improvement over what is already there.

history

Readers might often navigate between several suttas, and it can be hard to keep track. Perhaps we could remember them for them?

• when a user arrives at a sutta, store the URL.
• keep a list of, say, the last ten visited suttas
• when the keyboard is activated, show the list.

[thesunshade]

• index page
• change theme
• toggle root text
• toggle main references
• play on SCVoice
• copy text of entire sutta to clipboard (I would use this for sure)

Since SC doesn't have any user input other than search, there's no need to bind it to ctrl, etc.

If there were no developer "costs" I'd say sure, why not. However I imagine that the number of people who would use it might be a small percentage of overall users (and only those on desktop). But those who spend hours doing study would probably use it.

I'd actually rather you skip the keyboard shortcuts and go right to a command palette like VS Code/Atom has. Then you could allow for the changing of all settings, not having to pick what you think would be the most useful.

As well, a command palette could also include a way to go directly to suttas. Of course typing in the url bar is great, but that involves some mousework.

Anything worth doing is worth overdoing, eh?

[thesunshade]

Interestingly, Github just added a command palette:

https://docs.github.com/en/get-started/using-github/github-command-palette

[sujato]

Cool, thanks for the ideas! And yeah, I saw that Github added one, and they are planning on extending it too.

• index page: can you elaborate on this? i'm not sure exactly what you mean.
• change theme, toggle root, toggle refs, play on Voice: these ones replicate functionality available in the toolbar. So we'd need to establish that there was enough benefit from adding a new way of doing the same thing. I'm not really sure, so I'd be interested to hear of arguments for the usefulness of these. Maybe it's simply the convenience of having everything in one, keyboard-driven place?
• Copy sutta text to clipboard: ok, interesting one. Shouldn't be hard to do.

skip the keyboard shortcuts and go right to a command palette like VS Code/Atom ha

Could you elaborate, I'm not sure the distinction? AFAIK, ninja-keys just exposes the UI interface, and we can do anything we like with it, including commands or shortcuts or whatever.

Another approach would be simply to provide keyboard bindings for the existing controls. The ctrl + k could simply display a map of bindings.

Anything worth doing is worth overdoing, eh?

Umm …

I imagine that the number of people who would use it might be a small percentage of overall users

Right. And smaller percentage-wise than the developer-centric places this tends to get used. Still!

[sujato]

This page: https://suttacentral.net/subjects

Oh right, yes, great idea. Maybe we could even have the index entries available via instant search?

Isn't the whole purpose of keyboard shortcuts to be able to do things with the keyboard that can be done other ways by fiddling with a mouse.

Sure. Again, I'm just thinking things through here.

typing part of the name of a feature

Right, hmm. Sounds like this would mesh well with an instant search kind of thing, index say the sutta titles and suggest them. We are hoping to do this with our search upgrade anyway.

[thesunshade]

Sounds like this would mesh well with an instant search kind of thing

In Joplin, the command palette and instant search are the same interface, but they have two shortcut keys. ctrl p for instant search and ctrl shift p for command palette. The only difference is that the command palette searches start with a colon.

[thesunshade]

I'd like to revisit this.

Re-reading from the top it sounds like although the title of the issue is "Keyboard shortcuts," what you are really talking about is a command palette.

Personally I think that hot keys (e.g. pressing v to scroll through the three view options) would be more useful and more understandable. I know not everyone is a dedicated keyboard shortcut user, but the concept is ubiquitous.

A command palette is a much newer thing. Also, I think it is well suited for apps that have hundreds of different commands and the user may not be able to memorize shortcuts for all of them (or even where they sit in a menu structure).

With the help of @buddhist-uni I was able to make a greasemonkey script to add some keyboard shortcuts to toggle the view and main refs. It's amazing and I can't believe I waited so many years to try and do it.

The problem is that with the site's shadow everything it's hard to run my own script. So I'd like for us to try adding a few keybindings to the site itself. I'm not saying that there shouldn't be a command palette as well, but that's going to be much more complicated to implement. Whereas I expect shortcuts for view options should be much easier.

I would suggest three to start:

• v to cycle through the three view options
• m to toggle the main refs on and off
• n to cycle through the three notes options.

What do you think? In order to avoid conflicts with existing shortcuts I suggest not using ctrl or alt with them. I believe that Gmail uses bare key strokes for shortcuts.

[firepick1]

This is a rather large topic, so I'll keep to simple problems and solutions.

Usurping the browsers own hot keys can be quite annoying to end users. I regularly use CTRL-K for the actual browser meaning. When I go to MDN, which has rudely hijacked CTRL-K for its own purposes, I have to hit CTRL-K twice to get bypass the rather annoying MDN override. Hot keys are precious and overriding sometimes frustrates users. When I use SC I either edit the URL bar or click the magnify icon. Because of this, I think the root problem may not be hotkeys...it might be... "let's make search better".

Making search better is difficult. There are a myriad of issues including history, lookahead, special characters, different contexts, etc.

We've recently introduced the Pali card in SC-Voice--it's a fast way to search the DPD Pali dictionary. This new implementation illustrates various solutions to the above problems.

• There is no CTRL-K. The existing convention is the magnify icon. We honor that.
• The context is provided by the Pali card, which is different than the Sutta Search Card. Instead of overloading one Search mechanism, we provide different contexts for search
• The Pali search can search for: accented Pali (saṁvega), unaccented Pali (samvega), and English definitions (sense of urgency)
• The Pali search dropdown menu shows: history, Pali exact matches and next-letter lookahead for Pali words

Sample the above at finding samvega at SC-Voice Best wishes for SC search! :heart:

[thesunshade]

Usurping the browsers own hot keys can be quite annoying to end users.

Did you miss the part where I suggested not usurping? Just using single key presses.

[sujato]

I think we're agreed that any implementation has to be careful not to usurp any hot keys. The first question to answer, then, will be: how do we guarantee that we don't usurp? Is there a best practice in this regard?

Assuming we can settle this, we can then start to ask, what is the simplest thing we can add that will be of most benefit? Start simple and evolve.

[thesunshade]

Maybe I'm not making my suggestion clear.

The hotkeys I am proposing are single letter key presses. No control, no alt. I don't think that outside of function keys (f1, f2, etc) escape, and backspace there are any keys the browser uses, especially not letters.

Edit: here are all of the gmail hotkeys. You can see many of them (e.g p and n for previous and next message) do not use a ctrl/alt combination.

I'm not pointing this out for the sake of not conflicting because these hokeys obviously only work when you have gmail open. Just to show that other sites use hot keys like this.

There just needs to be a test to make sure that the cursor isn't placed in the search field.

[thesunshade]

(sorry Bhante, missed your edit)

As far as the simplest one to implement, I'd say toggling the SC Main refs on and off. I would propose m to do that.

I think changing the root text view is also important, but it would involve deciding if there would be a single key, like v to rotate through all three (my preferred method) or if we should have three, e.g.

• p for plain view
• s for side by side
• l for line by line

I agree with doing something simple first. But we may want to spitball all the things we may want to do in the future just so we don't have to re-do what keys do what.

[firepick1]

I use many apps, so I tend to only care about "universally useful keys", such as the cursor keys or CTRL-K. I don't even remember what all the SC-Voice hot keys are. I therefore plod where others fly on the keyboard. I also understand the need for shortcuts and support them for those who do benefit.

[thesunshade]

I use many apps, so I tend to only care about "universally useful keys", such as the cursor keys or CTRL-K.

Other than cut/copy/paste, I don't think there is a such thing as universal keys. And especially there is no

Are you talking about a shortcut to display all of the shortcut keys in a table?

In some apps ctrl + K (like Discourse, Github, and Wordpress) inserts a linK. In Firefox and Chrome, it takes me to the search bar.

How people discover these shortcuts is indeed an issue. I suggest something like this.

@buddhist-uni ?

[thesunshade]

Here is everything I can think of that would be useful as shortcuts:

Easier to implement

• i to open info panel *
• p to open parallels panel *
• s to open search panel and put cursor there *
• n to toggle three note states
• v to toggle three view states
• h to toggle highlights
• n to select "None" refs
• m to toggle main refs
• c to toggle Chinese lookup
• d to toggle dark theme
• t to toggle toolbar (scroll, fixed, top) *
• x navigate to subject indeX (if we use i to open info)

More complicated

• w to toggle Pali word lookup between "off" and last used dictionary. This would require storing the last used dictionary
• o to open sutta in Voice.* (if v is used for view state). This is a bit more involved because it means openign a ne website. Do we really want a keypress to do that?

Note that this list only includes things that exist on the site currently.

* indicates items that would be difficult to indicate this key in the interface

[sujato]

That's all sounding good.

One thing, perhaps we could include a universal revert mechanism? Say you press a key by accident, something happens, how do you get back? Maybe a toast at the bottom of the page that just says "revert?" with a button, and revert could have its own hotkey.

Regarding hints for display, that sounds good. We should check prior art in this area. In LibreOffice the hotkey hints are in secondary text color, aligned right near the menu item. They don't have to be prominent.

[thesunshade]

One thing, perhaps we could include a universal revert mechanism?

Hmm… Are you suggesting that because I'm proposing bare key presses? Meaning that it's possible someone could press v accidentally? I think an "undo" feature like that would be more important if the keystroke was actually modifying data and not the state of the app. I can say as far as Gmail, I've been using it for almost 20 years and I don't recall tripping one of the keys accidentally. Also, having an undo/revert would dramatically increase the complexity. At least I think the feature could be added later. We have snackbars for most of the view items already. Perhaps an "undo" could be integrated into that existing behaviour.

In LibreOffice the hotkey hints are in secondary text color, aligned right near the menu item.

Of the hotkeys I propose above, only one has a clear position in a menu similar to your LO screen shot. (dark theme toggle). The rest appear in various places in the interface, mostly in the view menu.

I agree they don't need to be prominent. On the other hand if they aren't present enough, then people won't know about them. Not using ctrl/alt solves one problem, but it creates another since when people see Alt+M it's clear this is a shortcut. M doesn't have the same clarity. Since the shortcuts are only applicable on desktop, perhaps if they had a tooltip that would help.

I don't know if you saw my update to the mock-ups above, but changing the color makes them much less prominent.

In any case, we could try implementing a simple one like toggling the main refs without having to add it to the interface just yet.

[sujato]

They could be noted both in the position they occur, and in a special hotkey menu.

As for revert, sure, let's see if there is a need.

[thesunshade]

and in a special hotkey menu.

I was hoping to avoid having to have one more thing that needed to be internationalized, lol. But maybe the existing segments can be recycled.

My coding skills in this situation are mostly dependent on duplicating existing code on the site. Is this something that @HongDa could do for the Main ref's checkbox and then maybe I could try to the the others? I don't know what his schedule is like because of Bilara.

[khemarato]

So, I'm liking the idea of i for opening the Info panel and p for opening the Parallels. In that vein, I think it makes a lot of sense for o to open the view Options (as the o key is typically between the i and the p at the top right of the keyboard).

Then perhaps [ could open Voice?? It might be a bit strange for a key press to open another tab, however Voice is especially for our vision-impaired users, so I think it would be great for Voice to get a keyboard shortcut (so blind users are spared tabbing through to the Voice link). Any thoughts @sujato / @firepick1 / @sabbamitta ? :pray:

[thesunshade]

FYI for those not on a QWERTY keyboard, the [ isn't next to the letter P. Obviously the shortcuts are already Anglo-centric.

If necessary the current v could be changed to A for alignment.

[khemarato]

Hmm... The I O P order and placement seems pretty standard even on German and French etc keyboards. But you're right that [ is only the next in the English QWERTY. So, I'd be open to a different shortcut for Voice.

[sabbamitta]

Then perhaps [ could open Voice??

FYI for those not on a QWERTY keyboard, the [ isn't next to the letter P. Obviously the shortcuts are already Anglo-centric.

Yes, right, [ is not next to the series i o p on a German keyboard. Moreover, having to type it is much more complicated than typing a "normal" letter. If you press that key without any second key, you type "8". If you press that key with "shift", you type "(". In order to get "[" you have to press "AltGr" + that key.

It would be much more intuitive for German users to use "v" for opening Voice, even if that is not a neighbor to i o p; but that's probably already used for something else.

[thesunshade]

but that's probably already used for something else.

It's currently used for switching views on bilara texts. If we are going to change it to Voice I'd say it's better to do it sooner rather than later.

[firepick1]

Voice is a special case not used by most Internet users. For this reason, I suggest a reasonable solution would be to provide for custom shortcuts and let the user decide rather than the developer. Imposing a rule on all people will benefit some but not others. I have recently returned from vacation with relatives who favor laws banning abortion in all cases and I find that quite cruel. At some point rules/shortcuts should provide for individual benefit. Finding that balance is very very hard but important.

[thesunshade]

One of the next steps to take is to find a way to teach the user about the hotkeys. I propose a simple page with a menu item to get there. Like this:

An enhancement might be to have an overlay using k to pop one up. But that alone isn't enough since you would need to tell people about it somewhere.

[khemarato]

provide for custom shortcuts and let the user decide

I agree that customizability is great, but it's orthogonal to the issue at hand as, even with settings, we'd need to provide reasonable defaults. The question here is what those defaults should be (regardless of whether or not we later implement customization).

Voice is a special case not used by most Internet users.

Yes. I guess my question for you, @firepick1, is whether you use the Voice link on the sutta pages and, if so, how difficult is it to navigate to that link using assistive technologies and the way the page is designed right now?

Even though Voice users are a tiny number, if their experience is painful enough, it's worth improving! 💜

[thesunshade]

I've started drafting a hotkeys page legend in this branch:

https://github.com/suttacentral/suttacentral/tree/hotkeys-page

Obviously it needs work.

[khemarato]

hotkeys page legend

Cool! 😎

Why not an overlay?

[thesunshade]

Why not an overlay?

Hmm. Do you mean that the menu item would open an overlay instead of taking to a new page? That makes sense. I guess I just didn't like the burden of both a page and an overlay like we have for the search settings/filters.

[khemarato]

Why does it need a page?

[thesunshade]

Why does it need a page?

It doesn't. That's what I was trying to say. As long as an overlay could be triggered from the menu.

Thinking about it now, I believe the search stuff has its own page is because the top search bar is already an overlay and HongDa didn't want to have two. But you would need to ask him.

[firepick1]

Yes. I guess my question for you, @firepick1, is whether you use the Voice link on the sutta pages and, if so, how difficult is it to navigate to that link using assistive technologies and the way the page is designed right now?

Yes. I sometimes use the link that I can see to get to Voice. But I actually use that link rarely since searching in Voice is easier and faster for me.

SC is really not usable with assistive technologies. Last time we checked there were about 100 tab stops on a single SC page. Basically, SC is nightmare for assisted users. This is why we had to rewrite the UI for Voice, which has a spartan (vs. rich) UI. The very richness of the SC UI hampers assisted users with an overwhelm of nuanced utility.

The Voice links in SC are intended for able users who can see and wish to listen to the suttas. My hypothesis is that users tend to gravitate towards the application that best suits their needs. I use Voice primarily and only use SC for legacy references. That hypothesis suggests that switching applications is rare and that a shortcut for the link would be rarely used. My overall concern is that a proliferation of shortcuts results in a quagmire of complexity maintained in perpetuity. A good example of this quagmire are the customizable key bindings on our computers :scream_cat:. For small brains like mine, a handful of shortcuts is just fine and a customizable shortcut is absolutely wonderful.

[thesunshade]

Why not an overlay?

OK, so I looked at the site again (The same site I have looked at every day for years, lol) and realized that the overlay system we have is tied in with the secondary menu bar. It's not a floating dialog box that can be viewed on every page.

Maybe we could use the new <dialog> html element?

Also, will we also show the menu item for hotkeys on mobile. Doesn't really make sense.

[khemarato]

switching applications is rare and that a shortcut for the link would be rarely used.

Understood and agreed. No Voice shortcut it is, then! 😊

Maybe we could use the new <dialog> html element?

That's what I was thinking! It's closest to the original design @sujato posted above. But maybe that was based on what he thought was easy and not based on what he thought was best? (Bhante? 🙏)

[thesunshade]

Just discovered something odd with the hotkeys. When I go here: https://suttacentral.net/pli-tv-bi-pm/en/brahmali?lang=en&layout=sidebyside&reference=main&notes=asterisk&highlight=false&script=latin#172.1 I see side by side English/Pali and the main refs turned on. Then I press M, but instead of turning off the main refs, it hides the Pali. The toast says "The main reffs are now enabled".

Could this have to do with all of those params being given in the URL? I believe that params in the url override for that page but do not change the user's settings. I hadn't even considered this.

In any case, it's odd that m changes the view.

[khemarato]

Yes, that's correct. When you hit a keyboard shortcut, it switches from using the URL params to using your saved settings. This is the same behavior as when opening the view options.

[thesunshade]

But why would m ever hide the pali?

[khemarato]

I believe, if the URL says to show the Pāli, but your settings say to hide the Pāli. Then tapping m would switch you from URL-settings mode to saved-settings mode, causing the v setting to revert.

[thesunshade]

I'm going to suggest that the key to activate an overlay with all of the hotkeys be k instead of ?. My thinking is that ? requires two keystrokes on most keyboards. Also, indicating it in the interface it is more clear that a K is a keyboard shortcut, and not an icon to be hovered over or clicked on to get more info as is often the case with a ?

[sabbamitta]

Hmm … the "k" is meaningful for English, but not for all languages. For German, the word would be "Tastenkürzel", that could still be imagined with a "k", but I don't know for others.

But that's actually with most things: they are all designed for English speakers, and non-speakers have just to learn the acronyms like vocabulary without understanding what they mean—which is why I hate acronyms, and probably won't ever use most of the hotkeys. I simply keep forgetting the meaning.

[thesunshade]

Yes, short of customizable hotkeys I don't think there is any way around it. And for websites it's really fragile. Several things could mess with your local storage and erase your custom settings. Localizing the hotkeys seems like it could be very complicated.

But I think a lot will depend on how often people use them. For example most people know Ctrl + V will paste, although there is no connection at all with what it does and what it's called. If you are like me and need to toggle between different alignments, V should also stick in the brain. In VSCode, there is a "chord" for save all that is ctrl +k followed by s. I know it because I might need it 20+ times a day.

Or maybe we just need to make a nice printable overlay like we had back in the good old days:

[sabbamitta]

I don't think we could or should localize hotkeys. There will be some people who may use them and others who may not. Keystrokes that I am using many times a day, like CTRL + C and CTRL + V, are of course present in my memory. But in case I decide to fill more stuff into my memory, Pali grammar would perhaps be the more valuable choice (I've now successfully avoided to do this for a number of years …). :shrug:

[thesunshade]

@ihongda has mentioned that he is using Shoelace Components and there is a dialog component.

key	function
s	Open the top search bar
v	Toggle three view states for aligned texts (plain/side by side/line by line)
n	Toggle notes view (on asterisk/side notes/none)
m	Toggle main reference numbers on and off
t	Toggle PTS reference numbers on and off
r	Toggle all reference numbers on and off
i	Open Info panel
o	Open Views panel (aka options)
p	Open Parallel panel
esc	Close all overlays
?	Display this chart of hotkeys

Are we all good with having a link to open this dialog in the main site menu as I mocked up above? Bhante @sujato?

Ven. @khemarato, are you interested in working on this bit? Or guiding me?

[khemarato]

My vote is still to open the dialog with the ? key. It's much easier to remember than a random letter. And there's no reason the <kbd> UI indicator can't have a tooltip as well (in case people do hover over it). And obviously clicking on the ? will open the help dialog... which is exactly what someone clicking on a ? would want.

[thesunshade]

can't have a tooltip as well

In general I'm encouraging against the use of/need for tooltips simply because they then need to be translated/localized.

But I think you make an excellent point that if someone were to click on the ? then they get the dialog. So I'll change that in my table above.

Are you interested/able to start working on the dialog?