Helpbar improvements (configurable hints and key sorting)

[andrei-a-papou]

First off, I think the initial Helpbar is great and it shows the right kind of information to help newcomers learn the most important actions/commands/keybindings.

But as you keep working with pter and start using other features and/or adjusting keybindings to fit your workflow, you want a different set of hints to be visible. For me, this is for two reasons:

1. Learn new actions (e.g. I already know ? is help and q is for quitting, but I need a reminder that F12 is for opening todo.txt in external editor)
2. Learn new keys (often in addition to default ones)

Here's what I'm proposing:

1. Allow configuring the list of actions in Helpbar, falling back to the current defaults. In the config, this could be a newline-separated list (like with Include directive).
2. Show Helpbar keys in the order specified in the config file. Let's say I want a F4 to act as e -- to edit a task. And I want both the bindings to work. Currently, the Helpbar will only show me the e-binding (which is the default and which I already know), as it seems to sort in alphabetical order. It would be great if, say, config file order was preserved. Or maybe the Helpbar could always show the custom keybindings first.

[vonshednob]

I like that! It's like a customizable cheat-sheet for pter, but inside pter.

[andrei-a-papou]

Speaking of cheat sheets, perhaps it'd be helpful to add a CLI param to dump the Help screen to stdout (only without the section titles). Something like what tmux list-keys does.

With tmux, I feed its output to rofi (with some simple parsing), which gives me a searchable cheat sheet for all keybindings: https://i.imgur.com/AMuIf4R.png

A possible format (fields separated by tabs, spaces are just for readability here):

Create task \t create-task \t n
Create task \t create-task \t <f2>
Edit task \t edit-task \t e
Edit task \t edit-task \t <f4>

[vonshednob]

Oh, that's a good one! Does this this work? Or should the sections still have headers and be more clearly separated?

Edit: ah, too early; didn't follow your suggestion and just started hacking. And then of course even forgot to add the new file 🤦 Anyway, should work now.

[andrei-a-papou]

Works great, except we need to strip the trailing \r from output :) Otherwise less and other CLI tools go crazy.

In terms of columns/sections/etc, I think the output format is perfect for now. Let me play with it for a while and get back to you if I have any improvement ideas!

[andrei-a-papou]

With a bit of scripting, I now have a rofi-based cheat sheet for pter, awesome! https://i.imgur.com/cW1wG0b.png

[vonshednob]

Have a look at this commit; does this solve the problem with the trailing newline?

[andrei-a-papou]

Tested, problem solved, thank you!

[andrei-a-papou]

@vonshednob The external cheat sheet works well, but I think it would still be useful to implement 1) and 2) from the original comment. Or at least implement 1) (configurable Helpbar).

It's still faster to quickly glance at your Helpbar as opposed to switching contexts to an external cheat sheet. I think these features complement rather than replace each other. What do you say?

P.S. It's by no means a blocker, so I'm all for removing the 3.16 milestone tag but keeping this issue open for the future.

[vonshednob]

Dang, no you’re right! I missed that these two had been part of this issue! I want these to be in 3.16.

[vonshednob]

Showing user-defined keybindings first was easier than expected.

[andrei-a-papou]

The new code grabs the first custom keybinding from user config, perfect!

But can pter filter out default keybindings ONLY if they are not set in the user config?

That way, if a user needs a hint for a default keybinding, they can set it explicitly before other user-defined ones in the configuration file.

[vonshednob]

Hm, I’d rather not have all keybindings vanish just because a user has modified one keybinding. Most users will not do any changes in the configuration except the one thing that really bugs them.

Maybe a configuration option to only show custom keybindings in the help bar? 🤔

[andrei-a-papou]

So if I set something like help-custom-keys-only to yes, pter would (A) only show an action in Helpbar for which a custom keybinding has been defined? Or (B), pter would alternatively show a default keybinding for a Helpbar action for which no custom keybinding has been defined?

(A) + (B) would be ideal, but even (A) alone would be great. My use case is probably not the commonest one, so I don't mind defining all the keybindings explicitly if needed.

