doc: fix typos and clarify some parts

This commit is contained in:
Johannes Altmanninger 2020-05-28 18:37:26 +02:00
parent 3385c6a20e
commit e4f7d42396
11 changed files with 51 additions and 52 deletions

View File

@ -1,12 +1,12 @@
Edition auto insertion in Kakoune Edition auto insertion in Kakoune
================================= =================================
It is a quite common feature for code editor to help the programmer by It is a quite common feature for a code editor to help the programmer
automatically inserting some text in certain contexts. This document by automatically inserting some text in certain contexts. This document
goal is to explain how this is done in Kakoune. goal is to explain how this is done in Kakoune.
There is no special support in Kakoune for this problem, hooks are There is no special support in Kakoune for this task, hooks are
expected to be used in order to manage that, and the normal kakoune expected to be used in order to manage that, and the normal Kakoune
editing command are expected to be expressive enough so that relatively editing command are expected to be expressive enough so that relatively
complex indentation can be written concisely. complex indentation can be written concisely.
@ -27,7 +27,7 @@ s^\h+<ret>y # 2. select the leading spaces and copy them
j<a-h>P # 3. go back to next line start and paste the spaces j<a-h>P # 3. go back to next line start and paste the spaces
---------------------------------------------------------------- ----------------------------------------------------------------
note that if nothing gets selected on phase *2.*, an error will be raised. Note that if nothing gets selected on phase *2.*, an error will be raised.
We want to do that each time the user jumps a line, just after the new line We want to do that each time the user jumps a line, just after the new line
is inserted. So the hook would be: is inserted. So the hook would be:
@ -71,13 +71,13 @@ k<a-x> # 1. select the previous line
j<a-gt> # 3. go back to next line and indent it even if it is empty j<a-gt> # 3. go back to next line and indent it even if it is empty
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
Note that if no previous lines end with a +{+ or +(+, the +<a-k>+ command will Note that if no previous line ends with a +{+ or +(+, the +<a-k>+ command will
raise an error, and stop the execution. This is what we want: it is similar to raise an error, and stop the execution. This is what we want: it is similar to
what would happen if we would continue with no selections; the following what would happen if we would continue with no selections; the following
commands would have no effects. commands would have no effects.
However, the error would end up being caught by the hook execution code, and However, the error would end up being caught by the hook execution code, and
it will write informations about it in the debug buffer, which we do not want, it will write information about it in the debug buffer, which we do not want,
as this is actually expected. In order to prevent that, the exec should be as this is actually expected. In order to prevent that, the exec should be
wrapped in a try command. So we would have: wrapped in a try command. So we would have:

View File

@ -13,7 +13,7 @@ released versions.
* replace-ranges highlighter now support empty and multi-lines ranges * replace-ranges highlighter now support empty and multi-lines ranges
* `%var{...}` now expands to list of strings, `$kak_quoted_...` now work * `%val{...}` now expands to list of strings, `$kak_quoted_...` now work
as expected with these. as expected with these.
== Kakoune v2020.01.16 == Kakoune v2020.01.16

View File

@ -2,7 +2,7 @@
Some commands take an exclamation mark (*!*), which can be used to force Some commands take an exclamation mark (*!*), which can be used to force
the execution of the command (i.e. to quit a modified buffer, the the execution of the command (i.e. to quit a modified buffer, the
command *q!* has to be used). Aliases are mentionned below each commands. command *q!* has to be used). Aliases are mentioned below each command.
*doc* <topic>:: *doc* <topic>::
*alias* help + *alias* help +
@ -74,12 +74,12 @@ of the file onto the filesystem
*write-all* [-sync]:: *write-all* [-sync]::
*alias* wa + *alias* wa +
write all changed buffers that are associated to a file write all changed buffers that are associated with a file
*quit[!]* [<exit status>]:: *quit[!]* [<exit status>]::
*alias* q + *alias* q +
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. If specified, the client exit status unsaved buffer remaining. If specified, the client exit status
will be set to <exit status> will be set to <exit status>
*write-quit[!]* [-sync] [<exit status>]:: *write-quit[!]* [-sync] [<exit status>]::
@ -227,7 +227,7 @@ of the file onto the filesystem
filesystem. filesystem.
*-quoting* <quoting>::: *-quoting* <quoting>:::
define how each arguments are quoted in echo output: define how arguments are quoted in echo output:
- *raw* (default):::: - *raw* (default)::::
just join each argument with a space just join each argument with a space
@ -446,10 +446,10 @@ New commands can be defined using the *define-command* command:
*-shell-script-completion*::: *-shell-script-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 outputs one completion candidate per line.
The provided shell command will run after each keypress The provided shell command will run after each keypress
during the executing of the shell command, the following env vars are during the execution of the shell command, the following env vars are
available: available:
- *kak_token_to_complete*:::: - *kak_token_to_complete*::::
@ -461,12 +461,12 @@ New commands can be defined using the *define-command* command:
*-shell-script-candidates*::: *-shell-script-candidates*:::
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 outputs one completion candidate per line.
The provided shell command will run once at the beginning of each The provided shell command will run once at the beginning of each
completion session, candidates are cached and then used by kakoune completion session, candidates are cached and then used by kakoune
internal fuzzy engine internal fuzzy engine
during the executing of the shell command, the following env vars are during the execution of the shell command, the following env vars are
available: available:
- *kak_token_to_complete*:::: - *kak_token_to_complete*::::

View File

@ -2,7 +2,7 @@
== Declaration == Declaration
A 'face' refers how the specified text is displayed, it has a foreground A 'face' determines how text is displayed, it has a foreground
color, a background color, and some attributes. The value of a face has the color, a background color, and some attributes. The value of a face has the
following format: following format:
@ -41,9 +41,9 @@ following format:
*i*::: *i*:::
italic italic
*F*::: *F*:::
final, override the previous face instead of merging with it final, override the previous face instead of merging with it,
an will only be replaced if another face with the final and this face will only be replaced if another face with
attribute is applied the final attribute is applied
*f*::: *f*:::
final foreground, as final but only applies to face's final foreground, as final but only applies to face's
foreground color foreground color
@ -56,7 +56,7 @@ following format:
'base':: 'base'::
The base face on which this face applies, which can be any face name, The base face on which this face applies, which can be any face name,
as long as a cycle is not introduced. A face can reference itself, in as long as no cycle is introduced. A face can reference itself, in
which case it will apply on top of the parent scope version. which case it will apply on top of the parent scope version.
== Builtin faces == Builtin faces
@ -80,10 +80,10 @@ areas of the user interface:
cursor of the secondary selection cursor of the secondary selection
*PrimaryCursorEol*:: *PrimaryCursorEol*::
cursor of the primary selection when it lies on and end of line character cursor of the primary selection when it lies on an end of line character
*SecondaryCursorEol*:: *SecondaryCursorEol*::
cursor of the secondary selection when it lies on and end of line character cursor of the secondary selection when it lies on an end of line character
*MenuForeground*:: *MenuForeground*::
face for the selected element in menus face for the selected element in menus
@ -147,7 +147,7 @@ The following faces are used by builtin highlighters if enabled.
== Markup strings == Markup strings
In certain contexts, Kakoune can take a markup string, which is a string In certain contexts, Kakoune can take a markup string, which is a string
containing formatting informations. In these strings, the {facename} containing formatting information. In these strings, the {facename}
syntax will enable the face facename until another face gets activated, syntax will enable the face facename until another face gets activated,
or the end of the string is reached. or the end of the string is reached.
@ -167,7 +167,7 @@ and can be used to avoid having to escape text that might be mistaken
for markup instructions. for markup instructions.
For example this will prevent any '{' in the current buffer name from For example this will prevent any '{' in the current buffer name from
being incorrectly interpreted as markup instructions. being incorrectly interpreted as markup instruction.
---- ----
echo -markup "{Information}name:{\} %val{bufname}" echo -markup "{Information}name:{\} %val{bufname}"

View File

@ -3,7 +3,7 @@
== How to pronounce the name of the project and what does it mean ? == How to pronounce the name of the project and what does it mean ?
The name of the project is pronounced "Kak-oon", and is a word taken from a The name of the project is pronounced "Kak-oon", and is a word taken from a
New Caledonian dialect based on french. It means a hard blow, usually a punch, New Caledonian dialect based on French. It means a hard blow, usually a punch,
but generally refers to a blow into which all of one's strength went. but generally refers to a blow into which all of one's strength went.
== Is there going to be a Windows port of Kakoune ? == Is there going to be a Windows port of Kakoune ?
@ -88,7 +88,7 @@ dedicated tool, as is the case with `clang` and C code: you can use the
`clang-enable-autocomplete` and `clang-complete` builtin commands whenever `clang-enable-autocomplete` and `clang-complete` builtin commands whenever
editing a C/C++ file, and completion will work on function parameters. editing a C/C++ file, and completion will work on function parameters.
Note that the same features are available for python buffers, with the Note that the same features are available for Python buffers, with the
`jedi` script. `jedi` script.
== Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune ? == Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune ?
@ -174,7 +174,7 @@ balanced against the ability to select data over several lines.
As a fairly compliant follower of the UNIX philosophy, Kakoune does not As a fairly compliant follower of the UNIX philosophy, Kakoune does not
try to implement features that are best handled by separate, dedicated try to implement features that are best handled by separate, dedicated
tools. Windows splitting in terminals is a prime example of that tools. Window splitting in terminals is a prime example of that
concept, where the editor provides commands to interact with several concept, where the editor provides commands to interact with several
terminal multiplexers (e.g. `tmux`), as opposed to emulating their terminal multiplexers (e.g. `tmux`), as opposed to emulating their
functionalities. functionalities.

View File

@ -62,7 +62,7 @@ highlighter is replaced with the new one.
highlight the cursor line with a separate face highlight the cursor line with a separate face
*-separator* <separator text>::: *-separator* <separator text>:::
specify a string to separate the line numbers column with specify a string to separate the line numbers column from
the rest of the buffer (default is '|') the rest of the buffer (default is '|')
*-min-digits* <num>::: *-min-digits* <num>:::
@ -123,7 +123,7 @@ add-highlighter window/ dynregex '%reg{/}' 0:+i
== Specs highlighters == Specs highlighters
The following highlighters are useful to add indicators like lint warnings, The following highlighters are useful to add indicators like lint warnings,
git blame output or spelling typos. git blame output or spelling mistakes.
See <<options#types,`:doc options types`>> for the format of `line-specs` See <<options#types,`:doc options types`>> for the format of `line-specs`
and `range-specs`. and `range-specs`.
@ -217,7 +217,7 @@ add-highlighter <path>/<name>/<region_name> region \
match of *end*, preventing it from closing the region. match of *end*, preventing it from closing the region.
*type* and *params*:: *type* and *params*::
An highlighter type, and associated params, as they would be passed A highlighter type, and associated params, as they would be passed
to `add-highlighter` if they were not applied as a region. to `add-highlighter` if they were not applied as a region.
If the *-match-capture* switch is passed, then region closing and recurse If the *-match-capture* switch is passed, then region closing and recurse
@ -249,7 +249,7 @@ another region.
That matches the rule governing most programming language parsing. That matches the rule governing most programming language parsing.
A default region, that will apply its given highlighter for segments of the A default region, that will apply its given highlighter to the segments of the
buffer that are not in any defined region, can be added with the *default-region* buffer that are not in any defined region, can be added with the *default-region*
highlighter type. highlighter type.

View File

@ -171,7 +171,7 @@ name. Hooks with no description will always use an empty string.
*RawKey* `key`:: *RawKey* `key`::
Triggered whenever a key is pressed by the user, regardless of what mode Triggered whenever a key is pressed by the user, regardless of what mode
Kakoune is in, or what mappings are present (see Kakoune is in, or what mappings are present (see
<<mapping#,`:doc mapping`>>). It cannot triggered by `execute-keys`, <<mapping#,`:doc mapping`>>). It cannot be triggered by `execute-keys`,
even with the `-with-hooks` option (see even with the `-with-hooks` option (see
<<execeval#execute-keys-specific-switches,`:doc execeval execute-keys-specific-switches`>>). <<execeval#execute-keys-specific-switches,`:doc execeval execute-keys-specific-switches`>>).
@ -194,7 +194,7 @@ vars are available:
== Disabling Hooks == Disabling Hooks
Any normal mode command can be prefixed with `\ ` which will disable hook Any normal mode command can be prefixed with `\ ` which will disable hook
execution for the duration for the command (including the duration of modes execution for the duration of the command (including the duration of modes
the command could move to, so `\i` will disable hooks for the whole insert the command could move to, so `\i` will disable hooks for the whole insert
session). session).

View File

@ -144,7 +144,7 @@ the Shift modifier and moving will extend each selection instead.
repeat last object or *f*/*t* selection command repeat last object or *f*/*t* selection command
*m*:: *m*::
select to the next sequence enclosed by matching character, see the select to the next sequence enclosed by matching characters, see the
`matching_pairs` option in <<options#,`:doc options`>> `matching_pairs` option in <<options#,`:doc options`>>
*M*:: *M*::
@ -152,12 +152,12 @@ the Shift modifier and moving will extend each selection instead.
character, see the `matching_pairs` option in <<options#,`:doc options`>> character, see the `matching_pairs` option in <<options#,`:doc options`>>
*<a-m>*:: *<a-m>*::
select to the previous sequence enclosed by matching character, see the select to the previous sequence enclosed by matching characters, see the
`matching_pairs` option in <<options#,`:doc options`>> `matching_pairs` option in <<options#,`:doc options`>>
*<a-M>*:: *<a-M>*::
extend the current selection to the previous sequence enclosed by matching extend the current selection to the previous sequence enclosed by matching
character, see the `matching_pairs` option in <<options#,`:doc options`>> characters, see the `matching_pairs` option in <<options#,`:doc options`>>
*x*:: *x*::
select line on which the end of each selection lies (or next line when end lies select line on which the end of each selection lies (or next line when end lies
@ -292,10 +292,10 @@ Yanking (copying) and pasting use the *"* register by default (See <<registers#,
indent selected lines, including empty lines indent selected lines, including empty lines
*<*:: *<*::
deindent selected lines unindent selected lines
*<a-<>*:: *<a-<>*::
deindent selected lines, do not remove incomplete indent (3 leading unindent selected lines, do not remove incomplete indent (3 leading
spaces when indent is 4) spaces when indent is 4)
*u*:: *u*::
@ -347,7 +347,7 @@ Yanking (copying) and pasting use the *"* register by default (See <<registers#,
3<a-)> 3<a-)>
---------- ----------
rotate (1, 2, 3) and (3, 4, 6) independently rotates (1, 2, 3) and (3, 4, 6) independently
*<a-(>*:: *<a-(>*::
rotate selections content backward rotate selections content backward

View File

@ -31,7 +31,7 @@ command:
unset-option <scope> <name> unset-option <scope> <name>
--------------------------- ---------------------------
Unsetting an option will make it fallback to the value of its parent mode, Unsetting an option will make it fallback to the value of its parent scope,
hence options cannot be unset from the *global* scope. hence options cannot be unset from the *global* scope.
[[declare-option]] [[declare-option]]
@ -111,9 +111,9 @@ are exclusively available to built-in options.
All numeric fields are 1-based. All numeric fields are 1-based.
When the `update-option` is used on an option of this type, its When the command `update-option` is used on an option of this type,
ranges gets updated according to all the buffer modifications that its ranges get updated according to all the buffer modifications
happened since its timestamp. that happened since its timestamp.
`set -add` appends the new pair to the list `set -add` appends the new pair to the list
@ -122,8 +122,8 @@ are exclusively available to built-in options.
*line-specs*:: *line-specs*::
a list of a line number and a corresponding flag (`<line>|<flag a list of a line number and a corresponding flag (`<line>|<flag
text>`), except for the first element which is just the timestamp text>`), except for the first element which is just the timestamp
of the buffer. When the `update-option` is used on an option of this of the buffer. When `update-option` is used on an option of this
type, its lines gets updated according to all the buffer modifications type, its lines get updated according to all the buffer modifications
that happened since its timestamp. that happened since its timestamp.
See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>) See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
`set -add` appends the new spec to the list `set -add` appends the new spec to the list
@ -134,7 +134,7 @@ are exclusively available to built-in options.
`<line>.<column>[+<length>]@<timestamp>` format to define where the `<line>.<column>[+<length>]@<timestamp>` format to define where the
completion apply in the buffer. completion apply in the buffer.
Select commands are arbitrary kakoune commands that will be executed Select commands are arbitrary Kakoune commands that will be executed
each time the element is selected in the menu. The common use case is each time the element is selected in the menu. The common use case is
to display element specific documentation. to display element specific documentation.

View File

@ -147,8 +147,7 @@ More complex assertions can be expressed with lookarounds:
not match the text preceding the current position not match the text preceding the current position
For performance reasons lookaround contents must be sequence of literals, For performance reasons lookaround contents must be sequence of literals,
character classes or any-character (`.`); The use of quantifiers character classes or any-character (`.`); Quantifiers are not supported.
are not supported.
For example, `(?<!bar)(?=foo).` will match any character which is not For example, `(?<!bar)(?=foo).` will match any character which is not
preceded by `bar` and where `foo` matches from the current position preceded by `bar` and where `foo` matches from the current position
@ -179,7 +178,7 @@ The syntax tries to follow the ECMAScript regex syntax as defined by
https://www.ecma-international.org/ecma-262/8.0/ some divergences https://www.ecma-international.org/ecma-262/8.0/ some divergences
exists for ease of use or performance reasons: exists for ease of use or performance reasons:
* lookarounds are not arbitrary, but lookbehind are supported. * lookarounds are not arbitrary, but lookbehind is supported.
* `\K`, `\Q..\E`, `\A`, `\h` and `\z` are added. * `\K`, `\Q..\E`, `\A`, `\h` and `\z` are added.
* Stricter handling of escaping, as we introduce additional * Stricter handling of escaping, as we introduce additional
escapes, identity escapes like `\X` with X a non-special character escapes, identity escapes like `\X` with X a non-special character

View File

@ -102,7 +102,7 @@ with:
`%val{buffile}` of the buffer selections relate to `%val{buffile}` of the buffer selections relate to
*timestamp*:: *timestamp*::
`%val{timestamp}` at which the selection apply to `%val{timestamp}` at which the selection applies to
*main sel index*:: *main sel index*::
0-based index of the main selection 0-based index of the main selection