@subheading Goals

The @file{trunk/Scripts/Functions/Help/Backends/Texinfo} directory

structure organizes the `texinfo' backend used by @code{help}

functionality to manage the repository documentation manual

(@pxref{Directories trunk Manuals}).

@subheading Description

The @code{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 @code{texinfo} backend is an

interface the @command{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 @code{texinfo} backend takes the repository documentation manual

in texinfo format as input and produces Info, Pdf, XML, Xhtml and Txt

output files in the @file{trunk/Manuals/Texinfo/$LANG} directory

structure, where @var{$LANG} represents the language of the manual.

The Info, Pdf and Txt output files are produced through

@command{makeinfo} command and the Xhtml output through

@command{texi2html} command. Using the @command{makeinfo} command it

is also possible to output the repository documentation manual in

Docbook format, however, the output produced by @command{makeinfo}

command seems to have some malformations, so the @samp{docbook}

backend is considered instead (@pxref{Directories trunk Scripts

Functions Help Backends Docbook}). 

When producing Xhtml output, through @command{texi2html} command, the

output customization is controlled by common and specific

configuration files. Common configuration files are stored in

@file{trunk/Manuals/Texinfo} and include @file{repository.css},

@file{repository-init.pl} and @file{repository.sed}. Specific

configuration files, on the other hand, are stored inside

backend-specific directories (e.g.,

@file{trunk/Scripts/Functions/Help/Backends/Texinfo/Templates/$LANG})

and includes @file{repository-init.pl}, @file{repository.conf},

@file{repository.sed}.

When writting texinfo files, produced by @samp{texinfo} backend, the

way absolute paths are defined is important.  Absolute paths

definitions (e.g., through `@@include' and `@@image') must be set from

@file{trunk/} directory structure on.  This is necessary because the

documentation manual is exported using @file{@var{$HOME}/artwork}

directory structure as base.

Internationalization of repository documentation manual is performed

trough document templates and the @env{LANG} environment variable.

There is one repository documentation manual for each locale specified

by @env{LANG} environment variable. When no template is available for

a specific language, the @code{en_US} templates are used as reference.

Each repository documentation manual written in language other than

English, must include the @samp{@@documentlanguage} and

@samp{@@documentencoding} directives in the main document file (e.g.,

@file{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 @samp{US-ASCII}, @samp{ISO-8859-1},

@samp{ISO-8859-15} or @samp{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., @samp{@@'a}, @samp{@@~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.,

@command{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

@command{texi2html} command to transform special characters to HTML

entities (e.g., @samp{á}, @samp{ñ}, etc.).  In the Pdf

output, special characters are printed well most of times with some

exceptions (e.g., the @samp{@@'i} don't replaces the dot over the

letter with the accentuation, but put the accentuation over it.).

@subheading Usage

The @samp{texinfo} backend is the default backend used by @code{help}

functionality when no @option{--backend} option is provided to

@command{centos-art.sh} script; or when it is explicitly specified

(e.g., @option{--backend="texinfo"}).

@subheading See also

@itemize

@item @ref{Directories trunk Scripts Functions Help Backends} 

@item @ref{Directories trunk Scripts Functions Help} 

@item @ref{Directories trunk Scripts Functions} 

@item @ref{Directories trunk Scripts} 

@item @ref{Directories trunk}

@end itemize