Add key binding descriptions

[carlocab]

These can descriptions can be viewed using <prefix>-? (under the default binding).

[bruno-]

This -N flag is a relatively recent addition being added to tmux 3.1. I think we may have to wait a bit so that we don't break the plugin for users running lower tmux version.

[carlocab]

Sure, no problem. Thanks for having a look!

[bruno-]

I got notified to check this PR. It's been a year since tmux 3.1 is released (Feb 2020), yet I'm still leery on merging this.

Unless there are objections I'd like to wait another 6 months or so. Will set a task for myself to revisit this then.

[carlocab]

Sure, I don't mind waiting. I guess waiting till after the release of 3.2 makes sense too, which, from what I understand, is planned in the next few months.

[jaclu]

In my plugins binding to a key, I have started to read the common variable @use_bind_key_notes_in_plugins If set to 1/Yes/True they will be used. If not set it assumes not to use -N, so safe for older versions of tmux and for users unaware of this feature.

A code fragment from jaclu/tmux-menus to show how I use it:

if bool_param "$(get_tmux_option "@use_bind_key_notes_in_plugins" "No")"; then
    use_notes=1
else
    use_notes=0
fi
log_it "use_notes=[$use_notes]"

if [ "$use_notes" -eq 1 ]; then
    tmux bind -N "$plugin_name" "$trigger_key" run-shell "$MENUS_DIR"/main.sh
else
    tmux bind "$trigger_key" run-shell "$MENUS_DIR"/main.sh
fi
log_it "Menus bound to: <prefix> $trigger_key"

#
#  Aargh in shell boolean true is 0, but to make the boolean parameters
#  more relatable for users 1 is yes and 0 is no, so we need to switch
#  them here in order for an assignment to follow boolean logic in caller
#
bool_param() {
    case "$1" in

        "0") return 1 ;;

        "1") return 0 ;;

        "yes" | "Yes" | "YES" | "true" | "True" | "TRUE" )
            #  Be a nice guy and accept some common positives
            log_it "Converted incorrect positive [$1] to 0"
            return 0
            ;;

        "no" | "No" | "NO" | "false" | "False" | "FALSE" )
            #  Be a nice guy and accept some common negatives
            log_it "Converted incorrect negative [$1] to 1"
            return 1
            ;;

        *)
            log_it "Invalid parameter bool_param($1)"
            error_msg "bool_param($1) - should be 0 or 1"
            ;;

    esac
    return 1 # default to False
}

[eggbean]

This -N flag is a relatively recent addition being added to tmux 3.1. I think we may have to wait a bit so that we don't break the plugin for users running lower tmux version.

I have recently found out that there's a safe way of doing this:

It is possible to add the note after the binding. This would fail in tmux < 3.2, but the binding will still work.

eg. Instead of...

tmux bind-key -N 'Install tpm-managed plugins' "$install_key" run-shell "$BINDINGS_DIR/install_plugins"

do...

tmux bind-key "$install_key" run-shell "$BINDINGS_DIR/install_plugins"
tmux bind-key -N 'Install tpm-managed plugins' "$install_key"

@carlocab If you make these changes there wouldn't be any reason for this PR to be not accepted, finally.

[carlocab]

Thanks for the suggestion @eggbean! Apologies that it took me so long to get around to updating this.

@bruno-, I'd appreciate if you took another look.

Also, for anyone still interested in what version of tmux most people still have:

tmux packaging status

[](https://repology.org/project/tmux/versions)

[jaclu]

Nice list @carlocab!

I use ASDF and have all tmux versions since 0.7 installed, letting you instantly switch which one to use. It is really convenient when you are doing tmux-plugins, both to see under what versions your plugin works and a practical way to see if simple fixes can make them work under other versions.