From d321421d0a409ee4473c996fd2275df0ff215eaf Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 22 Aug 2007 01:39:46 +0000
Subject: Simplify the syntax of CREATE/ALTER TEXT SEARCH DICTIONARY by
 treating the init options of the template as top-level options in the syntax.
  This also makes ALTER a bit easier to use, since options can be replaced
 individually. I also made these statements verify that the tmplinit method
 will accept the new settings before they get stored; in the original coding
 you didn't find out about mistakes until the dictionary got invoked.

Under the hood, init methods now get options as a List of DefElem instead
of a raw text string --- that lets tsearch use existing options-pushing code
instead of duplicating functionality.
---
 doc/src/sgml/ref/alter_tsdictionary.sgml  | 46 ++++++++++++++++++++++++-------
 doc/src/sgml/ref/create_tsdictionary.sgml | 43 ++++++++++++++++++++++++-----
 2 files changed, 72 insertions(+), 17 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/alter_tsdictionary.sgml b/doc/src/sgml/ref/alter_tsdictionary.sgml
index 59c33666557..a2929c70d12 100644
--- a/doc/src/sgml/ref/alter_tsdictionary.sgml
+++ b/doc/src/sgml/ref/alter_tsdictionary.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_tsdictionary.sgml,v 1.1 2007/08/21 21:08:47 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_tsdictionary.sgml,v 1.2 2007/08/22 01:39:44 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -20,7 +20,9 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> ( OPTION = <replaceable class="parameter">init_options</replaceable> )
+ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> (
+    <replaceable class="parameter">option</replaceable> [ = <replaceable class="parameter">value</replaceable> ] [, ... ]
+)
 ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> RENAME TO <replaceable>newname</replaceable>
 ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> OWNER TO <replaceable>newowner</replaceable>
 </synopsis>
@@ -31,8 +33,8 @@ ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> OWNER TO <replaceab
 
   <para>
    <command>ALTER TEXT SEARCH DICTIONARY</command> changes the definition of
-   a text search dictionary.  You can change the dictionary's initialization
-   options, or change the dictionary's name or owner.
+   a text search dictionary.  You can change the dictionary's
+   template-specific options, or change the dictionary's name or owner.
   </para>
 
   <para>
@@ -56,11 +58,22 @@ ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> OWNER TO <replaceab
    </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="parameter">init_options</replaceable></term>
+    <term><replaceable class="parameter">option</replaceable></term>
     <listitem>
      <para>
-      A new list of initialization options, or <literal>NULL</> to
-      remove all options.
+      The name of a template-specific option to be set for this dictionary.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">value</replaceable></term>
+    <listitem>
+     <para>
+      The new value to use for a template-specific option.
+      If the equal sign and value are omitted, then any previous
+      setting for the option is removed from the dictionary,
+      allowing the default to be used.
      </para>
     </listitem>
    </varlistentry>
@@ -83,18 +96,31 @@ ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> OWNER TO <replaceab
     </listitem>
    </varlistentry>
  </variablelist>
+
+  <para>
+   Template-specific options can appear in any order.
+  </para>
  </refsect1>
   
  <refsect1>
   <title>Examples</title>
 
   <para>
-   The following example command sets the language and stopword list
-   for a Snowball-based dictionary.
+   The following example command changes the stopword list
+   for a Snowball-based dictionary.  Other parameters remain unchanged.
+  </para>
+
+<programlisting>
+ALTER TEXT SEARCH DICTIONARY my_dict ( StopWords = newrussian );
+</programlisting>  
+
+  <para>
+   The following example command changes the language option to dutch,
+   and removes the stopword option entirely.
   </para>
 
 <programlisting>
-ALTER TEXT SEARCH DICTIONARY my_russian ( option = 'Language=russian, StopWords=my_russian' );
+ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords );
 </programlisting>  
  </refsect1>
 
diff --git a/doc/src/sgml/ref/create_tsdictionary.sgml b/doc/src/sgml/ref/create_tsdictionary.sgml
index 81c6a0c6edb..9aa53a6a7c4 100644
--- a/doc/src/sgml/ref/create_tsdictionary.sgml
+++ b/doc/src/sgml/ref/create_tsdictionary.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_tsdictionary.sgml,v 1.1 2007/08/21 21:08:47 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_tsdictionary.sgml,v 1.2 2007/08/22 01:39:44 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -22,7 +22,7 @@ PostgreSQL documentation
 <synopsis>
 CREATE TEXT SEARCH DICTIONARY <replaceable class="parameter">name</replaceable> (
     TEMPLATE = <replaceable class="parameter">template</replaceable>
-    [, OPTION = <replaceable class="parameter">init_options</replaceable> ]
+    [, <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ]]
 )
 </synopsis>
  </refsynopsisdiv>
@@ -78,17 +78,46 @@ CREATE TEXT SEARCH DICTIONARY <replaceable class="parameter">name</replaceable>
    </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="parameter">init_options</replaceable></term>
+    <term><replaceable class="parameter">option</replaceable></term>
     <listitem>
      <para>
-      A list of initialization options for the template functions.
-      This is a string containing <replaceable>keyword</> <literal>=</>
-      <replaceable>value</> pairs.  The specific keywords allowed
-      vary depending on the text search template.
+      The name of a template-specific option to be set for this dictionary.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">value</replaceable></term>
+    <listitem>
+     <para>
+      The value to use for a template-specific option.  If the value
+      is not a simple identifier or number, it must be quoted (but you can
+      always quote it, if you wish).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
+
+  <para>
+   The options can appear in any order.
+  </para>
+ </refsect1>
+  
+ <refsect1>
+  <title>Examples</title>
+
+  <para>
+   The following example command creates a Snowball-based dictionary
+   with a nonstandard list of stop words.
+  </para>
+
+<programlisting>
+CREATE TEXT SEARCH DICTIONARY my_russian (
+    template = snowball,
+    language = russian,
+    stopwords = myrussian
+);
+</programlisting>  
  </refsect1>
  
  <refsect1>
-- 
cgit v1.2.3