Kakrc to debug

Recipes & Guides
1

I noticed that when I have an error in kakrc, nothing is loaded about it.
So I need to correct it before to have the features come back.
And try again to improve kakrc better.
Is there a way to debug easily ?

2

Usually I test changes in kakrc in another kakoune instance. You can also wrap new changes in try %{} block.

3

Thanks,
Yes , good idea, I will try with second instance first, before to test it.
I m not yet familiar with client concept here described :

I understand that with this command, I can add more kakrc configuration in another file loaded with this command :slight_smile:

try %{ source .kakrc.local }

Could you explain what is doing this IDE command concretely ?:

def ide %{
    rename-client main
    set global jumpclient main

    new rename-client tools
    set global toolsclient tools

    new rename-client docs
    set global docsclient docs
}

What is the improvement for the user of kakoune ?

4

You can have multiple clients (windows / tmux panels / whatever) connected to single kakoune server. They will share options, opened buffers, registers etc. Each client has a “name” - you can see it on modeline

screen-2018-11-30-15-47

In this case I have client named client0 opened. 8967 is server session name (server PID by default).

There are options like docsclient that some Kakoune commands use to determine which client should be used to display docs, tools output etc.

5

I am also curious about what docsclient, jumpclient and toolsclient mean.
Can you think of some examples, because I cannot seem to find any documentation about those options.

One interesting use case would be to have auto completion menu and hover information from LSP in a separate client.

6

docsclient, jumpclient and toolsclient are conventions followed by the plugins that ship with Kakoune. To understand how they work, you need to understand Kakoune clients and sessions.

When you run Kakoune, you’ll see text at the right-hand end of the status-bar like:

client0@[12345]

That means that particular Kakoune instance is the client named client0, and it’s connected to the Kakoune session 12345. If you run a Kakoune command like :new, you’ll see the new client has a different name, but the same session. All the clients connected to a session share the same set of open buffers, the same registers, and the same global hooks and options, but each client has its own “active” buffer, and its own set of selections.

You can pick a session name when you start Kakoune with the -s option (like kak -s mysession), but a client can be renamed at any time with the :rename-client command. The current session and client names are also available via the %val{session} and %val{client} expansions.

docsclient, jumpclient and toolsclient are options that can be set to the name of a client in the current session. For example, if you want your current client to be the docsclient for the current session, you can say:

set global docsclient %val{client}

Now, if you run a command that displays documentation (like :help faq) the documentation should be displayed in the docsclient, regardless of which client you ran the command in. If docsclient isn’t set, documentation commands generally show the documentation in the current client.

The three kinds of client are used for different things:

  • docsclient is used for showing documentation, usually associated with commands like :doc, and :man
  • toolsclient is used to show the output of tools, usually associated with commands like :make, :grep, and :lint
  • jumpclient is used when a command wants to jump to a particular place in a particular file. For example, if you hit Enter on one of the results from :grep, the file will be opened in the jumpclient and scrolled to the appropriate line

I use toolsclient and jumpclient all the time, usually side-by-side: edit a file on the left, hit a key to try compiling or running the tests and have the results show up on the right, then hit Enter on a compilation error or test failure to open the problematic code on the left again. If I need to look at two files (or two parts of the same file) side-by-side, I can still uses the toolsclient for that, but it will automatically go back to displaying test results (or whatever) the next time I need it.

I rarely use docsclient for anything, because so little of the documentation I need is available in a form Kakoune can display. Generally I keep a browser handy with a million tabs open for that kind of thing, anyway.

1 Like
7

Thanks for explaining.
I see now, that I could’ve found this on the wiki:

Somehow, I did not notice the wiki before…