List:Commits« Previous MessageNext Message »
From:paul Date:December 17 2005 10:47pm
Subject:svn commit - mysqldoc@docsrva: r585 - in trunk: . refman-5.1
View as plain text  
Author: paul
Date: 2005-12-17 23:47:50 +0100 (Sat, 17 Dec 2005)
New Revision: 585

Log:
 r4879@frost:  paul | 2005-12-17 16:46:58 -0600
 General revisions to plugin section.


Modified:
   trunk/
   trunk/refman-5.1/extending-mysql.xml


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:4878
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1694
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:4879
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1694

Modified: trunk/refman-5.1/extending-mysql.xml
===================================================================
--- trunk/refman-5.1/extending-mysql.xml	2005-12-17 22:47:27 UTC (rev 584)
+++ trunk/refman-5.1/extending-mysql.xml	2005-12-17 22:47:50 UTC (rev 585)
@@ -496,9 +496,9 @@
       server. Currently, the plugin API supports creation of full-text
       parser plugins. Such a plugin can be used to replace or augment
       the built-in full-text parser. For example, a plugin can parse
-      text into words using rules that differ from the rules used by the
-      built-in parser. This could be useful if you need to parse text
-      with different characteristics than those expected by the built-in
+      text into words using rules that differ from those used by the
+      built-in parser. This can be useful if you need to parse text with
+      characteristics different from those expected by the built-in
       parser.
     </para>
 
@@ -565,10 +565,10 @@
             The version information included in the plugin API enables a
             plugin library and each plugin that it contains to be
             self-identifying with respect to the API version that was
-            used when the library was built. If the API changes over
-            time, the version numbers will change, but a server can
-            examine a given plugin library's version information to
-            determine whether it supports the plugins in the library.
+            used to build the library. If the API changes over time, the
+            version numbers will change, but a server can examine a
+            given plugin library's version information to determine
+            whether it supports the plugins in the library.
           </para>
 
           <para>
@@ -580,7 +580,7 @@
             plugin in a library has a type-specific version number. For
             example, library containing a full-text parsing plugin has a
             general plugin API version number, and the plugin has a
-            version number for the full-text plugin interface.
+            version number specific to the full-text plugin interface.
           </para>
         </listitem>
 
@@ -606,7 +606,7 @@
             The newer plugin interface eliminates the security issues of
             the older UDF interface. When a UDF plugin type is
             implemented, that will allow non-plugin UDFs to be brought
-            into the plugin framework and the older interface will be
+            into the plugin framework and the older interface to be
             phased out.
           </para>
         </listitem>
@@ -706,9 +706,8 @@
         <listitem>
           <para>
             <literal>plugin_dir</literal> indicates the location of the
-            directory where all plugins (and UDFs) must be installed.
-            The value of this variable can be specified at server
-            startup with a
+            directory where all plugins must be installed. The value of
+            this variable can be specified at server startup with a
             <option>--plugin_dir=<replaceable>path</replaceable></option>
             option.
           </para>
@@ -783,7 +782,9 @@
             by serving as a front end for it. In this role, the plugin
             extracts text from the input and passes the text to the
             parser, which splits up the text into words using its normal
-            parsing rules.
+            parsing rules. In particular, this parsing will be affected
+            by the <literal>ft_<replaceable>xxx</replaceable></literal>
+            system variables and the stopword list.
           </para>
 
           <para>
@@ -1067,14 +1068,13 @@
         used. This means that uninstalling a plugin is something to do
         with care unless you do not care about the table contents. If
         you are uninstalling a plugin with no intention of reinstalling
