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

    <title>Texinfo</title>

    <para>

        This section describes the implementation of Texinfo

        documentation format inside the <function>help</function>

        functionality of <command>centos-art.sh</command> script

        described in <xref linkend="scripts-bash-help" />. In this

        section we assume you have a basic understanding of Texinfo

        documentation system. Otherwise, if you don't know what

        Texinfo documentation system is, read the Texinfo manual first

        (e.g., by running the <command>info texinfo</command> command)

        and then, come back here.

    </para>

    <sect2 id="manuals-formats-texinfo-structure">

    <title>Document Structure</title>

    <para>

        The <function>help</function> functionality of

        <command>centos-art.sh</command> provides a document structure

        that makes documentation manuals created through it to be

        scalable and maintainable through time.  This document

        structure follows the idea of an upside-down tree to organize

        chapters, sections, subsections and the like, as described in

        <xref linkend="manuals-production-identifying-structure" />.

    </para>

    <para> 

        The first time you use the <function>help</function>

        functionality to create a documentation manual in Texinfo

        format, the <function>help</function> functionality considers

        the working directory you are placed in to determine where to

        store the documentation manual source files.  When the current

        working directory is 

        class="directory">branches/Manuals/Texinfo</filename>, the

        documentation manual directory is created therein.  On all

        other situations, the documentation manual directory is

        created under 

        class="directory">trunk/Manuals</filename> directory.  Once

        the documentation manual directory has been created, the

        <function>help</function> functionality creates the related

        definition files using Texinfo documentation templates, as

        described in 

        />.

    </para>

    <para>

        Inside the documentation manual directory, source files are

        stored inside language-specific directories. The

        language-specific directories are necessary to implement

        internationalization of Texinfo source files, as described in

        <xref linkend="manuals-formats-texinfo-l10n" />.

    </para>

    <para>

        Inside the language-specific directory, the following files

        exist to store the manual's main definitions (e.g., title,

        subtitle, author, copyright notice, chapters, appendixes,

        indexes and all the similar stuff a documentation manual would

        have).  In addition to these files, there is one directory for

        each chapter created inside the manual.  Inside each chapter

        directory, you'll found the files controlling the section

        definitions related to that chapter they belong to.  The

        section files (a.k.a.  <quote>documentation entries</quote>)

        are suffixed with a 

        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>trunk/Manuals/${MANUAL_NAME}

`-- ${LANG}

    |-- ${CHAPTER_NAME}

    |   |-- chapter-menu.texinfo

    |   |-- chapter-nodes.texinfo

    |   |-- chapter.texinfo

    |   `-- ${SECTION_NAME}.texinfo

    |-- Licenses

    |   |-- chapter-menu.texinfo

    |   |-- chapter-nodes.texinfo

    |   `-- chapter.texinfo

    |-- ${MANUAL_NAME}.conf

    |-- ${MANUAL_NAME}-index.texinfo

    |-- ${MANUAL_NAME}-menu.texinfo

    |-- ${MANUAL_NAME}-nodes.texinfo

    `-- ${MANUAL_NAME}.texinfo</programlisting>

    </textobject>

    </mediaobject>

    </screenshot>

    </example>

    <para>

        Texinfo (as in <package>texinfo-4.8-14.el5</package>) doesn't

        support part sectioning inside documentation manuals, so

        neither does the <function>help</function> functionality of

        <command>centos-art.sh</command> script. Nevertheless, you can

        create several documentation manuals and

        <emphasis>considered</emphasis> them as part of a bigger

        documentation manual to workaround this issue.

    </para>

    <para>

        In this document structure, the creation of documentation

        manuals, chapters and sections is not limitted. You can create

        as many documenation manuals, chapters and sections as you

        need. The only limitation would be the amount of free space

        required to store the Texinfo source files and the output

        files produced from them.

    </para>

    </sect2>

    <sect2 id="manuals-formats-texinfo-templates">

    <title>Document Templates</title>

    <para>

        Texinfo document templates provide the initial state the

        <function>help</function> functionality of

        <command>centos-art.sh</command> script needs in order to

        create and maintain document structures, as that one described

        in <xref linkend="manuals-formats-texinfo-structure" />.

    </para>

    <para>

        Texinfo document templates are language-specific. This means

        that there is (or, at least, must be) one Texinfo document

        template for each language you plan to support documentation

        manuals for. By default, &TCAR; provides a default Texinfo

        document template under <filename class="directory">en_US</filename>

        directory. This template structure is used when your current

        locale is English language or when you are creating/editing a

        documentation manual in a language other than English, but no

        language-specific document template for that language exists

        in the directory:

    </para>

    <screen>

trunk/Scripts/Bash/Functions/Help/Texinfo/Templates</screen>

    <para>

        This directory organizes all Texinfo document templates using

        the format LL_CC, where LL is the language code (as in

        ISO-639) and CC the country code (as in ISO-3166). The

        directory structure of Texinfo document templates is

        illustrated in the 

        linkend="manuals-formats-texinfo-templates-example1" /> and

        implemented through the following files:

    </para>

    <variablelist>

    <varlistentry>

    <term><filename>manual.texinfo</filename></term>

    <listitem>

    <para>

        This file can be found inside the language-specific directory

        and contains the manual's main definitions (e.g., document

        title, document language, document authors, copyright notice,

        etc.). 

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>manual-menu.texinfo</filename></term>

    <listitem>

    <para>

        This file can be found inside the language-specific directory

        and contains the menu definitions of chapters inside the

        manual. Menu definitions in this file are automatically

        updated when a new chapter is created or deleted through the

        <function>help</function> functionality of

        <command>centos-art.sh</command> script.  Generally, you don't

        need to edit this file once the documentation manual has been

        created.

    </para>

    <para>

        When a documentation manual is created for first time, this

        file is copied from Texinfo document template directory

        structure to the documentation manual being currently created.

        At this specific moment, this file contains the following

        Texinfo menu definition:

    </para>

    <screen>@menu

* Licenses::

* Index::

