From 98134aa0736833c9f9e2226bf0b484d8a5fc3050 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Jun 03 2011 17:44:35 +0000 Subject: Update repository documentation manual. --- diff --git a/Manuals/Texinfo/en_US/Directories/trunk/Scripts/Functions/Help/Backends/Texinfo.texinfo b/Manuals/Texinfo/en_US/Directories/trunk/Scripts/Functions/Help/Backends/Texinfo.texinfo index a001194..9f03f83 100644 --- a/Manuals/Texinfo/en_US/Directories/trunk/Scripts/Functions/Help/Backends/Texinfo.texinfo +++ b/Manuals/Texinfo/en_US/Directories/trunk/Scripts/Functions/Help/Backends/Texinfo.texinfo @@ -1,36 +1,74 @@ @subheading Goals -@itemize -@item ... -@end itemize +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 -When @code{texinfo} backend is used (default behaviour), the manual -structure (@pxref{Directories trunk Manuals}) is supported by GNU -Texinfo, a documentation system that can produce both online -information and a printed manual from a single source. The @code{help} -functionality is an interface you can use to control the source files -in the manual structure. - -The manual output is produced from Texinfo files and stored in -@file{trunk/Manuals/Texinfo} on different formats including Info, PDF, -XHTML, XML and TXT. - -When the @samp{texinfo} backend is used, you'll always edit -documentation entries in English language, no matter what your -prefered language be. This way, the output produced from them will -always be in English language. To achieve the manual localization in -your prefered language you need to apply the @code{locale} -functionality of @command{centos-art.sh} script (@pxref{Directories -trunk Scripts Functions Locale}) to any of the XML-based English -outputs supported by @command{centos-art.sh} script (e.g., XHTML) to -produce portable objects for your prefered language and the -@code{render} functionality of @command{centos-art.sh} script -(@pxref{Directories trunk Scripts Functions Render}) to produce the -translated version of the output XHTML files taken in first place. The -translated version is produced in the same format of the file taken as -reference to build the portable objects. XHTML format in this case. +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 backend is an interface the +@command{centos-art.sh} script uses to control the most frequent +documenting tasks (reading, editing, update output files, etc.) in the +source files of manual structure. + +@subsubheading Output + +The @code{texinfo} backend takes the repository documentation manual +in texinfo format as input and produces Info, Pdf, Xhtml and Txt +output files in the @file{trunk/Manuals/Texinfo/} directory structure. +The Info, Pdf and Txt output files are produced through +@command{makeinfo} command and the Xhtml output through +@command{texi2html} command. + +@subsubheading Paths + +The way absolute paths are defined inside the repository documentation +manual 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. + +@subsubheading Templates + +Document templates provide the structure information (i.e., how the +manual is organized), the language used () and the codification (). + +@subsubheading Internationalization + +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