Add SGML documentation for contrib/spi and contrib/test_parser.

The spi documentation is pretty rudimentary, but it's a start.

doc/src/sgml/test-parser.sgml

@@ -0,0 +1,87 @@
+<!-- $PostgreSQL: pgsql/doc/src/sgml/test-parser.sgml,v 1.1 2007/12/03 04:18:47 tgl Exp $ -->
+
+<sect1 id="test-parser">
+ <title>test_parser</title>
+
+ <indexterm zone="test-parser">
+  <primary>test_parser</primary>
+ </indexterm>
+
+ <para>
+  This is an example of a custom parser for full text search.
+ </para>
+
+ <para>
+  It recognizes space-delimited words and returns just two token types:
+
+<programlisting>
+mydb=# SELECT * FROM ts_token_type('testparser');
+ tokid | alias |  description  
+-------+-------+---------------
+     3 | word  | Word
+    12 | blank | Space symbols
+(2 rows)
+</programlisting>
+
+  These token numbers have been chosen to be compatible with the default
+  parser's numbering.  This allows us to use its <function>headline()</>
+  function, thus keeping the example simple.
+ </para>
+
+ <sect2>
+  <title>Usage</title>
+
+  <para>
+   Running the installation script creates a text search parser
+   <literal>testparser</>.  It has no user-configurable parameters.
+  </para>
+
+  <para>
+   You can test the parser with, for example,
+
+<programlisting>
+mydb=# SELECT * FROM ts_parse('testparser', 'That''s my first own parser');
+ tokid | token  
+-------+--------
+     3 | That's
+    12 |  
+     3 | my
+    12 |  
+     3 | first
+    12 |  
+     3 | own
+    12 |  
+     3 | parser
+</programlisting>
+  </para>
+
+  <para>
+   Real-world use requires setting up a text search configuration
+   that uses the parser.  For example,
+
+<programlisting>
+mydb=# CREATE TEXT SEARCH CONFIGURATION testcfg ( PARSER = testparser );
+CREATE TEXT SEARCH CONFIGURATION
+
+mydb=# ALTER TEXT SEARCH CONFIGURATION testcfg
+mydb-#   ADD MAPPING FOR word WITH english_stem;
+ALTER TEXT SEARCH CONFIGURATION
+
+mydb=#  SELECT to_tsvector('testcfg', 'That''s my first own parser');
+          to_tsvector          
+-------------------------------
+ 'that':1 'first':3 'parser':5
+(1 row)
+
+mydb=# SELECT ts_headline('testcfg', 'Supernovae stars are the brightest phenomena in galaxies',
+mydb(#                    to_tsquery('testcfg', 'star'));
+                           ts_headline                           
+-----------------------------------------------------------------
+ Supernovae &lt;b&gt;stars&lt;/b&gt; are the brightest phenomena in galaxies
+(1 row)
+</programlisting>
+  </para>
+
+ </sect2>
+
+</sect1>