head	1.4;
access;
symbols
	REL9_0_0:1.3.12.1
	REL9_1_ALPHA1:1.4
	REL9_0_RC1:1.3.12.1
	REL9_0_BETA4:1.3.12.1
	REL9_0_STABLE:1.3.0.12
	REL9_0_BETA3:1.3
	REL9_0_BETA2:1.3
	REL8_3_11:1.2
	REL8_4_4:1.2
	REL9_0_BETA1:1.3
	REL9_0_ALPHA5_BRANCH:1.3.0.10
	REL9_0_ALPHA5:1.3
	REL8_3_10:1.2
	REL8_4_3:1.2
	REL9_0_ALPHA4:1.3
	REL9_0_ALPHA4_BRANCH:1.3.0.8
	REL8_5_ALPHA3:1.3
	REL8_5_ALPHA3_BRANCH:1.3.0.6
	REL8_3_9:1.2
	REL8_4_2:1.2
	REL8_5_ALPHA2:1.3
	REL8_5_ALPHA2_BRANCH:1.3.0.4
	REL8_3_8:1.2
	REL8_4_1:1.2
	REL8_5_ALPHA1:1.3
	REL8_5_ALPHA1_BRANCH:1.3.0.2
	REL8_4_STABLE:1.2.0.4
	REL8_4_0:1.2
	REL8_4_RC2:1.2
	REL8_4_RC1:1.2
	REL8_4_BETA2:1.2
	REL8_4_BETA1:1.2
	REL8_3_7:1.2
	REL8_3_6:1.2
	REL8_3_5:1.2
	REL8_3_4:1.2
	REL8_3_3:1.2
	REL8_3_2:1.2
	REL8_3_1:1.2
	REL8_3_STABLE:1.2.0.2
	REL8_3_0:1.2
	REL8_3_RC2:1.2
	REL8_3_RC1:1.2
	REL8_3_BETA4:1.1;
locks; strict;
comment	@# @;


1.4
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.3;

1.3
date	2009.08.05.18.06.49;	author tgl;	state Exp;
branches
	1.3.12.1;
next	1.2;

1.2
date	2007.12.06.04.12.10;	author tgl;	state Exp;
branches;
next	1.1;

1.1
date	2007.12.02.21.13.34;	author tgl;	state Exp;
branches;
next	;

1.3.12.1
date	2010.07.29.19.34.36;	author petere;	state Exp;
branches;
next	;


desc
@@


1.4
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/dict-xsyn.sgml,v 1.3 2009/08/05 18:06:49 tgl Exp $ -->

<sect1 id="dict-xsyn">
 <title>dict_xsyn</title>

 <indexterm zone="dict-xsyn">
  <primary>dict_xsyn</primary>
 </indexterm>

 <para>
  <filename>dict_xsyn</> (Extended Synonym Dictionary) is an example of an
  add-on dictionary template for full-text search.  This dictionary type
  replaces words with groups of their synonyms, and so makes it possible to
  search for a word using any of its synonyms.
 </para>

 <sect2>
  <title>Configuration</title>

  <para>
   A <literal>dict_xsyn</> dictionary accepts the following options:
  </para>
  <itemizedlist>
   <listitem>
    <para>
     <literal>matchorig</> controls whether the original word is accepted by
     the dictionary. Default is <literal>true</>.
    </para>
   </listitem>
   <listitem>
    <para>
     <literal>matchsynonyms</> controls whether the synonyms are
     accepted by the dictionary. Default is <literal>false</>.
    </para>
   </listitem>
   <listitem>
    <para>
     <literal>keeporig</> controls whether the original word is included in
     the dictionary's output. Default is <literal>true</>.
    </para>
   </listitem>
   <listitem>
    <para>
     <literal>keepsynonyms</> controls whether the synonyms are included in
     the dictionary's output. Default is <literal>true</>.
    </para>
   </listitem>
   <listitem>
    <para>
     <literal>rules</> is the base name of the file containing the list of
     synonyms.  This file must be stored in
     <filename>$SHAREDIR/tsearch_data/</> (where <literal>$SHAREDIR</> means
     the <productname>PostgreSQL</> installation's shared-data directory).
     Its name must end in <literal>.rules</> (which is not to be included in
     the <literal>rules</> parameter).
    </para>
   </listitem>
  </itemizedlist>
  <para>
   The rules file has the following format:
  </para>
  <itemizedlist>
   <listitem>
    <para>
     Each line represents a group of synonyms for a single word, which is
     given first on the line. Synonyms are separated by whitespace, thus:
<programlisting>
word syn1 syn2 syn3
</programlisting>
    </para>
   </listitem>
   <listitem>
    <para>
     The sharp (<literal>#</>) sign is a comment delimiter. It may appear at
     any position in a line.  The rest of the line will be skipped.
    </para>
   </listitem>
  </itemizedlist>

  <para>
   Look at <filename>xsyn_sample.rules</>, which is installed in
   <filename>$SHAREDIR/tsearch_data/</>, for an example.
  </para>
 </sect2>

 <sect2>
  <title>Usage</title>

  <para>
   Running the installation script creates a text search template
   <literal>xsyn_template</> and a dictionary <literal>xsyn</>
   based on it, with default parameters.  You can alter the
   parameters, for example

<programlisting>
mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false);
ALTER TEXT SEARCH DICTIONARY
</programlisting>

   or create new dictionaries based on the template.
  </para>

  <para>
   To test the dictionary, you can try

<programlisting>
mydb=# SELECT ts_lexize('xsyn', 'word');
      ts_lexize
-----------------------
 {syn1,syn2,syn3}

mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true);
ALTER TEXT SEARCH DICTIONARY

