196 lines
4.9 KiB
Plaintext
196 lines
4.9 KiB
Plaintext
|
.TH KAKOUNE 1 "" "" "HIGHLIGHTERS"
|
||
|
|
|
||
|
|
.TP
|
||
|
|
Manipulation of the displayed text is done through highlighters, which can be added or removed with the following commands:
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " <highlighter_name> <highlighter_parameters> …"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
and
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR rmhl " <highlighter_id>"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
.IR highlighter_id
|
||
|
|
is a name generated by the highlighter specified with
|
||
|
|
.IR highlighter_name ","
|
||
|
|
possibly dependent on the parameters. Use command completion in a prompt on the
|
||
|
|
.IR rmhl
|
||
|
|
command to see the existing highlighters ids.
|
||
|
|
|
||
|
|
.SH General highlighters
|
||
|
|
.TP
|
||
|
|
.BR regex " <ex> <capture_id>:<face> …"
|
||
|
|
highlight a regex, takes the regex as first parameter, followed by any number of face parameters. For example:
|
||
|
|
.IR addhl 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
|
||
|
|
.TP
|
||
|
|
.BR dynregex
|
||
|
|
Similar to regex, but expand (like a command paramater would) the given expression before building a regex from the result
|
||
|
|
.TP
|
||
|
|
.BR flag_lines " <flag> <option_name>"
|
||
|
|
add a column in front of text, and display the given flag in it for everly line contained in the int-list option named <option_name>
|
||
|
|
.TP
|
||
|
|
.BR show_matching
|
||
|
|
highlight matching char of the character under the selections cursor using MatchingChar face
|
||
|
|
.TP
|
||
|
|
.BR number_lines " <-relative> <-hlcursor> <-separator <separator text> >"
|
||
|
|
show line numbers, with the following options:
|
||
|
|
.RS 7
|
||
|
|
.TP
|
||
|
|
.BR -relative
|
||
|
|
show line numbers relative to the main cursor line
|
||
|
|
.TP
|
||
|
|
.BR -hlcursor
|
||
|
|
highlight the cursor line with a separate face
|
||
|
|
.TP
|
||
|
|
.BR -separator
|
||
|
|
specify a string to separate the line numbers column with the rest of the buffer (default is
|
||
|
|
.IR | ")"
|
||
|
|
.RE
|
||
|
|
.TP
|
||
|
|
.BR fill " <face>"
|
||
|
|
fill using the given
|
||
|
|
.IR face ","
|
||
|
|
mostly useful with regions highlighters
|
||
|
|
|
||
|
|
.SH Highlighting Groups
|
||
|
|
|
||
|
|
The group highlighter is a container for other highlighters. You can add a group to the current window using
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " group <name>"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
The
|
||
|
|
.IR -group
|
||
|
|
switch of the
|
||
|
|
.IR addhl
|
||
|
|
command provides a mean to add highlighters inside this group:
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group <name> <type> <params>..."
|
||
|
|
.RE
|
||
|
|
|
||
|
|
Groups can contain other groups, the
|
||
|
|
.IR -group
|
||
|
|
switch can be used to define a path as follows:
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group <name> group <subname>"
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group <name>/<subname> <type> <params>…"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
.SH 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:
|
||
|
|
.TP
|
||
|
|
.BR name
|
||
|
|
user defined, used to identify the region
|
||
|
|
.TP
|
||
|
|
.BR opening
|
||
|
|
regex that defines the region start text
|
||
|
|
.TP
|
||
|
|
.BR closing
|
||
|
|
regex that defines the region end text
|
||
|
|
.TP
|
||
|
|
.BR recurse
|
||
|
|
regex that defines the text that matches recursively an end token into the region
|
||
|
|
.RE
|
||
|
|
|
||
|
|
The
|
||
|
|
.IR recurse
|
||
|
|
option is useful for regions that can be nested, for example the
|
||
|
|
.IR %sh{\ …\ }
|
||
|
|
construct in kakoune accept nested
|
||
|
|
.IR {\ …\ } " so " %sh{\ …\ {\ …\ }\ …\ }
|
||
|
|
is valid. This region can be defined with:
|
||
|
|
.IR shell_expand\ %sh\\{\ \\}\ \\{
|
||
|
|
|
||
|
|
Regions are used in the regions highlighter which can take any number of regions.
|
||
|
|
|
||
|
|
The command:
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " regions <name> <region_name1> <opening1> <closing1> <recurse1>"
|
||
|
|
<region_name2> <opening2> <closing2> <recurse2>…
|
||
|
|
.RE
|
||
|
|
|
||
|
|
defines multiple regions in which other highlighters can be added as follows:
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group <name>/<region_name> …"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
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
|
||
|
|
.IR -default
|
||
|
|
switch to define the default region, when no other region matches the current buffer range:
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR -default " <default_region>"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
Most programming languages can then be properly highlighted using a regions highlighter as root:
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " regions -default code <lang>"
|
||
|
|
string <str_opening> <str_closing> <str_recurse> \
|
||
|
|
comment <comment_opening> <comment_closing> <comment_recurse>
|
||
|
|
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group <lang>/code …"
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group <lang>/string …"
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group <lang>/comment …"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
.SH 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:
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group /<group_name> …"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
When the group switch values starts with a
|
||
|
|
.IR / ","
|
||
|
|
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:
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group / group <name>"
|
||
|
|
.TP
|
||
|
|
.BR addhl " -group /name regex …"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
It can then be referenced in a window using the ref highlighter.
|
||
|
|
|
||
|
|
.RS 3
|
||
|
|
.TP
|
||
|
|
.BR addhl " ref <name>"
|
||
|
|
.RE
|
||
|
|
|
||
|
|
The ref can reference any named highlighter in the shared namespace.
|