From 8ff1048193a59cfca879ea527bdaacd01d6fd699 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 27 Jan 2024 02:59:46 +0000 Subject: [PATCH] chore(build): auto-generate vimdoc --- doc/kitty-scrollback.nvim.txt | 126 ++++++++++++++++++++++++++++++++-- 1 file changed, 122 insertions(+), 4 deletions(-) diff --git a/doc/kitty-scrollback.nvim.txt b/doc/kitty-scrollback.nvim.txt index 09d5b88e..e9d47a2f 100644 --- a/doc/kitty-scrollback.nvim.txt +++ b/doc/kitty-scrollback.nvim.txt @@ -362,12 +362,130 @@ key matches a builtin name (prefixed with `ksb_builtin_`) then the configuration will be merged with the builtin configuration. All of the builtin configurations are defined in lua/kitty-scrollback/configs/builtin.lua <./lua/kitty-scrollback/configs/builtin.lua>. The user defined configuration -with take precedence and override any fields that are defined in both the +will take precedence and override any fields that are defined in both the builtin and user defined configuration. -- TODO: defined a builtin config and provide an example of referencing it -- TODO: describe the format of the global config and provide an example -- TODO: provide details on config precedence `default_opts > global_opts > builtin_opts > user_opts` and provide an example +Having the ability to merge a user defined configuration with the builtin in +configuration is useful for scenarios that you wish to keep the default kitten +mappings generated by the `:KittyScrollbackGenerateKittens` command. + +For example, imagine a scenario where you wish to modify the configuration for +the `ksb_builtin_get_text_all` but do not wish to provide you own configuration +name `myconfig` and have to update the reference in `kitty.conf` to `map +kitty_mod+h kitty_scrollback_nvim --config myconfig`. In this scenario, the +default mapping is defined in `kitty.conf` as + +> + map kitty_mod+h kitty_scrollback_nvim +< + + + `ℹ` `NOTE` + When no explicit configuration is passed to `kitty_scrollback_nvim`, the config + `ksb_builtin_get_text_all` is used. Effectively, the command becomes `map + kitty_mod+h kitty_scrollback_nvim --config ksb_builtin_get_text_all` +You can achieve this by creating a user defined configuration with the key +`ksb_builtin_get_text_all` as follows. + +>lua + ksb_builtin_get_text_all = { + kitty_get_text = { + ansi = false, + }, + } +< + +The builtin configuration for `ksb_builtin_get_text_all` is + +>lua + ksb_builtin_get_text_all = { + kitty_get_text = { + extent = 'all', + }, + }, +< + +The user and builtin configurations will be merged resulting in + +>lua + ksb_builtin_get_text_all = { + kitty_get_text = { + ansi = false, + extent = 'all', + }, + }, +< + +This approach can be used to modify the builtin configuration (e.g., +`ksb_builtin_get_text_all`, `ksb_builtin_last_cmd_output`, and +`ksb_builtin_last_visited_cmd_output`). But, if you have a common configuration +that you wish to have applied to all of configurations, then it is better to +use a global configuration. + +So far, all entries in the options table have been in the form a key/value pair +where the key is a `string` representing the name of the configuration. There +is an additional reserved entry for the global configuration which is the first +element of the options table without a key (technically the key is `1` but it +does not have to be defined). + +If you would like to provide a global configuration to automatically hide the +status window, this can be achieved as follows. Notice the first entry in the +options table does not define a key, this will be considered global options and +applied to all builtin and user defined configurations. + +>lua + require('kitty-scrollback').setup({ + -- global configuration + { + status_window = { + autoclose = true, + }, + }, + -- builtin configuration override + ksb_builtin_get_text_all = { + kitty_get_text = { + ansi = false, + }, + }, + -- user defined configuration table + myconfig = { + kitty_get_text = { + ansi = false, + }, + } + -- user defined configuration function + myfnconfig = function(kitty_data) + return { + kitty_get_text = { + extent = (kitty_data.scrolled_by > kitty_data.lines) and 'all' or 'screen', + }, + } + end, + }) +< + +The configuration precedence is `default > global > builtin > user` where +`default` has the lowest and `user` has the highest precedence. + +To summarize, - `default` is the standard options defined by +kitty-scrollback.nvim and can be found in the file +lua/kitty-scrollback/configs/defaults.lua +<./lua/kitty-scrollback/configs/defaults.lua>. - `global` is global options +that apply to all `builtin` and `user` defined configurations. The first +element in the options table without a key is considered the `global` options. +- `builtin` is the options defined by kitty-scrollback.nvim for each +`kitty_scrollback_nvim` kitten command generated by +`:KittyScrollbackGenerateKittens` (e.g., `ksb_builtin_get_text_all`, +`ksb_builtin_last_cmd_output`, and `ksb_builtin_last_visited_cmd_output`). The +builtin options can be found in the file +lua/kitty-scrollback/configs/builtin.lua +<./lua/kitty-scrollback/configs/builtin.lua>. - `user` is the options defined +by the user in the options table with a `string` name that is referenced in +`kitty.conf` using the `--config` flag when defining a mapping for the +`kitty_scrollback_nvim` kitten (e.g., `map kitty_mod+h kitty_scrollback_nvim +--config myconfig`). User defined options can be any `string` and will merge +with `builtin` options if they share the same key such as +`ksb_builtin_get_text_all`. ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Options Type Description