mydb=# SELECT ts_lexize('xsyn', 'word');
      ts_lexize
-----------------------
 {word,syn1,syn2,syn3}

mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false, MATCHSYNONYMS=true);
ALTER TEXT SEARCH DICTIONARY

mydb=# SELECT ts_lexize('xsyn', 'syn1');
      ts_lexize
-----------------------
 {syn1,syn2,syn3}

mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true, MATCHORIG=false, KEEPSYNONYMS=false);
ALTER TEXT SEARCH DICTIONARY

mydb=# SELECT ts_lexize('xsyn', 'syn1');
      ts_lexize
-----------------------
 {word}
</programlisting>

   Real-world usage will involve including it in a text search
   configuration as described in <xref linkend="textsearch">.
   That might look like this:

<programlisting>
ALTER TEXT SEARCH CONFIGURATION english
    ALTER MAPPING FOR word, asciiword WITH xsyn, english_stem;
</programlisting>

  </para>
 </sect2>

</sect1>
@


1.3
log
@Add matchorig, matchsynonyms, and keepsynonyms options to contrib/dict_xsyn.

Sergey Karpov
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/dict-xsyn.sgml,v 1.2 2007/12/06 04:12:10 tgl Exp $ -->
d67 1
a67 1
    <programlisting>
d69 1
a69 1
    </programlisting>
@


1.3.12.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/dict-xsyn.sgml,v 1.3 2009/08/05 18:06:49 tgl Exp $ -->
d67 1
a67 1
<programlisting>
d69 1
a69 1
</programlisting>
@


1.2
log
@Make an editorial pass over the newly SGML-ified contrib documentation.
Fix lots of bad markup, bad English, bad explanations.

This commit covers only about half the contrib modules, but I grow weary...
@
text
@d1 1
a1 1
<!-- $PostgreSQL$ -->
d26 20
a45 3
     <literal>keeporig</> controls whether the original word is included (if
     <literal>true</>), or only its synonyms (if <literal>false</>). Default
     is <literal>true</>.
d110 8
d119 16
d137 1
a137 1
   but real-world usage will involve including it in a text search
@


1.1
log
@Add SGML docs for contrib/dict_int and contrib/dict_xsyn.
Albert Cervera i Areny
@
text
@d1 2
d5 1
a5 1
 
d11 4
a14 3
  The Extended Synonym Dictionary module replaces words with groups of their
  synonyms, and so makes it possible to search for a word using any of its
  synonyms.
d19 1
d26 3
a28 2
     KEEPORIG controls whether the original word is included, or only its
     synonyms. Default is 'true'.
d33 6
a38 3
     RULES is the base name of the file containing the list of synonyms.
     This file must be in $(prefix)/share/tsearch_data/, and its name must
     end in ".rules" (which is not included in the RULES parameter).
d49 1
a49 2
     given first on the line. Synonyms are separated by whitespace:
    </para>
d53 1
d57 2
a58 2
     Sharp ('#') sign is a comment delimiter. It may appear at any position
     inside the line.  The rest of the line will be skipped.
d64 2
a65 2
   Look at xsyn_sample.rules, which is installed in $(prefix)/share/tsearch_data/,
   for an example.
d71 1
a71 6
  <programlisting>
mydb=# SELECT ts_lexize('xsyn','word');
ts_lexize
----------------
{word,syn1,syn2,syn3)
  </programlisting>
d73 32
a104 1
   Change dictionary options:
a105 4
  <programlisting>
mydb# ALTER TEXT SEARCH DICTIONARY xsyn (KEEPORIG=false);
ALTER TEXT SEARCH DICTIONARY
  </programlisting>
@

