diff --git a/doc/kakoune.1.txt b/doc/kakoune.1.txt new file mode 100644 index 00000000..86f64a0b --- /dev/null +++ b/doc/kakoune.1.txt @@ -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 :: + execute argument on initialisation + +-f :: + act as a filter, executing given keys on given files + +-p :: + just send stdin as commands to the given session + +-c :: + connect to given session + +-s :: + 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" *.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. diff --git a/doc/manpages/commands b/doc/manpages/commands new file mode 100644 index 00000000..d5c599da --- /dev/null +++ b/doc/manpages/commands @@ -0,0 +1,154 @@ +KAKOUNE(1) +========== + +NAME +---- +commands - a + +Primitives +---------- +*e[dit]* [ []]:: + 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]* []:: + write buffer to 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]* :: + switch to buffer + +*d[el]b[uf]* []:: + delete the buffer , use d[el]b[uf]! to force deleting a modified buffer + +*source* :: + execute commands in + +*runtime* :: + execute commands in , is relative to kak executable path + +*colorscheme* :: + load named colorscheme + +*nameclient* :: + set current client name + +*namebuf* :: + set current buffer name + +*echo* :: + show in status line + +*nop*:: + does nothing, but arguments will be evaluated (e.g. shell expansion) + +*set* :: + change the value of an option (c.f. the 'options' documentation page) + +*alias* :: + define a new alias, within the context of a scope + +*unalias* []:: + remove an alias if its current value is the same as the one passed as an optional parameter, remove it unconditionally otherwise + +*decl* [-hidden] []:: + declare a new option, the -hidden hides the option in completion suggestions (c.f. the 'options' documentation page) + +*face* :: + define a face (c.f. the 'faces' documentation page) + +*exec* [] ...:: + execute a series of keys, as if they were hit (c.f. the 'execeval' documentation page) + +*eval* [] ...:: + execute commands, as if they were entered in the command prompt (c.f. the 'execeval' documentation page) + +*def* [] :: + define a new command (c.f. the 'Declaring new commands' section below) + +*map* :: + bind a combination of keys to another one (c.f. the 'commands' documentation page) + +*hook* [-group ] :: + execute a command whenever an event is triggered (c.f. the 'hooks' documentation page) + +*rmhooks* :: + remove every hooks in *scope* that are part of the given *group* (c.f. the 'hooks' documentation page) + +*addhl* [] ...:: + add a highlighter to the current window (c.f. the 'highlighters' documentation page) + +*rmhl* :: + 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 the user for a string, when the user validates, store the result in given *register* and run *commmand*. the *-init * switch allows setting initial content + +*onkey* :: + wait for next key from user, writes it into given and execute commands + +*menu* ...:: + 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* :: + 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* catch :: + 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* :: + 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] :: + *commands* is a string containing the commands to execute, and *flags* can be any combination of the following parameters: + +*-params* :: + the command accepts a *num* parameter, which can be either a number, or of the form .., with both and 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} } }" +-------------------------------------------------------- diff --git a/doc/manpages/execeval b/doc/manpages/execeval new file mode 100644 index 00000000..fb2144fc --- /dev/null +++ b/doc/manpages/execeval @@ -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 [] ... +eval [] ... +---------------------------- + +*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* :: + execute in the context of the client named *name* + +*-try-client* :: + 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* :: + 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 is a string of registers to be restored after execution diff --git a/doc/manpages/expansions b/doc/manpages/expansions new file mode 100644 index 00000000..1f48462c --- /dev/null +++ b/doc/manpages/expansions @@ -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! +---------------------------------------------------------- + * 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_*:: + value of option *name* +*kak_reg_*:: + value of register *r* +*kak_socket*:: + filename of session socket ('/tmp/kak-') +*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_*:: + 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 ('\\'). diff --git a/doc/manpages/faces b/doc/manpages/faces new file mode 100644 index 00000000..b3a43b1d --- /dev/null +++ b/doc/manpages/faces @@ -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 diff --git a/doc/manpages/highlighters b/doc/manpages/highlighters new file mode 100644 index 00000000..344504fa --- /dev/null +++ b/doc/manpages/highlighters @@ -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 ... +------------------------------------------------------- + +and + +----------------------- +*rmhl* +----------------------- + +*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* : ...:: + 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* :: + add a column in front of text, and display the given flag in it for everly line contained in the int-list option named + +*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* ::: + specify a string to separate the line numbers column with the rest of the buffer (default is '|') + +*fill* :: + 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 +-------------------- + +The *-group* switch of the *addhl* command provides a mean to add highlighters inside this group: + +---------------------------------------- +addhl -group ... +---------------------------------------- + +Groups can contain other groups, the *-group* switch can be used to define a path as follows: + +-------------------------------------------------- +addhl -group group +addhl -group / ... +-------------------------------------------------- + +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 + ... +----------------------------------------------------------------------- + +defines multiple regions in which other highlighters can be added as follows: + +--------------------------------------- +addhl -group / ... +--------------------------------------- + +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 * 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 \ + string \ + comment + +addhl -group /code ... +addhl -group /string ... +addhl -group /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 / ... +-------------------------------- + +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 +addhl -group /name regex ... +------------------------------ + +It can then be referenced in a window using the ref highlighter. + +------------------ +addhl ref +------------------ + +The ref can reference any named highlighter in the shared namespace. diff --git a/doc/manpages/hooks b/doc/manpages/hooks new file mode 100644 index 00000000..a7dd6e63 --- /dev/null +++ b/doc/manpages/hooks @@ -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 ] +---------------------------------------------------------------------- + +*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 +----------------------- + +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 *=* + +*BufSetOption*:: + an option was set in a buffer context, the filtering text is *=* + +*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. diff --git a/doc/manpages/options b/doc/manpages/options new file mode 100644 index 00000000..483c2fc0 --- /dev/null +++ b/doc/manpages/options @@ -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=*::: + where *opt-name* is a 'str-list' option. The first element of the list should follow the format: + + .[+]@ + + 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 diff --git a/doc/manpages/registers b/doc/manpages/registers new file mode 100644 index 00000000..445c8476 --- /dev/null +++ b/doc/manpages/registers @@ -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 +----------- +**:: + when in insert mode or in a prompt, insert the value stored in the *c* register (single character) + +*"*:: + in normal mode, select the ** 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, ...) diff --git a/doc/manpages/shortcuts b/doc/manpages/shortcuts new file mode 100644 index 00000000..b47f5a94 --- /dev/null +++ b/doc/manpages/shortcuts @@ -0,0 +1,578 @@ +KAKOUNE(1) +========== + +NAME +---- +shortcuts - a + +Insert mode +----------- +**:: + leave insert mode + +**:: + delete characters before cursors + +**:: + delete characters under cursors + +**, **, **, **:: + move the cursors in given direction + +**:: + move cursors to line begin + +**:: + move cursors to end of line + +**:: + select next completion candidate + +**:: + select previous completion candidate + +**:: + explicit insert completion query, followed by: + + *f*::: + explicit file completion + + *w*::: + explicit word completion + + *l*::: + explicit line completion + +**:: + disable automatic completion for this insert session + +**:: + insert contents of the register given by next key + +**:: + insert next keystroke directly into the buffer, without interpreting it + +**:: + commit changes up to now as a single undo group + +**:: + 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 + +**:: + 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 + +**:: + 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) + +**:: + expand selections to contain full lines (including end-of-lines) + +**:: + trim selections to only contain full lines (not including last end-of-line) + +*%*:: + select whole buffer + +**:: + select to line begin + +**:: + select to line end + +*/*:: + search (select next match) + +**:: + search (select previous match) + +*?*:: + search (extend to next match) + +**:: + search (extend to previous match) + +*n*:: + select next match + +*N*:: + add a new selection with next match + +**:: + select previous match + +**:: + 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 + +**:: + flip the selections direction + +**:: + 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 + +**:: + paste all after current selection end, and select each pasted string + +**:: + 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 + +**:: + join selected lines + +**:: + join selected lines and select spaces inserted in place of line breaks + +*>*:: + indent selected lines + +*>*:: + indent selected lines, including empty lines + +*<*:: + deindent selected lines + +**:: + 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 + +**:: + 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 + +**:: + swap case + +*@*:: + convert tabs to spaces in current selections, uses the buffer tabstop option or the count parameter for tabstop + +**:: + convert spaces to tabs in current selections, uses the buffer tabstop option or the count parameter for tabstop + +**:: + rotate selections content, if specified, the count groups selections, so the following command + + 3 + + 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 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 + +**:: + 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) + +**:: + set the search pattern to the current selection (verbatim, no smart detection) + +Jump list +--------- + +**:: + Jump forward + +**:: + Jump backward + +**:: + save current selections + +Multiple selections +------------------- + +*s*:: + create a selection + +**:: + split the current selections on line boundaries + +*S*:: + split the current selection + +*C*:: + copy the current selection to the next line + +**:: + copy the current selection to the previous line + +**:: + clear a multiple selection + +**:: + clear the current selection + +**:: + keep the selections that match the given regex + +**:: + clear selections that match the given regex + +*|*:: + pipe each selection through the given external filter program and replace the selection with its output + +**:: + pipe each selection through the given external filter program and ignore its output + +*$*:: + pipe each selection to the given shell command + +Object Selection +---------------- + +**:: + selects the whole object + +**:: + 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 +--------------- + +**:: + validate prompt + +**:: + abandon without + +**, **:: + move cursor to previous character + +**, **:: + move cursor to previous character + +**:: + move cursor to first character + +**:: + move cursor to passed last character + +**, **:: + erase character before cursor + +**, **:: + erase character under cursor + +**:: + avance to next word begin + +**:: + advance to next WORD begin + +**:: + go back to previous word begin + +**:: + go back to previous WORD begin + +**:: + advance to next word end + +**:: + advance to next word end + +**, **:: + select previous entry in history + +**, **:: + select next entry in history + +**:: + select next completion candidate + +**:: + select previous completion candidate + +**:: + insert then content of the register given by next key + +**:: + insert next keystroke without interpretting it + +**:: + 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*:: + 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. diff --git a/rc/doc.kak b/rc/doc.kak new file mode 100644 index 00000000..97811145 --- /dev/null +++ b/rc/doc.kak @@ -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${colout}gg + nop %sh{rm ${colout}} + set buffer filetype man + " + + if [ $# -gt 1 ]; then + echo "try %{ exec '%(?i)^\h+[^\n]*?\Q${2}\E\'' } catch %{ exec 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} $@" + } +} diff --git a/src/Makefile b/src/Makefile index d74bf368..c0de3aa7 100644 --- a/src/Makefile +++ b/src/Makefile @@ -20,6 +20,15 @@ endif sources := $(wildcard *.cc) objects := $(addprefix ., $(sources:.cc=$(suffix).o)) deps := $(addprefix ., $(sources:.cc=$(suffix).d)) +docs := commands \ + execeval \ + expansions \ + faces \ + highlighters \ + hooks \ + options \ + registers \ + shortcuts \ PREFIX ?= /usr/local DESTDIR ?= # root dir @@ -29,6 +38,7 @@ NCURSESW_INCLUDE ?= /usr/include/ncursesw bindir := $(DESTDIR)$(PREFIX)/bin sharedir := $(DESTDIR)$(PREFIX)/share/kak docdir := $(DESTDIR)$(PREFIX)/share/doc/kak +mandir := $(DESTDIR)$(PREFIX)/man/man1 os := $(shell uname) @@ -62,17 +72,33 @@ kak : $(objects) .%$(suffix).o: %.cc $(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: cd ../test && ./run tags: 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: rm -f .*.o .*.d kak tags XDG_CONFIG_HOME ?= $(HOME)/.config -install: kak +install: kak man doc mkdir -p $(bindir) install -m 0755 kak $(bindir) mkdir -p $(sharedir)/rc @@ -84,5 +110,6 @@ install: kak mkdir -p $(docdir) install -m 0644 ../README.asciidoc $(docdir) install -m 0644 ../doc/* $(docdir) + install -m 0644 ../doc/kakoune.1.gz $(mandir) .PHONY: tags install