Git commit df5ee4f402041decbf302e4cc2321b5eefc64428 by Christoph Cullmann, on behalf of Jonathan Poelen. Committed on 17/09/2023 at 13:41. Pushed by cullmann into branch 'master'.
Update syntax highlighting documentation M +39 -22 doc/katepart/development.docbook A +- -- doc/katepart/ksyntaxhighlighter6-trace-format.png https://invent.kde.org/utilities/kate/-/commit/df5ee4f402041decbf302e4cc2321b5eefc64428 diff --git a/doc/katepart/development.docbook b/doc/katepart/development.docbook index 32cdff9189..2b51231630 100644 --- a/doc/katepart/development.docbook +++ b/doc/katepart/development.docbook @@ -439,6 +439,11 @@ line. Available attributes are:</term> <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>attribute</userinput> identifies the style to use for a +character when no rule matches or when a rule does not specify attribute. +In the latter case, <emphasis>attribute</emphasis> of the context specified +in the rule's <emphasis>context</emphasis> will be used.</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 @@ -448,10 +453,9 @@ to pop three times, or even <userinput>#pop#pop!OtherContext</userinput> to pop 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, ⪚, -<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> +<userinput>SomeContext##JavaScript</userinput>. +Context switches are also described in <xref linkend="kate-highlight-rules-detailled"/>. +Default: #stay.</para> <para><userinput>lineEmptyContext</userinput> defines the context if an empty line is encountered. The nomenclature of context switches is the same as previously described in <emphasis>lineEndContext</emphasis>. Default: #stay.</para> @@ -710,7 +714,8 @@ context.</para> <listitem> <para>An <emphasis>order</emphasis> telling the engine to stay in the current context (<userinput>#stay</userinput>), or to pop back to a -previous context used in the string (<userinput>#pop</userinput>).</para> +previous context used in the string (<userinput>#pop</userinput>). +An empty or absent context is equivalent to <userinput>#stay</userinput>.</para> <para>To go back more steps, the #pop keyword can be repeated: <userinput>#pop#pop#pop</userinput></para> </listitem> @@ -727,9 +732,7 @@ followed by two hashes (<userinput>##</userinput>) and another 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> +</para> </listitem> </itemizedlist> @@ -740,15 +743,14 @@ following sections.</para> <title>Common attributes</title> <para>All rules have the following attributes in common and are available whenever <userinput>(common attributes)</userinput> appears. -<emphasis>attribute</emphasis> and <emphasis>context</emphasis> -are required attributes, all others are optional. +All attributes are optional. </para> <listitem> -<para><emphasis>attribute</emphasis>: An attribute maps to a defined <emphasis>itemData</emphasis>.</para> +<para><emphasis>attribute</emphasis>: An attribute maps to a defined <emphasis>itemData</emphasis>. Default: <emphasis>attribute</emphasis> from the context specified in <emphasis>context</emphasis> attribute.</para> </listitem> <listitem> -<para><emphasis>context</emphasis>: Specify the context to which the highlighting system switches if the rule matches.</para> +<para><emphasis>context</emphasis>: Specify the context to which the highlighting system switches if the rule matches. Default: #stay.</para> </listitem> <listitem> <para><emphasis>beginRegion</emphasis>: Start a code folding block. Default: unset.</para> @@ -922,6 +924,8 @@ to match.</para> <programlisting><Detect2Chars char="(character)" char1="(character)" (common attributes) /></programlisting> <para>The <userinput>char</userinput> attribute defines the first character to match, <userinput>char1</userinput> the second.</para> +<para>This rule is present for historical reasons and for readability it's +preferable to use <userinput>StringDetect</userinput>.</para> </listitem> </varlistentry> @@ -1177,11 +1181,6 @@ they are slow compared to the other rules. So you may consider the following tips. </para> -<listitem> -<para>If you only match two characters use <userinput>Detect2Chars</userinput> -instead of <userinput>StringDetect</userinput>. The same applies to -<userinput>DetectChar</userinput>.</para> -</listitem> <listitem> <para>Regular expressions are easy to use but often there is another much faster way to achieve the same result. Consider you only want to match @@ -1211,7 +1210,7 @@ want to switch context when you meet the string <userinput>*/</userinput>, but need to process that string in the next context. The below rule will match, and the <userinput>lookAhead</userinput> attribute will cause the highlighter to keep the matched string for the next context. -<programlisting><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting> +<programlisting><StringDetect attribute="Comment" context="#pop" String="*/" lookAhead="true" /></programlisting> </para> </listitem> <listitem> @@ -1228,9 +1227,8 @@ keep the matched string for the next context. </listitem> <listitem> <para>You can validate every &XML; file by using the command -<command>validatehl.sh language.xsd mySyntax.xml</command>. -The files <filename>validatehl.sh</filename> and <filename>language.xsd</filename> -are available in <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema";>Syntax +<command>validatehl.sh mySyntax.xml</command>. +The file <filename>validatehl.sh</filename> use <filename>language.xsd</filename> which are both available in <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema";>Syntax Highlighting repository</ulink>. </para> </listitem> @@ -1239,7 +1237,7 @@ Highlighting repository</ulink>. <emphasis>ENTITIES</emphasis>. Example:</para> <programlisting> <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE language SYSTEM "language.dtd" +<!DOCTYPE language [ <!ENTITY myref "[A-Za-z_:][\w.:_-]*"> ]> @@ -1247,6 +1245,25 @@ Highlighting repository</ulink>. <para>Now you can use <emphasis>&myref;</emphasis> instead of the regular expression.</para> </listitem> +<listitem> +<para>On Kate Editor, you can reload syntaxes using the built-in command line +(<userinput>F7</userinput> shortcut by default) and the <command>reload-highlighting</command> +command.</para> +</listitem> +<listitem> +<para>You can use the command-line utility named <userinput>ksyntaxhighlighter6</userinput> +(<userinput>kate-syntax-highlighter</userinput> on older versions) to test a +syntax and display the style and regions associated with each part of a text.</para> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="ksyntaxhighlighter6-trace-format.png"/></imageobject> +<textobject><phrase>Result of <command>ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp</command>.</phrase></textobject> +<caption><para>Result of <command>ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp</command>.</para> +</caption> +</mediaobject> + +<para>Use <command>ksyntaxhighlighter6 -h</command> for more options.</para> +</listitem> </itemizedlist> </sect3> diff --git a/doc/katepart/ksyntaxhighlighter6-trace-format.png b/doc/katepart/ksyntaxhighlighter6-trace-format.png new file mode 100644 index 0000000000..db23207da9 Binary files /dev/null and b/doc/katepart/ksyntaxhighlighter6-trace-format.png differ
