branch master updated: Add format_single_footnote formatting reference for a single footnote

[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 2f18569665 Add format_single_footnote formatting reference for a 
single footnote
2f18569665 is described below

commit 2f185696654b41dd43d1904f66fc4c9ed0ae73ca
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Fri Jul 26 17:08:47 2024 +0200

    Add format_single_footnote formatting reference for a single footnote
    
    * doc/texi2any_api.texi (Customizing Footnotes),
    tp/Texinfo/Convert/HTML.pm (%default_formatting_references)
    (_default_format_single_footnote, _default_format_footnotes_sequence),
    tp/Texinfo/XS/convert/call_html_perl_function.c
    (call_formatting_function_format_single_footnote),
    tp/Texinfo/XS/convert/convert_html.c
    (html_default_format_single_footnote, format_single_footnote)
    (html_default_format_footnotes_sequence): add a formatting reference
    for a single footnote.  Based on a report and a patch of Roger Crew.
---
 ChangeLog                                       | 14 ++++++
 doc/texi2any_api.texi                           | 17 ++++++-
 tp/Texinfo/Convert/HTML.pm                      | 15 +++++--
 tp/Texinfo/XS/convert/call_html_perl_function.c | 59 ++++++++++++++++++++++++
 tp/Texinfo/XS/convert/call_html_perl_function.h |  5 +++
 tp/Texinfo/XS/convert/convert_html.c            | 60 +++++++++++++++++++------
 tp/Texinfo/XS/main/converter_types.h            |  1 +
 7 files changed, 153 insertions(+), 18 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ecc5561b92..3d879f1e39 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2024-07-26  Patrice Dumas  <pertusus@free.fr>
+
+       Add format_single_footnote formatting reference for a single footnote
+
+       * doc/texi2any_api.texi (Customizing Footnotes),
+       tp/Texinfo/Convert/HTML.pm (%default_formatting_references)
+       (_default_format_single_footnote, _default_format_footnotes_sequence),
+       tp/Texinfo/XS/convert/call_html_perl_function.c
+       (call_formatting_function_format_single_footnote),
+       tp/Texinfo/XS/convert/convert_html.c
+       (html_default_format_single_footnote, format_single_footnote)
+       (html_default_format_footnotes_sequence): add a formatting reference
+       for a single footnote.  Based on a report and a patch of Roger Crew.
+
 2024-07-26  Patrice Dumas  <pertusus@free.fr>
 
        * doc/Makefile.am (MAINTAINERCLEANFILES): set generated Texinfo files
diff --git a/doc/texi2any_api.texi b/doc/texi2any_api.texi
index 74ce1bef0f..d54c461841 100644
--- a/doc/texi2any_api.texi
+++ b/doc/texi2any_api.texi
@@ -4163,7 +4163,22 @@ The formatting of footnotes content is done by the
 Formats and returns the footnotes that need to be formatted.  This function
 normally calls @code{get_pending_footnotes}.  The default function also calls
 @code{footnote_location_href} to link to the location in the document where
-the footnote appeared.
+the footnote appeared, and the @code{format_single_footnote} formatting
+function to format a single footnote.
+@end deftypefn
+
+The formatting of one footnote is done by the @code{format_single_footnote}
+formatting reference:
+
+@deftypefn {Function Reference} @var{$footnote} format_single_footnote @
+  (@var{$converter}, @var{$footnote_id}, @var{$footnote_location_href}, @
+   @var{$footnote_mark}, @var{$footnote_text})
+Formats and returns a single footnote.
+@var{$footnote_id} is the
+identifier for the location where the footnote arguments are expanded.
+@var{$footnote_location_href} is the href that links to the footnote location
+in the main document.  @var{$footnote_mark} is the footnote number or mark.
+Lastly, @var{$footnote_text} is the formatted footnote argument.
 @end deftypefn
 
 If footnotes are in a separate output unit (@pxref{Output Units}), the
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 9a1b03bf12..f4aa2d93ce 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -8478,6 +8478,7 @@ foreach my $customized_reference 
('external_target_split_name',
      'format_end_file' => \&_default_format_end_file,
      'format_footnotes_segment' => \&_default_format_footnotes_segment,
      'format_footnotes_sequence' => \&_default_format_footnotes_sequence,
+     'format_single_footnote' => \&_default_format_single_footnote,
      'format_heading_text' => \&_default_format_heading_text,
      'format_navigation_header' => \&_default_format_navigation_header,
      'format_navigation_panel' => \&_default_format_navigation_panel,
@@ -11466,6 +11467,14 @@ $after_body_open
   return $result;
 }
 
+sub _default_format_single_footnote($$$$$)
+{
+  my $self = shift;
+  my ($id, $href, $mark, $text) = @_;
+  return $self->html_attribute_class('h5', ['footnote-body-heading']) . '>'.
+     "<a id=\"$id\" href=\"$href\">($mark)</a></h5>\n" . $text;
+}
+
 sub _default_format_footnotes_sequence($)
 {
   my $self = shift;
@@ -11502,9 +11511,9 @@ sub _default_format_footnotes_sequence($)
       $footnote_mark = '' if (!defined($footnote_mark));
     }
 
-    $result .= $self->html_attribute_class('h5', ['footnote-body-heading']) . 
'>'.
-     "<a id=\"$footid\" 
href=\"$footnote_location_href\">($footnote_mark)</a></h5>\n"
-     . $footnote_text;
+    $result .= &{$self->formatting_function('format_single_footnote')}($self,
+                            $footid, $footnote_location_href, $footnote_mark,
+                                                              $footnote_text);
   }
   return $result;
 }
