xenia/kakoune
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge README fixes from xificurC/master

Browse Source
This commit is contained in:
Maxime Coste 2015-06-05 13:12:15 +01:00
commit 202f170c66
1 changed files with 66 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
README.asciidoc
View File

@ -76,7 +76,7 @@ Features
Screenshots Screenshots
~~~~~~~~~~~ ~~~~~~~~~~~
[[screenshow-i3]] [[screenshot-i3]]
.Kakoune in i3 .Kakoune in i3
image::doc/screenshot-i3.gif[Kakoune in i3] image::doc/screenshot-i3.gif[Kakoune in i3]
@ -99,13 +99,13 @@ Kakoune dependencies are:
To build, just type *make* in the src directory To build, just type *make* in the src directory
Kakoune can be built on Linux, MacOS, and Cygwin. Due to Kakoune relying heavily Kakoune can be built on Linux, MacOS, and Cygwin. Due to Kakoune relying heavily
on being in an Unix like environment, no native Windows version is planned. on being in a Unix-like environment, no native Windows version is planned.
Installing Installing
~~~~~~~~~~ ~~~~~~~~~~
In order to install kak on your system, rather than running it directly from In order to install kak on your system, rather than running it directly from
it's source directory, type *make install*, you can specify the `PREFIX` and its source directory, type *make install*, you can specify the `PREFIX` and
`DESTDIR` if needed. `DESTDIR` if needed.
[TIP] [TIP]
@ -170,12 +170,12 @@ Just running *kak* launch a new kak session with a client on local terminal.
and stdin if piped in, and apply given keys on each. and stdin if piped in, and apply given keys on each.
At startup, if `-n` is not specified, Kakoune will try to source the file 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 `../share/kak/kakrc` relative to the kak binary. This kak file will then try
to source any files in $XDG_CONFIG_HOME/kak/autoload (with $XDG_CONFIG_HOME to source any files in `$XDG_CONFIG_HOME/kak/autoload` (with `$XDG_CONFIG_HOME`
defaulting to $HOME/.config), and finally $XDG_CONFIG_HOME/kak/kakrc. defaulting to `$HOME/.config`), and finally `$XDG_CONFIG_HOME/kak/kakrc`.
The common pattern is to add links to $XDG_CONFIG_HOME/kak/autoload to the The common pattern is to add links to `$XDG_CONFIG_HOME/kak/autoload` to the
scripts in $PREFIX/share/kak/rc that the user wants sourced at kak launch. scripts in `$PREFIX/share/kak/rc` that the user wants sourced at kak launch.
Basic Interaction Basic Interaction
----------------- -----------------
@ -209,10 +209,10 @@ key.
Movement Movement
~~~~~~~~ ~~~~~~~~
* `h`: select the character on the right of selection end * `h`: select the character on the left of selection end
* `j`: select the character below the selection end * `j`: select the character below the selection end
* `k`: select the character above the selection end * `k`: select the character above the selection end
* `l`: select the character on the left of 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 * `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 * `b`: select preceding whitespaces and the word on the left of selection end
@ -227,8 +227,8 @@ Movement
* `%`: select whole buffer * `%`: select whole buffer
* `alt-H`: select to line begin * `alt-h`: select to line begin
* `alt-L`: select to line end * `alt-l`: select to line end
* `/`: search (select next match) * `/`: search (select next match)
* `?`: search (extend to next match) * `?`: search (extend to next match)
@ -384,9 +384,9 @@ One way to get a multiselection is via the `s` key.
For example, to change all occurences of word 'roger' to word 'marcel' For example, to change all occurences of word 'roger' to word 'marcel'
in a paragraph, here is what can be done: in a paragraph, here is what can be done:
select the paragraph with enough `x`. press `s` and enter roger then enter. select the paragraph with enough `x`. press `s` and enter roger, then enter.
now paragraph selection was replaced with multiselection of each roger in Now paragraph selection was replaced with multiselection of each roger in
the paragraph. press `c` and marcel<esc> to replace rogers with marcels. the paragraph. Press `c` and marcel<esc> to replace rogers with marcels.
A multiselection can also be obtained with `S`, which splits the current A multiselection can also be obtained with `S`, which splits the current
selection according to the regex entered. To split a comma separated list, selection according to the regex entered. To split a comma separated list,
@ -452,7 +452,7 @@ Commands
When pressing `:` in normal mode, Kakoune will open a prompt to enter a command. When pressing `:` in normal mode, Kakoune will open a prompt to enter a command.
Commands are used for non editing tasks, such as opening a buffer, writing the Commands are used for non editing tasks, such as opening a buffer, writing the
current one, quitting, etc... current one, quitting, etc.
Basic Commands Basic Commands
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
@ -498,7 +498,7 @@ Kakoune support three string syntax:
* `%{strings}`: these strings are very useful when entering commands * `%{strings}`: these strings are very useful when entering commands
- the `{` and `}` delimiter are configurable: you can use any non - the `{` and `}` delimiters are configurable: you can use any non
alphanumeric character. like `%[string]`, `%<string>`, `%(string)`, alphanumeric character. like `%[string]`, `%<string>`, `%(string)`,
`%\~string~` or `%!string!`... `%\~string~` or `%!string!`...
- if the character following the % is one of {[(<, then the closing one is - if the character following the % is one of {[(<, then the closing one is
@ -535,11 +535,11 @@ for example you can display last search pattern with
Shell expansion Shell expansion
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
The `%sh{...}` expansion replaces it's content with the output of the shell The `%sh{...}` expansion replaces its content with the output of the shell
commands in it, it is similar to the shell $(...) syntax and is evaluated commands in it. It is similar to the shell $(...) syntax and is evaluated
only when needed. only when needed.
for example: %sh{ ls } is replaced with the output of the ls command. for example: `%sh{ ls }` is replaced with the output of the ls command.
Some of Kakoune state is available through environment variables: Some of Kakoune state is available through environment variables:
@ -565,7 +565,7 @@ to find the environment variable reference in the shell script executed.
Hence `%sh{ ./script.sh }` with `script.sh` referencing an environment Hence `%sh{ ./script.sh }` with `script.sh` referencing an environment
variable will not work. variable will not work.
for example you can print informations on the current file in the status For example you can print informations on the current file in the status
line using: line using:
------------------------------- -------------------------------
@ -682,7 +682,7 @@ Some options are built in Kakoune, and can be used to control it's behaviour:
* `autoreload` _yesnoask_: auto reload the buffers when an external * `autoreload` _yesnoask_: auto reload the buffers when an external
modification is detected. modification is detected.
* `ui_options`: colon separated list of key=value pairs that are forwarded to * `ui_options`: colon separated list of key=value pairs that are forwarded to
the user interface implementation. The NCurses UI support the following option: the user interface implementation. The NCurses UI support the following options:
- `ncurses_status_on_top`: if `yes`, or `true` the status line will be placed - `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. at the top of the terminal rather than at the bottom.
- `ncurses_assistant`: specify the nice assistant you get in info boxes, can - `ncurses_assistant`: specify the nice assistant you get in info boxes, can
@ -693,10 +693,10 @@ Some options are built in Kakoune, and can be used to control it's behaviour:
Faces Faces
----- -----
A Face refer the how specified text is displayed, a Face has a foreground A Face refers how the specified text is displayed. A face has a foreground
color, a background color, and some attributes. color, a background color, and some attributes.
Faces can be defined and modified with the face command. Faces can be defined and modified with the face command:
----------------------- -----------------------
:face <name> <facespec> :face <name> <facespec>
@ -725,9 +725,9 @@ attributes is a string of letters each defining an attributes:
* `b`: Bold * `b`: Bold
Using named faces instead of facespec permits to change the effective faces Using named faces instead of facespec permits to change the effective faces
afterward. afterwards.
there are some builtins faces used by internal Kakoune functionalities: There are some builtins faces used by internal Kakoune functionalities:
* `Default`: default colors * `Default`: default colors
* `PrimarySelection`: main selection face for every selected character except * `PrimarySelection`: main selection face for every selected character except
@ -753,11 +753,11 @@ Advanced topics
Registers Registers
~~~~~~~~~ ~~~~~~~~~
Registers are named list of text. They are used for various purpose, like Registers are named lists of text. They are used for various purposes, like
storing the last yanked test, or the captures groups associated with the storing the last yanked test, or the captured groups associated with the
selections. selections.
Yanking and pasting uses the register `"`, however most commands using register Yanking and pasting uses the register `"`, however most commands using a register
can have their default register overriden by using the `"` key followed by the can have their default register overriden by using the `"` key followed by the
register. For example `"sy` will yank (`y` command) in the `s` register. `"sp` register. For example `"sy` will yank (`y` command) in the `s` register. `"sp`
will paste from the `s` register. will paste from the `s` register.
@ -770,28 +770,28 @@ For example, `ctrl-r` followed by " will insert the currently yanked text.
selection. selection.
Registers are lists, instead of simply text in order to interact well with Registers are lists, instead of simply text in order to interact well with
multiselection. Each selection have it's own captures, or yank buffer. multiselection. Each selection has its own captures or yank buffer.
Macros Macros
~~~~~~ ~~~~~~
Kakoune can record and replay a sequence of key press. Kakoune can record and replay a sequence of key presses.
When pressing the `Q` key, followed by an alphabetic key for the macro name, When pressing the `Q` key, followed by an alphabetic key for the macro name,
Kakoune begins macro recording: every pressed keys will be added to the Kakoune begins macro recording: every pressed key will be added to the
macro until the `Q` key is pressed again. macro until the `Q` key is pressed again.
To replay a macro, use the `q` key, followed by the macro name. To replay a macro, use the `q` key, followed by the macro name.
macros are actually stored as a key sequence into a register, a macro name Macros are actually stored as a key sequence into a register, i.e. a macro name
is a register name. is a register name.
Search selection Search selection
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
Using the `*` key, you can set the search pattern to the current selection. Using the `*` key, you can set the search pattern to the current selection.
This tries to be intelligent. It will for example detect if current selection This tries to be intelligent. It will for example detect if the current selection
begins and/or end at word boundaries, and set the search pattern accordingly. begins and/or ends at word boundaries and set the search pattern accordingly.
with `alt-*` you can set the search pattern to the current seletion without with `alt-*` you can set the search pattern to the current seletion without
Kakoune trying to be smart. Kakoune trying to be smart.
@ -800,7 +800,7 @@ Exec and Eval
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
the `:exec` and `:eval` commands can be used for running Kakoune commands. the `:exec` and `:eval` commands can be used for running Kakoune commands.
`:exec` run keys as if they were pressed, whereas `:eval` executes it's given `: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, paremeters as if they were entered in the command prompt. By default,
they do their execution in the context of the current client. they do their execution in the context of the current client.
@ -824,7 +824,7 @@ Some parameters provide a way to change the context of execution:
The execution stops when the last key/command is reached, or an error The execution stops when the last key/command is reached, or an error
is raised. is raised.
key parameters gets concatenated, so the following commands are equivalent. Key parameters get concatenated, so the following commands are equivalent:
---------------------- ----------------------
:exec otest<space>1 :exec otest<space>1
@ -835,7 +835,7 @@ Insert mode completion
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
Kakoune can propose completions while inserting text, the `completers` option Kakoune can propose completions while inserting text, the `completers` option
control automatic completion, which kicks in when a certain idle timeout is controls automatic completion, which kicks in when a certain idle timeout is
reached (100 milliseconds). Insert mode completion can be explicitely triggered reached (100 milliseconds). Insert mode completion can be explicitely triggered
using *control-x*, followed, by: using *control-x*, followed, by:
@ -844,6 +844,8 @@ using *control-x*, followed, by:
* *l* : buffer line completion * *l* : buffer line completion
* *o* : option based completion * *o* : option based completion
Completion candidates can be selected using `ctrl-n` and `ctrl-p`.
Highlighters Highlighters
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -871,10 +873,10 @@ general highlighters are:
For example: `:addhl regex //(\h`TODO:)?[^\n]` 0:cyan 1:yellow,red` For example: `:addhl regex //(\h`TODO:)?[^\n]` 0:cyan 1:yellow,red`
will highlight C++ style comments in cyan, with an eventual 'TODO:' in will highlight C++ style comments in cyan, with an eventual 'TODO:' in
yellow on red background. yellow on red background.
* `search`: highlight every matches to the current search pattern with the * `search`: highlight every match to the current search pattern with the
`Search` face `Search` face
* `flag_lines <flag> <option_name>`: add a column in front of text, and display the * `flag_lines <flag> <option_name>`: add a column in front of text, and display the
given flag in it for everly lines contained in the int-list option named given flag in it for everly line contained in the int-list option named
<option_name>. <option_name>.
* `show_matching`: highlight matching char of the character under the selections * `show_matching`: highlight matching char of the character under the selections
cursor using `MatchingChar` face. cursor using `MatchingChar` face.
@ -911,7 +913,7 @@ addhl -group <name>/<subname> <type> <params>...
Regions highlighters Regions highlighters
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
A special highlighter provide a way to segment the buffer into regions, which are A special highlighter provides a way to segment the buffer into regions, which are
to be highlighted differently. to be highlighted differently.
A region is defined by 4 parametes: A region is defined by 4 parametes:
@ -956,7 +958,7 @@ That matches the rule governing most programming language parsing.
`regions` also supports a `-default <default_region>` switch to define the `regions` also supports a `-default <default_region>` switch to define the
default region, when no other region matches the current buffer range. default region, when no other region matches the current buffer range.
most programming languages can then be properly highlighted using a `regions` Most programming languages can then be properly highlighted using a `regions`
highlighter as root: highlighter as root:
----------------------------------------------------------------- -----------------------------------------------------------------
@ -1003,35 +1005,35 @@ the `ref` can reference any named highlighter in the shared namespace.
Hooks Hooks
~~~~~ ~~~~~
commands can be registred to be executed when certain events arise. Commands can be registred to be executed when certain events arise.
to register a hook, use the hook command. To register a hook use the hook command.
----------------------------------------------------------------------- -----------------------------------------------------------------------
:hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands> :hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
----------------------------------------------------------------------- -----------------------------------------------------------------------
<scope> can be either global, buffer or window (or any of their prefixes), `<scope>` can be either global, buffer or window (or any of their prefixes).
the scope are hierarchical, meaning that a Window calling a hook will Scopes are hierarchical, meaning that a Window calling a hook will
execute it's own, the buffer ones and the global ones. execute its own, the buffer ones and the global ones.
<command> is a string containing the commands to execute when the hook is `<command>` is a string containing the commands to execute when the hook is
called. called.
for example, to automatically use line numbering with .cc files, For example to automatically use line numbering with .cc files,
use the following command: use the following command:
----------------------------------------------------- -----------------------------------------------------
:hook global WinCreate .*\.cc %{ addhl number_lines } :hook global WinCreate .*\.cc %{ addhl number_lines }
----------------------------------------------------- -----------------------------------------------------
if <group> is given, make this hook part of the named group. groups if `<group>` is given, make this hook part of the named group. groups
are used for removing hooks with the `rmhooks` command are used for removing hooks with the `rmhooks` command
----------------------- -----------------------
rmhooks <scope> <group> rmhooks <scope> <group>
----------------------- -----------------------
will remove every hooks in <scope> that are part of the given group. will remove every hooks in `<scope>` that are part of the given group.
existing hooks are: existing hooks are:
@ -1074,19 +1076,19 @@ existing hooks are:
configuration files configuration files
* `KakEnd`: Kakoune is quitting. * `KakEnd`: Kakoune is quitting.
when not specified, the filtering text is an empty string. When not specified, the filtering text is an empty string.
Key Mapping Key Mapping
~~~~~~~~~~~ ~~~~~~~~~~~
You can redefine keys meaning using the map command You can redefine a key's meaning using the map command
------------------------------------------------------ ------------------------------------------------------
:map <scope> <mode> <key> <keys> :map <scope> <mode> <key> <keys>
------------------------------------------------------ ------------------------------------------------------
with `scope` being one of `global, buffer or window` (or any prefix), with `scope` being one of `global`, `buffer` or `window` (or any prefix),
mode being `insert, normal, prompt, menu or user` (or any prefix), `key` being mode being `insert`, `normal`, `prompt`, `menu` or `user` (or any prefix), `key` being
a single key name and `keys` a list of keys. a single key name and `keys` a list of keys.
`user` mode allows for user mapping behind the `,` key. Keys will be executed in `user` mode allows for user mapping behind the `,` key. Keys will be executed in
@ -1095,15 +1097,15 @@ normal mode.
Defining Commands Defining Commands
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
new commands can be defined using the `:def` command. New commands can be defined using the `:def` command.
------------------------------ ------------------------------
:def <command_name> <commands> :def <command_name> <commands>
------------------------------ ------------------------------
<commands> is a string containing the commands to execute `<commands>` is a string containing the commands to execute.
def can also takes some flags: `def` can also takes some flags:
* `-env-params`: pass parameters given to commands in the environment as * `-env-params`: pass parameters given to commands in the environment as
kak_paramN with N the parameter number kak_paramN with N the parameter number
@ -1153,7 +1155,7 @@ not that useful in this context.
Aliases Aliases
~~~~~~~ ~~~~~~~
With `:alias` commands can be given additional names. aliases are scoped, so With `:alias` commands can be given additional names. Aliases are scoped, so
that an alias can refer to one command for a buffer, and to another for another that an alias can refer to one command for a buffer, and to another for another
buffer. buffer.
@ -1168,19 +1170,19 @@ an alias for `<command>`
:unalias <scope> <alias> [<expected>] :unalias <scope> <alias> [<expected>]
------------------------------------- -------------------------------------
Will remove the given alias in the given scope. If `<expected>` is specified will remove the given alias in the given scope. If `<expected>` is specified
the alias will only be removed if its current value is `<expected>`. the alias will only be removed if its current value is `<expected>`.
FIFO Buffer FIFO Buffer
~~~~~~~~~~~ ~~~~~~~~~~~
the `:edit` command can take a -fifo parameter: the `:edit` command can take a `-fifo` parameter:
--------------------------------------------- ---------------------------------------------
:edit -fifo <filename> [-scroll] <buffername> :edit -fifo <filename> [-scroll] <buffername>
--------------------------------------------- ---------------------------------------------
in this case, a buffer named `<buffername>` is created which reads its content In this case, a buffer named `<buffername>` is created which reads its content
from fifo `<filename>`. When the fifo is written to, the buffer is automatically from fifo `<filename>`. When the fifo is written to, the buffer is automatically
updated. updated.
@ -1188,10 +1190,10 @@ if the `-scroll` switch is specified, the initial cursor position will be made
such as the window displaying the buffer will scroll as new data is read. such as the window displaying the buffer will scroll as new data is read.
This is very useful for running some commands asynchronously while displaying This is very useful for running some commands asynchronously while displaying
their result in a buffer. See rc/make.kak and rc/grep.kak for examples. their result in a buffer. See `rc/make.kak` and `rc/grep.kak` for examples.
When the buffer is deleted, the fifo will be closed, so any program writing When the buffer is deleted, the fifo will be closed, so any program writing
to it will receive SIGPIPE. This is usefull as it permits to stop the writing to it will receive `SIGPIPE`. This is usefull as it permits to stop the writing
program when the buffer is deleted. program when the buffer is deleted.
Menus Menus