[no subject]

[Patrice Dumas]

branch: master
commit d46231fcb2fdee9a6d8f28369ef8e3701fd9ed89
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Tue Nov 26 23:50:31 2024 +0100

    * doc/texinfo.texi (Internationalization of Document Strings): move
    details on libintl implementations used to the end, and update to be
    clearer now that there is also a C implementation.
    Describe that braced argument for varying parts of the strings are
    used before telling that %s is not used.
    Remove argument on Perl version, we require that version already.
    Put in an @ignore block the justification of using braced argument for
    variable strings, there is no need for a justification.
    Remove the point on encoding, it is not important nowadays that UTF-8
    is generally used.
---
 ChangeLog        | 13 +++++++++++++
 doc/texinfo.texi | 53 +++++++++++++++++++++++++++--------------------------
 2 files changed, 40 insertions(+), 26 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 5f0d28abc4..4a0ef7b076 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2024-11-26  Patrice Dumas  <pertusus@free.fr>
+
+       * doc/texinfo.texi (Internationalization of Document Strings): move
+       details on libintl implementations used to the end, and update to be
+       clearer now that there is also a C implementation.
+       Describe that braced argument for varying parts of the strings are
+       used before telling that %s is not used.
+       Remove argument on Perl version, we require that version already.
+       Put in an @ignore block the justification of using braced argument for
+       variable strings, there is no need for a justification.  
+       Remove the point on encoding, it is not important nowadays that UTF-8
+       is generally used.
+
 2024-11-26  Gavin Smith <gavinsmith0123@gmail.com>
 
        * doc/texinfo.texi (@definfoenclose, Generating HTML)
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index f5736a51d1..132d81b365 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -16170,37 +16170,28 @@ the value of the @code{documentlanguage} at the time 
of the string
 being output (@pxref{@code{@@documentlanguage}}, for the Texinfo
 command interface).
 
-@pindex 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 ensure that it is available if needed.  It is
-also possible to use the system @code{gettext} (the choice can be made
-at build-time).
-
 @vindex texinfo_document @r{Gettext domain}
 @cindex Perl format strings for translation
-The Gettext domain @samp{texinfo_document} is used for the strings.
+The Gettext framework with the @samp{texinfo_document} domain
+is used for those strings (@pxref{Top,,, gettext, Gettext}).
 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
-@samp{@{arg_name@}}.  (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, @samp{@{section@}} will be replaced by the section name:
+are denoted by @samp{@{arg_name@}}, but not by @code{%s} and the like.
+(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, @samp{@{section@}}
+will be replaced by the section name:
 
 @example
 see @{section@}
 @end example
 
-These Perl-style brace format strings are used for two reasons: first,
-changing the order of @code{printf} arguments is only available since
-Perl@tie{}5.8.0; second, and more importantly, the order of arguments
+@c Ignore, there is no need to justify this choice
+@ignore
+These Perl-style brace format strings are used because the order of arguments
 is unpredictable, since @@-command expansion may lead to different
 orders depending on the output format.
+@end ignore
 
 The expansion of a translation string is done like this:
 
@@ -16232,12 +16223,11 @@ Generated on @@emph@{@{date@}@} using
 @@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}.
 @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, the
-@samp{@@pxref} translation string can be like this:
+This approach is admittedly a bit complicated.  Its usefulness is that it
+supports specifying the formatting of the translated string independently
+of the output format.
+
+For example, the @samp{@@pxref} translation string can be like this:
 
 @example
 see @{node_file_href@} section `@{section@}' in @@cite@{@{book@}@}
@@ -16248,6 +16238,17 @@ which allows for specifying a string independently of 
the output
 format, while nevertheless with rich formatting it may be translated
 appropriately in many languages.
 
+@c TODO Seems like an implementation detail.  Remove?
+@pindex libintl-perl @r{Gettext implementation}
+If Perl is used for strings translation in @command{texi2any}, 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 ensure that it is available if needed.
+It is also possible to use the system @code{libintl-perl} (the choice can be
+made at build-time).
+
 
 @node Invoking @command{pod2texi}
 @nodedescription Translating Perl Pod to Texinfo.