Double hyphens in variable names.

Double hyphens in variable names.

[Lute Kamstra]

I'm trying to document the variable `imenu--index-alist' in the Lisp
Reference Manual.  When I write this in the Texinfo source file:

@defvar imenu--index-alist

Texinfo produces an info file that has this:

 - Variable: imenu-index-alist

Note that the double hyphen is reduced to a single hyphen.  Am I
missing something, or is this a bug in Texinfo?

What is the significance of a double hyphen in a symbol name anyway?

  Lute.

Re: Double hyphens in variable names.

[Eli Zaretskii]

> From: Lute Kamstra <Lute.Kamstra@cwi.nl>
> Date: Wed, 01 Oct 2003 15:53:12 +0200
> 
> I'm trying to document the variable `imenu--index-alist' in the Lisp
> Reference Manual.  When I write this in the Texinfo source file:
> 
> @defvar imenu--index-alist
> 
> Texinfo produces an info file that has this:
> 
>  - Variable: imenu-index-alist
> 
> Note that the double hyphen is reduced to a single hyphen.  Am I
> missing something, or is this a bug in Texinfo?

Not a bug, but a feature.  See the node "Conventions" in the Texinfo
manual.  In this case, you want to say

  @defvar imenu---index-alist

(three dashes in a row).

Re: Double hyphens in variable names.

[Lute Kamstra]

Eli Zaretskii <eliz@elta.co.il> writes:

>> I'm trying to document the variable `imenu--index-alist' in the Lisp
>> Reference Manual.  When I write this in the Texinfo source file:
>> 
>> @defvar imenu--index-alist
>> 
>> Texinfo produces an info file that has this:
>> 
>>  - Variable: imenu-index-alist
>> 
>> Note that the double hyphen is reduced to a single hyphen.  Am I
>> missing something, or is this a bug in Texinfo?
>
> Not a bug, but a feature.  See the node "Conventions" in the Texinfo
> manual.  In this case, you want to say
>
>   @defvar imenu---index-alist
>
> (three dashes in a row).

I see; now it shows up right in the info file:

 - Variable: imenu--index-alist

However, it generates this index entry:

* imenu---index-alist:                   Imenu.

Also, the dvi file shows a long dash as apposed to the desired two
hyphens.

Note that when I do:

@defvar @code{imenu--index-alist}

