Document that the regexp split functions ignore zero-length matches in

certain corner cases.  Per discussion, the code does what we want, but
it really needs to be documented that these functions act differently
from regexp_matches.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7e11d757352e236778e9b461e5954f9110d3b4c2..0f9e9b2d07d78be3e497ee56581d70717094444c 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -3383,10 +3383,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
    </para>
 
    <para>
-    <productname>PostgreSQL</productname>'s regular expressions are implemented
-    using a package written by Henry Spencer.  Much of
-    the description of regular expressions below is copied verbatim from his
-    manual entry.
+    As the last example demonstrates, the regexp split functions ignore
+    zero-length matches that occur at the start or end of the string
+    or immediately after a previous match.  This is contrary to the strict
+    definition of regexp matching that is implemented by
+    <function>regexp_matches</>, but is usually the most convenient behavior
+    in practice.  Other software systems such as Perl use similar definitions.
    </para>
 
 <!-- derived from the re_syntax.n man page -->
@@ -3394,6 +3396,13 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
    <sect3 id="posix-syntax-details">
     <title>Regular Expression Details</title>
 
+   <para>
+    <productname>PostgreSQL</productname>'s regular expressions are implemented
+    using a package written by Henry Spencer.  Much of
+    the description of regular expressions below is copied verbatim from his
+    manual entry.
+   </para>
+
    <para>
     Regular expressions (<acronym>RE</acronym>s), as defined in
     <acronym>POSIX</acronym> 1003.2, come in two forms: