Doc: improve documentation of websearch_to_tqsuery().

It wasn't totally clear about punctuation other than what's
specified being ignored.

Pavel Borisov and Tom Lane

Discussion: https://postgr.es/m/CALT9ZEFsBdsogVjG40Z4KfM1Um=wj1FE9hJ00GK3oVfzz0sFNg@mail.gmail.com

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 86cb2379fcce54a4c1cfa445f0b5de0f3df7985f..b0afaebf728939a9bf5891bbb61e5dcd3d7e4c5f 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11381,11 +11381,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
         <replaceable>query</replaceable> <type>text</type> )
         <returnvalue>tsquery</returnvalue>
        <?br?>
-        Converts text to a <type>tsquery</type>, normalizing words according to
-        the specified or default configuration.  Quoted word sequences are
-        converted to phrase tests, and the word <quote>or</quote> is
-        understood as producing an OR operator.  This approximates the
-        behavior of some common web search tools.
+        Converts text to a <type>tsquery</type>, normalizing words according
+        to the specified or default configuration.  Quoted word sequences are
+        converted to phrase tests.  The word <quote>or</quote> is understood
+        as producing an OR operator, and a dash produces a NOT operator;
+        other punctuation is ignored.
+        This approximates the behavior of some common web search tools.
        <?br?>
         <literal>websearch_to_tsquery('english', '"fat rat" or cat dog')</literal>
         <returnvalue>'fat' &lt;-&gt; 'rat' | 'cat' &amp; 'dog'</returnvalue>

diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index ce2b4c664f9423ec3f4fac7fb811db66887bc4aa..187ff22f3eaf9574000fa275257bf2886fcc70ff 100644 (file)
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -913,7 +913,7 @@ SELECT plainto_tsquery('english', 'The Fat & Rats:C');
  'fat' & 'rat' & 'c'
 </screen>
 
-    Here, all the input punctuation was discarded as being space symbols.
+    Here, all the input punctuation was discarded.
    </para>
 
    <indexterm>
@@ -969,16 +969,16 @@ websearch_to_tsquery(<optional> <replaceable class="parameter">config</replaceab
     syntax in which simple unformatted text is a valid query.
     Unlike <function>plainto_tsquery</function>
     and <function>phraseto_tsquery</function>, it also recognizes certain
-    operators. Moreover, this function should never raise syntax errors,
+    operators. Moreover, this function will never raise syntax errors,
     which makes it possible to use raw user-supplied input for search.
     The following syntax is supported:
+
     <itemizedlist  spacing="compact" mark="bullet">
      <listitem>
        <para>
         <literal>unquoted text</literal>: text not inside quote marks will be
         converted to terms separated by <literal>&amp;</literal> operators, as
-        if processed by
-        <function>plainto_tsquery</function>.
+        if processed by <function>plainto_tsquery</function>.
       </para>
      </listitem>
      <listitem>
@@ -990,18 +990,26 @@ websearch_to_tsquery(<optional> <replaceable class="parameter">config</replaceab
      </listitem>
      <listitem>
       <para>
-       <literal>OR</literal>: logical or will be converted to
+       <literal>OR</literal>: the word <quote>or</quote> will be converted to
        the <literal>|</literal> operator.
       </para>
      </listitem>
      <listitem>
       <para>
-       <literal>-</literal>: the logical not operator, converted to the
+       <literal>-</literal>: a dash will be converted to
        the <literal>!</literal> operator.
       </para>
      </listitem>
     </itemizedlist>
+
+    Other punctuation is ignored.  So
+    like <function>plainto_tsquery</function>
+    and <function>phraseto_tsquery</function>,
+    the <function>websearch_to_tsquery</function> function will not
+    recognize <type>tsquery</type> operators, weight labels, or prefix-match
+    labels in its input.
    </para>
+
    <para>
     Examples:
 <screen>