On Thu, Jul 25, 2024 at 07:55:03PM -0700, Roger Crew via Bug reports for the
GNU Texinfo documentation system wrote:
> Now, as it happens, what I want to do is indeed possible in 7.1 with
> a custom 'format_footnotes_sequence' handler.
>
> However, since what I actually want is format *individual* footnotes,
> doing it using THAT handler first requires re-parsing the footnotes
> back out of a previously formatted string, which, aside from needing a
> slightly hairy regexp, will be inherently fragile, i.e., if some other
> custom handler/config-setting or some later makeinfo version decides
> the <h5> that currently starts each footnote should change to
> something else, I will lose.
I do not understand why you need to do that if you customize the
format_footnotes_sequence handler. Something like the following in an
init file (untested):
sub _my_format_single_footnote($$$$$)
{
my $self = shift;
my ($id, $href, $mark, $text) = @_;
......
return $formatted_single_footnote;
}
sub my_format_footnotes_sequence($)
{
my $self = shift;
my $pending_footnotes = $self->get_pending_footnotes();
my $result = '';
foreach my $pending_footnote_info_array (@$pending_footnotes) {
my ($command, $footid, $docid, $number_in_doc,
$footnote_location_filename, $multi_expanded_region)
= @$pending_footnote_info_array;
my $footnote_location_href = $self->footnote_location_href($command, undef,
$docid,
$footnote_location_filename); my $footnote_text
= $self->convert_tree_new_formatting_context($command->{'args'}->[0],
"$command->{'cmdname'} $number_in_doc $footid");
chomp ($footnote_text);
$footnote_text .= "\n";
my $footnote_mark;
if ($self->get_conf('NUMBER_FOOTNOTES')) {
$footnote_mark = $number_in_doc;
} else {
$footnote_mark = $self->get_conf('NO_NUMBER_FOOTNOTE_SYMBOL');
$footnote_mark = '' if (!defined($footnote_mark));
}
$result .= _my_format_single_footnote($self, $footid,
$footnote_location_href, $footnote_mark, $footnote_text);
}
}
texinfo_register_formatting_function('format_footnotes_sequence',
\&my_format_footnotes_sequence);
> It would be much better to have a 'format_single_footnote' handler that
> gets invoked on each footnote.
>
> I'm quite happy to do an actual pull request if you'd prefer, but since
> this would be a new codebase for me, I'd rather first make sure that this
> is not something you've already considered and rejected for some reason.
There is a trade-off between complexity and ease of customization.
Given a full cover of customization (which is the case in 7.1), in
general, the less customization format_* customization functions the
better, but it can be counterbalances by usability.
In that specific case, on the one hand, I agree that being able to
change a single footnote is relevant, as it is where most of the actual
formatting takes place. On the other hand, this increases even more the
level of detail for footnotes customization, if we did the same for all
the formatting, we would have to add a lot of format_* functions.
Overall, I'd say that since it does not add too much complexity and
corresponds to a real need, I'll add the change.
> (**) In the latest source, the needed changes seem to be confined to
> tp/TexInfo/Convert/HTML.pm:
That's what is needed for Perl, but in the master for the upcoming
release, there is a parallel C implementation for speed that needs about
the same changes (in tp/Texinfo/XS/. Straightforward when it is as you
propose an addition of a format_* function without new code.
> %default_formatting_references = (
> ...
> '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,
> ...
> );
>
> ...
>
> +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($)
> {
> ...
> - $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->{'format_single_footnote'})}(
> + $self, $footid, "$footnote_location_href", $footnote_mark,
> + $footnote_text);
> ...
> }
Thanks for the report.
--
Pat
