From 930001c626f85c0c117778423606b953d241309f Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Thu, 5 Jan 2017 11:28:22 +0000 Subject: [PATCH] Rework Kakoune configuration loading documentation Fixes #1063 --- README.asciidoc | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 1dd5d14a..f69edc84 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -244,18 +244,36 @@ Just running *kak* launch a new kak session with a client on local terminal. * `-clear`: clear dead sessions socket files * `-ro`: prevent modifications to all buffers from being saved to disk -At startup, if `-n` is not specified, Kakoune will try to source the file -`../share/kak/kakrc` relative to the kak binary. This kak file will then try -to recursively source any files in `$XDG_CONFIG_HOME/kak/autoload` (with -`$XDG_CONFIG_HOME` defaulting to `$HOME/.config`, and falling back to -`../share/kak/autoload/` if that autoload directory does not exists), then -`../share/kak/kakrc.local` if it exists, and finally `$XDG_CONFIG_HOME/kak/kakrc`. +Configuration +^^^^^^^^^^^^^ -That leads to the following behaviour: by default, with no user autoload -directory, the system wide autoload directory is used, once the user wants -control on autoloading, they can create an autoload directory and eventually -symlink individual scripts, or the whole system wide autoload directory. They -can as well add any new scripts not provided with Kakoune. +There are two directories containing Kakoune's scripts: + +* `runtime`: located in `../share/kak/` relative to the `kak` binary + contains the system scripts, installed with Kakoune. +* `userconf`: located in `$XDG_CONFIG_HOME/kak/`, which defaults + to `$HOME/.config/kak/` on most systems, containing the user + configuration. + +When `-n` is not specified, Kakoune will load its startup script located +at `${runtime}/kakrc` relative to the `kak` binary. This startup script +is responsible for loading the user configuration. + +First, Kakoune will search recursively for `.kak` files in the `autoload` +directory. It will first look for an `autoload` directory at +`${userconf}/autoload` and will fallback to `${runtime}/autoload` if +it does not exists. + +Once all those files are loaded, Kakoune will try to source +`${runtime}/kakrc.local` which is expected to contain distribution provided +configuration. + +And finally, the user configuration will be loaded from `${userconf}/kakrc`. + +NOTE: If you create a user `autoload` directory in `${userconf}/autoload`, +the system one at `${runtime}/autoload` will not be loaded anymore. You can +add a symbolic link to it (or to individual scripts) inside +`${userconf}/autoload` to keep loading system scripts. Basic Interaction -----------------