branch master updated: Add customization of external node reference names

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new f0cfa4354b Add customization of external node reference names
f0cfa4354b is described below

commit f0cfa4354ba0fb0e33aa3990c853e7f69fd9438f
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Tue Sep 5 10:16:23 2023 +0200

    Add customization of external node reference names
    
    * doc/texi2any_api.texi (Customizing Output Target Names)
    (Customizing External Node Output Names), tp/Texinfo/Convert/HTML.pm
    (%customizable_file_id_setting_references, _external_node_href):
    add external_target_split_name and external_target_non_split_name
    file id setting customization function reference.  Based on
    Jonas Hahnfeld feedback.
---
 ChangeLog                  | 11 ++++++++++
 doc/texi2any_api.texi      | 54 +++++++++++++++++++++++++++++++++++++++++++++-
 tp/Texinfo/Convert/HTML.pm | 32 +++++++++++++++++++++++----
 3 files changed, 92 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index e3acf9eea8..f0ce940546 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2023-09-05  Patrice Dumas <pertusus@free.fr>
+
+       Add customization of external node reference names
+
+       * doc/texi2any_api.texi (Customizing Output Target Names)
+       (Customizing External Node Output Names), tp/Texinfo/Convert/HTML.pm
+       (%customizable_file_id_setting_references, _external_node_href):
+       add external_target_split_name and external_target_non_split_name
+       file id setting customization function reference.  Based on
+       Jonas Hahnfeld feedback.
+
 2023-09-04  Patrice Dumas <pertusus@free.fr>
 
        * tp/Texinfo/Convert/HTML.pm (_external_node_href): initialize
diff --git a/doc/texi2any_api.texi b/doc/texi2any_api.texi
index bccefa31f6..07dc423863 100644
--- a/doc/texi2any_api.texi
+++ b/doc/texi2any_api.texi
@@ -1859,6 +1859,7 @@ 
texinfo_register_file_id_setting_function('node_file_name',
 @menu
 * File: Customizing Output File Names.
 * Target: Customizing Output Target Names.
+* External Node: Customizing External Node Output Names.
 * Special Elements: Customizing Special Elements Output Names.
 @end menu
 
@@ -1947,7 +1948,7 @@ described here.
 @c xx target for a section is the node id.
 
 The following function reference is for target items (nodes, anchors,
-floats):
+floats), including for external manuals:
 
 @deftypefn {Function Reference} @var{$target} label_target_name @
            (@var{$converter}, @var{$normalized}, @var{\@@node_contents}, 
@var{$default_target})
@@ -1959,6 +1960,7 @@ should return the target (@var{$target}).
 @end deftypefn
 
 The element corresponding to the label can be found with @code{label_command}
+if the label corresponds to an internal reference
 (@pxref{Target Commands Links@comma{} Texts and Associated Commands}):
 @example
 my $element;
@@ -1989,6 +1991,56 @@ the sectioning element (@var{$file}).
 @end deftypefn
 
 
