Kakscript for the first time is hard, documenting my journey

Resources
4

This is really well-written and comprehensive! Good work! I do have some notes, however.

Under “How Kakoune loads configuration”, the text kind of implies without stating outright that Kakoune will load the standard library then load user configuration. This is generally true, but a bit misleading. If you look at the standard kakrc file the process runs like this:

  • Load everything from the user’s autoload directory
  • If and only if that doesn’t exist, load everything from the system autoload directory
  • Load the per-system kakrc.local file
  • Load the user’s kakrc

One of the most common questions we get from new users is “I installed a plugin and now my syntax highlighting stopped working”, because they created the autoload directory to put the plugin into, and that disabled loading of the standard library. I think it’s worth calling out this quirk for prospective new users.

In “A Better Way: Store State First”, the example uses $kak_client_list to get a list from Kakoune into the shell, and later $kak_quoted_reg_c to get another list from Kakoune into the shell, but you don’t describe the difference between those two, or how to distinguish one from the other. It might be worth having an earlier section about communication between Kakoune and the shell, to cover *_quoted_* expansions, and Kakoune-quoting in shell.

In “Use Kakoune Quotes in Shell Blocks When Possible”, it suggests that Kakoune always provides handy environment variables like $kak_client or $kak_opt_filetype to shell blocks. This is not true! Kakoune only exports environment variables mentioned in the text of the block or (in recent versions) in command-line arguments.

So:

echo %sh{ env | grep kak_ }

…will print nothing, but:

echo %sh{ env | grep kak_ # kak_client }

…will print the name of the current client, and so will:

def -params 1 checkvars %{ echo %sh{ env | grep kak_ } }
checkvars kak_client

There’s scope for a follow-up post with advanced topics like $kak_command_fifo, but since this is just focussing on the layers of evaluation and expansion, that’s fine — you address those topics well.

1 Like