> From: Gavin Smith <[email protected]> > Date: Mon, 21 Nov 2022 18:43:18 +0000 > Cc: Arsen Arsenović <[email protected]>, > [email protected] > > 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.