-        it later (for example, to update it with a new version), and you
-        care about the table contents, you should dump the table with
-        <command>mysqldump</command> and remove the <literal>WITH
-        PARSER</literal> clause from the dumped <literal>CREATE
-        TABLE</literal> statement so that you can reload the table
-        later. If you do not care about the table, <literal>DROP
-        TABLE</literal> can be used even if plugins associated with the
-        table are missing.
+        it later and you care about the table contents, you should dump
+        the table with <command>mysqldump</command> and remove the
+        <literal>WITH PARSER</literal> clause from the dumped
+        <literal>CREATE TABLE</literal> statement so that you can reload
+        the table later. If you do not care about the table,
+        <literal>DROP TABLE</literal> can be used even if any plugins
+        associated with the table are missing.
       </para>
 
     </section>
@@ -1136,7 +1136,8 @@
 
         <para>
           The <literal>st_mysql_plugin</literal> structure is common to
-          every type of plugin. Its members are used as follows:
+          every type of plugin. Its members should be filled in as
+          follows:
         </para>
 
         <itemizedlist>
@@ -1290,11 +1291,12 @@
 
         <para>
           A full-text parser plugin is used in two different contexts,
-          indexing and searching. In either context, the server calls
-          the initialization and deinitialization functions at the
-          beginning and end of processing each SQL statement that causes
-          the plugin to be invoked. During statement processing, the
-          main parsing function is called according to its use:
+          indexing and searching. In both contexts, the server calls the
+          initialization and deinitialization functions at the beginning
+          and end of processing each SQL statement that causes the
+          plugin to be invoked. However, during statement processing,
+          the server calls the main parsing function in context-specific
+          fashion:
         </para>
 
         <itemizedlist>
@@ -1308,14 +1310,14 @@
 
           <listitem>
             <para>
-              For searching, the parser is called to parse the search
-              string. It might also be called for rows processed by the
-              statement. In natural language mode, there is no need for
-              the server to call the parser. For boolean mode phrase
-              searches or natural language searches with query
-              expansion, the parser is used to parse column values for
-              information that is not in the index. Also, if a boolean
-              mode search is done for a column that has no
+              For searching, the server calls the parser to parse the
+              search string. The parser might also be called for rows
+              processed by the statement. In natural language mode,
+              there is no need for the server to call the parser. For
+              boolean mode phrase searches or natural language searches
+              with query expansion, the parser is used to parse column
+              values for information that is not in the index. Also, if
+              a boolean mode search is done for a column that has no
               <literal>FULLTEXT</literal> index, the built-in parser
               will be called. (Plugins are associated with specific
               indexes. If there is no index, no plugin is used.)
@@ -1397,23 +1399,15 @@
             <para>
               A pointer to a callback function that invokes the server's
               built-in parser. Use this callback when the plugin acts as
-              a front-end to the built-in parser. When the plugin's
-              parsing function is called, it processes the input to
-              extract the text and passes the text to the
+              a front-end to the built-in parser. That is, when the
+              plugin parsing function is called, it should process the
+              input to extract the text and pass the text to the
               <literal>mysql_parse</literal> callback.
             </para>
 
             <para>
-              A front-end plugin can extract text and pass it all at
-              once to the built-in parser, or it can extract and pass
-              text to the built-in parser a piece at a time. However, in
-              this case, the built-in parser treats the pieces of text
-              as though there are implicit word breaks between them.
-            </para>
-
-            <para>
-              The first parameter for this callback function is the
-              <literal>mysql_ftparam</literal> member of the parsing
+              The first parameter for this callback function should be
+              the <literal>mysql_ftparam</literal> member of the parsing
               context structure. That is, if <literal>param</literal>
               points to the structure, invoke the callback like this:
             </para>
@@ -1421,6 +1415,14 @@
 <programlisting>
 param-&gt;mysql_parse(param-&gt;mysql_ftparam, ...);
 </programlisting>
+
+            <para>
+              A front-end plugin can extract text and pass it all at
+              once to the built-in parser, or it can extract and pass
+              text to the built-in parser a piece at a time. However, in
+              this case, the built-in parser treats the pieces of text
+              as though there are implicit word breaks between them.
+            </para>
           </listitem>
 
           <listitem>