(I'm assuming the Helpbar would still use the first user-defined keybinding, as in the current git HEAD.)

[vonshednob]

Let’s pin examples to this, because it becomes a bit tricky 😅

Let’s take the two actions jump-to and edit-task. Default binding is : and e.

Right now if a user sets a new keybinding, e.g. ^G to jump-to, the help bar would show [^G] jump-to and [e] edit task. That’s option (B), if I get you right?
I can imagine a configuration option help-shows that can be set to prefer-custom (which is this described behaviour).

If help-shows is set to only-custom, in this example the help bar would only show [^G] jump-to.

The real tricky problem (and I do not see how I could solve that easily) is what happens if the user writes in their configuration file e = edit-note. Technically that’s a custom key binding, but it matches the default. So it’s not a change. But it is a custom thing 😩

[andrei-a-papou]

Examples are helpful. yes! So let me back up and explain one of my use cases properly. I don't think I've done that well.

I write todos and notes in several languages, e.g. in English and German. Here's a sample German keyboard layout:

Note for example the : key. It's in a different spot compared to the US English layout. Where the US layout has a colon, the German one has ä.

Here comes the important part: For productivity, it's critical to be able to use a single-key binding and not think of the keyboard layout! Pter has amazing keyboard support, so it lets me create multiple sets of keybindings:

<colon> = jump-to
ä  = jump-to

So far so good. I can hit the same physical key and call the right action regardless of layout.

Now, which key hint should be shown in the Helpbar? To my mind, pter should always prefer a custom keybinding over the default one. If a user sets a keybinding, they must prefer it!

In addition (and this is the tricky part you referred to earlier), the user-set keybinding should be shown even if it matches the default one.

In my example above, German is a secondary language and I don't always remember where ä is. If I think "colon", my fingers jump to the right key in the English layout, but not necessarily in German. So the Helpbar should pick up <colon> = jump-to (because it comes first in my config and I put it there for a reason) and show : Jump to item. If I change the order of bindings in the config, the Helpbar should always pick the first user-defined one.

So to summarize, the behavior I would call ideal is this:

1. The Helpbar actions are defined by help-actions -- ☑️ done
2. If no help-actions are set by user, fall back to default actions -- ☑️ done
3. If there's a user-set keybinding for the action, the Helpbar should always prefer it -- whatever it is, even if it looks the same as the default one -- ❗ partially done, key hint for a custom binding is currently being removed if it matches the default
4. If there are multiple user-set keybindings for an action, show the first one in Helpbar -- ☑️ done
5. If there's no user-set keybinding for an action, show the default binding hint -- ☑️ done
6. If there's no user-set OR default keybinding for an action, don't show the action -- ☑️ done

Currently, pter mostly works as expected, but because of item number 3 I'm getting ä Jump to item in my Helpbar, which is NOT helpful at all 😆 So I put together an ugly local workaround patch to get the old behavior back, hopefully temporarily :)

Maybe a configuration option to only show custom keybindings in the help bar?

I think I may have misunderstood this idea originally. Right now I don't see the need for this option, but if a separate config option would help get the "arguably ideal behavior" above, I'm all for it!

[andrei-a-papou]

For the record, I'm attaching the quick and dirty patch I'm using that seems to get the job done. It only deals with task list keybindings for now, though.

90-user-keys-helpbar.diff.gz

[vonshednob]

I could have sworn : was at ö, but it’s been a while!

On topic though I’m afraid to keep track of which user-defined key binding is the first (and for that matter whether a keybinding is user-defined, even if it is the same as the default) is not easily fixable without breaking corner cases (mainly because the keybindings are a dictionary, so bindings are there or they are not…). Or, well, like you did, with lots of duplication of information.

I’m not sure how to solve this cleanly yet. 🤔 Gotta give it a bit more time to mull it over.

If I can’t come up with a good solution until tomorrow, I’ll just take your fix 🤷

[andrei-a-papou]

Yeah, I thought about changing the data structure for the bindings, but the change seemed too invasive and frankly I don't know the codebase well enough not to introduce new bugs... Also perhaps pter needs a unit test for the keybindings feature as it's become more complex.

[vonshednob]

I had the same idea about the changed data structure for keybindings, but it feels a bit like confusing the purposes too much.

The unit tests for the keybindings is a good idea; just really tricky with them being so tightly integrated into the user interface. Some refactoring would do the code a lot of good, but who has the time?

[andrei-a-papou]

In terms of refactoring, do you prefer any kind of code style? Maybe introducing the black linter would be a baby step in the right direction that wouldn't take a lot of time. With black, all code from all PRs/contributions would always be formatted the same.

I don't have a meaningful Python IDE configured right now (working on it) but I remember using black in the past and it helped refactoring and collaboration.

[vonshednob]

Yeah, I totally use an IDE and not just two terminals in a trenchcoat 😅

No idea what black is, but I mostly just try to follow the usual PIP style and try to keep the lines shorter than 120 character 🤷 .
Unfortunately pter grew very quickly in the beginning and could have used some more following these rules and: decluttering. Like moving all actions into classes with an execute function that tasks a task. Or decoupling the UI from the curses screens to make a transition to some other terminal driver easier.

[andrei-a-papou]

Black is opinionated, but I did like it: https://github.com/psf/black

Yeah, I totally use an IDE and not just two terminals in a trenchcoat

Good for you, I'm using nano right now, I need to stop! :)

[vonshednob]

nano isn't bad. It's vim on my side, so pretty much the same just with more sunk-cost-fallacy attached 🤷