Blame Documentation/Models/Docbook/Tcar-ug/Manuals/Formats/texinfo.docbook

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