"Self documenting" kakrc

Complaints & Improvements
#1

I had an idea recently that I think could potentially help newcomers. What if we provided a heavily documented kakrc that could be easily copied over to the individuals $XDF_CONFIG_HOME/kak/ to jumpstart their own personal configuration.

There is a lot of documentation and tips around user configuration but its kinda scattered in different places. This would allow people to see what options are available, learn about them in one place, and this all happens from within the Kakoune, similar to how people learn vim from vimtutor, where they can get instant feedback (via sourcing). I feel like this method fits neatly in line with the self-documenting principle of Kakoune. There’s also the added side effect that something like this might deter newcomers from copying other configs from around the internet which could have unintended side effects.

This isn’t a completely new idea obviously. A project that takes this approach and does it well is the very popular terminal Alacritty. There is also idiomatic-vimrc, which does a great job of empowering vim users to understand how they can configure their editor.

Ideally, the idiomatic kakrc would be a combination of these two, then all you have to do is let people know about it

Ready to make Kakoune your own?:
cp /path/to/kakoune/contrib/kakrc $XDG_CONFIG_HOME/kak/kakrc

1 Like
#2

There are probably some newcomers who like this approach to configuring but it would mean splitting Kakoune’s documentation further apart between :doc, the Readme, the wiki, and the proposed default config file—basically the opposite of “self-documenting” (generating documentation from source code so that you need to update the documentation only in one place). A better term would be “discoverability”.

In the case of Alacritty, the default config is the documentation. There is no :doc. This makes Alacritty and Kakoune a bit less comparable.

The community article The first two hours of Kakoune in two minutes already provides a well-commented “configuration file to steal from”. However, newcomers do not know this article unless they discovered Kakoune by following a link to this article on Lobsters etc.

1 Like
#3

What about generating a commented out kakrc which enumerated as commented out all of the default options? I kind of like the sshd_config approach.

#4

I think this is a good idea, and I think a lot of people would get use out of it. That said, I don’t think it needs to be in kakoune proper. I think as a community, we have to accept that everything doesn’t need to be included in kakoune proper, we can add value without getting it mainlined.

I say just start it – make a github project for kakoune-config and let people submit PRs with examples of stuff.

1 Like
#5

Doom emacs has its place in the emacs community as a distribution of emacs with a preset config built on top of emacs. Doing a distribution of Kakoune is a reasonable thing to do, but I haven’t needed to do enough to warrant it.

Even with a distribution existing, I think it’s good for vanilla to still be usable, and I think Kakoune is very usable in that regard even if the discoverability could be improved.