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

370193
<sect1 id="manuals-formats-texinfo">
1c9079
856ac0
    <title>Texinfo</title>
1c9079
1c9079
    <para>
4bdef7
        This section describes the implementation of Texinfo
4b6d8d
        documentation format inside the 
4b6d8d
        linkend="scripts-bash-help"/> functionality of
4b6d8d
        <command>centos-art.sh</command> script. In this section we
4b6d8d
        assume you have a basic understanding of Texinfo documentation
4b6d8d
        system. Otherwise, if you don't know what Texinfo
4b6d8d
        documentation system is, read the Texinfo manual first (e.g.,
4b6d8d
        by running the <command>info texinfo</command> command) and
4b6d8d
        then, come back here.
1c9079
    </para>
1c9079
1c9079
    <sect2 id="manuals-formats-texinfo-structure">
856ac0
    <title>Document Structure</title>
1c9079
    <para>
4b6d8d
        The <xref linkend="scripts-bash-help"/> 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> 
4b6d8d
        The <xref linkend="scripts-bash-help"/>
4b6d8d
        functionality creates documentation manuals source files in
4b6d8d
        the 
47422e
        class="directory">Documentation/Models/Texinfo/</filename>
4b6d8d
        directory and saves output produced from them in the 
47422e
        class="directory">Documentation/Manuals/Texinfo/</filename>
4b6d8d
        directory.  To produce documentation manuals initial source
4b6d8d
        files, the <xref linkend="scripts-bash-help"/> functionality
4b6d8d
        uses Texinfo documentation templates, as described in 
4b6d8d
        linkend="manuals-formats-texinfo-templates" />.
4b6d8d
    </para>
4b6d8d
4b6d8d
    <para>
4b6d8d
        Inside the documentation models 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,
4b6d8d
        indexes and all similar stuff a documentation manual usually
4b6d8d
        has).  In addition to these files, there is one directory for
270da1
        each chapter created inside the manual.  Inside each chapter
4b6d8d
        directory, you'll find the files controlling the section
4b6d8d
        definitions related each chapter they belong to.  The section
4b6d8d
        files (a.k.a.  <quote>documentation entries</quote>) are
4b6d8d
        suffixed with a <filename class="extension">texinfo</filename>
4b6d8d
        extension and named 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>
47422e
    <programlisting>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
4b6d8d
        neither the <xref linkend="scripts-bash-help"/> functionality
4b6d8d
        does.  Nevertheless, you can create several documentation
4b6d8d
        manuals and considered them as part of a bigger documentation
4b6d8d
        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
4b6d8d
        files produced from them in your workstation.
c2e3b3
    </para>
aab348
1c9079
    </sect2>
1c9079
1c9079
    <sect2 id="manuals-formats-texinfo-templates">
856ac0
    <title>Document Templates</title>
856ac0
    <para>
4b6d8d
        Texinfo document templates provide the initial document
4b6d8d
        structure the <xref linkend="scripts-bash-help"/>
4b6d8d
        functionality needs in order to create and maintain document
4b6d8d
        structures, as described in 
4b6d8d
        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
4b6d8d
        in the 
47422e
        class="directory">Scripts/Documentation/Models/Texinfo/Default/</filename>
4b6d8d
        directory.
1c9079
    </para>
1c9079
1c9079
    <para>
4b6d8d
        The 
47422e
        class="directory">Scripts/Documentation/Models/Texinfo/Default/</filename>
4b6d8d
        directory organizes all Texinfo document templates using the
4b6d8d
        format LL_CC, where LL is the language code (as in ISO-639)
4b6d8d
        and CC the country code (as in ISO-3166). The directory
4b6d8d
        structure of Texinfo document templates is illustrated in the
4b6d8d
        <xref linkend="manuals-formats-texinfo-templates-example1" />
4b6d8d
        and 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
4b6d8d
        manual. When <xref linkend="scripts-bash-help" />
4b6d8d
        functionality creates instances of this file, menu definitions
4b6d8d
        inside it are automatically updated when a new chapter is
4b6d8d
        created or deleted through the 
4b6d8d
        linkend="scripts-bash-help"/> functionality.  Generally, you
4b6d8d
        don't need to edit instances of this file once the
4b6d8d
        documentation manual has been 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.
4b6d8d
        At this specific moment, the instance created contains the
4b6d8d
        following Texinfo menu definition:
52b8a7
    </para>
52b8a7
4b6d8d
<programlisting>
4b6d8d
@menu
52b8a7
* Licenses::
52b8a7
* Index::
4b6d8d
@end menu
4b6d8d
</programlisting>
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
4b6d8d
        instances of this file. To preserve the manual consistency,
