Re: Relating multiple index entries to one table item

[Gavin Smith]

On Mon, Nov 21, 2022 at 03:23:58PM +0200, Eli Zaretskii wrote:
> The index entries should precede the first @item, not be after it.  Maybe
> doing so doesn't work in this case, but you should move the index entries
> before the @item/@itemx lines regardless, since otherwise the indexing
> commands will not land you where you want.

I am not sure if this is the standard usage.  For example, in a copy
of the sources for the elisp manual I have saved, in a file called
emacs-lispref-27.2/windows.texi, there is the following:

    @table @code
    @item pop-up-windows
    @vindex pop-up-windows@r{, replacement for}
    This variable is @code{t} by default.  Instead of customizing it to
    @code{nil} and thus telling @code{display-buffer} what not to do, it's
    much better to list in @code{display-buffer-base-action} the action
    functions it should try instead as, for example:

    @example
    @group
    (customize-set-variable
     'display-buffer-base-action
     '((display-buffer-reuse-window display-buffer-same-window
        display-buffer-in-previous-window
        display-buffer-use-some-window)))
    @end group
    @end example

    @item pop-up-frames
    @vindex pop-up-frames@r{, replacement for}
    Instead of customizing this variable to @code{t}, customize
    @code{display-buffer-base-action}, for example, as follows:

    @example
    @group
    (customize-set-variable
     'display-buffer-base-action
     '((display-buffer-reuse-window display-buffer-pop-up-frame)
       (reusable-frames . 0)))
    @end group
    @end example

    @item same-window-buffer-names
    @itemx same-window-regexps
    @vindex same-window-buffer-names@r{, replacement for}
    @vindex same-window-regexps@r{, replacement for}
    Instead of adding a buffer name or a regular expression to one of
    these options use a @code{display-buffer-alist} entry for that buffer
    specifying the action function @code{display-buffer-same-window}.

    @example
    @group
    (customize-set-variable
     'display-buffer-alist
     (cons '("\\*foo\\*" (display-buffer-same-window))
            display-buffer-alist))
    @end group
    @end example
    @end table

You can see here that the index commands are used after the @item or @itemx.
Apparently it was the same case in the gcc manual.

In the case of ambiguous input like:

@table @asis
@item CAR
@vindex CDAR
@item DAR
@end table

current texi2any outputs:

<dl class="table">
<dt id='index-CDAR'><span>CAR<a class="copiable-link" href='#index-CDAR'> 
&para;</a></span></dt>
<dt>DAR</dt>
</dl>

- associating the index entry with the preceding @item, not the succeeding
item.

Hence, I think our starting point is to make mixed @item/@itemx/@?index
work appropriately, associating index commands that immediately follow
@item commands with them.  I think it might be better in a case like

@table @gcctabopt
@item -Wpedantic
@itemx -pedantic
@opindex pedantic
@opindex Wpedantic
@opindex Wno-pedantic

to find some way to make all index entries link to the top @item, rather
than changing to interleaving like this:

@table @gcctabopt
@item -Wpedantic
@opindex Wpedantic
@opindex Wno-pedantic
@itemx -pedantic
@opindex pedantic

and making the link for "pedantic" only link to the @itemx.  When someone
uses the "pedantic" index entry they are better off seeing the whole thing.