From aec4fc426194a255ce7650c9ea592497fd0c973a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 5 Nov 2023 01:00:53 +0000 Subject: [PATCH] chore(build): auto-generate vimdoc --- doc/kitty-scrollback.nvim.txt | 307 ++++++++++++++++------------------ 1 file changed, 145 insertions(+), 162 deletions(-) diff --git a/doc/kitty-scrollback.nvim.txt b/doc/kitty-scrollback.nvim.txt index 5f9f70e9..e99d1998 100644 --- a/doc/kitty-scrollback.nvim.txt +++ b/doc/kitty-scrollback.nvim.txt @@ -1,4 +1,4 @@ -*kitty-scrollback.nvim.txt* For NVIM v0.10+ Last change: 2023 November 04 +*kitty-scrollback.nvim.txt* For NVIM v0.10+ Last change: 2023 November 05 ============================================================================== Table of Contents *kitty-scrollback.nvim-table-of-contents* @@ -29,109 +29,104 @@ commands in Neovim. MIGRATING TO V2.0.0 *kitty-scrollback.nvim-migrating-to-v2.0.0* - `IMPORTANT` v2.0.0 has breaking changes and requires steps to properly migrate - from v1.X.X. - You can ignore this section if you have not previously installed any version of kitty-scrollback.nvim -   - - Migration Steps - - - - - - -> - - If you are using the [packer.nvim](https://github.com/wbthomason/packer.nvim) package manager, then - add the custom `User` event `KittyScrollbackLaunch` as a trigger for lazy loading. See [Installation](#-installation) for additional details. -< + |‼| |IMPORTANT| + v2.0.0 has breaking changes and requires steps to properly migrate from v1.X.X. + You can ignore this section if you have not previously installed any version of + kitty-scrollback.nvim +`-` `Migration Steps` + - If you are using the packer.nvim + package manager, then add the custom `User` event `KittyScrollbackLaunch` as a + trigger for lazy loading. See |kitty-scrollback.nvim-installation| for + additional details. >lua - event = { 'User KittyScrollbackLaunch' } -< - -> - - Regenerate default Kitten mappings and add to `kitty.conf` + event = { 'User KittyScrollbackLaunch' } < + - Regenerate default Kitten mappings and add to `kitty.conf` >sh - nvim --headless +'KittyScrollbackGenerateKittens' +'set nonumber' +'set norelativenumber' +'%print' +'quit!' 2>&1 + nvim --headless +'KittyScrollbackGenerateKittens' +'set nonumber' +'set norelativenumber' +'%print' +'quit!' 2>&1 < - -> - - Remove previous kitty-scrollback.nvim Kitten mappings in `kitty.conf` - - - The default mapping keys changed from `ctrl+shift` to `kitty_mod`. The default values for `kitty_mod` in Kitty is `ctrl+shift`. + - Remove previous kitty-scrollback.nvim Kitten mappings in `kitty.conf` + - The default mapping keys changed from `ctrl+shift` to `kitty_mod`. The default + values for `kitty_mod` in Kitty is `ctrl+shift`. - If you are using the default value for `kitty_mod` of `ctrl+shift`, then no change is needed. - If you are using a different value for `kitty_mod`, then you should correct any potential mapping conflicts that may occur - now that `kitty-scrollback.nvim` is using `kitty_mod`. - - - Migrate any customized configurations to the new format - - When you define your kitty-scrollback.nvim Kitten configuration, do not use `--config-file` `yourconfigfile.lua`. Instead, - move the contents of `yourconfigfile.lua` to an entry in the configuration passed to the kitty-scrollback.nvim setup function. - -< + now that `kitty-scrollback.nvim` is using `kitty_mod`. + - Migrate any customized configurations to the new format + - When you define your kitty-scrollback.nvim Kitten configuration, do not use + `--config-file` `yourconfigfile.lua`. Instead, move the contents of + `yourconfigfile.lua` to an entry in the configuration passed to the + kitty-scrollback.nvim setup function. >lua - require('kitty-scrollback').setup({ - yourconfig = function() - ... - end, - }) + require('kitty-scrollback').setup({ + yourconfig = function() + ... + end, + }) < + Update your Kitten to use the name of the configuration defined in the setup + function. In this example, `--config-file yourconfigfile.lua` changes to + `--config yourconfig` +`-` `Real example` > - Update your Kitten to use the name of the configuration defined in the setup function. In this example, - `--config-file yourconfigfile.lua` changes to `--config yourconfig` -< --Real example - - - `NOTE` The configuration to view the last command output now references a - builtin configuration instead of a file. The new configuration can be viewed by - running `:KittyScrollbackGenerateKittens`. -- Old configuration - - The Kitten defined in `kitty.conf` references the configuration file `get_text_last_cmd_output.lua` - ->kitty - # Browse output of the last shell command in nvim - map kitty_mod+g kitty_scrollback_nvim --config-file get_text_last_cmd_output.lua +> `ℹ` `NOTE` < + ->lua - -- get_text_last_cmd_output.lua - local M = {} - M.config = function() - return { - kitty_get_text = { - extent = 'last_visited_cmd_output', - ansi = true, - }, - } - end - - return M -< - -- New configuration - - The Kitten defined in `kitty.conf` references the builtin configuration name `ksb_builtin_last_cmd_output` - ->kitty - # Browse output of the last shell command in nvim - map kitty_mod+g kitty_scrollback_nvim --config ksb_builtin_last_cmd_output -< +> ->lua - require('kitty-scrollback').setup({ - ksb_builtin_last_cmd_output = function() - return { - kitty_get_text = { - extent = 'last_visited_cmd_output', - ansi = true, - }, - } - end - }) +> The configuration to view the last command output now references a builtin configuration instead of a file. The + +> new configuration can be viewed by running `:KittyScrollbackGenerateKittens`. + + - Old configuration + - The Kitten defined in `kitty.conf` references the configuration file `get_text_last_cmd_output.lua` + + ```kitty + # Browse output of the last shell command in nvim + map kitty_mod+g kitty_scrollback_nvim --config-file get_text_last_cmd_output.lua + ``` + + ```lua + -- get_text_last_cmd_output.lua + local M = {} + M.config = function() + return { + kitty_get_text = { + extent = 'last_visited_cmd_output', + ansi = true, + }, + } + end + + return M + ``` + + - New configuration + The Kitten defined in `kitty.conf` references the builtin configuration name `ksb_builtin_last_cmd_output` + + ```kitty + # Browse output of the last shell command in nvim + map kitty_mod+g kitty_scrollback_nvim --config ksb_builtin_last_cmd_output + ``` + + ```lua + require('kitty-scrollback').setup({ + ksb_builtin_last_cmd_output = function() + return { + kitty_get_text = { + extent = 'last_visited_cmd_output', + ansi = true, + }, + } + end + }) + ``` + < @@ -145,33 +140,30 @@ FEATURES *kitty-scrollback.nvim-features* EXAMPLE USE CASES *kitty-scrollback.nvim-example-use-cases* -- Copy scrollback text to the clipboard - -- Open Kitty’s scrollback history (default mapping ``) -- Search backward for a pattern in Neovim `?{pattern}` -- Enter Visual mode `v` and select desired text -- Copy selection to clipboard (default mapping `y`) -- `kitty-scrollback.nvim` automatically closes and returns to Kitty - -- Modify and execute command - -- Open Kitty’s scrollback history (default mapping ``) -- Copy desired selection to clipboard (e.g., `yy`) - - Alternatively, you could just enter Insert mode (`i` or `a`) to open an empty floating window (similar to `` in Bash) -- `kitty-scrollback.nvim` opens a floating window in Neovim with the contents of the selection -- Modify the content -- Execute the command (default mapping ``) -- `kitty-scrollback.nvim` automatically closes and executes the command in Kitty - -- Modify and paste content - -- Open Kitty’s scrollback history (default mapping ``) -- Copy desired selection to clipboard (e.g., `yy`) -- `kitty-scrollback.nvim` opens a floating window in Neovim with the contents of the selection -- Modify the content - - Note: you can close (default mapping ``) and reopen (yank or enter Insert mode) the floating window multiple times -- Paste the content (default mapping `` or `:w`) -- `kitty-scrollback.nvim` automatically closes and paste the contents in Kitty for further editing +`-` `Copy scrollback text to the clipboard` + - Open Kitty’s scrollback history (default mapping ``) + - Search backward for a pattern in Neovim `?{pattern}` + - Enter Visual mode `v` and select desired text + - Copy selection to clipboard (default mapping `y`) + - `kitty-scrollback.nvim` automatically closes and returns to Kitty + +`-` `Modify and execute command` + - Open Kitty’s scrollback history (default mapping ``) + - Copy desired selection to clipboard (e.g., `yy`) + - Alternatively, you could just enter Insert mode (`i` or `a`) to open an empty floating window (similar to `` in Bash) + - `kitty-scrollback.nvim` opens a floating window in Neovim with the contents of the selection + - Modify the content + - Execute the command (default mapping ``) + - `kitty-scrollback.nvim` automatically closes and executes the command in Kitty + +`-` `Modify and paste content` + - Open Kitty’s scrollback history (default mapping ``) + - Copy desired selection to clipboard (e.g., `yy`) + - `kitty-scrollback.nvim` opens a floating window in Neovim with the contents of the selection + - Modify the content + - Note: you can close (default mapping ``) and reopen (yank or enter Insert mode) the floating window multiple times + - Paste the content (default mapping `` or `:w`) + - `kitty-scrollback.nvim` automatically closes and paste the contents in Kitty for further editing PREREQUISITES *kitty-scrollback.nvim-prerequisites* @@ -190,13 +182,14 @@ command: < - `NOTE` It is good practice to first read the script - + `ℹ` `NOTE` + It is good practice to first read the script + before running `sh -c` directly from the web INSTALLATION *kitty-scrollback.nvim-installation* -- Using lazy.nvim +`-` `Using [lazy.nvim](https://github.com/folke/lazy.nvim)` >lua { @@ -213,7 +206,7 @@ INSTALLATION *kitty-scrollback.nvim-installation* } < -- Using packer.nvim +`-` `Using [packer.nvim](https://github.com/wbthomason/packer.nvim)` >lua use({ @@ -230,7 +223,7 @@ INSTALLATION *kitty-scrollback.nvim-installation* }) < -- Using Neovim’s built-in package support |pack| +`-` `Using Neovim's built-in package support [pack](https://neovim.io/doc/user/usr_05.html#05.4)` >bash mkdir -p "$HOME/.local/share/nvim/site/pack/mikesmithgh/start/" @@ -245,8 +238,9 @@ INSTALLATION *kitty-scrollback.nvim-installation* CONFIGURATION *kitty-scrollback.nvim-configuration* - `NOTE` The Advanced Configuration - + `ℹ` `NOTE` + The Advanced Configuration + section of the Wiki provides detailed demos of each configuration option. KITTY ~ @@ -254,32 +248,31 @@ KITTY ~ The following steps outline how to properly configure kitty.conf -- Enable allow_remote_control - - -- Valid values are `yes`, `socket`, `socket-only` -- If `kitty-scrollback.nvim` is the only application controlling Kitty then `socket-only` is preferred to continue denying TTY requests. - -- Set listen_on to -a Unix socket - -- For example, `listen_on unix:/tmp/kitty` +`-` `Enable + [allow_remote_control](https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.allow_remote_control)` + - Valid values are `yes`, `socket`, `socket-only` + - If `kitty-scrollback.nvim` is the only application controlling Kitty then `socket-only` is preferred to continue denying TTY requests. -- Enable shell_integration - +`-` `Set + [listen_on](https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.listen_on) to a + Unix socket` + - For example, `listen_on unix:/tmp/kitty` -- Set `shell_integration` to `enabled` -- Do not add the option `no-prompt-mark` +`-` `Enable + [shell_integration](https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.shell_integration)` + - Set `shell_integration` to `enabled` + - Do not add the option `no-prompt-mark` -- Add kitty-scrollback.nvim mappings - -- Generate default Kitten mappings and add to `kitty.conf` +`-` `Add kitty-scrollback.nvim mappings` + - Generate default Kitten mappings and add to `kitty.conf` >sh nvim --headless +'KittyScrollbackGenerateKittens' +'set nonumber' +'set norelativenumber' +'%print' +'quit!' 2>&1 < -- Completely close and reopen Kitty- Check the health of kitty-scrollback.nvim +`-` `Completely close and reopen Kitty` + +`-` `Check the health of kitty-scrollback.nvim` >sh nvim +'KittyScrollbackCheckHealth' @@ -287,8 +280,7 @@ a Unix socket - Follow the instructions of any `ERROR` or `WARNINGS` reported during the healthcheck -- Test kitty-scrollback.nvim is working as expected by pressing kitty_mod+h to -open the scrollback buffer in Neovim +`-` `Test kitty-scrollback.nvim is working as expected by pressing kitty_mod+h to open the scrollback buffer in Neovim` `kitty_mod` is a special modifier key alias for default shortcuts. You can change the value of this option to alter all default shortcuts that use @@ -298,7 +290,7 @@ change the value of this option to alter all default shortcuts that use The default value of `kitty_mod` is `ctrl+shift`. In this example, `kitty_mod+h` represents `ctrl+shift+h`. -- See example kitty.conf for reference +`-` `See example kitty.conf for reference` >sh allow_remote_control yes @@ -469,9 +461,6 @@ By default, `kitty-scrollback.nvim` uses Nerd Fonts in the status window. If you would like to use ASCII instead, set the option `status_window.style_simple` to `true`. -- Status window with Nerd Fonts opts.status_window.style_simple = false -- Status window with ASCII text opts.status_window.style_simple = true - COMMANDS AND LUA API *kitty-scrollback.nvim-commands-and-lua-api* @@ -496,33 +485,33 @@ The API is available via the `kitty-scrollback.api` module. e.g., `require('kitty-scrollback.api')` -------------------------------------------------------------------------------------------------------------- - Mapping Default Mode API Description + Mapping Default Mode API Description Mapping --------------------------- ------------ ------- --------------------- --------------------------------------- - (KsbExecuteCmd) n,i execute_command() Execute the contents of the paste +(KsbExecuteCmd) n,i execute_command() Execute the contents of the paste window in Kitty - (KsbPasteCmd) n,i paste_command() Paste the contents of the paste window +(KsbPasteCmd) n,i paste_command() Paste the contents of the paste window to Kitty without executing - (KsbToggleFooter) g? n toggle_footer() Toggle the paste window footer that +(KsbToggleFooter) g? n toggle_footer() Toggle the paste window footer that displays mappings - (KsbCloseOrQuitAll) n close_or_quit_all() If the current buffer is the paste +(KsbCloseOrQuitAll) n close_or_quit_all() If the current buffer is the paste buffer, then close the window. Otherwise quit Neovim - (KsbQuitAll) n,i,t quit_all() Quit Neovim +(KsbQuitAll) n,i,t quit_all() Quit Neovim - (KsbVisualYankLine) Y v Maps to "+Y +(KsbVisualYankLine) Y v Maps to "+Y - (KsbVisualYank) y v Maps to "+y +(KsbVisualYank) y v Maps to "+y - (KsbNormalYankEnd) Y n Maps to "+y$ +(KsbNormalYankEnd) Y n Maps to "+y$ - (KsbNormalYank) y n Maps to "+y +(KsbNormalYank) y n Maps to "+y - (KsbNormalYankLine) yy n Maps to "+yy +(KsbNormalYankLine) yy n Maps to "+yy -------------------------------------------------------------------------------------------------------------- RECOMMENDATIONS *kitty-scrollback.nvim-recommendations* @@ -558,12 +547,6 @@ ALTERNATIVES *kitty-scrollback.nvim-alternatives* - kitty_grab - Keyboard-driven screen grabber for Kitty - kitty-kitten-search - Kitten for the kitty terminal emulator providing live incremental search in the terminal history. -============================================================================== -2. Links *kitty-scrollback.nvim-links* - -1. *style_simple_false*: https://github.com/mikesmithgh/kitty-scrollback.nvim/assets/10135646/662bf132-0b39-4028-b69f-eb85fbb69b60 -2. *style_simple_true*: https://github.com/mikesmithgh/kitty-scrollback.nvim/assets/10135646/c19a1869-e4e4-40fd-b619-fed771d0153f - Generated by panvimdoc vim:tw=78:ts=8:noet:ft=help:norl: