Goals
-----

The trunk/Scripts/Functions/Help/Backends/Texinfo directory structure organizes the `texinfo' backend used by help functionality to manage the repository documentation manual (see Directories trunk Manuals).

Description
-----------

The texinfo backend is supported by GNU Texinfo, a documentation system that can produce both online information and a printed manual from a single source. The texinfo backend is an interface the centos-art.sh script uses to control the frequent documenting tasks (e.g., reading, editing, update output files, etc.) in the source files of a Texinfo documentation manual structure.

The texinfo backend takes the repository documentation manual in texinfo format as input and produces Info, Pdf, XML, Xhtml and Txt output files in the trunk/Manuals/Texinfo/$LANG directory structure, where $LANG represents the language of the manual. The Info, Pdf and Txt output files are produced through makeinfo command and the Xhtml output through texi2html command. Using the makeinfo command it is also possible to output the repository documentation manual in Docbook format, however, the output produced by makeinfo command seems to have some malformations, so the docbook backend is considered instead (see Directories trunk Scripts Functions Help Backends Docbook).

When producing Xhtml output, through texi2html command, the output customization is controlled by common and specific configuration files. Common configuration files are stored in trunk/Manuals/Texinfo and include repository.css, repository-init.pl and repository.sed. Specific configuration files, on the other hand, are stored inside backend-specific directories (e.g., trunk/Scripts/Functions/Help/Backends/Texinfo/Templates/$LANG) and includes repository-init.pl, repository.conf, repository.sed.

When writting texinfo files, produced by texinfo backend, the way absolute paths are defined is important.  Absolute paths definitions (e.g., through `@include' and `@image') must be set from trunk/ directory structure on.  This is necessary because the documentation manual is exported using $HOME/artwork directory structure as base.

Internationalization of repository documentation manual is performed trough document templates and the LANG environment variable. There is one repository documentation manual for each locale specified by LANG environment variable. When no template is available for a specific language, the en_US templates are used as reference.

Each repository documentation manual written in language other than English, must include the @documentlanguage and @documentencoding directives in the main document file (e.g., repository.texinfo) to provide the language and encoding information respectively.  The language information can be any value specified by ISO-639 language code standard and the ecoding informormation can be either US-ASCII, ISO-8859-1, ISO-8859-15 or ISO-8859-2.

The encoding information is required in order for Txt and Info outputs to show special characters, defined through Texinfo special way of accentuation (e.g., @'a, @~n, etc.), correctly. In this specific case, to read both Txt and Info files, it is required that the terminal you are performing the reading action (e.g., gnome-terminal) be encoded with the same value you specified inside the repository documentation manual. Otherwise, special characters may not look as expected.

Using Texinfo special way of accentuation is also required for texi2html command to transform special characters to HTML entities (e.g., &aacute;, &ntilde;, etc.).  In the Pdf output, special characters are printed well most of times with some exceptions (e.g., the @'i don't replaces the dot over the letter with the accentuation, but put the accentuation over it.).

Usage
-----

The texinfo backend is the default backend used by help functionality when no --backend option is provided to centos-art.sh script; or when it is explicitly specified (e.g., --backend="texinfo").

See also
--------

  * Directories trunk Scripts Functions Help Backends

  * Directories trunk Scripts Functions Help

  * Directories trunk Scripts Functions

  * Directories trunk Scripts

  * Directories trunk