4b6d8d
        the <xref linkend="scripts-bash-help"/> functionality prevents
4b6d8d
        you from deleting any of these chapters once the documentation
4b6d8d
        manual 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
4b6d8d
        manual.  When <xref linkend="scripts-bash-help"/>
4b6d8d
        functionality creates instances of this file, node definitions
4b6d8d
        inside it are automatically created based on menu definitions
4b6d8d
        (see <filename>manual-menu.texinfo</filename> file above) and
4b6d8d
        they don't include any content here.  Instead, as part of the
4b6d8d
        node definition, the @include command is used to
2894ff
        connect each node with its content.  Generally, you don't need
4b6d8d
        to edit instances of this file once the documentation manual
4b6d8d
        has been 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
4b6d8d
        need to edit instnaces of this file once the documentation
4b6d8d
        manual has been 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
4b6d8d
        directory so you be able to customize specific information
4b6d8d
        like menu order, title styles and template assignments
4b6d8d
        therein. 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>
4b6d8d
        This file contains Texinfo's main chapter definition used
4b6d8d
        by <xref linkend="scripts-bash-help"/> functionality when new
4b6d8d
        chapters are created inside documentation manuals. When
4b6d8d
        chapters are created for first time, they come without any
4b6d8d
        introduction or documentation entry inside.
4b6d8d
    </para>
4b6d8d
    <para>
4b6d8d
        In case you need to add/update the chapters definition files,
4b6d8d
        edit the related chapter definition file inside the
4b6d8d
        documentation manual you are working on, not the template file
4b6d8d
        used to create it. To edit the chapter definition file, don't
4b6d8d
        provide any section information in the documentation entry.
4b6d8d
        For example, if you want to update the chapter introduction
4b6d8d
        related to <quote>trunk</quote> chapter inside
4b6d8d
        <quote>tcar-fs</quote> documentation manual, use the
4b6d8d
        <quote>tcar-fs::trunk:</quote> documentation entry.
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
4b6d8d
        contains the node definition the <xref linkend="scripts-bash-help"/>
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
4b6d8d
        <xref linkend="scripts-bash-help"/> functionality when new
4b6d8d
        documentation entries are created inside chapters of
4b6d8d
        documentation manuals. When documentation entries are created
4b6d8d
        for first time, they are created as empty documentation
4b6d8d
        entries that you need to fill up with content.  Again, if you
4b6d8d
        want to update the content of sections inside the
4b6d8d
        documentation manual, update the related documentation entry
4b6d8d
        inside the documentation manual, not the template file used to
4b6d8d
        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
4b6d8d
        string referring the file name of documentation entries.  The
4b6d8d
        file names of documentation entries are made of letters,
4b6d8d
        numbers and the minus sign (which is generally used as word
4b6d8d
        separator).
52b8a7
    </para>
52b8a7
52b8a7
    <para>
4b6d8d
        Documentation entries are not limited inside chapters of
4b6d8d
        documentation manuals. You can create as many documentation
4b6d8d
        entries as you 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
4b6d8d
        manuals created through the <xref linkend="scripts-bash-help"/>
4b6d8d
        functionality.  Instead, they remain inside the template
4b6d8d
        directory structure so as to be reused each time the output of
4b6d8d
        documentation 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
4b6d8d
        directories and contains special transformations for Texi2html
270da1
        output. Again, when this file is inside language-specific
4b6d8d
        directories the transformation 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
4b6d8d
        achieved 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">
4b6d8d
    <title>Template for texinfo document structures</title>
1c9079
    <screenshot>
4b6d8d
    <screeninfo>Template for texinfo document structures</screeninfo>
1c9079
    <mediaobject>
1c9079
    <textobject>
4b6d8d
    <programlisting>
47422e
Documentation/Models/Texinfo/Default/
4b6d8d
|-- ${LANG}/
4b6d8d
|   |-- Chapters/
1c9079
|   |   |-- chapter-menu.texinfo
1c9079
|   |   |-- chapter-nodes.texinfo
1c9079
|   |   |-- chapter.texinfo
1c9079
|   |   `-- section.texinfo
4b6d8d
|   |-- 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
4b6d8d
`-- manual.sed
4b6d8d
</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>
4b6d8d
        The document expansions are special constructions the 
4b6d8d
        linkend="scripts-bash-help" /> functionality uses to generate
4b6d8d
        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 
47422e
        class="directory">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
47422e
        <filename class="directory">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.
4b6d8d
        This will produce an error because there is not a migration
4b6d8d
        feature available yet. In the future, when you change this
