xenia/kakoune
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update highlighters documentation

Browse Source 
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
README.asciidoc
View File

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

89
doc/manpages/highlighters.asciidoc
View File

@ -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_name2> <opening2> <closing2> <recurse2>... <region_name1> <opening1> <closing1> <recurse1> \
------------------------------------------------------------------------------ <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.