Search-doc.kak - Exploring kakoune documentation more conveniently

Plugins
1

Hello,

I have been a kakoune user for years, but now I am releasing a plugin for the first time!

The plugin is called search-doc.kak and it helps navigate to specific pieces of kakoune documentation faster than the built in :doc command. By pieces I mean specific kakoune commands, options, values, expansions, topics.

The plugin is used by via the command :search-doc <topic>, which works similarly to the :doc command in that it jumps to a piece of kakoune documentation. The difference is that ‘:search-doc’ accepts a single argument <topic> that specifies the piece in more detail than the two arguments of :doc. This specificity is particularly beneficial, since search-doc provides extensive argument completion.

Here is a screenshot from an example where I was searching for documentation on Kakoune keys that include {:

screenshot
screenshot1585×799 73.6 KB

I have found the plugin useful despite its simplicity, and I hope that someone else finds it useful as well.

Let me know what you think.

5 Likes
2

For the Ruby part, you can use 'EOF' (including the quotes), so you are more free about the characters in the program.

ruby - a b c <<'EOF'
  …
EOF
3

Thanks for the Ruby tip. I looked at my code again to apply the tip, but I realized that I am currently piping other things to the standard input of ruby already. That is, I have:

<one-command-here> ... | ruby -e '<ruby-script-here>'

Thus a here document (<<') is not easy to use there for passing the ruby script.

Since there is only one single quote in the script that needs quoting, its okay for now. Currently I use '"'"' to represent the single quote within the single quoted ruby script. Moreover, the single quote is within double quotes in the script, so the combined result is "'"'"'", which is a bit funny but it works :slight_smile:

4

It could make sense to generate the candidates only once and pass the candidates to display with printf.

define-command search-doc -params 1 -shell-script-candidates %opt{search_doc_completion} %{
  …
}

You can find an example implementation in chronic.kak.

1 Like
5

grep -P is not available on Darwin so a quick workaround did the trick:
declare-option str search_doc_command "ag --only-matching --recurse --all-text"

ag
the_silver_searcher

And good as gold. Thanks greet tool Jori.

6

Precomputing candidates is a good idea. Thanks for the pointer to chronic.kak also.

There is a trade-off between precomputing candidates and computing them on-demand. Precomputation increases start up time and on-demand computation causes a tiny delay whenever the candidates are shown.

To overcome this trade-off to some extent, I updated search-doc.kak to use a hybrid approach between precomputation and on-demand computation. The hybrid approach uses on-demand computation on the first time the search-doc command is called. On that first call, the command redefines itself to use cached candidates on any future calls. This way there is the same tiny delay as before on the first call and no delay on future calls.

It took a bit of tinkering to get it working, and it is a bit complicated, but now it seems to work :slight_smile:

For this plugin the difference in responsiveness is quite minimal, but for some more complicated command with more expensive candidate computations, the difference might be meaningful.

7

Thanks! I am glad you like the plugin duncan.

I updated search-doc.kak to use ag the way you suggested if ag is available, and to use grep as before otherwise.

8

Great now I can plug.kak on updates, thank you very much Jori.