[utilities/kate] doc/katepart: document the multiple context feature of Syntax Highlighting

[Waqar Ahmed]

Git commit 27a78b098f501c9b8426901b982435c9cd59a59f by Waqar Ahmed, on behalf of Jonathan Poelen.
Committed on 25/04/2026 at 06:37.
Pushed by waqar into branch 'master'.

document the multiple context feature of Syntax Highlighting

The new syntax `context="name1!name2##SH!name3"` allows
multiple contexts to be stacked.

This syntax avoids the multiplication of contexts when
a common syntax precedes a particular syntax.

For example, strings (single or double quote) in () or []
require the definition of four string contexts:

    single quote + ]
    double quote + ]
    single quote + )
    double quote + )

Which is represented by the following graph:

    "[" -> SqStr_1 -> "]"
        \> DqStr_1 /
    "(" -> SqStr_2 -> ")"
        \> DqStr_2 /

By stacking the closure before SqStr or DqStr, it is
possible to reduce the number of contexts by jumping
over the closure via a #pop.

    "[" -> SqStr -> "]"
        \> DqStr /
    "(" -> SqStr -> ")"
        \> DqStr /

M  +4    -0    doc/katepart/development.docbook

https://invent.kde.org/utilities/kate/-/commit/27a78b098f501c9b8426901b982435c9cd59a59f

diff --git a/doc/katepart/development.docbook b/doc/katepart/development.docbook
index 30feddf5f2..6460475c23 100644
--- a/doc/katepart/development.docbook
+++ b/doc/katepart/development.docbook
@@ -727,6 +727,10 @@ An empty or absent context is equivalent to <userinput>#stay</userinput>.</para>
 (<emphasis>!</emphasis>) and an <emphasis>identifier</emphasis>, which
 will make the engine first follow the order and then switch to the
 other context, ⪚ <userinput>#pop#pop!OtherContext</userinput>.</para>
+<para>You can stack multiple contexts by repeating mark
+(<emphasis>!</emphasis>) and an <emphasis>identifier</emphasis>`, e.g.
+<userinput>ContextA!ContextB!ContextC</userinput>. The last context in
+the list is active immediately; the others will be accessed using `#pop`.</para>
 </listitem>
 <listitem>
 <para>An <emphasis>identifier</emphasis>, which is a context name,