the double hyphens are handled properly in the sense that it shows up
in info as:

 - Variable: `imenu--index-alist'

and in the info file's index as:

* imenu--index-alist:                    Imenu.

The dvi file shows two hyphens as well.  The only problem, of course,
is that the variable name is surrounded by quotes in the info file and
is shown with a different font in the dvi file.  I think that Texinfo
should be changed so that the @defvr command (I assume that @defvar is
defined in terms of @defvr) handles hyphens like @code.


  Lute.

Re: Double hyphens in variable names.

[Luc Teirlinck]

What if you do:

@defvar imenu@verb{ -- }index-alist

The spaces can be replaced by any other delimiter.

Does this lead to satisfactory results?

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Luc Teirlinck]

Maybe @verb{|--|} might be better than @verb{ -- }.

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> What if you do:
>
> @defvar imenu@verb{ -- }index-alist
>
> The spaces can be replaced by any other delimiter.
>
> Does this lead to satisfactory results?

No.  For the info file, it does produce:

 - Variable: imenu--index-alist

but for the info file's index it produces:

* imenu:                                 Imenu.

Additionally, it chokes TeX:

  ! Undefined control sequence.
  \tabeightspaces ->\catcode `\^^I=\active \def ^^I
                                                   {\ \ \ \ \ \ \ \ }
  \setupverb ...catcode `\`=\active \tabeightspaces 
                                                    \obeylines \uncatcodespeci...

  \verb ->\begingroup \setupverb 
                                 \doverb 
  <argument> imenu\verb 
                        { -- }index-alist
  \code #1->#1

  \dosubind ...e \toks 0}\xdef \indexsorttmp {\temp 
                                                    }}\edef \temp {\write \csn...
  ...
  l.1850 @defvar imenu@verb{ -- }index-alist

Still, even if it had worked, wouldn't it be best that the @defvr
macro treats multiple hyphens like @code does?

  Lute.

Re: Double hyphens in variable names.

[Luc Teirlinck]

   Still, even if it had worked, wouldn't it be best that the @defvr
   macro treats multiple hyphens like @code does?

Maybe, but what about 

@defvar imenu@verb{|--|}index-alist

I had my suspicions about using space, even though it would be OK
according to the Texinfo manual, because LaTeX does _not_ allow space.

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

>    Still, even if it had worked, wouldn't it be best that the @defvr
>    macro treats multiple hyphens like @code does?
>
> Maybe, but what about 
>
> @defvar imenu@verb{|--|}index-alist
>
> I had my suspicions about using space, even though it would be OK
> according to the Texinfo manual, because LaTeX does _not_ allow space.

Identical results:

  ! Undefined control sequence.
  \tabeightspaces ->\catcode `\^^I=\active \def ^^I
                                                   {\ \ \ \ \ \ \ \ }
  \setupverb ...catcode `\`=\active \tabeightspaces 
                                                    \obeylines \uncatcodespeci...

  \verb ->\begingroup \setupverb 
                                 \doverb 
  <argument> imenu\verb 
                        {|--|}index-alist
  \code #1->#1

  \dosubind ...e \toks 0}\xdef \indexsorttmp {\temp 
                                                    }}\edef \temp {\write \csn...
  ...
  l.1850 @defvar imenu@verb{|--|}index-alist



  Lute.

Re: Double hyphens in variable names.

[Andreas Schwab]

Lute Kamstra <Lute.Kamstra@cwi.nl> writes:

> Luc Teirlinck <teirllm@dms.auburn.edu> writes:
>
>>    Still, even if it had worked, wouldn't it be best that the @defvr
>>    macro treats multiple hyphens like @code does?
>>
>> Maybe, but what about 
>>
>> @defvar imenu@verb{|--|}index-alist
>>
>> I had my suspicions about using space, even though it would be OK
>> according to the Texinfo manual, because LaTeX does _not_ allow space.
>
> Identical results:
>
>   ! Undefined control sequence.
>   \tabeightspaces ->\catcode `\^^I=\active \def ^^I
>                                                    {\ \ \ \ \ \ \ \ }
>   \setupverb ...catcode `\`=\active \tabeightspaces 
>                                                     \obeylines \uncatcodespeci...
>
>   \verb ->\begingroup \setupverb 
>                                  \doverb 
>   <argument> imenu\verb 
>                         {|--|}index-alist
>   \code #1->#1
>
>   \dosubind ...e \toks 0}\xdef \indexsorttmp {\temp 
                            ^^^^

This is the reason.  It tries to fully expand macros, but \verb is
special (not protected, in LaTeX terms).

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Double hyphens in variable names.

[Luc Teirlinck]

\verb apparently seems to be a LaTeX thing, not a TeX thing.  (I got
the same "Undefined control sequence." error in TeX, whereas it worked
perfectly in LaTeX.)  Texinfo uses TeX, not LaTeX.  However, according
to the Texinfo manual, it should have worked regardless.  I believe
that the fact that it did not work is a bug in Texinfo (unless I am
misunderstanding something).

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Kevin Rodgers]

Lute Kamstra wrote:

> What is the significance of a double hyphen in a symbol name anyway?

I suspect it was someone's attempt to emulate Common Lisp's use of

a colon between a package name and a symbol name without actually
implying that a package system exists in Emacs Lisp.  Blech,
get rid of them!

-- 
Kevin Rodgers

Re: Double hyphens in variable names.

[Oliver Scholz]

[Not directly related to the question about info:]

I was always assuming that variables and functions with a double
hyphen after the package prefix are supposed to be strictly internal.

If that is true then either `imenu--info-alist' should not start with
a double hyphen or it does not need documentation.

I may be wrong, though, and the double hyphen means something entirely
differen.

    Oliver
-- 
Oliver Scholz               11 Vendémiaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Double hyphens in variable names.

[Richard Stallman]

      I think that Texinfo
    should be changed so that the @defvr command (I assume that @defvar is
    defined in terms of @defvr) handles hyphens like @code.

I agree, that is clearly the right change.
Karl, is it feasible?

Re: Double hyphens in variable names.

[Luc Teirlinck]

