"/usr/share/xml/schema/dtd/4.3/docbookx.dtd" [

TO DO</xi:fallback>'> 

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

&fb;;</xi:include>' >

' >

' >

' >

  ]>

<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>

        <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>

        A debian package is available in the official Debian archive (release "unstable",

        "main" 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 "functional" use. 

      </para>

      <para>

        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>

        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>

        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>

        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>

      <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>

      <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 

                  "%"-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?).

          <title>Characteristics of ocaml-gettext implementation.</title>

          <tgroup cols="3">

              <row>

                <entry>Implementation</entry>

                <entry>Characteristics</entry>

                <entry>Use</entry>

              </row>

              <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. To support a language, the corresponding

                        locales need to be generated.

                      </para>

                    </listitem>

                  </itemizedlist>

                </entry>

              </row>

              <row>

                <entry>GettextStub.Preload</entry>