info-lookup-symbol

info-lookup-symbol

[Rehceb Rotkiv]

Hello,

when I use info-lookup-symbol, I sometimes get to the wrong place in the 
info file. For example, when I use info-lookup-symbol on the keyword 
"break" in a Python source code file, it takes me to the index item

* break <1>: try statement.

instead of

* break: break statement.

probably because (strangely) the first appears before the latter in the 
index of the info file. How can I avoid this? Is it, for example, 
possible, to get a summary of all index items that contain "break" 
instead of directly jumping to the first one? Also, how does Emacs know 
in which index file to look / how can I customize it?

Regards,
Rehceb Rotkiv

Re: info-lookup-symbol

[Eli Zaretskii]

> From: Rehceb Rotkiv <rehceb@no.spam.plz>
> Date: Sun, 08 Apr 2007 18:07:07 -0500
> 
> when I use info-lookup-symbol, I sometimes get to the wrong place in the 
> info file. For example, when I use info-lookup-symbol on the keyword 
> "break" in a Python source code file, it takes me to the index item
> 
> * break <1>: try statement.
> 
> instead of
> 
> * break: break statement.

Confirmed.

> probably because (strangely) the first appears before the latter in the 
> index of the info file.

That's the reason, yes.  The ones with <N> appear before the one
without because this is how disambiguation of identical index entries
is implemented in Texinfo; I will ask the Texinfo maintainer to change
that.

> How can I avoid this?

You can edit the index of the Python manual by hand, putting the main
index entry first in the Index node.  I don't have any better ideas at
this time.

But the _real_ fix is to complain to the authors of the Python manual:
they shouldn't be having several index entries named identically in
the first place.  They should instead qualify all but the single entry
(the one that points to the "break statement" node) with the
specialized aspects of "break" described in the other places.  For
example, the "break <1>" entry could be renamed to something like
"break, in `try' forms".

> Is it, for example, 
> possible, to get a summary of all index items that contain "break" 
> instead of directly jumping to the first one?

You can switch to the *info* buffer and type "i break TAB".

> Also, how does Emacs know 
> in which index file to look / how can I customize it?

This is set up either in info-look.el or in the language-specific mode
package.  In this case, see python-after-info-look in python.el.

Re: info-lookup-symbol

[Rehceb Rotkiv]

On Mon, 09 Apr 2007 09:57:02 +0300, Eli Zaretskii wrote:

> That's the reason, yes.  The ones with <N> appear before the one without
> because this is how disambiguation of identical index entries is
> implemented in Texinfo; I will ask the Texinfo maintainer to change
> that.

Yes, that would be a start.

> But the _real_ fix is to complain to the authors of the Python manual:

Then I would have to complain to a whole lot of authors, as identical 
indices seem to be common practice! On a quick look, I also found them in 
the Elisp and Bashref manuals. I suppose that others do it similarly.
However this is handled, it would be useful to have a function in info-
lookup-symbol that jumps to the next matching index (similar to "," in 
"i" = Info-index), because often there are multiple relevant entries for 
one symbol, like e.g. "some_item (definition)" and "some_item (syntax)", 
that one would typically want to consult successively.

> You can switch to the *info* buffer and type "i break TAB".
> 
> This is set up either in info-look.el or in the language-specific mode
> package.  In this case, see python-after-info-look in python.el.

Thanks for the info! For now, I will use the very handy "i break TAB"

Regards,
Rehceb

Re: info-lookup-symbol

[Lennart Borgman (gmail)]

Rehceb Rotkiv wrote:

> Thanks for the info! For now, I will use the very handy "i break TAB"

What does that command do? (Use C-h k and then "i break TAB" to show it.

I am using MS Windows and I am just wondering where "break" is on my 
keyboard. There is a keyboard key labeled "Pause/Break", but Emacs just says

   <pause> is undefined

if I type

   i [that keyboard key]

I am using Emacs from CVS.

Re: info-lookup-symbol

[Rehceb Rotkiv]

On Mon, 09 Apr 2007 14:48:00 +0200, Lennart Borgman (gmail) wrote:

> I am using MS Windows and I am just wondering where "break" is on my
> keyboard.

It's not a key, but a string that you enter literally! When you are in 
Info mode, i.e. looking at an info document in Emacs, you can use the 
function "Info-index", which is bound to "i" by default, to search for a 
string in the index of the info file -- in this case the Python keyword 
"break". And as Eli told me, when you press <TAB> instead of <RET> after 
entering the search string, you get a list of alle index entries 
containing the search string. Try it out, it's very useful!

HTH,
Rehceb

Re: info-lookup-symbol

[Lennart Borgman (gmail)]

Rehceb Rotkiv wrote:
> On Mon, 09 Apr 2007 14:48:00 +0200, Lennart Borgman (gmail) wrote:
> 
>> I am using MS Windows and I am just wondering where "break" is on my
>> keyboard.
> 
> It's not a key, but a string that you enter literally! When you are in 
> Info mode, i.e. looking at an info document in Emacs, you can use the 
> function "Info-index", which is bound to "i" by default, to search for a 
> string in the index of the info file -- in this case the Python keyword 
> "break". And as Eli told me, when you press <TAB> instead of <RET> after 
> entering the search string, you get a list of alle index entries 
> containing the search string. Try it out, it's very useful!
> 
> HTH,
> Rehceb


Ah, thanks. Normal Emacs completion. I have actually never used that in 
Info ;-)

Yes, that seems useful. I normally just use C-s in Info to free text 
search across nodes. It is does not take very long time to do this (if 
you know what you are looking for, of course).

Re: info-lookup-symbol

[Eli Zaretskii]

> Date: Mon, 09 Apr 2007 16:50:14 +0200
> From: "Lennart Borgman (gmail)" <lennart.borgman@gmail.com>
> CC: help-gnu-emacs@gnu.org
> 
> Normal Emacs completion. I have actually never used that in Info ;-)

Probably because it never worked in Emacs's Info until a year or so
ago, when Stefan (I think) implemented it, to be consistent with the
stand-alone Info reader (where TAB completion in index search worked
since day one).

> Yes, that seems useful. I normally just use C-s in Info to free text 
> search across nodes.

Index search is much more efficient that C-s.

> It is does not take very long time to do this (if you know what you
> are looking for, of course).

Index search is for using the manual as a reference, and in that case
you normally have some idea about what you are looking for.

Re: info-lookup-symbol

[Eli Zaretskii]

> From: Rehceb Rotkiv <rehceb@no.spam.plz>
> Date: Mon, 09 Apr 2007 07:05:40 -0500
> 
> > But the _real_ fix is to complain to the authors of the Python manual:
> 
> Then I would have to complain to a whole lot of authors, as identical 
> indices seem to be common practice!

It may be common practice, but it's bad practice nonetheless.

> On a quick look, I also found them in the Elisp and Bashref manuals.

The ELisp manual has 9 such occurrences out of 4000 index entries.
But thanks for pointing this out, I will fix them all for the next
release.

> However this is handled, it would be useful to have a function in info-
> lookup-symbol that jumps to the next matching index (similar to "," in 
> "i" = Info-index), because often there are multiple relevant entries for 
> one symbol, like e.g. "some_item (definition)" and "some_item (syntax)", 
> that one would typically want to consult successively.

I agree.  Please feel free to suggest this on emacs-devel@gnu.org.