Merge remote-tracking branch 'lenormf/manpage'
This commit is contained in:
Maxime Coste
commit
b59714bf2a
97
doc/kakoune.1.txt
Normal file
97
doc/kakoune.1.txt
Normal file
|
|
@ -0,0 +1,97 @@
|
||||||
|
kakoune(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
kakoune - a vim inspired, selection oriented code editor
|
||||||
|
|
||||||
|
SYNOPSIS
|
||||||
|
--------
|
||||||
|
*kak* [-q] [-u] [-n] [-l] [-e command] [-f command] [-p session_id] [-c session_id|[[-d] -s session_id] file ...
|
||||||
|
|
||||||
|
DESCRIPTION
|
||||||
|
-----------
|
||||||
|
Kakoune is a code editor heavily inspired by Vim, as such most of its commands are similar to Vi's ones, and it
|
||||||
|
shares Vi's "keystrokes as a text editing language" model.
|
||||||
|
|
||||||
|
Kakoune can operate in two modes, normal and insertion. In insertion mode, keys are directly inserted into the
|
||||||
|
current buffer. In normal mode, keys are used to manipulate the current selection and to enter insertion mode.
|
||||||
|
|
||||||
|
Kakoune has a strong focus on interactivity, most commands provide immediate and incremental results, while still
|
||||||
|
being competitive (as in keystroke count) with Vim.
|
||||||
|
|
||||||
|
Kakoune works on selections, which are oriented, inclusive range of characters, selections have an anchor and
|
||||||
|
a cursor character. Most commands move both of them, except when extending selection where the anchor character
|
||||||
|
stays fixed and the cursor one moves around.
|
||||||
|
|
||||||
|
OPTIONS
|
||||||
|
-------
|
||||||
|
-q::
|
||||||
|
in filter mode, be quiet about errors applying keys
|
||||||
|
|
||||||
|
-u::
|
||||||
|
use a dummy user interface, for testing purposes
|
||||||
|
|
||||||
|
-n::
|
||||||
|
do not source kakrc files on startup
|
||||||
|
|
||||||
|
-l::
|
||||||
|
list existing sessions
|
||||||
|
|
||||||
|
-d::
|
||||||
|
run as a headless session (requires -s)
|
||||||
|
|
||||||
|
-e <command>::
|
||||||
|
execute argument on initialisation
|
||||||
|
|
||||||
|
-f <command>::
|
||||||
|
act as a filter, executing given keys on given files
|
||||||
|
|
||||||
|
-p <session_id>::
|
||||||
|
just send stdin as commands to the given session
|
||||||
|
|
||||||
|
-c <session_id>::
|
||||||
|
connect to given session
|
||||||
|
|
||||||
|
-s <session_id>::
|
||||||
|
set session name
|
||||||
|
|
||||||
|
file::
|
||||||
|
one or more files to edit
|
||||||
|
|
||||||
|
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 exist), and finally *$XDG_CONFIG_HOME*'/kak/kakrc'.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
EXAMPLES
|
||||||
|
--------
|
||||||
|
kak /path/to/file::
|
||||||
|
Edit a file
|
||||||
|
|
||||||
|
kak ./file1.txt /path/to/file2.c::
|
||||||
|
Edit multiple files (multiple buffers will be created)
|
||||||
|
|
||||||
|
kak -f "ggO// kak: tabstop=8<esc>" *.c::
|
||||||
|
Insert a modeline that sets the tabstop variable at the beginning of several source code files
|
||||||
|
|
||||||
|
kak -e "man dup2"::
|
||||||
|
Use Kakoune as a man pager
|
||||||
|
|
||||||
|
FILES
|
||||||
|
-----
|
||||||
|
If not started with the -n switch, Kakoune will source the '../share/kak/kakrc' file relative to the kak binary,
|
||||||
|
which will source additional files:
|
||||||
|
|
||||||
|
* if the *$XDG_CONFIG_HOME*'/kak/autoload' directory exists, load every '*.kak' files in it, and load
|
||||||
|
recursively any subdirectory
|
||||||
|
* if it does not exists, fall back to the system wide autoload directory in '../share/kak/autoload'
|
||||||
|
|
||||||
|
After that, if it exists, source the *$XDG_CONFIG_HOME*'/kak/kakrc' file which should be used for user
|
||||||
|
configuration. In order to continue autoloading site-wide files with a local autoload directory, just add a symbolic
|
||||||
|
link to '../share/kak/autoload' into your local autoload directory.
|
||||||
154
doc/manpages/commands
Normal file
154
doc/manpages/commands
Normal file
|
|
@ -0,0 +1,154 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
commands - a
|
||||||
|
|
||||||
|
Primitives
|
||||||
|
----------
|
||||||
|
*e[dit]* <filename> [<line> [<column>]]::
|
||||||
|
open buffer on file, go to given line and column. If file is already opened, just switch to this file. Use edit! to force reloading
|
||||||
|
|
||||||
|
*w[rite]* [<filename>]::
|
||||||
|
write buffer to <filename> or use it's name if filename is not given
|
||||||
|
|
||||||
|
*w[rite]a[ll]*::
|
||||||
|
write all buffers that are associated to a file
|
||||||
|
|
||||||
|
*q[uit]*::
|
||||||
|
exit Kakoune, use quit! to force quitting even if there is some unsaved buffers remaining
|
||||||
|
|
||||||
|
*wq*::
|
||||||
|
write current buffer and quit
|
||||||
|
|
||||||
|
*b[uffer]* <name>::
|
||||||
|
switch to buffer <name>
|
||||||
|
|
||||||
|
*d[el]b[uf]* [<name>]::
|
||||||
|
delete the buffer <name>, use d[el]b[uf]! to force deleting a modified buffer
|
||||||
|
|
||||||
|
*source* <filename>::
|
||||||
|
execute commands in <filename>
|
||||||
|
|
||||||
|
*runtime* <filename>::
|
||||||
|
execute commands in <filename>, <filename> is relative to kak executable path
|
||||||
|
|
||||||
|
*colorscheme* <name>::
|
||||||
|
load named colorscheme
|
||||||
|
|
||||||
|
*nameclient* <name>::
|
||||||
|
set current client name
|
||||||
|
|
||||||
|
*namebuf* <name>::
|
||||||
|
set current buffer name
|
||||||
|
|
||||||
|
*echo* <text>::
|
||||||
|
show <text> in status line
|
||||||
|
|
||||||
|
*nop*::
|
||||||
|
does nothing, but arguments will be evaluated (e.g. shell expansion)
|
||||||
|
|
||||||
|
*set* <scope> <name> <value>::
|
||||||
|
change the value of an option (c.f. the 'options' documentation page)
|
||||||
|
|
||||||
|
*alias* <scope> <name> <command>::
|
||||||
|
define a new alias, within the context of a scope
|
||||||
|
|
||||||
|
*unalias* <scope> <name> [<command>]::
|
||||||
|
remove an alias if its current value is the same as the one passed as an optional parameter, remove it unconditionally otherwise
|
||||||
|
|
||||||
|
*decl* [-hidden] <type> <name> [<value>]::
|
||||||
|
declare a new option, the -hidden hides the option in completion suggestions (c.f. the 'options' documentation page)
|
||||||
|
|
||||||
|
*face* <name> <facespec>::
|
||||||
|
define a face (c.f. the 'faces' documentation page)
|
||||||
|
|
||||||
|
*exec* [<flags>] <key> ...::
|
||||||
|
execute a series of keys, as if they were hit (c.f. the 'execeval' documentation page)
|
||||||
|
|
||||||
|
*eval* [<flags>] <command> ...::
|
||||||
|
execute commands, as if they were entered in the command prompt (c.f. the 'execeval' documentation page)
|
||||||
|
|
||||||
|
*def* [<flags>] <name> <command>::
|
||||||
|
define a new command (c.f. the 'Declaring new commands' section below)
|
||||||
|
|
||||||
|
*map* <scope> <mode> <key> <keys>::
|
||||||
|
bind a combination of keys to another one (c.f. the 'commands' documentation page)
|
||||||
|
|
||||||
|
*hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
|
||||||
|
execute a command whenever an event is triggered (c.f. the 'hooks' documentation page)
|
||||||
|
|
||||||
|
*rmhooks* <scope> <group>::
|
||||||
|
remove every hooks in *scope* that are part of the given *group* (c.f. the 'hooks' documentation page)
|
||||||
|
|
||||||
|
*addhl* [<flags>] <highlighter_name> <highlighter_parameters> ...::
|
||||||
|
add a highlighter to the current window (c.f. the 'highlighters' documentation page)
|
||||||
|
|
||||||
|
*rmhl* <highlighter_id>::
|
||||||
|
remove the highlighter whose id is *highlighter_id* (c.f. the 'highlighters' documentation page)
|
||||||
|
|
||||||
|
Helpers
|
||||||
|
-------
|
||||||
|
Kakoune provides some helper commands that can be used to define composite commands:
|
||||||
|
|
||||||
|
*prompt* <prompt> <register> <command>::
|
||||||
|
prompt the user for a string, when the user validates, store the result in given *register* and run *commmand*. the *-init <str>* switch allows setting initial content
|
||||||
|
|
||||||
|
*onkey* <register> <command>::
|
||||||
|
wait for next key from user, writes it into given <register> and execute commands
|
||||||
|
|
||||||
|
*menu* <label1> <commands1> <label2> <commands2> ...::
|
||||||
|
display a menu using labels, the selected label’s commands are executed. menu can take an *-auto-single* argument, to automatically run commands when only one choice is provided, and a *-select-cmds* argument, in which case menu takes three argument per item, the last one being a command to execute when the item is selected (but not validated)
|
||||||
|
|
||||||
|
*info* <text>::
|
||||||
|
display text in an information box, at can take an *-anchor* option, which accepts left, right and cursor as value, in order to specify where the info box should be anchored relative to the main selection
|
||||||
|
|
||||||
|
*try* <commands> catch <on_error_commands>::
|
||||||
|
prevent an error in *commands* from aborting the whole commands execution, execute *on_error_commands* instead. If nothing is to be done on error, the catch part can be ommitted
|
||||||
|
|
||||||
|
*reg* <name> <content>::
|
||||||
|
set register *name* to *content*
|
||||||
|
|
||||||
|
Note that those commands are also available in the interactive mode, but are not really useful in that context.
|
||||||
|
|
||||||
|
Multiple commands
|
||||||
|
-----------------
|
||||||
|
Commands (c.f. previous sections) can be chained, by being separated either by new lines or by semicolons, as such a semicolon must be escaped with a backslash (\;) to be considered as a literal semicolon argument
|
||||||
|
|
||||||
|
Declaring new commands
|
||||||
|
----------------------
|
||||||
|
New commands can be defined using the *def* command:
|
||||||
|
|
||||||
|
*def* [flags] <command_name> <commands>::
|
||||||
|
*commands* is a string containing the commands to execute, and *flags* can be any combination of the following parameters:
|
||||||
|
|
||||||
|
*-params* <num>::
|
||||||
|
the command accepts a *num* parameter, which can be either a number, or of the form <min>..<max>, with both <min> and <max> omittable
|
||||||
|
|
||||||
|
*-file-completion*::
|
||||||
|
try file completion on any parameter passed to this command
|
||||||
|
|
||||||
|
*-client-completion*::
|
||||||
|
try client name completion on any parameter passed to this command
|
||||||
|
|
||||||
|
*-buffer-completion*::
|
||||||
|
try buffer name completion on any parameter passed to this command
|
||||||
|
|
||||||
|
*-shell-completion*::
|
||||||
|
following string is a shell command which takes parameters as positional params and output one completion candidate per line
|
||||||
|
|
||||||
|
*-allow-override*::
|
||||||
|
allow the new command to replace an exisiting one with the same name
|
||||||
|
|
||||||
|
*-hidden*::
|
||||||
|
do not show the command in command name completions
|
||||||
|
|
||||||
|
*-docstring*::
|
||||||
|
define the documentation string for the command
|
||||||
|
|
||||||
|
Using shell expansion allows to define complex commands or to access Kakoune state:
|
||||||
|
|
||||||
|
--------------------------------------------------------
|
||||||
|
def " print_selection %{ echo %sh{ ${kak_selection} } }"
|
||||||
|
--------------------------------------------------------
|
||||||
49
doc/manpages/execeval
Normal file
49
doc/manpages/execeval
Normal file
|
|
@ -0,0 +1,49 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
execeval - a
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
The *exec* and *eval* commands can be used to run Kakoune commands, and should be used as follows:
|
||||||
|
|
||||||
|
----------------------------
|
||||||
|
exec [<flags>] <key> ...
|
||||||
|
eval [<flags>] <command> ...
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
*exec* runs keys as if they were pressed, whereas *eval* executes its given paremeters as if they were entered in
|
||||||
|
the command prompt. By default, their execution happens within the context of the current client, and stops when
|
||||||
|
the last key/command is reached, or an error is raised.
|
||||||
|
|
||||||
|
Optional flags
|
||||||
|
--------------
|
||||||
|
*-client* <name>::
|
||||||
|
execute in the context of the client named *name*
|
||||||
|
|
||||||
|
*-try-client* <name>::
|
||||||
|
execute in the context of the client named *name* if such client exists, or else in the current context
|
||||||
|
|
||||||
|
*-draft*::
|
||||||
|
execute in a copy of the context of the selected client modifications to the selections or input state
|
||||||
|
will not affect the client. This permits to make some modification to the buffer without modifying the
|
||||||
|
user’s selection
|
||||||
|
|
||||||
|
*-itersel* (requires -draft)::
|
||||||
|
execute once per selection, in a context with only the considered selection. This permits to avoid cases
|
||||||
|
where the selections may get merged
|
||||||
|
|
||||||
|
*-buffer* <names>::
|
||||||
|
execute in the context of each buffers in the comma separated list *names*, as a name can be used to
|
||||||
|
iterate on all buffers
|
||||||
|
|
||||||
|
*-no-hooks*::
|
||||||
|
disable hook execution while executing the keys/commands
|
||||||
|
|
||||||
|
*-with-maps*::
|
||||||
|
use user key mapping in instead of built in keys (*exec* only)
|
||||||
|
|
||||||
|
*-save-regs* <regs>::
|
||||||
|
regs is a string of registers to be restored after execution
|
||||||
102
doc/manpages/expansions
Normal file
102
doc/manpages/expansions
Normal file
|
|
@ -0,0 +1,102 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
expansions - a
|
||||||
|
|
||||||
|
Strings
|
||||||
|
-------
|
||||||
|
\'strings'::
|
||||||
|
uninterpreted strings, use a backslash (\\') to escape the separator
|
||||||
|
"strings"::
|
||||||
|
expanded strings, % strings (c.f. next section) contained are expended, use a backslash (\\%) to escape the separator
|
||||||
|
%\{strings\}::
|
||||||
|
these strings are very useful when entering commands
|
||||||
|
+
|
||||||
|
* the '{' and '}' delimiters are configurable, you can use any non alphanumeric character
|
||||||
|
+
|
||||||
|
----------------------------------------------------------
|
||||||
|
e.g. %[string], %<string>, %(string), %~string~, %!string!
|
||||||
|
----------------------------------------------------------
|
||||||
|
* if the character following '%' is one of '{[(<', then the closing one is the matching '}])>' and the
|
||||||
|
delimiters are not escapable but are nestable
|
||||||
|
+
|
||||||
|
-----------------------------------------------------------
|
||||||
|
e.g. %{ roger {}; } is a valid string, %{ marcel \} as well
|
||||||
|
-----------------------------------------------------------
|
||||||
|
|
||||||
|
Typed expansions
|
||||||
|
----------------
|
||||||
|
*sh*::
|
||||||
|
shell expansion, similar to posix shell '$(...)' construct (c.f. next section)
|
||||||
|
*reg*::
|
||||||
|
register expansion, will be replaced by the content of the given register
|
||||||
|
*opt*::
|
||||||
|
option expansion, will be replaced with the value of the given option
|
||||||
|
*val*::
|
||||||
|
value expansion, gives access to the environment variable available to the Shell expansion. The 'kak_'
|
||||||
|
prefix is not used there
|
||||||
|
*arg*::
|
||||||
|
argument expansion, gives access to the arguments of the current command, the content can be a number,
|
||||||
|
or @ for all arguments
|
||||||
|
|
||||||
|
Shell expansions
|
||||||
|
----------------
|
||||||
|
The '%sh{...}' expansion replaces its content with the output of the shell commands in it. The following environment
|
||||||
|
variables are used to pass informations about Kakoune's state:
|
||||||
|
|
||||||
|
*kak_selection*::
|
||||||
|
content of the main selection
|
||||||
|
*kak_selections*::
|
||||||
|
content of the selection separated by colons, colons in the selection contents are escapted with a backslash
|
||||||
|
*kak_selection_desc*::
|
||||||
|
range of the main selection, represented as anchor,cursor; anchor and cursor are in this format: line.column
|
||||||
|
*kak_selections_desc*::
|
||||||
|
range of the selecations separated by colons
|
||||||
|
*kak_bufname*::
|
||||||
|
name of the current buffer
|
||||||
|
*kak_buffile*::
|
||||||
|
full path of the file or same as kak_bufname when there’s no associated file
|
||||||
|
*kak_buflist*::
|
||||||
|
the current buffer list, each buffer seperated by a colon
|
||||||
|
*kak_timestamp*::
|
||||||
|
timestamp of the current buffer, the timestamp is an integer value which is incremented each time the
|
||||||
|
buffer is modified
|
||||||
|
*kak_runtime*::
|
||||||
|
directory containing the kak binary
|
||||||
|
*kak_opt_<name>*::
|
||||||
|
value of option *name*
|
||||||
|
*kak_reg_<r>*::
|
||||||
|
value of register *r*
|
||||||
|
*kak_socket*::
|
||||||
|
filename of session socket ('/tmp/kak-<session>')
|
||||||
|
*kak_session*::
|
||||||
|
name of the current session
|
||||||
|
*kak_client*::
|
||||||
|
name of current client
|
||||||
|
*kak_cursor_line*::
|
||||||
|
line of the end of the main selection
|
||||||
|
*kak_cursor_column*::
|
||||||
|
column of the end of the main selection (in byte)
|
||||||
|
*kak_cursor_char_column*::
|
||||||
|
column of the end of the main selection (in character)
|
||||||
|
*kak_window_width*::
|
||||||
|
width of the current kakoune window
|
||||||
|
*kak_window_height*::
|
||||||
|
height of the current kakoune window
|
||||||
|
*kak_hook_param*::
|
||||||
|
filtering text passed to the currently executing hook
|
||||||
|
*kak_client_env_<name>*::
|
||||||
|
value of the *name* variable in the client environment (e.g. *$kak_client_env_SHELL* is the SHELL variable)
|
||||||
|
|
||||||
|
Note that in order for Kakoune to pass a value in the environment, the variable has to be spelled out within the
|
||||||
|
body of the expansion
|
||||||
|
|
||||||
|
Markup strings
|
||||||
|
--------------
|
||||||
|
In certain contexts, Kakoune can take a markup string, which is a string containing formatting informations.
|
||||||
|
In these strings, the {facename} syntax will enable the face facename until another face gets activated, or the
|
||||||
|
end of the string is reached.
|
||||||
|
Literal '{' characters shall be written '\{', and a literal backslash ('\') that preceeds a '{' character shall
|
||||||
|
be escaped as well ('\\').
|
||||||
93
doc/manpages/faces
Normal file
93
doc/manpages/faces
Normal file
|
|
@ -0,0 +1,93 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
faces - a
|
||||||
|
|
||||||
|
Declaration
|
||||||
|
-----------
|
||||||
|
A 'face' refers how the specified text is displayed, it has a foreground color, a background color, and some
|
||||||
|
attributes. The value of a face has the following format:
|
||||||
|
|
||||||
|
--------------------------------
|
||||||
|
fg_color[,bg_color][+attributes]
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
'fg_color', 'bg_color'::
|
||||||
|
a color whose value can be expressed in the following formats:
|
||||||
|
*black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, *white*:::
|
||||||
|
a named color
|
||||||
|
*default*:::
|
||||||
|
keep the existing color
|
||||||
|
*rgb:RRGGBB*:::
|
||||||
|
hexadecimal value
|
||||||
|
|
||||||
|
'attributes'::
|
||||||
|
string whose individual letters set an attribute:
|
||||||
|
*u*:::
|
||||||
|
underline
|
||||||
|
*r*:::
|
||||||
|
reverse
|
||||||
|
*b*:::
|
||||||
|
bold
|
||||||
|
*B*:::
|
||||||
|
blink
|
||||||
|
*d*:::
|
||||||
|
dim
|
||||||
|
*i*:::
|
||||||
|
italic
|
||||||
|
*e*:::
|
||||||
|
exclusive, override previous faces instead of merging with them
|
||||||
|
|
||||||
|
Builtin faces
|
||||||
|
-------------
|
||||||
|
The following default faces are used by color schemes to highlight certains areas of the user interface:
|
||||||
|
|
||||||
|
*Default*::
|
||||||
|
default colors
|
||||||
|
|
||||||
|
*PrimarySelection*::
|
||||||
|
main selection face for every selected character except the cursor
|
||||||
|
|
||||||
|
*SecondarySelection*::
|
||||||
|
secondary selection face for every selected character except the cursor
|
||||||
|
|
||||||
|
*PrimaryCursor*::
|
||||||
|
cursor of the primary selection
|
||||||
|
|
||||||
|
*SecondaryCursor*::
|
||||||
|
cursor of the secondary selection
|
||||||
|
|
||||||
|
*LineNumbers*::
|
||||||
|
face used by the number_lines highlighter
|
||||||
|
|
||||||
|
*LineNumberAbsolute*::
|
||||||
|
face used to highlight the line number of the main selection
|
||||||
|
|
||||||
|
*MenuForeground*::
|
||||||
|
face for the selected element in menus
|
||||||
|
|
||||||
|
*MenuBackground*::
|
||||||
|
face for the not selected elements in menus
|
||||||
|
|
||||||
|
*Information*::
|
||||||
|
face for the informations windows and information messages
|
||||||
|
|
||||||
|
*Error*::
|
||||||
|
face of error messages
|
||||||
|
|
||||||
|
*StatusLine*::
|
||||||
|
face used for the status line
|
||||||
|
|
||||||
|
*StatusCursor*::
|
||||||
|
face used for the status line cursor
|
||||||
|
|
||||||
|
*Prompt*::
|
||||||
|
face used prompt displayed on the status line
|
||||||
|
|
||||||
|
*MatchingChar*::
|
||||||
|
face used by the show_matching highlighter
|
||||||
|
|
||||||
|
*Search*::
|
||||||
|
face used to highlight search results
|
||||||
173
doc/manpages/highlighters
Normal file
173
doc/manpages/highlighters
Normal file
|
|
@ -0,0 +1,173 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
highlighters - a
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Manipulation of the displayed text is done through highlighters, which can be added or removed with the following
|
||||||
|
commands:
|
||||||
|
|
||||||
|
-------------------------------------------------------
|
||||||
|
addhl <highlighter_name> <highlighter_parameters> ...
|
||||||
|
-------------------------------------------------------
|
||||||
|
|
||||||
|
and
|
||||||
|
|
||||||
|
-----------------------
|
||||||
|
*rmhl* <highlighter_id>
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
*highlighter_id* is a name generated by the highlighter specified with *highlighter_name*, possibly dependent on
|
||||||
|
the parameters. Use command completion in a prompt on the *rmhl* command to see the existing highlighters ids.
|
||||||
|
|
||||||
|
General highlighters
|
||||||
|
--------------------
|
||||||
|
*regex* <ex> <capture_id>:<face> ...::
|
||||||
|
highlight a regex, takes the regex as first parameter, followed by any number of face parameters. For example:
|
||||||
|
|
||||||
|
addhl regex //(\hTODO:)?[^\n] 0:cyan 1:yellow,red
|
||||||
|
|
||||||
|
will highlight C++ style comments in cyan, with an eventual 'TODO:' in yellow on red background
|
||||||
|
|
||||||
|
*dynregex*::
|
||||||
|
Similar to regex, but expand (like a command paramater would) the given expression before building a regex from the result
|
||||||
|
|
||||||
|
*flag_lines* <flag> <option_name>::
|
||||||
|
add a column in front of text, and display the given flag in it for everly line contained in the int-list option named <option_name>
|
||||||
|
|
||||||
|
*show_matching*::
|
||||||
|
highlight matching char of the character under the selections cursor using MatchingChar face
|
||||||
|
|
||||||
|
*number_lines* [options]::
|
||||||
|
show line numbers, with the following *options*:
|
||||||
|
|
||||||
|
*-relative*:::
|
||||||
|
show line numbers relative to the main cursor line
|
||||||
|
|
||||||
|
*-hlcursor*:::
|
||||||
|
highlight the cursor line with a separate face
|
||||||
|
|
||||||
|
*-separator* <separator text>:::
|
||||||
|
specify a string to separate the line numbers column with the rest of the buffer (default is '|')
|
||||||
|
|
||||||
|
*fill* <face>::
|
||||||
|
fill using the given *face*, mostly useful with regions highlighters
|
||||||
|
|
||||||
|
Highlighting Groups
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
The group highlighter is a container for other highlighters. You can add a group to the current window using
|
||||||
|
|
||||||
|
--------------------
|
||||||
|
addhl group <name>
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
The *-group* switch of the *addhl* command provides a mean to add highlighters inside this group:
|
||||||
|
|
||||||
|
----------------------------------------
|
||||||
|
addhl -group <name> <type> <params>...
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
|
Groups can contain other groups, the *-group* switch can be used to define a path as follows:
|
||||||
|
|
||||||
|
--------------------------------------------------
|
||||||
|
addhl -group <name> group <subname>
|
||||||
|
addhl -group <name>/<subname> <type> <params>...
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
Regions highlighters
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
A special highlighter provides a way to segment the buffer into regions, which are to be highlighted differently.
|
||||||
|
|
||||||
|
*name*::
|
||||||
|
user defined, used to identify the region
|
||||||
|
*opening*::
|
||||||
|
regex that defines the region start text
|
||||||
|
*closing*::
|
||||||
|
regex that defines the region end text
|
||||||
|
*recurse*::
|
||||||
|
regex that defines the text that matches recursively an end token into the region
|
||||||
|
|
||||||
|
The *recurse* option is useful for regions that can be nested, for example the following contruct:
|
||||||
|
|
||||||
|
----------
|
||||||
|
%sh{ ... }
|
||||||
|
----------
|
||||||
|
|
||||||
|
accepts nested braces scopes ('{ ... }') so the following string is valid:
|
||||||
|
|
||||||
|
----------------------
|
||||||
|
%sh{ ... { ... } ... }
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
This region can be defined with:
|
||||||
|
|
||||||
|
------------------------
|
||||||
|
shell_expand %sh\{ \} \{
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Regions are used in the regions highlighter which can take any number of regions.
|
||||||
|
|
||||||
|
The following command:
|
||||||
|
|
||||||
|
-----------------------------------------------------------------------
|
||||||
|
addhl regions <name> <region_name1> <opening1> <closing1> <recurse1>
|
||||||
|
<region_name2> <opening2> <closing2> <recurse2>...
|
||||||
|
-----------------------------------------------------------------------
|
||||||
|
|
||||||
|
defines multiple regions in which other highlighters can be added as follows:
|
||||||
|
|
||||||
|
---------------------------------------
|
||||||
|
addhl -group <name>/<region_name> ...
|
||||||
|
---------------------------------------
|
||||||
|
|
||||||
|
Regions are matched using the left-most rule: the left-most region opening starts a new region. When a region closes, the closest next opening start another region.
|
||||||
|
|
||||||
|
That matches the rule governing most programming language parsing.
|
||||||
|
|
||||||
|
Regions also supports a *-default <default_region>* switch to define the default region, when no other region matches the current buffer range.
|
||||||
|
|
||||||
|
Most programming languages can then be properly highlighted using a regions highlighter as root:
|
||||||
|
|
||||||
|
-----------------------------------------------------------------
|
||||||
|
addhl regions -default code <lang> \
|
||||||
|
string <str_opening> <str_closing> <str_recurse> \
|
||||||
|
comment <comment_opening> <comment_closing> <comment_recurse>
|
||||||
|
|
||||||
|
addhl -group <lang>/code ...
|
||||||
|
addhl -group <lang>/string ...
|
||||||
|
addhl -group <lang>/comment ...
|
||||||
|
-----------------------------------------------------------------
|
||||||
|
|
||||||
|
Shared Highlighters
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Highlighters are often defined for a specific filetype, and it makes then sense to share the highlighters between all the windows on the same filetypes.
|
||||||
|
|
||||||
|
A shared highlighter can be defined with the following command:
|
||||||
|
|
||||||
|
--------------------------------
|
||||||
|
addhl -group /<group_name> ...
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
When the group switch values starts with a '/', it references a group in the shared highlighters, rather than the window highlighters.
|
||||||
|
|
||||||
|
The common case would be to create a named shared group, and then fill it with highlighters:
|
||||||
|
|
||||||
|
------------------------------
|
||||||
|
addhl -group / group <name>
|
||||||
|
addhl -group /name regex ...
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
It can then be referenced in a window using the ref highlighter.
|
||||||
|
|
||||||
|
------------------
|
||||||
|
addhl ref <name>
|
||||||
|
------------------
|
||||||
|
|
||||||
|
The ref can reference any named highlighter in the shared namespace.
|
||||||
123
doc/manpages/hooks
Normal file
123
doc/manpages/hooks
Normal file
|
|
@ -0,0 +1,123 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
hooks - a
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Commands can be registred to be executed when certain events arise. To register a hook use the following command:
|
||||||
|
|
||||||
|
----------------------------------------------------------------------
|
||||||
|
hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
|
||||||
|
----------------------------------------------------------------------
|
||||||
|
|
||||||
|
*scope* can be one of *global*, *buffer* or *window*.
|
||||||
|
|
||||||
|
*command* is a string containing the commands to execute when the hook is called.
|
||||||
|
|
||||||
|
For example to automatically use line numbering with .cc files, use the following command:
|
||||||
|
|
||||||
|
----------------------------------------------------
|
||||||
|
hook global WinCreate .*\.cc %{ addhl number_lines }
|
||||||
|
----------------------------------------------------
|
||||||
|
|
||||||
|
if *group* is given, make this hook part of the named group. Groups are used for removing hooks with the following
|
||||||
|
command:
|
||||||
|
|
||||||
|
-----------------------
|
||||||
|
rmhooks <scope> <group>
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
A call to the command above will remove every hooks in *scope* that are part of the given *group*.
|
||||||
|
|
||||||
|
Default hooks
|
||||||
|
-------------
|
||||||
|
*NormalIdle*::
|
||||||
|
a certain duration has passed since last key was pressed in normal mode
|
||||||
|
|
||||||
|
*NormalBegin*::
|
||||||
|
entering normal mode
|
||||||
|
|
||||||
|
*NormalEnd*::
|
||||||
|
leaving normal mode
|
||||||
|
|
||||||
|
*NormalKey*::
|
||||||
|
a key is received in normal mode, the key is used for filtering
|
||||||
|
|
||||||
|
*InsertIdle*::
|
||||||
|
a certain duration has passed since last key was pressed in insert mode
|
||||||
|
|
||||||
|
*InsertBegin*::
|
||||||
|
entering insert mode
|
||||||
|
|
||||||
|
*InsertEnd*::
|
||||||
|
leaving insert mode
|
||||||
|
|
||||||
|
*InsertKey*::
|
||||||
|
a key is received in insert mode, the key is used for filtering
|
||||||
|
|
||||||
|
*InsertMove*::
|
||||||
|
the cursor moved (without inserting) in insert mode, the key that triggered the move is used for filtering
|
||||||
|
|
||||||
|
*WinCreate*::
|
||||||
|
a window was created, the filtering text is the buffer name
|
||||||
|
|
||||||
|
*WinClose*::
|
||||||
|
a window was detroyed, the filtering text is the buffer name
|
||||||
|
|
||||||
|
*WinDisplay*::
|
||||||
|
a window was bound a client, the filtering text is the buffer name
|
||||||
|
|
||||||
|
*WinSetOption*::
|
||||||
|
an option was set in a window context, the filtering text is *<option_name>=<new_value>*
|
||||||
|
|
||||||
|
*BufSetOption*::
|
||||||
|
an option was set in a buffer context, the filtering text is *<option_name>=<new_value>*
|
||||||
|
|
||||||
|
*BufNew*::
|
||||||
|
a buffer for a new file has been created, filename is used for filtering
|
||||||
|
|
||||||
|
*BufOpen*::
|
||||||
|
a buffer for an existing file has been created, filename is used for filtering
|
||||||
|
|
||||||
|
*BufCreate*::
|
||||||
|
a buffer has been created, filename is used for filtering
|
||||||
|
|
||||||
|
*BufWritePre*::
|
||||||
|
executed just before a buffer is written, filename is used for filtering
|
||||||
|
|
||||||
|
*BufWritePost*::
|
||||||
|
executed just after a buffer is written, filename is used for filtering
|
||||||
|
|
||||||
|
*BufClose*::
|
||||||
|
executed when a buffer is deleted, while it is still valid
|
||||||
|
|
||||||
|
*BufOpenFifo*::
|
||||||
|
executed when a buffer opens a fifo
|
||||||
|
|
||||||
|
*BufReadFifo*::
|
||||||
|
executed after some data has been red from a fifo and inserted in the buffer
|
||||||
|
|
||||||
|
*BufCloseFifo*::
|
||||||
|
executed when a fifo buffer closes its fifo file descriptor either because the buffer is being deleted,
|
||||||
|
or because the writing end has been closed
|
||||||
|
|
||||||
|
*RuntimeError*::
|
||||||
|
an error was encountered while executing an user command the error message is used for filtering
|
||||||
|
|
||||||
|
*KakBegin*::
|
||||||
|
kakoune has started, this hook is called just after reading the user configuration files
|
||||||
|
|
||||||
|
*KakEnd*::
|
||||||
|
kakoune is quitting
|
||||||
|
|
||||||
|
*FocusIn*::
|
||||||
|
on supported clients, triggered when the client gets focused. the filtering text is the client name
|
||||||
|
|
||||||
|
*FocusOut*::
|
||||||
|
on supported clients, triggered when the client gets unfocused. the filtering text is the client name
|
||||||
|
|
||||||
|
When not specified, the filtering text is an empty string.
|
||||||
135
doc/manpages/options
Normal file
135
doc/manpages/options
Normal file
|
|
@ -0,0 +1,135 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
options - a
|
||||||
|
|
||||||
|
Types
|
||||||
|
-----
|
||||||
|
*int*::
|
||||||
|
an integer number
|
||||||
|
*bool*::
|
||||||
|
a boolean value, yes/true or no/false
|
||||||
|
*str*::
|
||||||
|
a string, some freeform text
|
||||||
|
*coord*::
|
||||||
|
a line, column pair (separated by comma)
|
||||||
|
*regex*::
|
||||||
|
as a string but the set commands will complain if the entered text is not a valid regex
|
||||||
|
*int-list*, *str-list*::
|
||||||
|
a list, elements are separated by a colon (:) if an element needs to contain a colon, it can be escaped
|
||||||
|
with a backslash
|
||||||
|
*enum(value1|value2|...)*::
|
||||||
|
an enum, taking one of the given values
|
||||||
|
*flags(value1|value2|...)*::
|
||||||
|
a set of flags, taking a combination of the given values joined by a '|' character
|
||||||
|
|
||||||
|
Scopes
|
||||||
|
------
|
||||||
|
*window*::
|
||||||
|
context linked to the window displaying a buffer
|
||||||
|
*buffer*::
|
||||||
|
context linked directly to the buffer
|
||||||
|
*global*::
|
||||||
|
global context linked to the instance of Kakoune
|
||||||
|
|
||||||
|
Options can have individual values that change from one scope to the other, which will be considered one after
|
||||||
|
another in the following order: *window* → *buffer* → *global*.
|
||||||
|
That means that two windows on the same buffer can use different options (e.g. different *filetype*).
|
||||||
|
However some options might end up being ignored if their scope is not in the command context.
|
||||||
|
For example, writing a file never uses the *window* scope when considering options, so any option related to
|
||||||
|
writing won't be taken into account if set in the *window* scope (e.g. *BOM*, *eolformat*).
|
||||||
|
|
||||||
|
Builtin options
|
||||||
|
---------------
|
||||||
|
|
||||||
|
*tabstop* 'int'::
|
||||||
|
width of a tab character
|
||||||
|
|
||||||
|
*indentwidth* 'int'::
|
||||||
|
width (in spaces) used for indentation, 0 means a tab character
|
||||||
|
|
||||||
|
*scrolloff* 'coord'::
|
||||||
|
number of lines, columns to keep visible around the cursor when scrolling
|
||||||
|
|
||||||
|
*eolformat* 'enum(lf|crlf)'::
|
||||||
|
the format of end of lines when writing a buffer, this is autodetected on load
|
||||||
|
|
||||||
|
*BOM* 'enum(none|utf8)'::
|
||||||
|
define if the file should be written with an unicode byte order mark
|
||||||
|
|
||||||
|
*complete_prefix* 'bool'::
|
||||||
|
when completing in command line, and multiple candidates exist, enable completion with common prefix
|
||||||
|
|
||||||
|
*incsearch* 'bool'::
|
||||||
|
execute search as it is typed
|
||||||
|
|
||||||
|
*aligntab* 'bool'::
|
||||||
|
use tabs for alignement command
|
||||||
|
|
||||||
|
*autoinfo* 'flags(command|onkey|normal)'::
|
||||||
|
display automatic information box in the enabled contexts
|
||||||
|
|
||||||
|
*autoshowcompl* 'bool'::
|
||||||
|
automatically display possible completions when editing a prompt
|
||||||
|
|
||||||
|
*ignored_files* 'regex'::
|
||||||
|
filenames matching this regex wont be considered as candidates on filename completion (except if the text
|
||||||
|
being completed already matches it)
|
||||||
|
|
||||||
|
*disabled_hooks* 'regex'::
|
||||||
|
hooks whose group matches this regex wont be executed. For example indentation hooks can be disabled with '.*-indent'
|
||||||
|
|
||||||
|
*filetype* 'str'::
|
||||||
|
arbitrary string defining the type of the file filetype dependant actions should hook on this option
|
||||||
|
changing for activation/deactivation
|
||||||
|
|
||||||
|
*path* 'str-list'::
|
||||||
|
directories to search for gf command
|
||||||
|
|
||||||
|
*completers* 'str-list'::
|
||||||
|
completion engines to use for insert mode completion (they are tried in order until one generates
|
||||||
|
candidates). Existing completers are:
|
||||||
|
|
||||||
|
*word=all*, *word=buffer*:::
|
||||||
|
which complete using words in all buffers (*word=all*) or only the current one (*word=buffer*)
|
||||||
|
|
||||||
|
*filename*:::
|
||||||
|
which tries to detect when a filename is being entered and provides completion based on local filesystem
|
||||||
|
|
||||||
|
*option=<opt-name>*:::
|
||||||
|
where *opt-name* is a 'str-list' option. The first element of the list should follow the format:
|
||||||
|
|
||||||
|
<line>.<column>[+<length>]@<timestamp>
|
||||||
|
|
||||||
|
to define where the completion apply in the buffer, and the other strings are the candidates
|
||||||
|
|
||||||
|
*static_words* 'str-list':::
|
||||||
|
list of words that are always added to completion candidates when completing words in insert mode
|
||||||
|
|
||||||
|
*autoreload* 'enum(yes|no|ask)'::
|
||||||
|
auto reload the buffers when an external modification is detected
|
||||||
|
|
||||||
|
*debug* 'flags(hooks|shell|profile)'::
|
||||||
|
dump various debug information in the '\*debug*' buffer
|
||||||
|
|
||||||
|
*modelinefmt* 'string'::
|
||||||
|
A format string used to generate the mode line, that string is first expanded as a command line would be
|
||||||
|
(expanding '%...{...}' strings), then markup tags are applied (c.f. the 'Expansions' documentation page)
|
||||||
|
|
||||||
|
*ui_options*::
|
||||||
|
colon separated list of key=value pairs that are forwarded to the user interface implementation. The
|
||||||
|
NCurses UI support the following options:
|
||||||
|
|
||||||
|
*ncurses_set_title*:::
|
||||||
|
if *yes* or *true*, the terminal emulator title will be changed
|
||||||
|
|
||||||
|
*ncurses_status_on_top*:::
|
||||||
|
if *yes*, or *true* the status line will be placed at the top of the terminal rather than at the bottom
|
||||||
|
|
||||||
|
*ncurses_assistant*:::
|
||||||
|
specify the nice assistant you get in info boxes, can be *clippy* (the default), *cat* or *none*
|
||||||
|
|
||||||
|
*ncurses_wheel_down_button*, *ncurses_wheel_up_button*:::
|
||||||
|
specify which button send for wheel down/up events
|
||||||
49
doc/manpages/registers
Normal file
49
doc/manpages/registers
Normal file
|
|
@ -0,0 +1,49 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
registers - a
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Registers are named lists of text -instead of simply text- in order to interact well with multiselection.
|
||||||
|
They are used for various purposes, like storing the last yanked test, or the captured groups associated with
|
||||||
|
the selections.
|
||||||
|
|
||||||
|
Interacting
|
||||||
|
-----------
|
||||||
|
*<c-r><c>*::
|
||||||
|
when in insert mode or in a prompt, insert the value stored in the *c* register (single character)
|
||||||
|
|
||||||
|
*"<c>*::
|
||||||
|
in normal mode, select the *<c>* register (single character)
|
||||||
|
|
||||||
|
Default registers
|
||||||
|
-----------------
|
||||||
|
Most commands using a register default to a specific one if not specified:
|
||||||
|
|
||||||
|
*"*::
|
||||||
|
default yank, used by yanking and pasting commands like *y*, *p* and *R*
|
||||||
|
|
||||||
|
*/*::
|
||||||
|
default search register, used by regex based commands like *s*, *\** or */*
|
||||||
|
|
||||||
|
*@*::
|
||||||
|
default macro register, used by *q* and *Q*
|
||||||
|
|
||||||
|
*^*::
|
||||||
|
default mark register, used by *z* and *Z*
|
||||||
|
|
||||||
|
Special registers
|
||||||
|
-----------------
|
||||||
|
Some registers are not general purposes, they cannot be written to, but they contain some special dat
|
||||||
|
|
||||||
|
*%*::
|
||||||
|
current buffer name
|
||||||
|
|
||||||
|
*.*::
|
||||||
|
current selection contents
|
||||||
|
|
||||||
|
*#*::
|
||||||
|
selection indices (first selection has 1, second has 2, ...)
|
||||||
578
doc/manpages/shortcuts
Normal file
578
doc/manpages/shortcuts
Normal file
|
|
@ -0,0 +1,578 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
shortcuts - a
|
||||||
|
|
||||||
|
Insert mode
|
||||||
|
-----------
|
||||||
|
*<esc>*::
|
||||||
|
leave insert mode
|
||||||
|
|
||||||
|
*<backspace>*::
|
||||||
|
delete characters before cursors
|
||||||
|
|
||||||
|
*<del>*::
|
||||||
|
delete characters under cursors
|
||||||
|
|
||||||
|
*<left>*, *<right>*, *<up>*, *<down>*::
|
||||||
|
move the cursors in given direction
|
||||||
|
|
||||||
|
*<home>*::
|
||||||
|
move cursors to line begin
|
||||||
|
|
||||||
|
*<end>*::
|
||||||
|
move cursors to end of line
|
||||||
|
|
||||||
|
*<c-n>*::
|
||||||
|
select next completion candidate
|
||||||
|
|
||||||
|
*<c-p>*::
|
||||||
|
select previous completion candidate
|
||||||
|
|
||||||
|
*<c-x>*::
|
||||||
|
explicit insert completion query, followed by:
|
||||||
|
|
||||||
|
*f*:::
|
||||||
|
explicit file completion
|
||||||
|
|
||||||
|
*w*:::
|
||||||
|
explicit word completion
|
||||||
|
|
||||||
|
*l*:::
|
||||||
|
explicit line completion
|
||||||
|
|
||||||
|
*<c-o>*::
|
||||||
|
disable automatic completion for this insert session
|
||||||
|
|
||||||
|
*<c-r>*::
|
||||||
|
insert contents of the register given by next key
|
||||||
|
|
||||||
|
*<c-v>*::
|
||||||
|
insert next keystroke directly into the buffer, without interpreting it
|
||||||
|
|
||||||
|
*<c-u>*::
|
||||||
|
commit changes up to now as a single undo group
|
||||||
|
|
||||||
|
*<a-;>*::
|
||||||
|
escape to normal mode for a single command
|
||||||
|
|
||||||
|
Movement
|
||||||
|
--------
|
||||||
|
'word' is a sequence of alphanumeric characters or underscore, and 'WORD' is a sequence of non whitespace characters
|
||||||
|
|
||||||
|
*h*::
|
||||||
|
select the character on the left of selection end
|
||||||
|
|
||||||
|
*j*::
|
||||||
|
select the character below the selection end
|
||||||
|
|
||||||
|
*k*::
|
||||||
|
select the character above the selection end
|
||||||
|
|
||||||
|
*l*::
|
||||||
|
select the character on the right of selection end
|
||||||
|
|
||||||
|
*w*::
|
||||||
|
select the word and following whitespaces on the right of selection end
|
||||||
|
|
||||||
|
*b*::
|
||||||
|
select preceding whitespaces and the word on the left of selection end
|
||||||
|
|
||||||
|
*e*::
|
||||||
|
select preceding whitespaces and the word on the right of selection end
|
||||||
|
|
||||||
|
*<a-[wbe]>*::
|
||||||
|
same as [wbe] but select WORD instead of word
|
||||||
|
|
||||||
|
*f*::
|
||||||
|
select to the next occurence of given character
|
||||||
|
|
||||||
|
*t*::
|
||||||
|
select until the next occurence of given character
|
||||||
|
|
||||||
|
*<a-[ft]>*::
|
||||||
|
same as [ft] but in the other direction
|
||||||
|
|
||||||
|
*m*::
|
||||||
|
select to matching character
|
||||||
|
|
||||||
|
*M*::
|
||||||
|
extend selection to matching character
|
||||||
|
|
||||||
|
*x*::
|
||||||
|
select line on which selection end lies (or next line when end lies on an end-of-line)
|
||||||
|
|
||||||
|
*<a-x>*::
|
||||||
|
expand selections to contain full lines (including end-of-lines)
|
||||||
|
|
||||||
|
*<a-X>*::
|
||||||
|
trim selections to only contain full lines (not including last end-of-line)
|
||||||
|
|
||||||
|
*%*::
|
||||||
|
select whole buffer
|
||||||
|
|
||||||
|
*<a-h>*::
|
||||||
|
select to line begin
|
||||||
|
|
||||||
|
*<a-l>*::
|
||||||
|
select to line end
|
||||||
|
|
||||||
|
*/*::
|
||||||
|
search (select next match)
|
||||||
|
|
||||||
|
*<a-/>*::
|
||||||
|
search (select previous match)
|
||||||
|
|
||||||
|
*?*::
|
||||||
|
search (extend to next match)
|
||||||
|
|
||||||
|
*<a-?>*::
|
||||||
|
search (extend to previous match)
|
||||||
|
|
||||||
|
*n*::
|
||||||
|
select next match
|
||||||
|
|
||||||
|
*N*::
|
||||||
|
add a new selection with next match
|
||||||
|
|
||||||
|
*<a-n>*::
|
||||||
|
select previous match
|
||||||
|
|
||||||
|
*<a-N>*::
|
||||||
|
add a new selection with previous match
|
||||||
|
|
||||||
|
*pageup*::
|
||||||
|
scroll up
|
||||||
|
|
||||||
|
*pagedown*::
|
||||||
|
scroll down
|
||||||
|
|
||||||
|
*'*::
|
||||||
|
rotate selections (the main selection becomes the next one)
|
||||||
|
|
||||||
|
*;*::
|
||||||
|
reduce selections to their cursor
|
||||||
|
|
||||||
|
*<a-;>*::
|
||||||
|
flip the selections direction
|
||||||
|
|
||||||
|
*<a-:>*::
|
||||||
|
ensure selections are in forward direction (cursor after anchor)
|
||||||
|
|
||||||
|
Changes
|
||||||
|
-------
|
||||||
|
|
||||||
|
*i*::
|
||||||
|
enter insert mode before current selection
|
||||||
|
|
||||||
|
*a*::
|
||||||
|
enter insert mode after current selection
|
||||||
|
|
||||||
|
*d*::
|
||||||
|
yank and delete current selection
|
||||||
|
|
||||||
|
*c*::
|
||||||
|
yank and delete current selection and enter insert mode
|
||||||
|
|
||||||
|
*.*::
|
||||||
|
repeat last insert mode change (*i*, *a*, or *c*, including the inserted text)
|
||||||
|
|
||||||
|
*I*::
|
||||||
|
enter insert mode at current selection begin line start
|
||||||
|
|
||||||
|
*A*::
|
||||||
|
enter insert mode at current selection end line end
|
||||||
|
|
||||||
|
*o*::
|
||||||
|
enter insert mode in a new line below current selection end
|
||||||
|
|
||||||
|
*O*::
|
||||||
|
enter insert mode in a new line above current selection begin
|
||||||
|
|
||||||
|
*y*::
|
||||||
|
yank selections
|
||||||
|
|
||||||
|
*p*::
|
||||||
|
paste after current selection end
|
||||||
|
|
||||||
|
*P*::
|
||||||
|
paste before current selection begin
|
||||||
|
|
||||||
|
*<a-p>*::
|
||||||
|
paste all after current selection end, and select each pasted string
|
||||||
|
|
||||||
|
*<a-P>*::
|
||||||
|
paste all before current selection begin, and select each pasted string
|
||||||
|
|
||||||
|
*R*::
|
||||||
|
replace current selection with yanked text
|
||||||
|
|
||||||
|
*r*::
|
||||||
|
replace each character with the next entered one
|
||||||
|
|
||||||
|
*<a-j>*::
|
||||||
|
join selected lines
|
||||||
|
|
||||||
|
*<a-J>*::
|
||||||
|
join selected lines and select spaces inserted in place of line breaks
|
||||||
|
|
||||||
|
*>*::
|
||||||
|
indent selected lines
|
||||||
|
|
||||||
|
*<a->>*::
|
||||||
|
indent selected lines, including empty lines
|
||||||
|
|
||||||
|
*<*::
|
||||||
|
deindent selected lines
|
||||||
|
|
||||||
|
*<a-<>*::
|
||||||
|
deindent selected lines, do not remove incomplete indent (3 leading spaces when indent is 4)
|
||||||
|
|
||||||
|
*!*::
|
||||||
|
insert command output before selection
|
||||||
|
|
||||||
|
*a-!*::
|
||||||
|
append command output after selection
|
||||||
|
|
||||||
|
*u*::
|
||||||
|
undo last change
|
||||||
|
|
||||||
|
*U*::
|
||||||
|
redo last change
|
||||||
|
|
||||||
|
*&*::
|
||||||
|
align selection, align the cursor of selections by inserting spaces before the first character of the selection
|
||||||
|
|
||||||
|
*<a-&>*::
|
||||||
|
copy indent, copy the indentation of the main selection (or the count one if a count is given) to all other ones
|
||||||
|
|
||||||
|
*`*::
|
||||||
|
to lower case
|
||||||
|
|
||||||
|
*~*::
|
||||||
|
to upper case
|
||||||
|
|
||||||
|
*<a-`>*::
|
||||||
|
swap case
|
||||||
|
|
||||||
|
*@*::
|
||||||
|
convert tabs to spaces in current selections, uses the buffer tabstop option or the count parameter for tabstop
|
||||||
|
|
||||||
|
*<a-@>*::
|
||||||
|
convert spaces to tabs in current selections, uses the buffer tabstop option or the count parameter for tabstop
|
||||||
|
|
||||||
|
*<a-'>*::
|
||||||
|
rotate selections content, if specified, the count groups selections, so the following command
|
||||||
|
|
||||||
|
3<a-'>
|
||||||
|
|
||||||
|
rotate (1, 2, 3) and (3, 4, 6) independently
|
||||||
|
|
||||||
|
Goto Commands
|
||||||
|
-------------
|
||||||
|
If a count is given prior to hitting *g*, *g* will jump to the given line
|
||||||
|
|
||||||
|
*gh*::
|
||||||
|
select to line begin
|
||||||
|
|
||||||
|
*gl*::
|
||||||
|
select to line end
|
||||||
|
|
||||||
|
*gg*, *gk*::
|
||||||
|
go to the first line
|
||||||
|
|
||||||
|
*gj*::
|
||||||
|
go to the last line
|
||||||
|
|
||||||
|
*ge*::
|
||||||
|
go to last char of last line
|
||||||
|
|
||||||
|
*gt*::
|
||||||
|
go to the first displayed line
|
||||||
|
|
||||||
|
*gc*::
|
||||||
|
go to the middle displayed line
|
||||||
|
|
||||||
|
*gb*::
|
||||||
|
go to the last displayed line
|
||||||
|
|
||||||
|
*ga*::
|
||||||
|
go to the previous (alternate) buffer
|
||||||
|
|
||||||
|
*gf*::
|
||||||
|
open the file whose name is selected
|
||||||
|
|
||||||
|
*g.*::
|
||||||
|
go to last buffer modifiction position
|
||||||
|
|
||||||
|
View commands
|
||||||
|
-------------
|
||||||
|
|
||||||
|
*V*::
|
||||||
|
lock view mode until <esc> is hit
|
||||||
|
|
||||||
|
*vv*, *vc*::
|
||||||
|
center the main selection in the window
|
||||||
|
|
||||||
|
*vt*::
|
||||||
|
scroll to put the main selection on the top line of the window
|
||||||
|
|
||||||
|
*vb*::
|
||||||
|
scroll to put the main selection on the bottom line of the window
|
||||||
|
|
||||||
|
*vh*::
|
||||||
|
scroll the window count columns left
|
||||||
|
|
||||||
|
*vj*::
|
||||||
|
scroll the window count line downward
|
||||||
|
|
||||||
|
*vk*::
|
||||||
|
scroll the window count line upward
|
||||||
|
|
||||||
|
*vl*::
|
||||||
|
scroll the window count columns right
|
||||||
|
|
||||||
|
|
||||||
|
Marks
|
||||||
|
-----
|
||||||
|
Marks use the *^* register by default.
|
||||||
|
|
||||||
|
*Z*::
|
||||||
|
will save the current selections to the register
|
||||||
|
|
||||||
|
*z*::
|
||||||
|
will restore the selections from the register
|
||||||
|
|
||||||
|
*<a-z>*::
|
||||||
|
will add the selections from the register to the existing ones
|
||||||
|
|
||||||
|
Macros
|
||||||
|
------
|
||||||
|
Macros use the *@* register by default
|
||||||
|
|
||||||
|
*Q*::
|
||||||
|
record a macro
|
||||||
|
|
||||||
|
*q*::
|
||||||
|
play a recorded macro
|
||||||
|
|
||||||
|
Searching
|
||||||
|
---------
|
||||||
|
Searches use the */* register by default
|
||||||
|
|
||||||
|
***::
|
||||||
|
set the search pattern to the current selection (automatically detects word boundaries)
|
||||||
|
|
||||||
|
*<a-***>*::
|
||||||
|
set the search pattern to the current selection (verbatim, no smart detection)
|
||||||
|
|
||||||
|
Jump list
|
||||||
|
---------
|
||||||
|
|
||||||
|
*<c-i>*::
|
||||||
|
Jump forward
|
||||||
|
|
||||||
|
*<c-o>*::
|
||||||
|
Jump backward
|
||||||
|
|
||||||
|
*<c-s>*::
|
||||||
|
save current selections
|
||||||
|
|
||||||
|
Multiple selections
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
*s*::
|
||||||
|
create a selection
|
||||||
|
|
||||||
|
*<a-s>*::
|
||||||
|
split the current selections on line boundaries
|
||||||
|
|
||||||
|
*S*::
|
||||||
|
split the current selection
|
||||||
|
|
||||||
|
*C*::
|
||||||
|
copy the current selection to the next line
|
||||||
|
|
||||||
|
*<a-C>*::
|
||||||
|
copy the current selection to the previous line
|
||||||
|
|
||||||
|
*<space>*::
|
||||||
|
clear a multiple selection
|
||||||
|
|
||||||
|
*<a-space>*::
|
||||||
|
clear the current selection
|
||||||
|
|
||||||
|
*<a-k>*::
|
||||||
|
keep the selections that match the given regex
|
||||||
|
|
||||||
|
*<a-K>*::
|
||||||
|
clear selections that match the given regex
|
||||||
|
|
||||||
|
*|*::
|
||||||
|
pipe each selection through the given external filter program and replace the selection with its output
|
||||||
|
|
||||||
|
*<a-|>*::
|
||||||
|
pipe each selection through the given external filter program and ignore its output
|
||||||
|
|
||||||
|
*$*::
|
||||||
|
pipe each selection to the given shell command
|
||||||
|
|
||||||
|
Object Selection
|
||||||
|
----------------
|
||||||
|
|
||||||
|
*<a-a>*::
|
||||||
|
selects the whole object
|
||||||
|
|
||||||
|
*<a-i>*::
|
||||||
|
selects the inner object, that is the object excluding it's surrounder
|
||||||
|
|
||||||
|
*[*::
|
||||||
|
selects to object start
|
||||||
|
|
||||||
|
*]*::
|
||||||
|
selects to object end
|
||||||
|
|
||||||
|
*{*::
|
||||||
|
extends selections to object start
|
||||||
|
|
||||||
|
*}*::
|
||||||
|
extends selections to object end
|
||||||
|
.RE
|
||||||
|
|
||||||
|
After this key, you need to enter a second key in order to specify which object you want
|
||||||
|
|
||||||
|
*b*, *(*, *)*::
|
||||||
|
select the enclosing parenthesis
|
||||||
|
|
||||||
|
*B*, *{*, *}*::
|
||||||
|
select the enclosing {} block
|
||||||
|
|
||||||
|
*r*, *[*, *]*::
|
||||||
|
select the enclosing [] block
|
||||||
|
|
||||||
|
*a*, *<*, *>*::
|
||||||
|
select the enclosing <> block
|
||||||
|
|
||||||
|
*"*::
|
||||||
|
select the enclosing double quoted string
|
||||||
|
|
||||||
|
*'*::
|
||||||
|
select the enclosing single quoted string
|
||||||
|
|
||||||
|
*`*::
|
||||||
|
select the enclosing grave quoted string
|
||||||
|
|
||||||
|
*w*::
|
||||||
|
select the whole word
|
||||||
|
|
||||||
|
*W*::
|
||||||
|
select the whole WORD
|
||||||
|
|
||||||
|
*s*::
|
||||||
|
select the sentence
|
||||||
|
|
||||||
|
*p*::
|
||||||
|
select the paragraph
|
||||||
|
|
||||||
|
*␣*::
|
||||||
|
select the whitespaces
|
||||||
|
|
||||||
|
*i*::
|
||||||
|
select the current indentation block
|
||||||
|
|
||||||
|
*n*::
|
||||||
|
select the number
|
||||||
|
|
||||||
|
*:*::
|
||||||
|
select user defined object, will prompt for open and close text
|
||||||
|
|
||||||
|
Prompt Commands
|
||||||
|
---------------
|
||||||
|
|
||||||
|
*<ret>*::
|
||||||
|
validate prompt
|
||||||
|
|
||||||
|
*<esc>*::
|
||||||
|
abandon without
|
||||||
|
|
||||||
|
*<left>*, *<a-h>*::
|
||||||
|
move cursor to previous character
|
||||||
|
|
||||||
|
*<right>*, *<a-l>*::
|
||||||
|
move cursor to previous character
|
||||||
|
|
||||||
|
*<home>*::
|
||||||
|
move cursor to first character
|
||||||
|
|
||||||
|
*<end>*::
|
||||||
|
move cursor to passed last character
|
||||||
|
|
||||||
|
*<backspace>*, *<a-x>*::
|
||||||
|
erase character before cursor
|
||||||
|
|
||||||
|
*<del>*, *<a-d>*::
|
||||||
|
erase character under cursor
|
||||||
|
|
||||||
|
*<c-w>*::
|
||||||
|
avance to next word begin
|
||||||
|
|
||||||
|
*<c-a-w>*::
|
||||||
|
advance to next WORD begin
|
||||||
|
|
||||||
|
*<c-b>*::
|
||||||
|
go back to previous word begin
|
||||||
|
|
||||||
|
*<c-a-b>*::
|
||||||
|
go back to previous WORD begin
|
||||||
|
|
||||||
|
*<c-e>*::
|
||||||
|
advance to next word end
|
||||||
|
|
||||||
|
*<c-a-e>*::
|
||||||
|
advance to next word end
|
||||||
|
|
||||||
|
*<up>*, *<c-p>*::
|
||||||
|
select previous entry in history
|
||||||
|
|
||||||
|
*<down>*, *<c-n>*::
|
||||||
|
select next entry in history
|
||||||
|
|
||||||
|
*<tab>*::
|
||||||
|
select next completion candidate
|
||||||
|
|
||||||
|
*<backtab>*::
|
||||||
|
select previous completion candidate
|
||||||
|
|
||||||
|
*<c-r>*::
|
||||||
|
insert then content of the register given by next key
|
||||||
|
|
||||||
|
*<c-v>*::
|
||||||
|
insert next keystroke without interpretting it
|
||||||
|
|
||||||
|
*<c-o>*::
|
||||||
|
disable auto completion for this prompt
|
||||||
|
|
||||||
|
Key mapping
|
||||||
|
-----------
|
||||||
|
Mapping a combination of keys to another one (a.k.a. key mapping or binding) can be done with the following command:
|
||||||
|
|
||||||
|
-------------------------------
|
||||||
|
map <scope> <mode> <key> <keys>
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
*scope*::
|
||||||
|
can be one of *global*, *window* or *buffer*
|
||||||
|
|
||||||
|
*mode*::
|
||||||
|
can be one of *insert*, *normal*, *prompt*, *menu*, *user* or a one character long arbitrary prefix (the
|
||||||
|
*user* mode uses the *,* prefix)
|
||||||
|
|
||||||
|
*key*::
|
||||||
|
the key to which the combination will be bound
|
||||||
|
|
||||||
|
*keys*::
|
||||||
|
string that lists the keys that will be executed when *key* is hit
|
||||||
|
|
||||||
|
Keys are always executed within the *normal* mode.
|
||||||
51
rc/doc.kak
Normal file
51
rc/doc.kak
Normal file
|
|
@ -0,0 +1,51 @@
|
||||||
|
|
||||||
|
decl str doc_path "/usr/share/doc/kak/manpages"
|
||||||
|
|
||||||
|
def -hidden -params 1..2 _doc-open %{
|
||||||
|
%sh{
|
||||||
|
manout=$(mktemp /tmp/kak-man-XXXXXX)
|
||||||
|
colout=$(mktemp /tmp/kak-man-XXXXXX)
|
||||||
|
|
||||||
|
MANWIDTH=${kak_window_width} man -l "$1" > $manout
|
||||||
|
retval=$?
|
||||||
|
|
||||||
|
col -b -x > ${colout} < ${manout}
|
||||||
|
rm ${manout}
|
||||||
|
|
||||||
|
if [ "${retval}" -eq 0 ]; then
|
||||||
|
echo "
|
||||||
|
edit! -scratch '*doc*'
|
||||||
|
exec |cat<space>${colout}<ret>gg
|
||||||
|
nop %sh{rm ${colout}}
|
||||||
|
set buffer filetype man
|
||||||
|
"
|
||||||
|
|
||||||
|
if [ $# -gt 1 ]; then
|
||||||
|
echo "try %{ exec '%<a-s><a-k>(?i)^\h+[^\n]*?\Q${2}\E<ret>\'' } catch %{ exec <space>gg }"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo "echo -color Error %{doc '$@' failed: see *debug* buffer for details}"
|
||||||
|
rm ${colout}
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
def -params 1..2 \
|
||||||
|
-shell-completion %{
|
||||||
|
find "${kak_opt_doc_path}" -type f -iname "*$@*.gz" -printf '%f\n' | while read l; do
|
||||||
|
echo "${l%.*}"
|
||||||
|
done
|
||||||
|
} \
|
||||||
|
doc -docstring "Open a buffer containing the documentation about a given subject" %{
|
||||||
|
%sh{
|
||||||
|
readonly PATH_DOC="${kak_opt_doc_path}/${1}.gz"
|
||||||
|
|
||||||
|
shift
|
||||||
|
if [ ! -f "${PATH_DOC}" ]; then
|
||||||
|
echo "echo -color Error No such doc file: ${PATH_DOC}"
|
||||||
|
exit
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "eval -try-client %opt{docsclient} _doc-open ${PATH_DOC} $@"
|
||||||
|
}
|
||||||
|
}
|
||||||
29
src/Makefile
29
src/Makefile
|
|
@ -20,6 +20,15 @@ endif
|
||||||
sources := $(wildcard *.cc)
|
sources := $(wildcard *.cc)
|
||||||
objects := $(addprefix ., $(sources:.cc=$(suffix).o))
|
objects := $(addprefix ., $(sources:.cc=$(suffix).o))
|
||||||
deps := $(addprefix ., $(sources:.cc=$(suffix).d))
|
deps := $(addprefix ., $(sources:.cc=$(suffix).d))
|
||||||
|
docs := commands \
|
||||||
|
execeval \
|
||||||
|
expansions \
|
||||||
|
faces \
|
||||||
|
highlighters \
|
||||||
|
hooks \
|
||||||
|
options \
|
||||||
|
registers \
|
||||||
|
shortcuts \
|
||||||
|
|
||||||
PREFIX ?= /usr/local
|
PREFIX ?= /usr/local
|
||||||
DESTDIR ?= # root dir
|
DESTDIR ?= # root dir
|
||||||
|
|
@ -29,6 +38,7 @@ NCURSESW_INCLUDE ?= /usr/include/ncursesw
|
||||||
bindir := $(DESTDIR)$(PREFIX)/bin
|
bindir := $(DESTDIR)$(PREFIX)/bin
|
||||||
sharedir := $(DESTDIR)$(PREFIX)/share/kak
|
sharedir := $(DESTDIR)$(PREFIX)/share/kak
|
||||||
docdir := $(DESTDIR)$(PREFIX)/share/doc/kak
|
docdir := $(DESTDIR)$(PREFIX)/share/doc/kak
|
||||||
|
mandir := $(DESTDIR)$(PREFIX)/man/man1
|
||||||
|
|
||||||
os := $(shell uname)
|
os := $(shell uname)
|
||||||
|
|
||||||
|
|
@ -62,17 +72,33 @@ kak : $(objects)
|
||||||
.%$(suffix).o: %.cc
|
.%$(suffix).o: %.cc
|
||||||
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -MD -MP -MF $(addprefix ., $(<:.cc=$(suffix).d)) -c -o $@ $<
|
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -MD -MP -MF $(addprefix ., $(<:.cc=$(suffix).d)) -c -o $@ $<
|
||||||
|
|
||||||
|
%.1: %
|
||||||
|
a2x -f manpage $<
|
||||||
|
%.1.gz: %.1.txt
|
||||||
|
a2x -f manpage $<
|
||||||
|
gzip -f $(basename $<)
|
||||||
|
|
||||||
test:
|
test:
|
||||||
cd ../test && ./run
|
cd ../test && ./run
|
||||||
tags:
|
tags:
|
||||||
ctags -R
|
ctags -R
|
||||||
|
|
||||||
|
man: ../doc/kakoune.1.gz
|
||||||
|
doc: $(addsuffix .1,$(addprefix ../doc/manpages/,$(docs)))
|
||||||
|
@for f in $^; do \
|
||||||
|
pagename="$${f##*/}"; pagename="$${pagename%.*}"; \
|
||||||
|
sed -i -r -e "s,^\.TH .+,.TH KAKOUNE 1 \"\" \"\" \"$${pagename^^}\"," \
|
||||||
|
-e "/^\.SH \"NAME\"/,+1d" $$f; \
|
||||||
|
gzip -f "$$f"; \
|
||||||
|
mv "$${f}.gz" "$${f/.1/}.gz"; \
|
||||||
|
done
|
||||||
|
|
||||||
clean:
|
clean:
|
||||||
rm -f .*.o .*.d kak tags
|
rm -f .*.o .*.d kak tags
|
||||||
|
|
||||||
XDG_CONFIG_HOME ?= $(HOME)/.config
|
XDG_CONFIG_HOME ?= $(HOME)/.config
|
||||||
|
|
||||||
install: kak
|
install: kak man doc
|
||||||
mkdir -p $(bindir)
|
mkdir -p $(bindir)
|
||||||
install -m 0755 kak $(bindir)
|
install -m 0755 kak $(bindir)
|
||||||
mkdir -p $(sharedir)/rc
|
mkdir -p $(sharedir)/rc
|
||||||
|
|
@ -84,5 +110,6 @@ install: kak
|
||||||
mkdir -p $(docdir)
|
mkdir -p $(docdir)
|
||||||
install -m 0644 ../README.asciidoc $(docdir)
|
install -m 0644 ../README.asciidoc $(docdir)
|
||||||
install -m 0644 ../doc/* $(docdir)
|
install -m 0644 ../doc/* $(docdir)
|
||||||
|
install -m 0644 ../doc/kakoune.1.gz $(mandir)
|
||||||
|
|
||||||
.PHONY: tags install
|
.PHONY: tags install
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user