Update highlighters documentation

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

1 files changed, 41 insertions, 48 deletions

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.