texinfo ChangeLog doc/texinfo.txi util/htmlxref...

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       10/07/30 18:47:41

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 
        util           : htmlxref.cnf 

Log message:
        (i18n of strings): edit

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1083&r2=1.1084
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.273&r2=1.274
http://cvs.savannah.gnu.org/viewcvs/texinfo/util/htmlxref.cnf?cvsroot=texinfo&r1=1.3&r2=1.4

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1083
retrieving revision 1.1084
diff -u -b -r1.1083 -r1.1084
--- ChangeLog   27 Jul 2010 23:39:37 -0000      1.1083
+++ ChangeLog   30 Jul 2010 18:47:39 -0000      1.1084
@@ -1,3 +1,7 @@
+2010-07-30  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Internationalization of strings): edit node.
+
 2010-07-27  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi (texiany Output Customization, makeinfo

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.273
retrieving revision 1.274
diff -u -b -r1.273 -r1.274
--- doc/texinfo.txi     27 Jul 2010 23:39:37 -0000      1.273
+++ doc/texinfo.txi     30 Jul 2010 18:47:40 -0000      1.274
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.273 2010/07/27 23:39:37 karl Exp $
address@hidden $Id: texinfo.txi,v 1.274 2010/07/30 18:47:40 karl 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.
 
@@ -18699,7 +18699,7 @@
 * Customizing generalized block command opening:: 
 * Four contexts::             Four different contexts for command expansion: 
                               normal text, preformatted text, strings and math.
-* Internationalization of strings::
+* Internationalization of Strings::
 @end menu
 
 
@@ -19219,117 +19219,146 @@
 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 Internationalization of Strings
address@hidden Internationalization of Strings in the Output Document
 
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 I18n
address@hidden Internationalization of strings in the output document
address@hidden Output documentation, internationalization of
+
address@hidden documentlanguage @r{configuration variable}
address@hidden writes some fixed strings in the generated document
+at various places: for cross-references, in page footers, on the help
+page, alternate text for images, and so on.  The string chosen depends
+on the value of the configuration variable @code{documentlanguage} at
+the time of the string output (@pxref{documentlanguage}, for the
+Texinfo command interface).
+
address@hidden libintl-perl Gettext implementation
+The Gettext framework is used for those strings (@pxref{Top,,,
address@hidden, Gettext}).  The @code{libintl-perl} package is used as
+the @code{gettext} implementation; more specifically, the pure Perl
+implementation is used, so Texinfo can support consistent behavior
+across all platforms and installations, which would not otherwise be
+possible.  @code{libintl-perl} is included in the Texinfo distribution
+and always installed, to be sure that it is available if needed.  It
+is also possible to use the system @code{gettext}; currently decided
+at build-time).  
+
address@hidden texinfo_document Gettext domain
+The Gettext domain @samp{texinfo_document} is used for the strings,
+and the subroutine @code{gdt} 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 to a hash holding the variable parts of the translated
+string, and @var{\%state} a hash reference determining the context of
+expansion (e.g., use the document state, expansion in string, no
+expansion, @dots{}).
 @end 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 Perl format strings for translation
+Translated strings are written as Texinfo, and may include
+@@-commands.  In translated strings, the varying parts of the string
+are not usually denoted by @code{%s} and the like, but by
address@hidden@address@hidden  (This convention is common for @code{gettext} in
+Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl
+Format Strings, gettext, GNU Gettext}.)  For example, in the
+following, @address@hidden@}} will be replaced by the section name:
+
 @example
 see @address@hidden
 @end 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.
+These Perl-style brace format strings are used for two reasons: first,
+changing the order of @code{printf} arguments is only available since
address@hidden; second, and more importantly, the order of the
+argument is unpredictable, since @@-command expansion may lead to
+different orders depending on the output format.  The expansion of
+a translation string is done like this:
 
-The expansion of those strings happens that way:
 @enumerate
address@hidden First the string is translated.  The locale 
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 
address@hidden @code{us-ascii} encoding, and translations
+If the @@documentlanguage is like @var{ll_CC}, @var{ll_CC} is tried
+first, and then @var{ll}.  If that does not exist, and the encoding is
+not @code{us-ascii}, then @code{us-ascii} is tried.  The idea is that
+if there is a @code{us-ascii} encoding, it means that all the
+characters in the charset may be expressed as @@-commands.  For
+example, there is a @code{fr.us-ascii} locale that can accomodate any
+encoding, since all the address@hidden characters have associated
+@@-commands.  On the other hand, Japanese has only a translation
address@hidden, since there are no @@-commands for Japanese characters.
+
address@hidden Next, the args in string are protected, for example
address@hidden@address@hidden becomes
address@hidden@@address@hidden@}arg_name@@address@hidden@}}
+(this part is skipped if there is nothing to expand).
+
address@hidden Next, the string is expanded as a Texinfo string.
address@hidden@@address@hidden@}} expands to @{ and
address@hidden@@address@hidden@}} expands to @}, such 
 that in the end one still gets @address@hidden@}} within an expanded 
