Document missing commands, fix rendering issues

This commit is contained in:
Frank LENORMAND 2016-03-12 11:13:49 +02:00
parent d554af7f0e
commit f32fe6c4cd
5 changed files with 105 additions and 46 deletions

View File

@ -585,25 +585,35 @@ saved in the command history.
Basic Commands Basic Commands
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
* `e[dit] <filename> [<line> [<column>]]`: open buffer on file, go to given Some commands take an esclamation mark (`!`), which can be used to force
the execution of the command (i.e. to quit a modified buffer, the
command `q!` has to be used).
* `cd <directory>`: change the current directory to the one passed
* `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. line and column. If file is already opened, just switch to this file.
use edit! to force reloading. use edit! to force reloading.
* `w[rite] [<filename>]`: write buffer to <filename> or use it's name if * `w[rite] [<filename>]`: write buffer to <filename> or use it's name if
filename is not given. filename is not given.
* `w[rite]a[ll]`: write all buffers that are associated to a file. * `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 * `q[uit][!]`: exit Kakoune, use quit! to force quitting even if there is some
unsaved buffers remaining. unsaved buffers remaining.
* `wq`: write current buffer and quit * `kill`: terminate the current session, all the clients as well as the server
* `w[a]q[!]`: write the current buffer (or all buffers when `waq` is used) and quit
* `b[uffer] <name>`: switch to buffer <name> * `b[uffer] <name>`: switch to buffer <name>
* `d[el]b[uf] [<name>]`: delete the buffer <name>, use d[el]b[uf]! to force * `b[uffer]n[ext]`: switch to the next buffer
deleting a modified buffer. * `b[uffer]p[rev]`: switch to the previous buffer
* `d[el]b[uf][!] [<name>]`: delete the buffer <name>
* `source <filename>`: execute commands in <filename> * `source <filename>`: execute commands in <filename>
* `runtime <filename>`: execute commands in <filename>, <filename> * `runtime <filename>`: execute commands in <filename>, <filename>
is relative to kak executable path. is relative to kak executable path.
* `colorscheme <name>`: load named colorscheme. * `colorscheme <name>`: load named colorscheme.
* `nameclient <name>`: set current client name * `nameclient <name>`: set current client name
* `namebuf <name>`: set current buffer name * `namebuf <name>`: set current buffer name
* `echo <text>`: show <text> in status line * `echo [options] <text>`: show <text> in status line, with the following options:
** `-color` <face>: print the given text with <face>, most commonly `Error` or `Information`
** `-markup`: expand the markup strings in <text>
** `-debug`: print the given text to the `\*debug*` buffer
* `nop`: does nothing, but as with every other commands, arguments may be * `nop`: does nothing, but as with every other commands, arguments may be
evaluated. So nop can be used for example to execute a shell command evaluated. So nop can be used for example to execute a shell command
while being sure that it's output will not be interpreted by kak. while being sure that it's output will not be interpreted by kak.
@ -1375,24 +1385,28 @@ Kakoune state:
Some helper commands can be used to define composite commands: Some helper commands can be used to define composite commands:
* `:prompt <prompt> <register> <command>`: Prompt the user for a string, when * `prompt <prompt> <register> <command>`: Prompt the user for a string, when
the user validates, store the result in given <register> and run <commmand>. the user validates, store the result in given <register> and run <commmand>.
the -init <str> switch allows setting initial content. the -init <str> switch allows setting initial content.
* `:onkey <register> <command>`: Wait for next key from user, writes it into given * `onkey <register> <command>`: Wait for next key from user, writes it into given
<register> and execute commands. <register> and execute commands.
* `:menu <label1> <commands1> <label2> <commands2>...`: display a menu using * `menu <label1> <commands1> <label2> <commands2>...`: display a menu using
labels, the selected label's commands are executed. labels, the selected label's commands are executed.
`menu` can take a -auto-single argument, to automatically run commands `menu` can take a -auto-single argument, to automatically run commands
when only one choice is provided. and a -select-cmds argument, in which 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 case menu takes three argument per item, the last one being a command
to execute when the item is selected (but not validated). to execute when the item is selected (but not validated).
* `:info <text>`: display text in an information box, at can take a -anchor * `info <text>`: display text in an information box, at can take a -anchor
option, which accepts `left`, `right` and `cursor` as value, in order to 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. specify where the info box should be anchored relative to the main selection.
* `:try <commands> catch <on_error_commands>`: prevent an error in <commands> * `try <commands> catch <on_error_commands>`: prevent an error in <commands>
from aborting the whole commands execution, execute <on_error_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. instead. If nothing is to be done on error, the catch part can be ommitted.
* `:reg <name> <content>`: set register <name> to <content> * `reg <name> <content>`: set register <name> to <content>
* `select <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...`:
replace the current selections with the one described in the argument
* `debug {info,buffers,options,memory,shared-strings}`: print some debug
information in the `*debug*` buffer
Note that these commands are available in interactive command mode, but are Note that these commands are available in interactive command mode, but are
not that useful in this context. not that useful in this context.

