branch master updated: Document strict API use in comments when the API is not used

[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 9532893dd0 Document strict API use in comments when the API is not used
9532893dd0 is described below

commit 9532893dd0c5fc6a173ccbd55874a9e06e6d5423
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Jun 4 22:43:44 2022 +0200

    Document strict API use in comments when the API is not used
    
    * tp/Texinfo/Convert/HTML.pm: use # API info: comments to
    document what strict API use would have been when the API is not
    used for speed.
    
    * doc/customization_api.texi (Init File Basics, Basic Formatting
    Customization): document # API info: comments. Document that
    customized format_protect_text function may not be called everywhere.
---
 ChangeLog                  | 12 ++++++++++++
 doc/customization_api.texi | 10 ++++++++--
 tp/Texinfo/Convert/HTML.pm | 35 +++++++++++++++++++++++++++++------
 3 files changed, 49 insertions(+), 8 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8607243a25..e1ae02a66a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2022-06-04  Patrice Dumas  <pertusus@free.fr>
+
+       Document strict API use in comments when the API is not used
+
+       * tp/Texinfo/Convert/HTML.pm: use # API info: comments to
+       document what strict API use would have been when the API is not
+       used for speed.
+
+       * doc/customization_api.texi (Init File Basics, Basic Formatting
+       Customization): document # API info: comments. Document that
+       customized format_protect_text function may not be called everywhere.
+
 2022-06-04  Gavin Smith  <gavinsmith0123@gmail.com>
 
        Cast for isalpha and isalnum arguments
diff --git a/doc/customization_api.texi b/doc/customization_api.texi
index c16f51a18c..47fa5dd76e 100644
--- a/doc/customization_api.texi
+++ b/doc/customization_api.texi
@@ -177,6 +177,9 @@ example is the @code{Texinfo::Convert::HTML} module which 
implements
 almost all the Texinfo HTML function described in this manual for the 
conversion
 to HTML@footnote{The @code{Texinfo::Convert::HTML} module also implements the
 HTML converter which go through the tree and call user defined functions.}.
+In @code{Texinfo::Convert::HTML} the API may not be followed strictly for
+performance reasons, in that case there should always be a @samp{API info:}
+comment which shows what the API conformat code should be.
 The Licenses conditions of the diverse files used as example should be taken
 into account when reusing code.
 
@@ -2440,11 +2443,14 @@ string.
                                            ($converter, $input_text)
 Return @var{$input_text} with HTML special characters and form feeds
 protected.
+
+For performance reasons, this function reference may not be called everywhere
+text is protected.  For those cases, the calling function could be
+redefined too to call 
@code{&@{$self->formatting_function('format_protect_text')@}(...)}.
 @end deftypefn
 
 @xref{Texinfo::Convert::Converter $protected_text = 
$converter->xml_protect_text($text),,
-Texinfo::Convert::Converter::xml_protect_text,tp_api}
-
+Texinfo::Convert::Converter::xml_protect_text,tp_api}.
 @item format_separate_anchor
 
 This function reference is called if there is not another HTML element to
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 1d871c607e..b70db0a9aa 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -173,6 +173,8 @@ sub html_attribute_class($$;$)
     confess("html_attribute_class: $classes not an array ref (for $element)");
   }
   if (!defined($classes) or scalar(@$classes) == 0
+      # API info: get_conf() API code conforming would be:
+      #  or $self->get_conf('NO_CSS')) {
         or $self->{'conf'}->{'NO_CSS'}) {
     if ($element eq 'span') {
       return '';
@@ -183,6 +185,8 @@ sub html_attribute_class($$;$)
 
   my $style = '';
 
+  # API info: get_conf() API code conforming would be:
+  #  if ($self->get_conf('INLINE_CSS_STYLE')) {
   if ($self->{'conf'}->{'INLINE_CSS_STYLE'}) {
     my @styles = ();
     foreach my $style_class (@$classes) {
@@ -3414,8 +3418,9 @@ sub _default_format_navigation_panel($$$$;$)
     }
 
     my ($active, $passive, $need_delimiter)
+      # API info: using the API to allow for customization would be:
+      #  = &{$self->formatting_function('format_button')}($self, $button);
        = &{$self->{'formatting_function'}->{'format_button'}}($self, $button);
-      # = &{$self->formatting_function('format_button')}($self, $button);
     if ($self->get_conf('HEADER_IN_TABLE')) {
       if (defined($active)) {
         $result .= $active;
@@ -5462,29 +5467,45 @@ sub _convert_text($$$)
 
   my $context = $self->{'document_context'}->[-1];
 
-  #if ($self->in_verbatim()) { # inline these calls for speed
-  if ($context->{'verbatim'}) {
-    return $self->_default_format_protect_text($text);
+  # API info: in_verbatim() API code conforming would be:
+  #if ($self->in_verbatim()) {
+  if ($context->{'verbatim'}) { # inline these calls for speed
+    # API info: using the API to allow for customization would be:
     #return &{$self->formatting_function('format_protect_text')}($self, $text);
+    return $self->_default_format_protect_text($text);
   }
   return $text if $context->{'raw'};
+  # API info: in_raw() API code conforming would be:
   #return $text if ($self->in_raw());
 
   my $formatting_context = $context->{'formatting_context'}->[-1];
   $text = uc($text) if $formatting_context->{'upper_case'};
+  # API info: in_upper_case() API code conforming would be:
   #$text = uc($text) if ($self->in_upper_case());
 
-  $text = _default_format_protect_text($self, $text);
+  # API info: using the API to allow for customization would be:
   #$text = &{$self->formatting_function('format_protect_text')}($self, $text);
+  $text = _default_format_protect_text($self, $text);
 
+  # API info: get_conf() API code conforming would be:
+  #if ($self->get_conf('ENABLE_ENCODING')
+  #    and $self->get_conf('OUTPUT_ENCODING_NAME')
+  #    and $self->get_conf('OUTPUT_ENCODING_NAME') eq 'utf-8') {
   if ($self->{'conf'}->{'ENABLE_ENCODING'}
       and $self->{'conf'}->{'OUTPUT_ENCODING_NAME'}
       and $self->{'conf'}->{'OUTPUT_ENCODING_NAME'} eq 'utf-8') {
     $text = Texinfo::Convert::Unicode::unicode_text($text,
                                         (in_code($self) or in_math($self)));
+  # API info: in_code() API code conforming and
+  # API info: in_math() API code conforming would be:
+  #} elsif (!$self->in_code() and !$self->in_math()) {
   } elsif (!$context->{'monospace'}->[-1] and !$context->{'math'}) {
+    # API info: get_conf() API code conforming would be:
+    #if ($self->{'conf'}->{'USE_NUMERIC_ENTITY'}) {
     if ($self->{'conf'}->{'USE_NUMERIC_ENTITY'}) {
       $text = $self->xml_format_text_with_numeric_entities($text);
+    # API info: get_conf() API code conforming would be:
+    #} elsif ($self->{'conf'}->{'USE_ISO'}) {
     } elsif ($self->{'conf'}->{'USE_ISO'}) {
       $text = _entity_text($text);
     } else {
@@ -5498,6 +5519,7 @@ sub _convert_text($$$)
 
   return $text if (in_preformatted($self));
 
+  # API info: in_non_breakable_space() API code conforming would be:
   #if ($self->in_non_breakable_space()) {
   if ($formatting_context->{'space_protected'}) {
     if ($text =~ /(\S*[_-]\S*)/) {
@@ -9887,8 +9909,9 @@ sub _protect_class_name($$)
   my $class_name = shift;
   $class_name =~ s/[$characters_replaced_from_class_names]/-/g;
 
+  # API info: using the API to allow for customization would be:
+  #  return &{$self->formatting_function('format_protect_text')}($self, 
$class_name);
   return _default_format_protect_text($self, $class_name);
-  #return &{$self->formatting_function('format_protect_text')}($self, 
$class_name);
 }
 
 my $debug;  # whether to print debugging output