Merge remote-tracking branch 'refs/remotes/origin/config-refactor' in…

…to config-refactor

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