From b963d0b11cbbf5017608878b4ec49fe9db4abe55 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Sat, 14 Jun 2014 12:46:26 +0100 Subject: [PATCH] update the readme for highlighters doc --- README.asciidoc | 137 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 118 insertions(+), 19 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 6fac63d57..f33fa2ac7 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -582,14 +582,8 @@ and :rmhl ---------------------- -existing highlighters are: +general highlighters are: - * +number_lines+: show line numbers - * +group +: highlighter group, containing other highlighters. - useful when multiple highlighters work together and need to be - removed as one. Adding and removing from a group can be done using - `:addhl -group ` - `:rmhl -group ` * +regex ...+: highlight a regex, takes the regex as first parameter, followed by any number of color parameters. color format is: :[,] @@ -603,6 +597,98 @@ existing highlighters are: . * +show_matching+: highlight matching char of the character under the selections cursor using +MatchingChar+ color alias. + * +number_lines+: show line numbers + * +fill +: fill with given color, mostly useful with region highlighters + (see below) + +Highlighting Groups +~~~~~~~~~~~~~~~~~~~ + +the +group+ highlighter is a container for other highlighters. You can add +a group to the current window using + +------------------ +addhl group +------------------ + +and then the +-group+ switch of +addhl+ provides a mean to add highlighters +inside this group. + +-------------------------------------- +addhl -group ... +-------------------------------------- + +groups can contain other groups, the +-group+ switch can be used to define a path. + +------------------------------------------------ +addhl -group group +addhl -group / ... +------------------------------------------------ + +Region highlighters +~~~~~~~~~~~~~~~~~~~ + +The +region+ highlighters takes 3 to 4 parameters: + +--------------------------------------------------- +addhl region [] +--------------------------------------------------- + ++name+ is user defined, but +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: + +------------------------------------- +addhl region shell_expand %sh\{ \} \{ +------------------------------------- + +It then provides a group named +content+ which can be filled with other highlighters +that will only be applied on the given regions. + +------------------------------------- +addhl -group shell_expand/content ... +------------------------------------- + +The +multi_region+ highlighter is even more powerfull, it can segment the buffer +in non overlapping regions. + +------------------------------------------------------------------------- +addhl multi_region \ + ... +------------------------------------------------------------------------- + +defines multiple regions in which other highlighters can be added + +------------------------------------- +addhl -group / ... +------------------------------------- + +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. + ++multi_region+ also supports a +-default + 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 +multi_region+ +highlighter as root: + +----------------------------------------------------------------- +addhl multi_region -default code \ + string \ + comment + +addhl -group /code ... +addhl -group /string ... +addhl -group /comment ... +----------------------------------------------------------------- Shared Highlighters ~~~~~~~~~~~~~~~~~~~ @@ -610,20 +696,30 @@ 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 +A shared highlighter can be defined with the +:addhl+ command ------------------------ -defhl ------------------------ +------------------------------ +addhl -group / ... +------------------------------ -Highlighters can be added to it using the regular +:addhl+ command, with the -+-def-group + option. +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: + +--------------------------- +addhl -group / group +addhl -group /name regex ... +--------------------------- It can then be referenced in a window using the +ref+ highlighter. --------------------------- -addhl ref --------------------------- +---------------- +addhl ref +---------------- + +the +ref+ can reference any named highlighter in the shared namespace. Hooks ----- @@ -844,14 +940,17 @@ FIFO Buffer the +:edit+ command can take a -fifo parameter: ------------------------------------ -:edit -fifo ------------------------------------ +--------------------------------------------- +:edit -fifo [-scroll] +--------------------------------------------- in this case, a buffer named ++ is created which reads its content from fifo ++. When the fifo is written to, the buffer is automatically updated. +if the +-scroll+ switch is specified, the initial cursor position will be made +such as the window displaying the buffer will scroll as new data is read. + This is very useful for running some commands asynchronously while displaying their result in a buffer. See rc/make.kak and rc/grep.kak for examples.