| <sect1 id="manuals-format-texinfo"> |
| |
| <title>Texinfo</title> |
| |
| <para> |
| This section describes the implementation of Texinfo |
| documentation format inside the <function>help</function> |
| functionality of <command>centos-art.sh</command> script |
| described in <xref linkend="scripts-bash-help" />. 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 <function>help</function> 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 first time you use the <function>help</function> |
| functionality to create a documentation manual in Texinfo |
| format, the <function>help</function> functionality considers |
| the working directory you are placed in to determine where to |
| store the documentation manual source files. When the current |
| working directory is <filename |
| class="directory">branches/Manuals/Texinfo</filename>, the |
| documentation manual directory is created therein. On all |
| other situations, the documentation manual directory is |
| created under <filename |
| class="directory">trunk/Manuals</filename> directory. Once |
| the documentation manual directory has been created, the |
| <function>help</function> functionality creates the related |
| definition files using Texinfo documentation templates, as |
| described in <xref linkend="manuals-formats-texinfo-templates" |
| />. |
| </para> |
| |
| <para> |
| Inside the documentation manual 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 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, you'll found the files controlling the section |
| definitions related to that 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 does the <function>help</function> functionality of |
| <command>centos-art.sh</command> script. Nevertheless, you can |
| create several documentation manuals and |
| <emphasis>considered</emphasis> 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. |
| </para> |
| |
| </sect2> |
| |
| <sect2 id="manuals-formats-texinfo-templates"> |
| <title>Document Templates</title> |
| <para> |
| Texinfo document templates provide the initial state the |
| <function>help</function> functionality of |
| <command>centos-art.sh</command> script needs in order to |
| create and maintain document structures, as that one 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 directory: |
| </para> |
| |
| <screen> |
| trunk/Scripts/Bash/Functions/Help/Texinfo/Templates</screen> |
| |
| <para> |
| This 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. Menu definitions in this file are automatically |
| updated when a new chapter is created or deleted through the |
| <function>help</function> functionality of |
| <command>centos-art.sh</command> script. Generally, you don't |
| need to edit 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, this file contains the following |
| Texinfo menu definition: |
| </para> |
| |
| <screen>@menu |
| * Licenses:: |
| * Index:: |
| @end menu</screen> |
| |
| <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 |
| this file. To preserve the manual consistency, the |
| <function>help</function> 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. Node definitions in this file 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 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 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 of later customizing specific |
| information like menu order, title styles and template |
| assignments. 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 the Texinfo's main chapter definition used |
| by <function>help</function> 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. If you want to add/update any |
| information inside the chapter definition itself, edit the |
| related chapter file inside the documentation manual you are |
| working on, not the template file used to create it. |
| </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 <function>help</function> |
| 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 |
| <function>help</function> functionality when new documentation |
| entries are created inside the chapters of a documentation |
| manual. 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 refering the file name of documentaiton entries. |
| The file names of documentation entries is made of letters, |
| numbers and the minus sign (which is generally used to |
| separate words). |
| </para> |
| |
| <para> |
| Documentation entries are not limited inside a documentation |
| manual. 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 <function>help</function> |
| functionality of <command>centos-art.sh</command> script. |
| 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 contain special transformations for Texi2html |
| output. Again, when this file is inside language-specific |
| directories the transformation have 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 |
| achived 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>Texinfo document template</title> |
| <screenshot> |
| <screeninfo>Texinfo document template</screeninfo> |
| <mediaobject> |
| <textobject> |
| <programlisting>trunk/Scripts/Bash/Functions/Help/Texinfo/Templates |
| |-- ${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 used 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. |
| </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 Internationalization</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 |
| <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 to Texinfo source files. |
| </para> |
| |
| <para> |
| In order to maintain localization of Texinfo source files |
| through <application>gettext</application> procedures, it is |
| necessary to convert the Texinfo source files into |
| XML format first. This way it would be possible to make use of |
| <function>locale</function> and <function>render</function> |
| functionalities from <command>centos-art.sh</command> 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 <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 <application>gettext</application> |
| 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 |
| <function>help</function> functionality of |
| <command>centos-art.sh</command> 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. |
| </para> |
| |
| <para> |
| The language information used in both Texinfo source files and |
| XHTML output produced by the <function>help</function> |
| functionality of <command>centos-art.sh</command> script 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 |
| <code>help</code> functionality of |
| <command>centos-art.sh</command> script 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 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 <code>help</code> |
| functionality of <command>centos-art.sh</command> script. Now, |
| considering them, we can conclude that it is no viable way to |
| localize Texinfo source files through |
| <application>gettext</application> 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. |
| </para> |
| |
| </sect3> |
| |
| </sect2> |
| |
| </sect1> |
| |