diff --git a/tp/Texinfo/XS/convert/call_html_perl_function.c 
b/tp/Texinfo/XS/convert/call_html_perl_function.c
index 910c5b9cad..74b911abb4 100644
--- a/tp/Texinfo/XS/convert/call_html_perl_function.c
+++ b/tp/Texinfo/XS/convert/call_html_perl_function.c
@@ -854,6 +854,65 @@ call_formatting_function_format_footnotes_segment 
(CONVERTER *self,
   return result;
 }
 
+char *
+call_formatting_function_format_single_footnote (CONVERTER *self,
+                                                 const char *footid,
+                        const char *footnote_location_href, const char *mark,
+                        const char *footnote_text,
+                        const FORMATTING_REFERENCE *formatting_reference)
+{
+  int count;
+  char *result;
+  const char *result_ret;
+  STRLEN len;
+  SV *result_sv;
+  SV *formatting_reference_sv;
+
+  dTHX;
+
+  formatting_reference_sv = formatting_reference->sv_reference;
+
+  if (self->modified_state)
+    {
+      build_html_formatting_state (self, self->modified_state);
+      self->modified_state = 0;
+    }
+
+  dSP;
+
+  ENTER;
+  SAVETMPS;
+
+  PUSHMARK(SP);
+  EXTEND(SP, 1);
+
+  PUSHs(sv_2mortal (newRV_inc (self->hv)));
+  PUSHs(sv_2mortal (newSVpv_utf8 (footid, 0)));
+  PUSHs(sv_2mortal (newSVpv_utf8 (footnote_location_href, 0)));
+  PUSHs(sv_2mortal (newSVpv_utf8 (mark, 0)));
+  PUSHs(sv_2mortal (newSVpv_utf8 (footnote_text, 0)));
+  PUTBACK;
+
+  count = call_sv (formatting_reference_sv,
+                   G_SCALAR);
+
+  SPAGAIN;
+
+  if (count != 1)
+    croak ("format_single_footnote should return 1 item\n");
+
+  result_sv = POPs;
+  result_ret = SvPVutf8 (result_sv, len);
+  result = non_perl_strndup (result_ret, len);
+
+  PUTBACK;
+
+  FREETMPS;
+  LEAVE;
+
+  return result;
+}
+
 char *
 call_formatting_function_format_footnotes_sequence (CONVERTER *self,
                          const FORMATTING_REFERENCE *formatting_reference)
diff --git a/tp/Texinfo/XS/convert/call_html_perl_function.h 
b/tp/Texinfo/XS/convert/call_html_perl_function.h
index 117fde2bd4..ff2e73be14 100644
--- a/tp/Texinfo/XS/convert/call_html_perl_function.h
+++ b/tp/Texinfo/XS/convert/call_html_perl_function.h
@@ -52,6 +52,11 @@ char *call_formatting_function_format_protect_text 
(CONVERTER *self,
                                               const char *text);
 char *call_formatting_function_format_footnotes_segment (CONVERTER *self,
                          const FORMATTING_REFERENCE *formatting_reference);
