[drew.adams@oracle.com: RE: cannot find :enable in Elisp manual index]

[drew.adams@oracle.com: RE: cannot find :enable in Elisp manual index]

[Richard Stallman]

Would someone please DTRT, then ack?

------- Start of forwarded message -------
X-Spam-Status: No, score=0.0 required=5.0 tests=UNPARSEABLE_RELAY 
	autolearn=failed version=3.1.0
From: "Drew Adams" <drew.adams@oracle.com>
To: "Emacs-Pretest-Bug" <emacs-pretest-bug@gnu.org>
Date: Thu, 24 May 2007 17:30:58 -0700
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
In-Reply-To: <BDEIJAFNGDOAGCJIPKPBOEJLCEAA.drew.adams@oracle.com>
Subject: RE: cannot find :enable in Elisp manual index

Same problem for ":type". It would be useful to be able to enter ":type" at
the `i' prompt and go to manual pages that mention ":type" (not just
"type").



> From: Drew Adams Sent: Tuesday, May 22, 2007 8:26 AM
>
> emacs -Q
> C-h i, choose Elisp manual
> i :enable
>
> There is no index entry for :enable.
>
> Also, entries for "enable" are shown, even though I type
> ":enable". That is, the `:' is ignored, instead of narrowing the set
> of matches.
>
> In GNU Emacs 22.0.96.1 (i386-mingw-nt5.1.2600)
>  of 2007-03-21 on LENNART-69DE564
> Windowing system distributor `Microsoft Corp.', version 5.1.2600
> configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'




_______________________________________________
emacs-pretest-bug mailing list
emacs-pretest-bug@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
------- End of forwarded message -------

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manual index]

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Fri, 25 May 2007 20:19:57 -0400
> 
> Would someone please DTRT, then ack?

Is this even feasible?  Index entries cannot include colons, it's a
limitation of the Info format.  The Texinfo manual clearly says not to
use them.

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Drew Adams]

> > Would someone please DTRT, then ack?
>
> Is this even feasible?  Index entries cannot include colons, it's a
> limitation of the Info format.  The Texinfo manual clearly says not to
> use them.

That's really too bad, if it's the case. Keywords are important things to
put in an index (not to mention the fact that some languages to be
documented might use colons in special ways). If this is really not
feasible, then users are reduced to using search in Info to find a keyword
such as :type, :display, or :enable - pretty primitive (but still far better
than visiting the many "type", "display", "enable" etc. index entries).

Is there no way to escape a colon somehow, so that Info does not interpret
it? The Texinfo manual says that this limitation is because "a colon
separates the menu entry name from the node name, so a colon in the entry
name confuses Info." If there is no way to escape a colon - to let Info know
when a colon doesn't indicate a menu + entry, then shouldn't there be?

Analogy: In Framemaker, colons in index entries are used to create
hierarchical entries, so, e.g., "foo:bar" produces an index entry "foo" with
subentry "bar". You can nevertheless escape a colon with a backslash, so,
e.g., "foo:bar\:toto" produces entry "foo" with subentry "bar:toto".

I haven't used TeX/LaTeX/Texinfo for 20 years, but my memory of LaTeX and
Tex, at least, is of something very powerful and flexible. I'm surprised if
there is no such escape mechanism for Texinfo.

Suggestion: If a user enters a colon at the `Info-index' prompt, print a
message saying 1) that the colon is being ignored, and 2) you can, as an
alternative, use search (`s' or `C-s') to search the manual for a term that
contains a colon. IOW, let users know right away how to work around this
limitation.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Mon, 28 May 2007 21:01:52 -0700
> 
> That's really too bad, if it's the case. Keywords are important things to
> put in an index (not to mention the fact that some languages to be
> documented might use colons in special ways). If this is really not
> feasible, then users are reduced to using search in Info to find a keyword
> such as :type, :display, or :enable - pretty primitive

Actually, I don't think it's so bad as you make it sound -- in the
case of Emacs Lisp (as opposed to, for example, C++), because I really
doubt that many people would use `:foo' instead of `foo' to look for
the keywords.  After all, the colon is similar to the quote ' in Emacs
Lisp, and you aren't going to lobby for indexing 'keymap or
'wrong-number-of-arguments, would you?

> (but still far better
> than visiting the many "type", "display", "enable" etc. index entries).

Please suggest how to qualify the index entries for the keywords that
use such common words, so that they would clearly stand out in the
list popped by TAB-completion.

> Is there no way to escape a colon somehow, so that Info does not interpret
> it?

Sadly, no.

> I haven't used TeX/LaTeX/Texinfo for 20 years, but my memory of LaTeX and
> Tex, at least, is of something very powerful and flexible.

TeX and LaTeX are powerful, but Texinfo is implemented by a very
simple one-pass processor and a bunch of TeX macros, so it doesn't
have a power that is anywhere near that.

> Suggestion: If a user enters a colon at the `Info-index' prompt, print a
> message saying 1) that the colon is being ignored, and 2) you can, as an
> alternative, use search (`s' or `C-s') to search the manual for a term that
> contains a colon.

I think index search is so much more powerful that `s', even with the
colon problem, that it's not a good idea to suggest `s'.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Stephen Berman]

On Tue, 29 May 2007 22:12:12 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> (but still far better
>> than visiting the many "type", "display", "enable" etc. index entries).
>
> Please suggest how to qualify the index entries for the keywords that
> use such common words, so that they would clearly stand out in the
> list popped by TAB-completion.

How about "type (keyword)", "display (keyword)", "enable (keyword)"?

Steve Berman

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Eli Zaretskii]

> From: Stephen Berman <Stephen.Berman@gmx.net>
> Date: Tue, 29 May 2007 22:05:23 +0200
> 
> How about "type (keyword)", "display (keyword)", "enable (keyword)"?

Thanks.  This is what we do already, please take a look at the index
entries.  I thought maybe we can come up with something better.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Stephen Berman]

On Tue, 29 May 2007 23:58:02 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stephen Berman <Stephen.Berman@gmx.net>
>> Date: Tue, 29 May 2007 22:05:23 +0200
>> 
>> How about "type (keyword)", "display (keyword)", "enable (keyword)"?
>
> Thanks.  This is what we do already, please take a look at the index
> entries.  I thought maybe we can come up with something better.

Whoops, sorry.  Actually, I did do `i type TAB TAB' before posting,
and noticed "type (button property)", which prompted my suggestion.
In my haste I overlooked "type, defcustom keyword".  For me, the
latter is a bit less eye-catching than using parentheses as I
suggested, but I would consider either quite adequate.  My Elisp
manual (from GNU Emacs 22.1.50.1 of 2007-04-30) does not contain index
entries "display, defcustom keyword" or "enable, defcustom keyword",
but perhaps they've been added since (if not, I again would prefer the
parenthentical form).

Steve Berman

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Drew Adams]

> >> (but still far better than visiting the many "type",
> >> "display", "enable" etc. index entries).
> >
> > Please suggest how to qualify the index entries for the keywords that
> > use such common words, so that they would clearly stand out in the
> > list popped by TAB-completion.
>
> How about "type (keyword)", "display (keyword)", "enable (keyword)"?

I didn't understand Eli's request, but now I guess I do. Your suggestion is,
I guess, that entries for keywords would contain " (keyword)". Yes, that
would be a good workaround.

Of course, a user who just types `i enable RET', instead of `i enable TAB'
will never know about this possibility... Still, this is worth doing, IMO.

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Drew Adams]

> > That's really too bad, if it's the case. Keywords are important
> > things to put in an index (not to mention the fact that some
> > languages to be documented might use colons in special ways).
> > If this is really not feasible, then users are reduced to
> > using search in Info to find a keyword
> > such as :type, :display, or :enable - pretty primitive
>
> Actually, I don't think it's so bad as you make it sound -- in the
> case of Emacs Lisp (as opposed to, for example, C++), because I really
> doubt that many people would use `:foo' instead of `foo' to look for
> the keywords.  After all, the colon is similar to the quote ' in Emacs
> Lisp, and you aren't going to lobby for indexing 'keymap or
> 'wrong-number-of-arguments, would you?

Nonsense.

1) Info is not just for Emacs and Emacs Lisp.

2) Looking up ":type" as opposed to "type" is in no way analogous to looking
up "'keymap" as opposed to "keymap". I can't believe that you would suggest
such a thing.

> > (but still far better than visiting the many "type",
> > "display", "enable" etc. index entries).
>
> Please suggest how to qualify the index entries for the keywords that
> use such common words, so that they would clearly stand out in the
> list popped by TAB-completion.

I don't understand the request. I see no problem with showing ":type" in
*Completions*. Please explain.

You should be able to type ":type" (without the quotes) at the `Info-index'
prompt, and have it take you to a node that discusses :type.

> > Is there no way to escape a colon somehow, so that Info does
> > not interpret it?
>
> Sadly, no.

Dommage. That would be a useful enhancement.

> > I haven't used TeX/LaTeX/Texinfo for 20 years, but my memory of
> > LaTeX and Tex, at least, is of something very powerful and
> > flexible.
>
> TeX and LaTeX are powerful, but Texinfo is implemented by a very
> simple one-pass processor and a bunch of TeX macros, so it doesn't
> have a power that is anywhere near that.
>
> > Suggestion: If a user enters a colon at the `Info-index' prompt,
> > print a message saying 1) that the colon is being ignored, and
> > 2) you can, as an alternative, use search (`s' or `C-s') to
> > search the manual for a term that contains a colon.
>
> I think index search is so much more powerful that `s', even with the
> colon problem, that it's not a good idea to suggest `s'.

1: I agree with you 100% about the relative utility of `i' over `s' - in
general.

2: I disagree with you 100% in the case of keywords. Try it. Pick one and
count how many keystrokes or whatever it takes to get you to a node that
actually discusses that keyword using both `i' and `s'. The latter wins
hands down.

With `i :link', you have to visit 17 index entries out of 20 before you get
to a node containing :link. But `s' with `:link' takes you immediately to a
node discussing :link - in fact, of course, all hits of `s :link' discuss
:link. Similarly for other keywords: With :tag you must visit 6 out of 6
`tag' entries to finally get to :tag; with :group 4/11; :load 19/42;
:require 4/5; :version 24/30.

Neither `i :enable' nor `i :keymap' in the Elisp manual will _ever_ get you
to a page with that keyword - they're not indexed at all. Of course, to find
that out for :keymap, say, you will need to visit all 45 entries and check
for ":keymap" in each one!

It's hard to imagine why you would "think index search is so much more
powerful that `s', _even with the colon problem_." Maybe we have different
ideas of "powerful".

#1 + #2: That's why I wrote: "users are reduced to using search
in Info to find a keyword". "Reduced to" in the sense of limited
functionality, because `i' is usually much better than `s' (when there is an
appropriate index entry). "Reduced to" also in the sense of forced to,
because `s' is better than `i' for keywords (sadly).

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <rms@gnu.org>, <emacs-devel@gnu.org>
> Date: Tue, 29 May 2007 14:03:10 -0700
> 
> Nonsense.

If you want to continue this discussion with me, please stop the
attitude.  I have better things to do with my scarce free time than
talk to someone who thinks that about my opinions.

> 1) Info is not just for Emacs and Emacs Lisp.

But I was talking _only_ about the ELisp manual, and I said that
explicitly.  There's no argument that this is a grave limitation for
some other manuals (and I said that explicitly as well).

> 2) Looking up ":type" as opposed to "type" is in no way analogous to looking
> up "'keymap" as opposed to "keymap". I can't believe that you would suggest
> such a thing.

Well, then maybe we have quite different perceptions of the Emacs Lisp
syntax and semantics.  The colon plays a role that is very similar to
the quote: it is used to mean the literal symbol name as opposed to
the value of the symbol.

> 2: I disagree with you 100% in the case of keywords. Try it. Pick one and
> count how many keystrokes or whatever it takes to get you to a node that
> actually discusses that keyword using both `i' and `s'. The latter wins
> hands down.
> 
> With `i :link', you have to visit 17 index entries out of 20 before you get
> to a node containing :link.

That's not what I'd suggest to do in this situation.  I'd suggest to
type "i link TAB".  Then I see this:

    Possible completions are:
    link, customization keyword	   linking files

and it's quite clear that the first one is the one I want.

> Neither `i :enable' nor `i :keymap' in the Elisp manual will _ever_ get you
> to a page with that keyword - they're not indexed at all. Of course, to find
> that out for :keymap, say, you will need to visit all 45 entries and check
> for ":keymap" in each one!

`enable' isn't indexed at all, but "i keymap TAB TAB TAB" immediately
shows 3 different usages of :keymap at the beginning of the list of
completions.  No need to visit 45 entries.

> It's hard to imagine why you would "think index search is so much more
> powerful that `s', _even with the colon problem_."

Well, maybe now you understand that better.

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Drew Adams]

> > > I really doubt that many people would use `:foo' instead of
> > > `foo' to look for the keywords.

Seems like the most natural thing, to me. If you want to look up "bobsled",
you type "bobsled"; you don't type "obsled".

> > > After all, the colon is similar to the quote ' in Emacs
> > > Lisp, and you aren't going to lobby for indexing 'keymap or
> > > 'wrong-number-of-arguments, would you?

I would look up the keyword :type by entering its name, ":type". I think
most users would.

`'type', or `(quote type)', is not the keyword, and neither is `type'. The
keyword is the symbol `:type', that is, the symbol whose name is ":type"
(not "type").

> > 2) Looking up ":type" as opposed to "type" is in no way
> >    analogous to looking up "'keymap" as opposed to "keymap".
>
> Well, then maybe we have quite different perceptions of
> the Emacs Lisp syntax and semantics.

Perhaps we have. What is your perception of this?

(symbol-name :type)  => ":type"
(symbol-name ':type) => ":type"
(symbol-name 'type)  => "type"

(symbol-value :type)  => ":type"
(symbol-value ':type) => ":type"
(symbol-value 'type)  => Error, void variable type

The symbol whose name is ":type" has itself as its value. And this is not
the same symbol as the symbol whose name is "type" (and which has no
predefined value). The latter is not a keyword.

> The colon plays a role that is very similar to
> the quote: it is used to mean the literal symbol name as opposed to
> the value of the symbol.

The literal symbol name of :type is ":type". It is not "type".

The colon is part of the name; it is not just a quoting mechanism.
Evaluation to self is not implicit quotation: (eval (eval (eval :foo))) is
:foo, but (eval (eval (eval 'foo))) is usually something quite different
from `foo'.

Keywords are constant symbols - symbols that evaluate to themselves, just
like t and nil. Would you say that there is an invisible quote-like thingy
in front of t and nil that although we can't see it "is used to mean the
literal symbol name as opposed to the value of the symbol" t or nil?

> > 2: I disagree with you 100% in the case of keywords. Try it.
> >    Pick one and count how many keystrokes or whatever it takes
> >    to get you to a node that actually discusses that keyword
> >    using both `i' and `s'. The latter wins hands down.
> >
> >    With `i :link', you have to visit 17 index entries out of 20
> >    before you get to a node containing :link.
>
> That's not what I'd suggest to do in this situation.
> I'd suggest to type "i link TAB".

Good point. To find the index entry for `:type' users can hit `type TAB'
instead of `:type RET'. Fair enough. But you know, some users just might not
think to do that. After all, if they've used Emacs before version 22 (which
introduced index-entry completion), then they just might not be in the habit
yet.

Don't get me wrong - I'm happy we have the `type, defcustom keyword'
workaround. But some users might never use TAB here and so never notice it.
Or, like me, they might have learned about it but they might forget it
occasionally - old habits die hard. And, even if they do notice and do
remember, they might not know the intimate details about Info's colon
difficulties (!), so they might naturally try `i :type TAB', with no match
and no message teaching them their mistake.

So, let's draw user attention to the workaround. I repeat my previous
suggestion about displaying a helpful message when the user enters a keyword
name such as `i :foobar' (i.e. with a colon), whether with TAB or RET, but
amend it to suggest that they use `i foobar, defcustom keyword'. (I withdraw
my suggestion of suggesting `s :foobar'.) IOW, if Info can't handle colons,
but users don't know that and might well try to use them, then let's inform
them how to get the job done.

It's not ideal for completion to give the impression that the keyword is
`type' when it is really `:type' ("type, defcustom keyword"), but at this
point it seems unavoidable. I hope this can be fixed in the future.

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Drew Adams]

I said:

> display a helpful message when the user enters a keyword
> name such as `i :foobar' (i.e. with a colon), whether with
> TAB or RET, ... to suggest that they use `i foobar, defcustom keyword'.

That would be OK for the Emacs-Lisp manual, but for Info more generally
perhaps we should display a message saying that a colon cannot be present in
an index entry and so it is ignored.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Johan Bockgård]

"Drew Adams" <drew.adams@oracle.com> writes:

> Don't get me wrong - I'm happy we have the `type, defcustom keyword'
> workaround. But some users might never use TAB here and so never
> notice it. Or, like me, they might have learned about it but they
> might forget it occasionally

No kidding.


From: Drew Adams
Subject: RE: no :type in Elisp index
Date: Sun, 26 Nov 2006 14:14:21 -0800

> > emacs -Q
> > C-h i, choose Elisp manual
> > i :type gives message "Info-index: No `:type' in index"
> 
> Alas, index entries cannot have colons in them.

I didn't know that. That's too bad.

> If you type "i type TAB", you will see an index entry for the
> `:type' button property, though. Is that what you were looking for?

No. Please add a `type' index entry for node "Customization Types".

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Eli Zaretskii]

> From: bojohan+news@dd.chalmers.se (Johan =?utf-8?Q?Bockg=C3=A5rd?=)
> Date: Wed, 30 May 2007 17:17:33 +0200
> 
> > If you type "i type TAB", you will see an index entry for the
> > `:type' button property, though. Is that what you were looking for?
> 
> No. Please add a `type' index entry for node "Customization Types".

There is one already: "type, defcustom keyword".

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Drew Adams" <drew.adams@oracle.com>
>
>> 2) Looking up ":type" as opposed to "type" is in no way analogous
>> to looking up "'keymap" as opposed to "keymap". I can't believe
>> that you would suggest such a thing.
>
> Well, then maybe we have quite different perceptions of the Emacs
> Lisp syntax and semantics.  The colon plays a role that is very
> similar to the quote: it is used to mean the literal symbol name as
> opposed to the value of the symbol.

Not really: it makes the symbol a self-quoting one, but the colon is
part of that symbol.  You can easily see this by typing
M-: :test RET

>> It's hard to imagine why you would "think index search is so much
>> more powerful that `s', _even with the colon problem_."
>
> Well, maybe now you understand that better.

While I don't agree with Drew's way of asking for things (though in
all fairness I am probably not much better), I think having keywords
starting with colon indexed would be definitely appropriate and
expected behavior.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Eli Zaretskii]

> Cc: "Drew Adams" <drew.adams@oracle.com>,  rms@gnu.org,  emacs-devel@gnu.org
> From: David Kastrup <dak@gnu.org>
> Date: Wed, 30 May 2007 07:23:52 +0200
> 
> I think having keywords starting with colon indexed would be
> definitely appropriate and expected behavior.

Me too (as I said), but it's unfortunately impossible at the moment
(as I said).  The discussion was how much of a catastrophe is that
(well, at least that's what _I_ was talking about; Drew's offensive
sarcasm, I no longer understand what it's about).

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Eli Zaretskii]

> Date: Thu, 31 May 2007 02:01:22 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: drew.adams@oracle.com, emacs-devel@gnu.org
> 
> Drew's offensive sarcasm, I no longer understand what it's about

Actually, let me be honest and say that I simply do not _want_ to
understand what it's about, given the style and the attitude.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    Is there no way to escape a colon somehow, so that Info does not interpret
    it? The Texinfo manual says that this limitation is because "a colon
    separates the menu entry name from the node name, so a colon in the entry
    name confuses Info." If there is no way to escape a colon - to let Info know
    when a colon doesn't indicate a menu + entry, then shouldn't there be?

In the long term, we could redesign Info format.  However, such a change
takes years to put into place.

Instead of doing this, perhaps it would be better to replace the format
with a completely new format.

I wonder if we could use some limited subset of HTML, so that Emacs
could display it even though it doesn't really understand HTML.
Meanwhile, any browser could also display it, and standalone Info
could be a variant of a browser.

Karl, what do you think?

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Jason Rumney]

Richard Stallman wrote:
> In the long term, we could redesign Info format.  However, such a change
> takes years to put into place.
>   
Rather than using \: to escape a colon, which would not be backwards
compatible so would take years to filter through, it might be a good
idea to introduce SGML character entities to texinfo, so a colon could
be escaped as :

This will only work if &, # and ; do not already have special meaning in
texinfo (I don't know enough about the format to answer that but I'm
sure many here do).
Then if the user is using an older version of info they will see
":enable" in the index instead of ":enable", but at least info will
not be confused into doing something wrong.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    Rather than using \: to escape a colon, which would not be backwards
    compatible so would take years to filter through, it might be a good
    idea to introduce SGML character entities to texinfo, so a colon could
    be escaped as :

That seems plausible.

    This will only work if &, # and ; do not already have special meaning in
    texinfo

They don't.

Karl, what do you think of this idea?

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Robert J. Chassell]

    Is there no way to escape a colon somehow, so that Info does not
    interpret it?

Colons came into the early Info long before their other uses were
invented.  As RMS says, 

    In the long term, we could redesign Info format.  However, such a
    change takes years to put into place.

He wonders

    ... if we could use some limited subset of HTML ...

Consider DebianDoc, which is an XML format that looks like HTML and
converts to Texinfo.  It exists and works fine.

    http://www.debian.org/doc/manuals/sgml-howto/x306.html

However, the key is code that converts from the Microsoft windowing
system `doc' format that is used by many, including, for example, US
nuclear operators.  They use it for `procedures' (what we would call
`written orders').

The `doc' format handles many of the layout, font, and printing needs
that people have.  Moreover, it is now used by many even though it
carries legal restrictions.

It is intended for printing on paper but in Texinfo or in a
deriviative could be converted to HTML, DVI, PDF, PostScript, LaTeX,
and such, for high resolution output.

Converting it to the low resolution output that Info offers would be
more difficult and perhaps impossible.  If that could be done, then we
would be golden.

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    The `doc' format handles many of the layout, font, and printing needs
    that people have.  Moreover, it is now used by many even though it
    carries legal restrictions.

What precisely are these legal restrictions?
I need a clear picture of the situation
in order to think about its implications.

    Converting it to the low resolution output that Info offers would be
    more difficult and perhaps impossible.

Could you mention one issue that makes this difficult?

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Robert J. Chassell]

       The `doc' format handles many of the layout, font, and printing needs
       that people have.  Moreover, it is now used by many even though it
       carries legal restrictions.

   What precisely are these legal restrictions?

Last I heard, Microsoft did not permit you to give or sell binaries or
source code of its proprietary software to others without their
permission; nor could you modify or study it.  I have not read the
license to which you must agree when you rent their code.

       Converting it to the low resolution output that Info offers
       would be more difficult and perhaps impossible.

   Could you mention one issue that makes this difficult?

I don't think any is difficult but no one has made the conversion for
Open Office.  Maybe there is not enough interest or maybe the
conversion really is difficult; I don't know.  The Open Office format
has automatic numbering of paragraphs, sections, etc., and can be
converted to HTML (and it has many other features, but those I
remember).

I don't use Open Office; I use Texinfo and produce both high and low
resolution outputs.  Regularly, I produce DVI, PDF, HTML, and Info.
(Interest has decreased for PostScript, so I don't produce that every
day.  I don't produce LaTeX, RTF, DocBook, XML with a Texinfo DTD, or
plain text everyday, either.)  

Many people like to see their output as they write -- for anything
sighted people look at, that means three outputs currently:

  * high resolution frozen, printed books, which can be taken from the
    DVI output,

  * high resolution with active links, which can be taken from the
    HTML output, and

  * low resolution with active links, which can be taken from Info.

So with the Texinfo source, that means four views of the same content.
(Several years ago, I made a crude beginning of this, but no one else
cared; and I usually don't need to see the current outputs, so I lost
interest.)

As far as I can see, a converter would make it easier for some
organizations to change without as high a cost as they now face.

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

	   The `doc' format handles many of the layout, font, and printing needs
	   that people have.  Moreover, it is now used by many even though it
	   carries legal restrictions.

       What precisely are these legal restrictions?

    Last I heard, Microsoft did not permit you to give or sell binaries or

I had no idea you were talking about Word format.
We certainly don't want to use that.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Alan Mackenzie]

Morning, Richard!

On Fri, Jun 01, 2007 at 10:54:02PM -0400, Richard Stallman wrote:
[Drew Adams]:
>     Is there no way to escape a colon somehow, so that Info does not
>     interpret it? The Texinfo manual says that this limitation is
>     because "a colon separates the menu entry name from the node name,
>     so a colon in the entry name confuses Info." If there is no way to
>     escape a colon - to let Info know when a colon doesn't indicate a
>     menu + entry, then shouldn't there be?

> In the long term, we could redesign Info format.  However, such a change
> takes years to put into place.

Would enhancing the format with some quoting convention really amount to
a redesign, rather than just being an incremental enhancement?

> Instead of doing this, perhaps it would be better to replace the
> format with a completely new format.

Hmm.  I don't think that would go down well - "oh, not _another_ silly
document format from these wierd free software types".  ;-(  I think
that would push projects to use inferior (see below) existing formats
rather than "Infoplus".

> I wonder if we could use some limited subset of HTML, so that Emacs
> could display it even though it doesn't really understand HTML.
> Meanwhile, any browser could also display it, and standalone Info
> could be a variant of a browser.

> Karl, what do you think?

I'm not Karl, but....

I think this is a horrible idea.  I used to get lots of emails in HTML,
and I hated it.  The great thing about Info format is that you can read
it.  It's text.  You can dump it to a terminal, you can print it, you
can read it in Emacs, you can read it in an email client, you can read
it in the bath.  You can grep it, wc it, AWK it, perl it, head it, tail
it, and tailor it to ANY purpose with standard GNU tools.  Heck, you can
even write an Info file directly in Emacs (not that anyone does, of
course).

Info files have a very high signal/noise ratio.  95%, perhaps?  HTML
files have a much lower one.  Maybe around 40% on a good day.  Even with
hard drive sizes of several hundred gigabytes, I don't think we should
be cluttering up people's disks with megabytes of dumb html tags.

Now I predict that someone else is going to respond with "hey, why don't
we just use docbook?".  Well, why not?  For a start, [A-Z]+ML are
ghastly formats for people.  They're not really human readable, and thus
need special tools to edit them.  How many people edit XML directly in
Emacs?  I've tried it, and it's not nice.  You can't comment out
sections of code, it's almost as bloated as Cobol, and it uses stropped
keywords rather than braces to delimit sections.

Stropped keywords?  Anybody else here remember when you had to write
'begin' ..... 'end' in Algol (including the quotes)?  Thankfully that
became BEGIN .... END in everybody's "not my favourite" language, and
optimally became { .... } with C (and superoptimally a bit of
indentation in Python).  XML has gone back to the bad old Algol days
with the likes of <SUPERSCRIPTED_LETTER> ....  </SUPERSCRIPTED_LETTER>.

<YUCK> .... </YUCK>.

What is so difficult about quoting : in Info?  (And, for that matter,
other characters like "." as in @xref{Sample .emacs File,,,ccmode}).
Little more than identifying a suitable quoting character.  \ won't do,
because you'd break compatibility with every other existing manual.

However, we're surely not restricted to plain ASCII anymore, or are we?
So why couldn't we quote things with non-break-space (0xA0)?  That would
be minimally obtrusive when just reading the Info file as text.  In
Texinfo, it could be represented something like @quote{:}.  It would be
minimal work to implement in Texinfo.

-- 
Alan Mackenzie (Ittersbach, Germany).

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Drew Adams]

> > I wonder if we could use some limited subset of HTML, so that Emacs
> > could display it even though it doesn't really understand HTML.
> > Meanwhile, any browser could also display it, and standalone Info
> > could be a variant of a browser.

I won't get into a heated discussion about this (at least I'll try to stay
out ;-)), but I will say this, in spite of some good (and some not so good)
ideas voiced by Alan: I think it is a _good_ idea - one worth exploring
(discussing), at least.

Sure, HTML is bloated, as Alan pointed out. I don't care too much about
that, but others might. There are tools to remove the formatting junk. Just
as Info is an output format (Texinfo being the editing medium), so is HTML.

HTML is truly ubiquitous. In the form of XHTML (which is XML and is also
~HTML 4.0), it is easily manipulated by program, and there are many tools to
do that. There are tools to transform it to practically any output or
intermediate format one can imagine, and if some such tool doesn't exist, it
can be built using XML transformation tools such as XSLT and XQuery. Every
modern doc production system is now XML-based - and becoming increasingly
more so. Even authoring tools such as Framemaker now have XML as innards.
Even Microsoft Office is moving to XML.

I'm not necessarily suggesting that Texinfo should be XML-based or should be
sidestepped in favor of XML from the beginning. I'm saying that XHTML can be
a better output format than is Info, _and_ you can manipulate it better.
IOW, Texinfo -> some internal XML model -> XHTML. (The latter transformation
is XML to XML, from internal model to presentation format.)

Yes, I think it's not a bad idea at all. Bravo! The more I think about it,
the more I don't see why this shouldn't be done. (And a side effect might be
that Emacs would become (even) more XML savvy.)

Again, no flames please. I just wanted to voice my vote.

[I do also agree, BTW, with Alan and others who have said that we need not
do this just because we cannot escape colons for Info! We can add colon
escaping to Texinfo/Info separately. Moving from Info to XHTML is a separate
question, IMO.]

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Eli Zaretskii]

> Date: Sat, 2 Jun 2007 11:18:10 +0100
> Cc: Drew Adams <drew.adams@oracle.com>, eliz@gnu.org, karl@gnu.org,
>   emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> Would enhancing the format with some quoting convention really amount to
> a redesign, rather than just being an incremental enhancement?

If you can suggest a quoting convention that doesn't break backward
compatibility, maybe it will qualify as incremental enhancement.  It's
not easy, since currently Info is almost plain text, so any character
can be used in it.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Alan Mackenzie]

Hi, Eli!

On Sat, Jun 02, 2007 at 08:26:13PM +0300, Eli Zaretskii wrote:
> > Date: Sat, 2 Jun 2007 11:18:10 +0100
> > Cc: Drew Adams <drew.adams@oracle.com>, eliz@gnu.org, karl@gnu.org,
> >   emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > Would enhancing the format [Info] with some quoting convention
> > really amount to a redesign, rather than just being an incremental
> > enhancement?

> If you can suggest a quoting convention that doesn't break backward
> compatibility, maybe it will qualify as incremental enhancement.  It's
> not easy, since currently Info is almost plain text, so any character
> can be used in it.
 
I suggested using "non-break-space" as an an escape character (though
the suggestion probably got buried in the rant).  This isn't an ASCII
character, but is 0xA0 in ISO-8859-1.  If NBS is common enough
throughout character sets, it would be a minimally disruptive
convention, since it would appear simply as a space in displayers which
didn't interpret it.

-- 
Alan.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Jason Rumney]

Alan Mackenzie wrote
> I suggested using "non-break-space" as an an escape character

The problem is not what you make the escape character, it is how you
avoid putting a colon somewhere where older versions of Emacs and the
standalone info reader are not expecting it.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    I think this is a horrible idea.  I used to get lots of emails in HTML,
    and I hated it.  The great thing about Info format is that you can read
    it.

It is not hard to read hand-written HTML such as is used on gnu.org.

      It's text.

But that means there are no faces, no graphics, no non-ASCII
characters, etc.  Info format was a fine way of representing
documentation in the 1970s, with the features that made sense for
on-line reading at the time.  But now much better features are normal
for displaying text, even in Emacs.

      How many people edit XML directly in
    Emacs?  I've tried it, and it's not nice.

My suggestion was to use a limited subset of HTML, not XML.  I edit
simple HTML by hand often for gnu.org pages.

I do not know how XML differs from HTML.  Perhaps something makes XML
harder to edit than HTML; I have no opinion about that.

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Drew Adams]

> I do not know how XML differs from HTML.  Perhaps something makes XML
> harder to edit than HTML; I have no opinion about that.

Just a point of info: Both XML and HTML code can be complex. And some XML
and some HTML code can be simple.

If a generalization about editing ease can be made, it is the opposite: XML
is easier to edit than HTML with an editor like Emacs, because, like Lisp,
its structure is regular. HTML's structure allows some special cases that
make life more difficult for editor assistance and analysis.

General HTML allows some things that are non-XML, purportedly to make coding
(typing) it easier or quicker for humans. For example, you can use <p>
without a corresponding closing tag </p>. That is like allowing a Lisp-like
language to drop `)' in some situations, for "coding convenience". Such
"conveniences" are of course a pita when it comes to code that manipulates
code. In Emacs, we commonly use major-mode bindings to analyze, navigate,
and manipulate code - automatically provide closing tags and such.

Emacs doesn't need the HTML departures from XML. They are not even needed
generally, except for legacy reasons. They are considered by many to be bad
features introduced for bad reasons. HTML 4.01 (which I think is the latest
standard) cleans up some of what existed before, but it still allows some of
the non-XML stuff, for backward compatibility.

XHTML is what we should target, if we do this Info conversion/replacement.
These reference provides good background, especially the first:

FAQ about HTML and XHTML: http://www.w3.org/MarkUp/2004/xhtml-faq
XHTML:  http://www.w3.org/MarkUp/
HTML 4.01: http://www.w3.org/TR/html4/

XHMTML is 100% XML *and* 100% HTML. It is essentially the HTML 4.01
standard, but made consistent - that is, made to also be XML (every <p>
needs a corresponding </p> etc.). Nothing important is lost by using XHTML
instead of the full HTML 4.01, and a lot is gained.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Richard Stallman]

    General HTML allows some things that are non-XML, purportedly to make coding
    (typing) it easier or quicker for humans. For example, you can use <p>
    without a corresponding closing tag </p>. That is like allowing a Lisp-like
    language to drop `)' in some situations, for "coding convenience".

We could make Texinfo always generate the closing construct when it
generates HTML.

RE: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Drew Adams]

>     General HTML allows some things that are non-XML, purportedly
>     to make coding (typing) it easier or quicker for humans. For
>     example, you can use <p> without a corresponding closing tag
>     </p>. That is like allowing a Lisp-like
>     language to drop `)' in some situations, for "coding convenience".
>
> We could make Texinfo always generate the closing construct when it
> generates HTML.

Yes. More generally, the idea would be to make sure that it generates XHTML
(a version of HTML that is also XML).

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
> I do not know how XML differs from HTML.  Perhaps something makes XML
> harder to edit than HTML; I have no opinion about that.

XML is typically more verbose and picky than html.  It's intended to be
easier to parse (for machines), but a side effect is that it's somewhat
harder/more-annoying to read and write for humans.

E.g. they got rid of the "implicit end tag" stuff from SGML, which is
what allows you to omit the paragraph end-tag (</p>) in html text.
[I think even the paragraph _start_ tag is a small but pervasive
annoyance...]

Existing xml tag-sets like docbook seem to tend towards extreme
verbosity, to the extent that e.g. docbook source text is pretty much
unreadable without something stripping the annotations.  Other tag-sets
may be better, but docbook seems more the norm than an exception.

-miles

-- 
`There are more things in heaven and earth, Horatio,
 Than are dreamt of in your philosophy.'

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Karl Berry]

Regarding allowing arbitary characters in node names.

It seems to me that neither \: nor SGML entities are a solution.  Either
one involves making normal characters special (\ or &#;), which will
break lots of existing documents.  There are Texinfo documents which
have the literal text "&123;" precisely to document whatever &123; is.

Perhaps I'm missing something, but I don't see how having some simple
HTML-ish output would solve the problem either.  Even if we design and
implement such a thing, Info output will still need to continue to exist
for plenty of years to come, and therefore source documents could still
not use : (or whatever) in node names.  (See also my last paragraph below.)

Using 0xA0 (or any other single byte value) for a quote is not a
solution either, in my mind.  It could have worked if it had been
designed that way from the beginning, but now there are documents with a
literal 0xA0 in the input.  We don't want to break them.

What I think has the best chance of working in the context of the
current Info format is to use the same construct for arbitrary
characters that we already invented for images:
^@^H[image src="somefile.png"^@^H] 
(the ASCII ^@ and ^H I'm writing in this email are actual NUL and BS
chars in real output.)

For instance, we could have
^@^H[char xxxx^@^H]
where xxxx are hex digits.  It would be interpreted according to
whatever encoding was declared for the document.

Existing viewers would obviously just display it literally, which is
ugly, but I don't think it would otherwise break anything, as making new
special characters would.  I can't be certain without trying it, but I
don't think existing viewers would bomb out if this sequence occurred in
a node name.

What happens on the Texinfo input side is another problem, but this
message is too long already.
    
    But that means there are no faces, no graphics, no non-ASCII
    characters, etc.  

Non-ASCII characters can be included literally, since there is a
provision for defining the character set.

Images can now be included with the construct above.  I believe this
works in Emacs 22, at least I hope so, since that's why it was invented.
A similar construct is used to mark indexes.

One more thought: someone going to the trouble of writing a whole new
viewer might as well use TexinfoML XML for its input, it seems to me (as
Juri wrote).  It exists today (makeinfo --xml) and has been used in a
couple of real projects (e.g., http://www.nongnu.org/texi2latex/).  It
essentially translates Texinfo source into XML syntax, doing a few
Texinfo-ish things like macro expansion and conditionals along the way.
It doesn't make any layout decisions, as Info format does (and must).

karl

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    It seems to me that neither \: nor SGML entities are a solution.  Either
    one involves making normal characters special (\ or &#;), which will
    break lots of existing documents.  There are Texinfo documents which
    have the literal text "&123;" precisely to document whatever &123; is.

Are there info files that have constructs like &123; in the menu item
names?  That (and maybe xrefs) is where quoting is needed.

    Perhaps I'm missing something, but I don't see how having some simple
    HTML-ish output would solve the problem either.  Even if we design and
    implement such a thing, Info output will still need to continue to exist
    for plenty of years to come, and therefore source documents could still
    not use : (or whatever) in node names.

Even if we avoid using colon in menu items for a few more years, until
we declare the old Info format obsolete, the plan can be a good one.
It could provide a lot of different benefits in addition to using
colons in menu names.

    For instance, we could have
    ^@^H[char xxxx^@^H]
    where xxxx are hex digits.

We can use that as the short-term solution for colons in menu names.
However, we should still consider moving to an HTML-based new Info
format, as a long-term plan to provide many new features.

    One more thought: someone going to the trouble of writing a whole new
    viewer might as well use TexinfoML XML for its input, it seems to me (as
    Juri wrote).

In principle, this might be just as good as using a subset of HTML.
However, in practice, using a subset of HTML would allow any browser
to display Info files.  Could TexinfoML XML do that?

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Juri Linkov]

>     One more thought: someone going to the trouble of writing a whole new
>     viewer might as well use TexinfoML XML for its input, it seems to me (as
>     Juri wrote).
>
> In principle, this might be just as good as using a subset of HTML.
> However, in practice, using a subset of HTML would allow any browser
> to display Info files.  Could TexinfoML XML do that?

`makeinfo --html' already generates output that any browser can display.
What is missing in HTML output are Info-specific semantical elements,
like references to next and previous nodes, menu items grouped to menus,
index items that can be easily extracted.

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

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Drew Adams]

> >     One more thought: someone going to the trouble of writing a
> >     whole new viewer might as well use TexinfoML XML for its
> >     input, it seems to me (as Juri wrote).
> >
> > In principle, this might be just as good as using a subset of HTML.
> > However, in practice, using a subset of HTML would allow any browser
> > to display Info files.  Could TexinfoML XML do that?
>
> `makeinfo --html' already generates output that any browser can display.
> What is missing in HTML output are Info-specific semantical elements,
> like references to next and previous nodes, menu items grouped to menus,
> index items that can be easily extracted.

I'm not suggesting this is the way to go, but I wrote a library, mkhtml.el,
that built upon htmlize.el, changing all Info links into HTML hyperlinks. I
still have the library, but it works only with an out-of-date version of
htmlize.el (which I'm not even sure I still have).

My point is that it is doable to 1) convert to HTML a la htmlize, and then
2) convert Info links (menus, xrefs, everything) to HTML links.

You make a more general point, however. Things such as index lookup via `i'
would have no HTML counterpart (or, rather, one might need to be developed).
ECMAscript? (ugh!)

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Richard Stallman]

    You make a more general point, however. Things such as index lookup via `i'
    would have no HTML counterpart

Why do you think so?  If the index is stored as HTML, searching it
can be implemented, just as it was implemented with Info format.

RE: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Drew Adams]

