From 83211279c8f1066857ee7b630b03cc5e09a60e7a Mon Sep 17 00:00:00 2001 From: Andre Ramnitz Date: Mon, 11 Nov 2024 23:37:03 +0100 Subject: [PATCH] banners: update kak banner --- banner-kak.asc | 663 +++++++++++++++---------------------------------- 1 file changed, 200 insertions(+), 463 deletions(-) diff --git a/banner-kak.asc b/banner-kak.asc index ffa2ed74..180108bb 100644 --- a/banner-kak.asc +++ b/banner-kak.asc @@ -1,463 +1,200 @@ -+=----------------------------------------------------------------------------=+ - _ _ - | | | | - | | __ __ _ | | __ ___ _ _ _ __ ___ - | |/ / / _` | | |/ / / _ \ | | | | | '_ \ / _ \ - | < | (_| | | < | (_) | | |_| | | | | | | __/ - |_|\_\ \__,_| |_|\_\ \___/ \__,_| |_| |_| \___| - - Mawww's experiment for a better code editor -+=----------------------------------------------------------------------------=+ - -This walk-through is an introduction to Kakoune's basic editing capabilities -to help new users transition over easily from another editor, or simply -learn how to write and edit documents with style. - -During the learning period, it is useful to activate an automatically displayed -contextual help for commands in normal mode: `:set -add global autoinfo normal` - -In the first section, you will learn about the primitives of the editing -language to be able to get to a level of knowledge of the editor that -guarantees that you can work with it efficiently. - -In the second section, for users who've gone through the basics and want to -move on to more advanced functionalities, we explain other primitives whose -role has a less dominant place in an everyday editing session, but still -prove themselves powerful when used on the right occasion. - -Finally, as this document is in no way an exhaustive list of features, don't -hesitate to check out the official documentation to complement your tool-set, -ask questions to more seasoned users on IRC, and check the documentation -using the built-in `:doc` command. - -+=--------------------------------=+ BASICS +=--------------------------------=+ - - =[ MODES - - Kakoune uses a paradigm called "modal editing" to allow - .---, users to either have every single key they type inserted - | i | into the file being edited (called "insert mode"), - `---' or execute commands that are triggered by the keys hit - (the "normal mode"). Aside from arrow keys, most keys - .---, described in this document are "editing primitives" that - |esc| have to be hit in normal mode, which is the default mode - `---' when you start the editor. To enter insert mode, hit the - `i` key, and to leave it and return to normal mode, hit the - escape key. - - - =[ MOVEMENT - .---, - | ↑ | Movement in a buffer (the representation of the contents - .---'---'---, of a file opened by Kakoune) can be achieved using the arrow - | ← | ↓ | → | keys, which will move the cursor up one column/row into - `---'---'---` a given direction. - - However, furthering the tradition of mode-based editors, - .---,---,---,---, the `h`, `j`, `k` and `l` keys can be used for the same - | h | j | k | l | purpose, and will respectively move the cursor to the - `---'---'---'---` left, down, up, right by one, when hit. Using those keys - | | | | is the recommended way of moving around in a buffer. - .---,---,---,---, If you're not familiar with this concept, the proximity - | ← | ↓ | ↑ | → | of those four keys with the rest of the lettered keys - `---'---'---'---` on a `qwerty` layout allows faster interaction with the - primitives than if the user had to move their hand to - .---, reach the arrow keys. - | g |_. - `---' |`.---, Another way of moving the cursor is the "goto" utility, - | | g | invoked by hitting the `g` key. A menu will pop up with a - | `---' summary of all the possible keys that can be hit, along with - `.---, the location where they will move the cursor to, but the - | e | most used ones that we are interested in, for now, are `g` - `---' and `e`. The first one will jump to the beginning of the - buffer, and the second one to its end. - - - =[ VIEW - - .---, Displacing the cursor can sometimes move the view into an - | v |_. inconvenient configuration, leaving some necessary context - `---' |`.---, off-screen, or simply feel uncomfortable to type into. - | | t | Kakoune provides a menu (similar to the `goto` menu - | `---' mentioned in the previous section) that allows users to - |`.---, move the current view in relation to the position of the - | | b | cursor. Upon hitting the `v` key, a short menu appears - | `---' which allows us to hit a second key according to how the - `.---, view should be centered vertically: to leave the cursor - | v | respectively on top, at the bottom or in the middle of the - `---' current view, hit the `t`, `b` or `v` keys. - - - =[ SEARCH - - In order to move the cursor to a specific word, the search - command is the way to go. This functionality allows - .---, the user to jump to the next occurrence of a piece of text. - | / | Upon hitting the `/` key, a prompt reading "search" - `---' will pop up in the status bar in which you can type - your text and validate using the `` (return) key. - .---, .---, You'll notice that as you type, the cursor changes location - |alt|+| / | to automatically give you a preview of where the cursor - `---' `---' would be displaced to if you validated the search. However, - this behavior is only a preview, exiting prompt mode with - the `` (escape) key will leave the current position - .---, of the cursor unchanged. Note that you can also use a - | n | regular expression as input. By default the search - `---' function will look for results forward, starting from - the current location of the cursor, but you can search - .---, .---, backwards using `` (alt + `/`). - |alt|+| n | - `---' `---' Jumping from one match to the other forward can be achieved - using the `n` key, and backwards using the `` (alt + - `n`) key combination. - - - =[ SELECTIONS - - You have certainly noticed that when searching for - .---, text, the cursor extends to highlight the entire match. - | ; | In fact, what we know in other editors as a "cursor" is - `---' actually a single character wide selection in Kakoune, - and can be expanded using primitives. When "expanded", - .---, .---, the selection is an area whose beginning is the "anchor" - |alt|+| ; | and the end the "secondary cursor". To switch anchor and - `---' `---' cursor, use ``, and to collapse the selection onto - its anchor, use `;`. - - Moreover, not only Kakoune expands the principle of - "cursor" by introducing selections, but it also allows - .---, multiple selections within the same buffer. This makes - | % | it very convenient to modify text in multiple locations - `---' at once, as editing primitives apply to all the currently - selected text. - .---, - | s | Example: to remove all occurrences of the word "foo", one - `---' would select the entire buffer (`%`), select occurrences of - the word (`s`, "\bfoo\b", ``), then remove it (`d`). - - ==[ SELECTING OBJECTS - - In addition to allowing text selection using regular - .---, .---, expressions, certain objects are defined by default to - |alt|+| i | allow easy selection of text. Objects are bits of text - `---' `---' in the buffer that are identified according to their - structure, rather than their contents, e.g., a paragraph, - .---, .---, a sentence, or a word. When the cursor is located within - |alt|+| a | the boundaries of an object you want to interact with, - `---' `---' several options are available: selecting the contents of an - object without its boundaries (``), a part of it (from - .---, the anchor to its end or its beginning, respectively `]` - | ] | and `[`), or the entire object (``). Those "selection - `---' ranges" are the first part of a two stages shortcut, - as once you've used the key that dictates what part of - .---, the object is to be selected, a menu with a description - | [ | of all the object types select-able will be displayed, - `---' giving a summary of all the keys you can hit to complete - the selection procedure. - - Example: to select the paragraph in which the anchor lies, - invoke the "inner object selection" shortcut (``), - locate "paragraph" in the information box that pops up and - .---, hit the according key (`p`). The entire two steps sequence - | [ |_. is thus: ` p`. - `---' |`.---, - | | ( | Example: to select everything between the anchor and the - | `---' beginning of the current parenthesis pair, use the selection - `.---, sequence: `[ (`. Note that common objects that use - | r | pairs of opening/closing punctuation signs (brackets, - `---' braces, quotes etc) have an alternative second key that - is displayed in the information menu that you can use to - minimize finger gymnastics. The previous shortcut could - thus also be written: `[ b`. - - ==[ MOVEMENT SELECTIONS - - If objects are an easy way to select content-agnostic - .---, data in a buffer, they can also be seen as a way to move - | [ |_. about the buffer. As selecting objects will displace the - `---' `.---, anchor into a given direction, you can wrap or move around - | p | particular chunks of text without using the conventional - `---' means (e.g., arrow keys or jumps), turning them partially - into movement primitives. - .---, - | ] |_. Example: one of the most used object selection combination - `---' `.---, is the "object end/begin paragraph" one: using `[` or - | p | `]` will displace the anchor into a given direction, and - `---' applying that to the paragraph object allows "jumping" - from one newline separated block of text to another. - The resulting shortcut is thus: `] p` to move forward, or - `[ p` to move backward. - - - =[ FILTERING A SELECTION - - Selecting an entire buffer (`%`) or parts of it (`s`) is a - natural and basic operation in a typical editing session, - .---, .---, however, there are some cases where we need to be able to - |alt|+| k | drop some selections arbitrarily, as opposed to trying - `---' `---' to select the ones we need directly. This concept becomes - very useful when coming up with a regular expression for - .---, .---, the basic selection primitive (`s`) is too tedious (if - |alt|+| K | even possible), that's why the editor provides us with a - `---' `---' "keep matching" and a "keep not matching" operations, - in order to respectively keep exclusively the selections - who match or do not match a given regular expression. - - Example: when parsing a log file whose lines follow the - usual log pattern (e.g. "[1484383442] ERROR: some data"), - we want to be able to select all the lines individually - .---, .---, (`%`, `` to split all the lines), keep those that - |alt|+| s | start with a bracketed time-stamp (`^\[`), but - `---' `---' exclude the debug messages (`DEBUG`). Of course, - it's possible to come up with a regular expression to - match those simple requirements, but it would take more - work to write it than to organically apply filters on a - general selection, individually. - - - =[ SELECTION DUPLICATION - - .---, Duplicating content can be achieved using a widely - | y | implemented concept: yanking and pasting. Yanking the - `---' current selection (`y`) into the copy register allows the - .---, user to subsequently insert the copied text in the buffer - | p | (`p`). - `---' - .---, Note that the default "paste" primitive will insert the - | P | contents of the copy register after the current selection, - `---' if you want copied text to be inserted before the current - selection then you can use the `P` key. - - - =[ DELETING / REPLACING SELECTIONS - - Text replacement is a two-step process in Kakoune, which - .---, involves selecting text to be replaced, and then erasing it - | d | to insert the replacement text. After selections have been - `---' made, you can simply hit the deletion primitive (`d`), then - .---, either enter insert mode to write down the replacement text - | c | (`i`), or stay in command mode to paste the replacement - `---' text stored in the copy register. As deleting and entering - .---, insert mode can be redundant, a primitive that implements - | R | deletion followed by insert mode entrance was implemented: - `---' `c`. You can also directly replace the current selection - with the content of the copy register using a primitive - also implemented for that purpose: `R`. - - - =[ UNDO / REDO - - Mistakes or wrong decisions can happen while editing. - .---, To go back to earlier states of the buffer, you can press - | u | the `u` key several times. On the contrary, pressing `U` - `---' allows traveling forward in the history tree. - - -+=-------------------------------=+ ADVANCED +=-------------------------------=+ - - =[ SPLITTING - - The selection primitive (`s`) is a powerful tool to select - chunks of data, but sometimes the format of said data isn't - .---, uniform enough to allow creating clear cut selections. In - | S | order to avoid having to write overly complicated regular - `---' expressions that select precisely the wanted text, the - splitting primitive (`S`) allows applying a delimiter to - the current selection, splitting it into separate chunks. - - Example: selecting the items in a CSV-style list (e.g., - "1,2,3,4") is as simple as selecting the line, then - splitting it using the comma separator (`S,`). Note that - more advanced splitting is possible, since the delimiter - passed to this primitive is a regular expression. - - - =[ ROTATING - - Often used in conjunction with the splitting primitive - (`S`), the rotation primitive (``) shifts all the - selections clock-wise. Note that a count (described after) - allows the rotation to take place in sub-groups whose size - .---, .---, is given by the count parameter. - |alt|+| ) | - `---' `---' Example: in a numbered list where all the numbers are - selected (e.g., `1 2 3 4 5 6 7 8 9 0`), a rotation using - this primitive will shift all the numbers by one selection - forward, while leaving the original multiple selections - untouched (e.g., `0 1 2 3 4 5 6 7 8 9`). - - - =[ COUNTS - - .---, In order to pass a count to a primitive, simply type the - |0-9|_. number out before hitting the primitive key/combination. - `---' |`.---, Counts allow primitives to specialize or extend their - | | g | original functionality by using it as a parameter, - | `---' acting on their side effect. - |`.---, - | | G | Example: in order to respectively jump or select up to a - | `---' particular line, pass the line number to the `g` or `G` - |`.---, primitives (e.g., `42g` or `7G`). - | | o | - | `---' Example: creating an arbitrary amount of new lines - `.---, above or below the current line and spawning a new selection - | O | for each of them is achieved by passing the number of lines - `---' as a count respectively to the `o` and `O` primitives. - - - =[ REGISTERS - - Similarly to counts, registers influence the behavior of - .---, certain primitives. They are storage structures identified - | " |_. by a single character, and are populated by primitives as a - `---' `.---, result of a side effect. Although primitives populate a - |a-z| specific register by default, it's possible to modify which - `---' is going to be populated upon execution using the double - quote (`"`) primitive, and subsequently hitting a key that - .---, will serve as an identifier. - | * | - `---' Example: the smart search primitive (`*`) uses the current - selection as a search pattern, which will be saved to the - .---, `/` register. In order to use this primitive to execute a - | " |_. .---, temporary search, one could make this primitive save the - `---' `| _ | pattern to a different register, to preserve the default one, - `---' e.g., `"m*` to save the pattern to the `m` register, or even - `"_*` to save the pattern to a "null" register, which does - not store anything written to it. - - ==[ CAPTURE GROUPS - - Although registers can pass as mere buffer metadata, - .---, .---, they are an integral part of an editing session. The - |ctl|+| r | `` key combination allows to insert into the buffer - `---' `---' the value of a register, whose identifier is typed right - after the combination. - -.---, .---, Example: inserting the name of the current buffer in insert -|ctl|+| r |_. mode can be achieved using the `%` register, which holds -`---' `---' `.---, this information: `%`. - | % | - `---' Other registers that are set automatically are - the numbered registers, which hold the values of the groups - matched in the last search or select operation (`/` and -.---, .---, `s` primitives). -|ctl|+| r |_. -`---' `---' `.---, Example: when using the search primitive (`/`) with a - |0-9| regular expression containing groups to match a list of - `---' first and last names (e.g., `(\w+) (\w+)` on `John Doe`), - issuing `1` would insert the first name (`John`), - and `2` the last name (`Doe`). - - - =[ CUSTOM SELECTIONS - - Despite the ability to select bits of data using regular - expressions, there are times when using them isn't enough, - and additional manual editing of the selections is - .---, needed. In order to loop through all the selections and - | ) | remove the current one, two primitives are available: - `---' respectively the parenthesis (`)`), and the alt/comma - key combination (``). - .---, .---, - |alt|+| , | Example: given a list of three numbers all selected - `---' `---' individually, (e.g., `1 2 3`), deselecting the second - selection would be done by hitting the parenthesis primitive - (`)`) until the according selection is the current one, - then hitting `` to end up with only the first - and third number selected. - - However, being able to trim out some selections out - .---, of a bigger set isn't always convenient, as it doesn't - | ^ | allow more advanced constructs such as combining sets of - `---' multiple-selections that result from different regular - .---, expressions. To allow that, the save mark (`Z`) and append - | Z | mark (``) come in handy, as they respectively save - `---' the current selection to the mark register (`^`), and - show a menu that allows appending the current selection -.---, .---, to the mark register upon hitting the `a` key. That way, -|alt|+| z |_. it becomes possible to chain and save (append) several -`---' `---' `.---, selections made using completely different methods - | a | (select, split etc) without being forced to preserve - `---' them at all times. - .---, - | z | Restoring a mark saved to the mark register using those - `---' primitives can be achieved by using the restore mark - primitive (`z`). - - - =[ LEVERAGING SHELL COMMANDS - - UNIX systems provide with some tools whose purpose is - to interact with raw data, and being a UNIX compliant - .---, aspiring tool itself, Kakoune allows leveraging those - | | | tools to modify a buffer's contents. Upon invoking the pipe - `---' primitive (`|`), an input field pops up which prompts for - a shell command, to which the selections will individually - be sent through the command's standard input. - - Example: wrapping a selection can be achieved by invoking - the `fold` utility, e.g., `|fold -w80`. You could also want - to see a patch of all the modifications made to the buffer - since it was last saved: `%|diff -u % -`. Note that - the `%` has to be typed interactively, as it will - insert the name of the buffer into the command. - - Another equally useful primitive that doesn't depend on - .---, the contents of the current selections is the exclamation - | ! | mark primitive (`!`), which simply insert the output of - `---' the given shell command before each selection. - - Example: in order to insert the date of the day at the - beginning of the current buffer, one could use `gg` - followed with `!date`. - - But not all shell-related primitives insert data into - the current buffer, the `$` key is in fact a way to - .---, apply a predicate to all selections, in order to filter - | $ | them out. The command passed to this primitive will be - `---' executed in a new shell using each individual selection for - context, which will either be kept if the command returned - a successful exit code (zero) or dropped otherwise (any - non-zero value). - - Example: after selecting all the lines in a buffer and - splitting them individually (`%`, ``), keeping every - odd-numbered line can be achieved with the following - sequence: `$` `[ $((kak_reg_hash)) -ne 0 ]`. - - - =[ REPEATING ACTIONS - - ==[ PUNCTUAL INTERACTIONS - - In order to modify text efficiently or insert redundant - bits of data, two primitives are available. The dot `.` - .---, primitive repeats the last change that was made in insert - | . | mode (e.g., writing down text after hitting the insert - `---' primitive `i`). Similarly, repeating the last selection - (e.g., make with the find primitive `f`) can be achieved - using the `` primitive. - - Example: to select a paragraph to append a newline - .---, .---, character to it and cycle through the following paragraphs - |alt|+| . | to repeat the same insertion an arbitrary amount of times, - `---' `---' one would first select the paragraph with `]p`, append a - newline to it `a`, then repeat both operations - as needed with `` and `.` respectively. - - ==[ COMPLEX CHANGES - - Transforming successive chunks of formatted data can - .---, be cumbersome when done manually, and lack hindsight - | q | when writing a script for that particular purpose - `---' non-interactively. The middle ground between the two - .---, solutions is to record the modifications made to one - | Q | chunk interactively, and replay the sequence of keys - `---' at will. The sequence in question is a macro: the `Q` - primitive will create a new one (i.e., record all the keys -.---, .---, hit henceforth until the escape key `` is hit), and -|ctl|+| r |_. the `q` primitive will replay the keys saved in the macro. -`---' `---' `.---, - | @ | Notes: macros can easily be translated into a proper - `---' script, as they are saved in the `@` register, which you - can insert into a buffer using `@`. +# Kakoune + +set verbose mode (good for learning) +`:set -add global autoinfo normal` + +## Movement + +### Goto + +`10g` - go to line 10 + +`g` + + +`g` - buffer start + +`e` - buffer end + +`j` - buffer bottom + +`t` - window top + +`c` - window center + +`b` - window bottom + + +`l` - line end + +`h` - line begin + +`i` - line non blank start + +### Align screen relative to cursor (Vim z+) + +`v` + + +`v` - center vertically + +`m` - center horizontally + +`t` - top + +`b` - bottom + +`h`, `j`, `k`, `l` - scroll one char + +### Search + +`/ ` - start search forward (backward) + +`n ` - search next search pattern forward (backward) + +`N ` - extend next search pattern forward (backward) + +### Selections + +`%` - select whole buffer + +`s` - select (find) regex in selected text + +`` - select first and last char of selection(s) + +`` - split selection on line ends + +`S` - split selection on given regex + +`x` - select line (`X` - next line below) + +`` - extend selections to whole lines + +`` - crop selections to whole lines + +`` - switch anchor and cursor + +`;` - collapse selection to its anchor (one char, effectively reduce selection to one char) + +`` - select inner object + +`` - select all object (paragraph, sentence, etc) + +`[` - select to beginning of an object; `` - split selected text on line ends + +`` - select lines matching regexp inside selection + +`` - select lines NOT matching regexp inside selection + +`7G` - select to line 7 + +`` - select until beginning of; line like Vim `0` + +`` - select until end of line; like Vim `$` + +`m` - match paranthesis; like Vim's `%`, select parans and content inside + +`` - match parens backwards (direction) + +`M` - get a selection from current cursor to next block end or rather extend to next parans included + +`` - extend to prev parens + +`f` - select to next char included (`` - prev char) + +`C` - copy selection on next lines (`` - previus lines) + +`` - copy identation + +`Z` - save selection in mark register `^` + +`z` - restore selections stored in register `^` + +`` - combine selection from register, confirm by hitting `a` for example + +`` - combine selections to register + +`` - remove all selections except main + +`` - remove main selection + +`_` - trim selections + +### Text manipulation + +`y` - yank + +`p` - paste after (`P` before) + +`` - paste every yanked selection after selected text, keep new (pasted) selection (`` before) + +`d` - delete + +`i` - instert + +`c` - delete and inserst + +`R` - replace selection with the content of the register + +`` - replace selected text with yanked text + +`u` - undo + +`U` - redo + +`` - join with next line (`` include spaces) + +`backtick` - convert to lower-case (`` - swap case) + +`~` - convert to upper-case + +`o` - insert on new line below (`O` above) + +`` - add new line below (`` above) + +## Advanced + +`)` - loop through selections (`(` backward) + +`` - rotate splitted selection clock-wise (`` counter clock-wise) + +`"m*` - save smart search (*) pattern to register `m` (`_` is a null register) + +`` - instert into the buffer value stored in the register (`%` - buffer name, etc.); numbers correspond to submatches, like `(\w+)` + +`.` - repeat last insert session + +`` - repeat last selection (for example `]p`); like Vim' `;` + +`Q` - start recording macro until `Esc` is hit + +`q` - replay the macro (saved in the `@` register) + +### Shell + +`|` - modify selections by passind to the shell command which will transform them and write back (`` will ignore results) + +`!` - insert a result of the shell cmd before selections (`` - append result) + +`$` - apply predicate to selections (0 return value is considered a success); filiter them + +### Tips + +`|fold -w80` - wrap selection + +`!date` - insert date before selection + +`$xsel -bi` - copy selection to clipboard. `-bi` stands for `--clipboard --input` + +`%|diff -u % -` - compare current buffer contents with the version saved to disk + +`` insert mode -> normal mode (for one cmd) -> back, preseving selections/bindings, modes can be deeply nested (hit Esc more than once if needed) + +The couple `u` and `U` lets you move backward and forward in the last branch while their alternative versions `` `` follow absolute history id which may be located somewhere else in the history tree. + -- 2.51.2