Git commit 858b18d7a8d49348e4d4e24531f36e4f93cc6834 by Christoph Cullmann, on behalf of Nibaldo González. Committed on 09/03/2021 at 17:20. Pushed by cullmann into branch 'master'.
Update syntax highlighting documentation M +66 -11 doc/katepart/development.docbook https://invent.kde.org/utilities/kate/commit/858b18d7a8d49348e4d4e24531f36e4f93cc6834 diff --git a/doc/katepart/development.docbook b/doc/katepart/development.docbook index 31dfb9c3c..34ced7fa6 100644 --- a/doc/katepart/development.docbook +++ b/doc/katepart/development.docbook @@ -235,11 +235,11 @@ GenericDataLocation</option></userinput> which usually are and <filename class="directory">/usr/share/</filename>. </para> -<para>For Flatpak and Snap packages, the data location is different -for each application. In a Flatpak application, usually is -<filename class="directory"><envar>$HOME</envar>/.var/app/<replaceable>package-name</replaceable>/data/</filename> +<para>In Flatpak and Snap packages, the above directory will not work as the data location +is different for each application. In a Flatpak application, usually is +<filename class="directory"><envar>$HOME</envar>/.var/app/<replaceable>flatpak-package-name</replaceable>/data/</filename> and in a Snap application is -<filename class="directory"><envar>$HOME</envar>/snap/<replaceable>package-name</replaceable>/current/.local/share/</filename>. +<filename class="directory"><envar>$HOME</envar>/snap/<replaceable>snap-package-name</replaceable>/current/.local/share/</filename>. For example, for <ulink url="https://flathub.org/apps/details/org.kde.kate";>&kate;'s Flatpak package</ulink>, the custom &XML; files are located in <filename class="directory"><envar>$HOME</envar>/.var/app/org.kde.kate/data/org.kde.syntax-highlighting/syntax/</filename> @@ -250,6 +250,36 @@ it is <filename class="directory"><envar>$HOME</envar>/snap/kate/current/.local/ <para>On &Windows; these files are located <filename>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename>. <replaceable>%USERPROFILE%</replaceable> usually expands to <filename>C:\Users\<replaceable>user</replaceable></filename>.</para> +<para>In summary, for most configurations the directory of custom &XML; +files is as follows:</para> + +<informaltable> +<tgroup cols="2"> +<tbody> +<row> +<entry>For local user</entry> +<entry><filename class="directory"><envar>$HOME</envar>/.local/share/org.kde.syntax-highlighting/syntax/</filename></entry> +</row> +<row> +<entry>For all users</entry> +<entry><filename class="directory">/usr/share/org.kde.syntax-highlighting/syntax/</filename></entry> +</row> +<row> +<entry>For Flatpak packages</entry> +<entry><filename class="directory"><envar>$HOME</envar>/.var/app/<replaceable>flatpak-package-name</replaceable>/data/org.kde.syntax-highlighting/syntax/</filename></entry> +</row> +<row> +<entry>For Snap packages</entry> +<entry><filename class="directory"><envar>$HOME</envar>/snap/<replaceable>snap-package-name</replaceable>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename></entry> +</row> +<row> +<entry>On &Windows;</entry> +<entry><filename>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename></entry> +</row> +</tbody> +</tgroup> +</informaltable> + <para>If multiple files exist for the same language, the file with the highest <userinput>version</userinput> attribute in the <userinput>language</userinput> element will be loaded.</para> <variablelist> @@ -412,20 +442,34 @@ line. Available attributes are:</term> <listitem> <para><userinput>name</userinput> states the context name. Rules will use this name to specify the context to switch to if the rule matches.</para> + <para><userinput>lineEndContext</userinput> defines the context the highlight system switches to if it reaches the end of a line. This may either be a name of another context, <userinput>#stay</userinput> to not switch the context (⪚. do nothing) or <userinput>#pop</userinput> which will cause it to leave this context. It is possible to use for example <userinput>#pop#pop#pop</userinput> to pop three times, or even <userinput>#pop#pop!OtherContext</userinput> to pop -two times and switch to the context named <userinput>OtherContext</userinput>.</para> +two times and switch to the context named <userinput>OtherContext</userinput>. +It is also possible to switch to a context that belongs to another language definition, +in the same way as in the <userinput>IncludeRules</userinput> rules, e.g. +<userinput>SomeContext##JavaScript</userinput>. Note that it is not possible to use +this context switch in combination with <userinput>#pop</userinput>, for example, +<userinput>#pop!SomeContext##JavaScript</userinput> is not valid. +Context switches are also described in <xref linkend="kate-highlight-rules-detailled"/>.</para> <para><userinput>lineEmptyContext</userinput> defines the context if an empty -line is encountered. Default: #stay.</para> +line is encountered. The nomenclature of context switches is the same as +previously described in <emphasis>lineEndContext</emphasis>. Default: #stay.</para> +<para><userinput>fallthroughContext</userinput> specifies the next context to +switch to if no rule matches. The nomenclature of context switches is +the same as previously described in <emphasis>lineEndContext</emphasis>. +Default: #stay.</para> <para><userinput>fallthrough</userinput> defines if the highlight system switches -to the context specified in fallthroughContext if no rule matches. -Default: <emphasis>false</emphasis>.</para> -<para><userinput>fallthroughContext</userinput> specifies the next context -if no rule matches.</para> +to the context specified in <userinput>fallthroughContext</userinput> if no rule +matches. Note that since &kde; &frameworks; 5.62 this attribute is deprecated +in favor of only <userinput>fallthroughContext</userinput>, since if the +<userinput>fallthroughContext</userinput> attribute is present it is implicitly +understood that the value of <userinput>fallthrough</userinput> is +<emphasis>true</emphasis>. Default: <emphasis>false</emphasis>.</para> <para><userinput>noIndentationBasedFolding</userinput> disables indentation-based folding in the context. If indentation-based folding is not activated, this attribute is useless. This is defined in the element <emphasis>folding</emphasis> of the group <emphasis>general</emphasis>. @@ -680,6 +724,17 @@ previous context used in the string (<userinput>#pop</userinput>).</para> will make the engine first follow the order and then switch to the other context, ⪚ <userinput>#pop#pop!OtherContext</userinput>.</para> </listitem> +<listitem> +<para>An <emphasis>identifier</emphasis>, which is a context name, +followed by two hashes (<userinput>##</userinput>) and another +<emphasis>identifier</emphasis>, which is the name of a language definition. +This naming is similar to that used in <userinput>IncludeRules</userinput> +rules and allows you to switch to a context belonging to another syntax +highlighting definition, e.g. <userinput>SomeContext##JavaScript</userinput>. +Note that it is not possible to use this context switch in combination with +<userinput>#pop</userinput>, for example, +<userinput>#pop!SomeContext##JavaScript</userinput> is not valid.</para> +</listitem> </itemizedlist> <para>Rule specific attributes varies and are described in the @@ -741,7 +796,7 @@ expression. Whenever a rule allows this attribute it will contain a </listitem> </itemizedlist> -<para>How does it work:</para> +<para><userinput>How does it work:</userinput></para> <para>In the <link linkend="regular-expressions">regular expressions</link> of the <userinput>RegExpr</userinput> rules, all text within simple curved brackets
