diff --git a/doc/manpages/commands.asciidoc b/doc/manpages/commands.asciidoc index d5c599da..256a593e 100644 --- a/doc/manpages/commands.asciidoc +++ b/doc/manpages/commands.asciidoc @@ -8,7 +8,8 @@ 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 + 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 @@ -17,7 +18,8 @@ Primitives 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 + exit Kakoune, use quit! to force quitting even if there is some + unsaved buffers remaining *wq*:: write current buffer and quit @@ -26,13 +28,15 @@ Primitives switch to buffer *d[el]b[uf]* []:: - delete the buffer , use d[el]b[uf]! to force deleting a modified buffer + 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 + execute commands in , is relative to kak + executable path *colorscheme* :: load named colorscheme @@ -56,75 +60,102 @@ Primitives 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 + 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) + 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) + 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) + 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) + 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) + 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) + 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) + 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) + 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: +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 + 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 + 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) + 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 + 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 + 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. +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 +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: + *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 + 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 @@ -136,7 +167,8 @@ New commands can be defined using the *def* command: 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 + 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 @@ -147,7 +179,8 @@ New commands can be defined using the *def* command: *-docstring*:: define the documentation string for the command -Using shell expansion allows to define complex commands or to access Kakoune state: +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.asciidoc b/doc/manpages/execeval.asciidoc index fb2144fc..033d2898 100644 --- a/doc/manpages/execeval.asciidoc +++ b/doc/manpages/execeval.asciidoc @@ -7,15 +7,17 @@ execeval - a Description ----------- -The *exec* and *eval* commands can be used to run Kakoune commands, and should be used as follows: +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 +*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 @@ -24,20 +26,23 @@ Optional flags 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 + 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 + 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 + 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 + 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 diff --git a/doc/manpages/expansions.asciidoc b/doc/manpages/expansions.asciidoc index 1f48462c..4132f816 100644 --- a/doc/manpages/expansions.asciidoc +++ b/doc/manpages/expansions.asciidoc @@ -10,17 +10,20 @@ 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 + 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 + * 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 + * 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 @@ -29,40 +32,46 @@ e.g. %{ roger {}; } is a valid string, %{ marcel \} as well Typed expansions ---------------- *sh*:: - shell expansion, similar to posix shell '$(...)' construct (c.f. next section) + shell expansion, similar to posix shell '$(...)' construct (c.f. next + section) *reg*:: - register expansion, will be replaced by the content of the given register + 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 + 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 + 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: +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 + 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 + 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 + 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 + 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_*:: @@ -88,15 +97,18 @@ variables are used to pass informations about Kakoune's state: *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) + 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 +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 ('\\'). +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.asciidoc b/doc/manpages/faces.asciidoc index b3a43b1d..483200bc 100644 --- a/doc/manpages/faces.asciidoc +++ b/doc/manpages/faces.asciidoc @@ -7,8 +7,9 @@ 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: +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] @@ -38,11 +39,13 @@ fg_color[,bg_color][+attributes] *i*::: italic *e*::: - exclusive, override previous faces instead of merging with them + 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: +The following default faces are used by color schemes to highlight certains +areas of the user interface: *Default*:: default colors diff --git a/doc/manpages/highlighters.asciidoc b/doc/manpages/highlighters.asciidoc index 344504fa..8ab26a97 100644 --- a/doc/manpages/highlighters.asciidoc +++ b/doc/manpages/highlighters.asciidoc @@ -8,8 +8,8 @@ highlighters - a Description ----------- -Manipulation of the displayed text is done through highlighters, which can be added or removed with the following -commands: +Manipulation of the displayed text is done through highlighters, which can +be added or removed with the following commands: ------------------------------------------------------- addhl ... @@ -21,26 +21,33 @@ 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. +*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: + 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 + 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 + 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 + 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 + highlight matching char of the character under the selections cursor + using MatchingChar face *number_lines* [options]:: show line numbers, with the following *options*: @@ -52,7 +59,8 @@ General highlighters 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 '|') + 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 @@ -60,19 +68,22 @@ General highlighters Highlighting Groups ------------------- -The group highlighter is a container for other highlighters. You can add a group to the current window using +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: +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: +Groups can contain other groups, the *-group* switch can be used to define +a path as follows: -------------------------------------------------- addhl -group group @@ -82,7 +93,8 @@ addhl -group / ... Regions highlighters -------------------- -A special highlighter provides a way to segment the buffer into regions, which are to be highlighted differently. +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 @@ -91,9 +103,11 @@ A special highlighter provides a way to segment the buffer into regions, which a *closing*:: regex that defines the region end text *recurse*:: - regex that defines the text that matches recursively an end token into the region + 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: +The *recurse* option is useful for regions that can be nested, for example +the following contruct: ---------- %sh{ ... } @@ -111,7 +125,8 @@ This region can be defined with: shell_expand %sh\{ \} \{ ------------------------ -Regions are used in the regions highlighter which can take any number of regions. +Regions are used in the regions highlighter which can take any number +of regions. The following command: @@ -126,13 +141,17 @@ 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. +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. +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: +Most programming languages can then be properly highlighted using a regions +highlighter as root: ----------------------------------------------------------------- addhl regions -default code \ @@ -147,7 +166,8 @@ 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. +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: @@ -155,9 +175,11 @@ 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. +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: +The common case would be to create a named shared group, and then fill it +with highlighters: ------------------------------ addhl -group / group diff --git a/doc/manpages/hooks.asciidoc b/doc/manpages/hooks.asciidoc index a7dd6e63..80901845 100644 --- a/doc/manpages/hooks.asciidoc +++ b/doc/manpages/hooks.asciidoc @@ -8,7 +8,8 @@ hooks - a Description ----------- -Commands can be registred to be executed when certain events arise. To register a hook use the following command: +Commands can be registred to be executed when certain events arise. To +register a hook use the following command: ---------------------------------------------------------------------- hook [-group ] @@ -16,22 +17,25 @@ 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. +*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: +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: +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*. +A call to the command above will remove every hooks in *scope* that are part +of the given *group*. Default hooks ------------- @@ -60,7 +64,8 @@ Default hooks 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 + 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 @@ -72,22 +77,27 @@ Default hooks 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 *=* + 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 *=* + 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 + 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 + 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 + 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 @@ -99,25 +109,31 @@ Default hooks executed when a buffer opens a fifo *BufReadFifo*:: - executed after some data has been red from a fifo and inserted in the buffer + 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, + 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 + 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 + 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 + 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 + 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.asciidoc b/doc/manpages/options.asciidoc index 483c2fc0..53fd6802 100644 --- a/doc/manpages/options.asciidoc +++ b/doc/manpages/options.asciidoc @@ -16,14 +16,17 @@ Types *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 + 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 + 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 + a set of flags, taking a combination of the given values joined by a + '|' character Scopes ------ @@ -34,12 +37,14 @@ Scopes *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*). +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 --------------- @@ -51,16 +56,19 @@ Builtin options 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 + 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 + 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 + when completing in command line, and multiple candidates exist, + enable completion with common prefix *incsearch* 'bool':: execute search as it is typed @@ -75,38 +83,45 @@ Builtin options 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) + 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' + 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 + 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: + 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*) + 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 + 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: + 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 + 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 + 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 @@ -115,21 +130,25 @@ Builtin options 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) + 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: + 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 + 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 + 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* + 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.asciidoc b/doc/manpages/registers.asciidoc index 445c8476..807eb53f 100644 --- a/doc/manpages/registers.asciidoc +++ b/doc/manpages/registers.asciidoc @@ -7,14 +7,15 @@ 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. +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) + 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) @@ -24,10 +25,12 @@ 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 yank, used by yanking and pasting commands like *y*, *p* + and *R* */*:: - default search register, used by regex based commands like *s*, *\** or */* + default search register, used by regex based commands like *s*, *\** + or */* *@*:: default macro register, used by *q* and *Q* @@ -37,7 +40,8 @@ Most commands using a register default to a specific one if not specified: Special registers ----------------- -Some registers are not general purposes, they cannot be written to, but they contain some special dat +Some registers are not general purposes, they cannot be written to, but they +contain some special data *%*:: current buffer name diff --git a/doc/manpages/shortcuts.asciidoc b/doc/manpages/shortcuts.asciidoc index b47f5a94..518649e9 100644 --- a/doc/manpages/shortcuts.asciidoc +++ b/doc/manpages/shortcuts.asciidoc @@ -60,7 +60,8 @@ Insert mode Movement -------- -'word' is a sequence of alphanumeric characters or underscore, and 'WORD' is a sequence of non whitespace characters +'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 @@ -102,13 +103,15 @@ Movement extend selection to matching character *x*:: - select line on which selection end lies (or next line when end lies on an end-of-line) + 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) + trim selections to only contain full lines (not including last + end-of-line) *%*:: select whole buffer @@ -177,7 +180,8 @@ Changes yank and delete current selection and enter insert mode *.*:: - repeat last insert mode change (*i*, *a*, or *c*, including the inserted text) + repeat last insert mode change (*i*, *a*, or *c*, including the + inserted text) *I*:: enter insert mode at current selection begin line start @@ -228,7 +232,16 @@ Changes deindent selected lines **:: - deindent selected lines, do not remove incomplete indent (3 leading spaces when indent is 4) + deindent selected lines, do not remove incomplete indent (3 leading + spaces when indent is 4) + +*|*:: + 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 *!*:: insert command output before selection @@ -243,10 +256,12 @@ Changes redo last change *&*:: - align selection, align the cursor of selections by inserting spaces before the first character of the selection + 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 + 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 @@ -258,13 +273,16 @@ Changes swap case *@*:: - convert tabs to spaces in current selections, uses the buffer tabstop option or the count parameter for tabstop + 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 + 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 + rotate selections content, if specified, the count groups selections, + so the following command 3 @@ -363,10 +381,12 @@ 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 (automatically + detects word boundaries) **:: - set the search pattern to the current selection (verbatim, no smart detection) + set the search pattern to the current selection (verbatim, no smart + detection) Jump list --------- @@ -410,14 +430,9 @@ Multiple selections **:: 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 + pipe each selection to the given shell command and keep the ones + for which the shell returned 0 Object Selection ---------------- @@ -439,9 +454,9 @@ Object Selection *}*:: extends selections to object end -.RE -After this key, you need to enter a second key in order to specify which object you want +After these keys, you need to enter a second key in order to specify which +object you want *b*, *(*, *)*:: select the enclosing parenthesis @@ -556,7 +571,8 @@ Prompt Commands Key mapping ----------- -Mapping a combination of keys to another one (a.k.a. key mapping or binding) can be done with the following command: +Mapping a combination of keys to another one (a.k.a. key mapping or binding) +can be done with the following command: ------------------------------- map @@ -566,8 +582,8 @@ map 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) + 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