Add some quick documentation for tsearch2 compatibility module.

doc/src/sgml/contrib.sgml

@@ -55,6 +55,7 @@
  &seg;
  &sslinfo;
  &tablefunc;
+ &tsearch2;
  &uuid-ossp;
  &vacuumlo;
  &xml2;

doc/src/sgml/filelist.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.52 2007/11/10 23:30:46 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.53 2007/11/14 01:09:50 tgl Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -117,6 +117,7 @@
 <!entity seg             SYSTEM "seg.sgml">
 <!entity sslinfo         SYSTEM "sslinfo.sgml">
 <!entity tablefunc       SYSTEM "tablefunc.sgml">
+<!entity tsearch2        SYSTEM "tsearch2.sgml">
 <!entity uuid-ossp       SYSTEM "uuid-ossp.sgml">
 <!entity vacuumlo        SYSTEM "vacuumlo.sgml">
 <!entity xml2            SYSTEM "xml2.sgml"> 

doc/src/sgml/tsearch2.sgml

+<sect1 id="tsearch2">
+ <title>tsearch2</title>
+ 
+ <indexterm zone="tsearch2">
+  <primary>tsearch2</primary>
+ </indexterm>
+
+ <para>
+  The <literal>tsearch2</literal> module provides backwards-compatible
+  text search functionality for applications that used
+  <filename>contrib/tsearch2</> before text searching was integrated
+  into core <productname>PostgreSQL</productname> in release 8.3.
+ </para>
+
+ <sect2>
+  <title>Portability Issues</title>
+
+  <para>
+   Although the built-in text search features were based on
+   <filename>contrib/tsearch2</> and are largely similar to it,
+   there are numerous small differences that will create portability
+   issues for existing applications:
+  </para>
+
+  <itemizedlist mark="bullet">
+   <listitem>
+    <para>
+     Some functions' names were changed, for example <function>rank</>
+     to <function>ts_rank</>.
+     The replacement <literal>tsearch2</literal> module
+     provides aliases having the old names.
+    </para>
+   </listitem>
+
+   <listitem>
+    <para>
+     The built-in text search data types and functions all exist within
+     the system schema <literal>pg_catalog</>.  In an installation using
+     <filename>contrib/tsearch2</>, these objects would usually have been in
+     the <literal>public</> schema, though some users chose to place them
+     in a separate schema of their own.  Explicitly schema-qualified
+     references to the objects will therefore fail in either case.
+     The replacement <literal>tsearch2</literal> module
+     provides alias objects that are stored in <literal>public</>
+     (or another schema if necessary) so that such references will still work.
+    </para>
+   </listitem>
+
+   <listitem>
+    <para>
+     There is no concept of a <quote>current parser</> or <quote>current
+     dictionary</> in the built-in text search features, only of a current
+     search configuration (set by the <varname>default_text_search_config</>
+     parameter).  While the current parser and current dictionary were used
+     only by functions intended for debugging, this might still pose
+     a porting obstacle in some cases.
+     The replacement <literal>tsearch2</literal> module emulates these
+     additional state variables and provides backwards-compatible functions
+     for setting and retrieving them.
+    </para>
+   </listitem>
+  </itemizedlist>
+
+  <para>
+   There are some issues that are not addressed by the replacement
+   <literal>tsearch2</literal> module, and will therefore require
+   application code changes in any case:
+  </para>
+
+  <itemizedlist mark="bullet">
+   <listitem>
+    <para>
+     The old <function>tsearch2</> trigger function allowed items in its
+     argument list to be names of functions to be invoked on the text data
+     before it was converted to <type>tsvector</> format.  This was removed
+     as being a security hole, since it was not possible to guarantee that
+     the function invoked was the one intended.  The recommended approach
+     if the data must be massaged before being indexed is to write a custom
+     trigger that does the work for itself.
+    </para>
+   </listitem>
+
+   <listitem>
+    <para>
+     Text search configuration information has been moved into core
+     system catalogs that are noticeably different from the tables used
+     by <filename>contrib/tsearch2</>.  Any applications that examined
+     or modified those tables will need adjustment.
+    </para>
+   </listitem>
+
+   <listitem>
+    <para>
+     If an application used any custom text search configurations,
+     those will need to be set up in the core
+     catalogs using the new text search configuration SQL commands.
+     The replacement <literal>tsearch2</literal> module offers a little
+     bit of support for this by making it possible to load an old set
+     of <filename>contrib/tsearch2</> configuration tables into
+     <productname>PostgreSQL</productname> 8.3.  (Without the module,
+     it is not possible to load the configuration data because values in the
+     <type>regprocedure</> columns cannot be resolved to functions.)
+     While those configuration tables won't actually <emphasis>do</>
+     anything, at least their contents will be available to be consulted
+     while setting up an equivalent custom configuration in 8.3.
+    </para>
+   </listitem>
+
+   <listitem>
+    <para>
+     The old <function>reset_tsearch()</> and <function>get_covers()</>
+     functions are not supported.
+    </para>
+   </listitem>
+
+   <listitem>
+    <para>
+     The replacement <literal>tsearch2</literal> module does not define
+     any alias operators, relying entirely on the built-in ones.
+     This would only pose an issue if an application used explicitly
+     schema-qualified operator names, which is very uncommon.
+    </para>
+   </listitem>
+  </itemizedlist>
+
+ </sect2>
+
+ <sect2>
+  <title>Converting a pre-8.3 Installation</title>
+
+  <para>
+   The recommended way to update a pre-8.3 installation that uses
+   <filename>contrib/tsearch2</> is:
+  </para>
+
+  <procedure>
+   <step>
+    <para>
+     Make a dump from the old installation in the usual way,
+     but be sure not to use <literal>-c</> (<literal>--clean</>)
+     option of <application>pg_dump</> or <application>pg_dumpall</>.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     In the new installation, create empty database(s) and install
+     the replacement <literal>tsearch2</literal> module into each
+     database that will use text search.  This must be done
+     <emphasis>before</> loading the dump data!  If your old installation
+     had the <filename>contrib/tsearch2</> objects in a schema other
+     than <literal>public</>, be sure to adjust the
+     <literal>tsearch2</literal> installation script so that the replacement
+     objects are created in that same schema.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     Load the dump data.  There will be quite a few errors reported
+     due to failure to recreate the original <filename>contrib/tsearch2</>
+     objects.  These errors can be ignored, but this means you cannot
+     restore the dump in a single transaction (eg, you cannot use
+     <application>pg_restore</>'s <literal>-1</> switch).
+    </para>
+   </step>
+
+   <step>
+    <para>
+     Examine the contents of the restored <filename>contrib/tsearch2</>
+     configuration tables (<structname>pg_ts_cfg</> and so on), and
+     create equivalent built-in text search configurations as needed.
+     You may drop the old configuration tables once you've extracted
+     all the useful information from them.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     Test your application.
+    </para>
+   </step>
+  </procedure>
+
+  <para>
+   At a later time you may wish to rename application references
+   to the alias text search objects, so that you can eventually
+   uninstall the replacement <literal>tsearch2</literal> module.
+  </para>
+
+ </sect2>
+
+ <sect2>
+  <title>References</title>
+  <para>
+   Tsearch2 Development Site
+   <ulink url="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/"></ulink>
+  </para>
+ </sect2>
+
+</sect1>