View File

@ -7,7 +7,15 @@ commands - a
Primitives Primitives
---------- ----------
*e[dit]* <filename> [<line> [<column>]]::
Some commands take an esclamation mark (*!*), which can be used to force
the execution of the command (i.e. to quit a modified buffer, the
command *q!* has to be used).
*cd* <directory>::
change the current directory to the one passed
*e[dit][!]* <filename> [<line> [<column>]]::
open buffer on file, go to given line and column. If file is already 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 opened, just switch to this file. Use edit! to force reloading
@ -17,19 +25,27 @@ Primitives
*w[rite]a[ll]*:: *w[rite]a[ll]*::
write all buffers that are associated to a file write all buffers that are associated to a file
*q[uit]*:: *q[uit][!]*::
exit Kakoune, use quit! to force quitting even if there is some exit Kakoune, use quit! to force quitting even if there is some
unsaved buffers remaining unsaved buffers remaining
*wq*:: *kill*::
write current buffer and quit terminate the current session, all the clients as well as the server
*w[a]q[!]*::
write the current buffer (or all buffers when *waq* is used) and quit
*b[uffer]* <name>:: *b[uffer]* <name>::
switch to buffer <name> switch to buffer <name>
*d[el]b[uf]* [<name>]:: *b[uffer]n[ext]*::
delete the buffer <name>, use d[el]b[uf]! to force deleting a switch to the next buffer
modified buffer
*b[uffer]p[rev]*::
switch to the previous buffer
*d[el]b[uf][!]* [<name>]::
delete the buffer <name>
*source* <filename>:: *source* <filename>::
execute commands in <filename> execute commands in <filename>
@ -47,8 +63,17 @@ Primitives
*namebuf* <name>:: *namebuf* <name>::
set current buffer name set current buffer name
*echo* <text>:: *echo* [options] <text>::
show <text> in status line show *text* in status line, with the following *options*:
*-color* <face>:::
print the given text with *face*, most commonly *Error* or *Information*
*-markup*:::
expand the markup strings in *text* (c.f. the 'expansions' documentation page)
*-debug*:::
print the given text to the *\*debug** buffer
*nop*:: *nop*::
does nothing, but arguments will be evaluated (e.g. shell expansion) does nothing, but arguments will be evaluated (e.g. shell expansion)
@ -56,6 +81,9 @@ Primitives
*set* <scope> <name> <value>:: *set* <scope> <name> <value>::
change the value of an option (c.f. the 'options' documentation page) change the value of an option (c.f. the 'options' documentation page)
*unset* <scope> <name>::
unset the value of an option (c.f. the 'options' documentation page)
*alias* <scope> <name> <command>:: *alias* <scope> <name> <command>::
define a new alias, within the context of a scope define a new alias, within the context of a scope
@ -123,10 +151,17 @@ commands:
last one being a command to execute when the item is selected (but last one being a command to execute when the item is selected (but
not validated) not validated)
*info* <text>:: *info* [options] <text>::
display text in an information box, at can take an *-anchor* option, display text in an information box with the following *options*:
which accepts left, right and cursor as value, in order to specify
where the info box should be anchored relative to the main selection *-anchor* <line>.<column>:::
print the text at the given coordinates
*-placement* {above,below}:::
set the placement relative to the anchor
*-title* <text>:::
set the title of the message box
*try* <commands> catch <on_error_commands>:: *try* <commands> catch <on_error_commands>::
prevent an error in *commands* from aborting the whole commands prevent an error in *commands* from aborting the whole commands
@ -136,6 +171,12 @@ commands:
*reg* <name> <content>:: *reg* <name> <content>::
set register *name* to *content* set register *name* to *content*
*select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...::
replace the current selections with the one described in the argument
*debug* {info,buffers,options,memory,shared-strings}::
print some debug information in the *\*debug** buffer
Note that those commands are also available in the interactive mode, but Note that those commands are also available in the interactive mode, but
are not really useful in that context. are not really useful in that context.
@ -153,30 +194,30 @@ New commands can be defined using the *def* command:
*commands* is a string containing the commands to execute, and *flags* *commands* is a string containing the commands to execute, and *flags*
can be any combination of the following parameters: can be any combination of the following parameters:
*-params* <num>:: *-params* <num>:::
the command accepts a *num* parameter, which can be either a number, the command accepts a *num* parameter, which can be either a number,
or of the form <min>..<max>, with both <min> and <max> omittable or of the form <min>..<max>, with both <min> and <max> omittable
*-file-completion*:: *-file-completion*:::
try file completion on any parameter passed to this command try file completion on any parameter passed to this command
*-client-completion*:: *-client-completion*:::
try client name completion on any parameter passed to this command try client name completion on any parameter passed to this command
*-buffer-completion*:: *-buffer-completion*:::
try buffer name completion on any parameter passed to this command try buffer name completion on any parameter passed to this command
*-shell-completion*:: *-shell-completion*:::
following string is a shell command which takes parameters as following string is a shell command which takes parameters as
positional params and output one completion candidate per line positional params and output one completion candidate per line
*-allow-override*:: *-allow-override*:::
allow the new command to replace an exisiting one with the same name allow the new command to replace an exisiting one with the same name
*-hidden*:: *-hidden*:::
do not show the command in command name completions do not show the command in command name completions
*-docstring*:: *-docstring*:::
define the documentation string for the command define the documentation string for the command
Using shell expansion allows to define complex commands or to access Kakoune Using shell expansion allows to define complex commands or to access Kakoune

