<sect1 id="manuals-texinfo-l10n">
<title>Texinfo Document Localization</title>
<para>
The localization of documentation manuals produced through
texinfo documentation backend takes place by creating one
documentation manual for each language individually. These
manuals don't have a direct relation among themselves except
that one adopted by people writting them in order to keep
their content syncronized. In this configuration translators
take one documentation manual as reference and produce
translated versions of it. To keep track of changes, the
underlaying version control system must be used.
</para>
<para>
Notice that <application>gettext</application><footnote>
<para>
The <application>gettext</application> program translates
a natural language message into the user's language, by
looking up the translation in a message catalog. For more
information about the <application>gettext</application>
program, run <command>info gettext</command>.
</para>
</footnote> procedures cannot be applied to texinfo source
files. A possible work around would be to convert each
documentation manual from texinfo format to XML format and
then apply <application>gettext</application> procedures on it
through <command>xml2po</command> command. This would produce
a translated XML file which can be used to convert back the
documentation manual to texinfo format so it can be exported
to convenctional output formats. Even though it is possible to
convert texinfo source files into XML, the DTD and XSLT files
required to realize both markup validation and transnformation
back into texinfo format (or possibly other formats) are not
available inside &TCD; release 5.5.
</para>
<sect2 id="manuals-texinfo-l10n-language">
<title>Texinfo Document Language</title>
<para>
The language information of documentation manuals produced
through texinfo documentation backend is declared by texinfo's
<code>@documentlanguage</code> command and can take any
language code from ISO-639 as argument. This command is set in
the manual's main definition file and, generally, there is no
need to change it unless you mistakently create the manual for
a locale code different to that one you previously pretended
to do in first place.
</para>
<para>
The user's session locale information, as set in
<envar>LANG</envar> environment variable, determines the
language information used by new documentation manuals created
through the <function>help</function> functionality of
<command>centos-art.sh</command> script and its XHTML output
produced from <command>texi2html</command> command. The
user's session locale information can be customized in the
graphical login screen before login, or once you've login by
explicitly setting the value of <envar>LANG</envar>
environment variable inside the
<filename>~/.bash_profile</filename> file.
</para>
<tip>
<para>
To create documentation manuals in English language the
<envar>LANG</envar> environment variable must be set to
<code>en_US.UTF-8</code> or something similar. Likewise, if
you want to create documentation manuals in a language other
than English, be sure the <envar>LANG</envar> environment
variable is set to the appropriate locale code, based on the
output of <command>locale -a | less</command> command.
</para>
</tip>
<para>
When producing output from texinfo source files, the language
information set by <code>@documentlanguage</code> texinfo
command is ignored in Info and HTML output produced by
<command>makeinfo</command> command in the
<package>texinfo-4.8-14.el5</package> package, but cosidered
by Tex program to redefine various English words used in the
output (e.g., <quote>Chapter</quote>, <quote>Index</quote>,
<quote>See</quote>, and so on) based on the current language
set in.
</para>
</sect2>
<sect2 id="manuals-texinfo-l10n-encoding">
<title>Texinfo Document Encoding</title>
<para>
The encoding information of documentation manuals produced
trhough texinfo documentation backend is declared by texinfo's
<code>documentlanguage</code> command and can take
<code>US-ASCII</code>, <code>ISO-8859-1</code>,
<code>ISO-8859-15</code> or <code>ISO-8859-2</code> as
argument. Nevertheless, the encoding information inside
documentation manuals produced through texinfo documentation
backend is not declared at all when documentation manuals are
created for first time in order for documents to be written
and read in terminals with an UTF-8 encoding set in (as it is
in &TCD;).
</para>
<para>
When the <code>@documentencoding</code> command is set in
texinfo source files, the terminal encoding you use to read
the Info output must be set to that encoding you provided as
argument for <code>@documentencoding</code> before using an
Info reader to open the Info output file. Otherwise, when
terminal and texinfo source files encoding definition differs
one another, characters defined through texinfo's special way
of producing floating accents won't be displayed as expected
(even when the <option>--enable-encoding</option> is
provided to <command>makeinfo</command> command). On the
other hand, when the <code>@documentencoding</code> command is
not set in texinfo source files, it is possible to write
documentation manuals in a UTF-8 encoding terminal and also
reading localized Info output, as well. There is no need to
use texinfo's special way of producing floating accents since
the terminal encoding is able to interpret the characters
initially entered when the texinfo source files were written
in first place.
</para>
<para>
When texinfo's special way of producing floating accents isn't
used, HTML entities are not produced in XHTML output produced
by <command>texi2html</command> command and some accents
aren't well produced by <command>makeinfo</command> when PDF
output is produced, either. In this last case, when producing
PDF output, you can realize what the floating accents are by
trying to produce an accentuated Spanish <code>i</code> letter
(e.g., <code>í</code>). When you do so, you'll note that that
construction puts the accentuation <emphasis>over</emphasis>
the <code>i</code> letter's dot, instead of removing the
<code>i</code> letter's dot and placing the accent in its
place. In the case of XHTML output, however, it possible to
produce well localized XHTML output by setting
</para>
<screen><meta http-equiv="content-type" content="text/html; charset=UTF-8" /></screen>
<para>
on the head section of each XHTML output permits to all web
browsers supporting UTF-8 encoding to display the character
information correctly when reading it.
</para>
<para>
Based on these contradictions it was decided not to set the
@documentencoding command to texinfo source files produced by
the help functionality of centos-art.sh script. This desition
restricts texinfo documentation backend from producing well
localized PDF outputs from texinfo source files but permits it
to produce well localized Info, Text, and XHTML output that
can be read on UTF-8 ecoding terminals
</para>
</sect2>
</sect1>