From 412c21bf70bbc0d2cdf31a2bf13eac8705d75490 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Wed, 1 Nov 2017 19:00:44 +0800 Subject: [PATCH] Update highlighters documentation Remove documentation from the README and point to the highlighters doc. --- README.asciidoc | 163 +---------------------------- doc/manpages/highlighters.asciidoc | 89 ++++++++-------- 2 files changed, 42 insertions(+), 210 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 944aae29..2b8530b7 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -1251,168 +1251,7 @@ and entering back insert mode (with which binding ?) Highlighters ~~~~~~~~~~~~ -Manipulation of the displayed text is done through highlighters, which can be added -or removed with the command - ---------------------------------------------------------------- -:add-highlighter ---------------------------------------------------------------- - -and - ------------------------------------- -:remove-highlighter ------------------------------------- - -`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 :...`: 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 `: add a column in front of the buffer, - and display the flags specified in , using - * `show_matching`: highlight matching char of the character under the selections' - cursor using `MatchingChar` face. - * `show_whitespaces \<-tab \<-tabpad \<-lf \<-spc \<-nbsp `: display symbols on top of whitespaces to make them more explicit using the Whitespace face. - * `number_lines \<-relative> \<-hlcursor> \<-separator `: 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 `: Soft wrap buffer content to the smallest of window width and - max_width. Wrap at word boundaries if `-word` is specified. - * `fill `: fill using given face, mostly useful with <> - * `ranges `: 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 `: 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 `: highlight column 'number' with the given face - * `line `: 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 ----------------------------- - -and then the `-group` switch of `add-highlighter` provides a mean to add highlighters -inside this group. - ------------------------------------------------- -add-highlighter -group ... ------------------------------------------------- - -Groups can contain other groups, the `-group` switch can be used to define a path. - ----------------------------------------------------------- -add-highlighter -group group -add-highlighter -group / ... ----------------------------------------------------------- - -[[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` 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 \ - ... ---------------------------------------------------------------------------------- - -The above command defines multiple regions in which other highlighters can be added as follows: - ------------------------------------------------ -add-highlighter -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. - -`regions` 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 `regions` -highlighter as root: - ------------------------------------------------------------------ -add-highlighter regions -default code \ - string \ - comment - -add-highlighter -group /code ... -add-highlighter -group /string ... -add-highlighter -group /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 / ... ----------------------------------------- - -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 -add-highlighter -group /name regex ... --------------------------------------- - -It can then be referenced in a window using the `ref` highlighter. - --------------------------- -add-highlighter ref --------------------------- - -The `ref` can reference any named highlighter in the shared namespace. +See `:doc highlighters` Hooks ~~~~~ diff --git a/doc/manpages/highlighters.asciidoc b/doc/manpages/highlighters.asciidoc index 13a04c02..e4b56a6b 100644 --- a/doc/manpages/highlighters.asciidoc +++ b/doc/manpages/highlighters.asciidoc @@ -11,15 +11,19 @@ Description Manipulation of the displayed text is done through highlighters, which can be added or removed with the following commands: ---------------------------------------------------------------- -add-highlighter ... ---------------------------------------------------------------- +---------------------------------------------------------------------- +add-highlighter ... +---------------------------------------------------------------------- and ------------------------------------ -remove-highlighter ------------------------------------ +------------------------------------------ +remove-highlighter / +------------------------------------------ + +*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 @@ -32,9 +36,9 @@ General highlighters 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 ----------------------------------------------------------------- +------------------------------------------------------------------- +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 @@ -116,34 +120,25 @@ Highlighting Groups ------------------- 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 ----------------------------- +----------------------------------- +add-highlighter group +----------------------------------- -The *-group* switch of the *add-highlighter* command provides a mean to add highlighters -inside this group: +That group is then accessible using the */* path ------------------------------------------------ -add-highlighter -group ... +add-highlighter / ... ------------------------------------------------ -Groups can contain other groups, the *-group* switch can be used to define -a path as follows: - ----------------------------------------------------------- -add-highlighter -group group -add-highlighter -group / ... ----------------------------------------------------------- - 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 group -passes colorize|move|wrap -------------------------------------------------------- +-------------------------------------------------------------- +add-highlighter window group -passes colorize|move|wrap +-------------------------------------------------------------- Regions highlighters -------------------- @@ -185,15 +180,16 @@ of regions. The following command: ------------------------------------------------------------------------------- -add-highlighter regions - ... ------------------------------------------------------------------------------- +------------------------------------------------------ +add-highlighter regions \ + \ + ... +------------------------------------------------------ defines multiple regions in which other highlighters can be added as follows: ----------------------------------------------- -add-highlighter -group / ... +add-highlighter // ... ----------------------------------------------- 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: ----------------------------------------------------------------- -add-highlighter regions -default code \ +add-highlighter regions -default code \ string \ comment -add-highlighter -group /code ... -add-highlighter -group /string ... -add-highlighter -group /comment ... +add-highlighter //code ... +add-highlighter //string ... +add-highlighter //comment ... ----------------------------------------------------------------- Shared Highlighters @@ -228,22 +224,19 @@ 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: +Highlighters can be put in the shared scope in order to make them reusable. ----------------------------------------- -add-highlighter -group / ... ----------------------------------------- - -When the group switch values starts with a '/', it references a group in -the shared highlighters, rather than the window highlighters. +--------------------------------------- +add-highlighter shared/ ... +--------------------------------------- The common case would be to create a named shared group, and then fill it with highlighters: --------------------------------------- -add-highlighter -group / group -add-highlighter -group /name regex ... --------------------------------------- +--------------------------------------- +add-highlighter shared/ group +add-highlighter shared/ regex ... +--------------------------------------- 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 -------------------------- -The ref can reference any named highlighter in the shared namespace. +The ref can reference any named highlighter in the shared scope.