Re: Relating multiple index entries to one table item

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Mon, 21 Nov 2022 18:43:18 +0000
> Cc: Arsen Arsenović <arsen@aarsen.me>,
>       help-texinfo@gnu.org
> 
> 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.

And they are mistakes that need to be fixed.  If you type

  i pop-up-windows, replacement for RET

in the Info reader, you will land on the line _after_ the item's name.
Which is not what we want.

> In the case of ambiguous input like:
> 
> @table @asis
> @item CAR
> @vindex CDAR
> @item DAR
> @end table

This is simply wrong: the second one should be @itemx, right?

> 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.

If you can find a way of reordering them such that all the index entries are
processed before the @item's, I'll applaud.  My rule of having index entries
first is because then the current makeinfo produces indices that point to
where they should.