4b6d8d
        value, it must be possible to transform documentation manuals
4b6d8d
        from one format to another.
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">
4b6d8d
    <title>Document Localization</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
4b6d8d
        <command>gettext</command><footnote>
d0c037
        <para>
4b6d8d
            The <command>gettext</command> program  translates
d0c037
            a  natural language message into the user's language, by
d0c037
            looking up the translation in a message catalog. For more
4b6d8d
            information about the <command>gettext</command>
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
4b6d8d
        through <command>gettext</command> procedures, it is necessary
4b6d8d
        to convert the Texinfo source files into XML format first.
4b6d8d
        This way it would be possible to make use of 
4b6d8d
        linkend="scripts-bash-locale"/> and 
4b6d8d
        linkend="scripts-bash-render"/> functionalities to maintain
4b6d8d
        translation messages in different languages through portable
4b6d8d
        objects and producing localized XML files based on such
4b6d8d
        portable objects, respectively.  Once the localized XML file
4b6d8d
        is available, it would be a matter of using an XSLT processor
4b6d8d
        (see the <command>xsltproc</command> command) to realize the
4b6d8d
        convertion from XML to a localize Texinfo (or possible other)
4b6d8d
        format.  Nevertheless, this workaround fails because the
4b6d8d
        Document Type Definition (DTD) required to validate the XML
4b6d8d
        file produced from <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
4b6d8d
        source files through <command>gettext</command> procedures
4b6d8d
        would be to convert Texinfo source file to DocBook format; for
4b6d8d
        who the required DTD and XSLT files are available inside
4b6d8d
        &TC;;.  This way, following a procedure similar to that one
4b6d8d
        describe for XML files above, it would be possible to end up
4b6d8d
        having localized DocBook files that can be used as source to
4b6d8d
        produce localized output for both online and printing media.
4b6d8d
        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
4b6d8d
        <xref linkend="scripts-bash-help"/> functionality; 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
4b6d8d
        XHTML output produced by the <xref linkend="scripts-bash-help"/>
4b6d8d
        functionality is determined by the user's session
4b6d8d
        <envar>LANG</envar> environment variable.  This variable can
4b6d8d
        be customized in the graphical login screen before login, or
4b6d8d
        once you've login by explicitly setting the value of
4b6d8d
        <envar>LANG</envar> 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
4b6d8d
        <xref linkend="scripts-bash-help" /> functionality doesn't
4b6d8d
        declare the @documentencoding inside Texinfo
4b6d8d
        source files.  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
4b6d8d
        output, however, it is possible to produce well localized
4b6d8d
        XHTML 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
4b6d8d
        Texinfo source files produced by the 
4b6d8d
        linkend="scripts-bash-help" /> functionality. 
d0c037
    </para>
d0c037
d0c037
    </sect3>
d0c037
1c9079
    </sect2>
1c9079
4b6d8d
    <sect2 id="manuals-texinfo-l10n-conclusions">
4b6d8d
    <title>Conclusions</title>
4b6d8d
4b6d8d
    <para>
4b6d8d
        Texinfo documentation format is very good producing online
4b6d8d
        documentation for reading text terminals. It provides feautres
4b6d8d
        to export source files to different output formats both for
4b6d8d
        reading online and paper. However, localized documents becomes
4b6d8d
        hard to maintain because it is required one document structure
4b6d8d
        for each language you want to produce documentation for.
4b6d8d
    </para>
4b6d8d
    <para>
4b6d8d
        Intermediate formats like XML and Docbook provide an
4b6d8d
        alternative to centralize localization of Texinfo document
4b6d8d
        source files, but there is no supported way inside &TC;; to
4b6d8d
        transformed a localized XML file back into texinfo format, nor
4b6d8d
        a way of producing well formed Docbook documents from Texinfo
4b6d8d
        source files. Thus, one Texinfo source structure for each
4b6d8d
        language to support is the solution adopted by 
4b6d8d
        linkend="scripts-bash-help" /> functionality.
4b6d8d
    </para>
4b6d8d
4b6d8d
    <para>
4b6d8d
        When using Texinfo documentation format it is difficult to
4b6d8d
        produce well localized PDF outputs, but it is possible to
4b6d8d
        produce well localized Info, Text, and XHTML outputs as long
4b6d8d
        as no document encoding be explicitly set inside Texinfo
4b6d8d
        source files and UTF-8 be used as default terminal character
4b6d8d
        encoding.
4b6d8d
    </para>
4b6d8d
4b6d8d
    </sect2>
4b6d8d
1c9079
</sect1>
1c9079