Update highlighters documentation

Remove documentation from the README and point to the highlighters
doc.

2 files changed, 42 insertions, 210 deletions

diff --git a/README.asciidoc b/README.asciidoc
index 944aae29..2b8530b7 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -1251,168 +1251,7 @@ and entering back insert mode (with which binding ?)
 Highlighters
 ~~~~~~~~~~~~
 
-Manipulation of the displayed text is done through highlighters, which can be added
-or removed with the command
-
----------------------------------------------------------------
-:add-highlighter <highlighter_name> <highlighter_parameters...>
----------------------------------------------------------------
-
-and
-
-------------------------------------
-:remove-highlighter <highlighter_id>
-------------------------------------
-
-`highlighter_id` is a name generated by the highlighter specified with `highlighter_name`,
-possibly dependent on the parameters. Use command completion on remove-highlighter to see the existing
-highlighters' id.
-
-General highlighters are:
-
- * `regex <ex> <capture_id>:<face>...`: highlight a regex, takes the regex as
-       first parameter, followed by any number of face parameters.
-       For example: `:add-highlighter regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red`
-       will highlight C++ style comments in cyan, with an eventual 'TODO:' in
-       yellow on red background.
- * `dynregex`: Similar to regex, but expand (like a command parameter would) the
-       given expression before building a regex from the result.
- * `flag_lines <face> <option_name>`: add a column in front of the buffer,
-       and display the flags specified in <option_name>, using <face>
- * `show_matching`: highlight matching char of the character under the selections'
-       cursor using `MatchingChar` face.
- * `show_whitespaces \<-tab <separator> \<-tabpad <separator> \<-lf <separator> \<-spc <separator> \<-nbsp <separator>`: display symbols on top of whitespaces to make them more explicit using the Whitespace face.
- * `number_lines \<-relative> \<-hlcursor> \<-separator <separator text>`: show line numbers.
-       The -relative switch will show line numbers relative to the main cursor line, the
-       -hlcursor switch will highlight the cursor line with a separate face. With the
-       -separator switch one can specify a string to separate the line numbers column with
-       the rest of the buffer, default is `|`.
- * `wrap \<-word> \<-width <max_width>`: Soft wrap buffer content to the smallest of window width and
-      max_width. Wrap at word boundaries if `-word` is specified.
- * `fill <face>`: fill using given face, mostly useful with <<regions-highlighters,Regions highlighters>>
- * `ranges <option_name>`: use the data in the range-specs option of the given name to highlight the buffer.
-        The string part of the is interpretted as a face to apply to the range.
- * `replace-ranges <option_name>`: use the data in the range-specs option of the given name to highlight the buffer.
-        The string part of the is interpretted as a display line to display in place of the range.
- * `column <number> <face>`: highlight column 'number' with the given face
- * `line <number> <face>`: highlight line 'number' with the given face
-
-Highlighting Groups
-^^^^^^^^^^^^^^^^^^^
-
-The `group` highlighter is a container for other highlighters. You can add
-a group to the current window using
-
-----------------------------
-add-highlighter group <name>
-----------------------------
-
-and then the `-group` switch of `add-highlighter` provides a mean to add highlighters
-inside this group.
-
-------------------------------------------------
-add-highlighter -group <name> <type> <params>...
-------------------------------------------------
-
-Groups can contain other groups, the `-group` switch can be used to define a path.
-
-----------------------------------------------------------
-add-highlighter -group <name> group <subname>
-add-highlighter -group <name>/<subname> <type> <params>...
-----------------------------------------------------------
-
-[[regions-highlighters]]
-Regions highlighters
-^^^^^^^^^^^^^^^^^^^^
-
-A special highlighter provides a way to segment the buffer into regions, which are
-to be highlighted differently.
-
-A region is defined by 4 parameters:
-
-------------------------------------
-<name> <opening> <closing> <recurse>
-------------------------------------
-
-`name` is user defined, `opening`, `closing` and `recurse` are regexes.
-
- * `opening` defines the region start text
- * `closing` defines the region end text
- * `recurse` defines the text that matches recursively an end token into the region.
-
-`recurse` is useful for regions that can be nested, for example the `%sh{ ... }`
-construct in kakoune accept nested `{ ... }` so `%sh{ ... { ... } ... }` is valid.
-This region can be defined with:
-
-------------------------
-shell_expand %sh\{ \} \{
-------------------------
-
-Regions are used in the `regions` highlighter which can take any number
-of regions.
-
----------------------------------------------------------------------------------
-add-highlighter regions <name> <region_name1> <opening1> <closing1> <recurse1>  \
-                     <region_name2> <opening2> <closing2> <recurse2>...
----------------------------------------------------------------------------------
-
-The above command defines multiple regions in which other highlighters can be added as follows:
-
------------------------------------------------
-add-highlighter -group <name>/<region_name> ...
------------------------------------------------
-
-Regions are matched using the left-most rule: the left-most region opening starts
-a new region. When a region closes, the closest next opening start another region.
-
-That matches the rule governing most programming language parsing.
-
-`regions` also supports a `-default <default_region>` switch to define the
-default region, when no other region matches the current buffer range.
-
-Most programming languages can then be properly highlighted using a `regions`
-highlighter as root:
-
------------------------------------------------------------------
-add-highlighter regions -default code <lang> \
-    string <str_opening> <str_closing> <str_recurse> \
-    comment <comment_opening> <comment_closing> <comment_recurse>
-
-add-highlighter -group <lang>/code ...
-add-highlighter -group <lang>/string ...
-add-highlighter -group <lang>/comment ...
------------------------------------------------------------------
-
-Shared Highlighters
-^^^^^^^^^^^^^^^^^^^
-
-Highlighters are often defined for a specific filetype, and it makes then sense to
-share the highlighters between all the windows on the same filetypes.
-
-A shared highlighter can be defined with the `:add-highlighter` command
-
-----------------------------------------
-add-highlighter -group /<group_name> ...
-----------------------------------------
-
-When the group switch values starts with a '/', it references a group in the
-shared highlighters, rather than the window highlighters.
-
-The common case would be to create a named shared group, and then fill it
-with highlighters:
-
---------------------------------------
-add-highlighter -group / group <name>
-add-highlighter -group /name regex ...
---------------------------------------
-
-It can then be referenced in a window using the `ref` highlighter.
-
---------------------------
-add-highlighter ref <name>
---------------------------
-
-The `ref` can reference any named highlighter in the shared namespace.
+See `:doc highlighters` 
 
 Hooks
 ~~~~~
diff --git a/doc/manpages/highlighters.asciidoc b/doc/manpages/highlighters.asciidoc
index 13a04c02..e4b56a6b 100644
--- a/doc/manpages/highlighters.asciidoc
+++ b/doc/manpages/highlighters.asciidoc
@@ -11,15 +11,19 @@ Description
 Manipulation of the displayed text is done through highlighters, which can
 be added or removed with the following commands:
 
----------------------------------------------------------------
-add-highlighter <highlighter_name> <highlighter_parameters> ...
----------------------------------------------------------------
+----------------------------------------------------------------------
+add-highlighter <path> <highlighter_name> <highlighter_parameters> ...
+----------------------------------------------------------------------
 
 and
 
------------------------------------
-remove-highlighter <highlighter_id>
------------------------------------
+------------------------------------------
+remove-highlighter <path>/<highlighter_id>
+------------------------------------------
+
+*path* is the name of an highlighter group, it is expressed as a */*
+separated path starting with a scope. Scopes are *global*, *buffer*,
+*window* and *shared*
 
 *highlighter_id* is a name generated by the highlighter specified with
 *highlighter_name*, possibly dependent on the parameters. Use command
@@ -32,9 +36,9 @@ General highlighters
 	highlight a regex, takes the regex as first parameter, followed by
 	any number of face parameters. For example:
 
-----------------------------------------------------------------
-    add-highlighter regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red
-----------------------------------------------------------------
+-------------------------------------------------------------------
+add-highlighter window regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red
+-------------------------------------------------------------------
 
 	will highlight C++ style comments in cyan, with an eventual 'TODO:'
 	in yellow on red background
@@ -116,34 +120,25 @@ Highlighting Groups
 -------------------
 
 The *group* highlighter is a container for other highlighters. You can add a
-group to the current window using
+a subgroup to an existing group, or scope using:
 
-----------------------------
-add-highlighter group <name>
-----------------------------
+-----------------------------------
+add-highlighter <path> group <name>
+-----------------------------------
 
-The *-group* switch of the *add-highlighter* command provides a mean to add highlighters
-inside this group:
+That group is then accessible using the *<path>/<name>* path
 
 ------------------------------------------------
-add-highlighter -group <name> <type> <params>...
+add-highlighter <path>/<name> <type> <params>...
 ------------------------------------------------
 
-Groups can contain other groups, the *-group* switch can be used to define
-a path as follows:
-
-----------------------------------------------------------
-add-highlighter -group <name> group <subname>
-add-highlighter -group <name>/<subname> <type> <params>...
-----------------------------------------------------------
-
 In order to specify which kinds of highlighters can be added to a given group, the *-passes*
 flag set can be passed along with the group name. Possible values for this option can be one
 or several (separated with a pipe sign) of *colorize*, *move* or *wrap* (default: *colorize*):
 
--------------------------------------------------------
-add-highlighter group -passes colorize|move|wrap <name>
--------------------------------------------------------
+--------------------------------------------------------------
+add-highlighter window group -passes colorize|move|wrap <name>
+--------------------------------------------------------------
 
 Regions highlighters
 --------------------
@@ -185,15 +180,16 @@ of regions.
 
 The following command:
 
-------------------------------------------------------------------------------
-add-highlighter regions <name> <region_name1> <opening1> <closing1> <recurse1>
-				<region_name2> <opening2> <closing2> <recurse2>...
-------------------------------------------------------------------------------
+------------------------------------------------------
+add-highlighter <path> regions <name> \
+    <region_name1> <opening1> <closing1> <recurse1> \
+    <region_name2> <opening2> <closing2> <recurse2>...
+------------------------------------------------------
 
 defines multiple regions in which other highlighters can be added as follows:
 
 -----------------------------------------------
-add-highlighter -group <name>/<region_name> ...
+add-highlighter <path>/<name>/<region_name> ...
 -----------------------------------------------
 
 Regions are matched using the left-most rule: the left-most region opening
@@ -213,13 +209,13 @@ Most programming languages can then be properly highlighted using a region
 highlighter as root:
 
 -----------------------------------------------------------------
-add-highlighter regions -default code <lang> \
+add-highlighter <path> regions -default code <lang> \
 	string <str_opening> <str_closing> <str_recurse> \
 	comment <comment_opening> <comment_closing> <comment_recurse>
 
-add-highlighter -group <lang>/code ...
-add-highlighter -group <lang>/string ...
-add-highlighter -group <lang>/comment ...
+add-highlighter <path>/<lang>/code ...
+add-highlighter <path>/<lang>/string ...
+add-highlighter <path>/<lang>/comment ...
 -----------------------------------------------------------------
 
 Shared Highlighters
@@ -228,22 +224,19 @@ Shared Highlighters
 Highlighters are often defined for a specific filetype, and it makes then
 sense to share the highlighters between all the windows on the same filetypes.
 
-A shared highlighter can be defined with the following command:
-
-----------------------------------------
-add-highlighter -group /<group_name> ...
-----------------------------------------
+Highlighters can be put in the shared scope in order to make them reusable.
 
-When the group switch values starts with a '/', it references a group in
-the shared highlighters, rather than the window highlighters.
+---------------------------------------
+add-highlighter shared/<group_name> ...
+---------------------------------------
 
 The common case would be to create a named shared group, and then fill it
 with highlighters:
 
---------------------------------------
-add-highlighter -group / group <name>
-add-highlighter -group /name regex ...
---------------------------------------
+---------------------------------------
+add-highlighter shared/ group <name>
+add-highlighter shared/<name> regex ...
+---------------------------------------
 
 It can then be referenced in a window using the ref highlighter.
 
@@ -251,4 +244,4 @@ It can then be referenced in a window using the ref highlighter.
 add-highlighter ref <name>
 --------------------------
 
-The ref can reference any named highlighter in the shared namespace.
+The ref can reference any named highlighter in the shared scope.