>     You make a more general point, however. Things such as index
>     lookup via `i' would have no HTML counterpart
>
> Why do you think so?  If the index is stored as HTML, searching it
> can be implemented, just as it was implemented with Info format.

Yes, sure it can. You can have search capabilities across a set of HTML
pages. However, that search is not HTML coding; it is something else
(perhaps embedded within HTML code). It could be Javascript, ECMAscript,
Java, php, or whatever. All I meant was that the cross-pages search would
not itself be just static HTML code. We agree: search can be _implemented_
for HTML pages.

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Richard Stallman]

    > Why do you think so?  If the index is stored as HTML, searching it
    > can be implemented, just as it was implemented with Info format.

    Yes, sure it can. You can have search capabilities across a set of HTML
    pages. However, that search is not HTML coding; it is something else
    (perhaps embedded within HTML code). It could be Javascript, ECMAscript,
    Java, php, or whatever. All I meant was that the cross-pages search would
    not itself be just static HTML code. We agree: search can be _implemented_
    for HTML pages.

Now I see what you mean.  You seem to be talking about making `i' work
in an unmodified browser.  I was talking about making it work in an
Info reader which was a variant of a browser.  That is much easier.

Your idea might be good too, as long as it doesn't make the HTML
too ugly.

RE: [drew.adams@oracle.com: RE: cannot find :enableinElispmanualindex]

[Drew Adams]

>     All I meant was that the cross-pages search would
>     not itself be just static HTML code. We agree: search can be
>    _implemented_ for HTML pages.
>
> Now I see what you mean.  You seem to be talking about making `i' work
> in an unmodified browser.  I was talking about making it work in an
> Info reader which was a variant of a browser.  That is much easier.
>
> Your idea might be good too, as long as it doesn't make the HTML
> too ugly.

Yes, there are at least two possibilities:

1. design and implement a replacement for Info that is based
   on (X)HTML

2. add ways for standard Web browsers to take advantage of
   features that Info has, beyond clicking links: index
   search and other cross-page searches, keyboard access
   to follow links (e.g. HTML `accesskey' attribute)

If some thought is given to #2 when thinking about #1, then #1 can perhaps
benefit from some of the same implementation.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Stefan Monnier]

> You make a more general point, however. Things such as index lookup via `i'
> would have no HTML counterpart (or, rather, one might need to be developed).
> ECMAscript? (ugh!)

HTML doesn't care about key-bindings, so it's not clear what you mean.
But HTML does include notions for special links to "the next page" or "the
index page".  It's rarely used if ever, and very few browsers support them
usefully (i.e. better than by just ignoring them), but still: HTML supports
it just fine, it's only browsers which don't.


        Stefan

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Drew Adams]

> > You make a more general point, however. Things such as index
> > lookup via `i' would have no HTML counterpart (or, rather,
> > one might need to be developed). ECMAscript? (ugh!)
>
> HTML doesn't care about key-bindings, so it's not clear what you mean.

That's just what I meant: HTML doesn't care about key bindings.

> But HTML does include notions for special links to "the next page" or "the
> index page".  It's rarely used if ever, and very few browsers support them
> usefully (i.e. better than by just ignoring them), but still:
> HTML supports it just fine, it's only browsers which don't.

That's no doubt a good point.

I did mention the "HTML `accesskey' attribute", which seems to be a way to
attach key bindings to particular elements (such as <a> links). I'm not sure
how far that would get us, or what browser support there is for it.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Stefan Monnier]

> I did mention the "HTML `accesskey' attribute", which seems to be a way to
> attach key bindings to particular elements (such as <a> links).  I'm not
> sure how far that would get us, or what browser support there is for it.

I don't think makeinfo should worry about keybindings either.  I.e. the HTML
support to specify what is "the index page" is all we need.  The info
browser will then just provide an `i' keybinding to make use of it, but
other browsers should be free to provide such a thing or not or differently.
I.e. the support provided by HTML seems sufficient for `i' and probably also
for full-text-search.


        Stefan

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Drew Adams]

> > I did mention the "HTML `accesskey' attribute", which seems to
> > be a way to attach key bindings to particular elements (such
> > as <a> links).  I'm not sure how far that would get us, or what
> > browser support there is for it.
>
> I don't think makeinfo should worry about keybindings either.
> I.e. the HTML support to specify what is "the index page" is
> all we need.  The info browser will then just provide an `i'
> keybinding to make use of it, but other browsers should be free
> to provide such a thing or not or differently.
> I.e. the support provided by HTML seems sufficient for `i' and
> probably also for full-text-search.

HTML without some indication of key bindings provides no particular support
for keybindings. If the standard Emacs bindings (`i', for instance) were
specified in the HTML code as `accesskey' attributes, then browsers would
still be able to ignore them or do whatever else they like, but at least a
browser that supports `accesskey' would, without doing anything special,
provide user support for the standard Emacs Info bindings.

I don't know anything about `accesskey' besides what I read during a few
minutes of googling. In particular, I don't know which browsers might
support it. But it seems to be a standard HTML way to indicate key-binding
suggestions to a browser - in particular for links.

In our case, putting <A href="an-entry#index.html" accesskey="i"> or <A
href="an-xref#foo.html" accesskey="f"> or <A href="an-uplink#foo.html
accesskey="u"> would presumably be a simple way to indicate to an
accesskey-enabled browser to support `i', `f', and `u' for those three
links, respectively.

If the new Info browser itself was accesskey-enabled, then we would be
killing two birds with one stone. Anyway, it's just an idea that might be
worth exploring.

RE: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Drew Adams]

I wrote:
> HTML without some indication of key bindings provides no
> particular support
> for keybindings. If the standard Emacs bindings (`i', for instance) were
> specified in the HTML code as `accesskey' attributes, then browsers would
> still be able to ignore them or do whatever else they like, but at least a
> browser that supports `accesskey' would, without doing anything special,
> provide user support for the standard Emacs Info bindings.
>
> I don't know anything about `accesskey' besides what I read during a few
> minutes of googling. In particular, I don't know which browsers might
> support it. But it seems to be a standard HTML way to indicate key-binding
> suggestions to a browser - in particular for links.
>
> In our case, putting <A href="an-entry#index.html" accesskey="i"> or <A
> href="an-xref#foo.html" accesskey="f"> or <A href="an-uplink#foo.html
> accesskey="u"> would presumably be a simple way to indicate to an
> accesskey-enabled browser to support `i', `f', and `u' for those three
> links, respectively.
>
> If the new Info browser itself was accesskey-enabled, then we would be
> killing two birds with one stone. Anyway, it's just an idea that might be
> worth exploring.

I realized, walking to work after writing that, that some of what I wrote
above is nonsense. Presumably, `accesskey' can only work when the key is
unique for the HTML page (in our case, Info node). So (IIUC), `accesskey'
could work for `u', `n', `p', `1', `2', etc. (menu items), but not for `i'
or `f' (`i' is not even a link!).

I wasn't thinking of `accesskey' for `i' originally anyway, but I got
carried away above. In my original mention of `accesskey', I separated it
from treatment of `i' and `s'. This is what I suggested:

> there are at least two possibilities:
>
> 1. design and implement a replacement for Info that is based
>    on (X)HTML
>
> 2. add ways for standard Web browsers to take advantage of
>    features that Info has, beyond clicking links: index
>    search and other cross-page searches, keyboard access
>    to follow links (e.g. HTML `accesskey' attribute)
>
> If some thought is given to #2 when thinking about #1, then #1 can perhaps
> benefit from some of the same implementation.

Sorry for muddying the waters.

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Juri Linkov]

>> I don't know anything about `accesskey' besides what I read during a few
>> minutes of googling. In particular, I don't know which browsers might
>> support it. But it seems to be a standard HTML way to indicate key-binding
>> suggestions to a browser - in particular for links.

Using accesskey differs significantly between browsers.  In early versions
of Mozilla HTML page accesskeys were bound to the Alt modifier, thus
causing conflicts with browser's standard keys, such as Alt-F activating
the File menu.  In Firefox 2.0 this problem is mitigated by binding
accesskeys to the Alt-Shift modifier.  In the Konqueror pressing and releasing
the Ctrl key displays tooltips with the key name on the every HTML element
where the accesskey is assigned.  After pressing one of the displayed keys
it activates that element.

> Presumably, `accesskey' can only work when the key is
> unique for the HTML page (in our case, Info node). So (IIUC), `accesskey'
> could work for `u', `n', `p', `1', `2', etc. (menu items), but not for `i'
> or `f' (`i' is not even a link!).

`i' can be a link.  Just as in Emacs typing `i RET' visits the first
index node, the HTML standard supports the link type `index' for specifying
an index URL like

  <link rel="index" href="Command_Index.html" title="Index of this manual" />

Here is a list of other useful link types:

  <link rel="top" href="top.html"/>
  <link rel="home" href="home.html" />
  <link rel="prev" href="prev.html" />
  <link rel="next" href="next.html" />
  <link rel="up" href="../up.html" />
  <link rel="last" href="last.html" />
  <link rel="first" href="first.html" />
  <link rel="help" href="help.html" title="Help" />
  <link rel="author" href="author.html" title="Author" />
  <link rel="copyright" href="copyright.html" title="Copyright" />
  <link rel="search" href="search.html" title="Search this manual" />
  <link rel="contents" href="contents.html" title="Contents of this manual" />
  <link rel="glossary" href="glossary.html" title="Glossary of this manual" />
  <link rel="chapter" href="chapter1.html" title="Chapter 1" />
  <link rel="chapter" href="chapter11.html" title="Chapter 1.1" />
  <link rel="chapter" href="chapter12.html" title="Chapter 1.2" />
  <link rel="chapter" href="chapter2.html" title="Chapter 2" />
  <link rel="section" href="section1.html" title="Section 1" />
  <link rel="section" href="section11.html" title="Section 1.1" />
  <link rel="section" href="section12.html" title="Section 1.2" />
  <link rel="section" href="section2.html" title="Section 2" />
  <link rel="subsection" href="subsection1.html" title="Subsection 1" />
  <link rel="subsection" href="subsection11.html" title="Subsection 1.1" />
  <link rel="subsection" href="subsection12.html" title="Subsection 1.2" />
  <link rel="subsection" href="subsection2.html" title="Subsection 2" />
  <link rel="appendix" href="appendix1.html" title="Appendix 1" />

Support for these link types also differs from browser to browser.

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

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Stefan Monnier]

> Here is a list of other useful link types:

>   <link rel="top" href="top.html"/>
>   <link rel="home" href="home.html" />
>   <link rel="prev" href="prev.html" />
>   <link rel="next" href="next.html" />
>   <link rel="up" href="../up.html" />
>   <link rel="last" href="last.html" />
>   <link rel="first" href="first.html" />
>   <link rel="help" href="help.html" title="Help" />
>   <link rel="author" href="author.html" title="Author" />
>   <link rel="copyright" href="copyright.html" title="Copyright" />
>   <link rel="search" href="search.html" title="Search this manual" />
>   <link rel="contents" href="contents.html" title="Contents of this manual" />
>   <link rel="glossary" href="glossary.html" title="Glossary of this manual" />
>   <link rel="chapter" href="chapter1.html" title="Chapter 1" />
>   <link rel="chapter" href="chapter11.html" title="Chapter 1.1" />
>   <link rel="chapter" href="chapter12.html" title="Chapter 1.2" />
>   <link rel="chapter" href="chapter2.html" title="Chapter 2" />
>   <link rel="section" href="section1.html" title="Section 1" />
>   <link rel="section" href="section11.html" title="Section 1.1" />
>   <link rel="section" href="section12.html" title="Section 1.2" />
>   <link rel="section" href="section2.html" title="Section 2" />
>   <link rel="subsection" href="subsection1.html" title="Subsection 1" />
>   <link rel="subsection" href="subsection11.html" title="Subsection 1.1" />
>   <link rel="subsection" href="subsection12.html" title="Subsection 1.2" />
>   <link rel="subsection" href="subsection2.html" title="Subsection 2" />
>   <link rel="appendix" href="appendix1.html" title="Appendix 1" />

Yes, that's what I was talking about.

> Support for these link types also differs from browser to browser.

As far as I know, it's sadly about as good as inexistent.  I'd be happy to
learn otherwise.
In any case I think that makeinfo's (X)HTML should definitely make use of
them (that doesn't mean it doesn't: I just haven't bothered to check).


        Stefan

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Juri Linkov]

>> Support for these link types also differs from browser to browser.
>
> As far as I know, it's sadly about as good as inexistent.  I'd be happy to
> learn otherwise.

Fortunately, their support is a little more than inexistent.  For example,
Links displays rel-links as a group of links at the top of the HTML page like:

   Link: top
   Link: home
   Link: prev
   Link: next
   Link: up

There are a few extensions for Firefox (some of them are outdated, some not)
that put rel-links to menus on the special toolbar.

> In any case I think that makeinfo's (X)HTML should definitely make use of
> them (that doesn't mean it doesn't: I just haven't bothered to check).

It does as I can see.  Makeinfo adds a piece like below to every separate
HTML page:

<link title="Top" rel="start" href="index.html#Top">
<link rel="prev" href="Creating-and-Installing-Info-Files.html#Creating-and-Installing-Info-Files" title="Creating and Installing Info Files">
<link rel="next" href="Command-List.html#Command-List" title="Command List">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">

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

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Stefan Monnier]

> It does as I can see.  Makeinfo adds a piece like below to every separate
> HTML page:

> <link title="Top" rel="start" href="index.html#Top">

I see it uses "start" whereas you used "top" in your previous email.

> <link rel="prev" href="Creating-and-Installing-Info-Files.html#Creating-and-Installing-Info-Files" title="Creating and Installing Info Files">
> <link rel="next" href="Command-List.html#Command-List" title="Command List">
> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">

Good.  So it only lacks the `index' links.


        Stefan

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Juri Linkov]

>> It does as I can see.  Makeinfo adds a piece like below to every separate
>> HTML page:
>
>> <link title="Top" rel="start" href="index.html#Top">
>
> I see it uses "start" whereas you used "top" in your previous email.

There is some confusion with "start" and "top".  HTML3.2 defines "top" as

    rel="top"
        The link references the top of a hierarchy, e.g. the first
        or cover page in a collection. 

whereas HTML4.01 replaces "top" with "start" and defines it as

    rel="start"
        Refers to the first document in a collection of documents.
        This link type tells search engines which document is considered
        by the author to be the starting point of the collection.

Makeinfo generates rel="start".  I think this is correct since this is
defined by the latest HTML specification.  However, as the title of the
"start" link it uses the text "Top".  I suppose that's to maintain
compatibility with Texinfo terminology where the first node is named "Top".

>> <link rel="prev" href="Creating-and-Installing-Info-Files.html#Creating-and-Installing-Info-Files" title="Creating and Installing Info Files">
>> <link rel="next" href="Command-List.html#Command-List" title="Command List">
>> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
>
> Good.  So it only lacks the `index' links.

Yes, but as I see it can refer to only one index node:

      INDEX
	 The INDEX relationship identifies an index.

	 When REL=INDEX, the target document is an index for the
	 current document, or for the collection of documents of which
	 the current document is a member.

	 When REV=INDEX, the current document is an index. Additional
	 REL/REV values may be used to further specify the relationship
	 between the two ends of the link.

	 If the hypertext link is specified with REL in a LINK element,
	 an HTML user agent may present an icon in a tool bar.  An index
	 may be presented as an HTML document which is organized and
	 presented in a style reminiscent of a paper-based index.  An
	 index may also be presented as a form-based query into a full-
	 text search database.

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

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Stefan Monnier]

>> Good.  So it only lacks the `index' links.
> Yes, but as I see it can refer to only one index node:

So makeinfo would have to generate a special index page which combines all
the indices of the manual.


        Stefan

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Karl Berry]

    So makeinfo would have to generate a special index page which combines all
    the indices of the manual.

Sounds horribly ugly!  What is the gain?

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Stefan Monnier]

>     So makeinfo would have to generate a special index page which combines all
>     the indices of the manual.

> Sounds horribly ugly!  What is the gain?

The gain is that an HTML browser that provides a binding (say on the `i'
key) that allows looking up a term in the index, can then be used with full
functionality to browse Texinfo manuals.


        Stefan

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Karl Berry]

    The gain is that an HTML browser that provides a binding (say on the
    `i' key) that allows looking up a term in the index, 
    can then be used with full functionality to browse Texinfo manuals.

I would hope that we do not need to create an ersatz node to provide
this functionality.  Doing that seems very wrong to me.  Can't the
implementation of such a "binding" be smart enough to look in the proper
places?  What language are you talking about, anyway?

Anyway, this all seems very theoretical.

karl

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Stefan Monnier]

>     The gain is that an HTML browser that provides a binding (say on the
>     `i' key) that allows looking up a term in the index, 
>     can then be used with full functionality to browse Texinfo manuals.

> I would hope that we do not need to create an ersatz node to provide
> this functionality.  Doing that seems very wrong to me.  Can't the
> implementation of such a "binding" be smart enough to look in the proper
> places?  What language are you talking about, anyway?

An HTML browser can't/shouldn't know that it's looking at a Texinfo manual
and then magically know that to lookup in an index it needs to go to the
"top" node and then look for links with "index" in their name etc...

OTOH, it can/should provide a way to make use of the <link rel="index" ...>
feature defined in the HTML spec.  So makeinfo should make use of that
feature as well.


        Stefan

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Karl Berry]

Sigh.

Is there any browser which will actually do something sensible with
rel="index" now?

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[csant]

On Fri, 08 Jun 2007 04:28:51 +0200, Karl Berry <karl@freefriends.org>  
wrote:

> Is there any browser which will actually do something sensible with
> rel="index" now?

Yes, some browsers have the functionality to visit that URL (or any other  
one specified in <link/>s) with a command, and/or to display a menu with  
the authored <link/>s - though I am not sure whether any browser comes  
with a default binding for that...
/c

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Stefan Monnier]

>> Is there any browser which will actually do something sensible with
>> rel="index" now?

> Yes, some browsers have the functionality to visit that URL (or any other
> one specified in <link/>s) with a command, and/or to display a menu with
> the authored <link/>s - though I am not sure whether any browser comes  with
> a default binding for that...

I'm not sure it counts as "something sensible".  What should happen is more
like what happens with Info's `i' keybinding which doesn't let the user just
jump to the index, but searches it for him.


        Stefan

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Stefan Monnier]

> Is there any browser which will actually do something sensible with
> rel="index" now?

Not that I know.


        Stefan

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Juri Linkov]

> Is there any browser which will actually do something sensible with
> rel="index" now?

The only sensible use of rel="index" I know is putting a link pointing to
the index page on the toolbar of rel-links.  Using this toolbar the user
can visit the first HTML index page which can have next/prev links to
other index pages available for navigation.

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

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Karl Berry]

    Good.  So it only lacks the `index' links.

Please email suggestions for makeinfo's html output to bug-texinfo, ok?
(Patches are even better. :)

I am not sure what exactly is being proposed, since I did not see all
the mail that led up to this.

Thanks,
k

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Richard Stallman]

    `i' can be a link.  Just as in Emacs typing `i RET' visits the first
    index node,

The main purpose of `i' is to _search_ the index.
If it can't do that, I am not sure that "handling" it in
a different way is useful.

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Juri Linkov]

>     `i' can be a link.  Just as in Emacs typing `i RET' visits the first
>     index node,
>
> The main purpose of `i' is to _search_ the index.
> If it can't do that, I am not sure that "handling" it in
> a different way is useful.

In the Emacs Info browser (when it will read HTML files) it is possible
to make `i' to search the index in HTML files generated by makeinfo.

In standard HTML browsers this is problematic since there are no standard
ways to do this.  Usually, this kind of functionality is implemented by
server-side scripting.  I think we should not do this since reading
local Info manuals should be possible without a Web server.

But even a link to the Index HTML page is useful in standard HTML browsers,
since users can visit it and search the Index page with HTML page text search
commands (its analogy in Emacs is `i RET C-s text C-s C-s RET RET'),
though this is less convenient than `i text RET , , ,'.

BTW, I have an idea to improve the `i' commands in the Emacs Info browser.
Its main drawback currently is that it forces the user to cycle through
many Info nodes before arriving to the desired one.  We could create a new
command `Info-index-occur' that will ask the user for the index substring
and display a list of references from Index nodes that contain the given
substring.  Then the user can visit a selected index item in such subindex
node.

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

Re: [drew.adams@oracle.com: RE: cannot find :enable inElispmanualindex]

[Stefan Monnier]

> In standard HTML browsers this is problematic since there are no standard
> ways to do this.

I don't see why a plain HTML browser wouldn't want to do the "search the
index page for the appropriate link".  What's problematic about it?
Obviously, it'd need a bit of heuristic since the browser can't be sure
what format the index page uses, but it shouldn't be a problem in real life.


        Stefan

propose adding Icicles to Emacs

[Drew Adams]

Juri's Info suggestion provides a good opportunity to propose adding Icicles
to Emacs:

> BTW, I have an idea to improve the `i' commands in the
> Emacs Info browser. Its main drawback currently is that it
> forces the user to cycle through many Info nodes before
> arriving to the desired one.  We could create a new
> command `Info-index-occur' that will ask the user for the
> index substring and display a list of references from Index
> nodes that contain the given substring.  Then the user can
> visit a selected index item in such subindex node.

With Icicles, when you use `i' in Info:

* You can complete your input using an index-entry
  prefix (standard Emacs) or a regexp (e.g. substring).
  Completion candidates are updated to reflect your input.

* You can hit `M-*' and then type different input, to also
  match that (e.g. multiple regexps). Do this any number
  of times.

* You can use a key or mouse-click to visit individual matches
  - without exiting `i' completion.

* You can use keys to cycle among matches, in either direction.
  You need not cycle among all intermediate matches.

* You can visit any number of nodes that match, without leaving
  your (single) `i' invocation.

* Because you browse (cycle etc.) without leaving completion,
  your input continues to filter candidates - regexp or prefix.
  Change your input on the fly to change the match set for
  browsing.

* Hit `RET' or `C-g' to stop browsing (i.e., end `i'
  invocation) at a match you finally choose.

The same approach works also for `g' in Info. These features for `i' and `g'
come essentially for free - a couple lines of code implements them for
Icicles.


I've now signed papers and sent them in, so adding Icicles to Emacs could be
considered.

Icicles extends `completing-read', `read-file-name' etc. in various ways. It
provides users with yet another way to complete minibuffer input (like ido,
ibuffer,...). I propose adding it to Emacs in a way similar to how ido and
ibuffer are offered: for optional use. Icicles is encapsulated in a minor
mode, and turning the mode off gives you back vanilla Emacs. On the other
hand, we might want to also add some of its ideas directly to vanilla Emacs,
separately.

Icicles has many different features, including the following
(in addition to what was mentioned above about Info `i'):

* Its features are available for all kinds of completion:
  file, buffer, command,...even keys. The user interface is
  the same for all.

* Multi-commands: Define a command that acts on one foobar,
  and be able to use it also on multiple foobars in a single
  invocation. Visit multiple index entries with one `i' (see
  above). Use `C-h f' to browse the *Help* for any number of
  functions whose names match your input (like apropos on the
  fly, with full doc strings). Open selected files that match
  your input, with a single `C-x C-f'.

