[kate] doc/katepart: Highlight documentation: add equivalence in regex for number rules and add lookbehind assertions

[Dominik Haumann]

Git commit 007a7aef99999b3504a2b77d733adaa1f7198923 by Dominik Haumann, on behalf of Nibaldo González.
Committed on 10/01/2020 at 20:09.
Pushed by scmsync into branch 'master'.

Highlight documentation: add equivalence in regex for number rules and add lookbehind assertions

M  +11   -6    doc/katepart/development.docbook
M  +39   -0    doc/katepart/regular-expressions.docbook

https://commits.kde.org/kate/007a7aef99999b3504a2b77d733adaa1f7198923

diff --git a/doc/katepart/development.docbook b/doc/katepart/development.docbook
index d49310948..6d0ed3c64 100644
--- a/doc/katepart/development.docbook
+++ b/doc/katepart/development.docbook
@@ -734,7 +734,8 @@ only stored for the switched context, specified in its <userinput>context</useri
 <para>If the captures will not be used, both by dynamic rules and in the same regular expression,
 <userinput>non-capturing groups</userinput> should be used: <userinput>(?:PATTERN)</userinput></para>
 <para>The <emphasis>lookahead</emphasis> or <emphasis>lookbehind</emphasis> groups such as
-<userinput>(?=PATTERN)</userinput> or <userinput>(?!PATTERN)</userinput> are not captured.
+<userinput>(?=PATTERN)</userinput>, <userinput>(?!PATTERN)</userinput> or
+<userinput>(?<=PATTERN)</userinput> are not captured.
 See <link linkend="regular-expressions">Regular Expressions</link> for more information.</para>
 </listitem>
 
@@ -910,7 +911,7 @@ loose its delimiter property in all <emphasis>keyword</emphasis> rules.</para>
 <varlistentry>
 <term>Int</term>
 <listitem>
-<para>Detect an integer number.</para>
+<para>Detect an integer number (as the regular expression: <userinput>\b[0-9]+</userinput>).</para>
 <para><programlisting><Int (common attributes) /></programlisting></para>
 <para>This rule has no specific attributes.</para>
 </listitem>
@@ -919,7 +920,8 @@ loose its delimiter property in all <emphasis>keyword</emphasis> rules.</para>
 <varlistentry>
 <term>Float</term>
 <listitem>
-<para>Detect a floating point number.</para>
+<para>Detect a floating point number (as the regular expression:
+<userinput>(\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?</userinput>).</para>
 <para><programlisting><Float (common attributes) /></programlisting></para>
 <para>This rule has no specific attributes.</para>
 </listitem>
@@ -928,7 +930,8 @@ loose its delimiter property in all <emphasis>keyword</emphasis> rules.</para>
 <varlistentry>
 <term>HlCOct</term>
 <listitem>
-<para>Detect an octal point number representation.</para>
+<para>Detect an octal point number representation (as the regular
+expression: <userinput>\b0[0-7]+</userinput>).</para>
 <para><programlisting><HlCOct (common attributes) /></programlisting></para>
 <para>This rule has no specific attributes.</para>
 </listitem>
@@ -937,7 +940,8 @@ loose its delimiter property in all <emphasis>keyword</emphasis> rules.</para>
 <varlistentry>
 <term>HlCHex</term>
 <listitem>
-<para>Detect a hexadecimal number representation.</para>
+<para>Detect a hexadecimal number representation (as a regular expression:
+<userinput>\b0[xX][0-9a-fA-F]+</userinput>).</para>
 <para><programlisting><HlCHex (common attributes) /></programlisting></para>
 <para>This rule has no specific attributes.</para>
 </listitem>
@@ -1048,7 +1052,8 @@ time due to no match.</para>
 <varlistentry>
 <term>DetectIdentifier</term>
 <listitem>
-<para>Detect identifier strings (as a regular expression: [a-zA-Z_][a-zA-Z0-9_]*).</para>
+<para>Detect identifier strings (as the regular expression:
+<userinput>[a-zA-Z_][a-zA-Z0-9_]*</userinput>).</para>
 <programlisting><DetectIdentifier (common attributes) /></programlisting>
 
 <para>This rule has no specific attributes.</para>
diff --git a/doc/katepart/regular-expressions.docbook b/doc/katepart/regular-expressions.docbook
index cdf00c5eb..e15657758 100644
--- a/doc/katepart/regular-expressions.docbook
+++ b/doc/katepart/regular-expressions.docbook
@@ -384,6 +384,23 @@ but silently ignore the other matches.)</para>
 
 </sect3>
 
+<sect3 id="lookbehind-assertions">
+<title>Lookbehind Assertions</title>
+
+<para>A lookbehind assertion is a sub pattern, starting with either
+<literal>?<=</literal> or <literal>?<!</literal>.</para>
+
+<para>Lookbehind has the same effect as the lookahead, but works backwards.
+For example to match the literal string <quote>fruit</quote> but
+only if not preceded by <quote>grape</quote>, you could use this
+expression: <userinput>(?<!grape)fruit</userinput>.</para>
+
+<para>Sub patterns used for assertions are not captured.</para>
+
+<para>See also <link linkend="assertions">Assertions</link></para>
+
+</sect3>
+
 </sect2>
 
 <sect2 id="special-characters-in-patterns">
@@ -662,6 +679,28 @@ pattern.</para>
 </listitem>
 </varlistentry>
 
+<varlistentry>
+<term><userinput>(?<=PATTERN)</userinput> (Positive lookbehind)</term>
+<listitem><para>Lookbehind has the same effect as the lookahead, but works backwards.
+A lookbehind looks at the part of the string previous a possible match. The positive
+lookbehind will match a string only if it is preceded by the <emphasis>PATTERN</emphasis>
+of the assertion, but the text matched by that will not be included in the result.</para>
+<para>The expression <userinput>(?<cup)cake</userinput> will match at <quote>cake</quote>
+if it is succeeded by <quote>cup</quote> (in <quote>cupcake</quote> but not in
+<quote>cheesecake</quote> or in <quote>cake</quote> alone).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>(?<!PATTERN)</userinput> (Negative lookbehind)</term>
+<listitem><para>The negative lookbehind prevents a possible match to be acknowledged if
+the previous part of the searched string does match its <emphasis>PATTERN</emphasis>.</para>
+<para>The expression <userinput>(?<![\w\.])[0-9]+</userinput> will match at <quote>123</quote>
+in the strings <quote>=123</quote> and <quote>-123</quote> while it can not match <quote>123</quote>
+in <quote>.123</quote> or <quote>word123</quote>.</para>
+</listitem>
+</varlistentry>
+
 <varlistentry>
 <term><userinput>(PATTERN)</userinput> (Capturing group)</term>