runtime(doc): Improve the doc for :syn-containedin

closes: #18290

Co-authored-by: h_east <h.east.727@gmail.com>
Signed-off-by: Damien Lejay <damien@lejay.be>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index e6e4314b815f85db74d65b500c98b25efb02f44a..a6fbaef0911d7ea26a9f055c51b247c0a5aad655 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: 2025 Sep 14
+*syntax.txt*   For Vim version 9.1.  Last change: 2025 Sep 15
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -4866,6 +4866,12 @@ The "containedin" argument is followed by a list of syntax group names.  The
 item will be allowed to begin inside these groups.  This works as if the
 containing item has a "contains=" argument that includes this item.
 
+Only the immediate containing item (the one at the top of the syntax stack) is
+considered.  Vim does not search other ancestors.  If the immediate container
+neither contains this item via |:syn-contains| nor is named in this item's
+"containedin=", the match will not start even if some ancestor would allow it.
+Note that a |:syn-transparent| region still enforces its own |:syn-contains| list.
+
 The {group-name}... can be used just like for "contains", as explained above.
 
 This is useful when adding a syntax item afterwards.  An item can be told to
@@ -4880,6 +4886,7 @@ Matches for "containedin" are added to the other places where the item can
 appear.  A "contains" argument may also be added as usual.  Don't forget that
 keywords never contain another item, thus adding them to "containedin" won't
 work.
+See also: |:syn-contains|, |:syn-transparent|.
 
 
 nextgroup={group-name},..                              *:syn-nextgroup*