@end menu</screen>

    <para>

        Later, when chapters are added to or deleted from the

        documentation manual, the content of this file varies adding

        or deleting menu entries accordingly.  Nevertheless, the two

        entries shown above are ignored when new chapters are added to

        or removed from the list, so they will always be present in

        this file. To preserve the manual consistency, the

        <function>help</function> functionality prevents you from

        deleting any of these chapters once the documentation manual

        has been created.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>manual-nodes.texinfo</filename></term>

    <listitem>

    <para>

        This file can be found inside the language-specific directory

        and contains the node definitions of all chapters inside the

        manual.  Node definitions in this file are automatically

        created based on menu definitions (see

        <filename>manual-menu.texinfo</filename> file above) and they

        don't include any content here.  Instead, as part of the node

        definition, the @include command is used to

        connect each node with its content.  Generally, you don't need

        to edit this file once the documentation manual has been

        created.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>manual-index.texinfo</filename></term>

    <listitem>

    <para>

        This file can be found inside the language-specific directory

        and contains the Texinfo commands used to generated an

        organized view of all indexes you defined inside documentation

        entries so they can be quickly accessed. Generally, you don't

        need to edit this file once the documentation manual has been

        created.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>manual.conf</filename></term>

    <listitem>

    <para>

        This file contains the initial configuration of documentation

        manuals written in Texinfo format. When a documentation manual

        is created for first time, this file is copied into its target

        directory so you be able of later customizing specific

        information like menu order, title styles and template

        assignments. The content of this file is described in 

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

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>chapter.texinfo</filename></term>

    <listitem>

    <para>

        This file contains the Texinfo's main chapter definition used

        by <function>help</function> functionality when new chapters

        are created inside documentation manuals. When chapters are

        created for first time, they come without any introduction or

        documentation entry inside. If you want to add/update any

        information inside the chapter definition itself, edit the

        related chapter file inside the documentation manual you are

        working on, not the template file used to create it.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>chapter-menu.texinfo</filename></term>

    <listitem>

    <para>

        This file is part of Texinfo's main chapter definition and

        should be initially empty. Later, when chapters are created

        for first time, this file is copied as it is (i.e., empty)

        into the documentation manual to store the Texinfo menu

        entries related to all documentation entries created inside

        the chapter. The Texinfo menu entries related to documentation

        entries are automatically created using Texinfo source files

        as reference.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>chapter-nodes.texinfo</filename></term>

    <listitem>

    <para>

        This file is part of Texinfo's main chapter definition and

        contains the node definition the <function>help</function>

        functionality uses as reference to create the list of Texinfo

        nodes related to all documentation entries created inside the

        chapter. The node definition of documentation entries is 

        automatically created from the menu definition of

        documentation entries (see

        <filename>chapter-menu.texinfo</filename> file above), once it

        has been updated from Texinfo source files.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>section.texinfo</filename></term>

    <listitem>

    <para>

        This file contains the Texinfo section definition used by

        <function>help</function> functionality when new documentation

        entries are created inside the chapters of a documentation

        manual. When documentation entries are created for first time,

        they are created as empty documentation entries that you need

        to fill up with content.  Again, if you want to update the

        content of sections inside the documentation manual, update

        the related documentation entry inside the documentation

        manual, not the template file used to create it.

    </para>

    <para>

        The creation of documentation entries inside the documentation

        manual is represented by the

        <filename>${SECTION_NAME}.texinfo</filename> file, as

        described in 

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

        this example, ${SECTION_NAME} is a variable

        string refering the file name of documentaiton entries.

        The file names of documentation entries is made of letters,

        numbers and the minus sign (which is generally used to

        separate words).

    </para>

    <para>

        Documentation entries are not limited inside a documentation

        manual. You can create as many documentation entries as you

        need to describe the content of your manual.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <para>

        There are other files which aren't related to manual's source

        files, but to manual's output files. Such files are described

        below and can be found either inside or outside the

        language-specific directories so you can control common and

        specific output settings through them.  These files aren't

        copied into the directory structure of new documentation

        manuals created through the <function>help</function>

        functionality of <command>centos-art.sh</command> script.

        Instead, they remain inside the template directory structure

        so as to be reused each time the output of documentation

        manuals is rendered.

    </para>

    <variablelist>

    <varlistentry>

    <term><filename>manual-init.pl</filename></term>

    <listitem>

    <para>

        This file can be found inside and outside language-specific

        directories and contains the Texi2html initialization script.

        When this file is outside the language-specific directory, it

        contains common customizations to all language-specific

        outputs (e.g., changing the output DTD).  When this file is

        inside the language-specific directory, it contains

        translations for that language-specific output (e.g., special

        words like See, Index, Contents, Top, etc., are localized

        here).

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><filename>manual.sed</filename></term>

    <listitem>

    <para>

        This file can be found inside and outside language-specific

        directories and contain special transformations for Texi2html

        output. Again, when this file is inside language-specific

        directories the transformation have are applied to that

        language-specific XHTML output and when it is outside

        language-specific directories the transformations are applied

        to all language-specific XHTML outputs.  Most transformations

        achived through this file are to produce admonitions since

        Texinfo documentation format (as in

        <package>texinfo-4.8-14.el5</package>) doesn't have an

        internal command to build them.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <example id="manuals-formats-texinfo-templates-example1">

    <title>Texinfo document template</title>

    <screenshot>

    <screeninfo>Texinfo document template</screeninfo>

    <mediaobject>

    <textobject>

    <programlisting>trunk/Scripts/Bash/Functions/Help/Texinfo/Templates

|-- ${LANG}

|   |-- Chapters

|   |   |-- chapter-menu.texinfo

|   |   |-- chapter-nodes.texinfo

|   |   |-- chapter.texinfo

|   |   `-- section.texinfo

|   |-- Licenses

|   |   |-- GFDL.texinfo

|   |   |-- GPL.texinfo

|   |   |-- chapter-menu.texinfo

|   |   |-- chapter-nodes.texinfo

|   |   `-- chapter.texinfo

|   |-- manual-index.texinfo

|   |-- manual-init.pl

|   |-- manual-menu.texinfo

|   |-- manual-nodes.texinfo

|   |-- manual.conf

|   |-- manual.sed

|   `-- manual.texinfo

|-- manual-init.pl

`-- manual.sed</programlisting>

    </textobject>

    </mediaobject>

    </screenshot>

    </example>

    <para>

        Inside the directory structure of Texinfo document templates,

        the <filename class="directory">Chapters</filename> directory

        organizes chapter specific models used to create and maintain

        both chapter and sections files inside manuals. On the other

        hand, the <filename class="directory">Licenses</filename>

        directory organizes the license information linked from all

        manuals.  Notice the license information is not copied into

        documentation manuals when they are created, but refered from

        this location where they are maintained.  This configuration

        permites that all documentation manuals written in Texinfo

        format inside &TCAR; do use the same license information and

        if a change is committed to the license files, such changes be

        immediatly propagated to documentation manuals the next time

        their output files be updated.

    </para>

    </sect2>

    <sect2 id="manuals-formats-texinfo-macros">

    <title>Document Expansions</title>

    <para>

        The document expansions are special constructions used to

        generate content dynamically inside Texinfo source files.

    </para>

    <sect3>

    <title>The 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">trunk/Identity</filename> directory and want

        to create a linkable list of all documentation entries in the

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

        construction be expanded would look like the following:

    </para>

