Add a dedicated documentation page about scopes

Information related to scopes have also been modified in other documentation
pages.
This commit is contained in:
Frank LENORMAND 2016-10-13 11:55:09 +03:00
parent ee5c246861
commit 8b133e32d6
5 changed files with 88 additions and 27 deletions

View File

@ -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
the cursor when scrolling.
* `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
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
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
* `aligntab` _bool_: use tabs for alignment command
* `autoinfo` _flags(command|onkey|normal)_: display automatic information

View File

@ -83,7 +83,9 @@ command *q!* has to be used).
does nothing, but arguments will be evaluated (e.g. shell expansion)
*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"
*unset* <scope> <name>::
unset the value of an option (c.f. the 'options' documentation page)

View File

@ -15,7 +15,8 @@ register a hook use the following command:
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
is called.

View File

@ -38,23 +38,8 @@ Types
a set of flags, taking a combination of the given values joined by a
'|' character
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*).
Refer to the 'scopes' documentation page for more information about
scopes.
Builtin options
---------------
@ -71,15 +56,18 @@ Builtin options
*eolformat* 'enum(lf|crlf)'::
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)'::
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'::
prevent modifications from being saved to disk, all
buffers if set to `true` in the `global` scope, or current buffer if set in
the `buffer` scope.
prevent modifications from being saved to disk, all buffers if set
to `true` in the `global` scope, or current buffer if set in the
`buffer` scope; values of this option assigned to the `window`
scope are ignored
*incsearch* 'bool'::
execute search as it is typed

View 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').