+char *call_formatting_function_format_single_footnote (CONVERTER *self,
+                                                       const char *footid,
+                         const char *footnote_location_href, const char *mark,
+                         const char *footnote_text,
+                         const FORMATTING_REFERENCE *formatting_reference);
 char *call_formatting_function_format_footnotes_sequence (CONVERTER *self,
                          const FORMATTING_REFERENCE *formatting_reference);
 char *call_formatting_function_format_css_lines (CONVERTER *self,
diff --git a/tp/Texinfo/XS/convert/convert_html.c 
b/tp/Texinfo/XS/convert/convert_html.c
index 43f7272494..34e9de3d77 100644
--- a/tp/Texinfo/XS/convert/convert_html.c
+++ b/tp/Texinfo/XS/convert/convert_html.c
@@ -6411,6 +6411,49 @@ static char *foot_body_heading_array[] = 
{"footnote-body-heading"};
 static const STRING_LIST foot_body_heading_classes
    = {foot_body_heading_array, 1, 1};
 
+void
+html_default_format_single_footnote (CONVERTER *self, const char *footid,
+                    const char *footnote_location_href, const char *mark,
+                    const char *footnote_text, TEXT *result)
+{
+  char *attribute_class;
+
+  attribute_class = html_attribute_class (self, "h5",
+                    &foot_body_heading_classes);
+  text_append (result, attribute_class);
+  free (attribute_class);
+
+  text_printf (result, "><a id=\"%s\" href=\"%s\">(%s)</a></h5>\n",
+               footid, footnote_location_href, mark);
+
+  text_append (result, footnote_text);
+}
+
+void
+format_single_footnote (CONVERTER *self, const char *footid,
+                        const char *footnote_location_href, const char *mark,
+                        const char *footnote_text, TEXT *result)
+{
+  const FORMATTING_REFERENCE *formatting_reference
+   = &self->current_formatting_references[FR_format_single_footnote];
+  if (formatting_reference->status == FRS_status_default_set)
+    {
+      html_default_format_single_footnote (self, footid,
+                                   footnote_location_href, mark,
+                                   footnote_text, result);
+    }
+  else
+    {
+      char *footnote
+        = call_formatting_function_format_single_footnote (self, footid,
+                                           footnote_location_href, mark,
+                                                footnote_text,
+                                                formatting_reference);
+      text_append (result, footnote);
+      free (footnote);
+    }
+}
+
 void
 html_default_format_footnotes_sequence (CONVERTER *self, TEXT *result)
 {
@@ -6431,7 +6474,6 @@ html_default_format_footnotes_sequence (CONVERTER *self, 
TEXT *result)
           char *footnote_text;
           char *context_str;
           char *footnote_text_with_eol;
-          char *attribute_class;
           char *footnote_mark;
           char *footnote_location_href
            = html_footnote_location_href (self, command, 0,
@@ -6474,19 +6516,9 @@ html_default_format_footnotes_sequence (CONVERTER *self, 
TEXT *result)
           else
             footnote_mark = strdup ("");
 
-          attribute_class = html_attribute_class (self, "h5",
-                            &foot_body_heading_classes);
-          text_append (result, attribute_class);
-          free (attribute_class);
-
-          text_printf (result, "><a id=\"%s\" href=\"%s\">(%s)</a></h5>\n",
-                       footid, footnote_location_href, footnote_mark);
-
-          free (footnote_mark);
-          free (footnote_location_href);
-
-          text_append (result, footnote_text_with_eol);
-          free (footnote_text_with_eol);
+          format_single_footnote (self, footid, footnote_location_href,
+                                  footnote_mark, footnote_text_with_eol,
+                                  result);
         }
     }
   destroy_pending_footnotes (pending_footnotes);
diff --git a/tp/Texinfo/XS/main/converter_types.h 
b/tp/Texinfo/XS/main/converter_types.h
index e9ac233589..f4f43a8846 100644
--- a/tp/Texinfo/XS/main/converter_types.h
+++ b/tp/Texinfo/XS/main/converter_types.h
@@ -153,6 +153,7 @@ enum html_file_id_setting {
   html_fr_reference(format_end_file) \
   html_fr_reference(format_footnotes_segment) \
   html_fr_reference(format_footnotes_sequence) \
+  html_fr_reference(format_single_footnote) \
   html_fr_reference(format_heading_text) \
   html_fr_reference(format_navigation_header) \
   html_fr_reference(format_navigation_panel) \