From 173c0b14ab9ad1f54e74a2573d8212a720df1762 Mon Sep 17 00:00:00 2001 From: Oliver Kiddle Date: Thu, 15 Feb 2024 14:50:56 +0100 Subject: [PATCH] 52535: documentation for highlight groups and layers --- ChangeLog | 3 +++ Doc/Makefile.in | 3 ++- Doc/Zsh/mod_hlgroup.yo | 25 +++++++++++++++++++++++++ Doc/Zsh/prompt.yo | 8 ++++++++ Doc/Zsh/zle.yo | 11 +++++++++++ NEWS | 6 ++++++ 6 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 Doc/Zsh/mod_hlgroup.yo diff --git a/ChangeLog b/ChangeLog index 6d064eaf6..3cbf7d699 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,8 @@ 2024-02-15 Oliver Kiddle + * 52535: Doc/Makefile.in, Doc/Zsh/prompt.yo, Doc/Zsh/zle.yo, + Doc/Zsh/mod_hlgroup.yo, NEWS: documentation for highlight groups + * 52533: Src/Modules/hlgroup.c, Src/Modules/hlgroup.mdd, Src/prompt.c: add module to provide alternate readonly views of the content of .zle.hlgroups diff --git a/Doc/Makefile.in b/Doc/Makefile.in index dabe11fe3..d9be182e9 100644 --- a/Doc/Makefile.in +++ b/Doc/Makefile.in @@ -63,7 +63,8 @@ Zsh/mod_attr.yo Zsh/mod_cap.yo Zsh/mod_clone.yo \ Zsh/mod_compctl.yo Zsh/mod_complete.yo Zsh/mod_complist.yo \ Zsh/mod_computil.yo Zsh/mod_curses.yo \ Zsh/mod_datetime.yo Zsh/mod_db_gdbm.yo Zsh/mod_deltochar.yo \ -Zsh/mod_example.yo Zsh/mod_files.yo Zsh/mod_langinfo.yo \ +Zsh/mod_example.yo Zsh/mod_files.yo \ +Zsh/mod_hlgroup.yo Zsh/mod_langinfo.yo \ Zsh/mod_ksh93.yo Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo \ Zsh/mod_nearcolor.yo Zsh/mod_newuser.yo \ Zsh/mod_parameter.yo Zsh/mod_pcre.yo Zsh/mod_private.yo \ diff --git a/Doc/Zsh/mod_hlgroup.yo b/Doc/Zsh/mod_hlgroup.yo new file mode 100644 index 000000000..efe8934a1 --- /dev/null +++ b/Doc/Zsh/mod_hlgroup.yo @@ -0,0 +1,25 @@ +COMMENT(!MOD!zsh/hlgroup +Alternative views of highlighting groups +!MOD!) +The tt(zsh/hlgroup) module defines special parameters that represent +highlighting groups in different forms to ease the use of the groups when +configuring other tools. + +In each case, these are readonly associative arrays where accessing elements +uses values from the underlying tt(.zle.hlgroups) variable. + +startitem() +vindex(.zle.esc) +item(tt(.zle.esc))( +This associative array contains the literal escape sequences used to apply the +highlighting for each group. An example use would be when setting the +tt(LESS_TERMCAP_xx) environment variables for the tt(less) pager. +) +vindex(.zle.sgr) +item(tt(.zle.sgr))( +Where highlighting makes use of CSI escape sequences, this parameter contains +the "Select Graphic Rendition" number sequence. This is useful with, for +example the tt(GREP_COLORS) and tt(LSCOLORS) environment variables and the +tt(list-colors) style. +) +enditem() diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo index 909012c8e..de988ab7c 100644 --- a/Doc/Zsh/prompt.yo +++ b/Doc/Zsh/prompt.yo @@ -246,6 +246,14 @@ item(tt(%K) LPAR()tt(%k)RPAR())( Start (stop) using a different bacKground colour. The syntax is identical to that for tt(%F) and tt(%f). ) +item(tt(%H))( +Change all character visual attributes using a highlighting specification from +the tt(.zle.hlgroups) associative array. The key is specified in following +braces so, for example tt(%H{error}) will use the highlighting specification +for the `error' group. If the key is not found in the associative array then +it has no effect. Highlighting specifications are in the same format as for +the tt(zle_highlight) parameter. +) item(tt(%{)...tt(%}))( Include a string as a literal escape sequence. The string within the braces should not change the cursor diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index 495bd86a8..31eb3f3ba 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -2807,6 +2807,17 @@ item(tt(italic))( The characters in the given context are shown in a italic font. Not all terminals support italic fonts. ) +item(tt(hl=)var(group))( +Use the specified highlighting group. The var(group) is used as a key into +the associative array tt(.zle.hlgroups) to determine the actual highlighting. +) +item(tt(layer=)var(layer))( +The layer is used to determine precedence when multiple highlighting regions +overlap. The var(layer) is a decimal integer, with higher numbers taking +precedence over lower numbers. The default layer is 10 with 30 used as the +default for tt(special), 20 for tt(region) and tt(isearch) and 15 for +tt(paste). +) enditem() The characters described above as `special' are as follows. The diff --git a/NEWS b/NEWS index 4d4699f7e..d0a8584e2 100644 --- a/NEWS +++ b/NEWS @@ -10,6 +10,12 @@ Changes since 5.9 In region_highlight and zle_highlight, italic and faint can be specified as font attributes for terminals that support them. +Highlighting groups can be referenced in region_highlight and +zle_highlight for common attribute combinations and a layer can be +specified to indicate precedence where highlighted regions overlap. +Highlighting groups are also supported in the prompt via a new %H +prompt escape. + Ellipsis markers shown by the line editor to indicate where the line doesn't fit in the terminal can be highlighted.