Merge remote-tracking branch 'lenormf/doc-scopes'
This commit is contained in:
commit
dbae81fa5c
|
@ -871,12 +871,15 @@ Some options are built in Kakoune, and can be used to control it's behaviour:
|
||||||
* `scrolloff` _coord_: number of lines,columns to keep visible around
|
* `scrolloff` _coord_: number of lines,columns to keep visible around
|
||||||
the cursor when scrolling.
|
the cursor when scrolling.
|
||||||
* `eolformat` _enum(lf|crlf)_: the format of end of lines when
|
* `eolformat` _enum(lf|crlf)_: the format of end of lines when
|
||||||
writing a buffer, this is autodetected on load.
|
writing a buffer, this is autodetected on load; values of this option
|
||||||
|
assigned to the `window` scope are ignored
|
||||||
* `BOM` _enum(none|utf8)_: define if the file should be written
|
* `BOM` _enum(none|utf8)_: define if the file should be written
|
||||||
with an unicode byte order mark.
|
with an unicode byte order mark. Values of this option assigned to the
|
||||||
|
`window` scope are ignored
|
||||||
* `readonly` _bool_: prevent modifications from being saved to disk, all
|
* `readonly` _bool_: prevent modifications from being saved to disk, all
|
||||||
buffers if set to `true` in the `global` scope, or current buffer if set in
|
buffers if set to `true` in the `global` scope, or current buffer if set in
|
||||||
the `buffer` scope.
|
the `buffer` scope; values of this option assigned to the `window` scope are
|
||||||
|
ignored
|
||||||
* `incsearch` _bool_: execute search as it is typed
|
* `incsearch` _bool_: execute search as it is typed
|
||||||
* `aligntab` _bool_: use tabs for alignment command
|
* `aligntab` _bool_: use tabs for alignment command
|
||||||
* `autoinfo` _flags(command|onkey|normal)_: display automatic information
|
* `autoinfo` _flags(command|onkey|normal)_: display automatic information
|
||||||
|
|
|
@ -83,7 +83,11 @@ command *q!* has to be used).
|
||||||
does nothing, but arguments will be evaluated (e.g. shell expansion)
|
does nothing, but arguments will be evaluated (e.g. shell expansion)
|
||||||
|
|
||||||
*set* <scope> <name> <value>::
|
*set* <scope> <name> <value>::
|
||||||
change the value of an option (c.f. the 'options' documentation page)
|
change the value of an option (c.f. the 'options' documentation page),
|
||||||
|
note that the name of a particular buffer can be specified when the
|
||||||
|
target *scope* is 'buffer', e.g. set buffer=/path/to/buffer foo "bar";
|
||||||
|
the scope can also take the `current` special value, which will automatically
|
||||||
|
point to the narrowest scope available in the current context
|
||||||
|
|
||||||
*unset* <scope> <name>::
|
*unset* <scope> <name>::
|
||||||
unset the value of an option (c.f. the 'options' documentation page)
|
unset the value of an option (c.f. the 'options' documentation page)
|
||||||
|
|
|
@ -15,7 +15,8 @@ register a hook use the following command:
|
||||||
hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
|
hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
|
||||||
----------------------------------------------------------------------
|
----------------------------------------------------------------------
|
||||||
|
|
||||||
*scope* can be one of *global*, *buffer* or *window*.
|
*scope* can be one of *global*, *buffer* or *window* (c.f. the
|
||||||
|
'scopes' documentation page).
|
||||||
|
|
||||||
*command* is a string containing the commands to execute when the hook
|
*command* is a string containing the commands to execute when the hook
|
||||||
is called.
|
is called.
|
||||||
|
@ -144,9 +145,12 @@ Default hooks
|
||||||
filtering text is the client name
|
filtering text is the client name
|
||||||
|
|
||||||
*InsertCompletionShow*::
|
*InsertCompletionShow*::
|
||||||
Triggered when the insert completion menu gets displayed.
|
Triggered when the insert completion menu gets displayed
|
||||||
|
|
||||||
*InsertCompletionHide*::
|
*InsertCompletionHide*::
|
||||||
Triggered when the insert completion menu gets hidden.
|
Triggered when the insert completion menu gets hidden
|
||||||
|
|
||||||
When not specified, the filtering text is an empty string.
|
When not specified, the filtering text is an empty string. Note that
|
||||||
|
some hooks will not consider underlying scopes depending on what context
|
||||||
|
they are bound to be run into, e.g. the `BufWritePost` hook is a buffer
|
||||||
|
hook, and will not consider the `window` scope.
|
||||||
|
|
|
@ -38,23 +38,8 @@ Types
|
||||||
a set of flags, taking a combination of the given values joined by a
|
a set of flags, taking a combination of the given values joined by a
|
||||||
'|' character
|
'|' character
|
||||||
|
|
||||||
Scopes
|
Refer to the 'scopes' documentation page for more information about
|
||||||
------
|
scopes.
|
||||||
*window*::
|
|
||||||
context linked to the window displaying a buffer
|
|
||||||
*buffer*::
|
|
||||||
context linked directly to the buffer
|
|
||||||
*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*).
|
|
||||||
|
|
||||||
Builtin options
|
Builtin options
|
||||||
---------------
|
---------------
|
||||||
|
@ -71,15 +56,18 @@ Builtin options
|
||||||
|
|
||||||
*eolformat* 'enum(lf|crlf)'::
|
*eolformat* 'enum(lf|crlf)'::
|
||||||
the format of end of lines when writing a buffer, this is autodetected
|
the format of end of lines when writing a buffer, this is autodetected
|
||||||
on load
|
on load; values of this option assigned to the `window` scope are
|
||||||
|
ignored
|
||||||
|
|
||||||
*BOM* 'enum(none|utf8)'::
|
*BOM* 'enum(none|utf8)'::
|
||||||
define if the file should be written with an unicode byte order mark
|
define if the file should be written with an unicode byte order mark;
|
||||||
|
values of this option assigned to the `window` scope are ignored
|
||||||
|
|
||||||
*readonly* 'bool'::
|
*readonly* 'bool'::
|
||||||
prevent modifications from being saved to disk, all
|
prevent modifications from being saved to disk, all buffers if set
|
||||||
buffers if set to `true` in the `global` scope, or current buffer if set in
|
to `true` in the `global` scope, or current buffer if set in the
|
||||||
the `buffer` scope.
|
`buffer` scope; values of this option assigned to the `window`
|
||||||
|
scope are ignored
|
||||||
|
|
||||||
*incsearch* 'bool'::
|
*incsearch* 'bool'::
|
||||||
execute search as it is typed
|
execute search as it is typed
|
||||||
|
|
67
doc/manpages/scopes.asciidoc
Normal file
67
doc/manpages/scopes.asciidoc
Normal file
|
@ -0,0 +1,67 @@
|
||||||
|
KAKOUNE(1)
|
||||||
|
==========
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
scopes - a
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Scopes are groups in which a particular Kakoune object (a variable,
|
||||||
|
hook, alias etc) can have different values, depending on the group the
|
||||||
|
value was declared in.
|
||||||
|
|
||||||
|
Names and hierarchy
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Scopes are named as follows:
|
||||||
|
|
||||||
|
*window*::
|
||||||
|
context linked to the window displaying a buffer
|
||||||
|
*buffer*::
|
||||||
|
context linked directly to the buffer
|
||||||
|
*global*::
|
||||||
|
global context linked to the instance of Kakoune
|
||||||
|
|
||||||
|
The following order of priority applies to the above scopes:
|
||||||
|
|
||||||
|
--------------------------
|
||||||
|
window ]> buffer ]> global
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
The above priority line implies that objects can have individual values that
|
||||||
|
will be resolved first in the *window* scope (highest priority), then in
|
||||||
|
the *buffer* scope, and finally in the *global* scope (lowest priority).
|
||||||
|
|
||||||
|
Uses
|
||||||
|
----
|
||||||
|
|
||||||
|
The scope paradigm is very useful as it allows the user to customize the
|
||||||
|
behavior of the editor without modifying the configuration globally, as
|
||||||
|
is the case with other editors who only have a single *global* scope by
|
||||||
|
default.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
*filetype*::
|
||||||
|
A single buffer opened in two separate windows can have different
|
||||||
|
filetypes declared in the *window* scope with 'set' (c.f. the 'options'
|
||||||
|
documentation page)
|
||||||
|
|
||||||
|
*status line*::
|
||||||
|
All the buffers of the current session can have the same information
|
||||||
|
displayed in the status line, except for a specific buffer (the
|
||||||
|
'modelinefmt' option can be declared in the *global* scope, and
|
||||||
|
customized in the *buffer* scope with 'set', c.f. the 'options'
|
||||||
|
documentation page)
|
||||||
|
|
||||||
|
Execution context
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Some commands work in a specific context that might exclude one or
|
||||||
|
several scopes altogether, consequently ignoring some values of a given
|
||||||
|
object.
|
||||||
|
|
||||||
|
Example: the *window* scope is never considered when resolving the
|
||||||
|
values of options when writing a buffer (e.g. 'BOM', 'eolformat').
|
Loading…
Reference in New Issue
Block a user