@@ -1431,17 +1433,18 @@
             <para>
               A pointer to a callback function that adds a word to a
               full-text index or to the list of search terms. Use this
-              callback when the parser plugin acts as a replacement for
-              the built-in parser. When the plugin parsing function is
-              called, it parses the input into words and invokes the
-              <literal>mysql_add_word</literal> callback for each word.
+              callback when the parser plugin replaces the built-in
+              parser. That is, when the plugin parsing function is
+              called, it should parse the input into words and invoke
+              the <literal>mysql_add_word</literal> callback for each
+              word.
             </para>
 
             <para>
-              The first parameter for this callback function is the
-              mysql_ftparam member of the parsing context structure.
-              That is, if <literal>param</literal> points to the
-              structure, invoke the callback like this:
+              The first parameter for this callback function should be
+              the <literal>mysql_ftparam</literal> member of the parsing
+              context structure. That is, if <literal>param</literal>
+              points to the structure, invoke the callback like this:
             </para>
 
 <programlisting>
@@ -1468,8 +1471,7 @@
             <para>
               This is set by the server. It is passed as the first
               argument to the <literal>mysql_parse</literal> or
-              <literal>mysql_add_word</literal> callback. The plugin
-              should not modify it.
+              <literal>mysql_add_word</literal> callback.
             </para>
           </listitem>
 
@@ -1537,7 +1539,7 @@
                 </para>
 
                 <para>
-                  Parse in stopword mode. This is used for boolean
+                  Parse in stopword mode. This is used in boolean
                   searches for phrase matching. The parser should pass
                   all words to the server, even stopwords or words that
                   are outside any normal length limits.
@@ -1602,45 +1604,42 @@
             </para>
 
             <para>
-              The token type. This should be one of the following
-              values:
+              The token type. This should be one of values shown in the
+              following table:
             </para>
 
-            <itemizedlist>
-
-              <listitem>
-                <para>
-                  <literal>FT_TOKEN_EOF</literal>: End of data
-                </para>
-              </listitem>
-
-              <listitem>
-                <para>
-                  <literal>FT_TOKEN_WORD</literal>: A regular word
-                </para>
-              </listitem>
-
-              <listitem>
-                <para>
-                  <literal>FT_TOKEN_LEFT_PAREN</literal>: The beginning
-                  of a group or subexpression
-                </para>
-              </listitem>
-
-              <listitem>
-                <para>
-                  <literal>FT_TOKEN_RIGHT_PAREN</literal>: The end of a
-                  group or subexpression
-                </para>
-              </listitem>
-
-              <listitem>
-                <para>
-                  <literal>FT_TOKEN_STOPWORD</literal>: A stopword
-                </para>
-              </listitem>
-
-            </itemizedlist>
+            <informaltable>
+              <tgroup cols="2">
+                <colspec colwidth="40*"/>
+                <colspec colwidth="60*"/>
+                <tbody>
+                  <row>
+                    <entry><emphasis role="bold">Type</emphasis></entry>
+                    <entry><emphasis role="bold">Meaning</emphasis></entry>
+                  </row>
+                  <row>
+                    <entry><literal>FT_TOKEN_EOF</literal></entry>
+                    <entry>End of data</entry>
+                  </row>
+                  <row>
+                    <entry><literal>FT_TOKEN_WORD</literal></entry>
+                    <entry>A regular word</entry>
+                  </row>
+                  <row>
+                    <entry><literal>FT_TOKEN_LEFT_PAREN</literal></entry>
+                    <entry>The beginning of a group or subexpression</entry>
+                  </row>
+                  <row>
+                    <entry><literal>FT_TOKEN_RIGHT_PAREN</literal></entry>
+                    <entry>The end of a group or subexpression</entry>
+                  </row>
+                  <row>
+                    <entry><literal>FT_TOKEN_STOPWORD</literal></entry>
+                    <entry>A stopword</entry>
+                  </row>
+                </tbody>
+              </tgroup>
+            </informaltable>
           </listitem>
 
           <listitem>
