[no subject]

[Patrice Dumas]

branch: master
commit 6adcfb35e9a069569b292727597f41c4d26a3b43
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Nov 5 00:03:35 2022 +0100

    * tp/Texinfo/Common.pm (pgdt): add pgdt that does nothing to
    be able to marks translated strings with a translation context.
---
 ChangeLog            |  5 +++++
 tp/TODO              |  4 +---
 tp/Texinfo/Common.pm | 47 +++++++++++++++++++++++++++++++----------------
 3 files changed, 37 insertions(+), 19 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 62491468fc..30576ea853 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2022-11-04  Patrice Dumas  <pertusus@free.fr>
+
+       * tp/Texinfo/Common.pm (pgdt): add pgdt that does nothing to
+       be able to marks translated strings with a translation context.
+
 2022-11-04  Patrice Dumas  <pertusus@free.fr>
 
        * NEWS: update with @subentry, @seealso and @seeentry formatting
diff --git a/tp/TODO b/tp/TODO
index 81ea5e4192..71d2774a75 100644
--- a/tp/TODO
+++ b/tp/TODO
@@ -71,9 +71,7 @@ my $collator = Unicode::Collate::Locale->new('locale' => 
$documentlanguage, 'nor
 @sorted = $collator->sort(@not_sorted);
 
 
-in hyphenation: only text and accent commands, and should
-only appear in toplevel.  Not the only command with only
-text and accent commands, there is a FIXME in Common.pm.
+hyphenation: should only appear in toplevel.
 
 
 Some dubious nesting could be warned against.  The parsers context
diff --git a/tp/Texinfo/Common.pm b/tp/Texinfo/Common.pm
index 7e107c06fc..9a24c93242 100644
--- a/tp/Texinfo/Common.pm
+++ b/tp/Texinfo/Common.pm
@@ -75,6 +75,7 @@ $VERSION = '7.0';
 
 
 # i18n
+# For the messages translations.
 my $messages_textdomain = 'texinfo';
 
 sub __($) {
@@ -89,6 +90,25 @@ sub __p($$) {
 }
 
 
+# For the in-document output strings translations in the texinfo_document
+# textdomain.
+#
+# Return the string but do nothing else, used to mark strings to be translated
+# in the Gettext framework.
+# Can be used in other modules, inparticular if the modules already overwrite
+# gdt from Texinfo::Translations.
+sub gdt($)
+{
+  return $_[0];
+}
+
+# First argument is the translation context.
+sub pgdt($$)
+{
+  return $_[1];
+}
+
+
 # determine the null devices
 my $default_null_device = File::Spec->devnull();
 our %null_device_file = (
@@ -468,7 +488,7 @@ sub valid_customization_option($)
   return $valid_customization_options{$option};
 }
 
-# not documented on purpose, should not be called in user-defined
+# not documented on purpose, should not be directly called in user-defined
 # codes
 sub add_valid_customization_option($)
 {
@@ -565,13 +585,6 @@ foreach my $unformatted_brace_command ('anchor', 
'shortcaption',
   $unformatted_brace_commands{$unformatted_brace_command} = 1;
 }
 
-# Do nothing, used to mark translations for gettext.  The strings
-# are marked to be translated in the parsers with type 'untranslated'.
-sub gdt($)
-{
-  return $_[0];
-}
-
 our %def_map = (
     # basic commands.
     # 'arg' and 'argtype' are for everything appearing after the other
@@ -586,6 +599,8 @@ our %def_map = (
     'defop',     [ 'category', 'class' , 'name', 'arg' ],
     'deftp',     [ 'category', 'name', 'argtype' ],
     # shortcuts
+    # The strings are marked to be translated in the parsers with type
+    # 'untranslated'.
     'defun',         {'deffn'     => gdt('Function')},
     'defmac',        {'deffn'     => gdt('Macro')},
     'defspec',       {'deffn'     => gdt('Special Form')},
@@ -629,8 +644,7 @@ for my $cmd ('example', 'display', 'format', 'lisp', 
'quotation',
   $small_block_associated_command{'small'.$cmd} = $cmd;
 };
 
-# commands that should only appear at the root level and contain up to
-# the next root command.  @node and sectioning commands.
+# Section and heading commands hierarchical levels
 our %command_structuring_level = (
               'top'               => 0,
               'part'              => 0, # out of the main hierarchy
@@ -811,8 +825,9 @@ sub output_files_initialize
 # $FILE_PATH is the file path, it should be a binary string.
 # If $USE_BINMODE is set, call binmode() to set binary mode.
 # $OUTPUT_ENCODING argument overrides the output encoding.
-# returns the opened filehandle, or undef if opening failed,
-# and the $! error message or undef if opening succeeded.
+# Returns
+#  - the opened filehandle, or undef if opening failed,
+#  - the $! error message or undef if opening succeeded.
 sub output_files_open_out($$$;$$)
 {
   my $self = shift;
@@ -926,14 +941,14 @@ sub rearrange_tree_beginning($$)
     delete $before_node_section->{'contents'}
       if (scalar(@{$before_node_section->{'contents'}}) == 0);
   }
-  
+
   _add_preamble_before_content($before_node_section);
 }
 
 sub _add_preamble_before_content($)
 {
   my $before_node_section = shift;
-  
+
   # add a preamble for informational commands
   my $informational_preamble = {'type' => 'preamble_before_content',
                                 'parent' => $before_node_section,
@@ -1772,7 +1787,7 @@ sub _collect_commands_list_in_tree($$$)
 # associated_section part_associated_section associated_node associated_part
 # @prototypes @columnfractions titlepage quotation @author command
 # menu_entry_description menu_entry_name
-# 
+#
 # should point to other elements, or be copied.  And some should be recursed
 # into too.
 # extra->type->content
@@ -1868,7 +1883,7 @@ sub _substitute_references($$$)
   my $current = shift;
   my $new = shift;
   my $reference_associations = shift;
-  
+
   foreach my $key ('args', 'contents') {
     if ($new->{$key}) {
       my $index = 0;