[kate] doc/katepart: Highlight documentation: add include keywords

[Nibaldo González]

Git commit 6c2f6d88e8d33b26a487cffa5c77800c60b2dd3d by Nibaldo González.
Committed on 09/08/2019 at 18:29.
Pushed by ngonzalez into branch 'master'.

Highlight documentation: add include keywords

Summary: The documentation of the syntax highlighting is updated, adding a 
brief description and example of include-keywords.

Reviewers: #kate, dhaumann, cullmann

Reviewed By: #kate, cullmann

Subscribers: kwrite-devel, kde-doc-english

Tags: #kate, #documentation

Differential Revision: https://phabricator.kde.org/D23050

M  +16   -2    doc/katepart/development.docbook

https://commits.kde.org/kate/6c2f6d88e8d33b26a487cffa5c77800c60b2dd3d

diff --git a/doc/katepart/development.docbook b/doc/katepart/development.docbook
index 763116ec3..93e5046e9 100644
--- a/doc/katepart/development.docbook
+++ b/doc/katepart/development.docbook
@@ -286,6 +286,15 @@ elements <userinput>contexts</userinput> and 
<userinput>itemDatas</userinput>.</
 <para><userinput>list</userinput> elements contain a list of keywords. In
 this case the keywords are <emphasis>class</emphasis> and 
<emphasis>const</emphasis>.
 You can add as many lists as you need.</para>
+<para>Since &kde-frameworks; 5.53, a list can include keywords from another
+list or language/file, using the <userinput>include</userinput> element.
+<userinput>##</userinput> is used to separate the list name and the language
+definition name, in the same way as in the <userinput>IncludeRules</userinput> 
rule.
+This is useful to avoid duplicating keyword lists, if you need to include the 
keywords
+of another language/file. For example, the <emphasis>othername</emphasis> list
+contains the <emphasis>str</emphasis> keyword and all the keywords of the
+<emphasis>types</emphasis> list, which belongs to the <emphasis>ISO 
C++</emphasis>
+language.</para>
 <para>The <userinput>contexts</userinput> element contains all contexts.
 The first context is by default the start of the highlighting. There are
 two rules in the context <emphasis>Normal Text</emphasis>, which match
@@ -300,12 +309,17 @@ In this example, the <userinput>itemData</userinput> 
<emphasis>Normal Text</emph
 <programlisting>
   &lt;highlighting&gt;
     &lt;list name=&quot;somename&quot;&gt;
-      &lt;item&gt; class &lt;/item&gt;
-      &lt;item&gt; const &lt;/item&gt;
+      &lt;item&gt;class&lt;/item&gt;
+      &lt;item&gt;const&lt;/item&gt;
+    &lt;/list&gt;
+    &lt;list name=&quot;othername&quot;&gt;
+      &lt;item&gt;str&lt;/item&gt;
+      &lt;include&gt;types##ISO C++&lt;/include&gt;
     &lt;/list&gt;
     &lt;contexts&gt;
       &lt;context attribute=&quot;Normal Text&quot; 
lineEndContext=&quot;#pop&quot; name=&quot;Normal Text&quot; &gt;
         &lt;keyword attribute=&quot;Keyword&quot; context=&quot;#stay&quot; 
String=&quot;somename&quot; /&gt;
+        &lt;keyword attribute=&quot;Keyword&quot; context=&quot;#stay&quot; 
String=&quot;othername&quot; /&gt;
         &lt;DetectChar attribute=&quot;String&quot; context=&quot;string&quot; 
char=&quot;&amp;quot;&quot; /&gt;
       &lt;/context&gt;
       &lt;context attribute=&quot;String&quot; 
lineEndContext=&quot;#stay&quot; name=&quot;string&quot; &gt;