From 8b133e32d60fc60594482fff72dd52c1d9ddd27a Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Thu, 13 Oct 2016 11:55:09 +0300 Subject: [PATCH 1/2] Add a dedicated documentation page about scopes Information related to scopes have also been modified in other documentation pages. --- README.asciidoc | 9 +++-- doc/manpages/commands.asciidoc | 4 +- doc/manpages/hooks.asciidoc | 3 +- doc/manpages/options.asciidoc | 32 +++++----------- doc/manpages/scopes.asciidoc | 67 ++++++++++++++++++++++++++++++++++ 5 files changed, 88 insertions(+), 27 deletions(-) create mode 100644 doc/manpages/scopes.asciidoc diff --git a/README.asciidoc b/README.asciidoc index 275224f6..bc66177b 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 80013770..8e910da1 100644 --- a/doc/manpages/commands.asciidoc +++ b/doc/manpages/commands.asciidoc @@ -83,7 +83,9 @@ 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" *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 96dbc9f1..d8c65e3b 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. diff --git a/doc/manpages/options.asciidoc b/doc/manpages/options.asciidoc index c6ab0494..24e4ee4f 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 00000000..2f420207 --- /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'). From f4236fbb8bef31ce1fcdb8a8b696cc4ca433ead8 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Tue, 18 Oct 2016 15:36:43 +0300 Subject: [PATCH 2/2] Document the `current` scope and some hooks behaviour --- doc/manpages/commands.asciidoc | 4 +++- doc/manpages/hooks.asciidoc | 9 ++++++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/manpages/commands.asciidoc b/doc/manpages/commands.asciidoc index 8e910da1..b4070bbb 100644 --- a/doc/manpages/commands.asciidoc +++ b/doc/manpages/commands.asciidoc @@ -85,7 +85,9 @@ command *q!* has to be used). *set* :: 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" + 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 d8c65e3b..5d71e9c9 100644 --- a/doc/manpages/hooks.asciidoc +++ b/doc/manpages/hooks.asciidoc @@ -145,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.