'\" t
.\"     Title: kakoune
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/16/2018
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH KAK_HIGHLIGHTERS 1 "" "" "highlighters"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
highlighters \- a
.SH "DESCRIPTION"
.sp
Manipulation of the displayed text is done through highlighters, which can be added or removed with the following commands:
.sp
.if n \{\
.RS 4
.\}
.nf
addhl <highlighter_name> <highlighter_parameters> \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
and
.sp
.if n \{\
.RS 4
.\}
.nf
rmhl <highlighter_id>
.fi
.if n \{\
.RE
.\}
.sp
\fBhighlighter_id\fR is a name generated by the highlighter specified with \fBhighlighter_name\fR, possibly dependent on the parameters\&. Use command completion in a prompt on the \fBrmhl\fR command to see the existing highlighters ids\&.
.SH "GENERAL HIGHLIGHTERS"
.PP
\fBregex\fR <ex> <capture_id>:<face> \&...
.RS 4
highlight a regex, takes the regex as first parameter, followed by any number of face parameters\&. For example:
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
    addhl regex //(\ehTODO:)?[^\en] 0:cyan 1:yellow,red
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
will highlight C++ style comments in cyan, with an eventual \*(AqTODO:\*(Aq
in yellow on red background
.fi
.if n \{\
.RE
.\}
.PP
\fBdynregex\fR
.RS 4
Similar to regex, but expand (like a command parameter would) the given expression before building a regex from the result
.RE
.PP
\fBflag_lines\fR <flag> <option_name>
.RS 4
add a column in front of text, and display the given flag in it for every line contained in the int\-list option named <option_name>
.RE
.PP
\fBshow_matching\fR
.RS 4
highlight matching char of the character under the selections cursor using MatchingChar face
.RE
.PP
\fBnumber_lines\fR [options]
.RS 4
show line numbers, with the following
\fBoptions\fR:
.PP
\fB\-relative\fR
.RS 4
show line numbers relative to the main cursor line
.RE
.PP
\fB\-hlcursor\fR
.RS 4
highlight the cursor line with a separate face
.RE
.PP
\fB\-separator\fR <separator text>
.RS 4
specify a string to separate the line numbers column with the rest of the buffer (default is
\fI|\fR)
.RE
.RE
.PP
\fBranges\fR <option_name>
.RS 4
use the data in the range\-faces option of the given name to highlight the buffer\&.
.RE
.PP
\fBfill\fR <face>
.RS 4
fill using the given
\fBface\fR, mostly useful with regions highlighters
.RE
.SH "HIGHLIGHTING GROUPS"
.sp
The group highlighter is a container for other highlighters\&. You can add a group to the current window using
.sp
.if n \{\
.RS 4
.\}
.nf
addhl group <name>
.fi
.if n \{\
.RE
.\}
.sp
The \fB\-group\fR switch of the \fBaddhl\fR command provides a mean to add highlighters inside this group:
.sp
.if n \{\
.RS 4
.\}
.nf
addhl \-group <name> <type> <params>\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
Groups can contain other groups, the \fB\-group\fR switch can be used to define a path as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
addhl \-group <name> group <subname>
addhl \-group <name>/<subname> <type> <params>\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.SH "REGIONS HIGHLIGHTERS"
.sp
A special highlighter provides a way to segment the buffer into regions, which are to be highlighted differently\&.
.PP
\fBname\fR
.RS 4
user defined, used to identify the region
.RE
.PP
\fBopening\fR
.RS 4
regex that defines the region start text
.RE
.PP
\fBclosing\fR
.RS 4
regex that defines the region end text
.RE
.PP
\fBrecurse\fR
.RS 4
regex that defines the text that matches recursively an end token into the region
.RE
.sp
The \fBrecurse\fR option is useful for regions that can be nested, for example the following construct:
.sp
.if n \{\
.RS 4
.\}
.nf
%sh{ \&.\&.\&. }
.fi
.if n \{\
.RE
.\}
.sp
accepts nested braces scopes (\fI{ \&... }\fR) so the following string is valid:
.sp
.if n \{\
.RS 4
.\}
.nf
%sh{ \&.\&.\&. { \&.\&.\&. } \&.\&.\&. }
.fi
.if n \{\
.RE
.\}
.sp
This region can be defined with:
.sp
.if n \{\
.RS 4
.\}
.nf
shell_expand %sh\e{ \e} \e{
.fi
.if n \{\
.RE
.\}
.sp
Regions are used in the regions highlighter which can take any number of regions\&.
.sp
The following command:
.sp
.if n \{\
.RS 4
.\}
.nf
addhl regions <name> <region_name1> <opening1> <closing1> <recurse1>
                                <region_name2> <opening2> <closing2> <recurse2>\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
defines multiple regions in which other highlighters can be added as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
addhl \-group <name>/<region_name> \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.sp
That matches the rule governing most programming language parsing\&.
.sp
Regions also supports a \fB\-default <default_region>\fR switch to define the default region, when no other region matches the current buffer range\&.
.sp
Most programming languages can then be properly highlighted using a regions highlighter as root:
.sp
.if n \{\
.RS 4
.\}
.nf
addhl regions \-default code <lang> \e
        string <str_opening> <str_closing> <str_recurse> \e
        comment <comment_opening> <comment_closing> <comment_recurse>

addhl \-group <lang>/code \&.\&.\&.
addhl \-group <lang>/string \&.\&.\&.
addhl \-group <lang>/comment \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.SH "SHARED HIGHLIGHTERS"
.sp
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\&.
.sp
A shared highlighter can be defined with the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
addhl \-group /<group_name> \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
When the group switch values starts with a \fI/\fR, it references a group in the shared highlighters, rather than the window highlighters\&.
.sp
The common case would be to create a named shared group, and then fill it with highlighters:
.sp
.if n \{\
.RS 4
.\}
.nf
addhl \-group / group <name>
addhl \-group /name regex \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
It can then be referenced in a window using the ref highlighter\&.
.sp
.if n \{\
.RS 4
.\}
.nf
addhl ref <name>
.fi
.if n \{\
.RE
.\}
.sp
The ref can reference any named highlighter in the shared namespace\&.