Merge remote-tracking branch 'lenormf/doc-scopes'

5 files changed, 96 insertions, 30 deletions

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..b4070bbb 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* <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 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..5d71e9c9 100644
--- a/doc/manpages/hooks.asciidoc
+++ b/doc/manpages/hooks.asciidoc
@@ -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.
@@ -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 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').