@@ -1694,8 +1693,8 @@
             </para>
 
             <para>
-              Whether matching should be done as if the
-              <literal>*</literal> truncation operator has been given.
+              Whether matching should be done as if the boolean-mode
+              <literal>*</literal> truncation operator had been given.
             </para>
           </listitem>
 
@@ -1714,12 +1713,13 @@
         <title>&title-plugin-creating;</title>
 
         <para>
-          This section describes a step-by-step procedure for creating a
-          plugin library that contains a full-text parsing plugin named
+          This section provides a step-by-step procedure for creating a
+          plugin library. It shows how to develop a library that
+          contains a full-text parsing plugin named
           <literal>simple_parser</literal>. This plugin performs parsing
           based on simpler rules than those used by the MySQL built-in
-          full-text parser: Words are non-empty runs of non-empty
-          whitespace characters.
+          full-text parser: Words are non-empty runs of whitespace
+          characters.
         </para>
 
         <para>
@@ -1801,8 +1801,8 @@
             </para>
 
             <para>
-              Every plugin library includes a library descriptor that
-              must define two symbols:
+              Every plugin library must include a library descriptor
+              that must define two symbols:
             </para>
 
             <itemizedlist>
@@ -1960,7 +1960,7 @@
 
           <listitem>
             <para>
-              Set up the functions for each plugin.
+              Set up the plugin interface functions.
             </para>
 
             <para>
@@ -1994,7 +1994,8 @@
               The type-specific plugin descriptor for
               <literal>simple_parser</literal> names the initialization,
               deinitialization, and parsing functions that the server
-              invokes when the plugin is used. The initialization and
+              invokes when the plugin is used. For
+              <literal>simple_parser</literal>, the initialization and
               deinitialization functions do nothing:
             </para>
 
@@ -2027,8 +2028,8 @@
               to the text to be parsed, and a <literal>length</literal>
               member that indicates how long the text is. The simple
               parsing done by the plugin considers non-empty runs of
-              non-empty whitespace characters to be words, so it
-              identifies words like this:
+              whitespace characters to be words, so it identifies words
+              like this:
             </para>
 
 <programlisting>
@@ -2077,17 +2078,27 @@
     param-&gt;mysql_add_word(param-&gt;mysql_ftparam, word, len, 0);
 }
 </programlisting>
+
+            <para>
+              For boolean-mode parsing, <literal>add_word()</literal>
+              fills in the members of the <literal>bool_info</literal>
+              structure as described in
+              <xref linkend="plugin-api-type-specific"/>.
+            </para>
           </listitem>
 
           <listitem>
             <para>
               Compile the plugin library as a shared library and install
               it in the plugin directory. The procedure for compiling
-              shared objects varies from system to system. If the
+              shared objects varies from system to system. If you build
+              your library using the GNU autotools,
+              <command>libtool</command> should be able to generate the
+              correct compilation commands for your system. If the
               library is named <literal>mypluglib</literal>, you should
               end up with a shared object file that has a name something
-              like <filename>libmypluglib.so</filename>. The filename
-              might have a different extension on your system.
+              like <filename>libmypluglib.so</filename>. (The filename
+              might have a different extension on your system.)
             </para>
 
             <para>
@@ -2108,7 +2119,7 @@
 
             <para>
               When you install the plugin library, make sure that its
-              permissions are such that it is executable by the server.
+              permissions allow it to be executed by the server.
             </para>
           </listitem>
 
@@ -2164,7 +2175,7 @@
 
             <para>
               Insert some text into the table and try some searches.
-              These should verify that the parser treats all
+              These should verify that the parser plugin treats all
               non-whitespace characters as word characters:
             </para>
 

Thread
svn commit - mysqldoc@docsrva: r585 - in trunk: . refman-5.1paul17 Dec