+@node Customizing External Node Output Names
+@section Customizing External Node Output Names
+
+In the default case references to external nodes are set as described
+in the Texinfo manual (@pxref{HTML Xref,,, texinfo, Texinfo}).  Some
+customization is already possible for external manuals URLs as explained in
+the Texinfo manual (@pxref{HTML Xref Configuration,,, texinfo, Texinfo}),
+and by setting @code{EXTERNAL_CROSSREF_SPLIT},
+@code{EXTERNAL_CROSSREF_EXTENSION}, @code{EXTERNAL_DIR},
+@code{TOP_NODE_FILE_TARGET} or @code{IGNORE_REF_TO_TOP_NODE_UP}
+(@pxref{HTML Customization Variables,,, texinfo, Texinfo}).
+
+If the external reference is not already ignored because of
+@code{IGNORE_REF_TO_TOP_NODE_UP}, two function references give
+full control over the external node target output names, with
+@code{external_target_split_name} if the external target is considered
+to be split, and @code{external_target_non_split_name} if the external
+target is non split.
+
+@deftypefn {Function Reference} {(@var{$target}, @var{$host_directory}, 
@var{$file_name})} @
+  external_target_split_name(@var{$converter}, @var{$normalized}, 
@var{\@@node_contents}, @var{$default_target}, @
+    @var{$default_host_directory}, @var{$default_file_name})
+@var{$converter} is a converter object. @var{$normalized} is the
+normalized node name, @var{\@@node_contents} is a reference
+on an array containing the Texinfo tree contents of the external target.
+
+@var{$default_target}, @var{$default_host_directory} and
+@var{$default_file_name} are the target, host and directory URL part and file 
name
+URL part that have been already set.
+
+The function should return the @var{$target}, @var{$host_directory} and
+@var{$file_name} URL parts.
+@end deftypefn
+
+@deftypefn {Function Reference} {(@var{$target}, @var{$host_directory_file})} @
+  external_target_non_split_name(@var{$converter}, @var{$normalized}, 
@var{\@@node_contents}, @var{$default_target}, @
+    @var{$default_host_directory_file})
+@var{$converter} is a converter object. @var{$normalized} is the
+normalized node name, @var{\@@node_contents} is a reference
+on an array containing the Texinfo tree contents of the external target.
+
+@var{$default_target} is the target and @var{$default_host_directory_file}
+is the host and file name part of the URL that have been already
+set.
+
+The function should return the @var{$target} and @var{$host_directory_file}
+URL parts.
+@end deftypefn
+
+
 @node Customizing Special Elements Output Names
 @section Customizing Special Elements Output Names
 
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 2fef0995c6..7338bc245b 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -7399,7 +7399,9 @@ sub _pop_document_context($)
 
 # can be set through Texinfo::Config::texinfo_register_file_id_setting_function
 my %customizable_file_id_setting_references;
-foreach my $customized_reference ('label_target_name', 'node_file_name',
+foreach my $customized_reference ('external_target_split_name',
+                'external_target_non_split_name',
+                'label_target_name', 'node_file_name',
                 'sectioning_command_target_name', 'tree_unit_file_name',
                 'special_element_target_file_name') {
   $customizable_file_id_setting_references{$customized_reference} = 1;
@@ -9498,10 +9500,11 @@ sub _external_node_href($$$;$)
   # for messages only
   my $source_command = shift;
 
+  my $normalized = $external_node->{'normalized'};
+  my $node_contents = $external_node->{'node_content'};
   #print STDERR "external_node: ".join('|', keys(%$external_node))."\n";
   my ($target_filebase, $target)
-      = $self->_normalized_label_id_file($external_node->{'normalized'},
-                                         $external_node->{'node_content'});
+      = $self->_normalized_label_id_file($normalized, $node_contents);
 
   # undef if conversion is called through convert()
   my $default_target_split = $self->get_conf('EXTERNAL_CROSSREF_SPLIT');
@@ -9621,6 +9624,15 @@ sub _external_node_href($$$;$)
     } else {
       $file_name = $target_filebase . $external_file_extension;
     }
+    if (defined($self->{'file_id_setting'}->{'external_target_split_name'})) {
+      ($target, $directory, $file_name)
+        = &{$self->{'file_id_setting'}->{'external_target_split_name'}}($self,
+                             $normalized, $node_contents, $target,
+                             $directory, $file_name);
+      $directory = '' if (!defined($directory));
+      $file_name = '' if (!defined($file_name));
+      $target = '' if (!defined($target));
+    }
     my $result = $directory . $file_name;
     if ($target ne '') {
       $result .= '#' . $target;
@@ -9630,7 +9642,19 @@ sub _external_node_href($$$;$)
     if ($target eq '') {
       $target = 'Top';
     }
-    return $file . '#' . $target;
+    if (defined($self->{'file_id_setting'}->{
+                          'external_target_non_split_name'})) {
+      ($target, $file)
+       = 
&{$self->{'file_id_setting'}->{'external_target_non_split_name'}}($self,
+                             $normalized, $node_contents, $target, $file);
+      $file = '' if (!defined($file));
+      $target = '' if (!defined($target));
+    }
+    my $result = $file;
+    if ($target ne '') {
+      $result .= '#' . $target;
+    }
+    return $result;
   }
 }