Update highlighters documentation
Remove documentation from the README and point to the highlighters doc.
This commit is contained in:
Maxime Coste
parent
25dac6b24e
commit
412c21bf70
163
README.asciidoc
163
README.asciidoc
|
|
@ -1251,168 +1251,7 @@ and entering back insert mode (with which binding ?)
|
||||||
Highlighters
|
Highlighters
|
||||||
~~~~~~~~~~~~
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
Manipulation of the displayed text is done through highlighters, which can be added
|
See `:doc highlighters`
|
||||||
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.
|
|
||||||
|
|
||||||
Hooks
|
Hooks
|
||||||
~~~~~
|
~~~~~
|
||||||
|
|
|
||||||
|
|
@ -11,15 +11,19 @@ Description
|
||||||
Manipulation of the displayed text is done through highlighters, which can
|
Manipulation of the displayed text is done through highlighters, which can
|
||||||
be added or removed with the following commands:
|
be added or removed with the following commands:
|
||||||
|
|
||||||
---------------------------------------------------------------
|
----------------------------------------------------------------------
|
||||||
add-highlighter <highlighter_name> <highlighter_parameters> ...
|
add-highlighter <path> <highlighter_name> <highlighter_parameters> ...
|
||||||
---------------------------------------------------------------
|
----------------------------------------------------------------------
|
||||||
|
|
||||||
and
|
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_id* is a name generated by the highlighter specified with
|
||||||
*highlighter_name*, possibly dependent on the parameters. Use command
|
*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
|
highlight a regex, takes the regex as first parameter, followed by
|
||||||
any number of face parameters. For example:
|
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:'
|
will highlight C++ style comments in cyan, with an eventual 'TODO:'
|
||||||
in yellow on red background
|
in yellow on red background
|
||||||
|
|
@ -116,34 +120,25 @@ Highlighting Groups
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
The *group* highlighter is a container for other highlighters. You can add a
|
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
|
That group is then accessible using the *<path>/<name>* path
|
||||||
inside this group:
|
|
||||||
|
|
||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
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*
|
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
|
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*):
|
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
|
Regions highlighters
|
||||||
--------------------
|
--------------------
|
||||||
|
|
@ -185,15 +180,16 @@ of regions.
|
||||||
|
|
||||||
The following command:
|
The following command:
|
||||||
|
|
||||||
------------------------------------------------------------------------------
|
------------------------------------------------------
|
||||||
add-highlighter regions <name> <region_name1> <opening1> <closing1> <recurse1>
|
add-highlighter <path> regions <name> \
|
||||||
|
<region_name1> <opening1> <closing1> <recurse1> \
|
||||||
<region_name2> <opening2> <closing2> <recurse2>...
|
<region_name2> <opening2> <closing2> <recurse2>...
|
||||||
------------------------------------------------------------------------------
|
------------------------------------------------------
|
||||||
|
|
||||||
defines multiple regions in which other highlighters can be added as follows:
|
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
|
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:
|
highlighter as root:
|
||||||
|
|
||||||
-----------------------------------------------------------------
|
-----------------------------------------------------------------
|
||||||
add-highlighter regions -default code <lang> \
|
add-highlighter <path> regions -default code <lang> \
|
||||||
string <str_opening> <str_closing> <str_recurse> \
|
string <str_opening> <str_closing> <str_recurse> \
|
||||||
comment <comment_opening> <comment_closing> <comment_recurse>
|
comment <comment_opening> <comment_closing> <comment_recurse>
|
||||||
|
|
||||||
add-highlighter -group <lang>/code ...
|
add-highlighter <path>/<lang>/code ...
|
||||||
add-highlighter -group <lang>/string ...
|
add-highlighter <path>/<lang>/string ...
|
||||||
add-highlighter -group <lang>/comment ...
|
add-highlighter <path>/<lang>/comment ...
|
||||||
-----------------------------------------------------------------
|
-----------------------------------------------------------------
|
||||||
|
|
||||||
Shared Highlighters
|
Shared Highlighters
|
||||||
|
|
@ -228,22 +224,19 @@ Shared Highlighters
|
||||||
Highlighters are often defined for a specific filetype, and it makes then
|
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.
|
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> ...
|
add-highlighter shared/<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
|
The common case would be to create a named shared group, and then fill it
|
||||||
with highlighters:
|
with highlighters:
|
||||||
|
|
||||||
--------------------------------------
|
---------------------------------------
|
||||||
add-highlighter -group / group <name>
|
add-highlighter shared/ group <name>
|
||||||
add-highlighter -group /name regex ...
|
add-highlighter shared/<name> regex ...
|
||||||
--------------------------------------
|
---------------------------------------
|
||||||
|
|
||||||
It can then be referenced in a window using the ref highlighter.
|
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>
|
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.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user