diff --git a/README.asciidoc b/README.asciidoc index 275224f6d..bc66177ba 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -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 diff --git a/doc/manpages/commands.asciidoc b/doc/manpages/commands.asciidoc index 80013770c..b4070bbbe 100644 --- a/doc/manpages/commands.asciidoc +++ b/doc/manpages/commands.asciidoc @@ -83,7 +83,11 @@ command *q!* has to be used). does nothing, but arguments will be evaluated (e.g. shell expansion) *set* :: - 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* :: unset the value of an option (c.f. the 'options' documentation page) diff --git a/doc/manpages/hooks.asciidoc b/doc/manpages/hooks.asciidoc index 96dbc9f19..5d71e9c99 100644 --- a/doc/manpages/hooks.asciidoc +++ b/doc/manpages/hooks.asciidoc @@ -15,7 +15,8 @@ register a hook use the following command: hook [-group ] ---------------------------------------------------------------------- -*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. @@ -144,9 +145,12 @@ Default hooks filtering text is the client name *InsertCompletionShow*:: - Triggered when the insert completion menu gets displayed. + Triggered when the insert completion menu gets displayed *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. diff --git a/doc/manpages/options.asciidoc b/doc/manpages/options.asciidoc index c6ab04947..24e4ee4fa 100644 --- a/doc/manpages/options.asciidoc +++ b/doc/manpages/options.asciidoc @@ -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 diff --git a/doc/manpages/scopes.asciidoc b/doc/manpages/scopes.asciidoc new file mode 100644 index 000000000..2f4202073 --- /dev/null +++ b/doc/manpages/scopes.asciidoc @@ -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').