<screen>

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

@itemize

@item @ref{Trunk Identity Brushes}

@item @ref{Trunk Identity Fonts}

@item @ref{Trunk Identity Images}

@item @ref{Trunk Identity Models}

@item @ref{Trunk Identity Palettes}

@item @ref{Trunk Identity Patterns}

@item @ref{Trunk Identity Webenv}

@end itemize

@c -- ]>

</screen>

    <para>

        An interesting thing to notice here is that document

        expansions are executed each time the related documentation

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

        if the documentation entries related to directories under

        <filename class="directory">trunk/Identity</filename> changes

        for some reason (e.g., they are removed from documentation

        manual), the list generated as result of document expansion

        will be updated automatically after editing the documentation

        entry or updating the documentation manual structure.

    </para>

    </sect3>

    </sect2>

    <sect2 id="manuals-formats-texinfo-configuration">

    <title>Document Configuration</title>

    <para>

        The document configuration is stored in the 

        <filename>${MANUAL_NAME}.conf</filename> file, inside the

        documentation manual directory structure. This file is

        originally copied from <filename>manual.conf</filename>

        template file when the documentation manual is created for

        first time. The content of

        <filename>${MANUAL_NAME}.conf</filename> file is organized in

        sections. Each section here is written in one line of its own

        and have the form [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.

    </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 Internationalization</title>

    <para>

        To produce localized documentation manuals through Texinfo

        documentation format it is necessary to create one

        documentation manual for each language it is desired to

        support documentation for.  Documentation manuals created in

        this configuration don't have a direct relation among

        themselves except that one adopted by people writting them to

        keep their content syncronized.  In this configuration

        translators take one documentation manual as reference (a.k.a.

        the source manual) and produce several translated manuals

        based on its content.  To keep track of changes inside the

        source manual, the underlaying version control system must be

        used considering that there is no direct way to apply

        <application>gettext</application><footnote>

        <para>

            The <application>gettext</application> program  translates

            a  natural language message into the user's language, by

            looking up the translation in a message catalog. For more

            information about the <application>gettext</application>

            program, run <command>info gettext</command>.

        </para>

        </footnote> procedures to Texinfo source files.

    </para>

    <para>

        In order to maintain localization of Texinfo source files

        through <application>gettext</application> procedures, it is

        necessary to convert the Texinfo source files into

        XML format first.  This way it would be possible to make use of

        <function>locale</function> and <function>render</function>

        functionalities from <command>centos-art.sh</command> script

        to maintain translation messages in different languages

        through portable objets and producing localized XML files

        based on such portable objects, respectively.  Once the

        localized XML file is available, it would be a matter of using

        an XSLT processor (see the <command>xsltproc</command>

        command) to realize the convertion from XML to a localize

        Texinfo (or possible other) format.  Nevertheless, this

        workaround fails because the Document Type Definition (DTD)

        required to validate the XML file produced from

        <command>makeinfo</command> (as in

        <package>texinfo-4.8-14.el5</package>) is not availabe inside

        &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 <application>gettext</application>

        procedures would be to convert Texinfo source file to DocBook

        format; for who the required DTD and XSLT files are available

        inside &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

        <function>help</function> functionality of

        <command>centos-art.sh</command> script; unless you

        mistakently create the manual for a locale code different to

        that one you previously pretended to do in first place, of

        course.

    </para>

    <para>

        The language information used in both Texinfo source files and

        XHTML output produced by the <function>help</function>

        functionality of <command>centos-art.sh</command> script is

        determined by the user's session <envar>LANG</envar>

        environment variable.  This variable can be customized in the

        graphical login screen before login, or once you've login by

        explicitly setting the value of <envar>LANG</envar>

        environment variable inside the

        <filename>~/.bash_profile</filename> file.