HTML copiable links for @item/@itemx/index entry conglomeration

[Gavin Smith]

In the manual there are sections like

  @table @code
  @item --enable-encoding
  @itemx --disable-encoding
  @vindex IX--ONE
  @vindex IX--TWO
  aaaaaaaa
  @end table

(IX--ONE was originally --enable-encoding and IX--TWO was --disable-encoding,
but I found it easier to read the dumps for this input.)

In the HTML output, the first line "--enable-encoding" has a copiable
hyperlink, but the second "--disable-encoding" doesn't.  To start with,
we need to mark which index entry should correspond to which @item or @itemx,
by reordering:

  @table @code
  @item --enable-encoding
  @vindex IX--ONE
  @itemx --disable-encoding
  @vindex IX--TWO
  aaaaaaaa
  @end table

First question: is this the best order for this, or should it rather be

  @table @code
  @vindex IX--ONE
  @item --enable-encoding
  @vindex IX--TWO
  @itemx --disable-encoding
  aaaaaaaa
  @end table

This second order may be better, as, according to the manual:

> Index entries should precede the visible material that is being
> indexed.  For instance:
> 
>      @cindex hello
>      Hello, there!

Oddly, with the first example above, the copiable link for --enable-encoding
refers to #index-IX_002d_002dTWO, rather than #index-IX_002d_002dONE.
With the second output, there are no copiable links at all.

The processing in index entries in tables is fairly complicated, so getting
this to produce the right copiable links for both lines will take some
thought.  I'm writing this message both for myself to understand what
is happening and to seek advice.

Here's an explanation of what happens in more detail:  It starts in the
parser module with _gather_previous_item.  Without _gather_previous_item
the debugtree output looks like

  @table 
   %block_line_arg 
     @code command_as_argument 
   @item 
    %line_arg 
      |--enable-encoding|
   @vindex index_entry_command 
    %line_arg 
      |IX--ONE|
   @itemx 
    %line_arg 
      |--disable-encoding|
   @vindex index_entry_command 
    %line_arg 
      |IX--TWO|
   paragraph 
    |aaaaaaaa\n|
   @end 
    %line_arg 
      |table|

and calls to _gather_previous_item change this into

  @table 
   %block_line_arg 
     @code command_as_argument 
   table_entry 
    table_term 
     @item 
      %line_arg 
        |--enable-encoding|
     inter_item 
      @vindex index_entry_command 
       %line_arg 
         |IX--ONE|
     @itemx 
      %line_arg 
        |--disable-encoding|
    table_item 
     @vindex index_entry_command 
      %line_arg 
        |IX--TWO|
     paragraph 
      |aaaaaaaa\n|
   @end 
    %line_arg 
      |table|

_gather_previous_item creates the table_entry element, containing table_term
and table_item.

The next change occurs after the parser module has finished.  The
relate_index_entries_to_table_entries tree transformation takes the
index entry in table_item, IX--TWO, and associates it with the
first @item in table_term, the one for --enable-encoding (this is
_relate_index_entry_to_table_entry in Texinfo/Common.pm).  

It's evident that this sequence of events does not envision such input,
with mixed @item/@itemx/index commands.  Really, the IX--TWO index entry
should be associated with --disable-encoding, and the IX--ONE index
entry is the one that should be associated with for --enable-encoding.

If the code is to be changed to accomodate this kind of input better, my idea
would be to replace _gather_previous_item with something that does the job
of relate_index_entries_to_table_entries as well, eliminating the need
for this as a separate transformation after the parser is finished.
However, I don't have a concrete proposal yet.