[no subject]

[Patrice Dumas]

branch: master
commit 9f7ca354ff5a8a9bbfd72d120c25da6d54ac51ca
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Oct 29 21:28:20 2022 +0200

    Add optional translation context for in-document string translations
    
    * doc/texi2any_api.texi (Internationalization of Strings Function),
    tp/Texinfo/Translations.pm (gdt, pgdt), po_document/Makevars
    (XGETTEXT_OPTIONS), tp/Texinfo/Convert/HTML.pm (_translate_names):
    add a translation context argument to gdt() and add pgdt() which
    has the translation context as first argument.
    Update po_document/Makevars to have pgdt arguments in the correct
    order.
---
 ChangeLog                   | 13 ++++++++++++-
 doc/texi2any_api.texi       | 20 ++++++++++++++++----
 tp/Texinfo/Convert/HTML.pm  |  3 ++-
 tp/Texinfo/Convert/LaTeX.pm |  2 +-
 tp/Texinfo/Convert/Utils.pm |  4 ++--
 tp/Texinfo/Translations.pm  | 41 ++++++++++++++++++++++++++++++++++-------
 6 files changed, 67 insertions(+), 16 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 883475b781..5fdf429089 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -19,7 +19,18 @@
        initialize ACTIVE_ICONS and PASSIVE_ICONS to empty strings, instead
        set to undef the customization variables as a whole.
 
+2022-10-27  Patrice Dumas  <pertusus@free.fr>
+
+       Add optional translation context for in-document string translations
+
+       * doc/texi2any_api.texi (Internationalization of Strings Function),
+       tp/Texinfo/Translations.pm (gdt, pgdt), po_document/Makevars
+       (XGETTEXT_OPTIONS), tp/Texinfo/Convert/HTML.pm (_translate_names):
+       add a translation context argument to gdt() and add pgdt() which
+       has the translation context as first argument.
+       Update po_document/Makevars to have pgdt arguments in the correct
+       order.
+
 2022-11-07  Gavin Smith  <gavinsmith0123@gmail.com>
 
        * README-hacking: new ChangeLog file done
-
diff --git a/doc/texi2any_api.texi b/doc/texi2any_api.texi
index 2d555f243e..4d68e4dd27 100644
--- a/doc/texi2any_api.texi
+++ b/doc/texi2any_api.texi
@@ -1317,13 +1317,25 @@ the default code can be used in practice.
 @end quotation
 
 @vindex texinfo_document @r{Gettext domain}
-The subroutine @code{gdt}, from the @code{Texinfo::Translations} module
-is used for translated strings:
+The subroutines @code{gdt} or @code{pgdt}, from the
+@code{Texinfo::Translations} module is used for translated strings:
 
-@deftypefun {@var{$translated_tree} =} @var{$converter}->gdt (@var{$string}, 
@var{\%variables_hash})
+@deftypefun {@var{$translated_tree} =} @var{$converter}->gdt (@var{$string}, 
@var{\%variables_hash}, @var{$message_context})
+@deftypefunx {@var{$translated_tree} =} @var{$converter}->pgdt 
(@var{$message_context}, @var{$string}, @var{\%variables_hash})
 @var{$string} is the string to be translated, @var{\%variables_hash}
 is a hash reference holding the variable parts of the translated
-string.  The result returned is a perl Texinfo tree.
+string.   @var{$message_context} is an optional translation context
+that limits the search of the translated string to that context
+(@pxref{Contexts,,,gettext,GNU gettext tools}).
+The result returned is a perl Texinfo tree.
+
+If called as @code{pgdt}, @var{$message_context} is not optional
+and is the first argument.  @code{pgdt} is used to mark
+that the translated string has a context for tools extracting
+translatable strings to produce template files, which is not the case for
+@code{gdt}.  Since it is unlikely that marking a string for translation
+is of use in a user-defined code, @code{gdt} should be usable in all
+the cases.
 @end deftypefun
 
 When the string is expanded as Texinfo, and converted to a
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index fce91f2b33..7806e342f0 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -1903,6 +1903,7 @@ my %default_translated_directions_strings = (
      ' ' =>           {'converted' => ' '.$html_default_entity_nbsp.' '},
      'Top' =>         {'to_convert' => Texinfo::Common::gdt('Top')},
      'Contents' =>    {'to_convert' => Texinfo::Common::gdt('Contents')},
+                        # pgdt('Contents direction string text', 'Contents')
      'Overview' =>    {'to_convert' => Texinfo::Common::gdt('Overview')},
      'Index' =>       {'to_convert' => Texinfo::Common::gdt('Index')},
      'This' =>        {'to_convert' => Texinfo::Common::gdt('current')},
@@ -2049,7 +2050,7 @@ sub _translate_names($)
         $translated_commands{$command} = 1;
         $self->{'no_arg_commands_formatting'}->{$context}->{$command}->{'text'}
          = 
$self->gdt($self->{'no_arg_commands_formatting'}->{$context}->{$command}->{'translated'},
-                      undef, 'translated_text');
+                      undef, undef, 'translated_text');
       } elsif ($context eq 'normal') {
         # default translated commands
         my $translated_tree = 
Texinfo::Convert::Utils::translated_command_tree($self,
diff --git a/tp/Texinfo/Convert/LaTeX.pm b/tp/Texinfo/Convert/LaTeX.pm
index 892cf7a7a7..9275683e72 100644
--- a/tp/Texinfo/Convert/LaTeX.pm
+++ b/tp/Texinfo/Convert/LaTeX.pm
@@ -2743,7 +2743,7 @@ sub _convert($$)
                                    $element->{'args'}->[1]->{'contents'}});
             my $text = $self->gdt('{text} ({url})',
                           {'text' => $description, 'url' => 
"\\nolinkurl{$url_text}"},
-                                       'translated_text');
+                                       undef, 'translated_text');
             $result .= "\\href{$url_text}{$text}";
             return $result;
           } else {
diff --git a/tp/Texinfo/Convert/Utils.pm b/tp/Texinfo/Convert/Utils.pm
index 3e1b72bc8a..9747f64a6f 100644
--- a/tp/Texinfo/Convert/Utils.pm
+++ b/tp/Texinfo/Convert/Utils.pm
@@ -305,11 +305,11 @@ sub add_heading_number($$$;$)
           and $current->{'structure'}->{'section_level'} == 1) {
         $result = $self->gdt('Appendix {number} {section_title}',
                    {'number' => $number, 'section_title' => $text},
-                   'translated_text');
+                   undef, 'translated_text');
       } else {
         $result = $self->gdt('{number} {section_title}',
                    {'number' => $number, 'section_title' => $text},
-                   'translated_text');
+                   undef, 'translated_text');
       }
     } else {
       $result = $text;
diff --git a/tp/Texinfo/Translations.pm b/tp/Texinfo/Translations.pm
index 800006ed7d..c803ca5a34 100644
--- a/tp/Texinfo/Translations.pm
+++ b/tp/Texinfo/Translations.pm
@@ -97,9 +97,9 @@ sub _switch_messages_locale
 
 # Get document translation - handle translations of in-document strings.
 # Return a parsed Texinfo tree
-sub gdt($$;$$$)
+sub gdt($$;$$$$)
 {
-  my ($self, $message, $replaced_substrings, $type, $lang) = @_;
+  my ($self, $message, $replaced_substrings, $message_context, $type, $lang) = 
@_;
 
   # In addition to being settable from the command line,
   # the language needs to be dynamic in case there is an untranslated string
@@ -183,7 +183,14 @@ sub gdt($$;$$$)
 
   Locale::Messages::nl_putenv("LANGUAGE=$locales");
 
-  my $translated_message = Locale::Messages::gettext($message);
+  my $translated_message;
+
+  if (defined($message_context)) {
+    $translated_message = Locale::Messages::pgettext($message_context,
+                                                     $message);
+  } else {
+    $translated_message = Locale::Messages::gettext($message);
+  }
 
   Locale::Messages::textdomain($messages_textdomain);
 
@@ -328,6 +335,13 @@ sub _substitute ($$) {
   return $tree;
 }
 
+sub pgdt($$$;$$$)
+{
+  my ($self, $message_context, $message, $replaced_substrings, $type, $lang) = 
@_;
+  # FIXME would it be better to call $self->gdt?
+  return gdt($self, $message, $replaced_substrings, $message_context, $type, 
$lang);
+}
+
 
 sub _non_bracketed_contents($) {
   my $current = shift;
@@ -380,7 +394,7 @@ sub complete_indices($)
             $index_entry = gdt($self, '{name} on {class}',
                                       {'name' => $def_parsed_hash->{'name'},
                                        'class' => $def_parsed_hash->{'class'}},
-                                      undef, $entry_language);
+                                      undef, undef, $entry_language);
             $index_contents_normalized
               = [_non_bracketed_contents($def_parsed_hash->{'name'}),
                 { 'text' => ' on '},
@@ -391,7 +405,7 @@ sub complete_indices($)
             $index_entry = gdt($self, '{name} of {class}',
                                       {'name' => $def_parsed_hash->{'name'},
                                        'class' => $def_parsed_hash->{'class'}},
-                                      undef, $entry_language);
+                                      undef, undef, $entry_language);
             $index_contents_normalized
               = [_non_bracketed_contents($def_parsed_hash->{'name'}),
                  { 'text' => ' of '},
@@ -456,7 +470,7 @@ converted documents, and returns, in general, a texinfo 
tree.
 
 =over
 
-=item $tree = $object->gdt($string, $replaced_substrings, $mode, $lang)
+=item $tree = $object->gdt($string, $replaced_substrings, $message_context, 
$mode, $lang)
 X<C<gdt>>
 
 The I<$string> is a string to be translated.  In the default case,
@@ -468,10 +482,15 @@ reference identifies what is to be substituted, and the 
value is
 some string, texinfo tree or array content that is substituted in
 the resulting texinfo tree.  In the string to be translated word
 in brace matching keys of I<$replaced_substrings> are replaced.
+
 The I<$object> is typically a converter, but can be any object that implements
 C<get_conf>, or undefined (C<undef>).  If not undefined, the information in the
 I<$object> is used to determine the encoding, the documentlanguage and get some
-customization information. I<$lang> is optional. If set, it overrides the
+customization information.
+
+The I<$message_context> is optional.  If not C<undef> this is a translation
+context string for I<$string>.  It is the first argument of C<pgettext>
+in the C API of Gettext.  I<$lang> is optional. If set, it overrides the
 documentlanguage.
 
 =begin comment
@@ -509,6 +528,14 @@ may only be strings in that case.
 
 =back
 
+=item $tree = $object->pgdt($message_context, $string, $replaced_substrings, 
$mode, $lang)
+X<C<pgdt>>
+
+Same to C<gdt> except that the I<$message_context> is not optional.
+Calls C<gdt>.  This function is useful to mark strings with a
+translation context for translation.  This function is similar to pgettext
+in the Gettext C API.
+
 =back
 
 =head1 AUTHOR