Feature Request: Keyboard shortcuts

[mevanlc]

A few more site-native keyboard shortcuts would be appreciated! We are vim users after all!
I wrote the following userscript, the functionality of which you might consider for addition to the site natively. Sorry about the jQuery, I was in a rush!

// ==UserScript==
// @name         vimhelp.org search keyboard shortcuts
// @namespace    http://tampermonkey.net/
// @version      2024-01-02
// @description  '/' = keyword search, '?' = site search
// @author       Anonymous
// @match        https://vimhelp.org/*
// @require      https://code.jquery.com/jquery-3.7.1.slim.js
// @sandbox      JavaScript
// ==/UserScript==

(function () {
    'use strict';
    $(document).keydown(function (e) {
        var ele = document.activeElement;
        var eleIsEditable = ele.tagName === 'INPUT' ||
            ele.tagName === 'TEXTAREA' ||
            ele.tagName === 'SELECT' ||
            ele.isContentEditable;
        if (eleIsEditable) {
            return;
        }
        if (e.key === '/') {
            e.preventDefault();
            $('html, body').scrollTop(0);
            $('#vh-select-tag-ts-control').focus();
        } else if (e.key === '?') {
            e.preventDefault();
            $('html, body').scrollTop(0);
            $('#vh-srch-input').focus();
        }
    });
})();

[c4rlo]

Thanks for the suggestion, it's a nice idea.

I've now implemented it in 85a141b481f89db379c405922a11bf4f3c74fb13. It's live now, try it! It uses 'k' to focus the "Go to keyword" input and 's' to focus the "Site search" input. I'm hoping those keys are reasonable. I don't feel '/' and '?' are quite right; also, browsers sometimes already use '/' for a quick search (my Firefox does).

One thing still to do is to provide some kind of hint for these shortcuts; maybe some small text under each input box…

[mevanlc]

That's awesome c4rlo, thanks! I forgot about Firefox's quick search -- good catch.

I tried playing around with CSS to make a keyboard-looking key icon next to the input fields, but the line height is small enough that I didn't think that it was obvious what the hints meant. However, with a mouse hover tip, I think it might be clear enough.

But, then I went down a rabbit hole of making a modal keyboard help dialog (kind of like github has -- try clicking outside an input field and type ?). Have a look:

https://mevanlc.github.io/prototype-vimhelp/
https://github.com/mevanlc/prototype-vimhelp/

There are no vim help docs on that prototype -- I just cherrypicked the sections of code I was interested in changing. This is kind of a Big Change to vimhelp's (appreciated) minimal UI, so no hard feelings if you don't think this approach is a good fit. Anyway, feel free to grab the code as-is, or I could try to make a PR.

If you'd like to see a mockup for different presentations (like the inline mini keys + hover tip), let me know, I can put something together.

I used the dark/light theme CSS vars, but the --bg and --fg CSS vars aren't really setup to track "highlight" vs. "shadow", so I'm a little dissatisfied with how it looks under the light theme. With keyboard icons the "cap" of the key is supposed to look lighter than the shadowed border, but I gave up trying to find two CSS color vars where one is lighter than the other && that relationship stays when switching themes. I might have given up too early, but... it is what it is at this point.

Anyway, trying too hard to make the keys look skeuomorphic might be too much. I'm thinking I prefer github's more minimal presentation, which I might try emulating more closely.

[c4rlo]

Nice, thanks for that prototype! I think it's definitely a feasible option.

I have experimented with an inline hint as an alternative – this is now up at https://staging.vimhelp.org/ (sources are in the kbd-hints branch).

I'm not totally convinced by it though; the 'k'/'s' buttons look too much like a button you are supposed to click…

Also, your proposal has the advantage that if we ever add more keyboard shortcuts, perhaps for things where adding inline hints is even harder, it provides an easy solution. So I might go with that one…

[c4rlo]

Okay, I have now implemented something very close to your prototype. This is now live at https://staging.vimhelp.org/ (thereby overwriting my earlier design above, sorry; try shift-reload if it's broken). Sources are in the help-dialog branch. I hope the blur effect isn't too offensive, not sure how I feel about it myself.

I'll still tweak it a bit, notably ensuring graceful behaviour if <dialog> isn't supported or if JavaScript is disabled, and also disabling the whole thing if the client does not have a physical keyboard (not sure if I can properly test for that or need to do user agent sniffing).

Note to self: another thing that needs fixing is that on pages other than help.txt.html, the theme button is now misaligned with the search entries.

[mevanlc]

I had a chance to see both variations, and I think they both look great. With only two keyboard shortcuts, I think the field-overlay makes more sense. The blur looks good to my eyes. I might dial it down by 25%.

I did have a vague idea of prototyping more keyboard shortcuts for vimhelp.org. Personally I might use a few marks commands if they were available. If I'm reading a few sections of a large(r) help file, it might be useful. ma, mb, mc, etc, then [' or ]' to jump between them, and of course 'a to jump to a specific one, for example. Cross-file marks could be supported too. Marks could be persisted in the browser's localStorage. And a few ex commands might be fun, :marks, :hardcopy ..., and perhaps a few easter-egg commands for the curious (who knows what :q might do, hehe).

:g/pattern (with results in a popup window that can be clicked to jump you to the matching line, and probably a little more context info than vim would give you, like the section the line was found in or something).

The drop accent on the keyboard-key CSS should probably be under the key, since most people sit in front of their keyboard, not behind it 🙃, and that is the perspective one's brain maps to.

Since Chromium-derived browsers do not have Firefox's quick search feature, it might be nice if / (or whatever key) replicated that for those browsers.

The tag stack is pretty useful when using vim's in-built help. ^o - jump backwards, ^t - jump forwards. :tags - see where you've been. But, that might be overkill.

[c4rlo]

Hey, thanks for all the ideas, good food for thought :)

Can you clarify what you mean by "the drop accent on the keyboard-key CSS"? Are you saying the shadows look wrong to you?

Meanwhile, I've decided to go back to the inline hint approach: https://staging.vimhelp.org/. (Tag search behaviour is slightly off, will look into.) I'm planning to polish that a bit and go with that.

[c4rlo]

This is now live on https://vimhelp.org (and pushed to master). Tested in Firefox, Chromium and iOS Safari. Tested with JavaScript disabled. Mobile browsers don't get the keyboard shortcut hints.

[mevanlc]

Awesome! Thanks! I was just confused about the key shadow effect. After I zoomed in a smidge, I realized I was misinterpreting what I was seeing. I wonder if https://macvim.org/docs/ will merge. :)

[c4rlo]

Cool. Interesting about the macvim docs, I recall this came up in #22 but didn't realise this was a thing now, nice.