From d0c037fc4d60138ea74be24a53dafbd7b96d1c39 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Sep 15 2011 21:22:17 +0000 Subject: Update `Manuals/Formats/texinfo.docbook'. --- 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. + + + +