texinfo doc/texinfo.txi doc/draft_api.texi Chan...

[Patrice Dumas]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Patrice Dumas <pertusus>        13/01/08 21:57:04

Modified files:
        doc            : texinfo.txi draft_api.texi 
        .              : ChangeLog 

Log message:
                * doc/texinfo.txi (Internationalization of Strings), 
doc/draft_api.texi
                (Internationalization of Strings Function): re-add the text 
about
                translated strings in the manual keeping only the perl api 
information
                in draft_api.texi.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.516&r2=1.517
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/draft_api.texi?cvsroot=texinfo&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1506&r2=1.1507

Patches:
Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.516
retrieving revision 1.517
diff -u -b -r1.516 -r1.517
--- doc/texinfo.txi     8 Jan 2013 16:20:43 -0000       1.516
+++ doc/texinfo.txi     8 Jan 2013 21:57:03 -0000       1.517
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.516 2013/01/08 16:20:43 karl Exp $
address@hidden $Id: texinfo.txi,v 1.517 2013/01/08 21:57:03 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.
 
@@ -603,6 +603,7 @@
 * Invoking texi2any::        Running the translator from a shell.
 * texi2any Printed Output::  Calling @command{texi2dvi}.
 * Pointer Validation::       How to check that pointers point somewhere.
+* Internationalization of Strings::
 * Customization Variables::  Configuring @command{texi2any}.
 * texi2html::                An ancestor of @command{texi2any}.
 
@@ -656,17 +657,6 @@
 * Configuration:     HTML Xref Configuration.      htmlxref.cnf.
 * Preserving links:  HTML Xref Link Preservation.  MANUAL-noderename.cnf.
 
address@hidden Output Customization
-
-* Loading Init Files::               Finding and writing initialization files.
-* Init File Basics::                 What init files can contain and do.
-
-Init File Basics
-
-* Init File Namespaces:: @code{Texinfo::Config}.
-* Setting and Getting Customization Variables::
-* Internationalization of Strings::
-
 @@-Command List
 
 * Command Syntax::    General syntax for varieties of @@-commands.
@@ -16629,6 +16619,7 @@
 * Invoking texi2any::        Running the translator from a shell.
 * texi2any Printed Output::  Calling @command{texi2dvi}.
 * Pointer Validation::       How to check that pointers point somewhere.
+* Internationalization of Strings::
 * Customization Variables::  Configuring @command{texi2any}.
 * texi2html::                An ancestor of @command{texi2any}.
 @end menu
