<sect1 id="manuals-format-texinfo">
<title>Texinfo</title>
<para>
This section describes the implementation of Texinfo
documentation format inside the <xref
linkend="scripts-bash-help"/> functionality of
<command>centos-art.sh</command> script. In this section we
assume you have a basic understanding of Texinfo documentation
system. Otherwise, if you don't know what Texinfo
documentation system is, read the Texinfo manual first (e.g.,
by running the <command>info texinfo</command> command) and
then, come back here.
</para>
<sect2 id="manuals-formats-texinfo-structure">
<title>Document Structure</title>
<para>
The <xref linkend="scripts-bash-help"/> functionality of
<command>centos-art.sh</command> provides a document structure
that makes documentation manuals created through it to be
scalable and maintainable through time. This document
structure follows the idea of an upside-down tree to organize
chapters, sections, subsections and the like, as described in
<xref linkend="manuals-production-identifying-structure" />.
</para>
<para>
The <xref linkend="scripts-bash-help"/>
functionality creates documentation manuals source files in
the <filename
class="directory">trunk/Documentation/Models/Texinfo/</filename>
directory and saves output produced from them in the <filename
class="directory">trunk/Documentation/Manuals/Texinfo/</filename>
directory. To produce documentation manuals initial source
files, the <xref linkend="scripts-bash-help"/> functionality
uses Texinfo documentation templates, as described in <xref
linkend="manuals-formats-texinfo-templates" />.
</para>
<para>
Inside the documentation models directory, source files are
stored inside language-specific directories. The
language-specific directories are necessary to implement
internationalization of Texinfo source files, as described in
<xref linkend="manuals-formats-texinfo-l10n" />.
</para>
<para>
Inside the language-specific directory, the following files
exist to store the manual's main definitions (e.g., title,
subtitle, author, copyright notice, chapters, appendixes,
indexes and all similar stuff a documentation manual usually
has). In addition to these files, there is one directory for
each chapter created inside the manual. Inside each chapter
directory, you'll find the files controlling the section
definitions related each chapter they belong to. The section
files (a.k.a. <quote>documentation entries</quote>) are
suffixed with a <filename class="extension">texinfo</filename>
extension and named arbitrarily, as it is illustrated in <xref
linkend="manuals-formats-texinfo-structure-example1" />.
Inside section files it is where you write the manual's
content itself.
</para>
<example id="manuals-formats-texinfo-structure-example1">
<title>Texinfo document structure</title>
<screenshot>
<screeninfo>Texinfo document structure</screeninfo>
<mediaobject>
<textobject>
<programlisting>trunk/Manuals/${MANUAL_NAME}
`-- ${LANG}
|-- ${CHAPTER_NAME}
| |-- chapter-menu.texinfo
| |-- chapter-nodes.texinfo
| |-- chapter.texinfo
| `-- ${SECTION_NAME}.texinfo
|-- Licenses
| |-- chapter-menu.texinfo
| |-- chapter-nodes.texinfo
| `-- chapter.texinfo
|-- ${MANUAL_NAME}.conf
|-- ${MANUAL_NAME}-index.texinfo
|-- ${MANUAL_NAME}-menu.texinfo
|-- ${MANUAL_NAME}-nodes.texinfo
`-- ${MANUAL_NAME}.texinfo</programlisting>
</textobject>
</mediaobject>
</screenshot>
</example>
<para>
Texinfo (as in <package>texinfo-4.8-14.el5</package>) doesn't
support part sectioning inside documentation manuals, so
neither the <xref linkend="scripts-bash-help"/> functionality
does. Nevertheless, you can create several documentation
manuals and considered them as part of a bigger documentation
manual to workaround this issue.
</para>
<para>
In this document structure, the creation of documentation
manuals, chapters and sections is not limitted. You can create
as many documenation manuals, chapters and sections as you
need. The only limitation would be the amount of free space
required to store the Texinfo source files and the output
files produced from them in your workstation.
</para>
</sect2>
<sect2 id="manuals-formats-texinfo-templates">
<title>Document Templates</title>
<para>
Texinfo document templates provide the initial document
structure the <xref linkend="scripts-bash-help"/>
functionality needs in order to create and maintain document
structures, as described in <xref
linkend="manuals-formats-texinfo-structure" />.
</para>
<para>
Texinfo document templates are language-specific. This means
that there is (or, at least, must be) one Texinfo document
template for each language you plan to support documentation
manuals for. By default, &TCAR; provides a default Texinfo
document template under <filename class="directory">en_US</filename>
directory. This template structure is used when your current
locale is English language or when you are creating/editing a
documentation manual in a language other than English, but no
language-specific document template for that language exists
in the <filename
class="directory">trunk/Scripts/Documentation/Models/Texinfo/Default/</filename>
directory.
</para>
<para>
The <filename
class="directory">trunk/Scripts/Documentation/Models/Texinfo/Default/</filename>
directory organizes all Texinfo document templates using the
format LL_CC, where LL is the language code (as in ISO-639)
and CC the country code (as in ISO-3166). The directory
structure of Texinfo document templates is illustrated in the
<xref linkend="manuals-formats-texinfo-templates-example1" />
and implemented through the following files:
</para>
<variablelist>
<varlistentry>
<term><filename>manual.texinfo</filename></term>
<listitem>
<para>
This file can be found inside the language-specific directory
and contains the manual's main definitions (e.g., document
title, document language, document authors, copyright notice,
etc.).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>manual-menu.texinfo</filename></term>
<listitem>
<para>
This file can be found inside the language-specific directory
and contains the menu definitions of chapters inside the
manual. When <xref linkend="scripts-bash-help" />
functionality creates instances of this file, menu definitions
inside it are automatically updated when a new chapter is
created or deleted through the <xref
linkend="scripts-bash-help"/> functionality. Generally, you
don't need to edit instances of this file once the
documentation manual has been created.
</para>
<para>
When a documentation manual is created for first time, this
file is copied from Texinfo document template directory
structure to the documentation manual being currently created.
At this specific moment, the instance created contains the
following Texinfo menu definition:
</para>
<programlisting>
@menu
* Licenses::
* Index::
@end menu
</programlisting>
<para>
Later, when chapters are added to or deleted from the
documentation manual, the content of this file varies adding
or deleting menu entries accordingly. Nevertheless, the two
entries shown above are ignored when new chapters are added to
or removed from the list, so they will always be present in
instances of this file. To preserve the manual consistency,
the <xref linkend="scripts-bash-help"/> functionality prevents
you from deleting any of these chapters once the documentation
manual has been created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>manual-nodes.texinfo</filename></term>
<listitem>
<para>
This file can be found inside the language-specific directory
and contains the node definitions of all chapters inside the
manual. When <xref linkend="scripts-bash-help"/>
functionality creates instances of this file, node definitions
inside it are automatically created based on menu definitions
(see <filename>manual-menu.texinfo</filename> file above) and
they don't include any content here. Instead, as part of the
node definition, the <code>@include</code> command is used to
connect each node with its content. Generally, you don't need
to edit instances of this file once the documentation manual
has been created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>manual-index.texinfo</filename></term>
<listitem>
<para>
This file can be found inside the language-specific directory
and contains the Texinfo commands used to generated an
organized view of all indexes you defined inside documentation
entries so they can be quickly accessed. Generally, you don't
need to edit instnaces of this file once the documentation
manual has been created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>manual.conf</filename></term>
<listitem>
<para>
This file contains the initial configuration of documentation
manuals written in Texinfo format. When a documentation manual
is created for first time, this file is copied into its target
directory so you be able to customize specific information
like menu order, title styles and template assignments
therein. The content of this file is described in <xref
linkend="manuals-formats-texinfo-configuration" />.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>chapter.texinfo</filename></term>
<listitem>
<para>
This file contains Texinfo's main chapter definition used
by <xref linkend="scripts-bash-help"/> functionality when new
chapters are created inside documentation manuals. When
chapters are created for first time, they come without any
introduction or documentation entry inside.
</para>
<para>
In case you need to add/update the chapters definition files,
edit the related chapter definition file inside the
documentation manual you are working on, not the template file
used to create it. To edit the chapter definition file, don't
provide any section information in the documentation entry.
For example, if you want to update the chapter introduction
related to <quote>trunk</quote> chapter inside
<quote>tcar-fs</quote> documentation manual, use the
<quote>tcar-fs::trunk:</quote> documentation entry.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>chapter-menu.texinfo</filename></term>
<listitem>
<para>
This file is part of Texinfo's main chapter definition and
should be initially empty. Later, when chapters are created
for first time, this file is copied as it is (i.e., empty)
into the documentation manual to store the Texinfo menu
entries related to all documentation entries created inside
the chapter. The Texinfo menu entries related to documentation
entries are automatically created using Texinfo source files
as reference.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>chapter-nodes.texinfo</filename></term>
<listitem>
<para>
This file is part of Texinfo's main chapter definition and
contains the node definition the <xref linkend="scripts-bash-help"/>
functionality uses as reference to create the list of Texinfo
nodes related to all documentation entries created inside the
chapter. The node definition of documentation entries is
automatically created from the menu definition of
documentation entries (see
<filename>chapter-menu.texinfo</filename> file above), once it
has been updated from Texinfo source files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>section.texinfo</filename></term>
<listitem>
<para>
This file contains the Texinfo section definition used by
<xref linkend="scripts-bash-help"/> functionality when new
documentation entries are created inside chapters of
documentation manuals. When documentation entries are created
for first time, they are created as empty documentation
entries that you need to fill up with content. Again, if you
want to update the content of sections inside the
documentation manual, update the related documentation entry
inside the documentation manual, not the template file used to
create it.
</para>
<para>
The creation of documentation entries inside the documentation
manual is represented by the
<filename>${SECTION_NAME}.texinfo</filename> file, as
described in <xref
linkend="manuals-formats-texinfo-structure-example1" />. In
this example, <code>${SECTION_NAME}</code> is a variable
string referring the file name of documentation entries. The
file names of documentation entries are made of letters,
numbers and the minus sign (which is generally used as word
separator).
</para>
<para>
Documentation entries are not limited inside chapters of
documentation manuals. You can create as many documentation
entries as you need to describe the content of your manual.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
There are other files which aren't related to manual's source
files, but to manual's output files. Such files are described
below and can be found either inside or outside the
language-specific directories so you can control common and
specific output settings through them. These files aren't
copied into the directory structure of new documentation
manuals created through the <xref linkend="scripts-bash-help"/>
functionality. Instead, they remain inside the template
directory structure so as to be reused each time the output of
documentation manuals is rendered.
</para>
<variablelist>
<varlistentry>
<term><filename>manual-init.pl</filename></term>
<listitem>
<para>
This file can be found inside and outside language-specific
directories and contains the Texi2html initialization script.
When this file is outside the language-specific directory, it
contains common customizations to all language-specific
outputs (e.g., changing the output DTD). When this file is
inside the language-specific directory, it contains
translations for that language-specific output (e.g., special
words like See, Index, Contents, Top, etc., are localized
here).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>manual.sed</filename></term>
<listitem>
<para>
This file can be found inside and outside language-specific
directories and contains special transformations for Texi2html
output. Again, when this file is inside language-specific
directories the transformation are applied to that
language-specific XHTML output and when it is outside
language-specific directories the transformations are applied
to all language-specific XHTML outputs. Most transformations
achieved through this file are to produce admonitions since
Texinfo documentation format (as in
<package>texinfo-4.8-14.el5</package>) doesn't have an
internal command to build them.
</para>
</listitem>
</varlistentry>
</variablelist>
<example id="manuals-formats-texinfo-templates-example1">
<title>Template for texinfo document structures</title>
<screenshot>
<screeninfo>Template for texinfo document structures</screeninfo>
<mediaobject>
<textobject>
<programlisting>
trunk/Documentation/Models/Texinfo/Default/
|-- ${LANG}/
| |-- Chapters/
| | |-- chapter-menu.texinfo
| | |-- chapter-nodes.texinfo
| | |-- chapter.texinfo
| | `-- section.texinfo
| |-- Licenses/
| | |-- GFDL.texinfo
| | |-- GPL.texinfo
| | |-- chapter-menu.texinfo
| | |-- chapter-nodes.texinfo
| | `-- chapter.texinfo
| |-- manual-index.texinfo
| |-- manual-init.pl
| |-- manual-menu.texinfo
| |-- manual-nodes.texinfo
| |-- manual.conf
| |-- manual.sed
| `-- manual.texinfo
|-- manual-init.pl
`-- manual.sed
</programlisting>
</textobject>
</mediaobject>
</screenshot>
</example>
<para>
Inside the directory structure of Texinfo document templates,
the <filename class="directory">Chapters</filename> directory
organizes chapter specific models used to create and maintain
both chapter and sections files inside manuals. On the other
hand, the <filename class="directory">Licenses</filename>
directory organizes the license information linked from all
manuals. Notice the license information is not copied into
documentation manuals when they are created, but refered from
this location where they are maintained. This configuration
permites that all documentation manuals written in Texinfo
format inside &TCAR; do use the same license information and
if a change is committed to the license files, such changes be
immediatly propagated to documentation manuals the next time
their output files be updated.
</para>
</sect2>
<sect2 id="manuals-formats-texinfo-macros">
<title>Document Expansions</title>
<para>
The document expansions are special constructions the <xref
linkend="scripts-bash-help" /> functionality uses to generate
content dynamically inside Texinfo source files.
</para>
<sect3>
<title>The <code>SeeAlso</code> Expansion</title>
<para>
This expansion creates a list of links with section entries
one level ahead from the section entry being currently
processed. In this construction, the TYPE variable can be
either <quote>itemize</quote>, <quote>enumerate</quote> or
<quote>menu</quote>. When no TYPE variable is provided, the
<quote>itemize</quote> value is considered as default.
</para>
<screen>@c -- <[centos-art(SeeAlso,TYPE)
@c -- ]></screen>
<para>
This expansion might result useful when you are documenting
the repository file system. For example, if you are currently
editing the documentation entry related to <filename
class="directory">trunk/Identity</filename> directory and want
to create a linkable list of all documentation entries in the
first level under it, the code you'll have once the
construction be expanded would look like the following:
</para>
<screen>
@c -- <[centos-art(SeeAlso)
@itemize
@item @ref{Trunk Identity Brushes}
@item @ref{Trunk Identity Fonts}
@item @ref{Trunk Identity Images}
@item @ref{Trunk Identity Models}
@item @ref{Trunk Identity Palettes}
@item @ref{Trunk Identity Patterns}
@item @ref{Trunk Identity Webenv}
@end itemize
@c -- ]>
</screen>
<para>
An interesting thing to notice here is that document
expansions are executed each time the related documentation
entry is edited or updated. Following with the example above,
if the documentation entries related to directories under
<filename class="directory">trunk/Identity</filename> changes
for some reason (e.g., they are removed from documentation
manual), the list generated as result of document expansion
will be updated automatically after editing the documentation
entry or updating the documentation manual structure.
</para>
</sect3>
</sect2>
<sect2 id="manuals-formats-texinfo-configuration">
<title>Document Configuration</title>
<para>
The document configuration is stored in the
<filename>${MANUAL_NAME}.conf</filename> file, inside the
documentation manual directory structure. This file is
originally copied from <filename>manual.conf</filename>
template file when the documentation manual is created for
first time. The content of
<filename>${MANUAL_NAME}.conf</filename> file is organized in
sections. Each section here is written in one line of its own
and have the form <code>[section_name]</code>. Under sections,
the configuration settings take place through
<code>name="value"</code> pairs set in one line each. Notice
that quotation marks around the option_value are required.
Comments are also possible using the <code>#</code> character
at the begining of lines. Comments and empty lines (including
tabs and white spaces) are ignored. In case more than one
section or option appear with the same name inside the
configuration file, the first one found will be used. Nested
section definitions are not supported.
</para>
<screen>[section_name]
# This is a comment.
option_name = "option_value"</screen>
<para>
The <filename>${MANUAL_NAME}.conf</filename> file is specific
to document templates. If you are using Texinfo document
template to create documentation manuals, then the default
configuration file for that documentation manual is taken from
Texinfo document template directory structure. However, if you
are using a document template different to Texinfo document
template, the default configuration file will be taken from
the related document template directory structure you are
creating the documentation manual from.
</para>
<sect3>
<title>The <code>[main]</code> Section</title>
<para>
The <code>[main]</code> section organizes settings that let
you customize the way sections and menu definitions are
created inside the documentation manual. The following options
are available in this section:
</para>
<variablelist>
<varlistentry>
<term><code>manual_format</code></term>
<listitem>
<para>
This option specifies the documentation format used by manual.
To write documentation manuals in Texinfo format, the value
of this option must always be:
</para>
<screen>manual_format = "texinfo"</screen>
<caution>
<para>
Once the documentation manual has been created, you must not
change the value of <option>manual_format</option> option.
This will produce an error because there is not a migration
feature available yet. In the future, when you change this
value, it must be possible to transform documentation manuals
from one format to another.
</para>
</caution>
</listitem>
</varlistentry>
<varlistentry>
<term><code>manual_section_style</code></term>
<listitem>
<para>
This option specifies the title style used by sections inside
the manual. Possible values to this option are
`cap-each-word' to capitalize each word in the section title,
`cap-first-word' to capitalize the first word in the section
title only and `directory' to transform each word in the
section title into a directory path. From all these options,
`cap-each-word' is the one used as default.
</para>
<screen>manual_section_style = "cap-each-word"</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><code>manual_section_order</code></term>
<listitem>
<para>
This option specifies the order used by sections inside the
manual. By default new sections added to the manual are put on
the end to follow the section order in which they were
`created'. Other possible values to this option are `ordered'
and `reversed' to sort the list of sections alphabetically
from A-Z and Z-A, respectively.
</para>
<screen>manual_section_order = "created"</screen>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>The <code>[templates]</code> Section</title>
<para>
The <code>[templates]</code> section provides the assignment
relation between template files and documentation entry files
inside the manual. The template definition is set on the left
side using relative path and the documentation entry files are
described on the right side using a regular expression. The
first match wins.
</para>
<screen>Chapters/section.texinfo = "^.+\.texinfo$"</screen>
</sect3>
</sect2>
<sect2 id="manuals-formats-texinfo-l10n">
<title>Document Localization</title>
<para>
To produce localized documentation manuals through Texinfo
documentation format it is necessary to create one
documentation manual for each language it is desired to
support documentation for. Documentation manuals created in
this configuration don't have a direct relation among
themselves except that one adopted by people writting them to
keep their content syncronized. In this configuration
translators take one documentation manual as reference (a.k.a.
the source manual) and produce several translated manuals
based on its content. To keep track of changes inside the
source manual, the underlaying version control system must be
used considering that there is no direct way to apply
<command>gettext</command><footnote>
<para>
The <command>gettext</command> 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 <command>gettext</command>
program, run <command>info gettext</command>.
</para>
</footnote> procedures to Texinfo source files.
</para>
<para>
In order to maintain localization of Texinfo source files
through <command>gettext</command> procedures, it is necessary
to convert the Texinfo source files into XML format first.
This way it would be possible to make use of <xref
linkend="scripts-bash-locale"/> and <xref
linkend="scripts-bash-render"/> functionalities to maintain
translation messages in different languages through portable
objects and producing localized XML files based on such
portable objects, respectively. Once the localized XML file
is available, it would be a matter of using an XSLT processor
(see the <command>xsltproc</command> command) to realize the
convertion from XML to a localize Texinfo (or possible other)
format. Nevertheless, this workaround fails because the
Document Type Definition (DTD) required to validate the XML
file produced from <command>makeinfo</command> (as in
<package>texinfo-4.8-14.el5</package>) is not availabe inside
&TCD; (release 5.5), nor it is the XSLT files required to
realize the transformation itself for such DTD.
</para>
<para>
Another similar approach to maintain localization of Texinfo
source files through <command>gettext</command> procedures
would be to convert Texinfo source file to DocBook format; for
who the required DTD and XSLT files are available inside
&TCD;. This way, following a procedure similar to that one
describe for XML files above, it would be possible to end up
having localized DocBook files that can be used as source to
produce localized output for both online and printing media.
However, the DocBook output produced from
<command>makeinfo</command> command (as in
<package>texinfo-4.8-14.el5</package>) isn't a valid DocBook
document according to DocBook DTDs available inside &TCD;
(release 5.5) thus provoking the validation and transformation
of such a malformed document to fail.
</para>
<sect3 id="manuals-texinfo-l10n-language">
<title>Document Language</title>
<para>
The language information of those documentation manuals
produced through Texinfo documentation format is declared by
Texinfo's <code>@documentlanguage</code> command. This
command receives one argument refering the language code (as
in ISO-639 standard) and must be set inside the manual's main
definition file. Generally, there is no need to change the
document language declaration once it has been created by the
<xref linkend="scripts-bash-help"/> functionality; unless you
mistakently create the manual for a locale code different to
that one you previously pretended to do in first place, of
course.
</para>
<para>
The language information used in both Texinfo source files and
XHTML output produced by the <xref linkend="scripts-bash-help"/>
functionality is determined by the user's session
<envar>LANG</envar> environment variable. This variable 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.<footnote>
<para>
The appropriate locale code to set here can be found in
the output produced by the <command>locale -a |
less</command> command.
</para></footnote>
</para>
</tip>
<para>
When producing output from Texinfo source files using the
<command>makeinfo</command> command (as in the
<package>texinfo-4.8-14.el5</package> package), the language
information set by <code>@documentlanguage</code> is ignored
in Info and HTML output, but cosidered by Tex program to
redefine various English words used in the PDF output (e.g.,
<quote>Chapter</quote>, <quote>Index</quote>,
<quote>See</quote>, and so on) based on the current language
set in.
</para>
</sect3>
<sect3 id="manuals-texinfo-l10n-encoding">
<title>Document Encoding</title>
<para>
The encoding information of documentation manuals produced
through Texinfo documentation format is declared by Texinfo's
<code>@documentencoding</code> command and can take either
<code>US-ASCII</code>, <code>ISO-8859-1</code>,
<code>ISO-8859-15</code> or <code>ISO-8859-2</code> as
argument. Nevertheless, you should be aware that the
<xref linkend="scripts-bash-help" /> functionality doesn't
declare the <code>@documentencoding</code> inside Texinfo
source files. Let's see why.
</para>
<para>
When the <code>@documentencoding</code> command is set in
Texinfo source files, the terminal encoding you use to read
the Info output produced from such files must be set to that
encoding information you provided as argument to
<code>@documentencoding</code> command; this, before using an
Info reader to open the Info output file in the terminal.
Otherwise, when the terminal and the Texinfo source files
encoding definition differ 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 and read
documentation manuals using the UTF-8 encoding without needing
to use Texinfo's special way of producing floating accents
because the terminal encoding would be able to interpret the
characters 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>, nor in the HTML output
produced by <command>makeinfo</command>, nor in PDF output.
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 mark
<emphasis>over</emphasis> the <code>i</code> letter's dot,
instead of removing the <code>i</code> letter's dot and
put the accentuation mark on its place. In the case of XHTML
output, however, it is 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 to instruct the web
browsers what encoding to use to display the document content.
Of course, in order to display the document content correctly,
the web browser should provide support for UTF-8 encoding.
</para>
<para>
These contradictions provide the reasons over which it was
decided not to set the <code>@documentencoding</code> in those
Texinfo source files produced by the <xref
linkend="scripts-bash-help" /> functionality.
</para>
</sect3>
</sect2>
<sect2 id="manuals-texinfo-l10n-conclusions">
<title>Conclusions</title>
<para>
Texinfo documentation format is very good producing online
documentation for reading text terminals. It provides feautres
to export source files to different output formats both for
reading online and paper. However, localized documents becomes
hard to maintain because it is required one document structure
for each language you want to produce documentation for.
</para>
<para>
Intermediate formats like XML and Docbook provide an
alternative to centralize localization of Texinfo document
source files, but there is no supported way inside &TCD; to
transformed a localized XML file back into texinfo format, nor
a way of producing well formed Docbook documents from Texinfo
source files. Thus, one Texinfo source structure for each
language to support is the solution adopted by <xref
linkend="scripts-bash-help" /> functionality.
</para>
<para>
When using Texinfo documentation format it is difficult to
produce well localized PDF outputs, but it is possible to
produce well localized Info, Text, and XHTML outputs as long
as no document encoding be explicitly set inside Texinfo
source files and UTF-8 be used as default terminal character
encoding.
</para>
</sect2>
</sect1>