4fabba3d12
doc.kak now behaves as a basic asciidoc renderer. Asciidoc is unfortunately still a dependency to generate the manpage of the `kak` command.
243 lines
7.7 KiB
Plaintext
243 lines
7.7 KiB
Plaintext
= Highlighters
|
|
|
|
== Description
|
|
|
|
Manipulation of the displayed text is done through highlighters, which can
|
|
be added or removed with the following commands:
|
|
|
|
----------------------------------------------------------------------
|
|
add-highlighter <path> <highlighter_name> <highlighter_parameters> ...
|
|
----------------------------------------------------------------------
|
|
|
|
and
|
|
|
|
------------------------------------------
|
|
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
|
|
completion in a prompt on the *remove-highlighter* command to see the existing highlighters
|
|
ids.
|
|
|
|
== General highlighters
|
|
|
|
*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 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
|
|
|
|
*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* [options]::
|
|
display symbols on top of whitespaces to make them more explicit
|
|
using the Whitespace face, with the following *options*:
|
|
|
|
*-lf* <separator>:::
|
|
a one character long separator that will replace line feeds
|
|
|
|
*-spc* <separator>:::
|
|
a one character long separator that will replace spaces
|
|
|
|
*-nbsp* <separator>:::
|
|
a one character long separator that will replace non-breakable spaces
|
|
|
|
*-tab* <separator>:::
|
|
a one character long separator that will replace tabulations
|
|
|
|
*-tabpad* <separator>:::
|
|
a one character long separator that will be appended to tabulations to honor the *tabstop* option
|
|
|
|
|
|
*number_lines* [options]::
|
|
show line numbers, with the following *options*:
|
|
|
|
*-relative*:::
|
|
show line numbers relative to the main cursor line
|
|
|
|
*-hlcursor*:::
|
|
highlight the cursor line with a separate face
|
|
|
|
*-separator* <separator text>:::
|
|
specify a string to separate the line numbers column with
|
|
the rest of the buffer (default is '|')
|
|
|
|
*wrap* [options]::
|
|
soft wrap buffer text at window width, with the following *options*:
|
|
|
|
*-word*:::
|
|
wrap at word boundaries instead of codepoint boundaries.
|
|
|
|
*-indent*:::
|
|
preserve line indent when wrapping.
|
|
|
|
*-width <max_width>*:::
|
|
wrap text at *max_width* if the window is wider.
|
|
|
|
*fill* <face>::
|
|
fill using the given *face*, mostly useful with 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 face *face*
|
|
|
|
*line* <number> <face>::
|
|
highlight line *number* with face *face*
|
|
|
|
== Highlighting Groups
|
|
|
|
|
|
The *group* highlighter is a container for other highlighters. You can add a
|
|
a subgroup to an existing group, or scope using:
|
|
|
|
-----------------------------------
|
|
add-highlighter <path> group <name>
|
|
-----------------------------------
|
|
|
|
That group is then accessible using the *<path>/<name>* path
|
|
|
|
------------------------------------------------
|
|
add-highlighter <path>/<name> <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 window group -passes colorize|move|wrap <name>
|
|
--------------------------------------------------------------
|
|
|
|
== Regions highlighters
|
|
|
|
A special highlighter provides a way to segment the buffer into regions,
|
|
which are to be highlighted differently.
|
|
|
|
*name*::
|
|
user defined, used to identify the region
|
|
*opening*::
|
|
regex that defines the region start text
|
|
*closing*::
|
|
regex that defines the region end text
|
|
*recurse*::
|
|
regex that defines the text that matches recursively an end token
|
|
into the region
|
|
|
|
The *recurse* option is useful for regions that can be nested, for example
|
|
the following contruct:
|
|
|
|
----------
|
|
%sh{ ... }
|
|
----------
|
|
|
|
accepts nested braces scopes ('{ ... }') so the following string is valid:
|
|
|
|
----------------------
|
|
%sh{ ... { ... } ... }
|
|
----------------------
|
|
|
|
This region can be defined with:
|
|
|
|
------------------------
|
|
shell_expand %sh\{ \} \{
|
|
------------------------
|
|
|
|
Regions are used in the region highlighters which can take any number
|
|
of regions.
|
|
|
|
The following command:
|
|
|
|
------------------------------------------------------
|
|
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 <path>/<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.
|
|
|
|
If the *-match-capture* switch is passed, then region closing and recurse
|
|
matches are considered valid for a given region opening match only if they
|
|
matched the same content for the capture 1.
|
|
|
|
Most programming languages can then be properly highlighted using a region
|
|
highlighter as root:
|
|
|
|
-----------------------------------------------------------------
|
|
add-highlighter <path> regions -default code <lang> \
|
|
string <str_opening> <str_closing> <str_recurse> \
|
|
comment <comment_opening> <comment_closing> <comment_recurse>
|
|
|
|
add-highlighter <path>/<lang>/code ...
|
|
add-highlighter <path>/<lang>/string ...
|
|
add-highlighter <path>/<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.
|
|
|
|
Highlighters can be put in the shared scope in order to make them reusable.
|
|
|
|
---------------------------------------
|
|
add-highlighter shared/<group_name> ...
|
|
---------------------------------------
|
|
|
|
The common case would be to create a named shared group, and then fill it
|
|
with highlighters:
|
|
|
|
---------------------------------------
|
|
add-highlighter shared/ group <name>
|
|
add-highlighter shared/<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 scope.
|