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

[Christian Brabandt]

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

Commit: https://github.com/vim/vim/commit/8e0d374e4d3f1be11e64010d69b6d9a5e913ec8d
Author: Damien Lejay <dam...@lejay.be>
Date: Mon Sep 15 18:05:18 2025 +0000

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

closes: https://github.com/vim/vim/issues/18290

Co-authored-by: h_east <h.eas...@gmail.com>
Signed-off-by: Damien Lejay <dam...@lejay.be>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index e6e4314b8..a6fbaef09 100644
--- 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*