From abc2d28570f364786fdab77c66452ef236187602 Mon Sep 17 00:00:00 2001 From: Delapouite Date: Tue, 6 Mar 2018 11:34:00 +0100 Subject: [PATCH] Docs: extend explanations about line_flags, ranges and replace-ranges --- doc/pages/highlighters.asciidoc | 100 +++++++++++++++++++++----------- doc/pages/options.asciidoc | 4 +- src/commands.cc | 2 +- 3 files changed, 71 insertions(+), 35 deletions(-) diff --git a/doc/pages/highlighters.asciidoc b/doc/pages/highlighters.asciidoc index b8093238d..1491f980a 100644 --- a/doc/pages/highlighters.asciidoc +++ b/doc/pages/highlighters.asciidoc @@ -24,34 +24,15 @@ separated path starting with a scope. Scopes are *global*, *buffer*, completion in a prompt on the *remove-highlighter* command to see the existing highlighters ids. -== General highlighters - -*regex* : ...:: - highlight a regex, takes the regex as first parameter, followed by - any number of face parameters. For example: - -------------------------------------------------------------------- -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 - -*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 +== Convenient highlighters *show_matching*:: highlight matching char of the character under the selections' cursor - using MatchingChar face + using `MatchingChar` face *show_whitespaces* [options]:: display symbols on top of whitespaces to make them more explicit - using the Whitespace face, with the following *options*: + using the `Whitespace` face, with the following *options*: *-lf* ::: a one character long separator that will replace line feeds @@ -93,27 +74,80 @@ add-highlighter window regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red *-width *::: wrap text at *max_width* if the window is wider. +== General highlighters + *fill* :: fill using the given *face*, mostly useful with regions highlighters -*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 face *face* *line* :: highlight line *number* with face *face* -== Highlighting Groups +*regex* : ...:: + highlight a regex, takes the regex as first parameter, followed by + any number of face parameters. + 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 +------------------------------------------------------------------- + +*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 +--------------------------------------------- + +== Specs highlighters + +The following highlighters are useful to add indicators like lint warnings, +git blame output or spelling typos. +See <> for the format of `line-specs` +and `range-specs`. + +*flag_lines* :: + add columns in front of the buffer, and display the flags specified + in `line-specs` option, using . + In this example two words will be added in the gutter: a blue Foo at + line 1 and a bold red/yellow Bar on line 3: + +--------------------------------------------------------------- +declare-option line-specs my_flags +set-option window my_flags 1486635122:1|Foo:3|{red,yellow+b}Bar +add-highlighter window/ flag_lines blue my_flags +--------------------------------------------------------------- + +*ranges* :: + use the data in the `range-specs` option of the given name to highlight + the buffer. The string part of each tuple of the range-specs is + interpreted as a *face* to apply to the range. + In this example the 3 first chars of the buffer will be colored in red: + +------------------------------------------------- +declare-option range-specs my_range +set-option window my_range 1486635122:1.1,1.3|red +add-highlighter window/ ranges my_range +------------------------------------------------- + +*replace-ranges* :: + use the data in the `range-specs` option of the given name to highlight + the buffer. The string part of each tuple of the range-specs is + interpreted as a *display line* to display in place of the range. + Here, the 3 first chars of the buffer will be replaced by the word 'red': + +------------------------------------------------- +declare-option range-specs my_range +set-option window my_range 1486635122:1.1,1.3|red +add-highlighter window/ replace-ranges my_range +------------------------------------------------- + +== Highlighting Groups The *group* highlighter is a container for other highlighters. A subgroup can be added to an existing group or scope using: diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc index 384346297..3094105da 100644 --- a/doc/pages/options.asciidoc +++ b/doc/pages/options.asciidoc @@ -79,10 +79,11 @@ are exclusively available to built-in options. a `:` separated list of a pair of a buffer range (`.,.` or `.+`) and a string (separated by `|`), except for the - first element which is just the timestamp of the buffer. When the + first element which is just the timestamp of the buffer. When the `update-option` is used on an option of this type, its ranges gets updated according to all the buffer modifications that happened since its timestamp. + See <>) *line-specs*:: a `:` separated list of a line number and a corresponding flag @@ -90,6 +91,7 @@ are exclusively available to built-in options. the timestamp of the buffer. When the `update-option` is used on an option of this type, its lines gets updated according to all the buffer modifications that happened since its timestamp. + See <>) *completions*:: a `:` separated list of `||` diff --git a/src/commands.cc b/src/commands.cc index 493730087..8eb5acbbc 100644 --- a/src/commands.cc +++ b/src/commands.cc @@ -1346,7 +1346,7 @@ const CommandDesc update_option_cmd = { "update-option", nullptr, "update-option : update option from scope\n" - "some option types, such as line-descs or range-descs can be updated to latest buffer timestamp\n" + "some option types, such as line-specs or range-specs can be updated to latest buffer timestamp\n" " can be buffer, window, or current which refers to the narrowest " "scope the option is set in", ParameterDesc{ {}, ParameterDesc::Flags::None, 2, 2 },