branch master updated: * NEWS: document the change in HTML element class 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 d4d6fbecfa * NEWS: document the change in HTML element class names.
d4d6fbecfa is described below

commit d4d6fbecfa36f5585588cab25464d07ebee119cc
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Thu Jan 13 15:20:58 2022 +0100

    * NEWS: document the change in HTML element class names.
    
    Update tp/TODO and comments in tp/Texinfo/Convert/Converter.pm.
---
 ChangeLog                       |  4 ++++
 NEWS                            |  4 ++++
 tp/TODO                         | 49 +++++++++++++++++++++++++++++++++--------
 tp/Texinfo/Convert/Converter.pm | 17 +++++---------
 4 files changed, 54 insertions(+), 20 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1565cc0c81..e8256ffbf9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2022-01-13  Patrice Dumas  <pertusus@free.fr>
+
+       * NEWS: document the change in HTML element class names.
+
 2022-01-13  Patrice Dumas  <pertusus@free.fr>
 
        * NEWS, doc/texinfo.texi (HTML Customization Variables),
diff --git a/NEWS b/NEWS
index c15cb55453..69da04fd77 100644
--- a/NEWS
+++ b/NEWS
@@ -30,6 +30,10 @@ See the manual for detailed information.
  . remove CSS_LINES customization variable and add SHOW_BUILTIN_CSS_RULES.
  . HTML output:
      . use <code> tag for the output of @t instead of <tt>
+     . systematic addition of classes attribute in HTML elements based on the
+       Texinfo @-command names.  Renaming of class attributes to avoid
+       confusion with @-commands formatting and describe the role in the 
document
+       rather than the formatting style.
 
 6.8 (3 July 2021)
 * Language
diff --git a/tp/TODO b/tp/TODO
index 4dad78f131..2fa7ac91aa 100644
--- a/tp/TODO
+++ b/tp/TODO
@@ -28,10 +28,11 @@ nytprofhtml
 # firefox nytprof/index.html
 
 
-Documentation
-=============
+Missing documentation
+=====================
 
 Tree documentation in ParserNonXS.pm
+------------------------------------
 
 replaced, elided, elided_block types.
 
@@ -41,6 +42,9 @@ likely in many line commands
 
 'extra'->'isindex' for nodes.
 
+Other
+-----
+
 For converter writers,
 'output_init_conf' and 'converter_init_conf'.
 
@@ -228,7 +232,7 @@ Labels in Info (which also means index entries)
 
 
 DocBook
-=======
+-------
 
   deftypevr, deftypecv: use type and not returnvalue for the type
 
@@ -254,16 +258,43 @@ DocBook
   of each item but the standard "does not specify a set of appropriate 
keywords"
   so it cannot be used.
 
+Notes
+=====
+
+In january 2022 the classes in HTML elements were normalized.  There are no
+rules, but here is descriptions of the choices made at that time in case one
+want to use the same conventions.  The objective was to have the link between
+@-commands and classes easy to understand, avoid ambiguities, and have ways to
+style most of the output.
+
+The class names without hyphen were only used for @-commands, with one
+class attribute on an element maximum for each @-command appearing in the
+Texinfo source.  It was also attempted to have such a class for all
+the @-commands with an effect on output, though the coverage was not perfect,
+sometime it is not easy to select an element that would correspond to the
+most logical association with the @-command (case of @*ref @-commands with
+both a <cite> and a <a href> for example).
+
+Class names <command>-* with <command> a Texinfo @-command name were
+only used for classes marking elements within an @-command but in other
+elements that the main element for that @-command, in general sub elements.
+For example, a @flushright lead to a <div class="flushright"> where the
+@flushright command is and to <p class="flushright-paragraph"> for the
+paragraphs within the @flushright.
+
+Class names *-<command> with <command> a Texinfo @-command name were
+reserved for uses related to @-command <command>.  For example
+classes like summary-letter-printindex, cp-entries-printindex or
+cp-letters-header-printindex for the different parts of the @printindex
+formatting.
+
+For the classes not associated with @-commands, the names were selected to
+correspond to the role in the document rather than to the formatting style.
+
 
 Interrogations and remarks
 ==========================
 
-Instead of _set_global_multiple_commands have a better granularity and
-do something per command, with the possibility to really revert everything,
-including things that are not set by set_conf (There is a comment in the
-code above _set_global_multiple_commands)?  Not clear that it is really
-interesting, there is no clear use case for now.
-
 Should more Converter ignore the last new line (with type 
 last_raw_newline) of a raw block format?
 
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index 1de7471afb..384529153a 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -274,7 +274,7 @@ sub _in_preamble($)
 
 # $COMMANDS_LOCATION is 'before', 'last', 'preamble' or 'preamble_or_first'
 # 'before' means setting to the values before the document commands
-# (default and command-line).
+# (defaults and command-line).
 # 'preamble' means setting sequentially to the values in the preamble.
 # 'first_or_preamble'  means setting to the first value for the command
 # in the document if the first command is not in the preamble, else set
@@ -283,12 +283,9 @@ sub _in_preamble($)
 #
 # For unique command, the last may be considered to be the same as the first.
 #
-# If a value was given in converter input, it is never reset by documents
-# @-commands values.
-#
 # Notice that the only effect is to use set_conf (directly or through
-# _informative_command), @-commands side effects or settings using other
-# customization is not set/reset.
+# set_informative_command_value), no @-commands setting side effects are done
+# and associated customization variables are not set/reset either.
 sub set_global_document_commands($$;$)
 {
   my $self = shift;
@@ -320,14 +317,12 @@ sub set_global_document_commands($$;$)
     foreach my $global_command (@{$selected_commands}) {
       my $element;
       if ($self->get_conf('DEBUG')) {
-        print STDERR "SET_global_multiple_commands($commands_location) 
$global_command\n";
+        print STDERR "SET_global_document_commands($commands_location) 
$global_command\n";
       }
       if (defined($self->{'global_commands'}->{$global_command})
           and ref($self->{'global_commands'}->{$global_command}) eq 'ARRAY') {
-        if ($commands_location eq 'last')
-        {
-          $element =
-            $self->{'global_commands'}->{$global_command}->[-1];
+        if ($commands_location eq 'last') {
+          $element = $self->{'global_commands'}->{$global_command}->[-1];
           $self->set_informative_command_value($element);
         } else {
           if ($commands_location eq 'preamble_or_first'