texinfo ChangeLog doc/texinfo.txi

[Patrice Dumas]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Patrice Dumas <pertusus>        10/07/25 21:38:15

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
                * doc/texinfo.txi (Internationalization of strings): add this 
node
                describing the internationalization of strings output in 
texi2any.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1074&r2=1.1075
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.267&r2=1.268

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1074
retrieving revision 1.1075
diff -u -b -r1.1074 -r1.1075
--- ChangeLog   25 Jul 2010 17:35:49 -0000      1.1074
+++ ChangeLog   25 Jul 2010 21:38:14 -0000      1.1075
@@ -1,5 +1,10 @@
 2010-07-25  Patrice Dumas  <address@hidden>
 
+       * doc/texinfo.txi (Internationalization of strings): add this node
+       describing the internationalization of strings output in texi2any.
+
+2010-07-25  Patrice Dumas  <address@hidden>
+
        * doc/texinfo.txi: update the documentation of texi2any 
        customization to match the current state of the code.
 

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.267
retrieving revision 1.268
diff -u -b -r1.267 -r1.268
--- doc/texinfo.txi     25 Jul 2010 17:35:49 -0000      1.267
+++ doc/texinfo.txi     25 Jul 2010 21:38:15 -0000      1.268
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.267 2010/07/25 17:35:49 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.268 2010/07/25 21:38:15 pertusus Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -18678,6 +18678,7 @@
 * Customizing generalized block command opening:: 
 * Four contexts::             Four different contexts for command expansion: 
                               normal text, preformatted text, strings and math.
+* Internationalization of strings::
 @end menu
 
 
@@ -19197,6 +19198,120 @@
 Currently in @code{@@math}.
 @end table
 
address@hidden Internationalization of strings
address@hidden Internationalization of strings output in the document
+
address@hidden i18n
+
address@hidden writes some strings in the generated document at
+various places, at the page footers, on the help page, for special
+section headings, buttons alt text and so on.
+The string chosen depends on the value of the configuration variable
address@hidden at the time of the string output.
+
+The Gettext framework is used for those strings.  libintl-perl is used as
+a gettext implementation for the string output, and more precisely the
+pure perl implementation is used, to be sure to have a consistent gettext-like
+implementation which may not the case if the system gettext is used.  
+libintl-perl is shipped in texi2html and installed to be sure that it 
+is available.  It is also possible to use the system gettext (currently 
+decided at build-time).  The @samp{texifo_document} domain is used for the 
+strings. 
+
+The @code{gdt} subroutine is used for translated strings:
+
address@hidden {gdt} ($string, \%variables_hash, \%state)
+with @var{$string} the string to be translated, @var{\%variables_hash} a
+reference on a hash holding the variable parts of the translated string, and 
address@hidden a hash reference determining the context of expansion 
+(use the document state, expansion in string, no expansion...).
address@hidden defun
+
+Translated strings are Texinfo strings, which may have @@-commands.
+In translated strings, the variables parts of the string are not denoted 
+by %s and the like, but by @address@hidden@}} (which is common for gettext
+in Perl and is fully supported in GNU gettext, @ref{perl-format,,Perl Format 
Strings,gettext,GNU gettext tools}).
+For example, in the following, @address@hidden@}} will be replaced by the 
+section name:
address@hidden
+see @address@hidden
address@hidden example
+
+The use of the perl brace format strings is done for two reasons, first 
+changing the order of printf arguments is only available since perl 5.8.0, 
+second, and more importantly, the order of the argument may not be 
+predictable when @@-commands expansion may lead to different orders 
+depending on the output format.
+
+The expansion of those strings happens that way:
address@hidden
address@hidden First the string is translated.  The locale 
+is @@documentlanguage.@@documentencoding.
+
+If the @@documentlanguage is like ll_CC, ll_CC is tried first, and then ll.
+If the encoding is not us-ascii, us-ascii is also tried.  The idea is that
+if there is a us-ascii encoding, it means that all the characters in the
+charset may be expressed as @@-commands.   For example there is a fr.us-ascii
+locale that can accomodate any encoding, since all the latin1 characters
+have associated @@-commands.  For the ja translations, there is only ja.utf-8
+since there are no @@-commands for ja letters.
+
address@hidden Next the args in string are protected, for example 
@address@hidden@}} 
+becomes
address@hidden@@address@hidden@}arg_name@@address@hidden@}} (this part is 
skipped if there is no expansion).
+
address@hidden Next the string is expanded as a texinfo string.
address@hidden@@address@hidden@}} expands as @{ and
address@hidden@@address@hidden@}} expands as @}, such 
+that in the end one still gets @address@hidden@}} within an expanded 
+string (this part is skipped if there is no expansion).
+
address@hidden Then the in string arguments are substituted, for 
+example @address@hidden@}} is substituted by the corresponding argument.
address@hidden enumerate
+
+For example, in the following @address@hidden@}}, @address@hidden@}} 
+and @address@hidden@}} are the argument of the string.  Since they are used 
+in @code{@@uref}, their order in not predictable.  The 
@address@hidden'duplicate'=>address@hidden
+means the the document state should be used when expanding the string. 
address@hidden@address@hidden, @address@hidden@}} and @address@hidden@}}
+are substituted after the expansion, which means that they
+should already be acceptable output:
+
address@hidden
+gdt('This document was generated on @@address@hidden@address@hidden@} using 
@@address@hidden@address@hidden, 
@@address@hidden@address@hidden@address@hidden', @{
+           'date' => $date, 'program_homepage' => 
$Texi2HTML::address@hidden'program_homepage'@}, 'program' => 
$Texi2HTML::address@hidden'program_and_version'@} 
@},@{'duplicate'=>address@hidden);
address@hidden example
+
+This approach is a bit complicated, however what is interesting is that
+it allows to have translation available in different encodings for charset
+that are covered by @@-commands, and also to specify how the formatting for
+some commands is done independently of the output format but still allow it to
+be language dependent.  For example, the @samp{@@pxref} string may be:
+
address@hidden
+see @address@hidden section address@hidden@}\' in 
@@address@hidden@address@hidden@}
address@hidden example
+
+which allows to specify a string independently of the output format but with a
+rich formatting that may be differently translated in other languages.
+
+It is also possible to use more regular %s escapes, and also avoid any
+expansion (with @code{keep_texi} in the state).
+
+When a @code{@@documentlanguage} appears in the document and the language
+was not set on the command line, it may be convenient for the user to
+redefine some variables based on the new language.  There is a function
+reference that may be used for that, it is called each time  a
address@hidden@@documentlanguage} is encountered:
+
address@hidden {Function Reference} $translate_names
+This function is called each time @code{@@documentlanguage} is encountered
+and the language was not set on the command line.  It should be used
+to retranslate some strings based on the new language.
address@hidden deffn
+
+
 @node Elements
 @section Elements and associated informations
 
@@ -24063,7 +24178,7 @@
 (@url{http://www.gnu.org/software/rcs}) version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.267 2010/07/25 17:35:49 pertusus Exp $
+$Id: texinfo.txi,v 1.268 2010/07/25 21:38:15 pertusus Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -24142,7 +24257,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.267 2010/07/25 17:35:49 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.268 2010/07/25 21:38:15 pertusus Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi