'\" t
.\"     Title: OCAML-GETTEXT
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 2008-04-29
.\"    Manual: [FIXME: manual]
.\"    Source: ocaml-gettext
.\"  Language: English
.\"
.TH "OCAML\-GETTEXT" "1" "2008\-04\-29" "ocaml-gettext" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ocaml-gettext \- program to manage PO and MO files for OCaml source files\&.
.SH "SYNOPSIS"
.HP \w'\fBocaml\-gettext\fR\ 'u
\fBocaml\-gettext\fR \-\-action\ 
.br
[extract\ |\ compile\ |\ install\ |\ uninstall\ |\ merge]
.br
[\-\-extract\-command\ {\fIcmd\fR}]
.br
[\-\-extract\-default\-option\ {\fIoptions\fR}]
.br
[\-\-extract\-filename\-option\ {\fIfilename\fR}\ {\fIoptions\fR}]
.br
[\-\-extract\-pot\ {\fIfilename\fR}]
.br
[\-\-compile\-output\ {\fIfilename\fR}]
.br
[\-\-install\-language\ {\fIlanguage\fR}]
.br
[\-\-install\-category\ {\fIcategory\fR}]
.br
[\-\-install\-textdomain\ {\fItextdomain\fR}]
.br
[\-\-install\-destdir\ {\fIdirname\fR}]
.br
[\-\-uninstall\-language\ {\fIlanguage\fR}]
.br
[\-\-uninstall\-category\ {\fIcategory\fR}]
.br
[\-\-uninstall\-textdomain\ {\fItextdomain\fR}]
.br
[\-\-uninstall\-orgdir\ {\fIdirname\fR}]
.br
{\-\-merge\-pot\ {\fIfilename\fR}}
.br
[\-\-merge\-backup\-extension\ {\fIextension\fR}]
.br
[\-\-gettext\-failsafe\ 
.br
[{ignore}\ |\ {inform\-stderr}\ |\ {raise\-exception}]]
.br
[\-\-gettext\-disable] [\-\-gettext\-domain\-dir\ {\fItextdomain\fR}\ {\fIdir\fR}]
.br
[\-\-gettext\-dir\ {\fIdir\fR}]
.br
[\-\-gettext\-language\ {\fIlanguage\fR}]
.br
[\-\-gettext\-codeset\ {\fIcodeset\fR}]
.br
[\-\-version | \-\-short\-version | \-help | \-\-help]
.br
[file...]
.SH "DESCRIPTION"
.PP
This manual page documents briefly the
\fBocaml\-gettext\fR
command\&.
.PP
\fB\-\-action \fR\fB\fIextract\fR\fR
.RS 4
Files provided are considered to be OCaml source files and
\fBocaml\-gettext\fR
tries to extract translatable strings of it\&. The output of the command is a POT file\&. As a special case, if a file named
POTFILES
is in the list of the file provided, every line of it is considered as a file to be searched\&.
.RE
.PP
\fB\-\-action \fR\fB\fIcompile\fR\fR
.RS 4
Files provided are considered to be PO file\&. These files are compiled in binary MO files,
.RE
.PP
\fB\-\-action \fR\fB\fIinstall\fR\fR
.RS 4
Files provided are considered to be MO files\&. They are installed in their respective directories considering language, textdomain and category,
.RE
.PP
\fB\-\-action \fR\fB\fIuninstall\fR\fR
.RS 4
This is the symmetric command to
\fBinstall\fR, but it uninstalls files provided for the considered language, textdomain and category,
.RE
.PP
\fB\-\-action \fR\fB\fImerge\fR\fR
.RS 4
Merges a POT file with the provided PO file\&.
.RE
.PP
\fB\-\-extract\-command \fR\fB\fIcmd\fR\fR
.RS 4
Command to extract translatable strings from an OCaml source file\&. This command should output the same marshalled structure as
\fBocaml\-xgettext\fR\&. The best to do is to use the same build version of
\fBocaml\-gettext\fR\&.
.RE
.PP
\fB\-\-extract\-default\-option \fR\fB\fIoptions\fR\fR
.RS 4
Default options used when extracting translatable strings\&. These options are
\fBcamlp4\fR
options and will be passed to
\fBocaml\-xgettext\fR
when processing files that don\*(Aqt already have specific
\fBcamlp4\fR
options\&.
.RE
.PP
\fB\-\-extract\-filename\-option \fR\fB\fIfilename\fR\fR\fB \fR\fB\fIoptions\fR\fR
.RS 4
Specific filename
\fBcamlp4\fR
options\&. It is used when extracting strings from the specified filename\&. It overrides default
\fBcamlp4\fR
options\&.
.RE
.PP
\fB\-\-extract\-pot \fR\fB\fIfilename\fR\fR
.RS 4
POT file to write when extracting translatable strings\&.
.RE
.PP
\fB\-\-compile\-output \fR\fB\fIfilename\fR\fR
.RS 4
MO file to write when compiling a PO file\&. If not provided, the output will be the name of the PO file with "\&.mo" extension\&.
.RE
.PP
\fB\-\-install\-language \fR\fB\fIlanguage\fR\fR
.RS 4
Language to use when installing a MO file\&.
.RE
.PP
\fB\-\-install\-category \fR\fB\fIcategory\fR\fR
.RS 4
Category to use when installing a MO file\&.
.RE
.PP
\fB\-\-install\-textdomain \fR\fB\fItextdomain\fR\fR
.RS 4
Textdomain to use when installing a MO file\&.
.RE
.PP
\fB\-\-install\-destdir \fR\fB\fIdirname\fR\fR
.RS 4
Base directory to use when installing a MO file\&.
.RE
.PP
\fB\-\-uninstall\-language \fR\fB\fIlanguage\fR\fR
.RS 4
Language to use when uninstalling a MO file\&.
.RE
.PP
\fB\-\-uninstall\-category \fR\fB\fIcategory\fR\fR
.RS 4
Category to use when uninstalling a MO file\&.
.RE
.PP
\fB\-\-uninstall\-textdomain \fR\fB\fItextdomain\fR\fR
.RS 4
Textdomain to use when uninstalling a MO file\&.
.RE
.PP
\fB\-\-uninstall\-orgdir \fR\fB\fIdirname\fR\fR
.RS 4
Base directory used when uninstalling a MO file\&.
.RE
.PP
\fB\-\-merge\-pot \fR\fB\fIfilename\fR\fR
.RS 4
POT file to use as a master for merging PO file\&.
.RE
.PP
\fB\-\-merge\-backup\-extension \fR\fB\fIextension\fR\fR
.RS 4
Backup extension to use when moving PO file which have been merged\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Return version information on ocaml\-gettext\&.
.RE
.PP
\fB\-\-short\-version\fR
.RS 4
Returns only the version of ocaml\-gettext\&. The return is made to be easily parseable by
\fBconfigure\fR
script\&. The output of this command will always be the shortest version string, made of numeric characters (0\-9) and "\&."\&. The version strings should be compared considering that a version A is greater than a version B if there is a number between two "\&." of A that is greater than B the corresponding number, beginning at the right of the string\&. For example: 0\&.14 is greater than 0\&.13\&.1\&.
.RE
.PP
\fB\-help\fR, \fB\-\-help\fR
.RS 4
Displays the help about the
\fBocaml\-gettext\fR
command\&.
.RE
.SH "OCAML-GETTEXT OPTIONS"
.PP
This section describes briefly the common options provided by programs using ocaml\-gettext library\&.
.PP
\fB\-\-gettext\-failsafe ignore\fR
.RS 4
Defines the behaviour of ocaml\-gettext regarding any error that could be encountered during the processing of string translation\&.
\fBignore\fR
is the default behaviour\&. The string returned is the original string untranslated\&. This behaviour is consistent and allows to have a usable output, even if it is not perfect\&.
.RE
.PP
\fB\-\-gettext\-failsafe inform\-stderr\fR
.RS 4
Same behaviour as
\fBignore\fR, except that a message is printed on stderr,
.RE
.PP
\fB\-\-gettext\-failsafe raise\-exception\fR
.RS 4
Stops the program by raising an exception when an error is encountered\&.
.RE
.PP
\fB\-\-gettext\-disable\fR
.RS 4
Disables any translation made by ocaml\-gettext\&. All translations return the original string untranslated\&.
.RE
.PP
\fB\-\-gettext\-domain\-dir \fR\fB\fItextdomain\fR\fR\fB \fR\fB\fIdir\fR\fR\fB \fR
.RS 4
Defines a dir to search for a specific domain\&. This could be useful if MO files are stored in a non standard directory\&.
.RE
.PP
\fB\-\-gettext\-dir \fR\fB\fIdir\fR\fR
.RS 4
Adds a directory to search for MO files\&.
.RE
.PP
\fB\-\-gettext\-language \fR\fB\fIlanguage\fR\fR
.RS 4
Sets the language to use in ocaml\-gettext library\&. The language should be POSIX compliant\&. The language should follow the following convention: lang[_territory][\&.charset][@modifier]\&. The lang and territory should be two letters ISO code\&. Charset should be a valid ISO character set (at least recognised by the underlying charset recoding routine)\&. For example, valid languages are: fr_FR\&.ISO\-8859\-1@euro, de_DE\&.UTF\-8\&.
.RE
.PP
\fB\-\-gettext\-codeset \fR\fB\fIcodeset\fR\fR
.RS 4
Sets the codeset for output\&.
.RE
.PP
Users should be aware that these command line options, apply only for strings after the initialisation of the library\&. This means that if the options initially guessed by ocaml\-gettext don\*(Aqt match the command line provided, there should be some untranslated string, because these strings are translated before parsing options\&. This is particularly true for the usage message itself (\fB\-\-help\fR): even if the strings are translated, they are translated before setting the correct option\&.
.PP
Some options (\fB\-\-gettext\-codeset\fR
for example) are overrided internally for particular use\&. It should be required to always translate strings to UTF\-8 in graphical user interface (because GTK2 requires it)\&.
.SH "NOTES"
.PP
Options
\fB\-\-uninstall\-language\fR,
\fB\-\-uninstall\-textdomain\fR,
\fB\-\-install\-language\fR
and
\fB\-\-install\-textdomain\fR
could be guessed from the filename provided\&. You must be aware that these options can conflict with the fact that you provide several files to install\&. For example, if you provide a textdomain, you should either install several MO files which filenames only reflect the language or only one MO file if you also provide a language\&. For example, you can execute
\fBocaml\-gettext \fR\fB\fB\-\-install\-textdomain \fR\fB\fImytextdomain\fR\fR\fR\fB \fR\fB\fIfr\&.po\fR\fR\fB \fR\fB\fIde\&.po\fR\fR\fB \fR
without problem, but you cannot execute
\fBocaml\-gettext \fR\fB\fB\-\-install\-textdomain \fR\fB\fImytextdomain\fR\fR\fR\fB \fR\fB\fB\-\-install\-language \fR\fB\fIfr\fR\fR\fR\fB \fR\fB\fIfr\&.po\fR\fR\fB \fR\fB\fIde\&.po\fR\fR\fB \fR\&. This restriction is due to the fact that you should not over specified file installation\&.
.PP
Rules for guessing the language/textdomain are: language[\&.textdomain]\&.mo\&. For a full automated install without giving any hints, through command line options, you should name your file
fr\&.mytextdomain\&.mo
or
de\&.mytextdomain\&.mo\&.
.SH "SEE ALSO"
.PP
\fBocaml-xgettext\fR(1)
.PP
\fBocaml-gettext\fR(5)