From f32fe6c4cdfc0148935f4d97cf29803064a1fa98 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Sat, 12 Mar 2016 11:13:49 +0200 Subject: [PATCH] Document missing commands, fix rendering issues --- README.asciidoc | 54 ++++++++++++------- doc/manpages/commands.asciidoc | 83 ++++++++++++++++++++++-------- doc/manpages/expansions.asciidoc | 2 +- doc/manpages/highlighters.asciidoc | 6 ++- doc/manpages/shortcuts.asciidoc | 6 ++- 5 files changed, 105 insertions(+), 46 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 240392e7..7425139b 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -585,31 +585,41 @@ saved in the command history. Basic Commands ~~~~~~~~~~~~~~ - * `e[dit] [ []]`: 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 `: change the current directory to the one passed + * `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. + 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 + * `q[uit][!]`: exit Kakoune, use quit! to force quitting even if there is some + unsaved buffers remaining. + * `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] `: switch to buffer - * `d[el]b[uf] []`: delete the buffer , use d[el]b[uf]! to force - deleting a modified buffer. + * `b[uffer]n[ext]`: switch to the next buffer + * `b[uffer]p[rev]`: switch to the previous buffer + * `d[el]b[uf][!] []`: delete the buffer * `source `: execute commands in * `runtime `: execute commands in , - is relative to kak executable path. + 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 + * `echo [options] `: show in status line, with the following options: + ** `-color` : print the given text with , most commonly `Error` or `Information` + ** `-markup`: expand the markup strings in + ** `-debug`: print the given text to the `\*debug*` buffer * `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 - while being sure that it's output will not be interpreted by kak. - `:%sh{ echo echo tchou }` will echo tchou in Kakoune, whereas - `:nop %sh{ echo echo tchou }` will not, but both will execute the - 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. + `:%sh{ echo echo tchou }` will echo tchou in Kakoune, whereas + `:nop %sh{ echo echo tchou }` will not, but both will execute the + shell command. Multiple commands ~~~~~~~~~~~~~~~~~ @@ -1375,24 +1385,28 @@ Kakoune state: Some helper commands can be used to define composite commands: - * `:prompt `: Prompt the user for a string, when + * `prompt `: Prompt the user for a string, when the user validates, store the result in given and run . the -init switch allows setting initial content. - * `:onkey `: Wait for next key from user, writes it into given + * `onkey `: Wait for next key from user, writes it into given and execute commands. - * `:menu ...`: display a menu using + * `menu ...`: display a menu using labels, the selected label's commands are executed. `menu` can take a -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 a -anchor + * `info `: display text in an information box, at can take a -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 + * `try catch `: prevent an error in from aborting the whole commands execution, execute instead. If nothing is to be done on error, the catch part can be ommitted. - * `:reg `: set register to + * `reg `: set register to + * `select .,.:...`: + 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 not that useful in this context. diff --git a/doc/manpages/commands.asciidoc b/doc/manpages/commands.asciidoc index 256a593e..d0ab9d4f 100644 --- a/doc/manpages/commands.asciidoc +++ b/doc/manpages/commands.asciidoc @@ -7,7 +7,15 @@ commands - a Primitives ---------- -*e[dit]* [ []]:: + +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* :: + change the current directory to the one passed + +*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 @@ -17,19 +25,27 @@ Primitives *w[rite]a[ll]*:: 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 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]* :: switch to buffer -*d[el]b[uf]* []:: - delete the buffer , use d[el]b[uf]! to force deleting a - modified buffer +*b[uffer]n[ext]*:: + switch to the next buffer + +*b[uffer]p[rev]*:: + switch to the previous buffer + +*d[el]b[uf][!]* []:: + delete the buffer *source* :: execute commands in @@ -47,8 +63,17 @@ Primitives *namebuf* :: set current buffer name -*echo* :: - show in status line +*echo* [options] :: + show *text* in status line, with the following *options*: + + *-color* ::: + 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*:: does nothing, but arguments will be evaluated (e.g. shell expansion) @@ -56,6 +81,9 @@ Primitives *set* :: change the value of an option (c.f. the 'options' documentation page) +*unset* :: + unset the value of an option (c.f. the 'options' documentation page) + *alias* :: 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 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 +*info* [options] :: + display text in an information box with the following *options*: + + *-anchor* .::: + print the text at the given coordinates + + *-placement* {above,below}::: + set the placement relative to the anchor + + *-title* ::: + set the title of the message box *try* catch :: prevent an error in *commands* from aborting the whole commands @@ -136,6 +171,12 @@ commands: *reg* :: set register *name* to *content* +*select* .,.:...:: + 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 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* can be any combination of the following parameters: -*-params* :: +*-params* ::: the command accepts a *num* parameter, which can be either a number, or of the form .., with both and omittable -*-file-completion*:: +*-file-completion*::: 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 -*-buffer-completion*:: +*-buffer-completion*::: 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 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 -*-hidden*:: +*-hidden*::: do not show the command in command name completions -*-docstring*:: +*-docstring*::: define the documentation string for the command Using shell expansion allows to define complex commands or to access Kakoune diff --git a/doc/manpages/expansions.asciidoc b/doc/manpages/expansions.asciidoc index 4132f816..1d3f58b7 100644 --- a/doc/manpages/expansions.asciidoc +++ b/doc/manpages/expansions.asciidoc @@ -8,7 +8,7 @@ expansions - a Strings ------- \'strings':: - uninterpreted strings, use a backslash (\\') to escape the separator + 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 diff --git a/doc/manpages/highlighters.asciidoc b/doc/manpages/highlighters.asciidoc index 8ab26a97..66f40dff 100644 --- a/doc/manpages/highlighters.asciidoc +++ b/doc/manpages/highlighters.asciidoc @@ -18,7 +18,7 @@ addhl ... and ----------------------- -*rmhl* +rmhl ----------------------- *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 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:' in yellow on red background diff --git a/doc/manpages/shortcuts.asciidoc b/doc/manpages/shortcuts.asciidoc index 518649e9..bbbab1a9 100644 --- a/doc/manpages/shortcuts.asciidoc +++ b/doc/manpages/shortcuts.asciidoc @@ -225,7 +225,7 @@ Changes *>*:: indent selected lines -*>*:: +*>*:: indent selected lines, including empty lines *<*:: @@ -284,7 +284,9 @@ Changes rotate selections content, if specified, the count groups selections, so the following command - 3 +---------- + 3 +---------- rotate (1, 2, 3) and (3, 4, 6) independently