>From my previous message:

   \verb apparently seems to be a LaTeX thing, not a TeX thing.  (I got
   the same "Undefined control sequence." error in TeX, whereas it worked
   perfectly in LaTeX.)  Texinfo uses TeX, not LaTeX.  However, according
   to the Texinfo manual, it should have worked regardless.  I believe
   that the fact that it did not work is a bug in Texinfo (unless I am
   misunderstanding something).

I changed my mind on this, since @verb in isolation seems to work
perfectly, in all situations you describe.  It apparently is not
supposed to be called from within other environments such as @code.

So the problem seems to be confined to @defvr.

In:

@defvar imenu@verb{|--|}index-alist

It seems that `imenu@verb{|--|}index-alist' sometimes get treated as
implicitly inside an @code (@verb does not work) and sometimes not
(@verb works).  Of course, this is inconsistent.

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Luc Teirlinck]

>From my previous message:

   I changed my mind on this, since @verb in isolation seems to work
   perfectly, in all situations you describe.  It apparently is not
   supposed to be called from within other environments such as @code.

But then again, @verb _does_ work within @code in as far as the Info
output is concerned.  It works from within other environments in
LaTeX.  The Texinfo documentation does not explicitly say whether
@verb is supposed to work from within @code.  I will let Karl decide
whether the fact that @verb does not work (in all situations) from
within @code is a bug or not.  Andreas pointed out the reason for the
problem, assuming it is one.

   It seems that `imenu@verb{|--|}index-alist' sometimes get treated as
   implicitly inside an @code (@verb does not work) and sometimes not
   (@verb works).  Of course, this is inconsistent.

I should have said "would be inconsistent" (if my impression would be
correct).

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Luc Teirlinck]

>From my previous message:

   I should have said "would be inconsistent" (if my impression would be
   correct).

Actually, as Lute pointed out, in:

@defvar imenu--index-alist

the `imenu--index-alist' does get treated @code-style in the variable
index (like everything else there, by default), so it does seem
inconsistent not to do it everywhere.

The TeX error has however nothing to do with an implicit @code.  (I
just got confused for a moment.)  Of course, it is due very concretely
to the problem Andreas pointed out.  What is not clear to me is
whether the problem is there because of oversight or because one just
does not care about @verb inside @code or @defvar.

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Lute Kamstra]

Oliver Scholz <epameinondas@gmx.de> writes:

> [Not directly related to the question about info:]
>
> I was always assuming that variables and functions with a double
> hyphen after the package prefix are supposed to be strictly
> internal.
>
> If that is true then either `imenu--info-alist' should not start
> with a double hyphen or it does not need documentation.

Ah, there's a thought!  The reason I wanted to document
imenu--info-alist is that the manual currently documents
imenu-info-alist.  I thought the name was changed, but from Imenu's
history in CVS I see that it never used imenu-info-alist; it used
imenu--info-alist from day one.  Imenu's functionality can be easily
explained without referring to imenu--info-alist, so I think I'll do
that.

> I may be wrong, though, and the double hyphen means something
> entirely different.

It makes sense in this case; I was wondering why the variable was
mentioned is the manual as Imenu did not use it to interface with the
outside world.

  Lute.

Re: Double hyphens in variable names.

[Luc Teirlinck]

Lute Kamstra wrote:

   Imenu's functionality can be easily explained without referring to
   imenu--info-alist, so I think I'll do that.

I guess you really mean imenu--index-alist.  If I understand
correctly, (elisp)Imenu explains how a major mode author can help
construct imenu--index-alist in various ways.  The major mode author
is not supposed to play around with imenu--index-alist directly.  But
is taking a look at imenu--index-alist not useful for the author to
check his work?  Also could knowing about the alist he is trying to
construct with the other functions not be useful in understanding
those other functions?  (Assuming my above interpretation of the facts
is correct).

I saw you removed the documentation for the variable.  If you really
think it ought to be removed, then that is OK.  I am not necessarily
contesting that removal.  You know the node better than I do.  I just
took a quick look at it.  However, as a solution to the double dash
problem, removal seems a little bit too radical.  I believe the
following works in all situations, main text and index of both Info
and printed output:

@defvar {imenu-@--index-alist}