View File

@ -8,7 +8,7 @@ expansions - a
Strings Strings
------- -------
\'strings':: \'strings'::
uninterpreted strings, use a backslash (\\') to escape the separator uninterpreted strings, use a backslash (\') to escape the separator
"strings":: "strings"::
expanded strings, % strings (c.f. next section) contained are expended, expanded strings, % strings (c.f. next section) contained are expended,
use a backslash (\\%) to escape the separator use a backslash (\\%) to escape the separator

View File

@ -18,7 +18,7 @@ addhl <highlighter_name> <highlighter_parameters> ...
and and
----------------------- -----------------------
*rmhl* <highlighter_id> rmhl <highlighter_id>
----------------------- -----------------------
*highlighter_id* is a name generated by the highlighter specified with *highlighter_id* is a name generated by the highlighter specified with
@ -32,7 +32,9 @@ General highlighters
highlight a regex, takes the regex as first parameter, followed by highlight a regex, takes the regex as first parameter, followed by
any number of face parameters. For example: any number of face parameters. For example:
-----------------------------------------------------
addhl regex //(\hTODO:)?[^\n] 0:cyan 1:yellow,red addhl regex //(\hTODO:)?[^\n] 0:cyan 1:yellow,red
-----------------------------------------------------
will highlight C++ style comments in cyan, with an eventual 'TODO:' will highlight C++ style comments in cyan, with an eventual 'TODO:'
in yellow on red background in yellow on red background

View File

@ -225,7 +225,7 @@ Changes
*>*:: *>*::
indent selected lines indent selected lines
*<a->>*:: *<a\->>*::
indent selected lines, including empty lines indent selected lines, including empty lines
*<*:: *<*::
@ -284,7 +284,9 @@ Changes
rotate selections content, if specified, the count groups selections, rotate selections content, if specified, the count groups selections,
so the following command so the following command
----------
3<a-'> 3<a-'>
----------
rotate (1, 2, 3) and (3, 4, 6) independently rotate (1, 2, 3) and (3, 4, 6) independently