commit f1f5fb911b575372fef49a13d86079b5902ada76
parent 9b8a0755390b7eb3ad369f3a0a42eb9aecb8cbe2
Author: zeertzjq <zeertzjq@outlook.com>
Date: Sat, 27 Apr 2024 05:50:46 +0800
vim-patch:fe1e2b5e2d65
runtime(doc): clarify syntax vs matching mechanism
fixes: vim/vim#14643
https://github.com/vim/vim/commit/fe1e2b5e2d65f05d820f17db935b15454a63be06
Co-authored-by: Christian Brabandt <cb@256bit.org>
Diffstat:
6 files changed, 32 insertions(+), 3 deletions(-)
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
@@ -8208,6 +8208,10 @@ synconcealed({lnum}, {col}) *synconcealed()*
synconcealed(lnum, 5) [1, 'X', 2]
synconcealed(lnum, 6) [0, '', 0]
+ Note: Doesn't consider |matchadd()| highlighting items,
+ since syntax and matching highlighting are two different
+ mechanisms |syntax-vs-match|.
+
synstack({lnum}, {col}) *synstack()*
Return a |List|, which is the stack of syntax items at the
position {lnum} and {col} in the current window. {lnum} is
diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt
@@ -1375,6 +1375,19 @@ Finally, these constructs are unique to Perl:
==============================================================================
10. Highlighting matches *match-highlight*
+ *syntax-vs-match*
+ Note that the match highlight mechanism is independent
+ of |syntax-highlighting|, which is (usually) a buffer-local
+ highlighting, while matching is window-local, both methods
+ can be freely mixed. Match highlighting functions give you
+ a bit more flexibility in when and how to apply, but are
+ typically only used for temporary highlighting, without strict
+ rules. Both methods can be used to conceal text.
+
+ Thus the matching functions like |matchadd()| won't consider
+ syntax rules and functions like |synconcealend()| and the
+ other way around.
+
*:mat* *:match*
:mat[ch] {group} /{pattern}/
Define a pattern to highlight in the current window. It will
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
@@ -3825,7 +3825,9 @@ Whether or not it is actually concealed depends on the value of the
'conceallevel' option. The 'concealcursor' option is used to decide whether
concealable items in the current line are displayed unconcealed to be able to
edit the line.
-Another way to conceal text is with |matchadd()|.
+
+Another way to conceal text is with |matchadd()|, but internally this works a
+bit differently |syntax-vs-match|.
concealends *:syn-concealends*
@@ -3833,7 +3835,9 @@ When the "concealends" argument is given, the start and end matches of
the region, but not the contents of the region, are marked as concealable.
Whether or not they are actually concealed depends on the setting on the
'conceallevel' option. The ends of a region can only be concealed separately
-in this way when they have their own highlighting via "matchgroup"
+in this way when they have their own highlighting via "matchgroup". The
+|synconcealed()| function can be used to retrieve information about conealed
+items.
cchar *:syn-cchar*
*E844*
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
@@ -948,7 +948,7 @@ Syntax and highlighting: *syntax-functions* *highlighting-functions*
synIDattr() get a specific attribute of a syntax ID
synIDtrans() get translated syntax ID
synstack() get list of syntax IDs at a specific position
- synconcealed() get info about concealing
+ synconcealed() get info about (synax) concealing
diff_hlID() get highlight ID for diff mode at a position
matchadd() define a pattern to highlight (a "match")
matchaddpos() define a list of positions to highlight
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
@@ -9752,6 +9752,10 @@ function vim.fn.synIDtrans(synID) end
--- synconcealed(lnum, 5) [1, 'X', 2]
--- synconcealed(lnum, 6) [0, '', 0]
---
+--- Note: Doesn't consider |matchadd()| highlighting items,
+--- since syntax and matching highlighting are two different
+--- mechanisms |syntax-vs-match|.
+---
--- @param lnum integer
--- @param col integer
--- @return {[1]: integer, [2]: string, [3]: integer}
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
@@ -11621,6 +11621,10 @@ M.funcs = {
synconcealed(lnum, 4) [1, 'X', 2]
synconcealed(lnum, 5) [1, 'X', 2]
synconcealed(lnum, 6) [0, '', 0]
+
+ Note: Doesn't consider |matchadd()| highlighting items,
+ since syntax and matching highlighting are two different
+ mechanisms |syntax-vs-match|.
]=],
name = 'synconcealed',
params = { { 'lnum', 'integer' }, { 'col', 'integer' } },