OK this is ugly, but you could mention in the Texinfo source in a
comment that the ugliness is a work-around for a bug in Texinfo.  The
@- allows for a discretionary hyphen, but the text is short, so no
problem.  The braces around the entire name prevent the Info index
from just listing `imenu-'.  This will work even if the user does not
have makeinfo 4.7 or higher.  The current problems in Info need to be
fixed, but any such fix will require the user to install make-info
version 4.7 or higher.  (I believe 4.6 is still the latest released
version.)

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Luc Teirlinck]

Lute Kamstra wrote:

   Imenu's functionality can be easily explained without referring to
   imenu--info-alist, so I think I'll do that.

After reading things in somewhat more detail, it seems that you still
describe `imenu--info-alist' in as much detail as before, you just do
not mention its name.  I believe it would be better if you at least
mentioned that the return value of `imenu-create-index-function' is
stored in @code{imenu--info-alist}.  I believe that, as the return
value of `imenu-create-index-function', `imenu--info-alist' is not an
internal variable.  Strictly speaking, it should not have the two
consecutive dashes in its name.

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Luc Teirlinck]

>From my previous message:

   I believe it would be better if you at least
   mentioned that the return value of `imenu-create-index-function' is
   stored in @code{imenu--info-alist}.

@code{imenu--index-alist}, of course.

Sincerely,

Luc.

Re: Double hyphens in variable names.

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Lute Kamstra wrote:
>
>    Imenu's functionality can be easily explained without referring to
>    imenu--info-alist, so I think I'll do that.
>
> I guess you really mean imenu--index-alist.  

Yes, me braindead.

> If I understand correctly, (elisp)Imenu explains how a major mode
> author can help construct imenu--index-alist in various ways.  The
> major mode author is not supposed to play around with
> imenu--index-alist directly.  But is taking a look at
> imenu--index-alist not useful for the author to check his work?
> Also could knowing about the alist he is trying to construct with
> the other functions not be useful in understanding those other
> functions?  (Assuming my above interpretation of the facts is
> correct).

The author could just check the return value of the
imenu-create-index-function function that (s)he is writing.  Note that
I do describe this return value in detail.  I also mention that the
two other ways of setting up Imenu work through
imenu-create-index-function's default function.  I think that knowing
the name of the variable in which Imenu stores the return value is
only important when hacking on Imenu itself.

> I saw you removed the documentation for the variable.  If you really
> think it ought to be removed, then that is OK.

Yes, I do.

> I am not necessarily contesting that removal.  You know the node
> better than I do.  I just took a quick look at it.  However, as a
> solution to the double dash problem, removal seems a little bit too
> radical.

Getting rid of that problem is a nice by-product.  :-)

> I believe the following works in all situations, main text and index
> of both Info and printed output:
>
> @defvar {imenu-@--index-alist}
>
> OK this is ugly, but you could mention in the Texinfo source in a
> comment that the ugliness is a work-around for a bug in Texinfo.
> The @- allows for a discretionary hyphen, but the text is short, so
> no problem.  The braces around the entire name prevent the Info
> index from just listing `imenu-'.  This will work even if the user
> does not have makeinfo 4.7 or higher.  The current problems in Info
> need to be fixed, but any such fix will require the user to install
> make-info version 4.7 or higher.

Indeed, that seems to work well.  Thanks for the tip.

> (I believe 4.6 is still the latest released version.)

Yes.


  Lute.

Re: Double hyphens in variable names.

[Richard Stallman]

    If that is true then either `imenu--info-alist' should not start with
    a double hyphen or it does not need documentation.

I think this variable does not need to be in the manual.
However, it is just as well we found out about this Texinfo bug,
which I hope will be fixed soon.

Re: Double hyphens in variable names.

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Lute Kamstra wrote:
>
>    Imenu's functionality can be easily explained without referring to
>    imenu--info-alist, so I think I'll do that.
>
> After reading things in somewhat more detail, it seems that you still
> describe `imenu--info-alist' in as much detail as before, you just do
> not mention its name.  I believe it would be better if you at least
> mentioned that the return value of `imenu-create-index-function' is
> stored in @code{imenu--info-alist}.  I believe that, as the return
> value of `imenu-create-index-function', `imenu--info-alist' is not an
> internal variable.  Strictly speaking, it should not have the two
> consecutive dashes in its name.

