diff --git a/Manuals/Tcar-ug/Manuals/Formats/texinfo.docbook b/Manuals/Tcar-ug/Manuals/Formats/texinfo.docbook
index 68ad6b8..d26db0b 100644
--- a/Manuals/Tcar-ug/Manuals/Formats/texinfo.docbook
+++ b/Manuals/Tcar-ug/Manuals/Formats/texinfo.docbook
@@ -59,36 +59,92 @@
- Inside the language specific directory, the files
+ 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 the similar stuff a documentation manual would
+ have).
-
-${MANUAL_NAME}.texinfo
-${MANUAL_NAME}-index.texinfo
-${MANUAL_NAME}-menu.texinfo
-${MANUAL_NAME}-nodes.texinfo
+
+
+ ${MANUAL_NAME}.texinfo
+
+
+ ...
+
+
+
+
+ ${MANUAL_NAME}-index.texinfo
+
- exist to store the manual's main definitions (e.g., title,
- subtitle, author, copyright notice, chapters, appendixes,
- indexes and all the similar stuff a documentation manual would
- have). In addition to these files, there is one directory for
- each chapter created inside the manual. Inside each chapter
- directory, the files
+ ...
+
+
-
-chapter.texinfo
-chapter-menu.texinfo
-chapter-nodes.texinfo
+
+ ${MANUAL_NAME}-menu.texinfo
+
+
+ ...
+
+
+
+
+
+ ${MANUAL_NAME}-nodes.texinfo
+
+
+ ...
+
+
+
+
+
+
+ In addition to these files, there is one directory for each
+ chapter created inside the manual. Inside each chapter
+ directory, the following files exist to control section
+ definitions related to the chapter directory they belong to.
+
+
+
+
+ chapter.texinfo
+
+
+ ...
+
+
+
+
+
+ chapter-menu.texinfo
+
+
+ ...
+
+
+
+
+ chapter-nodes.texinfo
+
- exist to control section definitions related to the chapter
- directory they belong to. The documentation manual content
- itself is stored in section files (a.k.a.
- documentation entries) suffixed with texinfo extension and arbitrary
- names, as it is displayed in
+
+
+
+
+
+ The documentation manual content itself is stored in section
+ files (a.k.a. documentation entries) suffixed
+ with a texinfo
+ extension and arbitrary names, as it is illustrated in .
@@ -302,8 +358,205 @@ chapter-nodes.texinfo
Texinfo Document Internationalization
- ...
+ To produce localized documentation manuals through texinfo
+ documentation backend 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
+ gettext
+
+ The gettext 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 gettext
+ program, run info gettext.
+
+ procedures to texinfo source files.
+
+
+ In order to maintain localization of texinfo source files
+ through gettext procedures, it is
+ necessary to convert the texinfo source files into
+ XML format first. This way it would be possible to make use of
+ locale and render
+ functionalities from centos-art.sh script
+ to maintain translation messages in different languages
+ through portable objets 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 xsltproc
+ 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
+ makeinfo (as in
+ texinfo-4.8-14.el5) is not availabe inside
+ &TCD; (release 5.5), nor it is the XSLT files required to
+ realize the transformation itself for such DTD.
+
+
+
+ Another similar approach to maintain localization of texinfo
+ source files through gettext
+ 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
+ makeinfo command (as in
+ texinfo-4.8-14.el5) 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.
+
+
+
+ The Document Language
+
+ The language information of those documentation manuals
+ produced through texinfo documentation backend is declared by
+ texinfo's @documentlanguage 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
+ help functionality of
+ centos-art.sh script; unless you
+ mistakently create the manual for a locale code different to
+ that one you previously pretended to do in first place, of
+ course.
+
+
+
+ The language information used in both texinfo source files and
+ XHTML output produced by the help
+ functionality of centos-art.sh script is
+ determined by the user's session LANG
+ 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 LANG
+ environment variable inside the
+ ~/.bash_profile file.
+
+
+
+
+ To create documentation manuals in English language the
+ LANG environment variable must be set to
+ en_US.UTF-8 or something similar. Likewise, if
+ you want to create documentation manuals in a language other
+ than English, be sure the LANG environment
+ variable is set to the appropriate locale code, based on the
+ output of the locale -a | less command.
+
+
+
+
+ When producing output from texinfo source files using the
+ makeinfo command (as in the
+ texinfo-4.8-14.el5 package), the language
+ information set by @documentlanguage is ignored
+ in Info and HTML output, but cosidered by Tex program to
+ redefine various English words used in the PDF output (e.g.,
+ Chapter, Index,
+ See, and so on) based on the current language
+ set in.
+
+
+
+
+
+ The Document Encoding
+
+ The encoding information of documentation manuals produced
+ through texinfo documentation backend is declared by texinfo's
+ @documentencoding command and can take either
+ US-ASCII, ISO-8859-1,
+ ISO-8859-15 or ISO-8859-2 as
+ argument. Nevertheless, you should be aware that the
+ help functionality of
+ centos-art.sh script doesn't declare the
+ @documentencoding inside texinfo source files.
+ Let's see why.
+
+
+
+ When the @documentencoding 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
+ @documentencoding 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
+ is provided to
+ makeinfo command). On the other hand, when
+ the @documentencoding 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.
+
+
+
+ When texinfo's special way of producing floating accents isn't
+ used, HTML entities are not produced in XHTML output produced
+ by texi2html, nor in the HTML output
+ produced by makeinfo, 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 i letter (e.g.,
+ í). When you do so, you'll note that that
+ construction puts the accentuation mark
+ over the i letter's dot,
+ instead of removing the i letter's dot and
+ put the accentuation mark on its place. In the case of XHTML
+ output, however, it possible to produce well localized XHTML
+ output by setting
+
+
+ <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+
+
+ 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.
+
+
+
+ These contradictions provide the reasons over which it was
+ decided not to set the @documentencoding in those
+ texinfo source files produced by the help
+ functionality of centos-art.sh script. Now,
+ considering them, we can conclude that it is no viable way to
+ localize texinfo source files through
+ gettext procedures so one
+ documentation manual must be created for each language we
+ desire to support documentation for. In this configuration,
+ it is difficult the production of well localized PDF output,
+ 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.
+
+
+
+