mirror of
https://github.com/mawww/kakoune.git
synced 2024-11-22 05:03:56 +03:00
doc: fix typos and clarify some parts
This commit is contained in:
Johannes Altmanninger
parent
3385c6a20e
commit
e4f7d42396
@ -1,12 +1,12 @@
|
||||
Edition auto insertion in Kakoune
|
||||
=================================
|
||||
|
||||
It is a quite common feature for code editor to help the programmer by
|
||||
automatically inserting some text in certain contexts. This document
|
||||
It is a quite common feature for a code editor to help the programmer
|
||||
by automatically inserting some text in certain contexts. This document
|
||||
goal is to explain how this is done in Kakoune.
|
||||
|
||||
There is no special support in Kakoune for this problem, hooks are
|
||||
expected to be used in order to manage that, and the normal kakoune
|
||||
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
|
||||
editing command are expected to be expressive enough so that relatively
|
||||
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
|
||||
----------------------------------------------------------------
|
||||
|
||||
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
|
||||
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
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
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
|
||||
what would happen if we would continue with no selections; the following
|
||||
commands would have no effects.
|
||||
|
||||
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
|
||||
wrapped in a try command. So we would have:
|
||||
|
||||
|
||||
@ -13,7 +13,7 @@ released versions.
|
||||
|
||||
* 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.
|
||||
|
||||
== Kakoune v2020.01.16
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
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
|
||||
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>::
|
||||
*alias* help +
|
||||
@ -74,12 +74,12 @@ of the file onto the filesystem
|
||||
|
||||
*write-all* [-sync]::
|
||||
*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>]::
|
||||
*alias* q +
|
||||
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>
|
||||
|
||||
*write-quit[!]* [-sync] [<exit status>]::
|
||||
@ -227,7 +227,7 @@ of the file onto the filesystem
|
||||
filesystem.
|
||||
|
||||
*-quoting* <quoting>:::
|
||||
define how each arguments are quoted in echo output:
|
||||
define how arguments are quoted in echo output:
|
||||
|
||||
- *raw* (default)::::
|
||||
just join each argument with a space
|
||||
@ -446,10 +446,10 @@ New commands can be defined using the *define-command* command:
|
||||
|
||||
*-shell-script-completion*:::
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- *kak_token_to_complete*::::
|
||||
@ -461,12 +461,12 @@ New commands can be defined using the *define-command* command:
|
||||
|
||||
*-shell-script-candidates*:::
|
||||
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
|
||||
completion session, candidates are cached and then used by kakoune
|
||||
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:
|
||||
|
||||
- *kak_token_to_complete*::::
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
== 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
|
||||
following format:
|
||||
|
||||
@ -41,9 +41,9 @@ following format:
|
||||
*i*:::
|
||||
italic
|
||||
*F*:::
|
||||
final, override the previous face instead of merging with it
|
||||
an will only be replaced if another face with the final
|
||||
attribute is applied
|
||||
final, override the previous face instead of merging with it,
|
||||
and this face will only be replaced if another face with
|
||||
the final attribute is applied
|
||||
*f*:::
|
||||
final foreground, as final but only applies to face's
|
||||
foreground color
|
||||
@ -56,7 +56,7 @@ following format:
|
||||
|
||||
'base'::
|
||||
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.
|
||||
|
||||
== Builtin faces
|
||||
@ -80,10 +80,10 @@ areas of the user interface:
|
||||
cursor of the secondary selection
|
||||
|
||||
*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*::
|
||||
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*::
|
||||
face for the selected element in menus
|
||||
@ -147,7 +147,7 @@ The following faces are used by builtin highlighters if enabled.
|
||||
== Markup strings
|
||||
|
||||
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,
|
||||
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 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}"
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
== 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
|
||||
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.
|
||||
|
||||
== 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
|
||||
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.
|
||||
|
||||
== Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune ?
|
||||
@ -145,7 +145,7 @@ possible.
|
||||
|
||||
== My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ?
|
||||
|
||||
The `file` utility has several short comings, such as detecting the
|
||||
The `file` utility has several shortcomings, such as detecting the
|
||||
wrong mimetype for a file containing data with different syntax, e.g.
|
||||
a Python script containing hardcoded HTML templates detected as an HTML
|
||||
file.
|
||||
@ -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
|
||||
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
|
||||
terminal multiplexers (e.g. `tmux`), as opposed to emulating their
|
||||
functionalities.
|
||||
|
||||
@ -62,7 +62,7 @@ highlighter is replaced with the new one.
|
||||
highlight the cursor line with a separate face
|
||||
|
||||
*-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 '|')
|
||||
|
||||
*-min-digits* <num>:::
|
||||
@ -123,7 +123,7 @@ add-highlighter window/ dynregex '%reg{/}' 0:+i
|
||||
== Specs highlighters
|
||||
|
||||
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`
|
||||
and `range-specs`.
|
||||
|
||||
@ -217,7 +217,7 @@ add-highlighter <path>/<name>/<region_name> region \
|
||||
match of *end*, preventing it from closing the region.
|
||||
|
||||
*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.
|
||||
|
||||
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.
|
||||
|
||||
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*
|
||||
highlighter type.
|
||||
|
||||
|
||||
@ -171,7 +171,7 @@ name. Hooks with no description will always use an empty string.
|
||||
*RawKey* `key`::
|
||||
Triggered whenever a key is pressed by the user, regardless of what mode
|
||||
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
|
||||
<<execeval#execute-keys-specific-switches,`:doc execeval execute-keys-specific-switches`>>).
|
||||
|
||||
@ -194,7 +194,7 @@ vars are available:
|
||||
== Disabling Hooks
|
||||
|
||||
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
|
||||
session).
|
||||
|
||||
|
||||
@ -144,7 +144,7 @@ the Shift modifier and moving will extend each selection instead.
|
||||
repeat last object or *f*/*t* selection command
|
||||
|
||||
*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`>>
|
||||
|
||||
*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`>>
|
||||
|
||||
*<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`>>
|
||||
|
||||
*<a-M>*::
|
||||
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*::
|
||||
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
|
||||
|
||||
*<*::
|
||||
deindent selected lines
|
||||
unindent selected lines
|
||||
|
||||
*<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)
|
||||
|
||||
*u*::
|
||||
@ -347,7 +347,7 @@ Yanking (copying) and pasting use the *"* register by default (See <<registers#,
|
||||
3<a-)>
|
||||
----------
|
||||
|
||||
rotate (1, 2, 3) and (3, 4, 6) independently
|
||||
rotates (1, 2, 3) and (3, 4, 6) independently
|
||||
|
||||
*<a-(>*::
|
||||
rotate selections content backward
|
||||
|
||||
@ -31,7 +31,7 @@ command:
|
||||
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.
|
||||
|
||||
[[declare-option]]
|
||||
@ -111,9 +111,9 @@ are exclusively available to built-in options.
|
||||
|
||||
All numeric fields are 1-based.
|
||||
|
||||
When the `update-option` is used on an option of this type, its
|
||||
ranges gets updated according to all the buffer modifications that
|
||||
happened since its timestamp.
|
||||
When the command `update-option` is used on an option of this type,
|
||||
its ranges get updated according to all the buffer modifications
|
||||
that happened since its timestamp.
|
||||
|
||||
`set -add` appends the new pair to the list
|
||||
|
||||
@ -122,8 +122,8 @@ are exclusively available to built-in options.
|
||||
*line-specs*::
|
||||
a list of a line number and a corresponding flag (`<line>|<flag
|
||||
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
|
||||
type, its lines gets updated according to all the buffer modifications
|
||||
of the buffer. When `update-option` is used on an option of this
|
||||
type, its lines get updated according to all the buffer modifications
|
||||
that happened since its timestamp.
|
||||
See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
|
||||
`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
|
||||
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
|
||||
to display element specific documentation.
|
||||
|
||||
|
||||
@ -147,8 +147,7 @@ More complex assertions can be expressed with lookarounds:
|
||||
not match the text preceding the current position
|
||||
|
||||
For performance reasons lookaround contents must be sequence of literals,
|
||||
character classes or any-character (`.`); The use of quantifiers
|
||||
are not supported.
|
||||
character classes or any-character (`.`); Quantifiers are not supported.
|
||||
|
||||
For example, `(?<!bar)(?=foo).` will match any character which is not
|
||||
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
|
||||
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.
|
||||
* Stricter handling of escaping, as we introduce additional
|
||||
escapes, identity escapes like `\X` with X a non-special character
|
||||
|
||||
@ -102,7 +102,7 @@ with:
|
||||
`%val{buffile}` of the buffer selections relate to
|
||||
|
||||
*timestamp*::
|
||||
`%val{timestamp}` at which the selection apply to
|
||||
`%val{timestamp}` at which the selection applies to
|
||||
|
||||
*main sel index*::
|
||||
0-based index of the main selection
|
||||
|
||||
Loading…
Reference in New Issue
Block a user