Blob Blame History Raw
<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 -- &lt;[centos-art(SeeAlso,TYPE)
@c -- ]&gt;</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 -- &lt;[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 -- ]&gt;
</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>&lt;meta http-equiv="content-type" content="text/html; charset=UTF-8" /&gt;</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>