-string (this part is skipped if there is no expansion).
+string (this part is skipped if there is nothing to expand).
+
address@hidden Then the arguments are substituted; for 
+Example, @address@hidden@}} is replace by the corresponding actual
+argument.
 
address@hidden Then the in string arguments are substituted, for 
-example @address@hidden@}} is substituted by the corresponding argument.
 @end 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:
+In the following example, @address@hidden@}}, @address@hidden@}}
+and @address@hidden@}} are the arguments of the string.  Since they
+are used in @code{@@uref}, their order is not predictable.  The
address@hidden@{'duplicate'=>address@hidden means that 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('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'=>1,
+   @});
address@hidden example
+
+This approach is a bit complicated.  What is useful is that it
+supports having translations available in different encodings for
+encodings which can be covered by @@-commands, and also specifying how
+the formatting for some commands is done, independently of the output
+format yet still be language dependent.  For example, a
address@hidden@@pxref} translation string may be:
 
 @example
 see @address@hidden section address@hidden@}\' in 
@@address@hidden@address@hidden@}
 @end 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
+which allows specifying a string independently of the output format
+but with a rich formatting that may be translated appropriately in
+many languages.
+
+Expansion can be prevented via @code{keep_texi} in the @code{state} hash.
+
+When a @code{@@documentlanguage} line appears in the document and the
+language was not set on the command line, it is convenient for the
+translations to redefine some variables based on the new language.
+Therefore, Texinfo has a function reference which is called each time
 @code{@@documentlanguage} is encountered:
 
 @deffn {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.
+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 strings based on the new language.
 @end deffn
 
 
@@ -24199,7 +24228,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.273 2010/07/27 23:39:37 karl Exp $
+$Id: texinfo.txi,v 1.274 2010/07/30 18:47:40 karl 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}
@@ -24278,7 +24307,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.273 2010/07/27 23:39:37 karl Exp $
address@hidden $Id: texinfo.txi,v 1.274 2010/07/30 18:47:40 karl Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi

Index: util/htmlxref.cnf
===================================================================
RCS file: /sources/texinfo/texinfo/util/htmlxref.cnf,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- util/htmlxref.cnf   29 Jul 2010 00:55:44 -0000      1.3
+++ util/htmlxref.cnf   30 Jul 2010 18:47:41 -0000      1.4
@@ -1,5 +1,5 @@
 # htmlxref.cnf - reference file for Texinfo files on the web.
-htmlxrefversion=2010-07-29.00; # UTC
+htmlxrefversion=2010-07-30.17; # UTC
 
 # Copyright 2010 Free Software Foundation, Inc.
 # 
@@ -18,6 +18,10 @@
 R = http://www.gnu.org
 RS = ${R}/software
 
+anubis         chapter ${RS}/anubis/manual/html_chapter/
+anubis         section ${RS}/anubis/manual/html_section/
+anubis         node    ${RS}/anubis/manual/html_node/
+
 autoconf       mono    ${RS}/autoconf/manual/autoconf.html
 autoconf       node    ${RS}/autoconf/manual/html_node/
 
@@ -48,13 +52,27 @@
 gnat_ugn_unw   node    http://gcc.gnu.org/onlinedocs/gnat_ugn_unw/
 libgomp                node    http://gcc.gnu.org/onlinedocs/libgomp/
 
+gnus           mono    ${RS}/emacs/manual/html_node/mh-e/
+gnus           node    ${RS}/emacs/manual/html_mono/mh-e.html
+
 gnuschool      mono    ${RS}/gnuschool/gnuschool.html
 
+gtypist                mono    ${RS}/gtypist/doc/
+
 libextractor   mono    ${RS}/libextractor/extractor.html
 
+mailutils      mono    ${RS}/mailutils/manual/mailutils.html
+mailutils      node    ${RS}/mailutils/manual/html_node/
+
 maintain       mono    ${R}/prep/maintain/maintain.html
 maintain       node    ${R}/prep/maintain/html_node/
 
+mdk            mono    ${RS}/mdk/manual/mdk.html
+mdk            node    ${RS}/mdk/manual/html_node/
+
+mh-e           mono    ${RS}/emacs/manual/html_node/mh-e/
+mh-e           node    ${RS}/emacs/manual/html_mono/mh-e.html
+
 standards      mono    ${R}/prep/standards/standards.html
 standards      node    ${R}/prep/standards/html_node/