<sect1 id="manuals-formats-texinfo">

    <title>Texinfo</title>

    <para>

        This section describes the implementation of Texinfo

        documentation format inside the 

        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 

        class="directory">Documentation/Models/Texinfo/</filename>

        directory and saves output produced from them in the 

        class="directory">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 

        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 

        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>Documentation/Models/Texinfo/${MANUAL_NAME}

`-- ${LANG}

    |-- ${CHAPTER_NAME}/

    |   `-- ${SECTION_NAME}.texinfo

    |-- ${CHAPTER_NAME}-menu.texinfo

    |-- ${CHAPTER_NAME}-nodes.texinfo

    |-- ${CHAPTER_NAME}.texinfo

    |-- Licenses -> Documentation/Models/Texinfo/Default/${LANG}/Licenses

    |-- Licenses-menu.texinfo -> Documentation/Models/Texinfo/Default/${LANG}/Licenses-menu.texinfo

    |-- Licenses-nodes.texinfo -> Documentation/Models/Texinfo/Default/${LANG}/Licenses-nodes.texinfo

    |-- Licenses.texinfo -> Documentation/Models/Texinfo/Default/${LANG}/Licenses.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 consider 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 

        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 

        class="directory">Scripts/Documentation/Models/Texinfo/Default/</filename>

        directory.

    </para>

    <para>

        The 

        class="directory">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 

        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 @include 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 

        linkend="manuals-formats-texinfo-configuration" />.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>Chapters.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>Chapters-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>Chapters-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>Chapters-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 

        linkend="manuals-formats-texinfo-structure-example1" />. In

        this example, ${SECTION_NAME} 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>

Documentation/Models/Texinfo/Default/

|-- ${LANG}/

|   |-- Chapters/

|   |   |-- section.texinfo

|   |   `-- section-functions.texinfo

|   |-- Chapters-menu.texinfo

|   |-- Chapters-nodes.texinfo

|   |-- Chapters.texinfo

|   |-- Licenses/

|   |   |-- GFDL.texinfo

|   |   `-- GPL.texinfo

|   |-- Licenses-menu.texinfo

|   |-- Licenses-nodes.texinfo

|   |-- Licenses.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

        stores section specific models used to create and maintain

        section files inside manuals. File names beginning with

        <quote>Chapters</quote>, at the same level of 

        class="directory">Chapters</filename> directory, are used to

        create chapter specific files inside manuals.

    </para>

    <para>

        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 referred from

        models location where they are maintained.  This configuration

        permits all documentation manuals written in Texinfo format

        inside &TCAR; to use the same license information. This way,

        if a change is committed to license files, it will be

        immediately propagated to all 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 

        linkend="scripts-bash-help" /> functionality provides to

        generate content dynamically inside Texinfo source files.

    </para>

    <sect3>

    <title>The SeeAlso Expansion</title>

    <para>

        This expansion creates a list of links with section entries

        one level ahead from the section entry being currently

        processed.  In this construction, the TYPE variable can be

        either <quote>itemize</quote>, <quote>enumerate</quote> or

        <quote>menu</quote>. When no TYPE variable is provided, the

        <quote>itemize</quote> value is considered as default.

    </para>

    <screen>@c -- <[centos-art(SeeAlso,TYPE)

@c -- ]></screen>

    <para>

        This expansion might result useful when you are documenting

        the repository file system. For example, if you are currently

        editing the documentation entry related to 

        class="directory">Identity</filename> directory and want

        to create a linkable list of all documentation entries in the

        first level under it, the code you'll have once the

        construction be expanded would look like the following:

    </para>

<screen>

@c -- <[centos-art(SeeAlso)

@itemize

@item @ref{Trunk Identity Brushes}

@item @ref{Trunk Identity Fonts}

@item @ref{Trunk Identity Images}

@item @ref{Trunk Identity Models}

@item @ref{Trunk Identity Palettes}

@item @ref{Trunk Identity Patterns}

@item @ref{Trunk Identity Webenv}

@end itemize

@c -- ]>

</screen>

    <para>

        An interesting thing to notice here is that document

        expansions are executed each time the related documentation

        entry is edited or updated. Following with the example above,

        if the documentation entries related to directories under

        <filename class="directory">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 [section_name]. Under sections,

        the configuration settings take place through

        name="value" pairs set in one line each.  Notice

        that quotation marks around the option_value are required.

        Comments are also possible using the # 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 [main] Section</title>

    <para>

        The [main] 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>manual_format</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>manual_section_style</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>manual_section_order</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 [templates] Section</title>

    <para>

        The [templates] 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 

        linkend="scripts-bash-locale"/> and 

        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

        &TC;; (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

        &TC;;.  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 &TC;;

        (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 @documentlanguage command.  This

        command receives one argument refering the language code (as

        in ISO-639 standard) and must be set inside the manual's main

        definition file. Generally, there is no need to change the

        document language declaration once it has been created by the

        <xref linkend="scripts-bash-help"/> functionality; unless you