zsh's run-help compatibility?

[numero-744]

TL;DR: adding run-help-<program>() { <program> help $@ } to the generated completion for Zsh could help Zsh users to easily get the help for commands and subcommands.

---

Hello,

Thanks to clap, the completion for rust binaries in Zsh is really good, however I miss a feature: the use of alt-h to show the help.

In Zsh, in emacs mode (I guess really few people use Zsh in vim mode?), the alt-h shortcut is mapped to running run-help <the current command>, which shows a pager with help for the given command. Then, when the user quits the pager, Zsh restores the command with the cursor as is was left.

I love this feature, it is really useful to look for flags, wherever the cursor is in the line. However, it does not work with rust binaries as of now, and I would like to discuss about solutions.

First, a little bit of setup. With tools like OhMyZsh I guess everything is already set up for most users, but for users who use vanilla Zsh with custom configuration like me, or for users who just want to try run-help, here is how to configure it.

• in case Zsh guesses that you prefer vim mode, run bindkey -e to switch to emacs mode.
• unalias run-help, by default it is an alias to man, which is not really helpful.
• autoload -Uz run-help (I'm never sure about the -Uz flags) loads the smarter run-help module, which can do man but also other things.
• Extra: there are extensions for some famous commands, such as autoload -Uz run-help-git so that it detects git sub-commands to show the more specific help.

---

Okay now the proposal.
Assuming that clap generated the help subcommand which can be used as <program> help <remainder of the command>.
Adding support for this program in Zsh is as simple as adding a function to the ~/.zshrc file, for instance: run-help-jj() { jj help $@ }.
Then I can type jj op log… well what is the flag? alt-h. I get the help page and when I quit I get my command back in the prompt.

To me, the question is: should we provide such a command along with the generated completions? This is not exactly a completion, but it is a simple yet useful function for Zsh users.

Other solutions include: let people creating programs document this, or let users who know that they have to add this function add it for each program when they source the generated completion.

What do you think about it? Do you have other suggestions?

[epage]

Can this be included in the completion script (especially the dynamic completion script) or will this require generating another file?

[numero-744]

I think it can be included in the completion script as it should be sourced in the ~/.zshrc file.

For instance with dynamic completion, generating:

#compdef jj
function _clap_dynamic_completer_jj() {
    local _CLAP_COMPLETE_INDEX=$(expr $CURRENT - 1)
    local _CLAP_IFS=$'\n'

    local completions=("${(@f)$( \
        _CLAP_IFS="$_CLAP_IFS" \
        _CLAP_COMPLETE_INDEX="$_CLAP_COMPLETE_INDEX" \
        COMPLETE="zsh" \
        jj -- "${words[@]}" 2>/dev/null \
    )}")

    if [[ -n $completions ]]; then
        _describe 'values' completions
    fi
}

compdef _clap_dynamic_completer_jj jj

function run-help-jj() { jj help $@ }

…should do it

[epage]

So I'm not an expert on completions, especially zsh as I don't use it.

Looking at https://stackoverflow.com/questions/67136714/how-to-properly-install-new-completions-in-zsh, it sounds like our docs suggesting to source into zshrc are incorrect and instead a file is meant to be dropped in a specific location(s?).

Would that affect things?

[numero-744]

Okay so I have tried to proceed this way, and zsh does not see the run-help-jj function in the _jj file in the $fpath variable: the completion works correctly, but not the run-help.

[numero-744]

Assuming that clap generated the help subcommand

This assumption is wrong, for instance rg does not generate a help subcommand. So it should be run-help-rg() { rg --help } instead.

Also, installing the man page instead could be a better option as rg --help does not provide highlighting. run-help would find the man page without configuration.
However, for programs with subcommands, configuring run-help would be better than simply installing the man pages because it would show the man page for the specific subcommand.

On the other side, for jj, the help subcommand provides highlighting which is better than the man page in my opinion…
I am not sure it is possible to generate something which suits all use cases.

Do anyone have insights about this?

[epage]

This assumption is wrong, for instance rg does not generate a help subcommand. So it should be run-help-rg() { rg --help } instead.

We generate a help subcommand if other subcommands are present and if it isn't disabled. This could be detected inside of the generator so it could create either form.