When writing a major mode, you should never set imenu--index-alist
directly; nor should you have to use its value.  So it is not part of
Imenu's interface and therefore it is an internal variable.

  Lute.

Re: Double hyphens in variable names.

[Juri Linkov]

Since I just recently implemented new user interface to imenu
in ee-imenu (http://www.jurta.org/emacs/ee/imenu.en.html),
I can confirm that variable `imenu--info-alist' does not need to be
documented.  Only function `imenu-create-index-function' and its
return value are needed to be known to access imenu's internals.

-- 
http://www.jurta.org/emacs/

Re: Double hyphens in variable names.

[Karl Berry]

    The Texinfo documentation does not explicitly say whether
    @verb is supposed to work from within @code.  

I doubt it is worth the trouble to try to do this.  Can you think of a
reason why any real document would need @verb inside @code?  I can't.

Re: Double hyphens in variable names.

[Karl Berry]

    @defvar imenu--index-alist

I propose to make the @def... commands do an implicit @code, more or
less.  The principal change would be the names being printed in
typewriter (and typewriter slanted for arguments, I guess).  We'd get
ligature suppression for free, then.

This seems more logical than the roman fonts (bold and slanted) now
being used, although the roman fonts are prettier and take less space.

Does anyone object to that?

It would also be possible to write special-case code to remove ligatures
and such (in fact I seem to remember doing something along those lines
already for some past bug report), but all in all, the point is that
that identifiers is code, so we should print them in typewriter just
like other code fragments.

k

Re: Double hyphens in variable names.

[Luc Teirlinck]

Karl Berry wrote:

       The Texinfo documentation does not explicitly say whether
       @verb is supposed to work from within @code.  

   I doubt it is worth the trouble to try to do this.  Can you think of a
   reason why any real document would need @verb inside @code?  I can't.

No.  I was just wondering whether it was actually supposed to work or
not.  I can think of a real document where one would have wanted to
use it inside @defvar, but after the changes you propose, that will no
longer be necessary either.

Sincerely,

Luc.

Re: Double hyphens in variable names.

[David Ponce]

Hi,

 > When writing a major mode, you should never set imenu--index-alist
 > directly; nor should you have to use its value.  So it is not part of
 > Imenu's interface and therefore it is an internal variable.

Perhaps there is a case it is necessary to use `imenu--index-alist': to
force a rescan of the imenu.

For example, the Semantic toolkit set `imenu--index-alist' to nil to
force a rebuild of the imenu when the user customized an option that
change how the imenu will be organized (item sorted and/or grouped in
a different way).

Is there another "standard" method to force a rescan of the imenu
without using `imenu--index-alist'?

David

Re: Double hyphens in variable names.

[Richard Stallman]

    This seems more logical than the roman fonts (bold and slanted) now
    being used, although the roman fonts are prettier and take less space.

That sounds like a substantial change for the worse.  Taking up more
space may cause ugly breaks in some manuals.  Let's consider other
alternatives.

One other alternative is to use a fixed width font but slightly
smaller than the roman font now used.  That might use little or no
extra space.  It would have a drawback too, in reducing the visibility
of the function name, but it still could be better overall than using
a fixed width font of the same size.

Do you know of people who are sensitive that you could ask for advice?

Re: Double hyphens in variable names.

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
> One other alternative is to use a fixed width font but slightly
> smaller than the roman font now used.  That might use little or no
> extra space.  It would have a drawback too, in reducing the visibility
> of the function name, but it still could be better overall than using
> a fixed width font of the same size.

Mixing smaller font sizes in this way usually looks quite bad too.

-Miles
-- 
`The suburb is an obsolete and contradictory form of human settlement'

Re: Double hyphens in variable names.

[Werner LEMBERG]

>     This seems more logical than the roman fonts (bold and slanted)
>     now being used, although the roman fonts are prettier and take
>     less space.
> 
> That sounds like a substantial change for the worse.

I agree.

> One other alternative is to use a fixed width font but slightly
> smaller than the roman font now used.  That might use little or no
> extra space.  It would have a drawback too, in reducing the
> visibility of the function name, but it still could be better
> overall than using a fixed width font of the same size.

As already mentioned, it is ugly.

A TeXnical solution: Make the hyphen character active in @def... like
in this example:

  a - a -- a --- a

  \let\hyphen=-
  \catcode`\- \active
  \def-{\hyphen{}}

  a - a -- a --- a

I don't know how tricky this is to add, but a quick look into
texinfo.tex shows that only @code changes the category code of the
hyphen locally.


    Werner

Re: Double hyphens in variable names.

[Stepan Kasal]

Hello,

> Richard Stallman <rms@gnu.org> writes:
> > One other alternative is to use a fixed width font but slightly
> > smaller than the roman font now used.  That might use little or no
> > extra space.  It would have a drawback too, in reducing the visibility
> > of the function name, but it still could be better overall than using
> > a fixed width font of the same size.

The current implementation uses bxshape, which is pretty wide.  Replacing
cmbx10 by cmtt10 means getting _narrower_ results in average, I guess.

Observe the following excerpt from a .log file:

\bxshape:

> 48.07613pt.  l.1 \setbox0\hbox{\bf megabyte} \showthe\wd0
> 39.3956pt.   l.2 \setbox0\hbox{\bf variable} \showthe\wd0

\ttshape:

> 41.99963pt.  l.3 \setbox0\hbox{\tt megabyte} \showthe\wd0
> 41.99963pt.  l.4 \setbox0\hbox{\tt variable} \showthe\wd0

Two more notes:

On Sun, Oct 05, 2003 at 09:53:47AM +0900, Miles Bader wrote:
> Mixing smaller font sizes in this way usually looks quite bad too.
Sure.

current texinfo.tex contains:
| \setfont\defbf\bxshape{10}{\magstep1} %was 1314
| [...]
| \def\setdeffont#1 {\csname DEF#1\endcsname}
I don't know whether we prefer \defbf or \DEFbf (Karl?).

Have a nice day,
	Stepan Kasal

Re: Double hyphens in variable names.

[Lute Kamstra]

David Ponce <david.ponce@wanadoo.fr> writes:

>> When writing a major mode, you should never set imenu--index-alist
>> directly; nor should you have to use its value.  So it is not part
>> of Imenu's interface and therefore it is an internal variable.
>
> Perhaps there is a case it is necessary to use `imenu--index-alist':
> to force a rescan of the imenu.
>
> For example, the Semantic toolkit set `imenu--index-alist' to nil to
> force a rebuild of the imenu when the user customized an option that
> change how the imenu will be organized (item sorted and/or grouped
> in a different way).
>
> Is there another "standard" method to force a rescan of the imenu
> without using `imenu--index-alist'?

No, not on the lisp level.  There is a user-level way to do this: by
selecting the *Rescan* item from Imenu's menu.  Setting
imenu--index-alist to nil might work but it's not documented.  As it
seems useful for lisp programs to be able to force a rescan, we could
implement such a feature.  I'll try and see if I can come up with a
function that does this.

  Lute.

Re: Double hyphens in variable names.

[David PONCE]

Hi,

>>Is there another "standard" method to force a rescan of the imenu
>>without using `imenu--index-alist'?
> 
> No, not on the lisp level.  There is a user-level way to do this: by
> selecting the *Rescan* item from Imenu's menu.  Setting
> imenu--index-alist to nil might work but it's not documented.  As it
> seems useful for lisp programs to be able to force a rescan, we could
> implement such a feature.  I'll try and see if I can come up with a
> function that does this.

Thanks!  I think a such function will be very useful.  Perhaps it
could just contain the code run when selecting the *Rescan* item?
Something like this:

(defun imenu-refresh ()
  "Refresh the imenu."
  (imenu--cleanup)
  (setq imenu--index-alist nil)
  (imenu-update-menubar)
  t)

(defun imenu--menubar-select (item)
  "Use Imenu to select the function or variable named in this menu ITEM."
  (if (equal item imenu--rescan-item)
      (imenu-refresh)
    (imenu item)
    nil))

David

Re: Double hyphens in variable names.

[Lute Kamstra]

David PONCE <david.ponce@wanadoo.fr> writes:

>> As it seems useful for lisp programs to be able to force a rescan,
>> we could implement such a feature.  I'll try and see if I can come
>> up with a function that does this.
>
> Thanks!  I think a such function will be very useful.  Perhaps it
> could just contain the code run when selecting the *Rescan* item?
> Something like this:
>
> (defun imenu-refresh ()
>   "Refresh the imenu."
>   (imenu--cleanup)
>   (setq imenu--index-alist nil)
>   (imenu-update-menubar)
>   t)

Why insist on returning t?

> (defun imenu--menubar-select (item)
>   "Use Imenu to select the function or variable named in this menu ITEM."
>   (if (equal item imenu--rescan-item)
>       (imenu-refresh)
>     (imenu item)
>     nil))

I was thinking of something very similar. (I happens often, doesn't
it?)  I'll test it a bit first, though.

  Lute.

Re: Double hyphens in variable names.

[David PONCE]

>>(defun imenu-refresh ()
>>  "Refresh the imenu."
>>  (imenu--cleanup)
>>  (setq imenu--index-alist nil)
>>  (imenu-update-menubar)
>>  t)
> 
> 
> Why insist on returning t?

I just copied the code from `imenu--menubar-select' ;-)
I don't know the meaning of returning t after a rescan.

David

Re: Double hyphens in variable names.

[Juri Linkov]

Now Imenu is documented properly, but I want to suggest you to make
small corrections:

1. Documentation mentions the default value of
   imenu-create-index-function and even describes this function,
   but it don't tell the name of default function.
   You could add the default function name, i.e.:

- The default value of `imenu-create-index-function' is a function
- that uses `imenu-prev-index-position-function' and
+ The default value of `imenu-create-index-function' is the function
+ `imenu-default-create-index-function' that uses
+ `imenu-prev-index-position-function' and

2. Index name in `(INDEX-NAME SUB-ALIST)' actually refers to MENU-TITLE
   described above in the same Info node.  So you could change it to
   the same name, i.e.:

-          (INDEX-NAME SUB-ALIST)
+          (MENU-TITLE SUB-ALIST)

-- 
http://www.jurta.org/emacs/

Re: Double hyphens in variable names.

[Richard Stallman]

    (defun imenu-refresh ()
      "Refresh the imenu."

That makes sense.

    (defun imenu--menubar-select (item)
      "Use Imenu to select the function or variable named in this menu ITEM."

What is that useful for?

Re: Double hyphens in variable names.

[Lute Kamstra]

Richard Stallman <rms@gnu.org> writes:

>     (defun imenu-refresh ()
>       "Refresh the imenu."
>
> That makes sense.
>
>     (defun imenu--menubar-select (item)
>       "Use Imenu to select the function or variable named in this menu ITEM."
>
> What is that useful for?

It's the existing function from which David "stole" the implementation
of imenu-refresh.

  Lute.

Re: Double hyphens in variable names.

[David PONCE]

>>    (defun imenu--menubar-select (item)
>>      "Use Imenu to select the function or variable named in this menu ITEM."
>>
>>What is that useful for?
> 
> 
> It's the existing function from which David "stole" the implementation
> of imenu-refresh.

Absolutely right ;-)

Thanks Lute!

David

Re: Double hyphens in variable names.

[Lute Kamstra]

Juri Linkov <juri@jurta.org> writes:

> Now Imenu is documented properly, but I want to suggest you to make
> small corrections:
>
> 1. Documentation mentions the default value of
>    imenu-create-index-function and even describes this function,
>    but it don't tell the name of default function.
>    You could add the default function name, i.e.:
>
> - The default value of `imenu-create-index-function' is a function
> - that uses `imenu-prev-index-position-function' and
> + The default value of `imenu-create-index-function' is the function
> + `imenu-default-create-index-function' that uses
> + `imenu-prev-index-position-function' and
>
> 2. Index name in `(INDEX-NAME SUB-ALIST)' actually refers to MENU-TITLE
>    described above in the same Info node.  So you could change it to
>    the same name, i.e.:
>
> -          (INDEX-NAME SUB-ALIST)
> +          (MENU-TITLE SUB-ALIST)

Thanks a lot, Juri!  I'll commit your changes as soon as I've
committed some other changes in the same file that I'm working on
right now.

  Lute.