diff --git a/doc/pages/highlighters.asciidoc b/doc/pages/highlighters.asciidoc index ab6e169a..34bab82e 100644 --- a/doc/pages/highlighters.asciidoc +++ b/doc/pages/highlighters.asciidoc @@ -5,24 +5,23 @@ 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 -completion in a prompt on the *remove-highlighter* command to see the -existing highlighters ids. +*name* is the name of the highlighter, if name is omitted in +`add-highlighter` (the path ends with a `/`), it will be auto-generated +from the remaining parameters. == Convenient highlighters @@ -96,18 +95,18 @@ existing highlighters ids. This highlights C++ style comments in cyan, with an eventual 'TODO:' in yellow on red background: -------------------------------------------------------------------- -add-highlighter window regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red -------------------------------------------------------------------- +-------------------------------------------------------------------- +add-highlighter window/ regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red +-------------------------------------------------------------------- *dynregex* : ...:: similar to regex, but expand (like a command parameter would) the given expression before building a regex from the result. This highlights all the current search matches in italic: ----------------------------------------------- -add-highlighter window dynregex '%reg{/}' 0:+i ----------------------------------------------- +----------------------------------------------- +add-highlighter window/ dynregex '%reg{/}' 0:+i +----------------------------------------------- == Specs highlighters @@ -158,21 +157,22 @@ The *group* highlighter is a container for other highlighters. A subgroup can be added to an existing group or scope using: ----------------------------------- -add-highlighter group +add-highlighter / group ----------------------------------- -That group is then accessible using the */* path +Other highlighters can then be added to that group ------------------------------------------------ add-highlighter / ... ------------------------------------------------ -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*): +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 +add-highlighter window/ group -passes colorize|move|wrap -------------------------------------------------------------- == Regions highlighters @@ -180,16 +180,35 @@ add-highlighter window group -passes colorize|move|wrap 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 +------------------------------------- +add-highlighter / regions +------------------------------------- + +Individual region definitions can then be added to that highlighter + +---------------------------------------------------- +add-highlighter // 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 +*type* and *params*:: + An highlighter type, and associated params, as they would be passed + to `add-highlighter` if they were not applied as a region. + +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. + The *recurse* option is useful for regions that can be nested, for example the following contruct: @@ -209,47 +228,30 @@ 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 regions \ - \ - ... ------------------------------------------------------- - -defines multiple regions in which other highlighters can be added as follows: - ------------------------------------------------ -add-highlighter // ... ------------------------------------------------ - 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. +A default region, that will apply its given highlighter for segments of the +buffer that are not in any defined region, can be added with the *default-region* +highlighter type. -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. +----------------------------------------------------------------------------- +add-highlighter // default-region ... +----------------------------------------------------------------------------- Most programming languages can then be properly highlighted using a region highlighter as root: ----------------------------------------------------------------- -add-highlighter regions -default code \ - string \ - comment - -add-highlighter //code ... -add-highlighter //string ... -add-highlighter //comment ... +add-highlighter / regions +add-highlighter //string '"' '"' '' fill string +add-highlighter //comment '//' '$' '' fill comment +add-highlighter //code default-region group +add-highlighter //code/variable regex ... +add-highlighter //code/function regex ... ----------------------------------------------------------------- == Shared Highlighters @@ -259,12 +261,12 @@ 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/ ... ---------------------------------------- +--------------------------------- +add-highlighter shared/ ... +--------------------------------- -The common case would be to create a named shared group, and then fill it -with highlighters: +The common case would be to create a named shared group, or regions and then +fill it with highlighters: --------------------------------------- add-highlighter shared/ group @@ -273,8 +275,8 @@ add-highlighter shared/ regex ... It can then be referenced in a window using the ref highlighter. ---------------------------------- -add-highlighter window ref ---------------------------------- +---------------------------------- +add-highlighter window/ ref +---------------------------------- The ref can reference any named highlighter in the shared scope.