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
|
||||
~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
~~~~~
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
------------------------------------------------------
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user