Update highlighters documentation

Remove documentation from the README and point to the highlighters
doc.
This commit is contained in:
Maxime Coste 2017-11-01 19:00:44 +08:00
parent 25dac6b24e
commit 412c21bf70
2 changed files with 42 additions and 210 deletions

View File

@ -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
~~~~~

View File

@ -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:
Highlighters can be put in the shared scope in order to make them reusable.
----------------------------------------
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.
---------------------------------------
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.