[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>
   <highlighting>
     <list name="somename">
-      <item> class </item>
-      <item> const </item>
+      <item>class</item>
+      <item>const</item>
+    </list>
+    <list name="othername">
+      <item>str</item>
+      <include>types##ISO C++</include>
     </list>
     <contexts>
       <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
         <keyword attribute="Keyword" context="#stay" String="somename" />
+        <keyword attribute="Keyword" context="#stay" String="othername" />
         <DetectChar attribute="String" context="string" char="&quot;" />
       </context>
       <context attribute="String" lineEndContext="#stay" name="string" >