runtime(doc): clarify syntax vs matching mechanism

fixes: #14643

Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index a426124a03fb2ae6d061446ae60be91c36dcfcdf..79f3cd7c6882c12e43ee36d6aa48c0855f81ff68 100644 (file)
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -9980,6 +9980,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

diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt
index 2d1898de52b8c6384c883ae4275d3698abf4212d..c23462c81852537bb64bdc5c3664edc690891677 100644 (file)
--- a/runtime/doc/pattern.txt
+++ b/runtime/doc/pattern.txt
@@ -1,4 +1,4 @@
-*pattern.txt*   For Vim version 9.1.  Last change: 2023 Oct 23
+*pattern.txt*   For Vim version 9.1.  Last change: 2024 Apr 26
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -1394,6 +1394,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
index 7269e7d207bea51c19e30c05e9e8b0b71384feed..873315c823c937d722c30edd4f86e92182ac9ecc 100644 (file)
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -1,4 +1,4 @@
-*syntax.txt*   For Vim version 9.1.  Last change: 2024 Apr 22
+*syntax.txt*   For Vim version 9.1.  Last change: 2024 Apr 26
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -4314,7 +4314,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*
 
@@ -4322,7 +4324,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/tags b/runtime/doc/tags
index 6ad90225918a90f3d721287e875a7ebc9cd28712..dcd8db7e2af1dd3736220c92b51c4b5de4edea92 100644 (file)
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -10186,6 +10186,7 @@ syntax-latex    syntax.txt      /*syntax-latex*
 syntax-loading syntax.txt      /*syntax-loading*
 syntax-printing        usr_06.txt      /*syntax-printing*
 syntax-tex     syntax.txt      /*syntax-tex*
+syntax-vs-match        pattern.txt     /*syntax-vs-match*
 syntax.txt     syntax.txt      /*syntax.txt*
 syntax_cmd     syntax.txt      /*syntax_cmd*
 sys-file-list  help.txt        /*sys-file-list*

diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 04a9afb1b14eba662aab67203ee479779c78ce5d..8e719481a455ace03594e0a186e692585b96ab69 100644 (file)
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1,4 +1,4 @@
-*usr_41.txt*   For Vim version 9.1.  Last change: 2024 Feb 25
+*usr_41.txt*   For Vim version 9.1.  Last change: 2024 Apr 26
 
                     VIM USER MANUAL - by Bram Moolenaar
 
@@ -1096,7 +1096,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