@@ -17292,6 +17283,102 @@
 @code{makeinfo} checks that every node except the `Top' node is
 referenced in a menu.
 
address@hidden Internationalization of Strings
address@hidden Internationalization of Strings in the Output Document
+
address@hidden I18n
address@hidden Internationalization of strings in the output document
address@hidden Output documentation, internationalization of
+
address@hidden documentlanguage @r{customization 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 @code{documentlanguage} at the time of the string 
+being output (@address@hidden@@documentlanguage}}, for the Texinfo command 
+interface).
+
address@hidden libintl-perl @r{Gettext implementation}
+The Gettext framework is used for those strings (@pxref{,,,
+gettext, 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 @r{Gettext domain}
address@hidden Perl format strings for translation
+The Gettext domain @samp{texinfo_document} is used for the strings.
+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:
+
address@hidden
+see @address@hidden
address@hidden example
+
+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:
+
address@hidden
address@hidden First, the string is translated.  The locale 
+is @var{@@address@hidden@var{@@documentencoding}.
+
address@hidden @code{us-ascii} encoding, and translations
+If the @var{@@documentlanguage} has the form @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 accommodate 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 string is expanded as Texinfo, and converted.
+The arguments are substituted; for example, @address@hidden@}} is 
+replaced by the corresponding actual argument.
+
address@hidden enumerate
+
+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.
address@hidden@address@hidden, @address@hidden@}} and @address@hidden@}} are 
+substituted after the expansion:
+
address@hidden
+Generated on @@address@hidden@address@hidden@} using
+@@address@hidden@address@hidden, @@address@hidden@address@hidden@address@hidden
address@hidden example
+
+This approach is admittedly a bit complicated.  Its usefulness 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, an
address@hidden@@pxref} translation string may be:
+
address@hidden
+see @address@hidden section address@hidden@}\' in 
@@address@hidden@address@hidden@}
address@hidden example
+
address@hidden
+which allows specifying a string independently of the output format,
+but with rich formatting that may be translated appropriately in many
+languages.
 
 @node Customization Variables
 @section Customization Variables
@@ -21813,7 +21900,7 @@
 as:
 
 @example
-$Id: texinfo.txi,v 1.516 2013/01/08 16:20:43 karl Exp $
+$Id: texinfo.txi,v 1.517 2013/01/08 21:57:03 pertusus Exp $
 @end example
 
 (This is potentially useful in all sources that use version control,

Index: doc/draft_api.texi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/draft_api.texi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- doc/draft_api.texi  15 Sep 2012 18:06:53 -0000      1.1
+++ doc/draft_api.texi  8 Jan 2013 21:57:03 -0000       1.2
@@ -255,36 +255,11 @@
 @end ignore
 
 
address@hidden Internationalization of Strings
address@hidden Internationalization of Strings in the Output Document
-
address@hidden I18n
address@hidden Internationalization of strings in the output document
address@hidden Output documentation, internationalization of
-
address@hidden documentlanguage @r{customization 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 customization variable @code{documentlanguage} at
-the time of the string being output (@pxref{documentlanguage}, for the
-Texinfo command interface).
-
address@hidden libintl-perl @r{Gettext implementation}
-The Gettext framework is used for those strings (@pxref{Top,,,
-gettext, 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 Internationalization of Strings Function
address@hidden Internationalization of Strings in the Output Document Function
 
 @vindex texinfo_document @r{Gettext domain}
-The Gettext domain @samp{texinfo_document} is used for the strings,
-and the subroutine @code{gdt} is used for translated
-strings:
+The subroutine @code{gdt} is used for translated strings:
 
 @defun gdt (\%converter, $string, \%variables_hash)
 @var{$string} is the string to be translated, @var{\%variables_hash}
@@ -293,49 +268,11 @@
 about the context.  The result returned is a perl Texinfo tree.
 @end defun
 
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:
-
address@hidden
-see @address@hidden
address@hidden example
-
-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:
-
address@hidden
address@hidden First, the string is translated.  The locale 
-is @var{@@address@hidden@var{@@documentencoding}.
-
address@hidden @code{us-ascii} encoding, and translations
-If the @var{@@documentlanguage} has the form @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 accommodate 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 string is expanded as Texinfo, and converted to a
-Texinfo tree in perl.
-The arguments are substituted; for example, @address@hidden@}} is 
-replaced by the corresponding actual argument, which should be 
-Texinfo perl trees or Texinfo perl tree contents arrays.
-
address@hidden enumerate
+When the string is expanded as Texinfo, and converted to a
+Texinfo tree in perl, the arguments are substituted; for 
+example, @address@hidden@}} is replaced by the corresponding 
+actual argument, which should be Texinfo perl trees or Texinfo 
+perl tree contents arrays.
 
 In the following example, @address@hidden@}}, @address@hidden@}}
 and @address@hidden@}} are the arguments of the string.  Since they
@@ -356,21 +293,3 @@
    );
 @end example
 
-This approach is admittedly a bit complicated.  Its usefulness 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, an
address@hidden@@pxref} translation string may be:
-
address@hidden
-see @address@hidden section address@hidden@}\' in 
@@address@hidden@address@hidden@}
address@hidden example
-
address@hidden
-which allows specifying a string independently of the output format,
-but with rich formatting that may be translated appropriately in many
-languages.
-
-
address@hidden Command List

Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1506
retrieving revision 1.1507
diff -u -b -r1.1506 -r1.1507
--- ChangeLog   8 Jan 2013 21:02:06 -0000       1.1506
+++ ChangeLog   8 Jan 2013 21:57:04 -0000       1.1507
@@ -2,6 +2,10 @@
 
        * po_document/fr.us-ascii.po: update by Jean-Charles Malahieude,
        with additional edits.
+       * doc/texinfo.txi (Internationalization of Strings), doc/draft_api.texi
+       (Internationalization of Strings Function): re-add the text about
+       translated strings in the manual keeping only the perl api information
+       in draft_api.texi.
 
 2013-01-08  Karl Berry  <address@hidden>