* You use completion with multi-commands the same way you use
  it to choose a single completion candidate. Instead of `RET'
  or `mouse-2' or (to cycle) `down', you use `C-RET' or
  `C-mouse-2' or `C-down' to act on a candidate without exiting
  completion. The standard keys work the standard way, so there
  is no change in behavior if users don't explicitly use the
  multi-command keys. (Advanced features require you to invoke
  them explicitly, so beginners don't fall down a black hole.)

* Match negatively: Type input to match, then complement that
  set of matches. Repeat complementing with different inputs,
  to remove whole subsets of uninteresting candidates from
  consideration (and from further matching). Or use a key or
  the mouse to remove candidates individually.

* Use other set operations on the set of matching candidates,
  including acting on all of them (`C-!'). That is, apply the
  current command to each matching candidate. E.g.,
  delete/open/... all matching files (or buffers or...).

* Use multi-commands as multiple-choice menus: choose any
  number of matching candidates in *Completions*. Choose (act
  on) the same candidate multiple times, if appropriate.

* Sort the current set of candidates in various ways, on the
  fly. This affects cycling order. Different commands can
  make different sort orders available.

* Use multiple regexps to search text. This is an incremental
  search, but you need not go through each match in sequence:
  As for index entries (see above), you can skip around
  (direct access), cycle among hits, etc. Search for regexp
  subgroups within the regexp context. Combine predicates with
  syntactic search, on the fly. Use all of the completion
  features, such as complementing to remove whole subsets of
  uninteresting search hits.

* Same search mechanism for compilation hits, imenu
  definitions, occur,... Search across multiple buffers,
  files, or saved regions. Search only text with given text
  properties or overlay properties, such as faces.

* Replace text while searching: invoke replacement on the fly.
  No separate query-replace, and no need to cycle through each
  replacement candidate in only one order. Replace text during
  character-property search too. Use any replacement string
  accepted by 'query-replace-regexp'.

* Persistently save and reuse matching sets of candidates.

* Complete key sequences too - e.g. `C-x S-TAB' completes to
  the keys in `C-x' prefix map. Same completion possibilities
  as usual (multiple patterns, regexps, cycling,...).

* For Emacs-Lisp programmers, just use `completing-read' or
  `read-file-name' - users get most of the Icicles features
  with no programming. Or define commands as multi-commands:
  it's as easy to define a command to act on one or more
  foobars as it is to define a command that only acts on one.

There is a lot more. The doc is here:
http://www.emacswiki.org/cgi-bin/wiki/Icicles.
An overview is here:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Nutshell_View.

The library is big: several files. Much of that is doc. There
are many user options: being very general, you can use it in
different ways, and you can customize it accordingly.

Please consider adding Icicles to Emacs.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Icicles extends `completing-read', `read-file-name' etc. in various ways. It
    provides users with yet another way to complete minibuffer input (like ido,
    ibuffer,...). I propose adding it to Emacs in a way similar to how ido and
    ibuffer are offered: for optional use.

Does Icicles provide all its features in a modular way, by extending
the completion mechanism?

    * Multi-commands: Define a command that acts on one foobar,
      and be able to use it also on multiple foobars in a single
      invocation.

How is that implemented?

Does Icicles do advice?

RE: propose adding Icicles to Emacs

[Drew Adams]

>     Icicles extends `completing-read', `read-file-name' etc. in
>     various ways. It provides users with yet another way to
>     complete minibuffer input (like ido, ibuffer,...). I propose
>     adding it to Emacs in a way similar to how ido and
>     ibuffer are offered: for optional use.
>
> Does Icicles provide all its features in a modular way, by extending
> the completion mechanism?

It uses a minor mode, `icicle-mode'. It redefines some primitives such as
`completing-read' for use when the mode is active, and it restores them to
the original definitions when the mode is turned off.

If integrated with Emacs, this could be done by changing `completing-read'
etc. to act differently when `icicle-mode' is on, unless that is a no-no.

Icicles also makes additional minibuffer bindings, and, depending on the
value of a user option, it can replace some top-level commands with Icicles
versions (e.g. `find-file' with `icicle-find-file'). These actions are
reversed when the minor mode is exited, so you get back the vanilla Emacs
key bindings and commands.

Icicles does not change global bindings, with this exception: `S-TAB' is
bound in several keymaps to provide key completion. Any existing binding of
`S-TAB' is never replaced, however.

>     * Multi-commands: Define a command that acts on one foobar,
>       and be able to use it also on multiple foobars in a single
>       invocation.
>
> How is that implemented?

A minibuffer key binding, `C-RET' (or `C-mouse-2' in
`completion-list-mode-map'), calls a command that acts on the current
completion candidate, where "current" is determined by cycling or matching.

If you don't use `C-RET', and you just pick a single candidate with `RET' or
`mouse-2', then only that candidate is acted on, and completion exits. So,
you define a command that acts on a single candidate, and Icicles lets you
also use that command to act on multiple candidates (or on the same
candidate multiple times) during a single completion invocation.

A multi-command binds the action function to `C-RET' in the minibuffer to
perform the appropriate action on the current candidate (e.g. during
cycling).

You can use macro `icicle-define-command' to do that for you, to define a
multi-command that uses the same action function to (1) act on the current
candidate during completion (without exiting) and (2) act on the final
candidate chosen with RET. In general, the action on the current candidate
during completion need not be the same action that the command performs on
the candidate finally chosen, but in practice it is often the same.

Example - here is the definition of `icicle-find-tag', which is a
multi-command version of `find-tag'. It uses `find-tag' as the action
function, so `find-tag' is applied to the final candidate you choose with
`RET' and also to other candidates if you use `C-RET' before ending
completion with `RET' or `C-g'.

1 (icicle-define-command icicle-find-tag "Find tag..."
2   find-tag "Find tag: " 'tags-complete-tag nil nil nil nil
3   (funcall (or find-tag-default-function
4                (get major-mode 'find-tag-default-function)
5                'find-tag-default))
6   nil
7   ((completion-ignore-case
8     (if (and (boundp 'tags-case-fold-search)
9              (memq tags-case-fold-search '(t nil)))
10        tags-case-fold-search
11      case-fold-search)))
12  (require 'etags))

line argument
---- --------
1    name of the new command,
     doc string (here, it is the same as `find-tag')
2-6  arguments to completing-read - nothing different here
7-11 any extra bindings needed - `completion-ignore-case' here
12   any initial code executed after binding, before completing
     - here, we just want to be sure `etags' is loaded

The doc string you supply, which is the same here as that for `find-tag', is
supplemented by the macro to inform users that this is a multi-command and
they can use `C-RET' etc. Here is the resulting doc string for
`icicle-find-tag':

 Find tag (in current tags table) whose name...
 [same as `find-tag' doc]

 Read input, then call `find-tag' to act on it.

 Input-candidate completion and cycling are available.  While cycling,
 these keys with prefix `C-' act on the current candidate:

 `C-mouse-2', `C-RET' - Act on current completion candidate only
 `C-down'  - Act, then move to next prefix-completion candidate
 `C-up'    - Act, then move to previous prefix-completion candidate
 `C-next'  - Act, then move to next apropos-completion candidate
 `C-prior' - Act, then move to previous apropos-completion candidate
 `C-!'     - Act on *all* candidates, successively (careful!)

 With prefix `C-M-' instead of `C-', the same keys (`C-M-mouse-2',
 `C-M-RET', `C-M-down', and so on) provide help about the current
 candidate.

 Use `mouse-2', `RET', or `S-RET' to finally choose a candidate,
 or `C-g' to quit.

 This is an Icicles command - see `icicle-mode'.

In general, defining a multi-command is no more difficult than defining an
ordinary command that performs completion: command name, doc string, args to
completing-read, maybe some bindings, and the (same) action code.

Here is the definition of `icicle-bookmark':

(icicle-define-command icicle-bookmark
  "Jump to a bookmark.
You can use `S-delete' on any candidate bookmark to delete it instead."
  bookmark-jump "Bookmark: " (mapcar #'list (bookmark-all-names))
  nil t nil 'bookmark-history
  (or (and (boundp 'bookmark-current-bookmark)
           bookmark-current-bookmark)
      (bookmark-buffer-name))
  nil
  ((icicle-delete-candidate-object 'bookmark-delete)))

The doc string and extra binding here illustrate another feature. Not only
can you act on multiple candidates with the same action function (here,
`bookmark-jump'), but, if defined for a given multi-command (as here), you
can also act on multiple candidates with an appropriate deletion function
(here, `bookmark-delete'), which is invoked using `S-delete'.

Similarly, while using `C-x C-f' (`icicle-find-file), you can use `S-delete'
on selected candidate files to delete them. (There is a similar macro,
`icicle-define-file-command', for multi-commands that use `read-file-name'
instead of `completing-read'.)

You don't need to use a macro to define a multi-command. It is enough to
bind `icicle-candidate-action-fn' to the action function you want, in your
command that calls `completing-read'. Here, for example, is the definition
of `icicle-Info-index', which I referred to at the start of this thread.

(defun icicle-Info-index ()
  "Like `Info-index', but you can use `C-RET', `C-up' etc."
  (interactive)
  (let ((info-buf (current-buffer))
        (info-window (selected-window))
        (icicle-candidate-action-fn 'icicle-Info-index-action))
    (call-interactively 'Info-index)))

(defun icicle-Info-index-action (topic)
  "Completion action function for `icicle-Info-index'."
  (let ((minibuf-win (selected-window)))
    (set-buffer info-buf)
    (select-window info-window)
    (Info-index topic)
    (select-window minibuf-win)))

It is the predefined command `Info-index' that calls `completing-read'. All
this code does is bind the action function for `C-RET' and ensure that the
right window and buffer are used for that action.

There can also be an alternative action function, in addition to the action
function and the (optional) deletion function. You invoke the alternative
action on selected candidates by using `C-S-RET' instead of `C-RET'
(likewise, `C-S-mouse-2', `C-S-down',...). For example, for `icicle-search',
the action function takes you to the current search hit (via `C-RET' etc.).
The alternative action function performs text replacement on that search hit
(via `C-S-RET').

Keep in mind too that if you just want the other Icicles features (regexp
matching, cycling etc.) and you don't care about having a multi-command,
then you don't need to do anything special when you define a command that
uses completion - the Icicles redefinitions of `completing-read' and
`read-file-name' take care of everything.

> Does Icicles do advice?

Icicles does not use advice. Well, there is one tiny exception, which could
be replaced:

(defadvice next-history-element
  (after icicle-select-minibuffer-contents activate)
  "Select minibuffer contents and leave point at its beginning."
  (when (and icicle-mode
             (memq icicle-init-value-flag
                   '(preselect-start preselect-end)))
    (icicle-select-minibuffer-contents)
    (setq deactivate-mark nil)))

I don't like to use advice (I find it makes debugging harder), but in this
case I did.

If Icicles were integrated with Emacs, either `next-history-element' itself
could be patched to be Icicles-aware or, if that is a no-no, Icicles could
redefine `next-history-element' for `icicle-mode' use only. All this code
does, BTW, is preselect part of the current candidate in the minibuffer, for
easy manipulation or deletion. This preselection is optional.

I'll be glad to answer more questions on the list, but this is all also
explained in the Icicles doc, which is available as HTML on Emacs Wiki or as
plain text in the library files themselves.

Re: propose adding Icicles to Emacs

[Sean O'Rourke]

"Drew Adams" <drew.adams@oracle.com> writes:
> It uses a minor mode, `icicle-mode'. It redefines some primitives such as
> `completing-read' for use when the mode is active, and it restores them to
> the original definitions when the mode is turned off.

Word to the wise: it doesn't *quite* put things back the way they
were, so don't enable it in your long-running session.  I haven't
taken the time to figure out the reason, but after turning
icicles on and off again, partial filename completion was
disabled, and 'z' in a Gnus groups buffer kills the frame.

/s

RE: propose adding Icicles to Emacs

[Drew Adams]

> > It uses a minor mode, `icicle-mode'. It redefines some
> > primitives such as `completing-read' for use when the
> > mode is active, and it restores them to
> > the original definitions when the mode is turned off.
>
> Word to the wise: it doesn't *quite* put things back the way they
> were, so don't enable it in your long-running session.  I haven't
> taken the time to figure out the reason, but after turning
> icicles on and off again, partial filename completion was
> disabled, and 'z' in a Gnus groups buffer kills the frame.

No one has ever reported such bugs. Please report problems you think are
related to Icicles, providing enough detail to reproduce them.

If you run a long Emacs session, and then you cannot say what you did, what
happened, or what caused some problem you encountered, that does not
necessarily indicate an Icicles bug. What makes you think that Icicles is
the culprit?

FWIW:

> partial filename completion was disabled

* Icicles does not use or change partial completion.
  It does not enable or disable it, even temporarily.

> 'z' in a Gnus groups buffer kills the frame

* Icicles does not in any way bind the `z' key, in any
  keymap. It does not use or affect anything involved
  with Gnus. Icicles has no code that deletes frames.

* In Icicle mode (only), if you choose (user option) to
  use `icicle-kill-buffer' for `C-x k', and if you also
  choose to use my library `misc-cmds.el', then `C-x k'
  will also delete the window (but not the frame) when
  it kills a buffer. You indicated on Emacs Wiki that
  you did choose to use `misc-cmds.el'.

* If you also choose to use my library `frame-cmds.el',
  then a one-window frame will also be deleted when the
  window is deleted. Perhaps you chose that too?

  Icicles alone will not delete a frame, and even with the
  other libraries it will not delete a frame unless you
  are in Icicle mode and you choose to bind `C-x k' to
  `icicle-kill-buffer' in that mode. I did not propose to
  add the other libraries to Emacs. If Icicles were added
  to Emacs, then I would of course remove any conditional
  code that takes advantage of my other libraries.

When you exit Icicle mode, there are no hooks involving Icicles, and there
are no key bindings involving Icicles. It leaves nothing behind.

I suspect that your problems have nothing to do with Icicles, but please
demonstrate the contrary if you can, so that any bugs can be fixed.

Without reporting any specific bug, please don't propagate alarmist
admonitions such as "don't enable it in your long-running session."  I and
others use Icicles every day in very long sessions, and I've never heard of
any such problems. That's not proof that there are no bugs, but your
statement is no indication that you encountered an Icicles bug, and it does
not merit a Chicken Little cry of alarm.

Others are welcome to try Icicles out and see for themselves whether turning
Icicle mode on and off causes any problems.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    If integrated with Emacs, this could be done by changing `completing-read'
    etc. to act differently when `icicle-mode' is on, unless that is a no-no.

It is not out of the question to do this.  However, it would be nicer
to find a cleaner way.  Can you do most of these changes through key
bindings?  Which changes are left, that can't be done that way (or not
cleanly)?  Can we find non-ad-hoc ways of implementing them?

      it can replace some top-level commands with Icicles
    versions (e.g. `find-file' with `icicle-find-file').

Why does it do this?

    >     * Multi-commands: Define a command that acts on one foobar,
    >       and be able to use it also on multiple foobars in a single
    >       invocation.
    >
    > How is that implemented?

    A minibuffer key binding, `C-RET' (or `C-mouse-2' in
    `completion-list-mode-map'), calls a command that acts on the current
    completion candidate, where "current" is determined by cycling or matching.

How does it know what to call?  Is it the same command that invoked
the minibuffer?  Do you have to define a new function for this,
one for each command that uses the feature?

It sounds like an ugly mechanism, so if this feature is worth adding,
I would rather it be implemented differently.  The cleanest way I can
think of is to set a flag telling call-interactively to call the
function then loop around, keeping the same prefix argument.

This should work with ALL commands and avoid the need to define
separate multi-commands.

Once multi-commands are gone, does Icicles need to
redefine any commands?  Is it just a matter of changes
inside completing-read?

RE: propose adding Icicles to Emacs

[Drew Adams]

>     If integrated with Emacs, this could be done by changing
>     `completing-read' etc. to act differently when `icicle-mode'
>     is on, unless that is a no-no.
>
> It is not out of the question to do this.  However, it would be nicer
> to find a cleaner way.  Can you do most of these changes through key
> bindings?  Which changes are left, that can't be done that way (or not
> cleanly)?  Can we find non-ad-hoc ways of implementing them?

I'd propose adding Icicles first as an optional library, without trying to
integrate any of it deeply with Emacs. Later, we could look into a possible
tighter integration. We might even want later to move some of the behavior
to vanilla Emacs completion.

The `completing-read' code is here:
http://www.emacswiki.org/cgi-bin/wiki/icicles-fn.el. Perhaps others more
familiar with Emacs implementation can advise whether some of this
redefinition could or should be moved to the vanilla definition of
`completing-read' or what might be a "cleaner way" to do what is done now
this way. I would advise just leaving this code as is, at least for now.

>     it can replace some top-level commands with Icicles
>     versions (e.g. `find-file' with `icicle-find-file').
>

I should be clear that this is not about redefining commands; it is about
remapping their bindings: the bindings for `find-file' are mapped to
`icicle-find-file'.

> Why does it do this?

Because those replacements are enhanced versions. They are typically
multi-commands that 1) keep the same behavior as the original, as long as
you don't use any special Icicles minibuffer bindings, but also 2) let you
take advantage of those minibuffer bindings (e.g. `C-RET') to get the
multi-command behavior.

With the replacement, for instance, you can open any number of files, using
completion, with one invocation of `C-x C-f', and you can optionally delete
selected matching files on the fly (with `S-delete'). You can of course
change your minibuffer input during that one invocation, to match different
file names. (`M-k' clears the minibuffer.)

Again, this binding replacement is, in any case, optional for a user (option
`icicle-bind-top-level-commands-flag'), and it is only for
`icicle-mode-map'.

>     >     * Multi-commands: Define a command that acts on one foobar,
>     >       and be able to use it also on multiple foobars in a single
>     >       invocation.
>     >
>     > How is that implemented?
>
>     A minibuffer key binding, `C-RET' (or `C-mouse-2' in
>     `completion-list-mode-map'), calls a command that acts on the
>     current completion candidate, where "current" is determined by
>     cycling or matching.
>
> How does it know what to call?  Is it the same command that invoked
> the minibuffer?  Do you have to define a new function for this,
> one for each command that uses the feature?

A global variable, `icicle-candidate-fn', is bound to the function to use
for the action. If it is bound to nil, then `C-RET' etc. are associated with
the default action, which is to simply display individual help about the
candidate. (The help action is also always available on `C-M-RET' etc.)
Candidate help tries to DTRT, depending on the type of candidate (see
command `icicle-help-on-candidate').

Yes, you must define a new command, in order to adapt a given existing
command to multi-command use. This is a good thing, as some commands might
not lend themselves well to multi-command use (i.e. it might make no sense
for them, adding nothing). And, more often, it is appropriate for some
commands to have a slightly different action function for candidates during
completion than after completion (for instance, because the
buffer/window/frame context or the use context might be different).

The command used for the `C-RET' action can be any command. Sometimes
`C-RET' performs the same action as the command invoking completion would
carry out on the candidate chosen finally. Sometimes the action performed is
a bit different or even quite different.

The particular command and its context of use determines what is appropriate
(most useful). The devil is in the details of the particular command and its
use cases. We can generalize to some extent (that is what the
multi-command-defining macros are for), but the best definition of a given
multi-command should be decided case by case.

Also, the command that invoked completion is not the same thing as the part
of that command that actually acts on the candidate that is chosen - what I
call the action function, bound to `icicle-candidate-action-fn'. Also,
because of the difference in context (completion has not yet ended when the
action is carried out), some window, buffer, etc. management needs to be
taken into account.

You can take a look at the multi-commands that I have defined. They are all
in file icicles-cmd.el. You can find them by searching for any of these:

1. icicle-define-command
2. icicle-define-file-command
3. icicle-candidate-action-fn

#1 and #2 are those multi-commands that use the same action function for
final action and action during completion. #3 are other commands, which bind
`icicle-candidate-action-fn' explicitly.

The macro expansion of a multi-command defined using #1 or #2 is quite
complex. Some of its definition implements context management (window,
frame, buffer), and some of it implements treatment of possible errors from
application of the action function. For example, the original buffer,
window, or frame, to which we often want to return, might have been deleted
by application of the action to a particular candidate (e.g. if the action
is to kill the buffer, and the candidate acted on is the original buffer).
And we usually want to keep the focus after action application on the
minibuffer's frame, so that we can possibly keep using `C-RET' etc. on other
candidates.

To see what I mean about the complex definition, load icicles-cmd.el (not
.elc) and then use `symbol-function' on a command defined with one of the
macros. Or take a look at the macro definitions themselves, in
icicles-mac.el.

The optional alternative action function and the optional deletion-action
are treated similarly. For instance, binding
`icicle-candidate-alternative-action-fn' provides an alternative action,
bound to `C-S-RET' etc.

See
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Defining_Icicles_Commands
for more about defining multi-commands. See
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Multi-Commands_the_Hard_Way
for more about how the macros work.

> It sounds like an ugly mechanism,

What does? Why?

> so if this feature is worth adding,
> I would rather it be implemented differently.  The cleanest way I can
> think of is to set a flag telling call-interactively to call the
> function then loop around, keeping the same prefix argument.

Sorry, I don't understand this. Please elaborate. It "sounds like" you are
redesigning without even being familiar with the design.

I am not into redesigning Icicles or re-implementing the basic design. If
others wish to do that later, that's another matter. A lot of time, testing,
and use has gone into the current design and implementation. It works well,
and I think it is quite clean. When  not in Icicle mode, a user cannot tell
that s?he was ever in it. And when in Icicle mode, s?he can still use Emacs
in the same way as usual, with no real perception of a difference, as long
as s?he doesn't use any of the extra minibuffer bindings.

In some ways, the implementation is non-trivial - you don't want to make
cavalier changes, and you must retest lots of scenarios after a fundamental
change. Icicles is very general, which means that it has lots of different
use scenarios. There are some global variables that hold various kinds of
state, which means that some parts of the code are tightly coupled with
other parts. I haven't done that gratuitously, but only when I felt it was
necessary. That doesn't mean that there might not sometimes be a better way;
it means only that one must be careful making changes to the core
implementation.

I'm not against making minor changes that I become convinced would be
improvements, but I don't want to start over or possibly jeopardize things
that work well by making fundamental changes that are not simple. Vague "do
it this way instead" or "n'y a qu'a" suggestions won't convince me. If you
want to discuss concrete implementation details, that's fine. I'm open to
change, but I don't want to break things just because someone thinks s?he
has a better idea (without making an effor to try out that idea or discuss
it concretely).

If Icicles does not break anything, and it does not have a lasting effect
when you leave Icicle mode, then I think how it is implemented should not be
a concern. How it is implemented can of course be examined to help determine
if it breaks something.

After FSF owns the code, others can take responsibility for breaking
Icicles, if they like. Or I can continue to maintain it for FSF - which I
prefer. I intend anyway to maintain and enhance my own version of Icicles,
which I will continue to make available on Emacs Wiki. If my own version and
the Emacs version begin to diverge so much that I cannot work on the former,
then I'll go back to working on just the latter.

> keeping the same prefix argument.

Wrt prefix args: C-u is treated specially during completion, so that, for
instance, you can apply it to individual candidates that you act on using
`C-RET'. That is, you can use a different prefix argument each time you act
on a candidate, if you like. Remember, that, by default, you can act on the
same candidate multiple times. Sometimes that makes sense, sometimes it does
not. You can bind `icicle-use-candidates-only-once-flag' to control this.

See `icicles-mcmd.el' for the code (e.g. `icicle-universal-argument').

> This should work with ALL commands and avoid the need to define
> separate multi-commands.

Sorry, I don't agree.

1. It's not equally appropriate for all commands. It's not necessary for all
commands.

2. It's appropriate, for many commands, to specialize the action behavior
during completion. See the commands that explicitly bind
`icicle-candidate-action-fn', as opposed to just using
`icicle-define-command'. Command `icicle-search', for instance, could not be
defined using `icicle-define-command'.

> Once multi-commands are gone, does Icicles need to
> redefine any commands?  Is it just a matter of changes
> inside completing-read?

Sorry, I don't understand what you mean. Multi-commands will not be "gone".
Multi-commandness will not be extended automatically to all commands. That
is not appropriate.

Are you asking for a list of Emacs commands that Icicles redefines when you
are in Icicle mode (and restores when you exit that mode)? This is the
list - it is also in the header of `icicles.el':

 completing-read, display-completion-list, exit-minibuffer,
 minibuffer-complete-and-exit, read-file-name,
 read-from-minibuffer, read-string, dabbrev-completion,
 lisp-complete-symbol, mouse-choose-completion,
 choose-completion-string, completion-setup-function,
 switch-to-completions, next-history-element (advised only),
 repeat-complex-command

It's possible that some of these redefinitions could be moved to vanilla
Emacs permanently. Typically, the original definition is extended only
slightly. For instance, the `repeat-complex-command' definition is extended
to read the command to be repeated using `completing-read', so that you can
use completion on the history list and use `C-,' to sort the candidate list
(in *Completions*) in different ways.

If `icicle-bind-top-level-commands-flag' is non-nil, then various top-level
bindings are redefined for use in Icicle mode - the list is in
`icicles-mode.el'. In `icicle-mode-map', for example, `abort-recursive-edit'
is remapped to `icicle-abort-minibuffer-input'. The original binding is
restored when Icicle minor mode is exited.

As another example, `completion-setup-function' is modified so that it does
not print the help lines at the top of *Completions*. That printing is done
instead in `display-completion-list', so that the *Completions* window can
be fit to the buffer. Icicles formats the *Completions* display
"intelligently", determining a useful number of columns and height, and it
fits the window to the formatted buffer. (This formatting, e.g. column
spread and default window width, is under the control of user options.) That
is an enhancement that we might want to consider for vanilla Emacs.

As a third example, `switch-to-completions' is extended to always select the
*Completions* window, even when it is on another frame.

In sum, any attempt to integrate such changes tightly with the vanilla Emacs
code needs to be done on a case-by-case basis. I suggest that there is no
need to do that at all now, but it could be done over time, if some such
extensions were deemed useful to vanilla Emacs also.

Re: propose adding Icicles to Emacs

[Stefan Monnier]

> The `completing-read' code is here:
> http://www.emacswiki.org/cgi-bin/wiki/icicles-fn.el. Perhaps others more
> familiar with Emacs implementation can advise whether some of this
> redefinition could or should be moved to the vanilla definition of
> `completing-read' or what might be a "cleaner way" to do what is done now
> this way. I would advise just leaving this code as is, at least for now.

Redefining completing-read is a no-no in my book.  Please try to rewrite
your code so as not to do that (e.g. using minibuffer-setup-hook).  Also, if
it turns out to be impossible, or very inconvenient, then post a request for
enhancement to make it possible/easier.

>> it can replace some top-level commands with Icicles
>> versions (e.g. `find-file' with `icicle-find-file').
> I should be clear that this is not about redefining commands; it is about
> remapping their bindings: the bindings for `find-file' are mapped to
> `icicle-find-file'.

I.e. find-file is not changed.  You just remap C-x C-f to your
command, right?  That's perfectly fine.


        Stefan

RE: propose adding Icicles to Emacs

[Drew Adams]

> > The `completing-read' code is here:
> > http://www.emacswiki.org/cgi-bin/wiki/icicles-fn.el. Perhaps others more
> > familiar with Emacs implementation can advise whether some of this
> > redefinition could or should be moved to the vanilla definition of
> > `completing-read' or what might be a "cleaner way" to do what
> > is done now this way. I would advise just leaving this code as is,
> > at least for now.
>
> Redefining completing-read is a no-no in my book.  Please try to rewrite
> your code so as not to do that (e.g. using minibuffer-setup-hook).

I don't see how to do that. Concrete suggestions welcome. Please have a look
at the existing code. Likewise for the other, related functions
(`read-file-name', etc.).

I already do a lot of stuff on `minibuffer-setup-hook'. See, for instance,
`icicle-minibuffer-setup', which is on `minibuffer-setup-hook' when in
Icicle mode. I have no idea how to do what would need to be done for
`completing-read', `read-file-name',... with `minibuffer-setup-hook'.

The code restores the original definitions when Icicle mode is exited, so
I'm not sure why the redefinition within Icicle mode is a no-no. I'm not
arguing, but I don't see the reason for the prohibition.

> Also, if it turns out to be impossible, or very inconvenient,
> then post a request for enhancement to make it possible/easier.

I have no idea what to request. Perhaps if you explain what you mean about
using minibuffer-setup-hook, there will be no need.

> >> it can replace some top-level commands with Icicles
> >> versions (e.g. `find-file' with `icicle-find-file').
> > I should be clear that this is not about redefining commands;
> > it is about remapping their bindings: the bindings for
> > `find-file' are mapped to `icicle-find-file'.
>
> I.e. find-file is not changed.  You just remap C-x C-f to your
> command, right?  That's perfectly fine.

That is correct. I believe that only the functions I listed are actually
redefined (and only while in Icicle mode).

Re: propose adding Icicles to Emacs

[Stefan Monnier]

>> Redefining completing-read is a no-no in my book.  Please try to rewrite
>> your code so as not to do that (e.g. using minibuffer-setup-hook).

> I don't see how to do that.  Concrete suggestions welcome.  Please have
> a look at the existing code.  Likewise for the other, related functions
> (`read-file-name', etc.).

I'd rather it be the other way around: tell us what you're trying to do (and
finding you cannot do).

> I'm not sure why the redefinition within Icicle mode is a no-no.  I'm not
> arguing, but I don't see the reason for the prohibition.

It's OK for an external package (tho I prefer defadvice), but for reasons of
maintainability and general principle it's not good inside Emacs.
We probably do have such things already inside Emacs, but we want to reduce
such occurrences rather than increase them.

> Perhaps if you explain what you mean about using minibuffer-setup-hook,
> there will be no need.

E.g. Why not do the fiddling of initial-input with icicle-initial-value in
a minibuffer-setup-hook?


        Stefan

RE: propose adding Icicles to Emacs

[Drew Adams]

> >> Redefining completing-read is a no-no in my book.  Please try
> >> to rewrite your code so as not to do that (e.g. using
> >> minibuffer-setup-hook).
>
> > I don't see how to do that.  Concrete suggestions welcome.  Please have
> > a look at the existing code.  Likewise for the other, related functions
> > (`read-file-name', etc.).
>
> I'd rather it be the other way around: tell us what you're trying
> to do (and finding you cannot do).

As I said, I don't know how to approach that. What I'm trying to do now
should be clear from the code, but see below, for some concrete examples.

> > I'm not sure why the redefinition within Icicle mode is a
> > no-no.  I'm not arguing, but I don't see the reason for the
> > prohibition.
>
> It's OK for an external package (tho I prefer defadvice), but for
> reasons of maintainability and general principle it's not good
> inside Emacs. We probably do have such things already inside
> Emacs, but we want to reduce such occurrences rather than increase
> them.
>
> > Perhaps if you explain what you mean about using minibuffer-setup-hook,
> > there will be no need.
>
> E.g. Why not do the fiddling of initial-input with icicle-initial-value in
> a minibuffer-setup-hook?

That particular initialization is only appropriate for `completing-read',
not, for example, for `read-file-name' or other functions that cause
`minibuffer-setup-hook' to be invoked. In particular, `read-file-name' has a
very different treatment of the initial value.

I'm pretty sure that, had it been feasible to put the stuff that is done in
`completing-read' onto `minibuffer-setup-hook', that would have been the
first thing that I would have done. I don't recall now the details behind
each of the decisions to do what is done now in `completing-read' (or in
`read-file-name' etc.), and I would be reluctant to simply try to move any
such code to a hook.

I guess I'm asking that you trust, to some extent, that I did what I could
in that regard, but I'm open to concrete suggestions if you have them. I'm
grateful for new pairs of eyes and greater expertise and knowledge of Emacs
code. What I don't want to do is risk breaking things. As I said, there is a
lot going on, and it's not easy or obvious how to test everything after
making a fundamental change.

I really propose that the basic implementation be incorporated as it is now.
That should be OK, since the redefinitions are encapsulated in a minor mode.
We could revisit possible optimizations, cleanup, and other code
improvements later, carefully, and little by little.

For example, we could go through the Icicle-mode version of
`completing-read' piece by piece, trying to see whether such-and-such a
piece could be better done elsewhere or in a different way - just as I just
did above for `icicle-initial-value'. I believe that what is there now is
specific to `completing-read', and would be inappropriate (it wouldn't work)
if it were moved, say, to `minibuffer-setup-hook'.

Each of the pieces of code in the Icicles definition of `completing-read'
has a comment explaining the intention, so I think that it should be
possible for someone to make a suggestion regarding such a piece. For
example:

  ;; Override REQUIRE-MATCH as needed.
  (setq require-match (case icicle-require-match-flag
                        ((nil) require-match)
                        (no-match-required nil)
                        (partial-match-ok t)
                        (full-match-required 'full-match-required))
        icicle-require-match-p require-match)

Here, the intent of the first `setq' pair is to override the REQUIRE-MATCH
argument, based on the value of `icicle-require-match-flag', which is bound
in some commands, but is generally nil. This piece of code is common to both
`completing-read' and `read-file-name'; other pieces are specific to one or
the other (or to other such minibuffer functions, such as
`read-from-minibuffer').

Do you have a suggestion how or where better to do that? It cannot be done
in `minibuffer-setup-hook', because it redefines the value of a
`completing-read' argument.

The intention of the second `setq' pair is not commented, but it is simply
to record the REQUIRE-MATCH argument, so that it can be tested elsewhere.
One place that information is used is in `icicle-narrow-candidates', which
is bound to `M-*' and which you use for progressive completion, to provide a
new match pattern. That command launches a new `completing-read' or a new
`read-file-name' with appropriate arguments according to the current
context, and the appropriate value to pass for REQUIRE-MATCH is the same
value that was used originally. There are currently global variables such as
`minibuffer-completion-table', but AFAIK there is no variable for the
current REQUIRE-MATCH parameter. So, here's a case where, if we added such a
global variable to Emacs, this bit of code in the redefined
`completing-read' would go away.

Again, I agree that it would be worthwhile to examine the code in such
detail, with an eye to seeing what might in fact be needed in Emacs
generally (such as a `minibuffer-require-match' variable, perhaps), and also
with an eye to seeing how I might better do some things elsewhere and
differently than by redefining `completing-read'. I just don't expect that
there is one simple solution for all such stuff, and I don't think we should
try to do that now, except possibly for something easy and obvious.

Similarly, for the other code pieces. We could examine them one by one, but
I'm not sure what that would gain us. In the end, I suspect that there will
be a fair amount of redefinition that is needed, whatever else is tried.

(I didn't mention it, as I thought it was obvious, but the reason I change
the behavior of `completing-read' etc. is so that any code that uses such
functions can automatically take advantage of Icicles features.)

Some of the function redefinitions could perhaps be migrated to the general
Emacs code, as I mentioned earlier. I also mentioned that I think that
should not be attempted now, but after leaving it only in Icicles for a
while.

An example of this would be the Icicles redefinition of `read-face-name'.
The only change Icicles makes here is to display the face names in
*Completions* using their own faces. That is an obvious candidate for
inclusion in vanilla Emacs, IMO. This is the kind of thing that you guys
would generally do with a patch, but from a third-party library perspective,
I needed to do it by redefining (or advising) `read-face-name' temporarily
for the minor mode.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    > I'm not sure why the redefinition within Icicle mode is a no-no.  I'm not
    > arguing, but I don't see the reason for the prohibition.

    It's OK for an external package (tho I prefer defadvice), but for reasons of
    maintainability and general principle it's not good inside Emacs.
    We probably do have such things already inside Emacs, but we want to reduce
    such occurrences rather than increase them.

The reason is this.  To have a definition of foo in file A
and another in file B can be confusing.  A person who sees
the main definition in A won't know there is another.
(It's the same consequence if B advises foo.)

It is much better to have one single definition of foo, in file A,
with a conditional or hook to take care of what B wants.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    I don't see how to do that. Concrete suggestions welcome. Please have a look
    at the existing code. Likewise for the other, related functions
    (`read-file-name', etc.).

    I already do a lot of stuff on `minibuffer-setup-hook'. See, for instance,
    `icicle-minibuffer-setup', which is on `minibuffer-setup-hook' when in
    Icicle mode. I have no idea how to do what would need to be done for
    `completing-read', `read-file-name',... with `minibuffer-setup-hook'.

What are the jobs that need to be done there,
which you don't know how to do this way?

We could think about how else to do them.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     I don't see how to do that. Concrete suggestions welcome.
>     Please have a look at the existing code. Likewise for the
>     other, related functions (`read-file-name', etc.).
>
>     I already do a lot of stuff on `minibuffer-setup-hook'. See,
>     for instance, `icicle-minibuffer-setup', which is on
>     `minibuffer-setup-hook' when in Icicle mode. I have no idea
>     how to do what would need to be done for `completing-read',
>     `read-file-name',... with `minibuffer-setup-hook'.
>
> What are the jobs that need to be done there,
> which you don't know how to do this way?

What do you mean by "there"? If you mean on `minibuffer-setup-hook', then
please reread the above. I am saying that I cannot do there the different
things that I do now in various functions (`completing-read',
`read-file-name',...) on `minibuffer-setup-hook' instead.

I gave concrete examples for `completing-read' and pointed to the code for
the others as well. Each of the functions has different additional things
added, which cannot be done on `minibuffer-setup-hook'. Initializations etc.
that are appropriate for only one function (e.g. `completing-read') cannot
be put on a hook that is run when every function activates the minibuffer.

Re: propose adding Icicles to Emacs

[Stefan Monnier]

> I gave concrete examples for `completing-read' and pointed to the code for
> the others as well. Each of the functions has different additional things
> added, which cannot be done on `minibuffer-setup-hook'. Initializations etc.
> that are appropriate for only one function (e.g. `completing-read') cannot
> be put on a hook that is run when every function activates the minibuffer.

Saying "can't do that" is not helpful.
Please explain why you think you can't do that.  What would you need to do
be able to do?

E.g. you can probably distinguish from minibuffer-setup-hook between most of
the possible situations by looking at which keymap is used locally, what are
the settings for the various minibuffer-<foobar> variables, etc...

Maybe these solutions are just as ugly (e.g. comparing (current-local-map)
with minibuffer-local-completion-map would definitely count as an ugly
hack), but at least they may give us some idea of what might be needed.

Maybe other things just can't be done in minibuffer-setup-hook or
minibuffer-exit-hook because they need to be run at some completely
different moment.

Let's try to be constructive.


        Stefan

RE: propose adding Icicles to Emacs

[Drew Adams]

This mail is about how to handle Icicles code that redefines standard Emacs
functions. It details the case for each such function. It provides some
solutions and clarifies some open questions.

> > I gave concrete examples for `completing-read' and pointed to
> > the code for the others as well. Each of the functions has
> > different additional things added, which cannot be done on
> > `minibuffer-setup-hook'. Initializations etc. that are
> > appropriate for only one function (e.g. `completing-read')
> > cannot be put on a hook that is run when every function
> > activates the minibuffer.
>
> Saying "can't do that" is not helpful. Please explain why you
> think you can't do that. What would you need to do be able to do?

If code is specific to one function only, and you put it on the setup hook,
then it will also be executed for other functions for which it might not be
appropriate. Even in cases where that doesn't cause immediate harm, it
doesn't seem like a clean way to proceed, IMO. Things that are logically
local to a function should be contained inside it.

`minibuffer-setup-hook' is called all the time - even when completion is not
being done, as in `M-:', for instance. Trying to do something that is
specific to a particular minibuffer-reading function in the general setup
hook would be applying a sledge hammer, IMO.

Second, it is not just a matter of initialization before calling a built-in
function such as `completing-read'. If you look at the code, you'll see that
the result of `old-completing-read' is used, and there is a top-level catch
wrapped around it in some cases. This is to allow, in certain contexts, a
recursive minibuffer entry to return the result to the top level, so the
user doesn't have to keep hitting RET to get there.

In any case, Richard appears to prefer to implement Icicles-like features
directly in Emacs, including in the C code, so perhaps these kinds of things
can be moved directly to the original functions (e.g. `completing-read) - to
the extent that they might still be relevant in his design. That would be
the best approach, IMO.

For instance, here are some code-fragment candidates for outright removal if
Icicles features are integrated with Emacs:

1. The treatment of the prompt in my `completing-read' and `read-file-name'
can be eliminated. It simply adds a reminder to the prompt about some basic
Icicles bindings. If Icicles is part of Emacs, that will become sufficiently
known by the doc etc. Even in Icicles, unless you act explicitly to prevent
it, the reminder is removed after a certain number of Emacs sessions.

2. The treatment of `icicle-init-value-flag' can be eliminated, along with
that option. It does not jibe with the Emacs policy of deprecating the
INIT-VALUE argument. I like it, but Emacs developers will no doubt rule it
out. Alternatively, perhaps you could consider adding such an option, to
allow those users who, like me, would like the default value to always be
inserted as an init value. In any case, Icicles is not dependent on this.

3. The call to `icicle-fix-default-directory' (in my `read-file-name') can
be eliminated, along with that function, if this fix is moved into the Emacs
C code somewhere. This is a hack to convert any backslashes in
`default-directory' to slashes. Icicles needs it because Icicles lets you
use backslashes for regexp syntax during completion. This is important for
Icicles, and I don't think such a fix would in any way be harmful to Emacs.

4. My `completing-read' also removes the *Completions* window, at the end.
This was added because the window was not being removed when REQUIRE-MATCH
is non-nil. I'm not 100% sure this is still needed. If it is, then you can
think of this as a bug fix to `completing-read'.

Here are some fragments that would be candidates for integration directly
into the vanilla Emacs code:

1. The treatment of `icicle-require-match-flag' can be discussed. I already
spoke about this. This variable lets code that calls completion functions
such as `completing-read' override the REQUIRE-MATCH argument. Code can bind
this so that any contained calls for completion will respect the binding. I
think this is a good addition and such a variable should be available, but
others might disagree.

I already mentioned the need for a global variable that records (holds) the
value of the passed REQUIRE-MATCH argument. Perhaps these two variables can
be combined. The need for the latter variable, for Icicles, is, as I said,
to be able to call for another completion with the same argument. That is a
requirement for doing progressive completion (as it it is implemented
today). Progressive completion is using `M-*' to be able to input another
completion pattern to also match against the current set of candidates.

2. My `completing-read' also converts an alist of candidates that are
so-called "multi-completions" to the standard alist form. This too could be
added directly to Emacs `completing-read', just as Emacs 22 added the
ability to pass a flat list of strings instead of an alist.

Multi-completions let you provide several strings for each completion
candidate when you call a completion function. That is, a candidate can be a
list of strings. The strings are joined using a user-defined join string and
terminated with a user-defined end string. Icicles can also transform the
resulting string for presentation purposes etc. This is a useful feature
that allows, for instance, the displayed candidate to differ from the
returned candidate in a user-controlled way.

See these for an explanation of this feature:

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Multi-Completions

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Programming_Multi-Completion
s

Multi-completions are not to be confused with Icicles multi-commands, Emacs
`completing-read-multiple', or Emacs completion-candidate annotation.


***********
If we find a way to handle the needed initializations (which are a bit
different for the different completion functions) and the top-level `catch',
then this pretty much handles everything that is currently in the Icicles
version of `completing-read', `read-file-name', `read-from-minibuffer', and
`read-string'.

***********
File icicles-fn.el also redefines some other standard Emacs functions:

1. As I mentioned, my `read-face-name' just shows face names in
*Completions* using their own faces. IMO, that should also be done in Emacs,
but it is 100% independent of the rest of Icicles.

2. Same thing for `face-valid-attribute-values': It shows color names using
the colors they name. Good to add to Emacs, and independent of the rest of
Icicles.

3. My `choose-completion-string' has the minor tweak of not exiting the
minibuffer if this is just a `lisp-complete-symbol' completion. This was
done long ago, and I'm not sure it is still relevant. Again, if it is useful
it can be added to Emacs independently of the rest of Icicles - Icicles does
not depend on this.

4. My `completion-setup-function' and `display-completion-list' - see what I
wrote before (about fitting the *Completions* window to the buffer etc.).
This would mean modifying the definitions of `completion-setup-function' and
`display-completion-list' in ways that I think would be good anyway. For
instance, my `display-completion-list' does not remove text properties from
candidates, and it adjusts the number of displayed columns and their widths.
I personally would prefer to see `display-completion-list' be a Lisp
function, but I will survive without that. My enhancements to it are
independent of the rest of Icicles, but they do matter to the Icicles
experience ;-).

That covers all of the replacements of standard Emacs functions that I do in
icicles-fn.el. I also replace some standard functions in icicle-cmd.el and
icicle-mcmd.el.

***********
In icicle-mcmd.el:

1. My `exit-minibuffer', my `minibuffer-complete-and-exit', and my
`mouse-choose-completion' are enhanced to also remove the *Completions*
window. I think this should also be done in Emacs. This removal deletes all
windows anywhere that show *Completions*.

2. My `mouse-choose-completion' also records the number of the current
completion candidate in a global variable. This is so that Icicles functions
that work with the candidate number will also work when you choose a
candidate with the mouse, not just by cycling. The candidate number is very
important for Icicles, some functionality being dependent on it.

3. My `switch-to-completions' selects the *Completions* window, even if it
is on another frame. This could be added to Emacs independently of Icicles.

***********
In icicle-cmd.el:

1. My `dabbrev-completion' and my `lisp-complete-symbol' also select the
*Completions* window, even if it is on another frame. This is not very
important.

2. My `customize-apropos', `customize-apropos-faces',
`customize-apropos-groups', `customize-apropos-options', and
`repeat-complex-command' all use `completing-read' to read the regexp. Note
that using completion means not only that you can use regexp matching but
also that you can sort the candidates in different ways (important for
cycling order). This is not just key remapping; it is definition replacement
(via `defalias') and then restoration when you exit Icicle mode. I would
like to see something like this done in Emacs, but it is independent of the
rest of Icicles.

3. I also redefine some standard user options, overriding them with Icicles
versions: `search-ring-max', `regexp-search-ring-max', and
`kmacro-ring-max'. I do this so that Icicles users can have a different
value (typically much larger) for Icicles than they use for vanilla Emacs
use. I didn't want Icicles to be intrusive, so I let them have separate
values for these things, assuming they might want to use Icicle mode only
sometimes.

I'm not sure how this should be handled. Icicles facilitates using much
larger such rings, so it makes sense for Icicles users to have large values.
I suppose that we could just expect that users of Icicles (or Icicles-like
optional Emacs features) would always use it and so would customize their
standard options accordingly. In that case, we can get rid of the Icicles
versions of these options and the mode entry/exit redefinition/restoration.

******
I think that covers ALL of the replacements I do of standard Emacs functions
and options.
******

> E.g. you can probably distinguish from minibuffer-setup-hook
> between most of the possible situations by looking at which keymap
> is used locally, what are the settings for the various
> minibuffer-<foobar> variables, etc...

Ouch! That does not sound good to me. The idea is to reduce the use of ugly
hacks, not increase it ;-).

> Maybe these solutions are just as ugly (e.g. comparing (current-local-map)
> with minibuffer-local-completion-map would definitely count as an ugly
> hack), but at least they may give us some idea of what might be needed.
>
> Maybe other things just can't be done in minibuffer-setup-hook or
> minibuffer-exit-hook because they need to be run at some completely
> different moment.
>
> Let's try to be constructive.

I really don't see `minibuffer-setup-hook' as offering help here.

I think that, depending on the general approach to be taken for integrating,
the best solution is to modify `completing-read' so that it does what is
needed - where "what is needed" might be something different from what I do
now, depending on the chosen design for these features.

Hopefully, some of the information above will help in this direction.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    If code is specific to one function only, and you put it on the setup hook,
    then it will also be executed for other functions for which it might not be
    appropriate. Even in cases where that doesn't cause immediate harm, it
    doesn't seem like a clean way to proceed, IMO.

I understand this general point.  But I can only solve problems in
specific.  I'm asking about what you specifically need to do to make
completing-read do what you want.

    1. The treatment of the prompt in my `completing-read' and `read-file-name'
    can be eliminated. It simply adds a reminder to the prompt about some basic
    Icicles bindings. If Icicles is part of Emacs, that will become sufficiently
    known by the doc etc.

Right.

    2. The treatment of `icicle-init-value-flag' can be eliminated, along with
    that option. It does not jibe with the Emacs policy of deprecating the
    INIT-VALUE argument. I like it, but Emacs developers will no doubt rule it
    out. Alternatively, perhaps you could consider adding such an option, to
    allow those users who, like me, would like the default value to always be
    inserted as an init value. In any case, Icicles is not dependent on this.

Can't you use `minibuffer-setup-hook' to do that?

    3. The call to `icicle-fix-default-directory' (in my `read-file-name') can
    be eliminated, along with that function, if this fix is moved into the Emacs
    C code somewhere. This is a hack to convert any backslashes in
    `default-directory' to slashes. Icicles needs it because Icicles lets you
    use backslashes for regexp syntax during completion.

I semi-understand that, but how do the backslashes get into
`default-directory'?  If they serve to control completion, they should
always be eliminated by the time `read-file-name' returns, right?

    4. My `completing-read' also removes the *Completions* window, at the end.
    This was added because the window was not being removed when REQUIRE-MATCH
    is non-nil.

That is a bug.  If it still exists, we should fix it in `completing-read'.

    1. The treatment of `icicle-require-match-flag' can be discussed. I already
    spoke about this. This variable lets code that calls completion functions
    such as `completing-read' override the REQUIRE-MATCH argument. Code can bind
    this so that any contained calls for completion will respect the binding. I
    think this is a good addition and such a variable should be available, but
    others might disagree.

I don't know enough to have an opinion.  Can you present a use case
for this feature?

    I already mentioned the need for a global variable that records (holds) the
    value of the passed REQUIRE-MATCH argument. Perhaps these two variables can
    be combined. The need for the latter variable, for Icicles, is, as I said,
    to be able to call for another completion with the same argument.

I don't understand those words.

    Multi-completions let you provide several strings for each completion
    candidate when you call a completion function. That is, a candidate can be a
    list of strings. The strings are joined using a user-defined join string and
    terminated with a user-defined end string.

If this is useful, the right place to add it is inside
`try-completion' and other functions at the same level.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     If code is specific to one function only, and you put it on
>     the setup hook, then it will also be executed for other functions
>     for which it might not be appropriate. Even in cases where that
>     doesn't cause immediate harm, it
>     doesn't seem like a clean way to proceed, IMO.
>
> I understand this general point.  But I can only solve problems in
> specific.  I'm asking about what you specifically need to do to make
> completing-read do what you want.

Between an earlier email from me and the one you are quoting, I think I
answered that. I don't think I left anything out. I went through the code
bit by bit, explaining what was involved and what would need to be done, if
this redefinition were to dispensed with.

>     2. The treatment of `icicle-init-value-flag' can be
>     eliminated, along with
>     that option. It does not jibe with the Emacs policy of deprecating the
>     INIT-VALUE argument. I like it, but Emacs developers will no
>     doubt rule it
>     out. Alternatively, perhaps you could consider adding such an
>     option, to
>     allow those users who, like me, would like the default value
>     to always be
>     inserted as an init value. In any case, Icicles is not
>     dependent on this.
>
> Can't you use `minibuffer-setup-hook' to do that?

No. That hook runs whether completion is used or not. It even runs for
`M-:', for instance. Anyway, I said that you can eliminate this feature.
Let's not belabor this stuff; there's already enough to discuss.

>     3. The call to `icicle-fix-default-directory' (in my
>     `read-file-name') can be eliminated, along with that function,
>     if this fix is moved into the Emacs C code somewhere. This is a
>     hack to convert any backslashes in `default-directory' to slashes.
>     Icicles needs it because Icicles lets you
>     use backslashes for regexp syntax during completion.
>
> I semi-understand that, but how do the backslashes get into
> `default-directory'?  If they serve to control completion, they should
> always be eliminated by the time `read-file-name' returns, right?

They can get into `default-directory' on Windows, at least. IMO, they should
never get into it, but they can.

>     4. My `completing-read' also removes the *Completions*
>     window, at the end. This was added because the window was not
>     being removed when REQUIRE-MATCH is non-nil.
>
> That is a bug.  If it still exists, we should fix it in `completing-read'.

Right. I don't know if it is still a bug, but I think so. I believe I've
seen other users (of Emacs, not Icicles) complain recently about the
*Completions* window not going away. In fact I'm almost positive it's still
a bug, because when I turn off Icicle mode I notice it.

This happens when you have non-nil `pop-up-frames'. There are several ways
in which Emacs is not very friendly to  non-nil `pop-up-frames', as I've
mentioned before.

FWIW, in my own (non-Icicles) code, I also redirect the focus of
*Completions* to the minibuffer. That is, I give the standalone
*Completions* frame its own display function, and I do this inside that
function:

  (redirect-frame-focus (selected-frame) 1on1-minibuffer-frame)

IMO, that should also be built into Emacs for such a context. The input
focus for *Completions* should always be the minibuffer. Anyway, this is
off-topic...

>     1. The treatment of `icicle-require-match-flag' can be
>     discussed. I already spoke about this. This variable lets code
>     that calls completion functions such as `completing-read'
>     override the REQUIRE-MATCH argument. Code can bind
>     this so that any contained calls for completion will respect
>     the binding. I think this is a good addition and such a
>     variable should be  available, but others might disagree.
>
> I don't know enough to have an opinion.  Can you present a use case
> for this feature?

General: you might want to define a command that uses an existing that calls
`completing-read'. You don't therefore have direct access to the call, so
you cannot change the value of the REQUIRE-MATCH argument that was passed.

Specific example: Some users like buffer-name completion to always be
strict, a la Ibuffer, rather than lax, a la `switch-to-buffer'. Icicles has
a user option that you can set to make REQUIRE-MATCH effectively strict for
Icicles commands that use buffer names.

Those buffer commands bind variable `icicle-require-match-flag' to the
user's choice (which is the value of `icicle-buffer-require-match-flag'. My
`completing-read' checks `icicle-require-match-flag' and overrides the
REQUIRE-MATCH arg if appropriate. I mention buffer-name completion because
it is a common example, but the same principle applies to any completion.

>     I already mentioned the need for a global variable that
>     records (holds) the value of the passed REQUIRE-MATCH argument.
>     Perhaps these two variables can be combined. The need for the
>     latter variable, for Icicles, is, as I said,
>     to be able to call for another completion with the same argument.
>
> I don't understand those words.

Please see my reply to one of Stefan's emails on this topic. I am repeating
myself. Anyway...

1. `M-*' (`icicle-narrow-candidates') calls `completing-read' or
`read-file-name' again, recursively, to match an additional pattern you
provide. I call this "progressive completion", and it is akin to piping
greps. In this recursive call, the same value of REQUIRE-MATCH should be
used. Since this is in a different command, I need a global variable for
this value.

2. Also, `icicle-candidate-action', which is `C-RET' (likewise, the
alternative-action command, bound to `C-S-RET'), uses the recorded value of
REQUIRE-MATCH to handle the action. When a match is required, the candidate
must be one of those in `minibuffer-completion-table'. For lax completion,
`C-RET' lets you act on any input you type.

Note: having a global variable for REQUIRE-MATCH just makes sense, to me. We
already have the same thing for PREDICATE and TABLE
(`minibuffer-completion-predicate', `minibuffer-completion-table'). Icicles
uses these variables also for minibuffer commands. There is also a variable
`minibuffer-completion-confirm'. But there is no
`minibuffer-completion-require-match' - that's what my
`icicle-require-match-p' is.

>     Multi-completions let you provide several strings for each completion
>     candidate when you call a completion function. That is, a
>     candidate can be a list of strings. The strings are joined using
>     a user-defined join string and
>     terminated with a user-defined end string.
>
> If this is useful, the right place to add it is inside
> `try-completion' and other functions at the same level.

Maybe. I don't know. You can get an idea by checking where it is used.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    > I semi-understand that, but how do the backslashes get into
    > `default-directory'?  If they serve to control completion, they should
    > always be eliminated by the time `read-file-name' returns, right?

    They can get into `default-directory' on Windows, at least. IMO, they should
    never get into it, but they can.

Instead of catering to this bug, we should debug it and fix it.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Specific example: Some users like buffer-name completion to always be
    strict, a la Ibuffer, rather than lax, a la `switch-to-buffer'. Icicles has
    a user option that you can set to make REQUIRE-MATCH effectively strict for
    Icicles commands that use buffer names.

    Those buffer commands bind variable `icicle-require-match-flag' to the
    user's choice (which is the value of `icicle-buffer-require-match-flag'. My
    `completing-read' checks `icicle-require-match-flag' and overrides the
    REQUIRE-MATCH arg if appropriate. I mention buffer-name completion because
    it is a common example, but the same principle applies to any completion.

If we want such a feature, it should be a separate feature.

    Please see my reply to one of Stefan's emails on this topic. I am repeating
    myself. Anyway...

    1. `M-*' (`icicle-narrow-candidates') calls `completing-read' or
    `read-file-name' again, recursively, to match an additional pattern you
    provide. I call this "progressive completion", and it is akin to piping
    greps. In this recursive call, the same value of REQUIRE-MATCH should be
    used. Since this is in a different command, I need a global variable for
    this value.

I don't mind adding `minibuffer-completion-require-match' if we end up
needing it.

    2. Also, `icicle-candidate-action', which is `C-RET' (likewise, the
    alternative-action command, bound to `C-S-RET'), uses the recorded value of
    REQUIRE-MATCH to handle the action. When a match is required, the candidate
    must be one of those in `minibuffer-completion-table'. For lax completion,
    `C-RET' lets you act on any input you type.

If we implement this whole feature as I suggested, it will do the
right thing with REQUIRE-MATCH automatically.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    1. As I mentioned, my `read-face-name' just shows face names in
    *Completions* using their own faces. IMO, that should also be done in Emacs,
    but it is 100% independent of the rest of Icicles.

This could be a good idea.  Can it be done by replacing the standard
`read-face-name' with yours?  Would someone please look at installing
this?

    2. Same thing for `face-valid-attribute-values': It shows color names using
    the colors they name. Good to add to Emacs, and independent of the rest of
    Icicles.

Likewise.


    3. My `choose-completion-string' has the minor tweak of not exiting the
    minibuffer if this is just a `lisp-complete-symbol' completion. This was
    done long ago, and I'm not sure it is still relevant. Again, if it is useful
    it can be added to Emacs independently of the rest of Icicles - Icicles does
    not depend on this.

It seems random and probably not desirable.

    4. My `completion-setup-function' and `display-completion-list' - see what I
    wrote before (about fitting the *Completions* window to the buffer etc.).
    This would mean modifying the definitions of `completion-setup-function' and
    `display-completion-list' in ways that I think would be good anyway. For
    instance, my `display-completion-list' does not remove text properties from
    candidates, and it adjusts the number of displayed columns and their widths.
    I personally would prefer to see `display-completion-list' be a Lisp
    function, but I will survive without that. My enhancements to it are
    independent of the rest of Icicles, but they do matter to the Icicles
    experience ;-).

I am not sure what that previous text that refers to, but someone can
look at these changes and think about installing them.  Would someone
please do?

    3. My `switch-to-completions' selects the *Completions* window, even if it
    is on another frame. This could be added to Emacs independently of Icicles.

That seems good.  Would someone please look at installing this change?

    1. My `dabbrev-completion' and my `lisp-complete-symbol' also select the
    *Completions* window, even if it is on another frame. This is not very
    important.

Likewise.  Anything that selects the *Completions* buffer
ought to do it in a general way.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     1. As I mentioned, my `read-face-name' just shows face names in
>     *Completions* using their own faces. IMO, that should also be
>     done in Emacs, but it is 100% independent of the rest of Icicles.
>
> This could be a good idea.  Can it be done by replacing the standard
> `read-face-name' with yours?

Yes. It is not dependent on the rest of Icicles in any way.

> Would someone please look at installing this?
>
>     2. Same thing for `face-valid-attribute-values': It shows
>     color names using the colors they name. Good to add to Emacs,
>     and independent of the rest of Icicles.
>
> Likewise.

Yes, likewise.

>     4. My `completion-setup-function' and `display-completion-list'
>     - see what I wrote before (about fitting the *Completions*
>     window to the buffer etc.). This would mean modifying the
>     definitions of `completion-setup-function' and
>     `display-completion-list' in ways that I think would be good
>     anyway. For instance, my `display-completion-list' does not
>     remove text properties from candidates, and it adjusts the
>     number of displayed columns and their widths.
>     I personally would prefer to see `display-completion-list' be a Lisp
>     function, but I will survive without that. My enhancements to it are
>     independent of the rest of Icicles, but they do matter to the Icicles
>     experience ;-).
>
> I am not sure what that previous text that refers to,

>From my mail in this thread from Mon 6/11/2007 11:34 AM (your time might
vary):

| As another example, `completion-setup-function' is modified so that it
does
| not print the help lines at the top of *Completions*. That printing is
done
| instead in [my version of] `display-completion-list', so that the
| *Completions* window can be fit to the buffer. Icicles formats the
| *Completions* display "intelligently", determining a useful number of
| columns and height, and it fits the window to the formatted buffer.
| (This formatting, e.g. column and default window width, is under the
| control of user options.) That is an enhancement that we might want to
| consider for vanilla Emacs.

My version of `display-completion-list' is a Lisp transcription of the C
function in Emacs, to which I then added the enhancement just described.
These comments in the source code (icicles-fn.el) describe all of the
Icicles enhancements to `display-completion-list':

1. Does not remove text properties from candidates when it displays them in
*Completions*. [I think I persuaded you already to do this in Emacs. It may
already be in Emacs 22.]

2. Adjusts number of columns and their widths to window size.

3. The optional second arg is ignored.  In the vanilla Emacs version, this
is a string representing a common prefix, and faces
`completions-first-difference' and `completions-common-part' are used on
candidates.

#3 is necessary for Icicles because Emacs hard-codes application of these
faces. Icicles doesn't need this and it gets in the way. Icicles highlights
the common parts in a better way for Icicles (and in a way that is under the
control of the user).

FWIW, I personally prefer that `display-completion-list' be in Lisp,
precisely because it is easier for users to tweak (as I did). *Completions*
display is, IMO, the kind of thing that third-party libraries might want to
or even need to customize. I don't see the point of having such code in C.
Having to transcribe the C code to Lisp, in order to then customize it, is a
chore that shouldn't be necessary. I avoided it for a long time, until I got
to the point where I wanted to do #2, for which there was no other solution.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    My version of `display-completion-list' is a Lisp transcription of the C
    function in Emacs, to which I then added the enhancement just described.

It is probably ok to replace the C version with a Lisp version.
(Does anyone see why not?)

Re: propose adding Icicles to Emacs

[Juri Linkov]

>     1. As I mentioned, my `read-face-name' just shows face names in
>     *Completions* using their own faces. IMO, that should also be done in Emacs,
>     but it is 100% independent of the rest of Icicles.
>
> This could be a good idea.  Can it be done by replacing the standard
> `read-face-name' with yours?  Would someone please look at installing
> this?

Not a good idea in fact.  Face completions displayed in different faces
are hardly readable, and some of them which have black foreground on black
background (e.g. cursor, mouse, border) are not readable at all.

>     4. My `completion-setup-function' and `display-completion-list' - see what I
>     wrote before (about fitting the *Completions* window to the buffer etc.).
>     This would mean modifying the definitions of `completion-setup-function' and
>     `display-completion-list' in ways that I think would be good anyway. For
>     instance, my `display-completion-list' does not remove text properties from
>     candidates, and it adjusts the number of displayed columns and their widths.
>     I personally would prefer to see `display-completion-list' be a Lisp
>     function, but I will survive without that. My enhancements to it are
>     independent of the rest of Icicles, but they do matter to the Icicles
>     experience ;-).
>
> I am not sure what that previous text that refers to, but someone can
> look at these changes and think about installing them.  Would someone
> please do?

Do you mean rewriting `display-completion-list' in Lisp?

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

RE: propose adding Icicles to Emacs

[Drew Adams]

> >     1. As I mentioned, my `read-face-name' just shows face names in
> >     *Completions* using their own faces. IMO, that should also
> >     be done in Emacs, but it is 100% independent of the rest of Icicles.
> >
> > This could be a good idea.  Can it be done by replacing the standard
> > `read-face-name' with yours?  Would someone please look at installing
> > this?
>
> Not a good idea in fact.  Face completions displayed in different faces
> are hardly readable, and some of them which have black foreground on black
> background (e.g. cursor, mouse, border) are not readable at all.

I find it _very_ helpful. What you say is true for only a few corner cases,
in general. A WYSIWYG show/no-show option that could be toggled from the
minibuffer during completion could easily deal with that.

FWIW, with Icicles there is really no great problem, because you can easily
get help on any candidate or just show its name in the minibuffer. For
instance, even if you can't read its name in *Completions*, and you can't
guess what it is by its position in the alphabetized list, you can use
`C-M-mouse-2' or `C-M-RET' to get help on the `border' face candidate during
completion - you then see this in buffer *Help*:

 Face: border (sample) (customize this face)
 Documentation: Basic face for the frame border under X.
 Defined in `faces.el'.

          Family: unspecified
           Width: unspecified
          Height: unspecified
          Weight: unspecified
           Slant: unspecified
      Foreground: unspecified
      Background: black
       Underline: unspecified
        Overline: unspecified
  Strike-through: unspecified
             Box: unspecified
         Inverse: unspecified
         Stipple: unspecified
 Font or fontset: unspecified
         Inherit: unspecified

This is the same as what you see in Customize, and, yes, the text "sample"
here would be blacked out because the face has a black background, by
default. This help is supplied on the fly - completion continues as before.
And even without asking for help, whenever `border' is the current candidate
(e.g. by cycling) `border' appears in the minibuffer, without its face.

I'd say we shouldn't throw out the baby with the bathwater on this (he said,
hazarding comments about which is which) - the gain of showing faces far
outweighs the loss. It is a zillion times easier and quicker to pick a face
name among a long list of possibly similar names by looking for the face
appearance also, not just the name. Likewise for colors and color names. See
the effect of both here:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Text_Properties_in_Completio
ns.

The faces screenshot on that page shows the problem you mention for
`border', BTW (but not for `cursor', because I don't use the default black
background for it). It also demonstrates what you said about some faces
being difficult to read (e.g. light color against a light *Completions*
background). It is a representative screenshot, I think, so people can get a
good idea of both (-) the importance of the problem and (+) the value of
WYSIWYG.

For any given user color scheme and background mode, the vast majority of
faces will be quite readable on the user's *Completions* background -
otherwise, they would not be part of the scheme. What I mean is that if a
user uses a dark background, for instance, then it is likely that most of
the faces will be readable against a dark background. Of course, "most" is
not "all", and I do see your point. I suggest adding a user option and a
toggle for it in the minibuffer completion maps.

FWIW - I haven't (yet) added such an option and toggle to Icicles. I use
face-name completion all the time and I've never noticed a need for it, but
I do think it is a good thing to add. The toggle key-binding could be added
permanently or added only temporarily from the code of `read-face-name'
itself (and removed afterward). Likewise for `icicle-read-color' - a single
option and toggle command would be used for all such WYSIWYG *Completions*
displays.

BTW - Fonts are another candidate for this type of treatment. It is standard
on Windows, at least, to show font names in menus in their own fonts.
Likewise, for most publishing applications. It really makes choosing a font
much, much easier. Think too of `xselfont'.

> >     4. My `completion-setup-function' and `display-completion-list'
> >     - see what I wrote before (about fitting the *Completions*
> >     window to the buffer etc.). This would mean modifying the
> >     definitions of `completion-setup-function' and
> >     `display-completion-list' in ways that I think would be
> >     good anyway. For instance, my `display-completion-list' does
> >     not remove text properties from candidates, and it adjusts
> >     the number of displayed columns and their widths.
> >     I personally would prefer to see `display-completion-list' be a Lisp
> >     function, but I will survive without that. My enhancements to it are
> >     independent of the rest of Icicles, but they do matter to
> >     the Icicles
> >     experience ;-).
> >
> > I am not sure what that previous text that refers to, but someone can
> > look at these changes and think about installing them.  Would someone
> > please do?
>
> Do you mean rewriting `display-completion-list' in Lisp?

I have done that (and included the enhancements mentioned). See
icicles-fn.el for the code.

Re: propose adding Icicles to Emacs

[Juri Linkov]

> I find it _very_ helpful. What you say is true for only a few corner cases,
> in general. A WYSIWYG show/no-show option that could be toggled from the
> minibuffer during completion could easily deal with that.
>
> FWIW, with Icicles there is really no great problem, because you can easily
> get help on any candidate or just show its name in the minibuffer.

The command icicle-next-apropos-candidate-action <C-next> copies the face
name from the *Completions* window to the minibuffer with all its text
properties, so such faces as `border' are still unreadable in the
minibuffer.  A bug?

Also there is another bug (I can't believe it's by design): after typing
<C-next> the face description in the *Help* window goes out of sync with
the face name highlighted in the *Completions* window and displayed in the
minibuffer (e.g. when the current selected completion is `bold-italic',
the *Help* window displays the description of the previous face `bold').

> This is the same as what you see in Customize, and, yes, the text "sample"
> here would be blacked out because the face has a black background, by
> default.

This is the main difference: in Customize, the face name is displayed in
normal face, it's only the text "sample" that is displayed in the same
face it demontrates.  Have you tried to put faces only on part of face
names in the *Completions* window, or put them on the an additional
1-character overlay beside of every face name (that serves the same role
as the text "sample" but is much shorter)?

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

RE: propose adding Icicles to Emacs

[Drew Adams]

> > FWIW, with Icicles there is really no great problem, because
> > you can easily get help on any candidate or just show its name
> > in the minibuffer.
>
> The command icicle-next-apropos-candidate-action <C-next> copies the face
> name from the *Completions* window to the minibuffer with all its text
> properties, so such faces as `border' are still unreadable in the
> minibuffer.  A bug?

Not a bug; it was intended. But you're right about that behavior; I was
mistaken.
What I said about help is true though.

FWIW, I've just added a user option for WYSIWYG display in *Completions* and
a toggle for the option (bound in the minibuffer). I have not yet uploaded
it to the wiki.

> Also there is another bug (I can't believe it's by design): after typing
> <C-next> the face description in the *Help* window goes out of sync with
> the face name highlighted in the *Completions* window and displayed in the
> minibuffer (e.g. when the current selected completion is `bold-italic',
> the *Help* window displays the description of the previous face `bold').

No, this is the normal behavior of `C-next'. When you hit `C-next', it acts
on the _current_ completion candidate and _then_ moves to the next one (so
you can then act on it, in turn). `C-next' is thus a shortcut for `C-RET'
(act on the current candidate) followed by `next' (make the next candidate
current).

The current completion candidate is shown in the minibuffer and highlighted
in *Completions*. It is the candidate that help (or any other action) _will_
act on. When candidate `foo' is current, `C-RET' or `C-next' will act on it.

Thus, if you use `C-RET' when face-name `bold' is current, you will see help
on that face (`bold') displayed in *Help*. If you instead use `C-next', then
you still see help about `bold' displayed in *Help*, but the next candidate,
`bold-italic' becomes current (it is highlighted in *Completions* and
becomes your input in the minibuffer, so you can choose it with RET).

This is consistent and not at all confusing, once you've used it a bit, but
it might take some getting used to. `C-next' acts exactly like `next' in
this respect; in fact, it is `C-RET' + `next'.

FWIW - Originally, I had `C-next' as an abbreviation for `next' followed by
`C-RET', instead of the reverse. I changed it because I think it is more
user-friendly to always act on the current candidate - that is, the one that
highlighted. With the reverse order, you act, in effect, on the next
candidate, not the current candidate, so what you see as a candidate for
action is not what you will act on.

So, yes, this is by design, and I in fact tried the reverse design for a
long time before switching to this one.

> > This is the same as what you see in Customize, and, yes, the
> > text "sample" here would be blacked out because the face has
> > a black background, by default.
>
> This is the main difference: in Customize, the face name is displayed in
> normal face, it's only the text "sample" that is displayed in the same
> face it demontrates.

Correct. And that is exactly what you see in Icicles *Help* also: the face
name is not propertized; only "sample" shows the face. I just call
`describe-face'.

> Have you tried to put faces only on part of face names in the
> *Completions* window, or put them on the an additional
> 1-character overlay beside of every face name (that serves the same role
> as the text "sample" but is much shorter)?

I have not, but it could very easily be done. I personally don't think it's
worth it, but it's certainly worth trying out.

FWIW, I do something similar to what you suggest for color names: I
(optionally) show both the color name, without WYSIWYG coloring and its RGB
code, with coloring.

Yes, then it can become difficult to read the RGB code in some corner cases.
It's always the case that if you combine any information with a color sample
then there is a risk that that information will be imperceptible in some
cases.

I don't think this is a biggee, personally, but I have added a user option
and its toggle for this (I'll upload it as soon as I stop answering email!),
so users can choose the behavior they like.

We can design things like `read-face-name' and `icicle-read-color' any way
we like; there are lots of possibilities. For `icicle-read-color', for
instance, which is also a command, I let you use a prefix arg with different
values for different behaviors - different return values and different
*Completions* displays. If you use plain `C-u', for instance, then no colors
or RGB values are shown in *Completions* - just the color names.

Similarly, if we think it's useful and worth it, we can let `read-face-name
accept an additional argument that specifies how to display candidates -
possibly to be overridden by a user option such as the one I've added.

Re: propose adding Icicles to Emacs

[Juri Linkov]

>> Also there is another bug (I can't believe it's by design): after typing
>> <C-next> the face description in the *Help* window goes out of sync with
>> the face name highlighted in the *Completions* window and displayed in the
>> minibuffer (e.g. when the current selected completion is `bold-italic',
>> the *Help* window displays the description of the previous face `bold').
>
> No, this is the normal behavior of `C-next'. When you hit `C-next', it acts
> on the _current_ completion candidate and _then_ moves to the next one (so
> you can then act on it, in turn). `C-next' is thus a shortcut for `C-RET'
> (act on the current candidate) followed by `next' (make the next candidate
> current).

When I type `C-next' I expect it acting on the _next_ completion candidate
(`next' + `C-RET').  When I want it acting on the _current_ completion candidate,
I can simply type `C-RET'.

It is a pity that you changed your original design.  Displaying the result
of action applied to the previous completion candidate with the name of
the next completion candidate highlighted in the *Completions* window is
as confusing as for instance if you typed `next-error' and see the previous
match in the source buffer with the next match highlighted in the
grep/compilation buffer.

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

RE: propose adding Icicles to Emacs

[Drew Adams]

> >> Also there is another bug (I can't believe it's by design):
> >> after typing <C-next> the face description in the *Help* window
> >> goes out of sync with the face name highlighted in the
> >> *Completions* window and displayed in the minibuffer (e.g.
> >> when the current selected completion is `bold-italic',
> >> the *Help* window displays the description of the previous
> >> face `bold').
> >
> > No, this is the normal behavior of `C-next'. When you hit
> > `C-next', it acts on the _current_ completion candidate and
> > _then_ moves to the next one (so you can then act on it, in
> > turn). `C-next' is thus a shortcut for `C-RET'
> > (act on the current candidate) followed by `next' (make the
> > next candidate current).
>
> When I type `C-next' I expect it acting on the _next_ completion candidate
> (`next' + `C-RET').  When I want it acting on the _current_
> completion candidate, I can simply type `C-RET'.

Well, what can I say? That's what you expect and that's not what you get. We
disagree. Like I said, I first implemented it the way you think you would
prefer it, I corrected that design a long time afterward, and even though I
was already used to the previous behavior I preferred the new behavior - and
I still do.

> It is a pity that you changed your original design.  Displaying the result
> of action applied to the previous completion candidate with the name of
> the next completion candidate highlighted in the *Completions* window is
> as confusing as for instance if you typed `next-error' and see
> the previous match in the source buffer with the next match highlighted
> in the grep/compilation buffer.

This is not `next-error'.

The current candidate for action (including help display) is not only
highlighted in *Completions* but also inserted in the minibuffer so that you
can edit it or accept it as is. That is, you hit RET or C-RET to act on the
current candidate, which is in the minibuffer.

What should be in the minibuffer after you do that? My answer: the next
available candidate, so that you can act on it, in turn (whether with
`C-RET', `RET', or `C-next'). You should not see, in the minibuffer or
highlighted in *Completions*, the candidate that you already acted on. The
minibuffer input after you act on a candidate has to be a different
candidate, if you are to be able to act on successive candidates. What you
see in the minibuffer should again, per standard Emacs behavior, be what
will be acted on if you hit RET (or C-RET).

This, however, does not dictate what `C-next' should do. I say it should
perform the defined action on the current candidate and then prepare the
next candidate for possible action. You say that it should do nothing to the
current candidate and should act directly on the next candidate. It could be
designed either way.

For me, the text that appears in the minibuffer as input should be the
target of any user action. For you, `C-next' should perform an action on
text that is not yet in the minibuffer, and it should show that text in the
minibuffer after the action. With my approach, `C-next' followed by `C-RET'
or `RET' acts on two successive candidates. For you, it acts twice on the
same candidate. Likewise, for `C-prior'. But either approach can be
supported.

With the behavior you propose, a user thinks of `C-next' as not acting on
the current candidate but as acting on the next candidate. OK. I prefer to
think of all actions, `C-RET', `C-next', `C-prior', `C-up', `C-down', as
acting on the same, current candidate. I think this simplifies the user's
mental model a bit. It simplifies thinking about actions, just as it
simplifies talking about them (e.g. doc).

But I can't argue that the behavior you want doesn't also correspond to a
coherent user model.

It is logical to expect to see the result of acting on a candidate only
after choosing that candidate. For me, the candidate that is ripe for
choosing with the keyboard is the one that is (a) highlighted in
*Completions* and (b) present in the minibuffer as your default input.
Choosing it acts on it, and you then see the result.

You would respond that you don't disagree with most of that (display the
result after choosing what to act on), but you think it is logical to
sometimes choose (act on) a candidate that is not the one in the minibuffer.

I cannot convince you, but I'd suggest that you not focalize only on
candidate help, where the action is displaying help on the current
candidate. "Act on" can mean anything, depending on the context, and I think
in most contexts the current behavior is preferable.

Anyway, we can go 'round the barn multiple times about this, without really
getting anywhere. I think it's time to agree to disagree. If you as an
Icicles user want to define your own command and bind it in place of
`icicle-next-apropos-candidate-action' to `C-next', it is trivial to do so.
Here is the complete definition:

(defun icicle-next-apropos-candidate-action (&optional nth)
  "`icicle-candidate-action', then `icicle-next-apropos-candidate'.
Optional argument NTH is as for `icicle-next-apropos-candidate'."
  (interactive)
  (when (interactive-p) (icicle-barf-if-outside-minibuffer))
  (icicle-successive-action #'icicle-next-apropos-candidate
                            #'icicle-candidate-action
                            nth))

So your definition would be this:

(defun JURI-next-apropos-candidate-action (&optional nth)
  "`icicle-next-apropos-candidate', then `icicle-candidate-action'.
Optional argument NTH is as for `icicle-next-apropos-candidate'."
  (interactive)
  (when (interactive-p) (icicle-barf-if-outside-minibuffer))
  (icicle-successive-action #'icicle-candidate-action
                            #'icicle-next-apropos-candidate
                            nth))

I have nothing fundamentally against such an approach; I just don't agree
that it is generally preferable. What we can do is ask people to try the
current approach for a while, and then revisit the question after that
trial. It is trivial to flip the behavior if we decide to change it.

I think I mentioned that I in fact employ the approach you prefer for the
particular case of `icicle-search', because the use case is somewhat
different. The *Help* display is a bit similar to search, so I cannot say
that you are 100% wrong about it: if help display were all that `C-next' is
about, you might convince me. But help is available all of the time, as a
secondary action, when the primary action is something else. And for that
primary action, at least, I think it is clearer if the user's simple mental
model of "do something to act on the current candidate" is reinforced by
`C-next', so that a user can think of `C-next' as an atomic action on the
current candidate, just as for `C-RET' and `RET'.

Re: propose adding Icicles to Emacs

[Juri Linkov]

> The current candidate for action (including help display) is not only
> highlighted in *Completions* but also inserted in the minibuffer so that you
> can edit it or accept it as is. That is, you hit RET or C-RET to act on the
> current candidate, which is in the minibuffer.

When I browse completion candidates using <C-next> and <C-prev>, I look
not at their names in the minibuffer or in *Completions* window, but at
the output window of the action performed on them (displaying help for
a function/variable/face, or a file).  The mismatch between the window
that displays the result of action on the completion candidate (which
often contains the name of the completion candidate) and the name of the
completion candidate highlighted in the *Completions* window and in the
minibuffer is not only confusing but also *dangerous*.  It might lead to
deleting (with S-DEL) a wrong item (including a wrong file).  I don't want
to lose a file through misleading UI.

> I cannot convince you, but I'd suggest that you not focalize only on
> candidate help, where the action is displaying help on the current
> candidate. "Act on" can mean anything, depending on the context, and I think
> in most contexts the current behavior is preferable.

You could try to separate displaying help and performing other actions
to different keys.

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

RE: propose adding Icicles to Emacs

[Drew Adams]

> When I browse completion candidates using <C-next> and <C-prev>, I look
> not at their names in the minibuffer or in *Completions* window, but at
> the output window of the action performed on them (displaying help for
> a function/variable/face, or a file).

It depends on the action, doesn't it? In the case of browsing help, you are
right about eye focus, but only if you ask for help on each candidate in
succession. Even for help browsing, it is often the case that you do not
check the help of every candidate in the matching set. Rather, you check
candidates of interest, which might involve a sequence of several in a row
(`C-M-next') but which also might involve skipping some that you are not
interested in. You might use `next' to skip those, or just use `C-M-mouse-2'
to ask for help on specific candidates you click.

So, even in the case of help display, I don't agree that one's attention
when browsing is always on the *Help* buffer instead of *Completions*. It
all depends how you use it. Yes, if you just cycle through everything with
`C-M-next', without checking *Completions* to see what you want help on,
then your eye remains fixed on *Help*.

> The mismatch between the window
> that displays the result of action on the completion candidate (which
> often contains the name of the completion candidate)

Again, it depends on what the action is. You are focalizing on help
browsing, and, yes, the candidate name appears in *Help*. That is not
generally the case.

> and the name of the
> completion candidate highlighted in the *Completions* window and in the
> minibuffer is not only confusing but also *dangerous*.  It might lead to
> deleting (with S-DEL) a wrong item (including a wrong file).  I don't want
> to lose a file through misleading UI.

Yes, there is some risk associated with `S-delete' (not `S-DEL', BTW), and
with `C-!' (act on all candidates) also. This is the case regardless of the
behavior of `C-next', but I do see your point about eye-focus on *Help*
followed by `S-delete'. Perhaps `S-delete' and `C-!' should be disabled by
default (a la novice bindings), or perhaps you should need to confirm their
application. I don't have a strong opinion about that.

I've heard your preference and reasoning. I've agreed that I too felt, at
first, that what you prefer was appropriate (I started by adding only help -
no actions, so I too was focalized on help at the time). So far, no other
Icicles user has expressed a similar preference, however. (And no one has
complained about the risk of `S-delete'.) But I'll be the first to say that
lack of user complaint does not prove user acceptance or good design.

I proposed that people experiment with the current bindings, and then we can
discuss it. I'm open on this question, but I won't change it based only on
your preference after only a little use. We could also consider having a
user option for this, if opinions end up being evenly divided. So far, we
have only two voices, and you have played with it for only a short time, and
perhaps mainly with the candidate help. For now, you can easily flip the
behavior to get what you want (using the code I sent). Experiment with that
for a while to see if you prefer it in all contexts.

Again, the main reason I prefer the current behavior is so that the target
of the next action, whatever it might be, is the candidate that is
highlighted, which is also the candidate in the minibuffer. This makes it
_easy to see what you will act on_, which is, as you point out, especially
important if you use `S-delete' to delete the object associated with the
current candidate.

Also, I'm speaking only for Icicles and my Icicles development. Richard has
something else in mind for vanilla Emacs, IIUC. Who knows what Icicles
features he will want to add or adapt for Emacs, or what his choices for
this kind of cycling behavior will be?

> > I cannot convince you, but I'd suggest that you not focalize only on
> > candidate help, where the action is displaying help on the current
> > candidate. "Act on" can mean anything, depending on the
> > context, and I think in most contexts the current behavior is
preferable.
>
> You could try to separate displaying help and performing other actions
> to different keys.

Help is already on different keys: `C-M-next', `C-down', `C-M-RET' and
`C-M-mouse-2' for help. For actions, there is no Meta: just `C-next', etc.

It is true that I also let the non-Meta bindings default to help display
when there is no specific action defined for a given command. That's a
convenience, but it could be removed if it leads to confusion. The doc does
not teach you (I hope) to get in the habit of using `C-next' to obtain help.
If it does, then I need to fix that.

To be clear, there are three sets of bindings, for three possible actions on
the current completion candidate (which is highlighted):

1. Main action: `C-RET', `C-mouse-2', `C-next', `C-down'

2. Alternative action: `C-S-RET', `C-S-mouse-2', `C-S-next', `C-S-down'

3. Help action (help on candidate): `C-M-RET', `C-M-mouse-2', `C-M-next',
`C-M-down'

There is also the standard action of final choice (`RET', `mouse-2') and the
operation of cycling without acting (`next', `down'). There is a single
binding for the object deletion action: `S-delete'. There are also bindings
for removing the current candidate from the list, `delete' and `S-mouse-2',
and for saving it for later action, `insert'.

Re: propose adding Icicles to Emacs

[Stefan Monnier]

>> Do you mean rewriting `display-completion-list' in Lisp?
> I have done that (and included the enhancements mentioned). See
> icicles-fn.el for the code.

For what it's worth, there's code in pcvs-util.el which does something that
sounds related (cvs-insert-strings).  At least I also use it in my own
completion code where I've indeed reimplemented display-completion-list in
Elisp.


        Stefan

Re: propose adding Icicles to Emacs

[Richard Stallman]

Stefan, how about installing your new display-completion-list in the trunk?

Re: propose adding Icicles to Emacs

[Stefan Monnier]

> Stefan, how about installing your new display-completion-list in the trunk?

OK, I'll try and come up with a clean patch for it,


        Stefan

Re: propose adding Icicles to Emacs

[Stefan Monnier]

> Stefan, how about installing your new display-completion-list in the trunk?

It turns out it's a bit inconvenient to do: the function is called from
Fminibuffer_completion_help which is itself called from various other
C completion functions, ...

It works for me because I have rewritten all of the completion code in
Elisp, but doing it piecewise seems difficult.


        Stefan

RE: propose adding Icicles to Emacs

[Drew Adams]

> > Stefan, how about installing your new display-completion-list
> > in the trunk?
>
> It turns out it's a bit inconvenient to do: the function is called from
> Fminibuffer_completion_help which is itself called from various other
> C completion functions, ...
>
> It works for me because I have rewritten all of the completion code in
> Elisp, but doing it piecewise seems difficult.

FWIW -

I too redefined `display-completion-list' in Lisp, and I don't see a
problem. I generally didn't redefine other stuff defined in C - my code
eventually calls those standard functions. I don't, however, use
`minibuffer-completion-help' at all. What were the other places that were
problematic?

I don't doubt what you're saying - I'm just wondering if what I coded might
help. My definition of `display-completion-list' is in `icicles-fn.el', in
case it helps. You can easily spot and ignore the Icicles-specific
enhancements. Ignore altogether if this doesn't help.

A priori, if the problem is in the C callers to `display-completion-list',
then a different definition of that function wouldn't help. But I'm curious,
because I don't notice the problem you mention.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    It works for me because I have rewritten all of the completion code in
    Elisp, but doing it piecewise seems difficult.

Moving all the completion code into Lisp could be a good idea.
Speed is mostly not crucial there.

How much of a slowdown does this cause for try-completions?
Would this be unpleasant on slow computers?

Re: propose adding Icicles to Emacs

[Stefan Monnier]

>     It works for me because I have rewritten all of the completion code in
>     Elisp, but doing it piecewise seems difficult.

> Moving all the completion code into Lisp could be a good idea.
> Speed is mostly not crucial there.

> How much of a slowdown does this cause for try-completions?
> Would this be unpleasant on slow computers?

Oh, no, all-completions and try-completions are still in C.  I don't think
it's a good idea to move them to elisp for now.
But the rest can be moved just fine: it's not speed critical.


        Stefan

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Oh, no, all-completions and try-completions are still in C.  I don't think
    it's a good idea to move them to elisp for now.
    But the rest can be moved just fine: it's not speed critical.

I agree.  So how about installing all of this change
in the trunk?

Re: propose adding Icicles to Emacs

[Richard Stallman]

    > Not a good idea in fact.  Face completions displayed in different faces
    > are hardly readable, and some of them which have black foreground on black
    > background (e.g. cursor, mouse, border) are not readable at all.

    I find it _very_ helpful. What you say is true for only a few corner cases,
    in general.

The current code handles all cases acceptably.  It sounds like your
method is better in most cases, but much worse in a few cases.
As it is, we cannot use it.

    For
    instance, even if you can't read its name in *Completions*, and you can't
    guess what it is by its position in the alphabetized list,...

It is not acceptable for that to happen.

However, maybe someone can turn your feature into a good one by adding
a special case check for the cases that look bad with your code, and
treat them differently.  The result could be a feature that is always
acceptable, while still having the same benefits in the usual case.
That would be something we could install.

Re: propose adding Icicles to Emacs

[Stefan Monnier]

>     I find it _very_ helpful. What you say is true for only a few corner
>     cases, in general.

> The current code handles all cases acceptably.  It sounds like your
> method is better in most cases, but much worse in a few cases.
> As it is, we cannot use it.

Most like we'd want the list of faces to take the form of a list of
face-names (displayed with the default face) together with a constant text
(such as "sample") where that constant text is displayed with the face.


        Stefan

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Most like we'd want the list of faces to take the form of a list of
    face-names (displayed with the default face) together with a constant text
    (such as "sample") where that constant text is displayed with the face.

That is what Custom does now; but it is perhaps not the best thing.
What I have in mind is a hybrid approach (both for completion and for
Custom).

If the face is hard for reading text, do as you described above.
Otherwise, use the face itself to display its name.

What do you think?

RE: propose adding Icicles to Emacs

[Drew Adams]

>     Most like we'd want the list of faces to take the form of a list of
>     face-names (displayed with the default face) together with a
>     constant text (such as "sample") where that constant text is
>     displayed with the face.
>
> That is what Custom does now; but it is perhaps not the best thing.
> What I have in mind is a hybrid approach (both for completion and for
> Custom).
>
> If the face is hard for reading text, do as you described above.
> Otherwise, use the face itself to display its name.

1. "hard for reading text" is too hard to define and treat well.

2. A hybrid approach of having some names with separate swatches and some
names facified, without swatches, would be confusing.

Let the user decide which representation to use. See my previous mail on
this.

Re: propose adding Icicles to Emacs

[Stefan Monnier]

> If the face is hard for reading text,

This is terribly difficult to determine (other than by asking the user).

> do as you described above.
> Otherwise, use the face itself to display its name.

As a user, I'm not sure I'd like a scheme which occasionally switches
between two different representations, with no obvious justification for it.


        Stefan

RE: propose adding Icicles to Emacs

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 3359 bytes --]

> >     I find it _very_ helpful. What you say is true for only a few corner
> >     cases, in general.
>
> > The current code handles all cases acceptably.  It sounds like your
> > method is better in most cases, but much worse in a few cases.
> > As it is, we cannot use it.
>
> Most like we'd want the list of faces to take the form of a list of
> face-names (displayed with the default face) together with a constant text
> (such as "sample") where that constant text is displayed with the face.

OK, here is what I've done, for Icicles (see attached screenshots) -

(defcustom icicle-WYSIWYG-Completions-flag 4
  "*Non-nil means to show candidates in *Completions* using WYSIWYG.
This means, for instance, showing face names using their own faces."
  :type '(choice
          (integer :tag "Show candidate plus a WYSIWYG swatch of \
                         width..." :value 4)
          (const   :tag "Show candidate itself using WYSIWYG" t)
          (const   :tag "Show candidate as is, with no text \
                         properties" nil))
  :group 'Icicles-Completions-Display)

By default, `read-face-name' shows the face name without a face, followed by
a small swatch in the face - per Stefan's suggestion. By customizing
`icicle-WYSIWYG-Completions-flag', you can alternatively remove the color
swatch (no WYSIWYG display) or show the face name itself using the face,
instead.

Here is the new definition of `icicle-make-face-candidate', which formats
the face-name candidates:

(defun icicle-make-face-candidate (face)
  "Return a completion candidate for FACE."
  (if (wholenump icicle-WYSIWYG-Completions-flag)
      (let ((swatch (make-string icicle-WYSIWYG-Completions-flag ?M)))
        (put-text-property 0 icicle-WYSIWYG-Completions-flag
                           'face face swatch)
        (list (list (symbol-name face) swatch)))
    (let ((face-name (copy-sequence (symbol-name face))))
      (when icicle-WYSIWYG-Completions-flag
        (put-text-property 0 (length face-name) 'face face face-name))
      (list face-name))))

FWIW, I think the `read-face-name' code for Emacs 22 is a bit of a mess. It
takes an optional MULTIPLE argument, but this option is not treated as a
separate case. Instead, all of the code acts as if MULTIPLE were non-nil,
and then things that are not needed are ignored or stripped away. I've
cleaned this up a bit in the Icicles version.

Note: Icicles makes no special use of the MULTIPLE case. In particular, no
WYSIWYG treatment is done when MULTIPLE is provided. This is partly because
I don't have the time or will to wade through the crm.el code and try to
figure out how Icicles might deal with trying to redefine
`completing-read-multiple' to take advantage of Icicles multi-completions.
Icicles doesn't need this, and, if Icicles-like behavior is added to Emacs
one day, it is unclear how and whether Richard will want to do that.

In the Icicles definition of `read-face-name' for Emacs 22, all I've done,
besides cleaning up the treatment of MULTIPLE a bit (which has nothing to do
with Icicles and should be done anyway, IMO), is (1) add Icicles bindings
for multi-completion treatment and (2) use `icicle-make-face-candidate' to
create the candidates. These are trivial changes. The rest is the same
(ugly) code. The code is here:
http://www.emacswiki.org/cgi-bin/wiki/icicles-fn.el.


[-- Attachment #2: read-face-name-swatch-4.png --]
[-- Type: image/png, Size: 32069 bytes --]

[-- Attachment #3: read-face-name-whole-face.png --]
[-- Type: image/png, Size: 41308 bytes --]

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

RE: propose adding Icicles to Emacs

[Drew Adams]

I said:

> (defcustom icicle-WYSIWYG-Completions-flag 4
>   "*Non-nil means to show candidates in *Completions* using WYSIWYG.
> This means, for instance, showing face names using their own faces."
...

Strike that last sentence. I forgot to remove it.

Re: propose adding Icicles to Emacs

[Juri Linkov]

> By default, `read-face-name' shows the face name without a face, followed by
> a small swatch in the face - per Stefan's suggestion. By customizing
> `icicle-WYSIWYG-Completions-flag', you can alternatively remove the color
> swatch (no WYSIWYG display) or show the face name itself using the face,
> instead.

Entia non sunt multiplicanda.  Instead of inventing a dozen of new
representations of face samples, it would be better to use the format
familiar to users from using the command `list-faces-display':

  Use <mouse-2> or M-x help-follow on a face name to customize it
  or on its sample text for a description of the face.

  bold                abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
  bold-italic         abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
  border              abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
  buffer-menu-buffer  abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ

The face list in this format could be inserted into the *Completions* buffer
and selecting a face name will use it as the completion instead of going
to the Customization buffer.

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

RE: propose adding Icicles to Emacs

[Drew Adams]

> > By default, `read-face-name' shows the face name without a
> > face, followed by a small swatch in the face - per Stefan's
> > suggestion. By customizing `icicle-WYSIWYG-Completions-flag',
> > you can alternatively remove the color swatch (no WYSIWYG
> > display) or show the face name itself using the face, instead.
>
> Entia non sunt multiplicanda.  Instead of inventing a dozen of new
> representations of face samples, it would be better to use the format
> familiar to users from using the command `list-faces-display':
>
>   Use <mouse-2> or M-x help-follow on a face name to customize it
>   or on its sample text for a description of the face.
>
>   bold abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
>   bold-italic abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
...
> The face list in this format could be inserted into the
> *Completions* buffer and selecting a face name will use it as
> the completion instead of going to the Customization buffer.

You don't really propose putting all of that stuff in *Completions*, do you?

When it comes to display of color and such, people have very different needs
and preferences. Of the two screenshots I sent, I prefer the one with the
face on the entire face name; some other users might prefer the one with the
swatch; still others will prefer to see just the names, with no WYSIWYG
indication.

Allowing for different user preferences in a reasonable way is not violating
Occam's razor. We can discuss whether "a dozen of new representations of
face samples" is needed, or whether a few (as I proposed) suffices. That is,
we can discuss what constitutes "unnecessary multiplication of things" in
this particular case.

It is violating Occam's razor to multiply things unnecessarily in
*Completions*, under the arguments of (a) code reuse or (b) user
familiarity. The swatch screenshot I sent provides everything that the
`list-faces-display' provides, without all of the unnecessary clutter, and
it lets users control the size of the swatch.

Re: propose adding Icicles to Emacs

[Stefan Monnier]

> Entia non sunt multiplicanda.  Instead of inventing a dozen of new
> representations of face samples, it would be better to use the format
> familiar to users from using the command `list-faces-display':

Yup, makes perfect sense,


        Stefan

RE: propose adding Icicles to Emacs

[Drew Adams]

> > Entia non sunt multiplicanda.  Instead of inventing a dozen of new
> > representations of face samples, it would be better to use the format
> > familiar to users from using the command `list-faces-display':
>
> Yup, makes perfect sense,

In emacs -Q, there are 63 faces. In my emacs, when I bring it up, there are
280 faces. YMMV.

Adding a face swatch that is 53 characters wide to each completion candidate
means a lot of unnecessary clutter for *Completions*. It adds nothing for
the user in this context to repeat the alphabet twice, even if
`list-faces-display' is "familiar".

Entia non sunt multiplicanda, indeed.

Re: propose adding Icicles to Emacs

[Juri Linkov]

>> > Entia non sunt multiplicanda.  Instead of inventing a dozen of new
>> > representations of face samples, it would be better to use the format
>> > familiar to users from using the command `list-faces-display':
>>
>> Yup, makes perfect sense,
>
> In emacs -Q, there are 63 faces. In my emacs, when I bring it up, there are
> 280 faces. YMMV.

I have 329 faces now and would like to see them in the format identical to
the format of `list-faces-display' in the *Completions* buffer.  I see
no problem with that.

> Adding a face swatch that is 53 characters wide to each completion candidate
> means a lot of unnecessary clutter for *Completions*. It adds nothing for
> the user in this context to repeat the alphabet twice, even if
> `list-faces-display' is "familiar".

Exactly for the same reason you can complain about clutter in the output of
`list-faces-display'.

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

Re: propose adding Icicles to Emacs

[Juanma Barranquero]

On 6/20/07, Juri Linkov <juri@jurta.org> wrote:

> > Adding a face swatch that is 53 characters wide to each completion candidate
> > means a lot of unnecessary clutter for *Completions*. It adds nothing for
> > the user in this context to repeat the alphabet twice, even if
> > `list-faces-display' is "familiar".
>
> Exactly for the same reason you can complain about clutter in the output of
> `list-faces-display'.

I must be missing something obvious. Can't the user set
`list-faces-sample-text'? If 53 chars is too long for her in
*Completions*, I'd bet it'll be too in the output of
`list-faces-display'.

             Juanma

RE: propose adding Icicles to Emacs

[Drew Adams]

> I have 329 faces now and would like to see them in the format identical to
> the format of `list-faces-display' in the *Completions* buffer.  I see
> no problem with that.
>
> > Adding a face swatch that is 53 characters wide to each
> > completion candidate means a lot of unnecessary clutter for
> > *Completions*. It adds nothing for the user in this context
> > to repeat the alphabet twice, even if `list-faces-display'
> > is "familiar".
>
> Exactly for the same reason you can complain about clutter in the
> output of `list-faces-display'.

The contexts are not identical - the use of those buffers is different. You
choose a face in *Completions* for any number of reasons. Likewise, you can
use `list-faces-display' in different ways. The reasons for using the two
are not the same, though there can be some overlap.

Space in *Completions* is limited. I want to see as many face names as
possible in that relatively small space. *Completions* is about quick
interactivity - much more so than is `list-faces-display'. You are picking a
face name in *Completions*; it is the name that is most important.

Anyway, I agree that you can also make the argument that there might not be
a need to show two whole alphabets for each face in `list-faces-display'
either. This is under the control of a variable, `list-faces-sample-text',
but that variable is not currently a user option - perhaps it should be.

Presumably, the idea behind the long default value of
`list-faces-sample-text' is the same as that used to display fonts for
choosing: show what a representative sample of characters look like. This is
important for fonts (hence also for faces) because different characters look
different in different fonts. That is, some characters might look very
similar whereas other characters look very different. To see the difference
between two fonts or faces, you sometimes need to look at a lot of
characters.

This reason for showing complete alphabets can also be a reason for showing
other than just the latin alphabet. Font samples typically include digits,
for instance (in MS Windows, they show digits and only a few letters). Some
users might want to see different alphabets, for instance. Perhaps
`list-faces-sample-text' should be a defcustom, for this reason.

The use of face names as candidates in *Completions* is not identical to the
use of `list-faces-display'. One way to let users configure this difference
would be to use a separate option for the swatch display in *Completions
(the default value would not be 53 chars long, IMO). Icicles currently only
lets you change the swatch length, but it might be good to let you specify
the swatch text instead (a la `list-faces-sample-text').

RE: propose adding Icicles to Emacs

[Drew Adams]

> The use of face names as candidates in *Completions* is not
> identical to the use of `list-faces-display'. One way to let
> users configure this difference would be to use a separate
> option for the swatch display in *Completions (the default
> value would not be 53 chars long, IMO). Icicles currently
> only lets you change the swatch length, but it might be good
> to let you specify the swatch text instead (a la
> `list-faces-sample-text').

FWIW, I've done that. Option `icicle-WYSIWYG-Completions-flag' can now be a
string of text to use as the face sample (swatch).

(defcustom icicle-WYSIWYG-Completions-flag "MMMM"
  "*Non-nil means to show candidates in *Completions* using WYSIWYG."
  :type
  '(choice
    (string :tag "Show candidate plus a WYSIWYG swatch with text..."
            :value "MMMM")
    (const  :tag "Show candidate itself using WYSIWYG" t)
    (const  :tag "Show candidate as is, with no text properties" nil))
  :group 'Icicles-Completions-Display)

Re: propose adding Icicles to Emacs

[Juri Linkov]

> Space in *Completions* is limited. I want to see as many face names as
> possible in that relatively small space. *Completions* is about quick
> interactivity - much more so than is `list-faces-display'. You are picking a
> face name in *Completions*; it is the name that is most important.

The size of the *Completions* window is the same as the size of the *Help*
window displayed by `list-faces-display' with normal Emacs settings.

With `emacs -Q', both `M-x list-faces-display RET' and `M-x describe-face RET TAB'
display a window that occupies half of the frame.

And actually one face name per line in the output of `list-faces-display'
is more readable than two columns where names grow from left to right and
then from top to down.  In two column lists it's much easier to read at first
one column sorted top-down and then when the list continues on the second column.

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

Re: propose adding Icicles to Emacs

[Richard Stallman]

    > Entia non sunt multiplicanda.  Instead of inventing a dozen of new
    > representations of face samples, it would be better to use the format
    > familiar to users from using the command `list-faces-display':

    Yup, makes perfect sense,

As others have noted, that isn't good for the purpose
because it puts just one name on each line.

RE: propose adding Icicles to Emacs

[Drew Adams]

> The current code handles all cases acceptably.  It sounds like your
> method is better in most cases, but much worse in a few cases.
> As it is, we cannot use it.
> ...
> However, maybe someone can turn your feature into a good one by adding
> a special case check for the cases that look bad with your code, and
> treat them differently.  The result could be a feature that is always
> acceptable, while still having the same benefits in the usual case.
> That would be something we could install.

Uh, just how would you determine "the cases that look bad"? How would the
code tell whether a particular somewhat-light yellow foreground looks bad
against a not-too-dark cyan background that the user might happen to use for
*Completions*?

Or would you just treat the "simple" cases where the face foreground and
background (or nil for either) are _identical_ to the current *Completions*
foreground and background (or nil for either)? Juri's point was not only
that `border' showed black on black, but also that some face names were
difficult to read because of the particular combination with the
*Completions* foreground or background.

Trying to do what you suggest is, IMO, (1) a nightmare to try to do right
and (2) likely to be an unsuccessful compromise in any case. Not to mention
that this kind of thing depends on one's eyesight, the ambient room
lighting, monitor qualities, personal tolerances and preferences, the moon
phase, presence or absence of related fatwahs,... Users will cry out for
ways to customize this, and the result of trying to allow for that will
likely be a mess too. Sorry to be negative, but I suspect that that way lies
madness.

Stefan's suggestion of a separate swatch is much better, IMO. I've
implemented that - see my other mail on this.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Uh, just how would you determine "the cases that look bad"?

There is no "right answer", but I think it will not be terribly hard
to find a good enough answer.  The point is stop arguing about it
theoretically.  Experiment, try various conditions, and see what gives
good results.

I think it is a matter of having sufficient contrast between foreground
and background.  If that is so, the face name can be displayed in
the face itself.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    1. My `exit-minibuffer', my `minibuffer-complete-and-exit', and my
    `mouse-choose-completion' are enhanced to also remove the *Completions*
    window. I think this should also be done in Emacs. This removal deletes all
    windows anywhere that show *Completions*.

If Emacs has this bug, we will fix it.  We can wait and see if the bug
exists when we are done.  So no need to think about this now.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     1. My `exit-minibuffer', my `minibuffer-complete-and-exit', and my
>     `mouse-choose-completion' are enhanced to also remove the 
>     *Completions* window. I think this should also be done in Emacs.
>     This removal deletes all windows anywhere that show *Completions*.
> 
> If Emacs has this bug, we will fix it.  We can wait and see if the bug
> exists when we are done.  So no need to think about this now.

Understood. I was simply explaining why the code exists in Icicles.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    2. My `mouse-choose-completion' also records the number of the current
    completion candidate in a global variable. This is so that Icicles functions
    that work with the candidate number will also work when you choose a
    candidate with the mouse, not just by cycling. The candidate number is very
    important for Icicles, some functionality being dependent on it.

I don't understand what a "candidate number" is, and I think we will
have to consider this issue along with the core Icicles features.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     2. My `mouse-choose-completion' also records the number of the current
>     completion candidate in a global variable. This is so that
>     Icicles functions that work with the candidate number will also work
>     when you choose a candidate with the mouse, not just by cycling.
>     The candidate number is very important for Icicles, some functionality
>     being dependent on it.
>
> I don't understand what a "candidate number" is, and I think we will
> have to consider this issue along with the core Icicles features.

Let me explain. It's pretty important for Icicles.

The TABLE arg to `completing-read' can be an alist whose elements can be
conses whose cars are strings. The element cdrs can be anything.

You can choose a candidate in different ways in Icicles, including by
cycling to it and using RET, C-RET, or C-M-RET on the "current candidate"
during cycling. You can also choose it with `mouse-2', `C-mouse-2', or
`C-M-mouse-2' in *Completions*.

In some important cases, it is not enough to recuperate the string used in
*Completions* as the return value from `completing-read'. In those cases,
Icicles must recuperate the entire raw candidate value from the TABLE
argument - that is, it needs not only the candidate name but also its
associated alist data, that is, both the car and the cdr of the candidate
element.

One way that Icicles does this (the best way, when it is possible) is to use
the number (i.e. index) of the candidate in the TABLE arg. This index
corresponds to the order of candidates when cycling and the order of the
candidates in *Completions*.

Keep in mind that for some commands there can be different raw candidates
that have the same string name. For example, a candidate to `icicle-search'
looks like this:

 (SEARCH-HIT-STRING . HIT-END-MARKER) or
 ((SEARCH-HIT-STRING BUFFER-NAME) . HIT-END-MARKER), where

. SEARCH-HIT-STRING is the candidate "name", that is, the displayed
  candidate in *Completions*. It is a search-pattern hit.

. HIT-END-MARKER is a marker at the end of the search hit.
  It enables search to go to the hit.

. BUFFER-NAME is a string naming the buffer of the hit. It is
  propertized for *Completions*, to help distinguish hits from
  different buffers when searching across buffers.  That is,
  when multiple buffers or files are used, the candidate
  displayed in *Completions* has two parts: the search-hit
  string and the buffer name. Users can turn this display off
  with a user option, so that no BUFFER-NAME is present.

You can see that unless you cycle to define a "current completion candidate"
to choose, or you choose it with the mouse in *Completions*, just picking it
by completing its name does not necessarily uniquely identify the raw
completion candidate. If there is only one matching string, then it does,
but otherwise it does not.

So, you see that it is important for `mouse-choose-completion' to track the
candidate number, just as cycling tracks it. The need is to identify the
proper raw candidate, to be able to recuperate all of its data.

Yes, to forestall a question you might have, this could be implemented
differently if done inside Emacs itself. Working from without, it is a bit
of a workaround. Although `completing-read' lets you pass an alist as TABLE
arg, it does not give you any way to recuperate the alist element given the
chosen string, unless that string is unique. (You can use `assoc', but that
gives you just the first element that has that string.) `completing-read'
returns only the string that names the candidate, not the entire candidate
element from the alist.

Here, to give you an idea, is the code that recuperates a complete raw
candidate value, given its string part:

(defun icicle-get-alist-candidate (cand)
  "Return completion candidate (full entry) from `icicle-candidates-alist'.
CAND is the name of the candidate (a string).

If user cycled among candidates or used `mouse-2', then use the
current candidate number, and ignore CAND.

Otherwise:
  If only one candidate matches CAND, use that.
  Else raise an error telling user to use cycling or `mouse-2'."
  (and icicle-candidates-alist
       (let ((cand-entries
              (icicle-filter-alist icicle-candidates-alist
                                   icicle-completion-candidates)))
         (if (wholenump icicle-candidate-nb) ; Cycled or used `mouse-2'.
             (elt cand-entries
                  (mod icicle-candidate-nb
                       (length icicle-candidates-alist)))
           ;; If `icicle-completion-candidates' is nil, because user
           ;; didn't use `TAB' or `S-TAB', then `icicle-candidates-alist'
           ;; can contain non-matches.  So, we check for more than one
           ;; match.  However, we can't just use `assoc', because
           ;; candidates might be multi-completions (lists).
           (let ((first-match (icicle-first-matching-candidate
                               cand icicle-candidates-alist)))
             (if (and first-match
                      (not (icicle-first-matching-candidate
                            cand
                            (setq cand-entries
                                  (delete first-match cand-entries)))))
                 first-match            ; Only one match, so use it.
               (error
                "Ambiguous choice. Cycle or use `mouse-2' to choose \
unique matching candidate.")))))))

To simplify, think of `icicle-candidate-alist' as the TABLE arg to
`completing-read'.  `icicle-filter-alist' filters this alist, keeping only
those candidates that are current (i.e., whose strings are currently
displayed in *Completions*).

`icicle-first-matching-candidate' is like `assoc', but it also treats
multi-completions. Again, a multi-completion is an element of the TABLE arg
passed to `completing-read' whose car is a list of strings instead of a
string; the strings are joined together by my `completing-read' and treated
as a single candidate.

Icicles uses cycling and often makes use of multiple candidates that have
the same display appearance (same string), so the position of the string you
choose in the list of candidates is important. Another way of saying this is
that Icicles has a notion of "current candidate", which vanilla Emacs does
not.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    In some important cases, it is not enough to recuperate the string used in
    *Completions* as the return value from `completing-read'. In those cases,
    Icicles must recuperate the entire raw candidate value from the TABLE
    argument

I can see how that can be so.

    One way that Icicles does this (the best way, when it is possible) is to use
    the number (i.e. index) of the candidate in the TABLE arg. This index
    corresponds to the order of candidates when cycling and the order of the
    candidates in *Completions*.

That makes sense for a list or an alist, but how do you make that work
for an obarray or hash table?  You could scan it in a canonical order
to convert numbers to elements; is that what you do?

    To simplify, think of `icicle-candidate-alist' as the TABLE arg to
    `completing-read'.  `icicle-filter-alist' filters this alist, keeping only
    those candidates that are current (i.e., whose strings are currently
    displayed in *Completions*).

I think the right way to handle these features is to implement
those that we decide we want in minibuf.c.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    2. My `customize-apropos', `customize-apropos-faces',
    `customize-apropos-groups', `customize-apropos-options', and
    `repeat-complex-command' all use `completing-read' to read the regexp. Note
    that using completion means not only that you can use regexp matching but
    also that you can sort the candidates in different ways (important for
    cycling order).

I don't understand why it makes sense to do completion on regexps.
Would you please explain?

RE: propose adding Icicles to Emacs

[Drew Adams]

> I don't understand why it makes sense to do completion on regexps.
> Would you please explain?

This is, in my experience, the single most important (useful) feature that
Icicles has to offer. It is way out in front of any other Icicles feature or
combination of features in terms of its practical value. The benefits are
well documented in the doc I sent you (which is also on the wiki).

Two of the basic features of Icicles are (1) cycling among matching
candidates and (2) being able to match a regexp, not just a prefix. Icicles
started life with #1, but it wasn't until I added #2 that its utility took
off. #1 without #2 limits you, in effect, to working with smaller candidate
sets. Put conversely, you can make good use of even very large candidate
sets if you have regexp (or at least substring) matching. You can sort
candidates on the fly, to make cycling more efficient. You can narrow down
the set of candidates considerably, especially using multiple match patterns
("progressive completion").

My advice to new Icicles users is to not get in the bad habit of automatic,
"drone" cycling, but to instead take advantage of regexp (e.g. substring)
matching. Icicles is a different approach to completion, and regexp matching
is a large part of that. It doesn't sound like much, if you are not used to
it, and it can sound like something that would be overkill or would slow you
down, but I can honestly say that I use S-TAB (which is regexp completion)
much, much more than TAB, and I'm pretty sure that the same is true for
other Icicles users.

Please read the doc about this feature, and think about it. Here is a good
place to start:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Apropos_Completions.

But you will find that this feature (which I call "apropos completion") is
really at the heart of nearly every Icicles feature. That is, when you read
about the various features, their doc will nearly always make reference to
S-TAB, because each of the features is more useful when combined with regexp
matching.

Progressive completion (matching multiple patterns, taking the intersection
to narrow the candidate set) is a good example of a powerful feature that is
dependent on regexp, or at least substring, matching. Icicles search is
another. On-the-fly apropos (candidate help) is another. Really, there is
not a single Icicles feature I can think of that is not raised to a higher
level of utility by regexp matching.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    > I don't understand why it makes sense to do completion on regexps.
    > Would you please explain?

    This is, in my experience, the single most important (useful) feature that
    Icicles has to offer. It is way out in front of any other Icicles feature or
    combination of features in terms of its practical value. The benefits are
    well documented in the doc I sent you (which is also on the wiki).

    Two of the basic features of Icicles are (1) cycling among matching
    candidates and (2) being able to match a regexp, not just a prefix.

Are we talking about the same thing?  I am talking about this

    2. My `customize-apropos', `customize-apropos-faces',
    `customize-apropos-groups', `customize-apropos-options', and
    `repeat-complex-command' all use `completing-read' to read the regexp.

but you seem to be talking about entering a regexp
to do completion feature.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     > I don't understand why it makes sense to do completion on regexps.
>     > Would you please explain?
>
>     This is, in my experience, the single most important (useful)
>     feature that Icicles has to offer. It is way out in front of
>     any other Icicles feature or combination of features in terms
>     of its practical value. The benefits are
>     well documented in the doc I sent you (which is also on the wiki).
>
>     Two of the basic features of Icicles are (1) cycling among matching
>     candidates and (2) being able to match a regexp, not just a prefix.
>
> Are we talking about the same thing?  I am talking about this
>
>     2. My `customize-apropos', `customize-apropos-faces',
>     `customize-apropos-groups', `customize-apropos-options', and
>     `repeat-complex-command' all use `completing-read' to read the regexp.
>
> but you seem to be talking about entering a regexp
> to do completion feature.

Yes, we were not talking about the same thing - I misunderstood you; my bad.

To answer your question about `customize-*' -

Here is my definition of `customize-apropos-faces':

(defun icicle-customize-apropos-faces (regexp)
  "Customize all user faces matching REGEXP.
Use `S-TAB', [next], and [prior], to match regexp input - this lets
you see what items will be available in the customize buffer."
  (interactive
   (list (completing-read "Customize faces (regexp): "
                          obarray 'custom-facep nil nil
                          'regexp-history)))
  (customize-apropos regexp 'faces))

This means that, when prompted, you can do any of the following:

1. type a regexp and hit RET, to get customize for the matching
   faces - this is the same as what vanilla Emacs offers

2. type a regexp and hit S-TAB, to see the matching face names
   as candidates in *Completions* and then do one of the following:

 (a) change your regexp, either to narrow the choices further or
     to correct it if it didn't quite match what you expected

 (b) use `M-*' to add another match pattern, to narrow candidates
     down progressively

 (c) choose one or more candidate faces to customize, from the
     list of those that match, using `C-mouse-2' or `C-RET' or
     (finally) `RET'

3. hit TAB or S-TAB (without typing any input), to get a list of all
   faces as candidates, and then act as in 2a, 2b, or 2c

In the vanilla Emacs `customize-apropos-faces', you must provide a regexp
once and for all, with RET - there is no completion of face names available,
and no way to rectify your regexp without starting over.

This is a good example of the general advantage of regexp matching on the
fly, and the advantage of providing input by completion whenever possible.

RE: propose adding Icicles to Emacs

[Drew Adams]

> In the vanilla Emacs `customize-apropos-faces', you must provide a regexp
> once and for all, with RET - there is no completion of face names
> available, and no way to rectify your regexp without starting over.
>
> This is a good example of the general advantage of regexp matching on the
> fly, and the advantage of providing input by completion whenever possible.

I might add that once you have the ability to type and change the regexp to
match dynamically, there is less raison d'etre for these
`customize-apropos-*' commands. An Icicles user would simply use
`customize-face' and so on, instead.

Well, not really. A multi-command version of each would first need to be
defined, so that `C-RET' etc. could DTRT. With RMS's proposed
`call-interactively' tweak, this step would presumably be unnecessary.

With Icicles (without RMS's `call-interactively tweak), here is, for
example, a definition of a multi-command `customize-face':

(defun icicle-customize-face (face)
  "Customize face FACE."
  (interactive (list (let ((icicle-candidate-action-fn 'customize-face))
                       (read-face-name "Customize face: "))))
  (customize-face face))

Actually, because `customize-face' moves the frame focus to the Customize
frame, and you want to keep the focus on the minibuffer frame (which might
be a different frame) until you're done completing and acting on candidates,
this is what you really need:

(defun icicle-customize-face (face)
  "Customize face FACE."
  (interactive
   (list (let ((icicle-candidate-action-fn
                (lambda (x)
                 (customize-face x)
                 (select-frame-set-input-focus
                  (window-frame (minibuffer-window))))))
           (read-face-name "Customize face: "))))
  (customize-face face))

Also, there is the inconvenience that acting on all matching face names
would, in this case, open a separate Customize buffer for each. So, this is
not exactly equivalent to `customize-apropos-faces', and not quite as
convenient for customizing several faces.

Still, it does point out that having the ability to:

 1) type a regexp at any time to match candidates and
 2) act on any or all candidates (C-RET or C-!)

means that commands such as `(customize-)apropos-*' that ask for a regexp up
front are not quite so necessary.

Instead of entering a regexp once and for all to the prompt of such
commands, you can type the same regexp to any multi-command that acts on
such a candidate - in this case, a multi-command version of
`customize-face'.

And you can change that regexp on the fly, to correct it or to act on
different candidates. In `icicle-occur', for instance, you just start typing
a regexp and the matching lines become the search targets as you type - edit
the regexp and the search targets change (similar to `isearch-*-regexp').

An added specific advantage for `icicle-customize-face' is that, by using
`read-face-name' and `customize-face', you can see (WYSIWYG) the faces you
might choose to customize, in *Completions*. Even with the tweak to
`read-face-name' that provides this behavior generally,
`customize-apropos-faces' still shows plain face names as candidates,
because it does not use `read-face-name'.

Another advantage is of course on-the-fly help for individual faces: during
completion, `C-M-mouse-2' or `C-M-RET' on a face-name candidate shows the
face's doc string.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    I might add that once you have the ability to type and change the regexp to
    match dynamically, there is less raison d'etre for these
    `customize-apropos-*' commands. An Icicles user would simply use
    `customize-face' and so on, instead.

With `customize-apropos-faces', you get a custom buffer with ALL the
faces whose names match the regexp.

Using `customize-face' as a multi-command, and regexp-based
completion, you can pick some of the matching faces and put each of them into
a custom buffer.  But you can't make a custom buffer with two of them,
or all of them.  (Am I mistaken?)

This suggests that `customize-face', when it uses the multi-command
feature, should put all the faces in one buffer.  Well, I think that
is not too hard to do, in my proposed framework.

But this suggests there should be a minibuffer command to say "submit
each of current candidates, one by one."

RE: propose adding Icicles to Emacs

[Drew Adams]

>     I might add that once you have the ability to type and change
>     the regexp to match dynamically, there is less raison d'etre for these
>     `customize-apropos-*' commands. An Icicles user would simply use
>     `customize-face' and so on, instead.
>
> With `customize-apropos-faces', you get a custom buffer with ALL the
> faces whose names match the regexp.

Yes, I pointed that out several times as a definite advantage. I said this:

>> The only disadvantage is that you cannot use this command to
>> customize all matching faces in the same Customize buffer -
>> you get a different Customize buffer for each face. On the
>> other hand, two advantages are that (1) the
>> display of matching faces can be WYSIWYG (because it uses
>> `read-face-name') - a much better preview, and (2) you can get
>> help about individual faces while you are choosing them, in
>> case you have a doubt about the meanings (uses) of some of them.

> Using `customize-face' as a multi-command, and regexp-based
> completion, you can pick some of the matching faces and put each
> of them into a custom buffer.  But you can't make a custom buffer
> with two of them, or all of them.  (Am I mistaken?)

That is correct, assuming no changes to `customize-face'.

> This suggests that `customize-face', when it uses the multi-command
> feature, should put all the faces in one buffer. Well, I think that
> is not too hard to do, in my proposed framework.
>
> But this suggests there should be a minibuffer command to say "submit
> each of current candidates, one by one."

What do you mean, "submit"? Submit to what? Don't forget that there is
`C-S-RET' etc., which apply an alternative action. That action could be to
collect chosen candidates. IMO, it is useful to be able to have a different
final action (`RET') from the intermediate actions (`C-RET'). The final
action here could be to act on all in the same Customize buffer. The
intermediate action could be to accumulate.

As I said in a different message, Icicles has an idiom for this. There are
several multicommands that simply return a list of the candidates you
choose. Other commands use those commands (e.g. in their `interactive'
specs) to determine the user's choices, and then they act on that list as a
whole. For instance, multicommand `icicle-face-list' lets you pick a list of
faces; it returns the list. A command `customize-face-bis' could use that to
define the list of faces to customize, then show Customize for all together.

IOW, `C-RET' can be used for multiple choice, and the choices can be acted
on together, instead of individually. It all depends on how you define the
command.

Also, with the save-this-candidate and save-matching-candidates features,
you can create a set of candidates you want to act on, verify that set, and
then act on it. That action can be either act on each individually or act on
all together, depending on how you define the command.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    > But this suggests there should be a minibuffer command to say "submit
    > each of current candidates, one by one."

    What do you mean, "submit"? Submit to what?

Submit as an argument.  Just as C-RET submits the current minibuffer
contents as an argument (then reads another), this proposed command
would submit EACH of the current contents, one by one.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     > But this suggests there should be a minibuffer command to
>     > say "submit each of current candidates, one by one."
>
>     What do you mean, "submit"? Submit to what?
>
> Submit as an argument.  Just as C-RET submits the current minibuffer
> contents as an argument (then reads another), this proposed command
> would submit EACH of the current contents, one by one.

To be clear:

C-RET applies the action function to the current candidate as an argument,
but it does not read another. It does not end completion, so you simply type
(or cycle to) another candidate - there is no read operation.

C-! already applies the action function to EACH of the candidates that
currently match the minibuffer contents, one by one. Is that what you meant?
In the case of `customize-face', that opens a separate Customize buffer for
each chosen face.


If you instead mean to apply some function to a list of ALL of the
candidates, then see my previous message. For that, you would use a function
(a multi-command, in fact) that lets the user choose a list of candidates
and returns that list, and then you would act on the list. In the case of a
command `customize-faces', it would use multicommand `icicle-face-list' to
query the user for the list of faces, and then it would call
`custom-buffer-create' on `custom-sort-items' of the list of faces - exactly
as does `customize-apropos' today.

For examples of commands that use a multicommand that returns a list of
candidates that the user has chosen, see these commands:
icicle-add-buffer-config, icicle-search, icicle-occur,
icicle-search-char-property, icicle-search-file, and icicle-search-keywords.
Each of these uses a function (a multi-command) that asks the user to pick a
list of candidates (of files, buffers, faces, keywords, etc.), and then it
does something with that list.

For example, `icicle-search-keywords' lets the user pick keywords (regexps,
actually), and then it searches for any combination of those keywords. That
is, it creates a choice regexp (\(...\|...\|...\)) from the keywords, and
then it searches for that. The function that queries the user for the list
of keywords is the multi-command `icicle-keyword-list', but the user does
not call this directly, here.


If you were proposing to add a binding during completion that would always
do this kind of thing, then, yes, that could be attempted (I've considered
it, but I haven't done it yet). However, the function invoked on that list
needs to be supplied somehow - it cannot be the same function as C-RET (that
is what C-! does already). In the case of customizing faces, for instance,
that function would need to do what `custom-apropos' does with the list.

The way I would do that is to have another variable, similar to
`icicle-candidate-action-fn' and `icicle-candidate-alternative-action-fn',
that could be bound by the command. I would call it
`icicle-all-candidates-action-fn'. It would perform the action to which it
is bound on the list of chosen candidates.

In the case of `customize-face', for instance, this would then be the
definition:

(defun icicle-customize-face (face)
  "Customize face FACE."
  (interactive
    (list (let ((icicle-candidate-action-fn 'customize-face)
                (icicle-all-candidates-action-fn 'customize-faces))
            (read-face-name "Customize face: "))))
  (customize-face face))

Where `customize-faces' would be defined something like this:

(defun customize-faces (faces)
  "Open Customize buffer on all faces in list FACES."
  (custom-buffer-create
     (custom-sort-items faces t custom-buffer-order-groups)
     "*Customize Apropos*")))

Any way you look at it, I think you need to define the function that acts on
the list of chosen candidates. It cannot be defined automatically from the
`C-RET' action function - at least not in the general case.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    > Submit as an argument.  Just as C-RET submits the current minibuffer
    > contents as an argument (then reads another), this proposed command
    > would submit EACH of the current contents, one by one.

    To be clear:

    C-RET applies the action function to the current candidate as an argument,
    but it does not read another.

That implementation detail (which as you know I plan to do
differently) doesn't affect this point, which is about a feature.

    C-! already applies the action function to EACH of the candidates that
    currently match the minibuffer contents, one by one.

It sounds like that is the same feature.  That is good.

    In the case of `customize-face', that opens a separate Customize buffer for
    each chosen face.

I think `customize-face' as a multi-command should put all the faces
in one Custom buffer.  (Likewise the other `customize-...' commands.)

RE: propose adding Icicles to Emacs

[Drew Adams]

>     C-! already applies the action function to EACH of the candidates that
>     currently match the minibuffer contents, one by one.
>
> It sounds like that is the same feature.  That is good.
>
>     In the case of `customize-face', that opens a separate
>     Customize buffer for each chosen face.
>
> I think `customize-face' as a multi-command should put all the faces
> in one Custom buffer.  (Likewise the other `customize-...' commands.)

Then it needs to be defined that way.

The point is that `C-!' simply applies the action function (i.e. what
`C-RET' does) to each candidate, in turn. If that action function is the
current `customize-face', then it opens a new Customize buffer - for that
candidate. Opening a new Customize buffer is part of the current definition
of `customize-face'.

If the same function is used to act on a single candidate and to act on all
matching candidates, then you can get into trouble. The candidate action
function takes a candidate and does something with it. You are talking about
a function that takes a list of candidates and does something with that
list. That is not the same function.

If a given action function had an arg list such as (&rest candidates), then
you might be able to apply it to both a single candidate and multiple
candidates. But in the general case, you don't have control over what the
supplied action function is.

You can try to build in such a treatment, if you forego the ability of a
programmer to specify a different action function. If you try to
automatically convert each command that takes a candidate as arg into a
multicommand that operates on a list of such args, then you can do what you
hint (IIUYC). But you still need to provide the ability to do both: act on
all matching candidates individually (what C-! does) and act on all matching
candidates together. You still need to let the user do either of those. IMO,
it would be best to let the programmer define those actions separately,
instead of coupling them in some automatic way.

IMO, the way to handle this is what I said in my previous mail: bind a
function that expects and treats a list of candidates -
`icicle-all-candidates-action-fn'. That function can do whatever it wants.
In the case of `customize-face', it would open a single buffer for all
matching candidates, whereas `icicle-candidate-action-fn' opens a buffer for
its single candidate.

Opening a buffer is obviously only one possibility of a difference between a
desired action on the set as a whole and the set of desired actions on each
of the set members. The point is that if a programmer wants such a
difference in behavior in a particular case, then s?he needs to specify it
(unless you prohibit that expression and you impose a predefined relation).
A good way to specify those two different behaviors is by providing two
different functions.

Anyway, it's almost impossible to discuss this, because you are not specific
about your approach. We are waving at each other over a great distance,
making inordinate efforts to guess what the other is signaling. If you don't
want to talk about the details of the Icicles design and implementation,
then you need to provide the details of the design and implementation that
you have in mind. Otherwise, this discussion is too abstract to be useful -
we cannot follow each other and contribute anything meaningful.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    If the same function is used to act on a single candidate and to act on all
    matching candidates, then you can get into trouble. The candidate action
    function takes a candidate and does something with it. You are talking about
    a function that takes a list of candidates and does something with that
    list. That is not the same function.

I understand that's the case with your implementation.
I've envisioned another implementation in which multi-command
behavior works through a loop in call-interactively.
Thus, multi-argument input will be equivalent to
running the command over and over, with each argument.

Except for one thing: the command can tell that it is
being invoked for multi-command behavior.  And it can do
something different if it wants to.

Do you see the idea now?

RE: propose adding Icicles to Emacs

[Drew Adams]

>     If the same function is used to act on a single candidate and
>     to act on all matching candidates, then you can get into
>     trouble. The candidate action function takes a candidate and
>     does something with it. You are talking about a function that
>     takes a list of candidates and does something with that
>     list. That is not the same function.
>
> I understand that's the case with your implementation.
> I've envisioned another implementation in which multi-command
> behavior works through a loop in call-interactively.
> Thus, multi-argument input will be equivalent to
> running the command over and over, with each argument.

I know that.

> Except for one thing: the command can tell that it is
> being invoked for multi-command behavior. And it can do
> something different if it wants to.
>
> Do you see the idea now?

I believe I've seen your idea from the beginning, though we still have seen
no details, so it can be anything and everything ;-).

You say, "And [the command] can do something different if it wants to." That
was precisely my point. Somehow, someone needs to tell it whether, and if so
how, to let users do something different, if that is appropriate for that
particular command.

That is the same with my implementation, and, I think, with any
implementation. An operation on a set (list) is not necessarily the same
thing as N times _the same_ operation on each of its N elements. In the
general case - which we should provide programmers with, it is not the same.

The question is _how_ a programmer can indicate which function, if any, to
apply to the entire list (as a whole) and which function, if any, to apply
to each set member individually (all or selected members only). In some
cases it makes sense to let users do one, in some cases the other, and in
some cases both (separately).

In Icicles, the programmer who writes the command would do this by binding
appropriate variables to action functions, one for each desired behavior.
You might instead do this in any number of alternative ways, but you still
need to somehow let programmers control this. That was my point. "Do you see
the idea now?"

Are we talking about the same thing? Is it worth repeating what we're
saying? I'm not sure, at this point.

IMO, this is really a minor detail. There is a simple way to do this in
Icicles, and you can use a different simple way if you like.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    You say, "And [the command] can do something different if it wants to." That
    was precisely my point. Somehow, someone needs to tell it whether, and if so
    how, to let users do something different, if that is appropriate for that
    particular command.

The programmer will do this by checking a flag that `interactive' will
provide as an argument.

    The question is _how_ a programmer can indicate which function, if any, to
    apply to the entire list (as a whole) and which function, if any, to apply
    to each set member individually (all or selected members only). In some
    cases it makes sense to let users do one, in some cases the other, and in
    some cases both (separately).

No, that's not the question.  The question is how a programmer can
implement the desired behavior in each case.  With my proposal, the
programmer will make the command get an argument saying which behavior
to use.

Here's one idea:  use ! in the interactive spec to mean

   if the user uses the multi-command feature for this
   argument, read all the argument values, make a list of them,
   and pass that as the argument.

It would look like this:

(defun command (file)
  (interactive "!fFile: ")
  (if (listp file)
      ...operate on list of files...
    ...operate on one file...))

When using a Lisp expression inside `interactive',
it could look like this:

(defun command (file)
  (interactive
    (list (multi-arg-repeat
    	    (read-file-name ...))))
  (if (listp file)
      ...operate on list of files...
    ...operate on one file...))

where `multi-arg-repeat' is a suitable macro
that expands into something like

   (multi-arg-repeat-internal (lambda () (read-file-name ...)))

RE: propose adding Icicles to Emacs

[Drew Adams]

>     You say, "And [the command] can do something different if it
>     wants to." That was precisely my point. Somehow, someone needs
>     to tell it whether, and if so how, to let users do something
>     different, if that is appropriate for that particular command.
>
> The programmer will do this by checking a flag that `interactive' will
> provide as an argument.

That covers "whether", but not "how". Programmers should be able to specify
just what the set-as-a-whole operation does and how. In the case of
customize-face, for instance, it combines the face widgets in the same
Customize buffer. The relation between the action that is to be applied to
an individual object and the action to be applied to a list of such objects
is not obvious or fixed - or at least it should not be, IMO.

>     The question is _how_ a programmer can indicate which
>     function, if any, to apply to the entire list (as a whole) and
>     which function, if any, to apply to each set member individually
>     (all or selected members only). In some cases it makes sense to
>     let users do one, in some cases the other, and in
>     some cases both (separately).
>
> No, that's not the question.  The question is how a programmer can
> implement the desired behavior in each case.

You say "how to implement", and I say "how to indicate which function" -
tomayto, tomahto. Even if you don't use a Lisp function to implement the
behavior, the need is the same: be able to say what will be done and how.
Let's not get bogged down too much by terminology (if we do in fact
understand each other).

> With my proposal, the programmer will make the command get an
> argument saying which behavior to use.
> Here's one idea:  use ! in the interactive spec to mean
>
>    if the user uses the multi-command feature for this
>    argument, read all the argument values, make a list of them,
>    and pass that as the argument.

What do you mean by "uses the multi-command feature"? Do we agree that the
user would have different keys to invoke each of: (1) an action on the
current candidate, (2) an action on each matching candidate, individually,
and (3) an action on all matching candidates, taken together? I think you're
speaking only of the #3 "multi-command feature" here, right?

> It would look like this:
>
> (defun command (file)
>   (interactive "!fFile: ")
>   (if (listp file)
>       ...operate on list of files...
>     ...operate on one file...))

That's one possible way. Can I assume that users can also apply the one-file
action to all matching files, as is the case today with `C-!'? That is, they
can still do #2 above, right?

Your approach makes each command definition that uses "!" in the interactive
spec deal with the list (collective) and non-list (individual) cases
together, in a conditional in its body. In my approach, the main code of the
command (the single-item case) is what fills the command definition, and the
definition of the action for the list of files is defined as a separate
function. Which is clearer or otherwise better?

(defun command (file)
  (interactive "fFile: ")
  (let ((all-candidates-action-fn 'action-all))
     ...operate on one file...))

(defun action-all (files)
  ...operate on list of files...)

This still assumes your automatic treatment of multicommands via
`call-interactively'. The way I do it now separates each of the action
functions (the action "implementations", in your terms) from the command
definition itself:

(defun command ()
  (interactive)
  (let ((candidate-action-fn 'action-one)
        (all-candidates-action-fn 'action-all))
     (action-one (read-file-name "File: "))))

(defun action-one (file)
  ...operate on one file...))

(defun action-all (files)
  ...operate on list of files...)

In the general case, you can do something more or aomething different in the
`command' than just apply `action-one' to the file name that is read.

In the simplest case, `command' just binds the action functions, reads with
completion, and applies the main action to what is read. That is, `command'
is essentially an interface. In the simplest case, the body of `command'
looks like a definition of a simple command to act on one object (file).
Most Icicles multicommands will look just like the corresponding simple
commands, with `icicle-define-command' instead of `defun'.

In your approach, too, the simple case is simple. But in the general case,
all of the code for each of the various actions would presumably be in the
`command' body, in one big conditional. I'm not sure that's an improvement,
for programmers.

Anyway, I'm not against such an approach. I'm just saying that I'm not yet
convinced it is an improvement. Of course, you don't need to convince me.

> When using a Lisp expression inside `interactive',
> it could look like this:
>
> (defun command (file)
>   (interactive
>     (list (multi-arg-repeat
>     	    (read-file-name ...))))
>   (if (listp file)
>       ...operate on list of files...
>     ...operate on one file...))
>
> where `multi-arg-repeat' is a suitable macro
> that expands into something like
>
>    (multi-arg-repeat-internal (lambda () (read-file-name ...)))

I don't know what you have in mind for `multi-arg-repeat(-internal)'.

I really don't have any special suggestions about this. In general, I think
it's easier for a programmer to think in terms of separate action functions
for each of the things we've talked about:

1. help action        on current candidate
2. main action        on current candidate
3. alternative action on current candidate
4. deletion action    on current candidate
5. main action        on list of matching candidates
6. alternative action on list of matching candidates

We haven't actually talked about #6, but it is a logical feature, from the
moment that you allow for #3 and #5. The user can today apply the main
action (#2) or the alternative action (#3) to all matching candidates,
acting on each individually. No extra function needs to be defined for this;
#2 and #3 do the job. What you've brought up is #5: acting on all
collectively. I've added #6 here.

In my approach, which I think is maybe simpler for programmers, each of
#1-#6 is a predefined variable that you bind to the function you want. If a
variable is not bound or is bound to nil, then nothing happens when the user
invokes the corresponding key. More precisely, if #1 and #2 are not bound,
then candidate help is provided in a default way (which is nevertheless
specific to each candidate type).

If you think that what you've described is the best approach, then go for
it. I hope that you will still allow for all of #1-#4, at least.

As I said earlier, this (#5, and in fact the whole question of how to
implement multicommands) is peripheral to most of what could be integrated
from Icicles.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Your approach makes each command definition that uses "!" in the interactive
    spec deal with the list (collective) and non-list (individual) cases
    together, in a conditional in its body.

That's the purpose of `!': so you can distinguish those two cases.
If you don't want to distinguish them, then you don't write `!'.
Then the command gets called once for each argument.

I think it is a simple feature that makes it possible to implement,
in a clean way, all the multi-command features that we have discussed.

    This still assumes your automatic treatment of multicommands via
    `call-interactively'.

Exactly.  That's a better method.

I think it is a simple feature that makes it possible to implement,
in a clean way, all the multi-command features that we have discussed.

			  The way I do it now separates each of the action
    functions (the action "implementations", in your terms) from the command
    definition itself:

    (defun command ()
      (interactive)
      (let ((candidate-action-fn 'action-one)
	    (all-candidates-action-fn 'action-all))
	 (action-one (read-file-name "File: "))))

That's why my method is better.

(Note that this example reads a minibuffer argument inside the body of
the command, contrary to Emacs convention, which says you should read
them inside `interactive'.)

RE: propose adding Icicles to Emacs

[Drew Adams]

>     Your approach makes each command definition that uses "!" in
>     the interactive spec deal with the list (collective) and
>     non-list (individual) cases together, in a conditional in its
>     body.
>
> That's the purpose of `!': so you can distinguish those two cases.
> If you don't want to distinguish them, then you don't write `!'.

I understand that. And if you want to distinguish them, then you need the
conditional, as you indicated.

> Then the command gets called once for each argument.

Are you saying that if you use `!' in the interactive spec then a user can
have only the whole-set-at-once behavior and not also the
act-on-each-candidate behavior? I thought we were talking about _adding_ the
former, not substituting it for the latter. Now it sounds as if you want to
take the latter away.

Acting on a set as a whole is different from acting on each of its elements.
There is no reason to try to substitute one for the other, instead of
providing for both.

> I think it is a simple feature that makes it possible to implement,
> in a clean way, all the multi-command features that we have discussed.

I don't know about that. I haven't heard you confirm or explain how it
provides for the actions #1-#4 that I listed (1: help action, 2: main
action, 3: alt action, 4: delete action). You've only mentioned the main
action (#2) and applying a different action to the list as a whole (#5). And
it seems you are saying now that acting on the list (#5) would mean
foregoing acting on all matching candidates individually (`C-!'). It's not
clear to me what you are saying about the various actions.

Another reason I gave for using variables bound to action functions is so
that other code can override or test such a binding. For example, one
multicommand calls another to implement some of its behavior, but it
overrides a default action function or tests whether an action function is
defined. I gave an example illustrating the override.

>     This still assumes your automatic treatment of multicommands via
>     `call-interactively'.
>
> Exactly.  That's a better method.

The "this" was an example that used my approach of binding the
set-as-a-whole action function. It was a hybrid example that adopted
(assumed) your C-language enhancement to support the use of an argument for
a multicommand.

> > I think it is a simple feature that makes it possible to implement,
> in a clean way, all the multi-command features that we have discussed.

Repeating that doesn't show how it is so. You still haven't mentioned how
you will you implement/support the various actions (#1-#6).

> 	The way I do it now separates each of the action functions
>     (the action "implementations", in your terms) from the command
>     definition itself:
>
>     (defun command ()
>       (interactive)
>       (let ((candidate-action-fn 'action-one)
> 	        (all-candidates-action-fn 'action-all))
> 	    (action-one (read-file-name "File: "))))
>
> That's why my method is better.

What's why? What's the reason? If a programmer defines a command with each
of the actions #1-#6, then, IIUC, you end up with a big conditional in the
command body with your approach. Why is that better?

> (Note that this example reads a minibuffer argument inside the body of
> the command, contrary to Emacs convention, which says you should read
> them inside `interactive'.)

Do you mean this convention from the Elisp manual (sans rationale BTW)?

  "In most cases, you should not call minibuffer input functions in the
   middle of a Lisp function.  Instead, do all minibuffer input as part of
   reading the arguments for a command, in the `interactive' specification."

In most cases, OK, but it depends on the context. When input is read inside
`interactive' it is done before other processing by the command (unless some
such processing is also shoved inside `interactive', before the read, which
can result in contrived/unnatural code). That's not always the most
appropriate behavior.

You can also say that one should, in most cases, read command arguments
inside `interactive' (which is not quite the same thing). What is read here
is not an argument (or a "minibuffer argument").

You can argue that it should be, that it's better, in most cases, to read
user input as arguments. But, as you know, without redefining some of the
basic C infrastructure (as you now intend to do), it was not possible to put
the multicommand read inside `interactive'. Thus the departure from
convention. I gave the hybrid example to show that I agree that it would be
good to be able to treat the completion candidate as an argument.

Anyway, as I already said:

> 	I'm not against such an approach. I'm just saying that I'm
>     not yet convinced it is an improvement. Of course, you don't
>     need to convince me.

You don't need to convince me, but I do wonder if/how you intend to support
each of the possible actions we've discussed so far: #1-#6, plus letting
users apply #2 (main action) and #3 (alt action) to all matching candidates
individually.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Are you saying that if you use `!' in the interactive spec then a user can
    have only the whole-set-at-once behavior and not also the
    act-on-each-candidate behavior? I thought we were talking about _adding_ the
    former, not substituting it for the latter. Now it sounds as if you want to
    take the latter away.

The number of misunderstandings that have occurred in this
conversation have exausted my patience.  I cannot continue it.

I do not want to install Icicles as it exists, since it is a congeries
of features.  Some of those features I simply don't want.  Some I
would like to install, if they were implemented separately in the
cleanest possible way.  In particular, the multi-command behavior
is one I would accept if it is implemented cleanly.

I've suggested a clean approach for that feature, but I don't have
time to implement it myself.  If someone chooses to implement it, we
could install it.

Meanwhile, as I stated earlier, there are other small features in Icicles
that would be nice to install individually.

The practice of putting a congeries of features into a single
incoherent package creates a large and unnecessary obstacle to
installing some of them.  Often the obstacle is so big that none of
them ever get installed.

Thus we urge users to propose one feature at a time, one bug fix at a
time, etc.

RE: propose adding Icicles to Emacs

[Drew Adams]

> The number of misunderstandings that have occurred in this
> conversation have exausted my patience.  I cannot continue it.

That makes two of us. Thanks for pulling the plug - quite a relief. Now we
can each get back to more productive endeavors.

Re: propose adding Icicles to Emacs

[Juri Linkov]

> But this suggests there should be a minibuffer command to say "submit
> each of current candidates, one by one."

As I proposed on a different thread, we could improve `completing-read-multiple'
with different separators between completion candidates.  Currently it
supports `,' to separate completion candidates used as arguments of one
command (e.g. with faces this means putting a group of faces separated by
`,' in one custom buffer).  A new separator (e.g. `;') could be used to
separate completion candidates to call the action on each of them (thus
creating a separate buffer for faces separated by `;').

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

RE: propose adding Icicles to Emacs

[Davis Herring]

> In the vanilla Emacs `customize-apropos-faces', you must provide a regexp
> once and for all, with RET - there is no completion of face names
> available,
> and no way to rectify your regexp without starting over.
>
> This is a good example of the general advantage of regexp matching on the
> fly, and the advantage of providing input by completion whenever possible.

I'm not arguing against the end-result here (an interactive guide to the
effects of your entered regexp), but it strikes me as intensely confusing
to use the standard completing read mechanism (or a variant of it) to read
one thing (a regexp) while providing "completion" on another (face names).
 As a silly example, suppose a face name contained the character $: then
selecting it from *Completions* (because you realized you wanted just that
one) would have entirely the wrong effect.

In general, then, this process probably deserves another name than
"completing-read".  It's related to re-builder, in that it is interactive
"explanation" of a regexp; perhaps it could be called "building-read" or
so?

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

Re: propose adding Icicles to Emacs

[Lennart Borgman (gmail)]

Davis Herring wrote:
> In general, then, this process probably deserves another name than
> "completing-read".  It's related to re-builder, in that it is interactive
> "explanation" of a regexp; perhaps it could be called "building-read" or
> so?

re-completing-read?

RE: propose adding Icicles to Emacs

[Drew Adams]

> > In the vanilla Emacs `customize-apropos-faces', you must
> > provide a regexp once and for all, with RET - there is no
> > completion of face names available,
> > and no way to rectify your regexp without starting over.
> >
> > This is a good example of the general advantage of regexp
> > matching on the fly, and the advantage of providing input
> > by completion whenever possible.
>
> I'm not arguing against the end-result here (an interactive guide to the
> effects of your entered regexp), but it strikes me as intensely confusing
> to use the standard completing read mechanism (or a variant of it) to read
> one thing (a regexp) while providing "completion" on another (face names).
> As a silly example, suppose a face name contained the character $: then
> selecting it from *Completions* (because you realized you wanted just that
> one) would have entirely the wrong effect.
>
> In general, then, this process probably deserves another name than
> "completing-read".  It's related to re-builder, in that it is interactive
> "explanation" of a regexp; perhaps it could be called "building-read" or
> so?

At least one of us is likely confused about what the other means ;-).

What I was talking about has nothing to do with re-builder. No connection.
This is also not about "an interactive guide to the effects of your entered
regexp". In Icicles, you do not enter a regexp (with RET) at all. You type
some input and then complete it. One of the completion possibilities is to
use regexp matching instead of prefix matching. So, if your input is
`foo.*bar' and you ask for regexp matching, then you can match candidates
such as titifoobar, foo$titibar, and titifoo&*!(*@^$$$+%bartata.

If a face name contains `$', then selecting that name from *Completions*
just selects it - nothing new here. I don't understand what you mean by
"would have entirely the wrong effect". The effect is that you get the
candidate you select, always. The only thing new is how what you type is
matched against the domain of possible candidates.

In Icicles, whether you want what you type in the minibuffer to be
considered as (1) a prefix, to be matched using prefix matching (as in
vanilla Emacs), or as (2) a regexp, to be matched using regexp matching, is
under your control as a user. If you want the former, you hit TAB; if you
want the latter, you hit S-TAB.

If you do want regexp matching (which of course includes substring
matching), then, yes, `$' acts as a regexp special character for matching,
naturally. This means that if you want to match a `$' character literally,
then you type `\$' instead of `$' if you want regexp matching.

In addition, you can, at any time during minibuffer input completion, toggle
treatment of regexp special characters (i.e. as special) by hitting `C-`'.
This toggles the behavior of S-TAB, in effect, between regexp matching and
substring matching.

Summary: If you want to match a `$' character, do one of the following:

- Use prefix matching (TAB), not regexp matching (S-TAB).

- Type a regexp that matches a `$' character, and use S-TAB. Both `.' and
`\$', for instance, match a `$' character.

- Turn on automatic quoting of special characters in regexp matching, using
`C-`'. This makes S-TAB perform substring matching, not regexp matching.

[Also, as I mentioned in an earlier exchange in this thread, Icicles treats
`$' a little specially. If it is not in a position where it makes sense as
an end-of-line match, then it is available for environment-variable
substitution. See
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Special_Characters_in_Input_
Patterns for an explanation how globbing and regexp matching cohabit
peacefully in Icicles.]

RE: propose adding Icicles to Emacs

[Davis Herring]

>> > In the vanilla Emacs `customize-apropos-faces', you must
>> > [snip]
>>
>> In general, then, this process probably deserves another name than
>> "completing-read".  It's related to re-builder, in that it is
>> interactive
>> "explanation" of a regexp; perhaps it could be called "building-read" or
>> so?
>
> At least one of us is likely confused about what the other means ;-).
>
> What I was talking about has nothing to do with re-builder. No connection.
> This is also not about "an interactive guide to the effects of your
> entered
> regexp". In Icicles, you do not enter a regexp (with RET) at all. You type
> some input and then complete it. One of the completion possibilities is to
> use regexp matching instead of prefix matching. So, if your input is
> `foo.*bar' and you ask for regexp matching, then you can match candidates
> such as titifoobar, foo$titibar, and titifoo&*!(*@^$$$+%bartata.

We're talking about entering a regexp for (a more powerful version of)
`customize-apropos-faces'.  The result of your call to `completing-read'
is a regexp, which you then pass to the original c-a-f.  The
"completions", however, are not regexps, and so look very odd in the
context of completing the user's input -- of a regexp.  That's all I'm
saying.

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

RE: propose adding Icicles to Emacs

[Drew Adams]

> > In Icicles, you do not enter a regexp (with RET) at all.
> > You type some input and then complete it. One of the
> > completion possibilities is to use regexp matching instead
> > of prefix matching.
>
> We're talking about entering a regexp for (a more powerful version of)
> `customize-apropos-faces'.  The result of your call to `completing-read'
> is a regexp, which you then pass to the original c-a-f.  The
> "completions", however, are not regexps, and so look very odd in the
> context of completing the user's input -- of a regexp.  That's all I'm
> saying.

I think I understand you now. Does the following description help?

1. In the Icicles version, the prompt does not say "Customize regexp: " as
it does in vanilla Emacs. It says "Customize faces (regexp): ". IMO, the
original prompt is misleading - you are customizing faces, not a regexp
(whatever that would mean). You are entering a regexp in order to customize
the faces whose names match it - in both Icicles and vanilla Emacs.

2. At the prompt, you can type text that matches any number of face names.
You can enter this text, with `RET', just as for the current `c-a-f', and
the result will be identical to what happens today with `c-a-f': the faces
whose names match the text you entered will be customized together, in the
same Customize buffer. The text you enter is matched as a regexp against the
names of available faces (by vanilla `c-a-f'). With this usage, there is
zero difference from what happens in vanilla Emacs (except for the clearer
prompt in the Icicles case).

3. Alternatively, in Icicles you can type the same regexp but not hit RET
(yet). If you hit S-TAB, then the matching faces are available as completion
candidates. Yes, you are completing against face names, not against regexps
(whatever that might mean). If you then hit RET, then this is identical to
#2 - you simply had the advantage of previewing the faces that match.

If all of the faces have a common substring, then you will need to hit `C-l'
before `RET', to retrieve your regexp in the minibuffer. By default, Icicles
replaces your regexp in the minibuffer with the longest substring common to
all matches (this behavior is optional).

4. If the preview of the matching faces is not what you expect, you can edit
the regexp in the minibuffer - *Completions* is updated to reflect that
edit. Again, if you hit `RET', then go to #2 - you get the same behavior as
for `c-a-f'.

5. If, after hitting S-TAB, you want to customize only some of the matching
faces, you can use `C-RET' or `C-mouse-2' to choose those you want. (You can
use `next' and `prior' to cycle among the candidates, to be able to choose
some with `C-RET'.) There are additional ways that you can narrow down your
choice to a smaller set of face names, including these: (a) type additional
regexps that face names must also match, (b) exclude some names by typing
additional regexps and complementing their matches. You can use `RET' (go to
#2) to customize those that still match after narrowing the choices.

6. You need not ever use `RET' to end the `completing-read' call (and the
command), however. If you have already used `C-RET' with `S-TAB' to open
Customize buffers for all of the faces that you want to customize, then you
can just use `C-g' to end the command. (Or use `RET' with a regexp, such as
`uuuuuuuu', that matches no face names.)

HTH. Let me know if something is still not clear. Also, you might just give
it a try; it's easier (and more fun) to use than to read about.

Also, please see my followup message the same day, where I explained that
there is in fact not much need for such a command(!), whether the vanilla or
the Icicles version. I showed that the simple Icicles command
`icicle-customize-face' is about as good:

(defun icicle-customize-face (face)
  "Customize face FACE."
  (interactive
    (list (let ((icicle-candidate-action-fn 'customize-face))
            (read-face-name "Customize face: "))))
  (customize-face face))

The only disadvantage is that you cannot use this command to customize all
matching faces in the same Customize buffer - you get a different Customize
buffer for each face. On the other hand, two advantages are that (1) the
display of matching faces can be WYSIWYG (because it uses
`read-face-name') - a much better preview, and (2) you can get help about
individual faces while you are choosing them, in case you have a doubt about
the meanings (uses) of some of them.

Besides these differences, the reason for mentioning this command is to
illustrate how easy it is to define (vs the definition of vanilla `c-a-f').
And with Richard's proposed implementation of `call-interactively', even the
above definition would presumably be superfluous: `customize-face' would
work for any number of faces. (That assumes Icicles regexp matching with
S-TAB.)

Re: propose adding Icicles to Emacs

[Richard Stallman]

    1. In the Icicles version, the prompt does not say "Customize regexp: " as
    it does in vanilla Emacs. It says "Customize faces (regexp): ". 

I will install that bug fix presently.

The rest of the explanation makes sense now.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    What do you mean by "there"? If you mean on `minibuffer-setup-hook', then
    please reread the above.

It says that there are things you don't see how to do,
and that they are in a function `icicle-minibuffer-setup'.
But it doesn't say what they are.

To study the code to figure that out could take an hour,
and I have so much work I can't do it that way.
I need someone to explain to me.

    Initializations etc.
    that are appropriate for only one function (e.g. `completing-read') cannot
    be put on a hook that is run when every function activates the minibuffer.

Maybe that is so.  Therefore I need to know what features these things
are trying to implement, and in general terms how you've implemented
those features; they I can look for other ways to do it.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     What do you mean by "there"? If you mean on
>     `minibuffer-setup-hook', then please reread the above.
>
> It says that there are things you don't see how to do,
> and that they are in a function `icicle-minibuffer-setup'.
> But it doesn't say what they are.

No, it's the opposite. Stefan asked why I couldn't do what I do now in my
redefined `completing-read', `read-file-name' etc. in
`minibuffer-setup-hook' instead. What I replied ("above") was that I was
already doing all that could be done on that hook (via
`icicle-minibuffer-setup', which is on that hook). IOW, I was saying that I
didn't think that more that is done in `completing-read' etc. could be moved
to `minibuffer-setup-hook' (e.g. to `icicle-minibuffer-setup').

> To study the code to figure that out could take an hour,
> and I have so much work I can't do it that way.
> I need someone to explain to me.

I explained it in detail in my last reply to Stefan.

>     Initializations etc. that are appropriate for only one
>     function (e.g. `completing-read') cannot be put on a hook
>     that is run when every function activates
>     the minibuffer.
>
> Maybe that is so.  Therefore I need to know what features these things
> are trying to implement, and in general terms how you've implemented
> those features; they I can look for other ways to do it.

Please see my last mail to Stefan, where I replied in detail about each bit
of code in each standard function that I redefine, including
`completing-read'. I detail some solutions and clarify some remaining
questions.

Summary: I think some things can be dropped and others would need, IMO, to
be moved into standard Emacs functions such as `completing-read'.

We can address those explanations one by one, if you like.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Please see my last mail to Stefan, where I replied in detail about each bit
    of code in each standard function that I redefine, including
    `completing-read'.

Thank you for explaining it.  Although you sent that message to him
before reading mine, I did not receive your message until later.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Redefining completing-read is a no-no in my book.  Please try to rewrite
    your code so as not to do that (e.g. using minibuffer-setup-hook).  Also, if
    it turns out to be impossible, or very inconvenient, then post a request for
    enhancement to make it possible/easier.

We can make changes in completing-read so as to accommodate the needs
of these features.  The point is to do this cleanly.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    I'd propose adding Icicles first as an optional library, without trying to
    integrate any of it deeply with Emacs. Later, we could look into a possible
    tighter integration.

That is a very bad idea.  "Temporary" solutions tend to become
permanent, and to prevent that from occurring requires insistence.  No
software developer should install code meant to be temporary unless it
is essential to do so.  Icicles features are nice, but installing them
is not essential.

Therefore we will put the code into the form we want to keep permanently
and then install it.

    > Why does it do this?

    Because those replacements are enhanced versions. They are typically
    multi-commands that 1) keep the same behavior as the original, as long as
    you don't use any special Icicles minibuffer bindings, but also 2) let you
    take advantage of those minibuffer bindings (e.g. `C-RET') to get the
    multi-command behavior.

Let's suppose I can magically implement multi-command behavior without
the need to define separate multi-commands to do it.  (I think I can,
and I explained how.)

Is there any other reason in icicles to define new commands
to replace the existing ones?

If so, what is it?  Maybe I can find a better way to implement that,
too.

The need to replace commands is a complexity, and the code will
be much better if we avoid that complexity.

    Yes, you must define a new command, in order to adapt a given existing
    command to multi-command use. This is a good thing, as some commands might
    not lend themselves well to multi-command use (i.e. it might make no sense
    for them, adding nothing).

That is no argument against making multi-command behavior magic.
Just respond, "If it isn't useful there, don't use it there."

			       And, more often, it is appropriate for some
    commands to have a slightly different action function for candidates during
    completion than after completion (for instance, because the
    buffer/window/frame context or the use context might be different).

This might be a real issue.  Can you please give an example or two?

    If Icicles does not break anything, and it does not have a lasting effect
    when you leave Icicle mode, then I think how it is implemented should not be
    a concern.

That is true if you distribute it separately.
If it is part of Emacs, that changes everything.
We want Emacs to be modular.  My proposed implememtation
of multi-command behavior is totally modular.  I think we
can make it work with NO changes in any specific command. 

    The macro expansion of a multi-command defined using #1 or #2 is quite
    complex. Some of its definition implements context management (window,
    frame, buffer), and some of it implements treatment of possible errors from
    application of the action function. For example, the original buffer,
    window, or frame, to which we often want to return, might have been deleted
    by application of the action to a particular candidate (e.g. if the action
    is to kill the buffer, and the candidate acted on is the original buffer).
    And we usually want to keep the focus after action application on the
    minibuffer's frame, so that we can possibly keep using `C-RET' etc. on other
    candidates.

The code in call-interactively may need to deal with such cases.  I
think it can do so in ways that are independent of the specific
command that was run.

    Wrt prefix args: C-u is treated specially during completion, so that, for
    instance, you can apply it to individual candidates that you act on using
    `C-RET'. That is, you can use a different prefix argument each time you act
    on a candidate, if you like.

I just assumed it was the other way.  We could handle the prefix this
way just as easily.

     Remember, that, by default, you can act on the
    same candidate multiple times. Sometimes that makes sense, sometimes it does
    not.

Can you give me an example where it does not make sense?

    2. It's appropriate, for many commands, to specialize the action behavior
    during completion. See the commands that explicitly bind
    `icicle-candidate-action-fn', as opposed to just using
    `icicle-define-command'. Command `icicle-search', for instance, could not be
    defined using `icicle-define-command'.

Can you please explain an example of this specialization?
Then I can think about its consequences.

RE: propose adding Icicles to Emacs

[Drew Adams]

I'm not sure it's worth going into each of your comments, but I'll try.

Please see my previous email (with Plan A and Plan B). That is my position
and a starting point for discussion about how to proceed. (I received this
mail after sending my previous mail, BTW.)

>     I'd propose adding Icicles first as an optional library,
>     without trying to integrate any of it deeply with Emacs.
>     Later, we could look into a possible
>     tighter integration.
>
> That is a very bad idea.  "Temporary" solutions tend to become
> permanent, and to prevent that from occurring requires insistence.  No
> software developer should install code meant to be temporary unless it
> is essential to do so.  Icicles features are nice, but installing them
> is not essential.

Installing Icicles features is not essential to Emacs. We agree on that.

Evolution, even planned evolution, can proceed in stages. A stage that
includes Icicles as an optional package is not equivalent to ugly hacking or
sneaking in a trojan horse under the pretense or belief that it is only
temporary. I gave good reasons for my recommendation. It is not a good idea
to lay waste to everything first, IMO, but that is your call. You are
welcome to prefer plan B. In plan B, Icicles is a quarry of ideas, you are
the implementor, and I can be consulted if you have questions.

> Therefore we will put the code into the form we want to keep
> permanently and then install it.
>
>     > Why does it do this?
>
>     Because those replacements are enhanced versions. They are typically
>     multi-commands that 1) keep the same behavior as the
>     original, as long as you don't use any special Icicles minibuffer
>     bindings, but also 2) let you take advantage of those minibuffer
>     bindings (e.g. `C-RET') to get the multi-command behavior.
>
> Let's suppose I can magically implement multi-command behavior without
> the need to define separate multi-commands to do it.  (I think I can,
> and I explained how.)

You did _not_ explain how, beyond some hand waving. At least not to my
satisfaction. I don't understand your magic solution, and I think you don't
fully understand Icicles multi-command behavior. But if you choose plan B, I
don't necessarily need to understand your design, except to be able to
answer questions about the existing Icicles features.

If you don't want to explain it, you can implement it and we can then talk
about how it fits with Icicles features and what parts of Icicles could
perhaps be eliminated because of it.

Creating a multi-command is a programmer decision. Different multi-commands
work differently. The simplest just do what you have understood. But even in
the simplest cases, which can be handled by the Icicles definition macros, a
programmer can (and will sometimes need to) provide extra bindings or extra
code.

> Is there any other reason in icicles to define new commands
> to replace the existing ones?

Speaking of replacement is off the mark. Multi-commands and the ability to
define them as appropriate for a given use are one thing. Deciding to bind
`C-x C-f' to a multi-command file-finding function instead of vanilla
`find-file' file is another thing - a separate consideration. Forget the
latter, if you will; it's not necessary.

You seem bent on automatically converting all commands to multi-commands.
That might be useful, in a limited way. But programmers will still need to
be able to define multi-commands that go beyond the simple case. I gave
`icicle-search' as an example.

I do agree that much of the error and context handling that I add to a
multi-command definition via the definition macros could instead be built
into Emacs somehow, and that would be great.

Only please do that carefully, if you do it, and please still let
programmers bind their own candidate action function when they design a
custom multi-command. Without that feature, a lot is lost. As I said before,
you have only to look at the commands that explicitly bind
`icicle-candidate-action-fn' or `icicle-candidate-alt-action-fn' to get an
idea why this is needed. Again, `icicle-search' is a good example.

IOW, if you decide to build some magic into Emacs to implement some of the
multi-command functionality, please keep it flexible, so that Emacs-Lisp
programmers can build custom multi-commands that use different action
functions etc.

You know, there are other things that could also be moved into vanilla Emacs
as well (outside of using an Icicles package). Multi-commands depend on
candidate cycling (to be more precise, they cry out for it, but it is not a
strict logical requirement). The cycling logic is another thing that could
be provided by Emacs outside of Icicles. We are moving in the direction of
Plan B here.

> If so, what is it?
> Maybe I can find a better way to implement that, too.

Not sure what this means. I've said that we need not automatically replace
any command bindings. If users want to bind `C-x C-f' to a different
command, they can always do so. Even in Icicles, I don't force this on
anyone: a user option controls such command remapping.

> The need to replace commands is a complexity, and the code will
> be much better if we avoid that complexity.

There is no need to replace any commands. Keep them all.

>     Yes, you must define a new command, in order to adapt a given
>     existing command to multi-command use. This is a good thing, as
>     some commands might not lend themselves well to multi-command
>     use (i.e. it might make no sense for them, adding nothing).
>
> That is no argument against making multi-command behavior magic.
> Just respond, "If it isn't useful there, don't use it there."

Multi-commandness being inappropriate for a given command is one thing. Yes,
it should be possible to optionally not use multi-commandness, when that is
appropriate. That is what happens anyway now: by default, no action function
is defined, and C-RET provides candidate help (just as C-M-RET does).

The more important consideration is the following:

>     And, more often, it is appropriate for some commands to have a
>     slightly different action function for candidates during
>     completion than after completion (for instance, because the
>     buffer/window/frame context or the use context might be different).
>
> This might be a real issue.  Can you please give an example or two?

I did. `icicle-search'. And the other multi-commands that are defined by
explicitly binding an action function, alternate action function, or
candidate-help function, instead of being defined using a definition macro.

There are several multi-commands that are, themselves, built using
`icicle-search'. You can read about Icicles search here:

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Search_Commands%2c_Overview

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Search-And-Replace

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Other_Search_Commands

The `icicle-search' code is here:
http://www.emacswiki.org/cgi-bin/wiki/icicles-cmd.el

>     If Icicles does not break anything, and it does not have a
>     lasting effect when you leave Icicle mode, then I think how
>     it is implemented should not be a concern.
>
> That is true if you distribute it separately.
> If it is part of Emacs, that changes everything.
> We want Emacs to be modular.  My proposed implememtation
> of multi-command behavior is totally modular.  I think we
> can make it work with NO changes in any specific command.

No one is against modularity. I have not seen a "proposed implementation",
beyond some vague hand-waving. I'm not against simplification. I'm asking
for details, so I can understand you. My ideas are detailed in the
implementation. You can examine exactly how it is done now and propose
alternatives. Your proposal so far is, for me, something indeterminate and
uncommunicated.

>     The macro expansion of a multi-command defined using #1 or #2
>     is quite complex. Some of its definition implements context
>     management (window, frame, buffer), and some of it implements
>     treatment of possible errors from application of the action
>     function. For example, the original buffer, window, or frame,
>     to which we often want to return, might have been deleted
>     by application of the action to a particular candidate (e.g.
>     if the action is to kill the buffer, and the candidate acted on is
>     the original buffer). And we usually want to keep the focus after
>     action application on the minibuffer's frame, so that we can
>     possibly keep using `C-RET' etc. on other candidates.
>
> The code in call-interactively may need to deal with such cases.  I
> think it can do so in ways that are independent of the specific
> command that was run.

I agree that some of what is currently done in the definition macros (hence,
in the code of each multi-command defined with them) could be built into
Emacs - perhaps to handle all commands. However, that needs to be done
carefully and fully. For example, use of a standalone minibuffer and non-nil
pop-up-frames should also work.

I agree about "independent of the specific command that was run", but only
in the case of run-of-the-mill multi-commands. For some multi-commands you
want the frame focus to end up in a different place when you are done, for
example. You might typically work in the buffer of application after using a
multi-command, or you might instead typically want the minibuffer frame to
continue to have the focus so you can use it again - different commands have
different use cases. There needs to be some flexibility. A programmer needs
to be able to build a custom multi-command in the sense I have described.

I had my multi-command definition macros available for my own use, yet I did
not use them to define some of the multi-commands. Why? Because they are not
flexible enough - they cannot be flexible enough. There is no substitute for
being able to code what is needed in a particular case.

>     Wrt prefix args: C-u is treated specially during completion,
>     so that, for instance, you can apply it to individual candidates
>     that you act on using `C-RET'. That is, you can use a different
>     prefix argument each time you act on a candidate, if you like.
>
> I just assumed it was the other way.  We could handle the prefix this
> way just as easily.

Yes, this is the kind of thing that could advantageously be handled
automatically within the command loop (or whatever) of Emacs itself.

I think what I'm trying to say is that, yes, the infrastructure to interpret
multi-command definitions and handle multi-command bindings such as `C-RET'
could be built into Emacs, simplifying or eliminating, for example, the need
for the multi-command definition macros.

But programmers will still need a flexible way to direct and inform that
infrastructure, so that they can define custom multi-commands that DTRT in
different contexts. They need, at a minimum, a way to define the action
function, the alternative action function, the candidate-help function, and
object deletion for a given multi-command. There can be default behavior,
such as using the same action for both C-RET and RET and having an empty
alternative action, but programmers need to be able to override this default
behavior and provide their own functions for these things.

>     Remember, that, by default, you can act on the
>     same candidate multiple times. Sometimes that makes sense,
>     sometimes it does not.
>
> Can you give me an example where it does not make sense?

Practically every place where I have used a non-nil value for
`icicle-use-candidates-only-once' is an example. It is not so much that
multiple invocation would be harmful (though perhaps that can also be true
for some commands). It is that, in many cases, it is handy for the user to
remove the candidate from the list of available candidates, once it has been
acted on.

That is the purpose of `icicle-use-candidates-only-once'. This does not
definitively prevent using the candidate again in the same multi-command
invocation; it simply removes it from the candidate list for the time being,
so that you don't see it and you cannot cycle to it. If you complete again
(TAB or S-TAB), however, then you see the candidate again. This is exactly
the same behavior a user gets if s?he explictly uses the `delete' key or
`S-mouse-2' on the current completion candidate: it is simply removed as a
candidate (until you complete again).

For instance, command `icicle-set-option-to-t' reads the name of a binary
user option and sets it to t. It doesn't make much sense to do this more
than once to the same option in the same command invocation. Removing that
option from the list of candidates makes it easier to see the remaining
options that you can act on.

A case such as `icicle-delete-windows' is more along the lines of "if it's
done, it's done". Once you have deleted the windows showing a buffer, it
makes sense to remove that buffer name from the list of candidates, because
it makes no sense to choose it again. `icicle-delete-file' is similar: if
the file has been deleted, you should no longer see it as a candidate. (Some
multi-commands remove a used candidate directly, without employing
`icicle-use-candidates-only-once' to do that.)

BTW, it might seem that commands such as `icicle-find-file' might also want
to bind this option to non-nil. But a user might, in the same
`icicle-find-file' invocation, navigate among different files using
`C-RET' - that is, return to choose the same file name more than once. To
bind this option in any given context, it should not be the case that a user
might want to return to a given candidate and use it again.

BTW2: There is a difference between removing a candidate as a candidate and
removing (deleting) the object that the candidate names. If the candidate is
a file name for `icicle-delete-file', then the associated file is deleted by
the action function. In Icicles, you can also provide any multi-command with
a separate deletion action (invoked by `S-delete'), which deletes some
object associated with the candidate (name). Command `icicle-buffer', for
instance, uses `switch-to-buffer' as its action function and
`icicle-kill-a-buffer' as its deletion action - `C-RET' invokes the former
and `S-delete' invokes the latter.

FYI - wrt clicking the `delete' key to remove a candidate - I've recently
defined a complementary feature, to save a candidate for later
consideration. I haven't yet uploaded this feature to the wiki, but I'll do
so soon, after testing things a bit more.

This new feature lets you act more carefully than you might be prone to
using multi-command actions. You can choose a set of candidates (in several
ways, including choosing individual candidates to add) and then, later, take
a good look at that set and then act on all candidates at once. Think of
this as filling out a checklist and then later submitting it for action -
the way that Dired marked files work, for instance. In Icicles, you have
always been able to save the current set of matching candidates (to a
variable or a cache file) and to act on all set members. What I've added
recently is the ability to add additional members to such a saved set
(individually or as a set union).

>     2. It's appropriate, for many commands, to specialize the
>        action behavior during completion. See the commands that
>        explicitly bind `icicle-candidate-action-fn', as opposed
>        to just using `icicle-define-command'. Command
>        `icicle-search', for  instance, could not be
>        defined using `icicle-define-command'.
>
> Can you please explain an example of this specialization?
> Then I can think about its consequences.

It's best to read about what Icicles search offers and how it works, and
then look at the code for `icicle-search' as an example. I'll be glad to
answer questions, but I don't want to repeat here what is already written
elsewhere. Please see the links above.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    You seem bent on automatically converting all commands to multi-commands.
    That might be useful, in a limited way. But programmers will still need to
    be able to define multi-commands that go beyond the simple case. I gave
    `icicle-search' as an example.

Would you please explain what is special about it?

    > The need to replace commands is a complexity, and the code will
    > be much better if we avoid that complexity.

    There is no need to replace any commands. Keep them all.

As you have described it, Icicles replaces the command find-file.  It
does this by defining a new command (Icicle-find-file?) and remapping
remapping find-file to that.

I think this complexity is unnecessary, and I want to try to avoid
installing it.

The only purpose that I know of for defining Icicle-find-file is to
implement multi-command behavior.  Is there any other reason?

I have proposed a modular and clean way to provide the multi-command
behavior, without the need to replace commands in this way.  You said
that my proposal doesn't do the whole job.  Maybe you are right, but I
need you to explain.  What part of the job does it not do?

    No one is against modularity. I have not seen a "proposed implementation",
    beyond some vague hand-waving.

I gave you an outline of the scheme.  Of course I don't have all the
details.  I am trying to work out the details but I need your help.

    However, that needs to be done
    carefully and fully. For example, use of a standalone minibuffer and non-nil
    pop-up-frames should also work.

I expect we can write the code in Fcall_interactively to do TRT in
those cases.  The only way to make sure is to try it.

    I agree about "independent of the specific command that was run", but only
    in the case of run-of-the-mill multi-commands.

Even if this only handles the run-of-the-mill multi-commands, and the
exceptions are handled by your macros, that is still a big
simplification.  And we can continue trying to make this mechanism
better; perhaps we can make it handle more of the commands.

    For some multi-commands you
    want the frame focus to end up in a different place when you are done, for
    example.

Could you tell me about one example?  Maybe I can find a simple
general mechanism to handle this too.

    You might typically work in the buffer of application after using a
    multi-command, or you might instead typically want the minibuffer frame to
    continue to have the focus so you can use it again - different commands have
    different use cases.

Can you tell me about one example of each type, so I can see
why this is so?

    I had my multi-command definition macros available for my own use,
    yet I did not use them to define some of the multi-commands. Why?
    Because they are not flexible enough - they cannot be flexible
    enough. There is no substitute for being able to code what is
    needed in a particular case.

Maybe that is true, but first let's make a reasonable effort to make a
general mechanism handle as much of the job as possible.  Eventually
we may decide to handle a few hard cases with your macros.

    Practically every place where I have used a non-nil value for
    `icicle-use-candidates-only-once' is an example. It is not so much that
    multiple invocation would be harmful (though perhaps that can also be true
    for some commands). It is that, in many cases, it is handy for the user to
    remove the candidate from the list of available candidates, once it has been
    acted on.

We could build that into the low-level mechanism too.  It would be
quite clean.  Fcall_interactively just has to bind a certain variable
to nil, which holds a list of completion alternatives to exclude.
display-completion-list will ignore the alternatives in this list.
Then, each time around Fcall_interactively adds the proper argument
value to this list.

We could control the feature with a character in the interactive spec,
as in

    (interactive "#bDelete Windows of buffer:")

where # specifies using candidates only once.

    FYI - wrt clicking the `delete' key to remove a candidate - I've recently
    defined a complementary feature, to save a candidate for later
    consideration. I haven't yet uploaded this feature to the wiki, but I'll do
    so soon, after testing things a bit more.

These features seem interesting.  I think they can all be implemented
cleanly in Fcall_interactively, but this suggests we might want to make
it call some Lisp code which would handle some of these cases.

    It's best to read about what Icicles search offers and how it works, and
    then look at the code for `icicle-search' as an example. I'll be glad to
    answer questions, but I don't want to repeat here what is already written
    elsewhere. Please see the links above.

I will be glad to read the text you've already written, but finding
that text would be a pain for me.  Could you please email it to me?

RE: propose adding Icicles to Emacs

[Drew Adams]

>     You seem bent on automatically converting all commands to
>     multi-commands. That might be useful, in a limited way. But
>     programmers will still need to be able to define multi-commands
>     that go beyond the simple case. I gave `icicle-search' as an
>     example.
>
> Would you please explain what is special about it?

Ouch! It's a mother. I'd really appreciate it if you'd take a look at the
doc for Icicles search and then take a look at the code for the functions.
It would be a lot easier then to talk about it.

I don't suggest that we need to start by taking all the stuff that
`icicle-search' does into account, but I think it would be a good idea if
you took a look, to see the kind of thing that might be done. IOW, let's
start, as you already have, with the low-hanging fruit (80/20 rule), but you
might want to take a look at the search stuff to get a picture of what's
possible.

I'd also suggest loading Icicles and giving `icicle-search' (`C-c`') a
whirl. It's easier to experience that to read about.

>     > The need to replace commands is a complexity, and the code will
>     > be much better if we avoid that complexity.
>
>     There is no need to replace any commands. Keep them all.
>
> As you have described it, Icicles replaces the command find-file.

No, it doesn't replace it. If I gave that impression then I misspoke. What
it does, if a user so chooses, is remap whatever keys `find-file' is bound
to to `icicle-find-file'. Upon exiting Icicle mode, it undoes this
remapping.

> It does this by defining a new command (Icicle-find-file?) and remapping
> remapping find-file to that.

Yes, it remaps the command's key bindings. The command `find-file' is not
redefined.

> I think this complexity is unnecessary, and I want to try to avoid
> installing it.

Don't install it. I said, "There is no need to replace any commands." I
said:

>   Speaking of replacement is off the mark. Multi-commands and the
>   ability to define them as appropriate for a given use are one
>   thing. Deciding to bind `C-x C-f' to a multi-command file-finding
>   function instead of vanilla `find-file' file is another thing - a
>   separate consideration. Forget the latter, if you will; it's not
>   necessary.

Today, Icicles gives users the option to rebind `C-x C-f' to an Icicles
command instead of `find-file'. We need not give users that option in the
future. And if you build in multi-commandness, then there is absolutely no
reason for such a rebinding - only the new, multi-command implementation of
`find-file' will be needed.

> The only purpose that I know of for defining Icicle-find-file is to
> implement multi-command behavior.  Is there any other reason?

No, that is correct - it is the only reason.

> I have proposed a modular and clean way to provide the multi-command
> behavior, without the need to replace commands in this way.  You said
> that my proposal doesn't do the whole job.  Maybe you are right, but I
> need you to explain.  What part of the job does it not do?

Insofar as I understand it, it would do the whole job for commands such as
`find-file'. Perhaps it could also do the whole job for any multi-commands
that one can define today using macros `icicle-define-command' and
`icicle-define-file-command'. I don't know.

I haven't seen anything concrete, so I'm not sure how you will implement it.
If it does everything that those macros do (or the equivalent), then it will
make every command that calls `completing-read' or `read-file-name' (in the
`interactive' spec at least) into a multi-command, and that will be a good
thing.

I'm not sure how you will proceed, but I'm sure it will be different from
what I do today. The macros define a command of zero args that calls
`completing-read' and applies the action function to the result. The
minibuffer binding of `C-RET' also applies the action funtion to the current
candidate.

IIUC, in your approach, a user defines a command of one or more args, one
arg of which is provided by a call to `completing-read' in the `interactive'
spec (in one way or another). Then, whatever that command does to that arg
in the command body is done to the current completion candidate when you use
C-RET - that is, the entire command body is executed with the current
candidate passed as the parameter. Is that it? And I assume that any other
args keep their same values during this process.

It might be that your approach will do everything that the macros currently
do, just differently. It sounds good to me.

>     No one is against modularity. I have not seen a "proposed
>     implementation", beyond some vague hand-waving.
>
> I gave you an outline of the scheme.  Of course I don't have all the
> details.  I am trying to work out the details but I need your help.

I'll do my best to help where I can.

>     However, that needs to be done
>     carefully and fully. For example, use of a standalone
>     minibuffer and non-nil pop-up-frames should also work.
>
> I expect we can write the code in Fcall_interactively to do TRT in
> those cases.  The only way to make sure is to try it.

Agreed. See below for my concerns about frame focus.

>     I agree about "independent of the specific command that was
>     run", but only in the case of run-of-the-mill multi-commands.
>
> Even if this only handles the run-of-the-mill multi-commands, and the
> exceptions are handled by your macros, that is still a big
> simplification.

No, there is a misunderstanding. My macros, like your proposal, only handle
the run-of-the-mill commands. To be more precise, they might be a bit less
run-of-the-mill than your approach (I'm not sure of your approach), because
they let you bind, in the definition of the action function itself, the
action function etc. for a recursive call to `completing-read' or
`read-file-name'. IOW, they recognize that particular function variable,
`icicle-candidate-action-fn', whereas I'm not sure if your code will (I hope
so).

More generally, to allow a programmer to define a non-run-of-the-mill
multi-command s?he needs to be able to bind:

1. `icicle-candidate-action-fn' - the action function
2. `icicle-candidate-alternative-action-fn' - an alternative action function
3. `icicle-delete-candidate-object' - a deletion action

#1 is necessary to enable `C-RET', that is, to make it a multi-command at
all. With your implementation of multi-commands, some such variable would
still be necessary in the general case, to override use of the command body
for the action function - that is, to provide a different action from what
the command itself performs when you finally choose a candidate once and for
all.

One use case is defining a command that is itself called when defining
another command. The first command might define a default action function if
`icicle-candidate-action-fn' is nil when it is called. The second command
can bind the action function to override the default in the command it
calls. (There was an example of this, but I no longer have one to point to.)

#2 is optional but required if you want to provide an alternative action
(invoked by `C-S-RET' etc.). Icicles search is an example of a command where
you can use the alternative action. The alternative action replaces all or
part of the current search hit. (The main action visits the current search
hit.) It is likely that there would be more Icicles commands in the future
that would provide alternative actions. And a programmer can define custom
commands that have alternative actions.

#3 is optional but required if you want to provide a deletion action
(invoked by `S-delete'). Today, there are several commands that provide a
deletion action. You can bind this variable to either a deletion function or
a variable whose value is a list of candidate objects (the object associated
with the target candidate is deleted from the list variable).

See this page for a description of #2 and #3:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_More_About_Multi-Commands.

See this page for a description of Icicles search-and-replace using the
alternative action:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Search-And-Replace

In sum, I think your approach will handle most cases. It might handle all
cases handled by the macros. In the general case, a user would be able to
bind the variables to arbitrary functions and define an arbitrary command
that makes use of multi-commandness beyond the interactive spec.

> And we can continue trying to make this mechanism
> better; perhaps we can make it handle more of the commands.

I'm not against such an effort. In fact, I find it interesting. My current
assessment is that it is important for programmers to be able to specify an
arbitrary function for #1.  #2 and #3 could be considered nice-to-haves, but
#2 is needed for Icicles search, unless that is built in somehow. Whether
everything interesting can be cantoned to the `interactive' spec, I don't
know. I'd like to be able to bind #1, #2, and #3 in an arbitrary context and
call `completing-read' with those bindings current, to be able to use the
different actions during completion.

BTW, I should also mention that Icicles (optionally, but by default) uses a
multi-command version of `execute-extended-command'. This code is a bit
hairy. I think this feature is useful, but you might want to forego it if it
is too complicated to implement in your design. You might be interested to
take a look anyway. Perhaps you will see a way to do it in your approach, or
perhaps it will inspire other thoughts. At least, the example it will give a
flavor of using multi-command actions.

The code is in icicles-cmd.el. The description is here:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Multi_M-x.

[BTW - I understand that you don't often have Web access. The complete doc
(the same as is on the wiki) is also in files icicles-doc1.el and
icicles-doc2.el in plain-text form (not HTML). The section headings are
pretty much the same as the wiki page headings (URLs). So, for example,
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Multi_M-x corresponds to
section "Icicles Multi `M-x'", in file icicles-doc1.el. So you can read up
on this stuff if you are interested.]

>     For some multi-commands you
>     want the frame focus to end up in a different place when you
>     are done, for example.
>
> Could you tell me about one example?  Maybe I can find a simple
> general mechanism to handle this too.

Let's not worry about this now. I'm not sure there will be a problem. What's
probably the most important about this is written further below.

>     You might typically work in the buffer of application after using a
>     multi-command, or you might instead typically want the
>     minibuffer frame to continue to have the focus so you can use it
>     again - different commands have different use cases.
>
> Can you tell me about one example of each type, so I can see
> why this is so?

I can't now. I spent a while looking, but I can't seem to find what I
thought I'd find.

I think the general situation is this. It's easiest to follow if you think
of pop-up-frames being non-nil, with a standalone minibuffer.

1. You invoke a multi-command.

2. You use `C-RET' on candidates. Each action might pop up a buffer in a
different frame, giving it the focus - which is what you want in this case
(often).

3. If you use C-g, then you typically want to return to the original
buffer/frame.

4. You hit RET to finally choose a buffer/frame. You typically want the
focus to end up there.

You might, for #3 or #4, want the focus to be different, but I don't have a
concrete example.

I think perhaps what I was thinking of was that in defining action functions
I sometimes need to put a `select-frame-set-input-focus' in the action
function, either to force the focus to a frame associated with the current
candidate or, on the contrary (and more typically), to force the focus to
the minibuffer in preparation for another `C-RET'.

If that is in fact the only use for this, then perhaps there is no problem.
Presumably, your code would (1) keep the focus on the minibuffer and its
frame during completion (i.e. for each `C-RET'), (2) leave the focus
wherever the final `RET' found it or put it, and (3) put the focus back on
the original buffer/frame in case of C-g or error.

In some places, such as the multi `M-x', I do a few weird things perhaps,
because I want the `C-RET' context to be just like a top-level context. But
that might be irrelevant, and in any case it is not something to worry about
now.

>     I had my multi-command definition macros available for my own use,
>     yet I did not use them to define some of the multi-commands. Why?
>     Because they are not flexible enough - they cannot be flexible
>     enough. There is no substitute for being able to code what is
>     needed in a particular case.
>
> Maybe that is true, but first let's make a reasonable effort to make a
> general mechanism handle as much of the job as possible.  Eventually
> we may decide to handle a few hard cases with your macros.

That sounds good to me. I think it would probably be advisable to at least
have your basic handling respect bindings for an action, alternative action,
and deletion functions. If that's available, then I think most of the
flexibility needed will be provided. IOW, if your mechanism provides what
the macros provide, then we're off to a good start.

>     Practically every place where I have used a non-nil value for
>     `icicle-use-candidates-only-once' is an example. It is not so
>     much that multiple invocation would be harmful (though perhaps
>     that can also be true for some commands). It is that, in many
>     cases, it is handy for the user to remove the candidate from
>     the list of available candidates, once it has been acted on.
>
> We could build that into the low-level mechanism too.

That sounds good.

> It would be
> quite clean.  Fcall_interactively just has to bind a certain variable
> to nil, which holds a list of completion alternatives to exclude.
> display-completion-list will ignore the alternatives in this list.
> Then, each time around Fcall_interactively adds the proper argument
> value to this list.

But would the value still really be one of the possible completions, so that
if you hit TAB or S-TAB again during the same invocation of
`completing-read' it would show up again? That is the current behavior, and
the behavior I prefer. Or else at least have some way to get that removed
candidate back without starting all over. I want users to be able to do as
much as possible on the fly, in the same invocation of `completing-read'.

> We could control the feature with a character in the interactive spec,
> as in (interactive "#bDelete Windows of buffer:")
> where # specifies using candidates only once.

That's fine, but for me that's getting ahead of ourselves at this point. If
it helps you think about it, good.

>     FYI - wrt clicking the `delete' key to remove a candidate -
>     I've recently defined a complementary feature, to save a
>     candidate for later consideration. I haven't yet uploaded
>     this feature to the wiki, but I'll do
>     so soon, after testing things a bit more.

FYI - I uploaded this new feature yesterday. I intend to change the binding
(to `insert' from `C-insert'), but I've spent too much time on these emails!

> These features seem interesting.  I think they can all be implemented
> cleanly in Fcall_interactively, but this suggests we might want to make
> it call some Lisp code which would handle some of these cases.

I'm in favor of Emacs doing stuff in Lisp, because I want to be able to hack
it, and I don't hack C code (no fun for me, need to compile and build,
etc.). I understand that doing stuff in C is good for performance. For me,
this is a bit of an area of experimentation (UI experimentation), so I'd
like to keep stuff in Lisp as much as possible, to let people explore and
extend the ideas. That's just me.

BTW, wrt using literal `interactive' specs (as opposed to a sexp that's
eval'd in list arg to `interactive') - I've been advising Icicles users who
write multi-commands (my implementation, not yours) not to use literal
specs, because then using `M-*' (progressive completion: multiple match
patterns) will require users to hit RET to exit each recursive minibuffer
level separately. That is, because I put a `catch' in my version of
`completing-read' and `read-file-name', when a user makes a final completion
choice after using `M-*' I can throw the chosen value to the top. If a
programmer instead uses a literal `interactive' spec then my
`completing-read' code doesn't get called.

This wouldn't be a problem for your code. You could make sure that
`interactive' DTRT for a recursive minibuffer within `completing-read' etc.
Just want to point out this use case.

An alternative would be to implement `M-*' differently, and not use a
recursive call to `completing-read' at all. In my implementation of `M-&',
for instance, which is another form of progressive completion that lets you
add predicates on the fly to narrow completion choices, I don't use a
recursive call to `completing-read'. Instead, I modify the current
`completing-read' predicate and then complete again (as in implicit TAB or
S-TAB). I'm just pointing out that there might be different approaches for
this kind of thing.

>     It's best to read about what Icicles search offers and how it
>     works, and then look at the code for `icicle-search' as an
>     example. I'll be glad to answer questions, but I don't want
>     to repeat here what is already written
>     elsewhere. Please see the links above.
>
> I will be glad to read the text you've already written, but finding
> that text would be a pain for me.  Could you please email it to me?

See above: the doc is all in files icicles-doc1.el and icicles-doc2.el. Do
you need me to email you the source files, or can you get them from Emacs
wiki? On the wiki, the files are here, as well as easy ways to download them
all: http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Libraries.

It would help if you would read up some. It would sure cut down the needed
back and forth by email. This is killing me. I can't imagine that anyone
else is reading any of this. Also, if you want, we can take some of this off
line if you think it bothers more than interests others.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    I think the general situation is this. It's easiest to follow if you think
    of pop-up-frames being non-nil, with a standalone minibuffer.

    1. You invoke a multi-command.

    2. You use `C-RET' on candidates. Each action might pop up a buffer in a
    different frame, giving it the focus - which is what you want in this case
    (often).

    3. If you use C-g, then you typically want to return to the original
    buffer/frame.

    4. You hit RET to finally choose a buffer/frame. You typically want the
    focus to end up there.

It seems straightforward to implement that.  You make the command
switch to the new frame, and we just have to make sure C-g goes back
to the original frame.

    I sometimes need to put a `select-frame-set-input-focus' in the action
    function, either to force the focus to a frame associated with the current
    candidate or, on the contrary (and more typically), to force the focus to
    the minibuffer in preparation for another `C-RET'.

With my approach, the minibuffer mechanism will put the focus on the
minibuffer each time it is reentered.

    > It would be
    > quite clean.  Fcall_interactively just has to bind a certain variable
    > to nil, which holds a list of completion alternatives to exclude.
    > display-completion-list will ignore the alternatives in this list.
    > Then, each time around Fcall_interactively adds the proper argument
    > value to this list.

    But would the value still really be one of the possible completions, so that
    if you hit TAB or S-TAB again during the same invocation of
    `completing-read' it would show up again?

Right.  It would still be in the completion list, but it would
be excluded from buffers that show the completions.

    See above: the doc is all in files icicles-doc1.el and icicles-doc2.el. Do
    you need me to email you the source files, or can you get them from Emacs
    wiki?

Can you email me just the relevant documentation from those files?

RE: propose adding Icicles to Emacs

[Drew Adams]

> It seems straightforward to implement that.  You make the command
> switch to the new frame, and we just have to make sure C-g goes back
> to the original frame.

Yes, I agree, and said that. I'm not 100% sure that this typical sequence is
always all there is, but let's go with it, at least for now. If there are
complications then we can figure out what to do later.

>     I sometimes need to put a `select-frame-set-input-focus' in the action
>     function, either to force the focus to a frame associated
>     with the current candidate or, on the contrary (and more typically),
>     to force the focus to the minibuffer in preparation for another
`C-RET'.
>
> With my approach, the minibuffer mechanism will put the focus on the
> minibuffer each time it is reentered.

Yes, I realize that. That's why I said that I think my need to force TRT
will go away with a lower-level implementation.

>     But would the value still really be one of the possible
>     completions, so that
>     if you hit TAB or S-TAB again during the same invocation of
>     `completing-read' it would show up again?
>
> Right.  It would still be in the completion list, but it would
> be excluded from buffers that show the completions.

Until you explicitly ask for completion again, right? (Just rephasing the
same question, to be sure.)

>     See above: the doc is all in files icicles-doc1.el and
>     icicles-doc2.el. Do you need me to email you the source files, or
>     can you get them from Emacs wiki?
>
> Can you email me just the relevant documentation from those files?

I will mail you just the doc files. I'm not sure which parts you feel are
relevant. Do you already have the code? Do you intend to look at the code?

Re: propose adding Icicles to Emacs

[Richard Stallman]

    >     But would the value still really be one of the possible
    >     completions, so that
    >     if you hit TAB or S-TAB again during the same invocation of
    >     `completing-read' it would show up again?
    >
    > Right.  It would still be in the completion list, but it would
    > be excluded from buffers that show the completions.

    Until you explicitly ask for completion again, right? (Just rephasing the
    same question, to be sure.)

Yes.

Re: propose adding Icicles to Emacs

[Juri Linkov]

> The complete doc (the same as is on the wiki) is also in files
> icicles-doc1.el and icicles-doc2.el in plain-text form (not HTML).

Why did you write the documentation for the Icicles package as comments in
two Emacs Lisp files that have no Lisp code instead of writing it in Texinfo?

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

RE: propose adding Icicles to Emacs

[Drew Adams]

> > The complete doc (the same as is on the wiki) is also in files
> > icicles-doc1.el and icicles-doc2.el in plain-text form (not HTML).
>
> Why did you write the documentation for the Icicles package as comments in
> two Emacs Lisp files that have no Lisp code instead of writing it
> in Texinfo?

Because it was easier for me, including easier to transfer to wiki pages.
I'm not set up on Windows to write texinfo, and this is OK for now.

The doc was originally in the main file that loads the others, but that
became too big for a wiki upload, so I split it in two.

Re: propose adding Icicles to Emacs

[Richard Stallman]

A single unified Texinfo manual for Icicles is not what we want
anyway.

Since these are really a bunch of separate features, the documentation
for those features that we install will belong in different places in
the Emacs Manual.  

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Icicles does not use advice. Well, there is one tiny exception, which could
    be replaced:

    (defadvice next-history-element

What job does this advice do?

    If Icicles were integrated with Emacs, either `next-history-element' itself
    could be patched to be Icicles-aware or, if that is a no-no, Icicles could
    redefine `next-history-element' for `icicle-mode' use only.

Redefining such a function is almost as bad as advising it.
The goal is to avoid both such methods.

								All this code
    does, BTW, is preselect part of the current candidate in the minibuffer, for
    easy manipulation or deletion. This preselection is optional.

I don't understand "preselect" in this context.  Can you explain?

RE: propose adding Icicles to Emacs

[Drew Adams]

>     Icicles does not use advice. Well, there is one tiny
>     exception, which could  be replaced:
>
>     (defadvice next-history-element
>
> What job does this advice do?

I explained that a few lines further, which you quoted below.

>     If Icicles were integrated with Emacs, either
>     `next-history-element' itself could be patched to be
>     Icicles-aware or, if that is a no-no, Icicles could
>     redefine `next-history-element' for `icicle-mode' use only.
>
> Redefining such a function is almost as bad as advising it.
> The goal is to avoid both such methods.

I share the goal of avoiding redefining and advice. When you are working
outside the Emacs sources, you are sometimes forced to do one or the other.

> 	All this code does, BTW, is preselect part of the current
>     candidate in the minibuffer, for easy manipulation or
>     deletion. This preselection is optional.
>
> I don't understand "preselect" in this context.  Can you explain?

User option `icicle-init-value-flag', if non-nil, copies the default value
for completion to the minibuffer as an initial value. In that case, the
option also determines whether the initial value is preselected (region)
and, if so, where point and mark should be positioned.

People have different preferences. This has an importance especially if you
use delete-selection mode, where you can simply type to replace or delete
the active region.

These are the values for the option:

(choice
 (const :tag "Do not insert default value as initial value"
        nil)
 (const :tag "Insert (and leave cursor at end)"
        insert)
 (const :tag "Insert, preselect, and leave cursor at beginning"
        preselect-start)
 (const :tag "Insert, preselect, and leave cursor at end"
        preselect-end))

The default value of the option is nil. I personally use the value `insert',
which does not preselect any text.

BTW - a related feature exists for the current candidate, which is inserted
in the minibuffer during cycling. You can act on that candidate or edit its
text.

Two user options determine where to place point and mark wrt that minibuffer
input. Again, this has an importance especially for delete-selection mode.

These are the values for the mark position. Similarly for point.

(choice
 (const :tag "Leave mark at the beginning of the minibuffer input"
        input-start)
 (const :tag "Leave mark at the end of the minibuffer input"
        input-end)
 (const :tag "Leave mark at the beginning of the completion root"
        root-start)
 (const :tag "Leave mark at the end of the completion root"
        root-end))

"Root" refers to the common substring for all currently matching candidates.
"Input" refers to the complete minibuffer input. You can place point or mark
at the beginning or end of the root being completed or you can place point
or mark at the beginning or end of the entire minibuffer input.

You can thus make the region include all of the input, only the root, from
beginning to root, or from root to end.  You can put the cursor at either
end of the region.  You can make the region empty, by making point and mark
coincide (at any of the possible positions). These possibilities exist
because different people can have different preferences for minibuffer
input.

Icicles selects part of the minibuffer input according to these options.
Vanilla emacs does not provide candidate cycling, where the current
candidate becomes the entire minibuffer input. So vanilla Emacs cannot use
such a text-selection feature.

Re: propose adding Icicles to Emacs

[Stefan Monnier]

I think it would be good to include Icicles in Emacs.
Clearly, we wouldn't want to enable it by default since it changes the
behavior too much for many people's tastes, but just like iswitchb and ido
I think it's a valuable extension.


        Stefan

Re: propose adding Icicles to Emacs

[Richard Stallman]

    I think it would be good to include Icicles in Emacs.
    Clearly, we wouldn't want to enable it by default since it changes the
    behavior too much for many people's tastes, but just like iswitchb and ido
    I think it's a valuable extension.

It sounds like Icicles contains many good features that should be installed.
Perhaps all of them.  But we should not keep them as a bundle simply because
they are offered to us as a bundle.  We should separate them if they make
more sense separately, and keep them unified if they make more sense unified.

At least one should be implemented differently: multi-commands.
I explained how it is possible to simplify this tremendously
if you don't insist on doing the work at the Lisp level.

I don't know all the features in Icicles.  Perhaps other such
simplifications are possible, or perhaps not.  Someone needs to check.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     I think it would be good to include Icicles in Emacs.
>     Clearly, we wouldn't want to enable it by default since it changes the
>     behavior too much for many people's tastes, but just like
>     iswitchb and ido I think it's a valuable extension.
>
> It sounds like Icicles contains many good features that should be
> installed. Perhaps all of them.  But we should not keep them as a
> bundle simply because they are offered to us as a bundle.  We
> should separate them if they make more sense separately, and keep
> them unified if they make more sense unified.

Fine as a generalization. I don't disagree with the logic, including the
"simply because", "if", and "if". Where do we go from here?

Let me be clear about my position. I see two possibilities, A and B. I
prefer A, but I can also live with B.

Plan A -

My suggestion is to proceed in two stages: 1) take Icicles (i.e. add it to
Emacs) as a bundle now, offering it to general Emacs users as a separate,
optional package with its current functionality and design, and 2) later,
examine parts of Icicles that might usefully be peeled off and added to
vanilla Emacs itself, starting with the low-hanging fruit that doesn't shake
the entire tree (either Emacs or Icicles).

There is no reason that Icicles and Emacs cannot live together as each is
now, even if there might be some potential to make each even better by some
careful simplification, merging, or whatever in the future.

For stage #1, the immediate process of package addition and the period of
cohabitation that I propose, I am willing to do some minor cleanup, _if_ it
is clear to me what is required and _if_ it doesn't jeopardize the correct
functioning of Icicles. I'll consider such changes on a case by case basis,
and only _if_ someone works with me to make clear what is needed. I strongly
suggest that we make only minimal changes that are truly needed to added
Icicles as a separate package (stage #1).

Plan B -

An alternative (to my two-stage proposal, plan A), which I do not prefer but
which could also be workable for me, is for you not to add Icicles to Emacs,
but to instead take some of its ideas and add them in your own manner to
Emacs. That too works for me. In that case, I'll keep Icicles, and you can
borrow ideas from it if you like. That way, you will be clear and content
about what you get and how you implement it, and I won't have the discomfort
about not understanding what you want changed, or the risk of breaking
something because you've asked for changes that are not sufficiently thought
out. I will of course be available to answer questions about the existing
Icicles features and their implementation. And you can take pieces of
existing Icicles code, if you like. _You_ can take - I won't be chopping up
Icicles in this scenario.

I would prefer plan A - to let general Emacs users take advantage now of all
of Icicles, as they do Ido and Iswitchb, to experiment with it, provide
feedback on how its parts fit well together or don't, etc. But if you prefer
plan B, to treat Icicles only as a quarry of ideas, taking some ideas here
and there or not, that's OK by me too. I will continue to develop Icicles
separately, and if a piece of it ultimately becomes superfluous because
Emacs has implemented something similar, I can then remove it from Icicles.
Plan B admittedly has the advantage of going beyond the throw-away
prototype, doing things better the second time around.

If you choose plan B, I would ask only that you try to proceed in a way that
will not make it difficult for people to use Icicles with Emacs in the
meantime. For example, if you start adding a different kind of multi-command
functionality, please do so in a way that won't conflict too much with using
Icicles. That might not be easy or obvious, but if we work together and stay
mutually informed, things could be worked out. I'm not demanding that you
don't break anything for Icicles - I'm only asking for consideration and
cooperation. For now, Emacs does not do much with the minibuffer and Icicles
does a lot. Icicles uses lots of new minibuffer bindings, for instance. If
Emacs starts using lots of minibuffer bindings that conflict, then let's
agree to try to work something out.

I'm offering Emacs the ideas of Icicles - and the design and implementation
too, if you want it. I hope you can offer cooperation in return. I'd like to
see, in order of preference: either (plan A) Icicles working inside Emacs or
(plan B) Icicles working outside Emacs (in the sense that it is now
"outside"). I don't want to see Icicles no longer working anywhere because
it has been dismembered beyond use within Emacs or because Emacs has built
up its own features that prevent it from working.

> At least one should be implemented differently: multi-commands.
> I explained how it is possible to simplify this tremendously
> if you don't insist on doing the work at the Lisp level.

You explained no such thing. You asked "how does it know what to call?", "is
it the same command?", etc. You asked if every command couldn't be
automatically converted to a multi-command. I responded to all of this in
detail - you have not replied to any of that. You rather cavalierly proposed
a different implementation of a feature whose description you were not yet
clear about and were therefore still asking about. I explained more about
the feature, and I asked you for more detail about your vague redesign - no
reply.

I explained that I don't want to redesign or to reimplement the basic
design. I said that if others wish to do that, later (phase #2 of plan A),
then that's another matter. I recommend plan A: leaving the basic design and
implementation as they are now, adding the package now, possibly with some
minor modifications to fit standards or preferences, and then, perhaps,
revisiting design and implementation questions bit by bit later.

Once Icicles has been added to Emacs (plan A), IIUC, there are two
possibilities: (1) I continue to maintain it for Emacs (within Emacs), or
(2) someone else does that. I would prefer to maintain it myself, as I
intend to do so anyway, for my own version.

However, if Emacs developers want to rework the code extensibly, then that
is possible - after Icicles belongs to FSF, and at that point my
participation in the maintenance might diminish or dry up altogether. I have
nothing against performing some of the functionality in C, for instance, but
I will not work on that C code myself (you will be glad of that!). Once you
own it, you can break it as you like (to twist the Pottery Barn aphorism a
bit).

If someone wants to seriously take a look at reworking parts of the package,
I'm willing to spend some time working with that person or persons. But I
will not take some vague directive to go off and redo things, and then come
back to you hoping that things might have been understood and reworked to
your satisfaction. I don't read minds, among other things. In sum, either
you do it or I do it, and if I do it then I need to understand precisely
what "it" is, and I want to agree that "it" really should be done.

I am not saying "take it as is or leave it". I'm proposing a couple of
different ways you can take it. I'm saying that if there are changes you
think should be made, then let's discuss them _in detail_ first. And I'm
strongly recommending not to touch the basic structure of the code - at
least not for a while. Let users use it as it was intended, and let its
evolution and improvement be gradual, informed, and _deliberate_.

> I don't know all the features in Icicles.  Perhaps other such
> simplifications are possible, or perhaps not.  Someone needs to check.

Someone needs to take it seriously, one way or the other. Not knowing all of
the features is OK at this point, but it is not OK to redesign without
knowing all of the features and how they work together. (But you have the
option of plan B.)

I'll consider concrete suggestions of any nature, but I will be reluctant to
slash willy nilly and reconstruct. I've said it before; it should be quite
clear now. It won't happen on my watch, and without me understanding what it
is.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    My suggestion is to proceed in two stages: 1) take Icicles (i.e. add it to
    Emacs) as a bundle now, offering it to general Emacs users as a separate,
    optional package with its current functionality and design,

I have explained already why this is a bad idea.
It is not an option, because it adds a lot of unmodular code.

Icicles was implemented as an add-on, and to work with no changes
at the C level.  The right way to implement the features in Emacs
is different.

    An alternative (to my two-stage proposal, plan A), which I do not prefer but
    which could also be workable for me, is for you not to add Icicles to Emacs,
    but to instead take some of its ideas and add them in your own manner to
    Emacs.

In effect, you have declined to help with installing these features in
the right way.  I'm disappointed, but we can't make you do it.

We'll just have to see whether other people decide to do it.

There is another option: start with Icicles, rework it until its
implementation is clean and modular, and install that.  For some of
the features, this may be easier.  It too will wait for volunteers,
though.

    You explained no such thing. You asked "how does it know what to call?", "is
    it the same command?", etc. You asked if every command couldn't be
    automatically converted to a multi-command. I responded to all of this in
    detail - you have not replied to any of that.

That may have been true at the time you wrote it.  It takes a long time
for me to answer mail.  My response to that message went out in the same
transfer in which your premature rebuke came in.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     My suggestion is to proceed in two stages: 1) take Icicles
>     (i.e. add it to Emacs) as a bundle now, offering it to
>     general Emacs users as a separate, optional package with
>     its current functionality and design,
>
> I have explained already why this is a bad idea.
> It is not an option, because it adds a lot of unmodular code.

Are you sure that that code cannot be made modular enough to be added,
without breaking the basic design and starting over from scratch? Have you
actually looked at the code? I'm not suggesting you haven't; I'm just
curious whether your idea of how unmodular it is comes only from reading
email or from actually looking at the code.

> Icicles was implemented as an add-on, and to work with no changes
> at the C level.  The right way to implement the features in Emacs
> is different.

Can't argue against that generality.

>     An alternative (to my two-stage proposal, plan A), which I do
>     not prefer but which could also be workable for me, is for
>     you not to add Icicles to Emacs, but to instead take some of
>     its ideas and add them in your own manner to Emacs.
>
> In effect, you have declined to help with installing these features in
> the right way.  I'm disappointed, but we can't make you do it.
>
> We'll just have to see whether other people decide to do it.

Please read what you just quoted, and then read what you wrote just after
it.

What you quoted is a restatement of what I understand to be your position
now: you don't want to add Icicles to Emacs, but, instead, you want to "take
some of its ideas and add them in your own manner to Emacs". Or, in your own
words, "The right way to implement the features in Emacs is different." So,
if you interpret my phrasing of that as non-cooperation, then you should
also interpret your own phrasing of it in the same way. We are, I believe,
saying the same thing.

Why are you trying to twist what I wrote into a statement of refusal to
cooperate or participate? That guilt trip is unjustified, and it doesn't
work with me. "Take some of its ideas and add them in your own manner" is
_exactly_ what you propose, no? Where is the non-cooperation on my part in
that statement?

I think we are talking about the same proposal, which I called plan B:
abandoning the design of Icicles, since it was made as an add-on, and
starting over to implement the features in Emacs differently. I've said that
that works OK for me, though I prefer plan A. I repeat: I'm OK with plan B.

In fact, I agree that, if done right, the result of plan B could be better.
Icicles is a prototype, if you like, and there is nothing wrong with tossing
it and making a fresh start, keeping some of the ideas in mind. (However, as
I said, as long as Emacs does not offer equivalent functionality, I'll also
continue to offer Icicles separately as an add-on.)

> There is another option: start with Icicles, rework it until its
> implementation is clean and modular, and install that.  For some of
> the features, this may be easier.  It too will wait for volunteers,
> though.

It will at least wait for a clear picture of what is meant by that. "Go out
and make it modular" is not helpful to me.

I offered (plan B) my ideas or (plan A) my ideas plus my design and
implementation. I said I preferred plan A, but plan B is OK too.

Plan A: Recognizing that there is a lot of code and that there is some risk
of breaking things when modifying it, I stated that it is better for plan A
to be done in two stages, the second of which can tightly integrate Icicles
features with Emacs, and the first of which would stay closer to the current
design, to proceed conservatively. Stage 1 would be more or less my existing
design; stage 2 would be whatever you want. In stage 1, Icicles would be
sure to work well, and would remain encapsulated, as it is now. In stage 2,
Icicles could be dismembered and abandoned, possibly with some parts moved
inside Emacs.

Obviously, Icicles is an add-on now. I did not try to modify standard Emacs
source files. Recognizing that moving Icicles to Emacs in any way would mean
removing some of the add-on aspects and doing things directly in the source
code, I offered, for plan A, to clean up my implementation to some extent
(keeping the basic design): "_if_ it is clear to me what is required and
_if_ it doesn't jeopardize the correct functioning of Icicles...
consider[ing] such changes on a case by case basis, and only _if_ someone
works with me to make clear what is needed."

It should be clear from my emphasis here that: (1) I am offering to clean up
the code, (2) I am reluctant to dismember everything at once, for fear of
breaking things, and (3) I don't want to receive only some nebulous
direction "all you have to do is..." - I want to know exactly what changes
are requested, and I want to understand those proposed changes. That's
important for plan A, where it is mainly I who would be doing the cleanup
and it is my design that must be kept working after the cleanup. Do not tell
me simply, "Clean it up, bring it back, and I'll let you know if it's clean
enough." For the plan-A cleanup to work, I need to know what changes need to
be made.

Plan B: If the design and implementation are to be completely different,
however, then my _existing_ contribution is reduced to some of my ideas
which you might want to choose - plan B. That too works for me. I said I
would be available for questions and discussion, but if you choose to
redesign and re-implement, then you don't need my existing design or
implementation. I have not said that I won't help in any way beyond
discussion.

What I did say was that in that case (plan B), you are the one deciding what
is to be done and how. You are then in charge of dismembering, designing and
implementing - it is your responsibility. In that scenario, there is no
special need for me beyond consultation - others are probably better
implementors, in any case. However, if you have specific requests for design
or code on my part, then we can see how that goes.

Just as in plan A, I have the concern that any directions from you be
specific and understandable. I have not gotten a good impression in that
regard so far, frankly. I've tried to point to specific code and details, to
discuss how the implementation could be cleaned up for integration, and the
response was cloudy talk of magic solutions, vague mention that you know how
things can be done in a better way. Nothing wrong with your having the
answers in your head, but I don't read minds well, so if you want help from
me for your plan then you will need to find a way to better communicate your
idea.

It's not complicated, I think. There may be many possible ways to proceed,
but I see two main alternative directions: (1) you have your own idea and
are not very interested in the details of what the features are now, how
they work together, and how they are implemented, in which case you are
directing a new construction site from scratch, or (2) you would like to use
my ideas of the features and design, and work with me to get them added to
Emacs. Possibly with some modification - I'm not rigid; my concerns are (a)
not breaking or losing things horribly, and (b) knowing clearly what it is
that you are requesting.

In the first case (1), you don't especially need me or my implementation of
Icicles; you just need bodies (and perhaps some clarification from me of my
ideas). In the second case (2), we need to find a way to adapt the existing
design and implementation, where need be, for the best integration possible
without breaking things.

However, let me be clear that for #1, which is plan B, I remain interested
in Emacs, as always, and I would look forward to discussing how to design
and implement these features, if that participation is welcome. I am
interested in both Emacs and (obviously) ideas related to those that are
used in Icicles. If, in your new construction, you want to know more about
what exists in Icicles, or if you want to know my thoughts about your plans
and implementation, or if you want to know any new, related ideas I might
have, I'll be happy to participate. I am not dropping out in plan B. I am
saying only that it is your construction site.

Now, I would like very much to get back to discussing the _particulars_ of
what might be done, regardless of the approach you choose. Show me, for
instance, what you intend to do for the magic multi-command code, and let's
get back to talking about the details of what works and what doesn't.

>     You explained no such thing. You asked "how does it know what
>     to call?", "is it the same command?", etc. You asked if every
>     command couldn't be automatically converted to a multi-command.
>     I responded to all of this in detail - you have not replied to
>     any of that.
>
> That may have been true at the time you wrote it.  It takes a long time
> for me to answer mail.  My response to that message went out in the same
> transfer in which your premature rebuke came in.

See my reply to your later mail. As I said there, I still don't see an
explanation of your "magic" in your later mail. Your description of what you
intend is too vague for me to understand it.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Are you sure that that code cannot be made modular enough to be added,
    without breaking the basic design and starting over from scratch?

I am absolutely sure that my implementation of multi-command behavior
is much cleaner.  Replaceing a standard command is undesirable, so I
would like to minimize the number of commands that we need to replace.

    > The only purpose that I know of for defining Icicle-find-file is to
    > implement multi-command behavior.  Is there any other reason?

    No, that is correct - it is the only reason.

That's what I thought.  Therefore, my approach to multi-command
behavior will eliminate the need for many of Icicle's substitutes for
standard commands.

So I propose two things to be done in parallel:

* Implement multi-command behavior at the level of Fcall_interactively.

* Make a version of Icicles that doesn't define Icicle-find-file
and the other simple replacements (which are just for the purpose
of the multi-command feature).

    #1 is necessary to enable `C-RET', that is, to make it a multi-command at
    all. With your implementation of multi-commands, some such variable would
    still be necessary in the general case, to override use of the command body
    for the action function - that is, to provide a different action from what
    the command itself performs when you finally choose a candidate once and for
    all.

Can you explain some _specific_ reasons why that is needed?
Becuase it seems to me we can probably do without it.

    One use case is defining a command that is itself called when defining
    another command. The first command might define a default action function if
    `icicle-candidate-action-fn' is nil when it is called. The second command
    can bind the action function to override the default in the command it
    calls. (There was an example of this, but I no longer have one to point to.)

That is rather abstract and I find I just can't follow it.

    2. `icicle-candidate-alternative-action-fn' - an alternative action function
    3. `icicle-delete-candidate-object' - a deletion action

The easiest way to handle these is to use properties of the
command symbol, `minibuffer-alt-action', `minibuffer-delete-action'.
So we could do

 (put 'find-file 'minibuffer-delete-action 'delete-file)

S-delete would be defined to look for that property on this-command
to decide what to do.

We could implement the equivalent of `icicle-candidate-action-fn'
easily in the same way.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     Are you sure that that code cannot be made modular enough to be added,
>     without breaking the basic design and starting over from scratch?
>
> I am absolutely sure that my implementation of multi-command behavior
> is much cleaner.  Replaceing a standard command is undesirable, so I
> would like to minimize the number of commands that we need to replace.

Which command replacement are we talking about? I already detailed what
would be needed for `completing-read' and all of the other functions Icicles
that redefines. Those things I mentioned that cannot be foregone would need
to be done anyway, irrespective of multi-commands.

Apparently I still haven't made myself clear: Icicles replaces no commands.
It simply _rebinds_ some keys (and only if a user asks it to). This is about
command remapping, which is about key bindings. There is nothing unclean
about command remapping.

I think you mean to say that your approach would provide some multi-command
behavior without the need to define some multi-commands. I agree that that
would be a good thing, if that's what you're referring to here by "commands
that we need to replace."

I just want to be clear that we do _not_ need to replace any commands. _If_
you want `find-file' to act as a multi-command, then, in Icicles, you need
to define a multi-command for that. In your approach, IIUC, `find-file'
itself (and all commands that use completion in their interactive specs)
would automatically be a multi-command. And, as I've said before, that is a
good thing: I support your idea, IIUC.

>     > The only purpose that I know of for defining Icicle-find-file is to
>     > implement multi-command behavior.  Is there any other reason?
>
>     No, that is correct - it is the only reason.
>
> That's what I thought.  Therefore, my approach to multi-command
> behavior will eliminate the need for many of Icicle's substitutes for
> standard commands.

See above. You are phrasing the situation wrong (Icicles does not need to
substitute any standard commands), but I have no problem with what I think
you're really trying to say (see above).

> So I propose two things to be done in parallel:
>
> * Implement multi-command behavior at the level of Fcall_interactively.
>
> * Make a version of Icicles that doesn't define Icicle-find-file
> and the other simple replacements (which are just for the purpose
> of the multi-command feature).

Sounds good to me.

>     #1 is necessary to enable `C-RET', that is, to make it a
>     multi-command at all. With your implementation of
>     multi-commands, some such variable would
>     still be necessary in the general case, to override use of
>     the command body for the action function - that is, to
>     provide a different action from what the command itself
>     performs when you finally choose a candidate once and for
>     all.
>
> Can you explain some _specific_ reasons why that is needed?
> Becuase it seems to me we can probably do without it.

We can do without anything, of course. I already explained this and gave
examples. If you want to forego such features and have only a limited form
of multi-commands, then that's your decision.

I argued for adopting your implementation approach but also letting people
bind the 4 kinds of actions around any calls to completion functions (e.g.
`completing-read'): 1) action, 2) alternative action, 3) deletion, 4)
candidate help.

IIUC, your implementation limits a multi-command to using completion in the
`interactive' spec, and (so far), it does not let you provide specific
functions for the 4 possible multi-command actions.

>     One use case is defining a command that is itself called when defining
>     another command. The first command might define a default
>     action function if `icicle-candidate-action-fn' is nil when it is
>     called. The second command can bind the action function to
>     override the default in the command it calls. (There was an
>     example of this, but I no longer have one to point to.)
>
> That is rather abstract and I find I just can't follow it.

`icicle-search' provides for this, but there is today no command defined
using `icicle-search' that takes advantage of it. This is what `icicle
search' does:

(let ((icicle-candidate-action-fn
       (or icicle-candidate-action-fn 'icicle-search-action))
      (icicle-candidate-help-fn 'icicle-search-help)
      (icicle-update-input-hook
       (list 'icicle-search-highlight-all-input-matches)))

The binding of `icicle-candidate-action-fn' here lets a caller of
`icicle-search' bind its own action function, to override the default one,
`icicle-search-action'. There was a command that did that previously, but
there is none currently.

You can also see here an example of binding a candidate-help function that
is specific to this command (`icicle-search'). Icicles provides help on
individual candidates you choose (e.g. with `C-M-RET'), and a default help
function does that. It works quite well for lots of kinds of candidates, but
you might want, in your command, to define a specialized help function -
that's what `icicle-search' does: `icicle-search-help'.

>     2. `icicle-candidate-alternative-action-fn' - an alternative
>        action function
>     3. `icicle-delete-candidate-object' - a deletion action

And I forgot to list:

4. `icicle-candidate-help-fn' - a candidate help function.

> The easiest way to handle these is to use properties of the
> command symbol, `minibuffer-alt-action', `minibuffer-delete-action'.
> So we could do
>
>  (put 'find-file 'minibuffer-delete-action 'delete-file)
>
> S-delete would be defined to look for that property on this-command
> to decide what to do.
>
> We could implement the equivalent of `icicle-candidate-action-fn'
> easily in the same way.

Yes, that works too. I considered that, but I decided that binding was more
flexible, allowing more control over scope (overriding etc.).

Re: propose adding Icicles to Emacs

[Richard Stallman]

    Apparently I still haven't made myself clear: Icicles replaces no commands.
    It simply _rebinds_ some keys (and only if a user asks it to). This is about
    command remapping, which is about key bindings.

I've understood that ever since it was first mentioned.  It just
doesn't change as much as you think.

Command remapping is a way of replacing a command.  This method is
much cleaner than redefining the function, but still worth avoiding
when possible.  I think there is no need to replace these commands at
all, and I want to avoid it.

    IIUC, your implementation limits a multi-command to using completion in the
    `interactive' spec,

I described a way to specify this using `interactive'.  That does not
mean there are no other interfaces.  It is trivial to have an API for this.
Having it in `interactive' also is an advantage in simplicity.

			and (so far), it does not let you provide specific
    functions for the 4 possible multi-command actions.

Later in the message.

RE: propose adding Icicles to Emacs

[Drew Adams]

> Command remapping is a way of replacing a command.  This method is
> much cleaner than redefining the function, but still worth avoiding
> when possible.  I think there is no need to replace these commands at
> all, and I want to avoid it.

I already said several times that: 1) users can do without the multi-command
versions and 2) they will not have to, in any case, if you implement your
automatic multi-commandness approach.

>     IIUC, your implementation limits a multi-command to using
>     completion in the `interactive' spec,
>
> I described a way to specify this using `interactive'.  That does not
> mean there are no other interfaces.  It is trivial to have an API
> for this. Having it in `interactive' also is an advantage in simplicity.

It's not clear to me what you have in mind for this API. I have nothing
against your proposal for `interactive', as far as it goes.

> 	and (so far), it does not let you provide specific
>     functions for the 4 possible multi-command actions.
>
> Later in the message.

?

Did you intend to send more here?

Re: propose adding Icicles to Emacs

[Richard Stallman]

    User option `icicle-init-value-flag', if non-nil, copies the default value
    for completion to the minibuffer as an initial value. In that case, the
    option also determines whether the initial value is preselected (region)
    and, if so, where point and mark should be positioned.

That feature makes sense, it is only the term "preselect" that is the
problem.  That is not normal Emacs terminology, so please find another
way to describe the feature.

Re: propose adding Icicles to Emacs

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
> Icicles has many different features, including the following
> (in addition to what was mentioned above about Info `i'):

What exactly _is_ icicles, in one sentence?

It's kind of hard to tell exactly from your post, but my guess from
reading your message:  "It extends emacs completion in various handy ways".

However, it also sounds like there are a bunch of other unrelated
features, e.g., "Multi-commands" (what does this have to do with
completion?).  [If these really are unrelated to main purpose, why are
they part of the same package?]

-Miles

-- 
(\(\
(^.^)
(")")
*This is the cute bunny virus, please copy this into your sig so it can spread.

RE: propose adding Icicles to Emacs

[Drew Adams]

> > Icicles has many different features, including the following
> > (in addition to what was mentioned above about Info `i'):
>
> What exactly _is_ icicles, in one sentence?
> It's kind of hard to tell exactly from your post,

It should not be hard to tell. I listed the main features explicitly, point
by point - just after the sentence you quoted. Which ones do you have
trouble understanding?

> but my guess from reading your message: "It extends
> emacs completion in various handy ways".

If you have to boil it down to one sentence, that's as good as any.

The various completion enhancements are largely independent, but they work
well together. For instance, I wouldn't want candidate cycling without also
having regexp or substring matching, to narrow the match set before cycling.
It is the combination that makes it feasible to work with large candidate
sets and still cycle among those that are of interest.

But certainly those two features are relatively independent logically. You
could offer them separately - but I will not.

What would you say to someone who asks, "What exactly is incremental search,
anyway?" You could say "it lets you search incrementally", but that doesn't
help. I would list a few isearch features to describe it, wouldn't you? That
list might include: (1) typing changes are reflected, on the fly, in an
updated search hit list, and the cursor is moved to the new first hit, (2)
all hits are highlighted (lazily), (3) search wraps around, (4) C-g abandons
match failure, and so on. The various isearch features are relatively
independent, but they work well together, and I wouldn't want isearch
without all of them.

Boiling everything down to one sentence is a bit like saying that Emacs is
an extensible, customizable text editor, or that it extends editing and
programming "in various handy ways". Such descriptions don't help much, I'm
afraid.

To get an idea about Icicles, you need to either read something about it or
give it a try. I claim it has a lot to offer and merits a sincere
examination, not just a superficial dismissal. Disagree, if you like, but
after informing yourself a bit, please.

There is plenty of doc describing what Icicles is and what features it
offers, at http://www.emacswiki.org/cgi-bin/wiki/Icicles. I provided a
summary in my proposal message, and the doc starts out with a quick tour
that highlights the main features with examples of use:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Nutshell_View.

> However, it also sounds like there are a bunch of other
> unrelated features,

Unrelated in the sense of logical independence, yes. Unrelated in the sense
of not fitting together or supporting each other, no. Just like the isearch
features.

About the only hard dependencies among the Icicles features are these:

1. Progressive completion (matching with multiple patterns, to narrow
candidates down progressively) depends logically on something like regexp or
substring matching, because there is little sense in using multiple prefix
patterns.

2. The multi-command feature depends on being able to cycle among
candidates. This is not a hard dependency, since one could be limited to
clicking the mouse on individual candidates, but in practice cycling is
central to the use of multi-commands.

3. Icicles search, which is a different approach to incremental search and
replace, uses the multi-command feature. So does on-the-fly help for
individual completion candidates.

> e.g., "Multi-commands" (what does this have to do with
> completion?).  [If these really are unrelated to main purpose,
> why are they part of the same package?]

Call it "multi-completion" if you like (but that term has been used to mean
different things). It is 100% a completion feature: acting on multiple
completion candidates during a single invocation of completion (e.g.
`completing-read').

It _is_ completion; it simply promotes the act of choosing and acting on a
candidate, which until now could occur only at the end of completion, to the
matching and completion phase itself, letting you act on a candidate while
there are still other matching candidates and while you are still able to
change your input and define a different candidate set.

>From the moment that you treat completion as a process of defining a set of
matches followed by an act of picking a match, and you add the possibility
of cycling among or otherwise selecting multiple candidates, the idea of
also acting on those selected candidates springs to mind. Act how? Provide
candidate help. Perform the same action you perform for the final completion
choice. Perform a different action...

Are those all separate features? Are they strictly related logically? I'd
say that they fit well together, and I'd leave it at that. To see that they
fit together, you need either a little imagination and some time spent
reading about them or, better, some time spent trying them out.

Icicles is a big package. I will not convince you of its worth as long as
you don't take a serious look at it and you remain at the "sounds like",
"seems like", "I get the impression", level. The doc presents fairly well
the features and how to use Icicles, and it is trivial to load Icicles and
give it a try. If you honestly want to learn about it and get a feeling for
it, there are no obstacles.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    What would you say to someone who asks, "What exactly is incremental search,
    anyway?" You could say "it lets you search incrementally", but that doesn't
    help.

That doesn't help because all it does is reshuffle the same words.
But if you say, "You enter the search string interactively,
and searching occurs as you enter it", that is a useful answer
to the question.  It does not describe all the details,
but it does describe isearch overall.

This is possible because incremental search really is a single
feature, with a coherent overall purpose.

It appears that Icicles is not a single feature, but rather
a collection of features.

Re: propose adding Icicles to Emacs

[Richard Stallman]

    However, it also sounds like there are a bunch of other unrelated
    features, e.g., "Multi-commands" (what does this have to do with
    completion?).  [If these really are unrelated to main purpose, why are
    they part of the same package?]

That is a very important point.  It is quite common that a user
implements, in a single Lisp program, various features which he
likes but which do not really belong together.  In such a case,
to "install the package" is not really the right thing to consider.

What we should do instead is consider each of the features separately,
and decide what to do with it.

RE: propose adding Icicles to Emacs

[Drew Adams]

>     However, it also sounds like there are a bunch of other unrelated
>     features, e.g., "Multi-commands" (what does this have to do with
>     completion?).  [If these really are unrelated to main purpose, why are
>     they part of the same package?]
>
> That is a very important point.  It is quite common that a user
> implements, in a single Lisp program, various features which he
> likes but which do not really belong together.  In such a case,
> to "install the package" is not really the right thing to consider.
>
> What we should do instead is consider each of the features separately,
> and decide what to do with it.

I don't disagree. In fact I hope that the features will be examined in
detail and tried out. There is no other way for people to realize that the
features belong together - or not.

Re: propose adding Icicles to Emacs

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
>> What we should do instead is consider each of the features separately,
>> and decide what to do with it.
>
> I don't disagree. In fact I hope that the features will be examined in
> detail and tried out. There is no other way for people to realize that the
> features belong together - or not.

In many cases, even if the features enhance each other, if they're
logically unrelated, it's better to make them more clearly separate.

E.g., cua-mode is a prime example of a package which really should be
split up but was originally written with a lot of stuff sort of welded
together that should be separate.

-miles

-- 
[|nurgle|]  ddt- demonic? so quake will have an evil kinda setting? one that
            will  make every christian in the world foamm at the mouth?
[iddt]      nurg, that's the goal

Re: propose adding Icicles to Emacs

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> E.g., cua-mode is a prime example of a package which really should be
> split up but was originally written with a lot of stuff sort of welded
> together that should be separate.

Now that you mention cua:  It also uses C-RET (to mark a rectangle).
I hope the cua and icicles use of C-RET can co-exist without problems...

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: propose adding Icicles to Emacs

[joakim]

storm@cua.dk (Kim F. Storm) writes:

> Miles Bader <miles@gnu.org> writes:
>
>> E.g., cua-mode is a prime example of a package which really should be
>> split up but was originally written with a lot of stuff sort of welded
>> together that should be separate.
>
> Now that you mention cua:  It also uses C-RET (to mark a rectangle).
> I hope the cua and icicles use of C-RET can co-exist without problems...

C-RET is kind of difficult to produce in a terminal, meaning that some
of these emacs features are difficult to test for us emacs terminal
users.

> -- 
> Kim F. Storm <storm@cua.dk> http://www.cua.dk

-- 
Joakim Verona

Re: propose adding Icicles to Emacs

[Kim F. Storm]

joakim@verona.se writes:

> C-RET is kind of difficult to produce in a terminal, meaning that some
> of these emacs features are difficult to test for us emacs terminal
> users.

Since C-SPC toggles the normal mark, I was looking for "similar bindings"
to toggle the rectangle mark (C-RET) and global mark (S-C-SPC).

I chose C-RET to set the rectangle mark, since RET has a nice
mostly-rectangle shape, and C-RET is easy to type.


Do you have any suggestions for alternative bindings on a terminal?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: propose adding Icicles to Emacs

[joakim]

storm@cua.dk (Kim F. Storm) writes:

> joakim@verona.se writes:
>
>> C-RET is kind of difficult to produce in a terminal, meaning that some
>> of these emacs features are difficult to test for us emacs terminal
>> users.
>
> Since C-SPC toggles the normal mark, I was looking for "similar bindings"
> to toggle the rectangle mark (C-RET) and global mark (S-C-SPC).
>
> I chose C-RET to set the rectangle mark, since RET has a nice
> mostly-rectangle shape, and C-RET is easy to type.
>
>
> Do you have any suggestions for alternative bindings on a terminal?

No I dont really.

I dont really understand why C-RET doesnt work either.

I use a terminal emulator called Putty sometimes, and an xterm
sometimes. They differ in which keys are acceptable. For instance I
use shift-arrows for moving between windows using
(windmove-default-keybindings). I need to patch Putty to make
shift-arrows work, but it works directly with xterm.

If I could find out which keys are acceptable in terminals maybe I
could contribute better.

> -- 
> Kim F. Storm <storm@cua.dk> http://www.cua.dk

-- 
Joakim Verona

RE: propose adding Icicles to Emacs

[Drew Adams]

> >> C-RET is kind of difficult to produce in a terminal, meaning that some
> >> of these emacs features are difficult to test for us emacs terminal
> >> users.
> >
> > Since C-SPC toggles the normal mark, I was looking for "similar
> bindings"
> > to toggle the rectangle mark (C-RET) and global mark (S-C-SPC).
> >
> > I chose C-RET to set the rectangle mark, since RET has a nice
> > mostly-rectangle shape, and C-RET is easy to type.
> >
> >
> > Do you have any suggestions for alternative bindings on a terminal?
>
> No I dont really.
>
> I dont really understand why C-RET doesnt work either.
>
> I use a terminal emulator called Putty sometimes, and an xterm
> sometimes. They differ in which keys are acceptable. For instance I
> use shift-arrows for moving between windows using
> (windmove-default-keybindings). I need to patch Putty to make
> shift-arrows work, but it works directly with xterm.
>
> If I could find out which keys are acceptable in terminals maybe I
> could contribute better.


This is getting off thread for the Icicles proposal.

WRT Icicles, FWIW: Icicles makes several minibuffer bindings that are keys
you cannot use in terminal mode. For this reason, if you use terminal mode,
then Icicles warns you that you probably don't want to use it in terminal
mode without rebinding some keys, and the same thing is stated in the doc.
You will want to rebind S-TAB at the least.

I tried to pick keys that 1) were not already taken or 2) were not very
useful in minibuffer editing.

keys that work on terminals (was: Re: propose adding Icicles to Emacs)

[Dan Nicolaescu]

joakim@verona.se writes:

  > storm@cua.dk (Kim F. Storm) writes:
  > 
  > > joakim@verona.se writes:
  > >
  > >> C-RET is kind of difficult to produce in a terminal, meaning that some
  > >> of these emacs features are difficult to test for us emacs terminal
  > >> users.
  > >
  > > Since C-SPC toggles the normal mark, I was looking for "similar bindings"
  > > to toggle the rectangle mark (C-RET) and global mark (S-C-SPC).
  > >
  > > I chose C-RET to set the rectangle mark, since RET has a nice
  > > mostly-rectangle shape, and C-RET is easy to type.
  > >
  > >
  > > Do you have any suggestions for alternative bindings on a terminal?
  > 
  > No I dont really.
  > 
  > I dont really understand why C-RET doesnt work either.

Because C-RET does not correspond to an ASCII character like for
example C-j. 

xterm after version 216 has been changed to generate different strings
for the key combinations that were not usable before. You need to set
the "modifyOtherKeys" resource to 1 in order to enable this feature.
This change was done at my request, with the main intention was to
help emacs key bindings. AFAIK in such an xterm all useful key
combinations work: things like C-RET, C-. C-, work just fine.  
Unfortunately "modifyOtherKeys" is not set by default, to emacs users
cannot benefit from this by default.

Can we do something to have other terminal emulators support these key
bindings?

  > I use a terminal emulator called Putty sometimes, and an xterm
  > sometimes. They differ in which keys are acceptable. For instance I
  > use shift-arrows for moving between windows using
  > (windmove-default-keybindings). I need to patch Putty to make
  > shift-arrows work, but it works directly with xterm.

IMHO you need to try to convince the putty maintainers to generate the
shift-arrow keys by default, all modern terminal emulators do that
(xterm, rxvt, gnome-terminal, konsole).

Re: keys that work on terminals

[joakim]

Dan Nicolaescu <dann@ics.uci.edu> writes:
> xterm after version 216 has been changed to generate different strings
> for the key combinations that were not usable before. You need to set
> the "modifyOtherKeys" resource to 1 in order to enable this feature.
> This change was done at my request, with the main intention was to
> help emacs key bindings. AFAIK in such an xterm all useful key
> combinations work: things like C-RET, C-. C-, work just fine.  
> Unfortunately "modifyOtherKeys" is not set by default, to emacs users
> cannot benefit from this by default.

This is very interesting! I will try this.

> Can we do something to have other terminal emulators support these key
> bindings?
>
>   > I use a terminal emulator called Putty sometimes, and an xterm
>   > sometimes. They differ in which keys are acceptable. For instance I
>   > use shift-arrows for moving between windows using
>   > (windmove-default-keybindings). I need to patch Putty to make
>   > shift-arrows work, but it works directly with xterm.
>
> IMHO you need to try to convince the putty maintainers to generate the
> shift-arrow keys by default, all modern terminal emulators do that
> (xterm, rxvt, gnome-terminal, konsole).

I've been trying but have so far been unable to get a response.
I have the patch if someones interested.
-- 
Joakim Verona

RE: propose adding Icicles to Emacs

[Drew Adams]

> > E.g., cua-mode is a prime example of a package which really should be
> > split up but was originally written with a lot of stuff sort of welded
> > together that should be separate.
>
> Now that you mention cua:  It also uses C-RET (to mark a rectangle).
> I hope the cua and icicles use of C-RET can co-exist without problems...

FWIW, Icicles binds C-RET only in minibuffer maps. So, if a CUA user wants
to mark a rectangle in the minibuffer, then s?he would need to rebind a
command.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Stefan Monnier]

> HTML without some indication of key bindings provides no particular support
> for keybindings.

That's fine.  I don't think any document format can ever "provide support
for keybindings".  It's the responsibility of the browser to do that.
What the format needs to provide is support for particular features (such
as index search), and that *is* provided by HTML.


        Stefan

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    `makeinfo --html' already generates output that any browser can display.
    What is missing in HTML output are Info-specific semantical elements,
    like references to next and previous nodes, menu items grouped to menus,
    index items that can be easily extracted.

Can we figure out a way to include that in HTML,
so that we solve this problem without losing the ability to display
in an ordinary browser?

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Juri Linkov]

>     `makeinfo --html' already generates output that any browser can display.
>     What is missing in HTML output are Info-specific semantical elements,
>     like references to next and previous nodes, menu items grouped to menus,
>     index items that can be easily extracted.
>
> Can we figure out a way to include that in HTML,
> so that we solve this problem without losing the ability to display
> in an ordinary browser?

Including them in HTML is easy by using HTML semantical markup
(elements "div", attributes "class", etc.)

But the most trouble I expect from displaying HTML in Emacs.  There was
one unsuccessful project that implements a HTML browser in Emacs - w3.
Its failure causes doubts about expediency of using HTML in the Emacs
Info browser.

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

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Miles Bader]

Juri Linkov <juri@jurta.org> writes:
> But the most trouble I expect from displaying HTML in Emacs.  There was
> one unsuccessful project that implements a HTML browser in Emacs - w3.
> Its failure causes doubts about expediency of using HTML in the Emacs
> Info browser.

I don't think that's true -- the problem with W3 was that it was trying
to display _web pages_ in some sane manner, and the majority of web
pages are simply not very amenable to that.  They make far too many
assumptions about they environment they are displayed in, and do not
degrade gracefully at all if _anything_ changes.

With an info replacement on the other hand, we can control how html is
used, and perhaps more importantly, it's likely that a large subset of
texinfo authors will be _testing_ their documents in the Emacs
environment.

-miles
-- 
=====
(^o^;
(()))
*This is the cute octopus virus, please copy it into your sig so it can spread.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Juri Linkov]

>> But the most trouble I expect from displaying HTML in Emacs.  There was
>> one unsuccessful project that implements a HTML browser in Emacs - w3.
>> Its failure causes doubts about expediency of using HTML in the Emacs
>> Info browser.
>
> I don't think that's true -- the problem with W3 was that it was trying
> to display _web pages_ in some sane manner, and the majority of web
> pages are simply not very amenable to that.  They make far too many
> assumptions about they environment they are displayed in, and do not
> degrade gracefully at all if _anything_ changes.
>
> With an info replacement on the other hand, we can control how html is
> used, and perhaps more importantly, it's likely that a large subset of
> texinfo authors will be _testing_ their documents in the Emacs
> environment.

I agree that handling a small HTML subset generated by makeinfo makes
implementing its support in the Emacs Info reader more promising.
But then the makeinfo output format to use should not be HTML, but rather
XHTML, so we could use xml-parse-file to read generated manuals in Emacs.

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

RE: [drew.adams@oracle.com: RE: cannot find :enable in Elispmanualindex]

[Drew Adams]

> I agree that handling a small HTML subset generated by makeinfo makes
> implementing its support in the Emacs Info reader more promising.
> But then the makeinfo output format to use should not be HTML, but rather
> XHTML, so we could use xml-parse-file to read generated manuals in Emacs.

I don't see any reason not to use XHTML anyway, whatever we do. There is no
reason to use any HTML that is not XHTML - what would be gained by that?

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    With an info replacement on the other hand, we can control how html is
    used, and perhaps more importantly, it's likely that a large subset of
    texinfo authors will be _testing_ their documents in the Emacs
    environment.

Right.  Using a limited subset of HTML as an Info format
would mean that browsers can display it -- but programs to display
it need not be general browsers.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    Including them in HTML is easy by using HTML semantical markup
    (elements "div", attributes "class", etc.)

The Emacs info mode could easily handle those.

I wonder if there is a clean and simple way to implement
these features (menus and indices) with valid "ordinary" HTML,
and label that valid HTML as "menu" or "index" using `div',
so that the Emacs info reader could parse that HTML in a special
way so as to handle it as a menu or index.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Karl Berry]

    I wonder if there is a clean and simple way to implement
    these features (menus and indices) with valid "ordinary" HTML,

They are.  They are lists of links.  As in:
<ul>
<li><a href="somenode.html">Menu item</a>
...

(Of course there are lots of details, but that's the basic idea.)

    and label that valid HTML as "menu" or "index" using `div',

Right now they have classes specified in the <ul> element:
<ul class="menu"> ... </ul>
<ul class="index-fn" compact> ... </ul>

If it's desirable to use <div> for some reason, that's obviously easy to
do.
    
    However, in practice, using a subset of HTML would allow any browser
    to display Info files.  Could TexinfoML XML do that?

I'm not sure.  It is possible to associate "style information", at
least, with an XML schema that a browser would see, but whether that is
enough to do a good job, I've never investigated.  Maybe someone would
like to do that.


Using the HTML output vs. using the TexinfoML output are quite different
approaches.  Which one is better depends on how much of the rendering
you want to control in Emacs.  If you want complete control, then it
would make sense to use TexinfoML, whose goal is basically to be an XML
transliteration of the input.

The HTML (or XHTML) output is more of a "processed form" similar in
spirit to Info -- although it is certainly possible to affect the look
of the HTML output at HTML-rendering time, there are more limits than in
the XML approach.

As an example, consider the HTML for a node, which starts a paragraph,
includes the next/prev pointers as text, defines anchors to make
cross-references work, and so on:

<div class="node">
<p><hr>
<a name="%5ctypein"></a>
<a name="g_t_005ctypein"></a>
Next:&nbsp;<a rel="next" accesskey="n" href="#g_t_005ctypeout">\typeout</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="#Terminal-Input_002fOutput">Terminal Input/Output</a>

</div>

Compare that with the TexinfoML XML, which merely declares what the
various components are and says nothing about how they are displayed:

  <node>
    <nodename>\typein</nodename>
    <nodenext>\typeout</nodenext>
    <nodeup>Terminal Input/Output</nodeup>
...

Hope this helps,
karl

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    They are.  They are lists of links.  As in:
    <ul>
    <li><a href="somenode.html">Menu item</a>
    ...

    (Of course there are lots of details, but that's the basic idea.)

	and label that valid HTML as "menu" or "index" using `div',

    Right now they have classes specified in the <ul> element:
    <ul class="menu"> ... </ul>
    <ul class="index-fn" compact> ... </ul>

That seems simple enough.  Is there any flaw in it?

    <div class="node">
    <p><hr>
    <a name="%5ctypein"></a>
    <a name="g_t_005ctypein"></a>

I am completely baffled by that.  What does `%5ctypein' refer to?  Why
is it there?  What does `g_t_005ctypein' refer to?  Why is it there?

     Next:&nbsp;<a rel="next" accesskey="n" href="#g_t_005ctypeout">\typeout</a>,
     Up:&nbsp;<a rel="up" accesskey="u" href="#Terminal-Input_002fOutput">Terminal Input/Output</a>

What does `accesskey' mean?

Anyway, if we replace Info format, we do not have to preserve
the current layout of the line at the top of a node.  If some
simpler HTML construct can provide the needed navigation features,
it doesn't have to look the same.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Karl Berry]

    That seems simple enough.  Is there any flaw in it?

Not that I know of.

   I am completely baffled by that.  What does `%5ctypein' refer to?  

%5c is HTML-ese for \.  The name of the node is "\typein" with a
backslash.  Sorry, I should have picked a simpler node name for the example.

   Why is it there?  

So there can be references to this node from elsewhere.

   What does `g_t_005ctypein' refer to?  Why is it there?

It's another name for the same node due to annoying technicalities whose
details are not at the front of my mind.  Don't worry about it, I don't
think it affects anything here.

    What does `accesskey' mean?

On browsers that support it, users can press "n" (or whatever) and have
it do something useful.
    
    Anyway, if we replace Info format, we do not have to preserve
    the current layout of the line at the top of a node.  

I suppose, but I see nothing wrong with the current layout of the top of
a node in makeinfo's HTML output.

Anyway, the point is not to debate node line output.  All this was just
an example.  The point is to show the drastic difference between
makeinfo's HTML and XML output, both of which (among others) were being
proposed at various times for a "new generation" Emacs Info reader.

karl

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Juri Linkov]

> In the long term, we could redesign Info format.  However, such a change
> takes years to put into place.
>
> Instead of doing this, perhaps it would be better to replace the format
> with a completely new format.
>
> I wonder if we could use some limited subset of HTML, so that Emacs
> could display it even though it doesn't really understand HTML.
> Meanwhile, any browser could also display it, and standalone Info
> could be a variant of a browser.

I think the best format for the Emacs Info reader is Texinfo XML.
Makeinfo already has the option `--xml' that generates output files in
Texinfo XML.  This format just maps Texinfo elements onto XML in an
easily readable and unambiguous way, thus preserving all Texinfo markup from
the source Texinfo files to the Info reader.

However, with all its advantages I doubt that this format will replace
the old plain Info format soon.  But in the long term, perhaps, yes.
The main obstacle to adopting this format is the lack of its support
in the Emacs Info reader.  Recently I started writing a package
that provides it.  I'll post code later to this list for review
in a separate mail.

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

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Juri Linkov]

> Is there no way to escape a colon somehow, so that Info does not interpret
> it? The Texinfo manual says that this limitation is because "a colon
> separates the menu entry name from the node name, so a colon in the entry
> name confuses Info." If there is no way to escape a colon - to let Info know
> when a colon doesn't indicate a menu + entry, then shouldn't there be?

We could use a trick in the Info browser that if an index entry starts with
a colon, then interpret it as part of index entry, or if there is two colons
in a row then interpret the first one as part of the entry.  For example,

* :action (button property):    Button Properties.   (line  12)

where everything up to the last colon is the info entry.

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

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 03 Jun 2007 01:42:18 +0300
> Cc: karl@gnu.org, emacs-devel@gnu.org
> 
> We could use a trick in the Info browser that if an index entry starts with
> a colon, then interpret it as part of index entry, or if there is two colons
> in a row then interpret the first one as part of the entry.  For example,
> 
> * :action (button property):    Button Properties.   (line  12)
> 
> where everything up to the last colon is the info entry.

That might solve some of the problems in the ELisp manual, but the
gravest problems with colons in languages such as C++ will not be able
to use this trick.

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Juri Linkov]

>> We could use a trick in the Info browser that if an index entry starts with
>> a colon, then interpret it as part of index entry, or if there is two colons
>> in a row then interpret the first one as part of the entry.  For example,
>> 
>> * :action (button property):    Button Properties.   (line  12)
>> 
>> where everything up to the last colon is the info entry.
>
> That might solve some of the problems in the ELisp manual, but the
> gravest problems with colons in languages such as C++ will not be able
> to use this trick.

yep :), e.g.:

* class::method:    Description of Class::Method.   (line  12)

but we could try to use some heuristics like, for example, matching
a colon only when space follows it (":[ \t]+"), and so when it is not inside
an identifier.

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

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Karl Berry]

    but we could try to use some heuristics 

No.  If we're going to solve it, let's solve it right.

It is not just : that is problematic, and it's not just in menu items,
either.  There is also 
  . , ( )
in various contexts.

karl

Re: [drew.adams@oracle.com: RE: cannot find :enable in Elisp manualindex]

[Richard Stallman]

    yep :), e.g.:

    * class::method:    Description of Class::Method.   (line  12)

    but we could try to use some heuristics like, for example, matching
    a colon only when space follows it (":[ \t]+"), and so when it is not inside
    an identifier.

That might be a good idea.  In theory it is an incompatible change,
but in practice this incompatibily may be very rare.