Added yaz-icu man page
[yaz-moved-to-github.git] / doc / yaz-icu-man.xml
1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
2  "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
3 [
4      <!ENTITY % local SYSTEM "local.ent">
5      %local;
6      <!ENTITY % entities SYSTEM "entities.ent">
7      %entities;
8      <!ENTITY % idcommon SYSTEM "common/common.ent">
9      %idcommon;
10 ]>
11 <!-- $Id: yaz-icu-man.xml,v 1.1 2007-11-12 11:13:05 adam Exp $ -->
12 <refentry id="zoomsh">
13  <refentryinfo>
14   <productname>YAZ</productname>
15   <productnumber>&version;</productnumber>
16  </refentryinfo>
17  
18  <refmeta>
19   <refentrytitle>yaz-icu</refentrytitle>
20   <manvolnum>1</manvolnum>
21  </refmeta>
22  
23  <refnamediv>
24   <refname>yaz-icu</refname>
25   <refpurpose>YAZ ICU utility</refpurpose>
26  </refnamediv>
27
28  <refsynopsisdiv>
29   <cmdsynopsis>
30    <command>yaz-icu</command>
31    <arg choice="opt" rep="repeat">commands</arg>
32    <arg>-c <replaceable>config</replaceable></arg>
33    <arg>-p <replaceable>opt</replaceable></arg>
34    <arg>-x</arg>
35   </cmdsynopsis>
36  </refsynopsisdiv>
37  
38  <refsect1><title>DESCRIPTION</title>
39   <para>
40    <command>yaz-icu</command> is utility which demonstrates 
41    the ICU chain module of yaz. (<filename>yaz/icu.h</filename>).
42   </para>
43  </refsect1>
44
45  <refsect1><title>OPTIONS</title>
46   <variablelist>
47    <varlistentry>
48     <term>-c <replaceable>config</replaceable></term>
49     <listitem><para>
50       Specifies the file containing ICU chain configuration
51       which is XML based.
52      </para></listitem>
53    </varlistentry>
54
55    <varlistentry>
56     <term>-p <replaceable>type</replaceable></term>
57     <listitem><para>
58       Specifies extra information to be printed about the ICU system.
59       If <replaceable>type</replaceable> is <literal>c</literal>
60       then ICU converters are printed. 
61       If <replaceable>type</replaceable> is <literal>l</literal>
62       available locates are printed.
63       If <replaceable>type</replaceable> is <literal>t</literal>
64       available transliterators are printed.
65      </para></listitem>
66    </varlistentry>
67
68    <varlistentry>
69     <term>-x <replaceable>config</replaceable></term>
70     <listitem><para>
71       Specifies that output should be XML based rather than
72       "text" based.
73      </para></listitem>
74    </varlistentry>
75
76   </variablelist>
77  </refsect1>
78  <refsect1><title>ICU chain configuration</title>
79   <para>
80    The ICU chain configuration speicifies one or more rules to convert
81    text data into tokens. The configuration format is XML based.
82   </para>
83   <para>
84    The toplevel element must be named <literal>icu_chain</literal>.
85    The <literal>icu_chain</literal> element has one required attribute
86    <literal>locale</literal> which specifies the ICU locale to be used
87    in the conversion steps.
88   </para>
89   <para>
90    The <literal>icu_chain</literal> element must include elements where
91    each element specifies a conversion step. The conversion is performed
92    in the order in which the conversion steps are specified.
93    Each conversion element takes one attribute: <literal>rule</literal>
94    which serves as argument to the conversion step.
95   </para>
96   <para>
97    The following conversion elements are available:
98    
99    <variablelist>
100     <varlistentry>
101      <term>casemap</term>
102      <listitem><para>
103        Converts case and rule specifies how:
104
105        <variablelist>
106         <varlistentry>
107          <term>l</term>
108          <listitem>
109           <para>Lowercase using ICU function u_strToLower. </para>
110          </listitem>
111         </varlistentry>
112
113         <varlistentry>
114          <term>u</term>
115          <listitem>
116           <para>Upper case using ICU function u_strToUpper.</para>
117          </listitem>
118         </varlistentry>
119         
120         <varlistentry>
121          <term>t</term>
122          <listitem>
123           <para>To title using UCU function u_strToTitle.</para>
124          </listitem>
125         </varlistentry>
126
127         <varlistentry>
128          <term>f</term>
129          <listitem>
130           <para>Fold case using ICU function u_strFoldCase.</para>
131          </listitem>
132         </varlistentry>
133         
134        </variablelist>
135       </para></listitem>
136     </varlistentry>
137
138     <varlistentry>
139      <term>display</term>
140      <listitem><para>
141        This is a meta step which specifies that a term/token is to
142        be displayed. This term is retrieved in an application
143        using function icu_chain_token_display (<filename>yaz/icu.h</filename>).
144       </para></listitem>
145     </varlistentry>
146     
147     <varlistentry>
148      <term>transform</term>
149      <listitem><para>
150        Specifies an ICU transform rule. The rule attribute is the
151        custom transformation rule to be used. This is a text based format
152        which is offered by the ICU transform system. See
153        <ulink url="&url.icu.transform;">ICU Transforms</ulink> for
154        more information.
155       </para></listitem>
156     </varlistentry>
157     
158     <varlistentry>
159      <term>tokenize</term>
160      <listitem><para>
161        Breaks / tokenizes a string into components using
162        ICU functions ubrk_open, ubrk_setText, .. . The rule is
163        one of:
164        <variablelist>
165         <varlistentry>
166          <term>l</term>
167          <listitem>
168           <para>Line. ICU: UBRK_LINE.</para>
169          </listitem>
170         </varlistentry>
171
172         <varlistentry>
173          <term>s</term>
174          <listitem>
175           <para>Sentence. ICU: UBRK_SENTENCE.</para>
176          </listitem>
177         </varlistentry>
178         
179         <varlistentry>
180          <term>w</term>
181          <listitem>
182           <para>Word. ICU: UBRK_WORD.</para>
183          </listitem>
184         </varlistentry>
185
186         <varlistentry>
187          <term>c</term>
188          <listitem>
189           <para>Character. ICU: UBRK_CHARACTER.</para>
190          </listitem>
191         </varlistentry>
192
193         <varlistentry>
194          <term>t</term>
195          <listitem>
196           <para>Title. ICU: UBRK_TITLE.</para>
197          </listitem>
198         </varlistentry>
199
200        </variablelist>
201       </para></listitem>
202     </varlistentry>
203     
204    </variablelist>
205    
206   </para>
207  </refsect1>
208  <refsect1><title>EXAMPLES</title>
209   <para>
210    The following command analyzes text in file <filename>text</filename>
211    using ICU chain configuration <filename>chain.xml</filename>:
212    <screen>
213     cat text | yaz-icu -c chain.xml
214    </screen>
215    The chain.xml might look as follows:
216     <screen><![CDATA[
217 <icu_chain locale="en">
218   <transform rule="[:Control:] Any-Remove"/>
219   <tokenize rule="w"/>
220   <transform rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
221   <display/>
222   <casemap rule="l"/>
223 </icu_chain>
224 ]]>
225    </screen>
226   </para>
227  </refsect1>
228  <refsect1><title>SEE ALSO</title>
229   <para>
230    <citerefentry>
231     <refentrytitle>yaz</refentrytitle>
232     <manvolnum>7</manvolnum>
233    </citerefentry>
234   </para>
235   <para>
236    <ulink url="&url.icu;">ICU Home</ulink>
237   </para>
238   <para>
239    <ulink url="&url.icu.transform;">ICU Transforms</ulink>
240   </para>
241  </refsect1>
242 </refentry>
243
244 <!-- Keep this comment at the end of the file
245 Local variables:
246 mode: sgml
247 sgml-omittag:t
248 sgml-shorttag:t
249 sgml-minimize-attributes:nil
250 sgml-always-quote-attributes:t
251 sgml-indent-step:1
252 sgml-indent-data:t
253 sgml-parent-document:nil
254 sgml-local-catalogs: nil
255 sgml-namecase-general:t
256 End:
257 -->