<?xml version="1.0" encoding="ISO-8859-1"?>
<!--**********************************************************************-->
<!-- ocaml-gettext: a library to translate messages                       -->
<!--                                                                      -->
<!-- Copyright (C) 2003-2008 Sylvain Le Gall <sylvain@le-gall.net>        -->
<!--                                                                      -->
<!-- This library is free software; you can redistribute it and/or        -->
<!-- modify it under the terms of the GNU Lesser General Public           -->
<!-- License as published by the Free Software Foundation; either         -->
<!-- version 2.1 of the License, or (at your option) any later version;   -->
<!-- with the OCaml static compilation exception.                         -->
<!--                                                                      -->
<!-- This library is distributed in the hope that it will be useful,      -->
<!-- but WITHOUT ANY WARRANTY; without even the implied warranty of       -->
<!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU    -->
<!-- Lesser General Public License for more details.                      -->
<!--                                                                      -->
<!-- You should have received a copy of the GNU Lesser General Public     -->
<!-- License along with this library; if not, write to the Free Software  -->
<!-- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  -->
<!-- USA                                                                  -->
<!--**********************************************************************-->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
"/usr/share/xml/schema/dtd/4.3/docbookx.dtd" [
<!-- Source code -->
<!ENTITY expl                          '../examples'>
<!ENTITY xi                            'http://www.w3.org/2001/XInclude'>
<!ENTITY fbk                           '<xi:fallback xmlns:xi="&xi;">TO DO</xi:fallback>'> 
<!ENTITY po-makefile                   '<xi:include href="&expl;/po/Makefile"                parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY LINGUAS                       '<xi:include href="&expl;/po/LINGUAS"                 parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY POTFILES                      '<xi:include href="&expl;/po/POTFILES"                parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY makefile                      '<xi:include href="&expl;/program/Makefile"           parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY library-ml                    '<xi:include href="&expl;/library/library.ml"         parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY library-gettext-ml            '<xi:include href="&expl;/library/libraryGettext.ml"  parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY program-ml                    '<xi:include href="&expl;/program/program.ml"         parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY program-gettext-ml            '<xi:include href="&expl;/program/programGettext.ml"  parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY program-xml                   '<xi:include href="&expl;/doc/program.xml"            parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY makefile-doc                  '<xi:include href="&expl;/doc/Makefile"               parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY gui-glade                     '<xi:include href="&expl;/gui/gui.glade"              parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY gui-ml                        '<xi:include href="&expl;/gui/gui.ml"                 parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY makefile-gui                  '<xi:include href="&expl;/gui/Makefile"               parse="text" xmlns:xi="&xi;">&fbk;</xi:include>' >
<!ENTITY ocaml-gettext-manual          '<xi:include href="ocaml-gettext.xml"         xmlns:xi="&xi;" xpointer="xpointer(/refentry/node())"/>' >
<!ENTITY ocaml-xgettext-manual         '<xi:include href="ocaml-xgettext.xml"        xmlns:xi="&xi;" xpointer="xpointer(/refentry/node())"/>' >
<!ENTITY ocaml-gettext-options-manual  '<xi:include href="ocaml-gettext-options.xml" xmlns:xi="&xi;" xpointer="xpointer(/refentry/node())"/>' >

<!-- Links -->
<!ENTITY download-ocaml             'http://caml.inria.fr/ocaml/release.en.html'>
<!ENTITY site-ocaml                 'http://caml.inria.fr/'>
<!ENTITY download-gettext           'http://www.gnu.org/software/gettext/gettext.html#TOCdownloading'>
<!ENTITY site-gettext               'http://www.gnu.org/software/gettext/gettext.html'>
<!ENTITY site-documentation-gettext 'http://www.gnu.org/software/gettext/manual/gettext.html'>
<!ENTITY download-camomile          'http://prdownloads.sourceforge.net/camomile/'>
<!ENTITY site-camomile              'http://camomile.sourceforge.net/'>
<!ENTITY download-ocaml-fileutils   'http://www.gallu.homelinux.org/download/'>
<!ENTITY site-ocaml-fileutils       'http://www.gallu.homelinux.org/ocaml-fileutils.html'>
<!ENTITY download-ounit             'http://www.xs4all.nl/~mmzeeman/ocaml/'>
<!ENTITY site-ounit                 'http://www.xs4all.nl/~mmzeeman/ocaml/'>
<!ENTITY download-ocaml-benchmark   'http://sourceforge.net/project/showfiles.php?group_id=117069'>
<!ENTITY site-ocaml-benchmark       'http://ocaml-benchmark.sourceforge.net/'>
<!ENTITY download-docbook           'http://prdownloads.sourceforge.net/docbook/'>
<!ENTITY site-docbook               'http://docbook.sourceforge.net/'>
<!ENTITY download-xsltproc          'http://xmlsoft.org/XSLT/downloads.html'>
<!ENTITY download-findlib           'http://www.ocaml-programming.de/packages/'>
<!ENTITY site-gtranslator           'http://gtranslator.sourceforge.net/'>
<!ENTITY site-kbabel                'http://i18n.kde.org/tools/kbabel/'>
<!ENTITY download-fop               'http://www.apache.org/dyn/closer.cgi/xml/fop'>
  ]>
<book>
  <title>ocaml-gettext reference manual</title>
  <bookinfo>
    <legalnotice>
      <para>
        This user manual is considered as a source code and is licensed under the GNU Lesser General Public 
        License v2.1 with OCaml static compilation exception.
      </para>
    </legalnotice>
    <author>
      <firstname>Sylvain</firstname>
      <surname>Le Gall</surname>
    </author>
    <copyright>
      <year>2005</year>
      <holder>Sylvain Le Gall</holder>
    </copyright>
    <revhistory>
      <revision>
        <!-- BUG: to complete wiht the right tags -->
        <revnumber>svn:revision</revnumber>
        <date>svn:date</date>
      </revision>
    </revhistory>
  </bookinfo>
  <chapter>
    <title>Overview</title>
    <section>
      <title>What is ocaml-gettext ?</title>
      <para>
        ocaml-gettext is a library to support string translation in OCaml. It provides a simple interface 
        to help programmers and translators to create programs that can support different languages. This
        allows the internationalisation of programs.
      </para>
      <para>
        ocaml-gettext provides two main functionalities: 
        <itemizedlist>
          <listitem>
            <para>
              translate English strings into localised strings ( depending on which gettext data are installed ),
            </para>
          </listitem>
          <listitem>
            <para>
              convert charset from the one used by the translator into the charset of the user.
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>The library is build according three points of view:
        <itemizedlist>
          <listitem>
            <para>
              for the programmer: this library provides functions that can be used in OCaml,
            </para>
          </listitem>
          <listitem>
            <para>
              for the translator: this library provides a standard file format ( PO file ) to help the translator,
            </para>
          </listitem>
          <listitem>
            <para>
              for the user: this library provides a set of command line options to set the language 
              and the charset.
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        ocaml-gettext was initially only a wrapper of gettext. It comes with a patch against the source of
        xgettext to add support of the OCaml language. As i already used this approach, 
        i was convinced that this library should be better integrated by using more advanced features of 
        OCaml ( such as <command>camlp4</command> ). 
      </para>
      <para>
        As a result of porting gettext to ocaml-gettext, we have :
        <itemizedlist>
          <listitem>
            <para>
              a library that can understood the native format of gettext file ( MO file ),
            </para>
          </listitem>
          <listitem>
            <para>
              two implementations: a wrapper around gettext and a pure OCaml implementation using 
              camomile,
            </para>
          </listitem>
          <listitem>
            <para>
              <command>ocaml-gettext</command>: a command line tool to help you to extract, to merge and to install
              gettext data.
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </section>
    <section>
      <title>How is ocaml-gettext related to gettext ?</title>
      <para>
        ocaml-gettext is a close cousin of gettext. In fact, the API is based on gettext. Almost everything 
        in ocaml-gettext is compatible with gettext:
        <itemizedlist>
          <listitem>
            <para>functions provided in the API are very close to the gettext one,</para>
          </listitem>
          <listitem>
            <para>the library contains a binding of the gettext library,</para>
          </listitem>
          <listitem>
            <para>
              all the file used are gettext compatible: the library uses PO file for translator 
              and MO file for translation,
            </para>
          </listitem>
          <listitem>
            <para>
              the library tries to use the same initialisation sequence as gettext :
              it uses the same environment variable, tries to find MO files in the
              same places...
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        This documentation will not covered the point that are better explained in the 
        <link linkend="gettext-documentation">gettext documentation</link>. It is highly recommended 
        to read this documentation, before reading this manual. Most of the point that are explained there 
        are not explained again here. However, we have tried to be as precise as possible to enable 
        programming with ocaml-gettext without having the need to be a gettext expert.
      </para>
    </section>
  </chapter>
  <chapter>
    <title>How to install ocaml-gettext</title>
    <section>
      <title>Using source</title>
      <para>To compile ocaml-gettext, you need to install the following prerequisites :
        <itemizedlist>
          <listitem>
            <para>
              <ulink url="&download-ocaml;">OCaml</ulink> v3.10.1 or later,
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="&download-findlib;">findlib</ulink> v1.0.4 or later,
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="&download-ocaml-fileutils;">ocaml-fileutils</ulink> v0.3.0 or later,
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="&download-camomile;">camomile</ulink> v0.7.1 or later,
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="&download-gettext;">gettext</ulink> v0.14.3 or later,
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="&download-ounit;">OUnit</ulink> v1.0.1 or later
              <footnote id="build-test"><para>Only if you want to build unitary test tool</para></footnote>,
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="&download-ocaml-benchmark;">ocaml-benchmark</ulink> v0.6 or later 
              <footnote id="build-benchmark"><para>Only if you want to build benchmarking tool</para></footnote>,
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="&download-docbook;">Docbook DTD and stylesheets</ulink> v4.3
              <footnote id="build-doc"><para>Only if you want to build the documentation</para></footnote>,
            </para>
          </listitem>
           <listitem>
            <para>
              <ulink url="&download-xsltproc;">xsltproc</ulink> v1.1.12 or later,
              <footnoteref linkend="build-doc"/>,
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="&download-fop;">fop</ulink> v0.20.5 or later.
              <footnoteref linkend="build-doc"/>,
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Camomile and gettext are optional but you need at least one of them in order to be able to build 
        the command line tool <command>ocaml-gettext</command>. 
      </para>
      <para>
        After having build and install all prerequisites, extract the source
        code of ocaml-gettext to a directory. Go to the source directory and type :
        <itemizedlist>
          <listitem>
            <para>
              <command>./configure</command>
              <footnote>
                <para>
                  If needed, you can use <command>./configure <option>--help</option></command> 
                  to have a complete help on every option you can use to tweak the 
                  installation of ocaml-gettext. To enable documentation generation, use 
                  <option>--enable-doc</option>. To enable benchmark executable, use 
                  <option>--enable-bench</option>. To enable test executable, use 
                  <option>--enable-test</option>.
                </para>
              </footnote>
            </para>
          </listitem>
          <listitem>
            <para>
              <command>make</command>
            </para>
          </listitem>
          <listitem>
            <para>
              <command>make install</command>
            </para>
          </listitem>
          <listitem>
            <para>
              <command>cd test</command>
            </para>
          </listitem>
          <listitem>
            <para>
              <command>./test</command>
              <footnoteref linkend="build-test"/>
            </para>
          </listitem>
          <listitem>
            <para>
              <command>./benchmark</command>
              <footnoteref linkend="build-benchmark"/>
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Since ocaml-gettext is not yet a stable release, building the benchmark and the unitary test tools
        is important, especially for debugging purpose. If you encounter problems, you should first
        try to run this two commands. They will give you good hints on what causes the problem.
      </para>
      <note>
        <para>
          There is a <filename>patches</filename> directory in the source tree. This directory contains patches
          against different programs that should be compatible with ocaml-gettext. Please have a look to the
          <filename>README.patches</filename> of this directory, to know how to handle patching these programs.
        </para>
      </note>
    </section>
    <section>
      <title>Debian distribution</title>
      <para>
        <!-- Debian package -->
        A debian package is available in the official Debian archive ( release &quot;unstable&quot;,
        &quot;main&quot; section ). 
      </para>
      <para>
        To install it, use the command :
        <command>apt-get 
          <option>install</option> <varname>libgettext-ocaml-dev</varname>
        </command>.
      </para>
    </section>
    <section>
      <title>Other distributions</title>
      <para>
        There is no plan to release packages for other distributions. If you have any skill
        concerning the packaging of ocaml-gettext for any other distribution, please contact me.
      </para>
    </section>
  </chapter>
  <chapter>
    <title>Programming with ocaml-gettext</title>
    <section>
      <title>Overview</title>
      <para>
        The API of ocaml-gettext is really reduced. It is made on purpose. The design is heavily
        based on modules and functors. There is no real reason for this design, it was just 
        really useful at the time the code was written.
      </para>
      <para>
        The library supposes that all the <varname>textdomain</varname> that will be used during 
        translation, are declared before using it. It is a real constraint, but it enables more
        optimisation. Moreover, it allows having a more &quot;functional&quot; use. 
      </para>
      <para>
        <!-- Description of the parameter t -->
        First of all, a parameter <varname>t</varname> should be defined. This parameter holds 
        all the required value to initialise ocaml-gettext. In particular, it contains information 
        about :
        <itemizedlist>
          <listitem>
            <para>
              which textdomain will be used,
            </para>
          </listitem>
          <listitem>
            <para>
              which language will be used,
            </para>
          </listitem>
          <listitem>
            <para>
              how the error should be handle,
            </para>
          </listitem>
          <listitem>
            <para>
              which directory to search.
            </para>
          </listitem>
        </itemizedlist>
        This parameter is build and updated through internal functions. You don't have direct access
        to it.
      </para>
      <para>
        <!-- Description of the parameter t' -->
        The parameter <varname>t</varname> is not directly used for translation. It must be converted into
        a parameter <varname>t'</varname> which is a real function to access translation. The transformation
        from <varname>t</varname> to <varname>t'</varname> is handled through a function 
        <varname>realize</varname>. The parameter <varname>t'</varname> is used in low level translation.
      </para>
      <para>
        <!-- Description of the function realize -->
        All the work of the library is done in the function <varname>realize</varname>. This function is
        not provided in the base package. It is build out of real implementation of ocaml-gettext ( such as
        <varname>gettext-camomile</varname> or <varname>gettext-stub</varname> ). This function could handle
        all the parameters in different ways. Concerning <varname>gettext-camomile</varname>, it builds a 
        translation table for all the files found which correspond to a declared <varname>textdomain</varname>.
      </para>
      <para>
        <!-- Justification of the global variable -->
        Since it should be very difficult to pass a parameter <varname>t</varname> or <varname>t'</varname> in 
        all functions that should use translation, we provide a more simple way to use the library. The 
        top level functions use a global reference to store the parameters <varname>t</varname> and 
        <varname>t'</varname>. This helps to integrate ocaml-gettext more easily into existing application.
      </para>
    </section>
    <section>
      <title>Makefile and source layout</title>
      <!-- PO -->
      <para>
        The source layout should conform to the one described in 
        <link linkend="gettext-documentation">gettext documentation</link>. In particular, it should 
        contain a <filename>po</filename> directory. There should be in this directory : 
        <itemizedlist>
          <listitem>
            <para>
              a file <filename>LINGUAS</filename> describing available translations,
            </para>
          </listitem>
          <listitem>
            <para>
              a file <filename>POTFILES</filename> containing the listing of all files that
              contain translatable strings,
            </para>
          </listitem>
          <listitem>
            <para>
              a <filename>Makefile</filename> to build the whole thing,
            </para>
          </listitem>
          <listitem>
            <para>
              a set of PO file which contains translated strings for different languages.
            </para>
          </listitem>
        </itemizedlist>
        During the build, the <filename>Makefile</filename> should generate a file 
        <filename>your-domain.pot</filename> that contains a template PO file that can be used
        by translator.
      </para>
      <example>
        <title><filename>Makefile</filename> for <filename>po</filename></title>
        <programlisting>&po-makefile;</programlisting>
      </example>
      <example>
        <title><filename>LINGUAS</filename></title>
        <programlisting>&LINGUAS;</programlisting>
      </example>
      <example>
        <title><filename>POTFILES</filename></title>
        <programlisting>&POTFILES;</programlisting>
      </example>
      <!-- Source -->
      <para>
        To build programs and libraries with ocaml-gettext, the preferred way is to use ocamlfind. 
        There are five findlib packages: 
        <itemizedlist>
          <listitem>
            <para>
              gettext.base: the base package of ocaml-gettext. It contains the top level type
              required to compile any library,
            </para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              gettext.extension
              <footnote id="advanced-features">
                <para>
                  This feature is described here for your information only. Since it belongs to 
                  low level implementation of ocaml-gettext, it should not be used.
                </para>
              </footnote>
              : a package used to extend ocaml-gettext. It is reserved for very
              particular functions ( such as creating a new <varname>realize</varname> function ),
            </para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              gettext.extract<footnoteref linkend="advanced-features"/>: a package that enables 
              to create special <command>camlp4</command> program ( such as 
              <command>ocaml-xgettext</command> ),
            </para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              gettext-stub: an implementation of ocaml-gettext using gettext,
            </para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              gettext-camomile: an implementation of ocaml-gettext using camomile. It is a pure
              ocaml implementation.
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        In order to link an application or a library using ocaml-gettext, you should link with one of : gettext.base,
        gettext-camomile or gettext-stub.
      </para>
      <example>
        <title><filename>Makefile</filename></title>
        <programlisting>&makefile;</programlisting>
      </example>
    </section>
    <section>
      <title>Library</title>
      <para>
        Library should use the module <varname>Gettext.Library</varname>. It doesn't need any real implementation 
        of ocaml-gettext. By this way, you can let the library user choose the most appropriate ocaml-gettext 
        implementation. This point is essential : a library could be used as well in a GUI program or in short run
        command line program. These two examples don't require the same kind of implementation at all: GUI program 
        loads most of their translated strings, command line program only use one among them. So by using the module
        <varname>Gettext.Library</varname> framework, you don't restrict programs to use one particular implementation 
        of ocaml-gettext.
      </para>
      <para>
        The library should define, using the functor <varname>Init</varname> provided: 
        <itemizedlist>
          <listitem>
            <para>
              his textdomain through the <varname>textdomain</varname> value,
            </para>
          </listitem>
          <listitem>
            <para>
              his dependencies through the <varname>dependencies</varname> value,
            </para>
          </listitem>
          <listitem>
            <para>
              if needed his charset and directory binding ( but it is not recommended to do so ).
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        After having instantiated the module <varname>Gettext.Library</varname> with the appropriate <varname>Init</varname>, 
        you should use the function provided : 
        <itemizedlist>
          <listitem>
            <para>
              <varname>s_</varname> : for translating singular strings,
            </para>
          </listitem>
          <listitem>
            <para>
              <varname>f_</varname> : for translating singular strings which will be used with <varname>Printf</varname> 
              function
              <footnote id="printf-strings">
                <para>
                  Strings which should be used by <varname>Printf</varname> function are checked to be sure
                  that the returned strings are equivalent to the provided English string. In particular, every 
                  &quot;%&quot;-symbol should be the same in the provided string and the returned string. If not,
                  it is the untranslated string which is returned.
                </para>
              </footnote>,
            </para>
          </listitem>
          <listitem>
            <para>
              <varname>sn_</varname> : for translating plural strings,
            </para>
          </listitem>
          <listitem>
            <para>
              <varname>fn_</varname> : for translating plural strings which will be used with <varname>Printf</varname>
              function<footnoteref linkend="printf-strings"/>,
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <warning>
        <para>
          You must keep the function name <varname>s_</varname>, <varname>f_</varname>, <varname>sn_</varname> and <varname>fn_</varname>.
          The extraction of translatable strings matches these names. If you don't keep it, the extraction of translatable strings
          will fail.
        </para>
      </warning>
      <example>
        <title><filename>library.ml</filename></title>
        <programlisting>&library-ml;</programlisting>
      </example>
      <example>
        <title><filename>libraryGettext.ml</filename></title>
        <programlisting>&library-gettext-ml;</programlisting>
      </example>
      <para>
        All the calls to translation functions, use the textdomain provided in <varname>Init</varname>.
      </para>
      <para>
        The only constraint when using ocaml-gettext in your library is to provide an access to the value 
        <varname>Gettext.Library.init</varname>. This value is used as dependencies for other libraries and
        programs that depend on it. For example, since you use the library ocaml-gettext, your primary dependency
        is the function <varname>init</varname> provided in the top level ( the function <varname>Gettext.string_of_exception</varname>
        is localised ).
      </para>
      <warning>
        <para>
          If you distribute your library, don't forget to mention that ocaml-gettext will only be able to translate
          the string defined in your library, if and only if the MO file build with is also installed. If not installed
          ocaml-gettext is useless.
        </para>
      </warning>
    </section>
    <section>
      <title>Program</title>
      <para>
        Program should use ocaml-gettext just as libraries do. The only difference lies in the fact that you should provide 
        a <varname>realize</varname> function in the <varname>InitProgram</varname>. The other difference is that the 
        <varname>init</varname> value is not a dependency that should be used by other program. It is a <varname>Arg</varname>
        usable value. It allows user to define some important parameters. 
      </para>
      <example>
        <title><filename>program.ml</filename></title>
        <programlisting>&program-ml;</programlisting>
      </example>
      <example>
        <title><filename>programGettext.ml</filename></title>
        <programlisting>&program-gettext-ml;</programlisting>
      </example>
      <example>
        <title>Output of <command>program <option>--help</option></command></title>
        <screen>
          <prompt>$></prompt><command>./program <option>--help</option></command>
          <computeroutput>
              --my-name name                      Your name. Default : ""
              --gettext-failsafe {ignore|inform-stderr|raise-exception}  
                                                  Choose how to handle failure in ocaml-gettext. Default: ignore.
              --gettext-disable                   Disable the translation perform by ocaml-gettext. Default: enable.
              --gettext-domain-dir textdomain dir Set a dir to search ocaml-gettext files for the specified domain. Default: [  ].
              --gettext-dir dir                   Add a search dir for ocaml-gettext files. Default: [ "/usr/share/locale"; 
                                                  "/usr/local/share/locale" ].
              --gettext-language language         Set the default language for ocaml-gettext. Default: (none).
              --gettext-codeset codeset           Set the default codeset for outputting string with ocaml-gettext. Default: ISO-8859-1.
              -help                               Display this list of options
              --help                              Display this list of options
          </computeroutput>
        </screen>
      </example>
      <para>
        If you want to include a manpage ( or info file ), that describes the command line option of ocaml-gettext, you should use the Docbook 
        XML fragment distributed with this application. Docbook should be enough generic to allow you to link it into your documentation. 
        If you don't want to link it with your documentation, you can refer to <link linkend="ocaml-gettext-options">
        ocaml-gettext-options manpage</link>.
      </para>
      <example>
        <title><filename>program.xml</filename> : Docbook manpage</title>
        <programlisting>&program-xml;</programlisting>
      </example>

      <example>
        <title><filename>Makefile</filename> : Makefile for docbook manpage</title>
        <programlisting>&makefile-doc;</programlisting>
      </example>

      <para>
        You should take care of what implementation of ocaml-gettext you are using. In order to choose the right implementation
        you should consider your program and every characteristic of it ( how many strings does it need to fetch ? Does it use already
        a C library that link with gettext ? ).
        <table>
          <title>Characteristics of ocaml-gettext implementation.</title>
          <tgroup cols="3">
            <thead>
              <row>
                <entry>Implementation</entry>
                <entry>Characteristics</entry>
                <entry>Use</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>GettextCamomile.Map</entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        Pure OCaml implementation,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Full load of all MO files before any translation,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Use OCaml standard <varname>Map</varname>.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        Pure OCaml program,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Program that requires to translate a lot of strings,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Threaded program ( since it use OCaml Map, it should be thread safe without
                        problem ).
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
              </row>
              <row>
                <entry>GettextCamomile.Hashtbl</entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        Pure OCaml implementation,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Full load of all MO file before any translation,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Use OCaml standard <varname>Hashtbl</varname>.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        Pure OCaml program,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Program that requires to translate a lot of strings,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Should work with threaded program, provided that the <varname>Hashtbl</varname> 
                        works in threaded environment.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
              </row>
              <row>
                <entry>GettextCamomile.Open</entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        Pure OCaml implementation,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Load strings from MO if needed,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Use OCaml standard <varname>Hashtbl</varname>,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Use a dichotomic search for the strings,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Compute MO file to open at initialisation,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Open a file when fetching string,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Doesn't memorise already translated strings,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Implementation design copied from gettext.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        Pure OCaml program,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Program that require to translate very few strings,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Should work with threaded program, provided that <varname>open_in</varname> function call
                        work.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
              </row>
              <row>
                <entry>GettextStub.Native</entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        Native gettext library,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Partial load of all MO file before any translation, use <varname>mmap</varname>.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        OCaml program that uses library compiled with gettext,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Should work with threaded program, provided that the <varname>gettext</varname> 
                        work in threaded environment.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
              </row>
              <row>
                <entry>GettextStub.Preload</entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        Native gettext library,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Forced load of all MO file before any translation, the preload is realized by trying to load
                        the string &quot;&quot; for all the textdomain defined.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
                <entry>
                  <itemizedlist>
                    <listitem>
                      <para>
                        OCaml program that uses library compiled with gettext,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Program that needs to translate a lot of strings,
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        Should work with threaded program, provided that the <varname>gettext</varname> 
                        work in threaded environment.
                      </para>
                    </listitem>
                  </itemizedlist>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </para>
    </section>
    <section>
      <title>Graphical user interface</title>
      <para>
        Graphical user interface works just as a program or a library. The only difference is that the file which contains
        the graphical user interface should not be written in OCaml. You have two cases :
        <itemizedlist>
          <listitem>
            <para>
              You use glade file, so you should extract the strings from this file using <command>xgettext</command>
            </para>
          </listitem>
          <listitem>
            <para>
              You use a hand written interface written in OCaml, the extraction of the strings follow the same way
              as a library.
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        You should use the first alternative : it is easier for a translator to extract strings, without having to compile
        your application ( it enables translators that don't know OCaml to help you ). In order to do so, you should use the native
        <command>xgettext</command> binary ( provided with gettext ). It should support the format of the translatable strings found
        in your GUI file ( for example, <command>xgettext</command> supports glade file ).
      </para>
      <para>
        But for now you can only use the second alternative, because OCaml is not yet supported in <command>xgettext</command>. This
        should be fixed, once <command>ocaml-gettext</command> will be enough stable to become a back-end for <command>xgettext</command>
        <footnote>
          <para>
            For now, extracting strings from OCaml source file and glade file, requires to patch <productname>gettext</productname>. 
            You can find this path in patches. This patch will be sent to upstream author once it will be considered enough stable.
          </para>
        </footnote>.
      </para>
      <para>
        In the two cases, you just have to add your GUI file ( in OCaml or native form ) to <filename>POTFILES</filename>.
      </para>
      <para>
        Graphical user interfaces are good candidates for settings a fixed <varname>Init.codeset</varname>. Typically, GTK2 interfaces require 
        to have these parameters set to UTF-8.
      </para>

      <example>
        <title><filename>gui.ml</filename></title>
        <programlisting>&gui-ml;</programlisting>
      </example>

      <example>
        <title><command>./program --gettext-dir ../build/share/locale --gettext-lang C --my-name Sylvain</command></title>
        <screenshot>
          <graphic fileref="gui.png" format="PNG"/>
        </screenshot>
      </example>

      <example>
        <title><command>./program --gettext-dir ../build/share/locale --gettext-lang fr --my-name Sylvain</command></title>
        <screenshot>
          <graphic fileref="gui-fr.png" format="PNG"/>
        </screenshot>
      </example>

      <warning>
        <para>
          If you build <productname>lablgtk</productname> application, you must keep in mind that some locale settings are made
          in the function <varname>GMain.Init</varname>. Those settings could override those done through the command line
          options. In order to correctly use ocaml-gettext, you must be sure to call <varname>GMain.Init</varname> before 
          using <varname>Arg.parse</varname> with the ocaml-gettext args.
        </para>
      </warning>

    </section>
  </chapter>
  <chapter>
    <title>Translating ocaml-gettext programs and libraries</title>
    <para>
      ocaml-gettext has been built around gettext. This allows translators to use exactly the same technics as they should
      use with gettext. All the documentation required for translating can be found in <link linkend="gettext-documentation">
      gettext documentation</link>.
    </para>
    <para>
      It is recommended to use GUI which allows easier translation such as : 
      <itemizedlist>
        <listitem>
          <para>
            <ulink url="&site-gtranslator;">gtranslator</ulink>,
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url="&site-kbabel;">kbabel</ulink>.
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </chapter>
  <chapter>
    <title>Using ocaml-gettext programs</title>
    <para>
      ocaml-gettext program can be used just as any OCaml program. The only difference with standard OCaml program is that
      they come with a bunch of command line options which are specific to OCaml program. In most cases, you just have to define
      a well suited <varname>LC_ALL</varname> or <varname>LANG</varname> environment variable. Since ocaml-gettext is compatible
      with gettext, if your environment variable works with gettext, it should also works with ocaml-gettext.
    </para>
    <para>
      You can find more details in the <link linkend="gettext-documentation">gettext documentation</link> or in the <link 
      linkend="ocaml-gettext-options">ocaml-gettext-options manpage</link>.
    </para>
  </chapter>
  <appendix>
    <title>Tips and tricks</title>

    <section>
      <title>Adding gettext support without depending on ocaml-gettext</title>

      <para>
        You want to 'gettextify' your program, adding 's_' and 'f_'
        annotations throughout. However now your program has an additional
        dependency, ocaml-gettext. You can make ocaml-gettext optional by
        creating a set of dummy functions which do nothing:
      </para>

      <example>
        <title><filename>prog_gettext.ml</filename></title>
        <programlisting>
          (* This file is generated automatically by ./configure. *)
          module Gettext = 
          struct
            external s_ : string -> string = "%identity"
            external f_ : ('a -> 'b, 'c, 'd) format -> ('a -> 'b, 'c, 'd) format = "%identity"
            
            let sn_ : string -> string -> int -> string = 
              fun s p n -> 
                if n = 1 then s else p
                
            let fn_ : ('a -> 'b, 'c, 'd) format -> ('a -> 'b, 'c, 'd) format -> int -> ('a -> 'b, 'c, 'd) format = 
              fun s p n -> 
                if n = 1 then s else p
          end
        </programlisting>
      </example>

      <para>
        You have to arrange for your configure script to place the above
        content or the real ProgramGettext module into 'prog_gettext.ml',
        depending on whether it detects that ocaml-gettext is installed
        (eg. using 'ocamlfind query gettext' or some other method).
      </para>
    </section>
  </appendix>
  <appendix>
    <title>Links</title>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="&site-ocaml;">OCaml website</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="&site-gettext;">Gettext website</ulink>
        </para>
      </listitem>
      <listitem id="gettext-documentation">
        <para>
          <ulink url="&site-documentation-gettext;">Gettext documentation</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="&site-camomile;">Camomile website</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="&site-ocaml-fileutils;">ocaml-fileutils website</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="&site-ounit;">OUnit website</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="&site-ocaml-benchmark;">ocaml-benchmark website</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="&site-docbook;">Docbook website</ulink>
        </para>
      </listitem>
    </itemizedlist>
  </appendix>
  <appendix>
    <title>Manpages</title>
    <refentry>
      &ocaml-gettext-manual;
    </refentry>
    <refentry>
      &ocaml-xgettext-manual;
    </refentry>
    <refentry id="ocaml-gettext-options">
      &ocaml-gettext-options-manual;
    </refentry>
  </appendix>
</book>