new apropos feature in Emacs-22

new apropos feature in Emacs-22

[Luc Teirlinck]

>From `(emacs)Apropos':

    Because `C-h a' looks only for commands matching the string you
    specify, you may not find what you want on the first try.  In that
    case, don't just give up.  You can give Apropos a list of words to
    search for.  When more than one word is specified, at least two of
    those words must be present for an item to match.  If you are looking
    for commands to kill a chunk of text before point, try `C-h a kill back
    behind before <RET>'.  For even greater flexibility, you can also
    supply a regular expression to Apropos (*note Regexps::).

The described behavior is new in Emacs-22.  There are several problems
with it.

Firstly, the last sentence of the above paragraph is false.  You can
not specify any regexp: a regexp that contains spaces or tabs and that
only matches itself will be mistaken for a list of keywords, unless you
use a special trick, say using "[f]ont lock mode" instead of
"font lock mode" (but no such trick is mentioned in the Emacs manual).
This restriction might not be too bad for apropos-command and
apropos-variable, where spaces make little sense, but for
apropos-documentation (and actually sometimes also apropos-value) it
could easily confuse people used to the prior behavior.

Secondly, the "at least two matching keywords" rule seems arbitrary.
Why not use the convention that a list of keywords is specified as, say

directory folder [1

or

next directory folder [2

Where the number after `[' denotes the number of required matching
keywords and the unbalanced `[' guarantees that the convention never
overwrites a valid regexp.

If the present convention is kept unchanged, then one should at the
very least update the involved docstrings: although the Emacs manual
mentions the new behavior, apparently none of the docstrings of the
involved commands do.  All the docstrings still suggest that the
REGEXP argument will always be treated as a regular expression.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> Date: Fri, 4 Nov 2005 21:15:45 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> Secondly, the "at least two matching keywords" rule seems arbitrary.
> Why not use the convention that a list of keywords is specified as, say
> 
> directory folder [1
> 
> or
> 
> next directory folder [2

This feature (and any ad-hoc rules it implements) was discussed at
length around the time the feature was added.  Please be sure to read
those discussions before you suggest to change the decisions made back
then.

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Eli Zaretskii wrote:

   This feature (and any ad-hoc rules it implements) was discussed at
   length around the time the feature was added.  Please be sure to read
   those discussions before you suggest to change the decisions made back
   then.

Nothing in that discussion changes the fact that:

   (string-equal (regexp-quote regexp) regexp)

is just a horrible way to distinguish a regexp from a list of keywords.

The prompt string of the apropos commands says: (regexp or words).
Which of the two and how do I choose?  The docstrings all say that it
matches a regexp and do not mention keywords at all.

To the person who wants to use a regexp, it is confusing that
`M-x apropos-documentation RET font lock RET" produces tons of
unexpected matches and unexpected highlighting.

To the person who reads the Emacs manual and knows nothing about
regexps, it is even a lot more confusing that things like:

M-x apropos-documentation RET *scratch* buffer RET

does not find any matches, even though there are several places matching
both keywords.

Things like:

M-x apropos-documentation RET .emacs init RET

are probably even worse, since _some_ matches are actually displayed,
but not the ones the user may be trying to find.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> Date: Sat, 5 Nov 2005 09:52:38 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> 
>    This feature (and any ad-hoc rules it implements) was discussed at
>    length around the time the feature was added.  Please be sure to read
>    those discussions before you suggest to change the decisions made back
>    then.
> 
> Nothing in that discussion changes the fact that:
> 
>    (string-equal (regexp-quote regexp) regexp)
> 
> is just a horrible way to distinguish a regexp from a list of keywords.

Please don't get angry with me: I was only trying to say that the
seemingly arbitrary rule of "at least two matching keywords" might
have some valid reasons which are spelled out in the discussions.

I do agree that the doc strings should be updated to reflect the fact
that a list of keywords are accepted as well as regexps.

> To the person who wants to use a regexp, it is confusing that
> `M-x apropos-documentation RET font lock RET" produces tons of
> unexpected matches and unexpected highlighting.

I think the idea was that a list of words is more natural input at
that point than a regexp.  People nowadays are used to Google-style
queries more than to regexps.  FWIW, I rarely myself use regexps in
apropos.

> To the person who reads the Emacs manual and knows nothing about
> regexps, it is even a lot more confusing that things like:
> 
> M-x apropos-documentation RET *scratch* buffer RET
> 
> does not find any matches, even though there are several places matching
> both keywords.
> 
> Things like:
> 
> M-x apropos-documentation RET .emacs init RET
> 
> are probably even worse, since _some_ matches are actually displayed,
> but not the ones the user may be trying to find.

I think these problems were raised and discussed back then, but I
might be wrong.

RE: new apropos feature in Emacs-22

[Drew Adams]

    I think the idea was that a list of words is more natural input at
    that point than a regexp.  People nowadays are used to Google-style
    queries more than to regexps.  FWIW, I rarely myself use regexps in
    apropos.

Why try to mix regexp input with keyword input in the same command? That's
just asking for trouble. Why not have two different commands -
`apropos-with-keywords' and `apropos'? That's a cleaner way to add treatment
of keywords.

(Worse, but still better than this amalgam, would be to extend the `C-u'
options to provide for keyword input. The default should be the traditional,
regexp behavior, however.)

Sorry, I missed the original discussion.

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Eli Zaretskii wrote:

   > Nothing in that discussion changes the fact that:
   > 
   >    (string-equal (regexp-quote regexp) regexp)
   > 
   > is just a horrible way to distinguish a regexp from a list of keywords.

   Please don't get angry with me:

I was not angry and did not intend to sound angry.  I am sorry if
something in the above quote gave the impression I was.

   I was only trying to say that the
   seemingly arbitrary rule of "at least two matching keywords" might
   have some valid reasons which are spelled out in the discussions.

My _main_ objection was the confused semantics.  I just thought that
it might be possible to fix the semantics while at the same time
giving the user more flexibility, but this was secondary.

   I think these problems were raised and discussed back then, but I
   might be wrong.

I read through the entire thread and could not find it.  The danger of
misinterpreting an intended regexp as a list of keywords was
mentioned, but not the opposite danger of misinterpreting a list of
keywords as a regexp.  This danger can occur even if a single keyword
is specified, say .emacs, *scratch* , ses+.  Unless something is done
to avert that problem, then at least that problem should be mentioned
clearly in `(emacs)Apropos' (and in the docstrings).  The only mention
of regexps in `(emacs)Apropos' is:

    For even greater flexibility, you can also supply a regular expression
    to Apropos (*note Regexps::).

It does not explicitly mention that this "greater flexibility" means
that you can not use certain characters in your keywords.  It does
also not give any tips on how to make sure that an intended regexp
really gets interpreted by Emacs as a regexp.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 5 Nov 2005 09:33:12 -0800
> 
>     I think the idea was that a list of words is more natural input at
>     that point than a regexp.  People nowadays are used to Google-style
>     queries more than to regexps.  FWIW, I rarely myself use regexps in
>     apropos.
> 
> Why try to mix regexp input with keyword input in the same command? That's
> just asking for trouble. Why not have two different commands -
> `apropos-with-keywords' and `apropos'? That's a cleaner way to add treatment
> of keywords.

Please be sure to read the discussions about the various aspects of
this feature.  It starts here:

  http://lists.gnu.org/archive/html/emacs-devel/2002-05/msg00397.html

You will see that I already suggested back then to have a separate
command, in this message:

  http://lists.gnu.org/archive/html/emacs-devel/2002-05/msg00400.html

The ensuing discussion mentioned some drawbacks of that suggestion.

RE: new apropos feature in Emacs-22

[Drew Adams]

    Please be sure to read the discussions about the various aspects of
    this feature.  It starts here:
      http://lists.gnu.org/archive/html/emacs-devel/2002-05/msg00397.html
    You will see that I already suggested back then to have a separate
    command, in this message:
      http://lists.gnu.org/archive/html/emacs-devel/2002-05/msg00400.html
    The ensuing discussion mentioned some drawbacks of that suggestion.

Thanks for the links. I'll keep quiet after this - suffice it to say that I
don't agree with this new feature, and the "drawbacks" mentioned to using a
separate command were skimpy. 80% of that thread was about how to implement
a keyword-search feature within apropos, not whether or not that was a good
idea. This was the only "drawback" that I saw mentioned in the whole thread
(please correct me, if I missed something):

 - All apropos commands should `accept the same type of "search patterns".'

And this question was raised, but not pursued (that I saw): `What would
apropos-keywords look for? `commands', `variables' `documentation', or "all
of the above" ?'

That one "drawback" wasn't discussed at all, that I saw. I don't see _why_
all apropos commands _should_ accept the same type of "search patterns" -
what is the argument for this? I didn't see any.

Are we perhaps worried about people _expecting_ that all commands that have
the word "apropos" in their names behave the same way wrt input (unlikely,
IMO)? Is that the unstated worry? If so:

1) I think that's being a bit skittish.

2) We could, instead, introduce a command (or a whole series of different
commands, to respond to the question raised but not answered) that uses
keywords and does _not_ have the word "apropos" in its name. If that (the
name) is the only real concern, then let us choose a different name for the
keyword-search command(s) (hey, how about `keyword-search'?)

How did the (useful!) feature of keyword search get injected and locked into
the existing apropos commands? (Virus? ;-))

As I said, we're asking for trouble by trying to mix regexp syntax and
keyword syntax. The former is confusing enough - imagine how it will be when
people fall into it by accident! My bet is that neither the regexp syntax
nor the keyword syntax will be clear cut or work well.

Now, I'll shut up, after one last request:

Can we please have available some function(s) that will give the original,
regexp-syntax-only behavior, so that we may individually get back to
something reasonable? That is, can we have functions (not necessarily aimed
at novices) that we can use to build commands that do what the apropos
family did before? It could be `apropos-internal' (plus equivalents for doc
etc.) - or something else, if `apropos-internal' has already been infected
too ;-).

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Drew Adams wrote:

   The default should be the traditional, regexp behavior, however.

I believe that the idea was to make apropos easier for inexperienced
users knowing little about regexps.  But the present functionality
still can easily confuse such users for very natural keywords like
*scratch*, .emacs or ses+.

   Now, I'll shut up, after one last request:

   Can we please have available some function(s) that will give the original,
   regexp-syntax-only behavior, so that we may individually get back to
   something reasonable? That is, can we have functions (not necessarily aimed
   at novices) that we can use to build commands that do what the apropos
   family did before?

I see as solutions, in order of preference:

1.  A proper syntactic convention that uses keyword search for some
    invalid regexp: unbalanced [, final \, whatever.

2.  A customizable option for all apropos commands, that specifies
    either keyword lists only, or regexps only, or, for people who do
    not mind about unreliable and potentially confusing heuristics,
    the present behavior.  To be friendly to people uncomfortable with
    regexps, keywords only could be the default.

If the present behavior is kept unchanged, then at least it should be
documented properly, with the potential pitfalls clearly pointed out,
both in the docstrings and the Emacs manual.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Kim F. Storm]

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

> Thanks for the links. I'll keep quiet after this - suffice it to say that I
> don't agree with this new feature, and the "drawbacks" mentioned to using a
> separate command were skimpy.

There was one major reason for this change, and that reason has not changed:

To make it easier for the emacs "novice" to find information with apropos.

The assumption is that most users will be accustomed to use keyword
search, and only the experts will use regular expressions.

So we changed the standard apropos commands to accept keywords, and to keep
things simple, we chose the simple rule of "any two words matches".

Personally, I would have preferred to let apropos use keywords only
(and I haven't used regexps in apropos since this change was made), but
as a compromise, we retained regexp matching if the search pattern looks
like a regexp (and an expert user know how you can easily specify " +"
for a space to force the old semantics).

> That one "drawback" wasn't discussed at all, that I saw. I don't see _why_
> all apropos commands _should_ accept the same type of "search patterns" -
> what is the argument for this? I didn't see any.

IMO, it is the only logical thing to do.  I never thought I'd have to argue
about that...

> Are we perhaps worried about people _expecting_ that all commands that have
> the word "apropos" in their names behave the same way wrt input (unlikely,
> IMO)? Is that the unstated worry? If so:
>
> 1) I think that's being a bit skittish.

It's being "user friendly", and specifically "novice user friendly".

> 2) We could, instead, introduce a command (or a whole series of different
> commands, to respond to the question raised but not answered) that uses
> keywords and does _not_ have the word "apropos" in its name. If that (the
> name) is the only real concern, then let us choose a different name for the
> keyword-search command(s) (hey, how about `keyword-search'?)

_If_ we were to change the current situation, we should make the normal
commands accept keywords only, and make new commands for regexp matches.

> How did the (useful!) feature of keyword search get injected and locked into
> the existing apropos commands? (Virus? ;-))
>
> As I said, we're asking for trouble by trying to mix regexp syntax and
> keyword syntax. The former is confusing enough - imagine how it will be when
> people fall into it by accident! My bet is that neither the regexp syntax
> nor the keyword syntax will be clear cut or work well.

I doubt this is a real problem.  Do you have any evidence (actual user
complaints) to prove your case?

A user falling into this by accident will probably rephrase the query and
try again.  Just like goggling may require a few different sets of keywords
before you find something useful.

And the prompt does say ... (regexp or words), so if the user gets 
a lot of false hits, there is a clue to what went wrong.

>
> Now, I'll shut up, after one last request:
>
> Can we please have available some function(s) that will give the original,
> regexp-syntax-only behavior, so that we may individually get back to
> something reasonable? That is, can we have functions (not necessarily aimed
> at novices) that we can use to build commands that do what the apropos
> family did before? It could be `apropos-internal' (plus equivalents for doc
> etc.) - or something else, if `apropos-internal' has already been infected
> too ;-).

I don't understand why you need this.  If you (as an expert user) want
regexp mathing, specify a regexp -- it's as simple as that!

E.g. instead of "find file" (keyword search), write "find +file" (regexp).

But I agree that the doc strings could be improved.

--
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: new apropos feature in Emacs-22

[Lennart Borgman]

Kim F. Storm wrote:

>_If_ we were to change the current situation, we should make the normal
>commands accept keywords only, and make new commands for regexp matches.
>  
>
I remember I was confused by this. May I suggest a simple solution:

- Use keyword matching as default (ie like now really)
- If something looking like a regexp was entered then enter a simple 
y-or-n-p and ask the user if it is a regexp.

Hm. That is for interactive use of course. Maybe a parameter too ...

Well, I do not know if this is the right solution. Whatever we decide on 
help functions must not be confusing!

RE: new apropos feature in Emacs-22

[Drew Adams]

    _If_ we were to change the current situation, we should make the normal
    commands accept keywords only, and make new commands for regexp matches.

Sold!!  That works, for me - I don't care what names we give the commands.
They should be separate commands (regexp vs keyword) - that's all. `apropos'
for keywords and `foobar' for regexps is fine by me. I still haven't seen an
argument against keeping the two kinds of search separate, in separate
commands - what's the drawback? Go ahead and reserve the name "apropos" for
keyword search - no problem.

Please don't make Norman Newbie wonder what black hole he fell down because
he messed up the syntax...  "Novice user friendly", indeed.

(I said I'd shut up, so I'll skip the line-by-line.)

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Lennart Borgman wrote:

   - If something looking like a regexp was entered

Most strings are valid regexps.  Only a few exceptions are not.

Sincerely,

Luc.

RE: new apropos feature in Emacs-22

[Drew Adams]

Hi Lennart,

    May I suggest a __simple___ solution:

It's a joke, right? ;-)

    - Use keyword matching as default (ie like now really)
    - If something looking like a regexp was entered then enter a simple
    y-or-n-p and ask the user if it is a regexp.

    Hm. That is for interactive use of course. Maybe a parameter too ...

    Well, I do not know if this is the right solution. Whatever we
    decide on
    help functions must not be confusing!

Do you see? Do you see the complexity and confusion that creeps in when two
completely different syntaxes and different use cases are mixed up together
in the same command? We're forced to pile on hack after hack to disambiguate
the two cases.

 "Is this intended as a regexp?" "Do you really want to use a regexp?"
 Plus a parameter for non-interactive... Plus an error message or two...
Plus...

And Luc:

 Add a signal-character at the end, to indicate that it's really a regexp...

This is not the way to go. I have not seen one argument for _not_ using
separate commands (or command families): 1) keyword-search commands, 2)
regexp-search commands. Call #1 "apropos" and #2 "about-regexp" if you like,
but let's not try to mix them in the same command.

Best,

  Drew

RE: new apropos feature in Emacs-22

[Drew Adams]

I meant to send that reply to Lennart, not to the list. I'm truly sorry. -
Drew

    Hi Lennart,

    ...

Re: new apropos feature in Emacs-22

[Lennart Borgman]

Luc Teirlinck wrote:

>Lennart Borgman wrote:
>
>   - If something looking like a regexp was entered
>
>Most strings are valid regexps.  Only a few exceptions are not.
>  
>
Yes, but most strings does not look as regexps ;-)

Re: new apropos feature in Emacs-22

[Lennart Borgman]

Drew Adams wrote:

>Hi Lennart,
>
>    May I suggest a __simple___ solution:
>
>It's a joke, right? ;-)
>  
>
No.... but I will not defend it ;-)

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

    If the present convention is kept unchanged, then one should at the
    very least update the involved docstrings: although the Emacs manual
    mentions the new behavior, apparently none of the docstrings of the
    involved commands do.  All the docstrings still suggest that the
    REGEXP argument will always be treated as a regular expression.

We should certainly update the doc strings and manual, if we don't
change the behavior.

Someone else mentioned that there was a previous discussion.
I would like to reread it too.

Can someone tell me what range of dates it was, and a string
or strings I can search for to find those messages among
all the rest?

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Richard Stallman wrote:

   Someone else mentioned that there was a previous discussion.
   I would like to reread it too.

The thread starts at:

http://lists.gnu.org/archive/html/emacs-devel/2002-05/msg00397.html

   Can someone tell me what range of dates it was,

May 2002, as the above URL shows.

   and a string or strings I can search for to find those messages
   among all the rest?

"apropos commands and regexps" (_with_ the quotation marks included).

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Kim Storm wrote:

   Personally, I would have preferred to let apropos use keywords only
   (and I haven't used regexps in apropos since this change was made), but
   as a compromise,

One more example that compromises can be way worse than any of the
alternatives they compromise between.  In order of preference, I would
distinguish between regexps and keyword lists (or individual
keywords) by (1) an unambiguous notational convention, (2) by a user
option, or (3) by a combination of user option and separate functions.
The separate functions would call the regular functions while binding
the user option.

   we retained regexp matching if the search pattern looks like a regexp

You are trying to do the impossible.  "*scratch*" is clearly intended
as a literal keyword and "home directory" is likely to be meant as a
regexp, but your code concludes exactly the opposite.  No code can
decide whether something "looks like a regexp".

   I doubt this is a real problem.  Do you have any evidence (actual user
   complaints) to prove your case?

The current code has only been tested in CVS, by people familiar with
regexps.  Such people are aware that specifying *scratch*, .emacs or
ses+ as keywords is not going to work and know how to write the proper
regexps to get around that.

   The assumption is that most users will be accustomed to use keyword
   search, and only the experts will use regular expressions.

Are you sure that most newbies are accustomed to _your brand of_
keyword search: at least two alternatives in any order, with no way to
specify other requirements, _and_ with plenty of forbidden characters,
that are natural in an Emacs context, like `*', `.' `+'?  I never
encountered that before.  In the keyword searches that I am familiar
with you can enclose the keywords in quotation marks to force
sequential in order occurrence.  When doing web searches I nearly
invariably use quotation marks.  Moreover, in all keyword searches
that I am familiar with, it is perfectly possible to specify keywords
like *scratch*, .emacs or ses+.

I believe that after your change, newbies _still_ will have to learn
about regexps to accomplish what they are used to in search engines.
The only difference is that extra complexity and confusion is added on
top of the normal regexp rules.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> Date: Sat, 5 Nov 2005 19:57:38 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: drew.adams@oracle.com, emacs-devel@gnu.org
> 
> Are you sure that most newbies are accustomed to _your brand of_
> keyword search: at least two alternatives in any order, with no way to
> specify other requirements, _and_ with plenty of forbidden characters,
> that are natural in an Emacs context, like `*', `.' `+'?

Whether newbies are accustomed to this remains to be proven, but the
characters ``natural in the Emacs context'' above come from an
experienced user.

> In the keyword searches that I am familiar with you can enclose the
> keywords in quotation marks to force sequential in order occurrence.

That's an advanced feature, you know.

> I believe that after your change, newbies _still_ will have to learn
> about regexps to accomplish what they are used to in search engines.

Please explain why you think so.

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Eli Zaretskii wrote:

   Whether newbies are accustomed to this remains to be proven, but the
   characters ``natural in the Emacs context'' above come from an
   experienced user.

.emacs and *scratch* are only for experienced users?

   > In the keyword searches that I am familiar with you can enclose the
   > keywords in quotation marks to force sequential in order occurrence.

   That's an advanced feature, you know.

Really?  I always use quotation marks in websearches and would not
know how to search without them.  For instance, Richard asked us for a
string that gave him all postings in the old thread we are talking
about and nothing else and I said:

"apropos commands and regexps" (_with_ the quotation marks included).

It works.  Exactly all 56 postings in the thread, nothing else,
`apropos commands' without quotation marks gives 124 hits, 56 correct
ones and 68 false ones.  With the at least two hits rule, specifying
additional keywords makes things worse.

   > I believe that after your change, newbies _still_ will have to learn
   > about regexps to accomplish what they are used to in search engines.

   Please explain why you think so.

Several reasons.

Because you may want to search for, say, the words "overwrite mode" in
that order, separated only by non-word constituents.  The fact that
"mode" occurs somewhere in a doc string and "overwrite" somewhere else
is usually completely irrelevant and produces many false hits.
Sequential occurrence is _much_ less likely to be an accident than two
distinct keywords matching miles away in unrelated contexts.  Just do:

M-x apropos-documentation RET overwrite mode RET

and then: `C-s overwrite' and you will notice that the vast majority
of the matches in the 919 lines long buffer have absolutely nothing to
do with overwrite mode.

_And_ because sometimes you might want to search for keywords
containing characters that happen to be special in regexps, say
.emacs, .mailrc, whatever.  Why are these only for experienced users?

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sat, 5 Nov 2005 19:57:38 -0600 (CST)
>> From: Luc Teirlinck <teirllm@dms.auburn.edu>
>> Cc: drew.adams@oracle.com, emacs-devel@gnu.org
>> 
>> Are you sure that most newbies are accustomed to _your brand of_
>> keyword search: at least two alternatives in any order, with no way to
>> specify other requirements, _and_ with plenty of forbidden characters,
>> that are natural in an Emacs context, like `*', `.' `+'?
>
> Whether newbies are accustomed to this remains to be proven, but the
> characters ``natural in the Emacs context'' above come from an
> experienced user.
>
>> In the keyword searches that I am familiar with you can enclose the
>> keywords in quotation marks to force sequential in order occurrence.
>
> That's an advanced feature, you know.
>
>> I believe that after your change, newbies _still_ will have to learn
>> about regexps to accomplish what they are used to in search engines.
>
> Please explain why you think so.

We have string search and replace, and regexp search and replace.
Maybe regexp-apropos could be bound on C-h C-a .

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: new apropos feature in Emacs-22

[Stefan Monnier]

> The prompt string of the apropos commands says: (regexp or words).
> Which of the two and how do I choose?  The docstrings all say that it
> matches a regexp and do not mention keywords at all.

Rather than have two different commands or use yet another C-u prefix,
I suggest we replicate the M-r binding of isearch which allows toggling
between string and regexp searches.  It should of course toggle the prompt
as well between "(regexp)" and "(words)".


        Stefan

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> Date: Sat, 5 Nov 2005 23:36:17 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> 
>    Whether newbies are accustomed to this remains to be proven, but the
>    characters ``natural in the Emacs context'' above come from an
>    experienced user.
> 
> .emacs and *scratch* are only for experienced users?

You were talking about `.', `+', and `*' in general.

And yes, at least *scratch* is not something an unexperienced user
will look for, I think.

>    > In the keyword searches that I am familiar with you can enclose the
>    > keywords in quotation marks to force sequential in order occurrence.
> 
>    That's an advanced feature, you know.
> 
> Really?  I always use quotation marks in websearches

Then in my experience, you are a minority.

> and would not know how to search without them.

Just lose the quotes, it works ;-)

> For instance, Richard asked us for a
> string that gave him all postings in the old thread we are talking
> about and nothing else and I said:
> 
> "apropos commands and regexps" (_with_ the quotation marks included).
> 
> It works.

It could also misfire, e.g., if the actual phrase in the archives is
"regexps and apropos commands".  If you lose the quotes (and "and" as
well), you will find it regardless of the order.

In general, quotes are useful only if you know _exactly_ how the
phrase appears in the text, which is a relatively rare situation.
(I'm sure you know all this already.)

>    > I believe that after your change, newbies _still_ will have to learn
>    > about regexps to accomplish what they are used to in search engines.
> 
>    Please explain why you think so.
> 
> Several reasons.
> 
> Because you may want to search for, say, the words "overwrite mode" in
> that order, separated only by non-word constituents.

That's your ``always use quotes'' rule again; see above for why it
might not be useful for someone (like a newbie) who does not know the
exact phrase she is looking for.

> The fact that "mode" occurs somewhere in a doc string and
> "overwrite" somewhere else is usually completely irrelevant and
> produces many false hits.

False hits is a downside of any search engine (including `apropos' in
its pre-Emacs22 incarnation, btw).  Scoring and sorting according to
score--a new feature introduced together with the one we are
discussing--are supposed to alleviate that.

> Sequential occurrence is _much_ less likely to be an accident

Yes, _if_ you know the exact phrase.  A rather big IF, I'd say.
Mostly false for newbies, in my experience.

> _And_ because sometimes you might want to search for keywords
> containing characters that happen to be special in regexps, say
> .emacs, .mailrc, whatever.

A regexp ".emacs" will find a literal ".emacs", so this is not a big
problem.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sun, 06 Nov 2005 12:02:26 -0500
> Cc: eliz@gnu.org, emacs-devel@gnu.org
> 
> > The prompt string of the apropos commands says: (regexp or words).
> > Which of the two and how do I choose?  The docstrings all say that it
> > matches a regexp and do not mention keywords at all.
> 
> Rather than have two different commands or use yet another C-u prefix,
> I suggest we replicate the M-r binding of isearch which allows toggling
> between string and regexp searches.  It should of course toggle the prompt
> as well between "(regexp)" and "(words)".

I suggest that the prompt should also say that M-r toggles.

Re: new apropos feature in Emacs-22

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sat, 5 Nov 2005 23:36:17 -0600 (CST)
>> From: Luc Teirlinck <teirllm@dms.auburn.edu>

>> _And_ because sometimes you might want to search for keywords
>> containing characters that happen to be special in regexps, say
>> .emacs, .mailrc, whatever.
>
> A regexp ".emacs" will find a literal ".emacs", so this is not a big
> problem.

But it will also find "XEmacs" for an innocent little search term like
that.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Eli Zaretskii wrote:

   > _And_ because sometimes you might want to search for keywords
   > containing characters that happen to be special in regexps, say
   > .emacs, .mailrc, whatever.

   A regexp ".emacs" will find a literal ".emacs", so this is not a big
   problem.

With the current code, ".emacs init file" will trigger a regexp
search, whereas a newbie user unfamiliar with regexps might have
expected the usual "at least two matches" behavior.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> Cc: Luc Teirlinck <teirllm@dms.auburn.edu>,  emacs-devel@gnu.org
> From: David Kastrup <dak@gnu.org>
> Date: Sun, 06 Nov 2005 18:22:37 +0100
> 
> > A regexp ".emacs" will find a literal ".emacs", so this is not a big
> > problem.
> 
> But it will also find "XEmacs" for an innocent little search term like
> that.

Yes, and why is that a problem?

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> Date: Sun, 6 Nov 2005 12:31:27 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: emacs-devel@gnu.org
> 
> With the current code, ".emacs init file" will trigger a regexp
> search, whereas a newbie user unfamiliar with regexps might have
> expected the usual "at least two matches" behavior.

A search engine quite frequently brings unexpected matches, based on
its convoluted heuristics.  Perhaps you are unfamiliar with that
phenomenon because you tend to use quoted phrases (which defeat those
heuristics), but it's normal for majority of users I've seen.

Searching large bodies of text will never be an exact science.

Re: new apropos feature in Emacs-22

[Kim F. Storm]

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

>
> Because you may want to search for, say, the words "overwrite mode" in
> that order, separated only by non-word constituents.  The fact that
> "mode" occurs somewhere in a doc string and "overwrite" somewhere else
> is usually completely irrelevant and produces many false hits.
> Sequential occurrence is _much_ less likely to be an accident than two
> distinct keywords matching miles away in unrelated contexts.  Just do:
>
> M-x apropos-documentation RET overwrite mode RET
>
> and then: `C-s overwrite' and you will notice that the vast majority
> of the matches in the 919 lines long buffer have absolutely nothing to
> do with overwrite mode.

If we set apropos-sort-by-scores to t, then the most relevant
entries would be listed first.  The lesser important entries
are showed later.

IIRC, sort by scores was not turned on by default because it
was said to confuse people who expect at least the simple
apropos commands to list e.g. variables and functions in
alphabetical order.

But for apropos-documentation, it doesn't really make much sense to
ever sort things alphabetically, so maybe it makes sense to
unconditionally set apropos-sort-by-scores to t for
apropos-documentation.  Then the "false matches" will at least be
listed after the good ones.

A patch is attached below.  It seems to improve things "a lot".


> _And_ because sometimes you might want to search for keywords
> containing characters that happen to be special in regexps, say
> .emacs, .mailrc, whatever.  Why are these only for experienced users?

Yes, .emacs is a hard one -- but it is a very special case IMO.
Perhaps we could make an expection for it.  In any case C-s .emacs
easily finds the relevant matches.

Did you try to do C-h C-d .mailrc ?  I don't see any false matches there.

And for C-h C-d *scratch* RET, it finds all the relevant matches AFAICS.

I still don't see the "serious" problem here.


*** apropos.el	19 Sep 2005 00:24:21 +0200	1.106
--- apropos.el	06 Nov 2005 19:04:04 +0100	
***************
*** 106,114 ****
  
  (defcustom apropos-sort-by-scores nil
    "*Non-nil means sort matches by scores; best match is shown first.
! The computed score is shown for each match."
    :group 'apropos
!   :type 'boolean)
  
  (defvar apropos-mode-map
    (let ((map (make-sparse-keymap)))
--- 106,116 ----
  
  (defcustom apropos-sort-by-scores nil
    "*Non-nil means sort matches by scores; best match is shown first.
! If value is `verbose', the computed score is shown for each match."
    :group 'apropos
!   :type '(choice (const :tag "off" nil)
! 		 (const :tag "on" t)
! 		 (const :tag "show scores" verbose)))
  
  (defvar apropos-mode-map
    (let ((map (make-sparse-keymap)))
***************
*** 570,575 ****
--- 572,578 ----
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator () apropos-files-scanned ())
    (let ((standard-input (get-buffer-create " apropos-temp"))
+ 	(apropos-sort-by-scores (or apropos-sort-by-scores t)) ;; verbose?
  	f v sf sv)
      (unwind-protect
  	(save-excursion
***************
*** 822,828 ****
  			      ;; changed the variable!
  			      ;; Just say `no' to variables containing faces!
  			      'face apropos-symbol-face)
! 	  (if apropos-sort-by-scores
  	      (insert " (" (number-to-string (cadr apropos-item)) ") "))
  	  ;; Calculate key-bindings if we want them.
  	  (and do-keys
--- 825,831 ----
  			      ;; changed the variable!
  			      ;; Just say `no' to variables containing faces!
  			      'face apropos-symbol-face)
! 	  (if (eq apropos-sort-by-scores 'verbose)
  	      (insert " (" (number-to-string (cadr apropos-item)) ") "))
  	  ;; Calculate key-bindings if we want them.
  	  (and do-keys

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

   Yes, .emacs is a hard one -- but it is a very special case IMO.

This is just an example, of course.  Plenty of standard files (most,
actually) have `.'s in their names, plenty of standard buffers (most
of them) have `*'s in their names, several functions have *'s in
their names, say let* or list*, several variables have *'s in their
names (cl actually has tons of these variables and functions), some
have `+' in their name.  I can go on and on.  Most of the characters
that are "special" in regexps are common outside of regexps too.

   Did you try to do C-h C-d .mailrc ?

Is that a personal binding of yours?  For me, C-h C-d runs
`describe-distribution'.

   Did you try to do C-h C-d .mailrc ?  I don't see any false matches there.

   And for C-h C-d *scratch* RET, it finds all the relevant matches AFAICS.

   I still don't see the "serious" problem here.

The problem is that a if you put .mailrc, *scratch*, let* or whatever
in a list of keywords, then that list of keywords turns into a regexp.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Stefan Monnier wrote:

   Rather than have two different commands or use yet another C-u prefix,
   I suggest we replicate the M-r binding of isearch which allows toggling
   between string and regexp searches.  It should of course toggle the prompt
   as well between "(regexp)" and "(words)".

That seems like a good solution.  Maybe we could also have a user
option to determine which of "(regexp)" or "(words)" comes up by
default, so people who always use one of the two do not have to do an
extra M-r each time.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Eli Zaretskii wrote:

   That's your ``always use quotes'' rule again; see above for why it
   might not be useful for someone (like a newbie) who does not know the
   exact phrase she is looking for.

Phrases like "global font lock mode" or "text only terminal" are
conceptually single items, even though, without quoting, to the
computer they look like four or three unrelated keywords.  That is
exactly why one _needs_ quoting in searches.

A newbie using apropos can not be assumed to be 100% ignorant: one way
or the other he managed to find out about the apropos commands.  So he
should be familiar with at least some multi-word phrases that are
conceptually a single item.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Kim F. Storm]

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

> Eli Zaretskii wrote:
>
>    That's your ``always use quotes'' rule again; see above for why it
>    might not be useful for someone (like a newbie) who does not know the
>    exact phrase she is looking for.
>
> Phrases like "global font lock mode" or "text only terminal" are
> conceptually single items, even though, without quoting, to the
> computer they look like four or three unrelated keywords.  That is
> exactly why one _needs_ quoting in searches.

With apropos-sort-by-scores turned on, apropos-documentation returns
the following entries for "global font lock mode" (in this sequence):

global-font-lock-mode
  Command: Toggle Font-Lock mode in every buffer.
font-lock-mode
  Command: Toggle Font Lock mode.
font-lock-global-modes
  Variable: *Modes for which Font Lock mode is automagically turned on.
hi-lock-mode
  Command: Toggle minor mode for interactively adding font-lock highlighting patterns.
font-lock-support-mode
  Variable: *Support mode for Font Lock mode.
jit-lock-mode
  Function: Toggle Just-in-time Lock mode.
{the list is much longer, but most entries have some relevance}

On the other hand, if you search for the regexp "global font lock
mode", you get just two entries (not including the obvious
"global-font-lock-mode"):

font-lock-global-modes
  Variable: *Modes for which Font Lock mode is automagically turned on.
font-lock-mode
  Command: Toggle Font Lock mode.



BTW, I strongly doubt that any novice user will search for anything
remotely similar to "font lock". Instead they will search for "syntax
highlighting" -- where regexp and keyword search produces similar
results -- or they will search for "highlight syntax" where regexp
shows nothing, while keywords show that same result as before.

To me it is a bit strange that someone who favours regexp search is so
worried about the potential pitfalls of the novice, while those of us
who advocate keyword searches don't see the big problem...

> A newbie using apropos can not be assumed to be 100% ignorant: one way
> or the other he managed to find out about the apropos commands.  So he
> should be familiar with at least some multi-word phrases that are
> conceptually a single item.

And keyword search will find then -- and place them high on the list
with sort-by-score enabled.

In any case, I'll try to make some corrections to the scoring algorithm
to make it behave better when the search string/regexp matches literally
as well as a regexp (e.g. for .emacs or *scratch*).  It's almost there,
but there are a few rough edges...

--
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Kin Storm wrote:

   Did you try to do C-h C-d .mailrc ?  I don't see any false matches there.

(I guess you somehow mean `M-x apropos-documentation' instead of `C-h
C-d'.)  Just to make sure that you understand the real problem: with
the current code, `mail alias .mailrc' will not match the text
"mail alias in your .mailrc file" although a user unfamiliar with
regexps and familiar with your "at least two matches" rule would
expect it to match.

But, if we go for Stefan's solution, that problem would disappear anyway.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Alan Mackenzie]

On Sun, 6 Nov 2005, Eli Zaretskii wrote:

>> With the current code, ".emacs init file" will trigger a regexp
>> search, whereas a newbie user unfamiliar with regexps might have
>> expected the usual "at least two matches" behavior.

>A search engine quite frequently brings unexpected matches, based on its
>convoluted heuristics.  Perhaps you are unfamiliar with that phenomenon
>because you tend to use quoted phrases (which defeat those heuristics),
>but it's normal for majority of users I've seen.

I don't think this is an attribute that Emacs should emulate.  I have
frequently cursed the inability of search engines to accept regular
expressions as input.

Surely an Emacs user should be able to formulate a search criterion
without having to jump through hoops of dwimmyness, without the
uncertainty of not knowing how Emacs interprets his search string.  As
David Kastrup points out, these uncertainties come up in search strings
that will be used all the time, not occasional things that will occur
once in a blue moon.

Searching for a regular expression and searching for a match to any of a
list of keywords are distinct operations.  Surely they should have
distinct commands too.

-- 
Alan Mackenzie (Munich, Germany)

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

I looked at the previous discussion, and it seems to me that the
only change we need is in doc strings, prompts, and argument names.
Here's what I am thinking of installing.


*** apropos.el	18 Sep 2005 09:53:38 -0400	1.106
--- apropos.el	06 Nov 2005 15:09:10 -0500	
***************
*** 126,135 ****
  (defvar apropos-mode-hook nil
    "*Hook run when mode is turned on.")
  
! (defvar apropos-regexp nil
    "Regexp used in current apropos run.")
  
! (defvar apropos-orig-regexp nil
    "Regexp as entered by user.")
  
  (defvar apropos-all-regexp nil
--- 126,135 ----
  (defvar apropos-mode-hook nil
    "*Hook run when mode is turned on.")
  
! (defvar apropos-pattern nil
    "Regexp used in current apropos run.")
  
! (defvar apropos-orig-pattern nil
    "Regexp as entered by user.")
  
  (defvar apropos-all-regexp nil
***************
*** 270,278 ****
  	    "")))
  
  (defun apropos-rewrite-regexp (regexp)
!   "Rewrite a list of words to a regexp matching all permutations.
! If REGEXP is already a regexp, don't modify it."
!   (setq apropos-orig-regexp regexp)
    (setq apropos-words () apropos-all-words ())
    (if (string-equal (regexp-quote regexp) regexp)
        ;; We don't actually make a regexp matching all permutations.
--- 270,279 ----
  	    "")))
  
  (defun apropos-rewrite-regexp (regexp)
!   "Rewrite a space-separated words list to a regexp matching all permutations.
! If REGEXP contains any special regexp characters, that means it
! is already a regexp, so return it unchanged."
!   (setq apropos-orig-pattern regexp)
    (setq apropos-words () apropos-all-words ())
    (if (string-equal (regexp-quote regexp) regexp)
        ;; We don't actually make a regexp matching all permutations.
***************
*** 376,382 ****
                                (if (or current-prefix-arg apropos-do-all)
  				  "variable"
  				"user option")
!                               " (regexp or words): "))
                       current-prefix-arg))
    (apropos-command regexp nil
  		   (if (or do-all apropos-do-all)
--- 377,383 ----
                                (if (or current-prefix-arg apropos-do-all)
  				  "variable"
  				"user option")
!                               " (word list or regexp): "))
                       current-prefix-arg))
    (apropos-command regexp nil
  		   (if (or do-all apropos-do-all)
***************
*** 389,396 ****
  ;;;###autoload
  (defalias 'command-apropos 'apropos-command)
  ;;;###autoload
! (defun apropos-command (apropos-regexp &optional do-all var-predicate)
!   "Show commands (interactively callable functions) that match APROPOS-REGEXP.
  With optional prefix DO-ALL, or if `apropos-do-all' is non-nil, also show
  noninteractive functions.
  
--- 390,402 ----
  ;;;###autoload
  (defalias 'command-apropos 'apropos-command)
  ;;;###autoload
! (defun apropos-command (apropos-pattern &optional do-all var-predicate)
!   "Show commands (interactively callable functions) that match APROPOS-PATTERN.
! APROPOS-PATTERN can be a word, a list of words (separated by spaces),
! or a regexp (using some regexp special characters).  If it is a word,
! search for matches for that word as a substring.  If it is a list of words,
! search for matches for any two (or more) of those words.
! 
  With optional prefix DO-ALL, or if `apropos-do-all' is non-nil, also show
  noninteractive functions.
  
***************
*** 401,415 ****
  				   (if (or current-prefix-arg
  					   apropos-do-all)
  				       "or function ")
! 				   "(regexp or words): "))
  		     current-prefix-arg))
!   (setq apropos-regexp (apropos-rewrite-regexp apropos-regexp))
    (let ((message
  	 (let ((standard-output (get-buffer-create "*Apropos*")))
  	   (print-help-return-message 'identity))))
      (or do-all (setq do-all apropos-do-all))
      (setq apropos-accumulator
! 	  (apropos-internal apropos-regexp
  			    (or var-predicate
  				(if do-all 'functionp 'commandp))))
      (let ((tem apropos-accumulator))
--- 407,421 ----
  				   (if (or current-prefix-arg
  					   apropos-do-all)
  				       "or function ")
! 				   "(word list or regexp): "))
  		     current-prefix-arg))
!   (setq apropos-pattern (apropos-rewrite-regexp apropos-pattern))
    (let ((message
  	 (let ((standard-output (get-buffer-create "*Apropos*")))
  	   (print-help-return-message 'identity))))
      (or do-all (setq do-all apropos-do-all))
      (setq apropos-accumulator
! 	  (apropos-internal apropos-pattern
  			    (or var-predicate
  				(if do-all 'functionp 'commandp))))
      (let ((tem apropos-accumulator))
***************
*** 457,471 ****
  
  
  ;;;###autoload
! (defun apropos (apropos-regexp &optional do-all)
!   "Show all bound symbols whose names match APROPOS-REGEXP.
  With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also
  show unbound symbols and key bindings, which is a little more
  time-consuming.  Returns list of symbols and documentation found."
!   (interactive "sApropos symbol (regexp or words): \nP")
!   (setq apropos-regexp (apropos-rewrite-regexp apropos-regexp))
    (apropos-symbols-internal
!    (apropos-internal apropos-regexp
  			  (and (not do-all)
  			       (not apropos-do-all)
  			       (lambda (symbol)
--- 463,482 ----
  
  
  ;;;###autoload
! (defun apropos (apropos-pattern &optional do-all)
!   "Show all bound symbols whose names match APROPOS-PATTERN.
! APROPOS-PATTERN can be a word, a list of words (separated by spaces),
! or a regexp (using some regexp special characters).  If it is a word,
! search for matches for that word as a substring.  If it is a list of words,
! search for matches for any two (or more) of those words.
! 
  With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also
  show unbound symbols and key bindings, which is a little more
  time-consuming.  Returns list of symbols and documentation found."
!   (interactive "sApropos symbol (word list or regexp): \nP")
!   (setq apropos-pattern (apropos-rewrite-regexp apropos-pattern))
    (apropos-symbols-internal
!    (apropos-internal apropos-pattern
  			  (and (not do-all)
  			       (not apropos-do-all)
  			       (lambda (symbol)
***************
*** 520,540 ****
  
  
  ;;;###autoload
! (defun apropos-value (apropos-regexp &optional do-all)
!   "Show all symbols whose value's printed image matches APROPOS-REGEXP.
  With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also looks
  at the function and at the names and values of properties.
  Returns list of symbols and values found."
!   (interactive "sApropos value (regexp or words): \nP")
!   (setq apropos-regexp (apropos-rewrite-regexp apropos-regexp))
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator ())
     (let (f v p)
       (mapatoms
        (lambda (symbol)
  	(setq f nil v nil p nil)
! 	(or (memq symbol '(apropos-regexp
! 			   apropos-orig-regexp apropos-all-regexp
  			   apropos-words apropos-all-words
  			   do-all apropos-accumulator
  			   symbol f v p))
--- 531,556 ----
  
  
  ;;;###autoload
! (defun apropos-value (apropos-pattern &optional do-all)
!   "Show all symbols whose value's printed image matches APROPOS-PATTERN.
! APROPOS-PATTERN can be a word, a list of words (separated by spaces),
! or a regexp (using some regexp special characters).  If it is a word,
! search for matches for that word as a substring.  If it is a list of words,
! search for matches for any two (or more) of those words.
! 
  With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also looks
  at the function and at the names and values of properties.
  Returns list of symbols and values found."
!   (interactive "sApropos value (word list or regexp): \nP")
!   (setq apropos-pattern (apropos-rewrite-regexp apropos-pattern))
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator ())
     (let (f v p)
       (mapatoms
        (lambda (symbol)
  	(setq f nil v nil p nil)
! 	(or (memq symbol '(apropos-pattern
! 			   apropos-orig-pattern apropos-all-regexp
  			   apropos-words apropos-all-words
  			   do-all apropos-accumulator
  			   symbol f v p))
***************
*** 559,572 ****
  
  
  ;;;###autoload
! (defun apropos-documentation (apropos-regexp &optional do-all)
!   "Show symbols whose documentation contain matches for APROPOS-REGEXP.
  With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also use
  documentation that is not stored in the documentation file and show key
  bindings.
  Returns list of symbols and documentation found."
!   (interactive "sApropos documentation (regexp or words): \nP")
!   (setq apropos-regexp (apropos-rewrite-regexp apropos-regexp))
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator () apropos-files-scanned ())
    (let ((standard-input (get-buffer-create " apropos-temp"))
--- 575,593 ----
  
  
  ;;;###autoload
! (defun apropos-documentation (apropos-pattern &optional do-all)
!   "Show symbols whose documentation contain matches for APROPOS-PATTERN.
! APROPOS-PATTERN can be a word, a list of words (separated by spaces),
! or a regexp (using some regexp special characters).  If it is a word,
! search for matches for that word as a substring.  If it is a list of words,
! search for matches for any two (or more) of those words.
! 
  With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also use
  documentation that is not stored in the documentation file and show key
  bindings.
  Returns list of symbols and documentation found."
!   (interactive "sApropos documentation (word list or regexp): \nP")
!   (setq apropos-pattern (apropos-rewrite-regexp apropos-pattern))
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator () apropos-files-scanned ())
    (let ((standard-input (get-buffer-create " apropos-temp"))
***************
*** 610,616 ****
    (if (funcall predicate symbol)
        (progn
  	(setq symbol (prin1-to-string (funcall function symbol)))
! 	(if (string-match apropos-regexp symbol)
  	    (progn
  	      (if apropos-match-face
  		  (put-text-property (match-beginning 0) (match-end 0)
--- 631,637 ----
    (if (funcall predicate symbol)
        (progn
  	(setq symbol (prin1-to-string (funcall function symbol)))
! 	(if (string-match apropos-pattern symbol)
  	    (progn
  	      (if apropos-match-face
  		  (put-text-property (match-beginning 0) (match-end 0)
***************
*** 637,643 ****
    (let (p p-out)
      (while pl
        (setq p (format "%s %S" (car pl) (nth 1 pl)))
!       (if (or (not compare) (string-match apropos-regexp p))
  	  (if apropos-property-face
  	      (put-text-property 0 (length (symbol-name (car pl)))
  				 'face apropos-property-face p))
--- 658,664 ----
    (let (p p-out)
      (while pl
        (setq p (format "%s %S" (car pl) (nth 1 pl)))
!       (if (or (not compare) (string-match apropos-pattern p))
  	  (if apropos-property-face
  	      (put-text-property 0 (length (symbol-name (car pl)))
  				 'face apropos-property-face p))
***************
*** 653,659 ****
      p-out))
  
  
! ;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
  
  (defun apropos-documentation-check-doc-file ()
    (let (type symbol (sepa 2) sepb beg end)
--- 674,680 ----
      p-out))
  
  
! ;; Finds all documentation related to APROPOS-PATTERN in internal-doc-file-name.
  
  (defun apropos-documentation-check-doc-file ()
    (let (type symbol (sepa 2) sepb beg end)
***************
*** 782,788 ****
  If SPACING is non-nil, it should be a string; separate items with that string.
  If non-nil TEXT is a string that will be printed as a heading."
    (if (null apropos-accumulator)
!       (message "No apropos matches for `%s'" apropos-orig-regexp)
      (setq apropos-accumulator
  	  (sort apropos-accumulator
  		(lambda (a b)
--- 803,809 ----
  If SPACING is non-nil, it should be a string; separate items with that string.
  If non-nil TEXT is a string that will be printed as a heading."
    (if (null apropos-accumulator)
!       (message "No apropos matches for `%s'" apropos-orig-pattern)
      (setq apropos-accumulator
  	  (sort apropos-accumulator
  		(lambda (a b)

RE: new apropos feature in Emacs-22

[Drew Adams]

This feature changes the syntax and meaning of the input to apropos
functions. We've discussed the effects on the users of apropos commands.

There is also a (similar) effect on the programmatic use to consider. While
it is true that there are internal apropos functions that programs could use
instead of using the end-user commands:

1. There is no guarantee that programs do not use the end-user commands.

2. In some cases, there is no internal function that directly does what's
needed. For example, there is no internal equivalent of `apropos-variable'
(IIUC).

3. There is (still) no documentation for most of the internal commands
(apropos-documentation-check-doc-file, apropos-documentation-check-elc-file,
apropos-documentation-internal, apropos-symbols-internal,
apropos-value-internal). This can suggest to programmers that the internal
functions are not intended to be used externally.

Most of the discussion has centered on _how_ to obtain the syntax and
behavior of both the old (regexp) and the new (keywords) apropos at the same
time, in the same command - not on whether or not that is desirable.

The latest suggestion for combining the old and new in the same command was
to use `M-r' to toggle between old and new (in addition to `C-u' to toggle
`do-all') - and to add a new user option for selecting the default behavior.
This, like the other suggestions, is workable, but it doesn't help existing
programmatic use of the commands.

In order to not break existing code:

1. An extra (e.g. optional) parameter would need to be provided to the
commands.

2. Its default value (nil) would need to reflect the old behavior.

#2 conflicts with the desire to make the default syntax and behavior be
keyword search, in order to be more "novice user-friendly". We could treat
the interactive and programmatic values oppositely wrt to this parameter, of
course, but that would be downright mischievous.

I argued that the old and new syntaxes and behaviors should be implemented
in different commands. That would give all users what they want, without the
complexities of modes and mixed syntaxes. It would also not break any
existing code.

(I also said that I didn't care which commands got the "apropos" name, but
I've changed my mind on that, after thinking about existing programs that
might expect the old behavior from the "apropos" names. That is, I don't
really care about the names, but existing programs might.)

I've still seen _no argument_ (i.e. no rationale) voiced against using
separate commands. One could argue "Occam's razor: don't multiply things
needlessly", but that applies equally to all approaches discussed so far -
whether we multiply the number of commands or the number of use modes (e.g.
`M-r' toggle) for the existing commands.

So, I repeat the question:  _Why not_ leave the apropos commands as they
were, and create new, more "novice user-friendly", keyword-search commands?
The question deserves some reply, at least. It should have been addressed
before launching a discussion of _how_ to change the existing commands.

Re: new apropos feature in Emacs-22

[Stefan Monnier]

> I argued that the old and new syntaxes and behaviors should be implemented
> in different commands.  That would give all users what they want, without
> the complexities of modes and mixed syntaxes.  It would also not break any
> existing code.

Having separate commands means that you can't have both behaviors on the
same key-binding.  I like using the keybindings, and I sometimes need
regexps but generally prefer the keyword search.  That's the main reason
why I'm proposing the M-r solution.  I'd argue that the M-r solution should
also be added to query-replace, BTW.


        Stefan

RE: new apropos feature in Emacs-22

[Drew Adams]

    > I argued that the old and new syntaxes and behaviors should
    be implemented
    > in different commands.  That would give all users what they
    want, without
    > the complexities of modes and mixed syntaxes.  It would also
    not break any
    > existing code.

    Having separate commands means that you can't have both behaviors on the
    same key-binding.  I like using the keybindings, and I sometimes need
    regexps but generally prefer the keyword search.  That's the main reason
    why I'm proposing the M-r solution.

A good argument - worth stating explicitly for the discussion. Thx.

I guess I'd still prefer that we offer separate commands, with the built-in
bindings going to the novice-friendly commands. But I agree that key-binding
is a good argument for not using separate commands.

I prefer separate commands because I think we're asking for trouble by
mixing two radically different input syntaxes - especially if we're worried
about novices.

Although radically different, the syntaxes have some overlap (even if that
sounds paradoxical). They can seem the same (with similar behavior) in some
common cases, as others have pointed out, but they are not the same.
Sometimes, les faux amis are worse than les enemis, because of the
additional element of confusion.

    I'd argue that the M-r solution should also be added to query-replace,
BTW.

Do you mean for regexp vs literal input? I don't disagree with some such a
toggle. In fact, I use a command (bound to M-%) that works this way:

 - No PREFIX argument (nil) means replace literal string matches.

 - Positive PREFIX argument means replace word matches.

 - Negative PREFIX argument means replace regexp matches.

So, you see that I'm not insensitive to the single-key-binding argument.

Anyway, this is changing the subject; it should be a separate thread, if
pursued.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> Date: Mon, 7 Nov 2005 09:45:11 +0000 (GMT)
> From: Alan Mackenzie <acm@muc.de>
> cc: emacs-devel@gnu.org
> 
> On Sun, 6 Nov 2005, Eli Zaretskii wrote:
> 
> >> With the current code, ".emacs init file" will trigger a regexp
> >> search, whereas a newbie user unfamiliar with regexps might have
> >> expected the usual "at least two matches" behavior.
> 
> >A search engine quite frequently brings unexpected matches, based on its
> >convoluted heuristics.  Perhaps you are unfamiliar with that phenomenon
> >because you tend to use quoted phrases (which defeat those heuristics),
> >but it's normal for majority of users I've seen.
> 
> I don't think this is an attribute that Emacs should emulate.

We are not emulating any behavior, we just get hit by the same
problems as other search engines.

> Surely an Emacs user should be able to formulate a search criterion
> without having to jump through hoops of dwimmyness, without the
> uncertainty of not knowing how Emacs interprets his search string.  As
> David Kastrup points out, these uncertainties come up in search strings
> that will be used all the time, not occasional things that will occur
> once in a blue moon.

You are talking about something completely unrelated to what I was
saying.  While that's okay, why start it by quoting me?

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 7 Nov 2005 09:54:00 -0800
> 
> Most of the discussion has centered on _how_ to obtain the syntax and
> behavior of both the old (regexp) and the new (keywords) apropos at the same
> time, in the same command - not on whether or not that is desirable.

That's because everybody agreed that it was desirable.  There was no
need to discuss that about which we were in almost perfect agreement.

> So, I repeat the question:  _Why not_ leave the apropos commands as they
> were, and create new, more "novice user-friendly", keyword-search commands?
> The question deserves some reply, at least. It should have been addressed
> before launching a discussion of _how_ to change the existing commands.

This question was asked and answered.  I posted the URL here.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> Date: Mon, 7 Nov 2005 09:45:11 +0000 (GMT)
> From: Alan Mackenzie <acm@muc.de>
> Cc: emacs-devel@gnu.org
> 
> I have frequently cursed the inability of search engines to accept
> regular expressions as input.

Which ones?  Numazu, for example, does support regexps.

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

    With the current code, ".emacs init file" will trigger a regexp
    search, whereas a newbie user unfamiliar with regexps might have
    expected the usual "at least two matches" behavior.

Perhaps we should change the criteria so that a period does
not make it a regexp.  A different criterion would be ok
as long as it is simple.

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

Your patch for three values of apropos-sort-by-scores is good.
The idea of always showing scores for apropos-documentation also
seems good, but I think there should be a separate variable for that;
it shouldn't be forced to t.

Re: new apropos feature in Emacs-22

[Lennart Borgman]

Stefan Monnier wrote:

>Having separate commands means that you can't have both behaviors on the
>same key-binding.  I like using the keybindings, and I sometimes need
>regexps but generally prefer the keyword search.  That's the main reason
>why I'm proposing the M-r solution.  I'd argue that the M-r solution should
>also be added to query-replace, BTW.
>  
>
I like this idea if it is used consistently. Then it is easy to remember.

RE: new apropos feature in Emacs-22

[Drew Adams]

    > Most of the discussion has centered on _how_ to obtain the syntax and
    > behavior of both the old (regexp) and the new (keywords)
    apropos at the same
    > time, in the same command - not on whether or not that is desirable.

    That's because everybody agreed that it was desirable.  There was no
    need to discuss that about which we were in almost perfect agreement.

I've seen at least a couple of posts that indicate support for not combining
these in the same command. But you might be right that we are in the
minority. It's hard to tell, if the question isn't discussed - which is why
I raised it.

    > So, I repeat the question:  _Why not_ leave the apropos
    > commands as they were, and create new, more "novice
    > user-friendly", keyword-search commands?  The question
    > deserves some reply, at least. It should have been addressed
    > before launching a discussion of _how_ to change the existing
    > commands.

    This question was asked and answered.  I posted the URL here.

Stefan gave a good answer (key bindings) - today. But I did not see that
question asked or answered in the thread you cited. Can you please point out
the relevant passage?

Or did you mean only this, which I quoted earlier:

 - All apropos commands should `accept the same type of "search patterns".'

I already asked if that was all you meant, or if I was missing something you
saw in the thread. I have assumed the former, for lack of a reply, but let
me ask again.

If that is the only answer in the thread to the question, then just what
constitutes an "apropos command" in this regard? Is it any command that
returns information about something? Is it any command that has "apropos" in
its name? Does it refer only to the existing set of commands with "apropos"
in their names?

When I asked why all "apropos commands" should accept the same type of
input, Kim replied that it was obviously for user-friendliness.

If the existing set of commands with "apropos" in their names continued to
accept only regexps, and a new suite of commands, called, say,
`keywords-about-'* accepted only keywords, would that not be user-friendly?

Isn't it friendlier to users to make sure that the input syntax for a
command is simple, clear-cut, and unambiguous - with no surprises? Is having
two sets of commands, clearly distinguished by name, more confusing than
making users figure out how to finagle a crossbreed syntax to get one or the
other behavior?

That said, Stefan's proposal solves the syntax problem while still using the
same command - the two syntaxes would never be mixed (active at the same
time). The only problem I see with it is the problem of a default behavior
that both:

 - is suitable for newbies (=> keyword search, by default)

and

 - doesn't break existing code (=> regexp search, by default)

If we can somehow cut that knot, we might all agree on a solution. If not,
I'd still argue for separate commands.

One thing that might work is to create new commands for users, with the
toggle behavior that Stefan described (and the default in favor of
keywords). If the names are new, that change won't affect existing code. And
we can then deprecate the interactive use of the existing apropos
functions - or at least advertise only the new commands. That last step
should satisfy those who don't want two different sets of commands.

The only loss would be the current command names, for interactive use.
"Apropos", in this context, just means "about". We might call the new
commands `about', `about-variable', `about-documentation', etc. - but that
would be a bit misleading.

On the other hand, the action involved is really just a literal keyword
lookup - a search. So, more appropriate names would be `search-symbols',
`search-variables', `search-documentation', etc.  Or, better, `find-symbols'
etc. - because symbols etc. are not searched; they are found. Newbies would
in fact be more likely to stumble upon `find-commands' than
`apropos-command'.

Re: new apropos feature in Emacs-22

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 7 Nov 2005 14:59:31 -0800
> 
>     > So, I repeat the question:  _Why not_ leave the apropos
>     > commands as they were, and create new, more "novice
>     > user-friendly", keyword-search commands?  The question
>     > deserves some reply, at least. It should have been addressed
>     > before launching a discussion of _how_ to change the existing
>     > commands.
> 
>     This question was asked and answered.  I posted the URL here.
> 
> Stefan gave a good answer (key bindings) - today. But I did not see that
> question asked or answered in the thread you cited. Can you please point out
> the relevant passage?

I raised that in the second or third message in the thread.

> Or did you mean only this, which I quoted earlier:
> 
>  - All apropos commands should `accept the same type of "search patterns".'

Yes, that's what I got as a reply back then, and since everybody but
me seemed to agree on that principle, I didn't fight it.

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

   I looked at the previous discussion, and it seems to me that the
   only change we need is in doc strings, prompts, and argument names.
   Here's what I am thinking of installing.

The help echos in `menu-bar-apropos-menu' (Help -> Search Documentation)
and the Info nodes (emacs)Help, (emacs)Help Summary and (emacs)Apropos
would also need updating and/or clarification.  I guess (emacs)Apropos
should wait until we have decided on the final details.

   Perhaps we should change the criteria so that a period does
   not make it a regexp.  A different criterion would be ok
   as long as it is simple.

I grepped for `apropos' in the lisp directory.  I now believe that
making the default recognize even less regexps carries a risk of
breaking some things, relatively close to a release.  There were tons
of complex matches and I do not have the time to try to understand all
of them and see what would break them.

I believe that (emacs)Apropos should _explicitly_ warn that, if one
wants to search by keywords, keywords should not contain regexp special
characters and warn in particular that filenames containing dots can
normally not be used as keywords.  As people will sometimes _want_ to
use things like .emacs, .mailrc or .XDefaults as keywords, especially
for apropos-documentation, some escape convention should be provided.
Why not use my original proposal: final unquoted `[' (or final single
`\') is ignored and means that the input is unconditionally a list of
keywords, for this specialized (but real) need?

If we are willing to make somewhat more changes, there could be a user
option `apropos-search-style' whose default value nil could be the
present default with the `[' escape convention added.  There would
also be values 'keyword and 'regexp for keyword only and regexp only.
If we are willing to do somewhat more, then M-r could be unbound for
the nil value and toggle between the two other values.

I believe that, certainly with the M-r binding available, most people
knowing about the option would set it to one of the two non-nil values.
But I would guess that a default of 'regexp (which would be 100%
backward compatible) will probably be deemed unacceptable and (unlike
before my grepping) I now am afraid that an all keyword default would
break several things.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Kim F. Storm]

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

> I grepped for `apropos' in the lisp directory.  I now believe that
> making the default recognize even less regexps carries a risk of
> breaking some things, relatively close to a release.  There were tons
> of complex matches and I do not have the time to try to understand all
> of them and see what would break them.

I grepped for apropos too, and I didn't find any "complex matches".

Most of the matches has nothing to do with apropos.el functionality.

There are some (clever) rules in gnus-art to make a hyperlink out
of e.g.
   M-x apropos-documentation RET init file RET
but this will DTRT, as it takes the string between RET ... RET and
pass it to e.g. apropos-documentation which is exactly TRTD.

There is also this little snippet in wid-edit.el:
    (if (and (fboundp symbol) (boundp symbol))
	;; If there are two doc strings, give the user a way to pick one.
	(apropos (concat "\\`" (regexp-quote string) "\\'"))
But this explicitly makes the arg. into a regexp.

The rest seems to be trivial, and will DTRT as is.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: new apropos feature in Emacs-22

[Miles Bader]

So is Luc's belly-aching over apropos actually based on any real data
(users getting confused by apropos behavior)?

The mere presence of potential confusion does not mean that it's
likely to happen in practice.

Given that the current behavior offers a nice advantage -- it supports
both traditional emacs users who might use a regexp, and newbies will
will likely just give a list of plain words, all without an annoying
and confusing proliferation of commands -- it seems to me there needs
to be a good reason to change it, more than just a _potential_ for
confusion.

[If you were to judge Emacs generally on a potential-for-confusion
basis, I think you'd have no alternative but to just toss the whole
thing out and tell users to use pico instead... :-]

-miles
--
Do not taunt Happy Fun Ball.

Re: new apropos feature in Emacs-22

[Lennart Borgman]

Miles Bader wrote:

>So is Luc's belly-aching over apropos actually based on any real data
>(users getting confused by apropos behavior)?
>
>The mere presence of potential confusion does not mean that it's
>likely to happen in practice.
>
And the absence of complaints unfortunately does not mean that everyone 
is not confused. If I ever did learn something while teaching it was to 
my surprise that a very common reason for not asking is beeing confused  ;-)

Re: new apropos feature in Emacs-22

[Kim F. Storm]

"Richard M. Stallman" <rms@gnu.org> writes:

> I looked at the previous discussion, and it seems to me that the
> only change we need is in doc strings, prompts, and argument names.
> Here's what I am thinking of installing.

These changes are definitely an improvement.

Could you please install those changes soon, so I can go on to fix
the remaining issues with apropos.

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

    Could you please install those changes soon, so I can go on to fix
    the remaining issues with apropos.

I installed them.  Thanks.

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

    I believe that (emacs)Apropos should _explicitly_ warn that, if one
    wants to search by keywords, keywords should not contain regexp special
    characters and warn in particular that filenames containing dots can
    normally not be used as keywords.

I will do that.

				       As people will sometimes _want_ to
    use things like .emacs, .mailrc or .XDefaults as keywords, especially
    for apropos-documentation, some escape convention should be provided.
    Why not use my original proposal: final unquoted `[' (or final single
    `\') is ignored and means that the input is unconditionally a list of
    keywords, for this specialized (but real) need?

I don't think this will be very useful, because the people it is most
aimed at are beginners and they are unlikely to remember that this
is available.

The only think I can think of that would help beginners with such
inputs would be to detect such cases and ask the user "Did you mean
this as a regexp or as a list of keywords?"  That question would
help people without requiring them to remember in advance that the
two options exist.

I have not looked at the program callers of the apropos commands.
If this is likely to break them, maybe we should not do it.
Otherwise, would you like to do it?

Re: new apropos feature in Emacs-22

[Kim F. Storm]

"Richard M. Stallman" <rms@gnu.org> writes:

> The only think I can think of that would help beginners with such
> inputs would be to detect such cases and ask the user "Did you mean
> this as a regexp or as a list of keywords?"  That question would
> help people without requiring them to remember in advance that the
> two options exist.

> I have not looked at the program callers of the apropos commands.
> If this is likely to break them, maybe we should not do it.
> Otherwise, would you like to do it?

This is on my to-do list.

The main problem is that current callers always supply a regexp.

I'm thinking about adding a new optional argument ENABLE-KEYWORDS
to all apropos commands and set it via an interactive "p" spec,
i.e. so it is set to an integer for interactive use (meaning: ask user).

Other callers could specify "nil" (default) to mean interpret PATTERN
as regexp, "t" to mean interpret PATTERN as words, and ">0" to mean ask
user, and "<0" to mean "automatically determine" without asking.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: new apropos feature in Emacs-22

[Miles Bader]

2005/11/11, Kim F. Storm <storm@cua.dk>:
> I'm thinking about adding a new optional argument ENABLE-KEYWORDS
> to all apropos commands and set it via an interactive "p" spec,
> i.e. so it is set to an integer for interactive use (meaning: ask user).
>
> Other callers could specify "nil" (default) to mean interpret PATTERN
> as regexp, "t" to mean interpret PATTERN as words, and ">0" to mean ask
> user, and "<0" to mean "automatically determine" without asking.

I think it would be a _lot_ more intuitive to just have apropos
functions interpret PATTERN as a regexp if it's a string, and as a
list of keywords if it's a list.  There could be a
"read-apropos-pattern" function that would convert the user's input
into the appropriate lisp value, which could be used directly in the
(interactive ) form of various apropos commands.

-Miles
--
Do not taunt Happy Fun Ball.

Re: new apropos feature in Emacs-22

[Kim F. Storm]

Miles Bader <snogglethorpe@gmail.com> writes:

> I think it would be a _lot_ more intuitive to just have apropos
> functions interpret PATTERN as a regexp if it's a string, and as a
> list of keywords if it's a list.  There could be a
> "read-apropos-pattern" function that would convert the user's input
> into the appropriate lisp value, which could be used directly in the
> (interactive ) form of various apropos commands.

Very good idea.  I'll see what I can do!

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

Richard Stallman wrote:

   The only think I can think of that would help beginners with such
   inputs would be to detect such cases and ask the user "Did you mean
   this as a regexp or as a list of keywords?"  That question would
   help people without requiring them to remember in advance that the
   two options exist.

It would be _very_ annoying if that question were asked each time that
an input could be interpreted as a regexp, especially for people who
are always going to use a regexp.

Also, I believe that if a beginning user uses apropos, it usually is
because they read some doc somewhere that told them that, for more
info, they could run a specific apropos command with a specific
regexp.  If a _true_ newbie literally follows somebody else's
instructions and he gets asked: keywords or regexps?, then he may not
know what to do.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Luc Teirlinck]

       Why not use my original proposal: final unquoted `[' (or final single
       `\') is ignored and means that the input is unconditionally a list of
       keywords, for this specialized (but real) need?

   I don't think this will be very useful, because the people it is most
   aimed at are beginners and they are unlikely to remember that this
   is available.

Complete beginners do not even know about the apropos commands.  Users
must have learned about them somewhere, probably in `(emacs)Apropos'.
If you them tell there that they normally can not use regexp special
characters in keywords, then I believe that it would be good to tell
them about a way out.  Maybe they may not remember the exact character
when they need it, but they will remember that the manual mentioned a
way out and they can check it back up.

It might also be useful to have an option `apropos-search-style',
whose default is the present method, but can also specify 'keywords or
'regexp.  I know that I can force regexp search by using stuff like
`[o]verwrite mode', but it is easy to forget and then I get confused
by all the nonsense I get.  I never intend to use anything else but
regexp search and I am convinced that this must be true for many other
users too.  In that case being forced to always make the input into
something Kim's procedure recognizes as a regexp is a nuisance.  It
makes apropos annoyingly different from other commands that use
regexps.

Sincerely,

Luc.

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

    I think it would be a _lot_ more intuitive to just have apropos
    functions interpret PATTERN as a regexp if it's a string, and as a
    list of keywords if it's a list.  There could be a
    "read-apropos-pattern" function that would convert the user's input
    into the appropriate lisp value, which could be used directly in the
    (interactive ) form of various apropos commands.

That is a very good idea.  Would someone like to do it?

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

       The only think I can think of that would help beginners with such
       inputs would be to detect such cases and ask the user "Did you mean
       this as a regexp or as a list of keywords?"  That question would
       help people without requiring them to remember in advance that the
       two options exist.

    It would be _very_ annoying if that question were asked each time that
    an input could be interpreted as a regexp,

I agree.  What I proposed was to ask this question only in cases like
".emacs file" where users might plausibly think they were keywords;
that is to say, only when period is the only special regexp character.
Those cases would not be very common, so the total annoyance will be
small.

    Also, I believe that if a beginning user uses apropos, it usually is
    because they read some doc somewhere that told them that, for more
    info, they could run a specific apropos command with a specific
    regexp.

It is probably because they read some documentation.  I don't follow
the last part of your sentence.  Anyway, I don't think that makes this
question unuseful.

Re: new apropos feature in Emacs-22

[Juri Linkov]

> Complete beginners do not even know about the apropos commands.  Users
> must have learned about them somewhere, probably in `(emacs)Apropos'.

More likely, from the Help buffer after typing `C-h ?' or `f1 f1':

a  command-apropos.  Give a substring, and see a list of commands
   (functions that are interactively callable) that contain
   that substring.  See also the  apropos  command.

Note that this description is incomplete.  It says nothing about
patterns, word lists or regexps.  Maybe it is simple enough for
beginners.  But it might be confusing for beginners if after reading
this description and typing `a' they will see a prompt asking for
"(word list or regexp): ".

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

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

    More likely, from the Help buffer after typing `C-h ?' or `f1 f1':

    a  command-apropos.  Give a substring, and see a list of commands
       (functions that are interactively callable) that contain
       that substring.  See also the  apropos  command.

I will clarify that.

Re: new apropos feature in Emacs-22

[Juri Linkov]

>     More likely, from the Help buffer after typing `C-h ?' or `f1 f1':
>
>     a  command-apropos.  Give a substring, and see a list of commands
>        (functions that are interactively callable) that contain
>        that substring.  See also the  apropos  command.
>
> I will clarify that.

In the new text:

a  command-apropos.  Give a list of words or a regexp, to get a list of
        commands whose names match (they contain two or more of the words,
                                                 ===========
	or a match for the regexp).  See also the  apropos  command.

I don't understand why two or more of the words, if it is possible to
give just one word and find a command whose names contains one word.
Maybe more correct text is "they contain one or more of the words".

I see there is a new key binding `C-h d' for `apropos-documentation'.
Wouldn't it be better to reserve `C-h d' for something more useful
and to bind `apropos-documentation' to a new key prefix `C-h a'?
This will allow key bindings for the whole family of apropos commands:

    C-h a d - apropos-documentation
    C-h a v - apropos-variable
    C-h a c - apropos-command
    C-h a l - apropos-value
    C-h a a - apropos

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

Re: new apropos feature in Emacs-22

[Richard M. Stallman]

    a  command-apropos.  Give a list of words or a regexp, to get a list of
	    commands whose names match (they contain two or more of the words,
						     ===========
	    or a match for the regexp).  See also the  apropos  command.

    I don't understand why two or more of the words, if it is possible to
    give just one word and find a command whose names contains one word.

Because, when you give multiple words, only instances that contain
two or more of the words are shown.

    Maybe more correct text is "they contain one or more of the words".

That would be incorrect, in the case of a list of two or more words.
But I agree this is a problem.  Who can find a correct solution?

    I see there is a new key binding `C-h d' for `apropos-documentation'.
    Wouldn't it be better to reserve `C-h d' for something more useful
    and to bind `apropos-documentation' to a new key prefix `C-h a'?

Things are complex enough already, so I don't want to go that way.

Re: new apropos feature in Emacs-22

[Juri Linkov]

>     a  command-apropos.  Give a list of words or a regexp, to get a list of
> 	    commands whose names match (they contain two or more of the words,
> 						     ===========
> 	    or a match for the regexp).  See also the  apropos  command.
>
>     I don't understand why two or more of the words, if it is possible to
>     give just one word and find a command whose names contains one word.
>
> Because, when you give multiple words, only instances that contain
> two or more of the words are shown.
>
>     Maybe more correct text is "they contain one or more of the words".
>
> That would be incorrect, in the case of a list of two or more words.
> But I agree this is a problem.  Who can find a correct solution?

What about not saying about the number of words:

    a  command-apropos.  Give a list of words or a regexp, to get a list of
            commands whose names match (they contain given words,
            or a match for the regexp).  See also the  apropos  command.

>     I see there is a new key binding `C-h d' for `apropos-documentation'.
>     Wouldn't it be better to reserve `C-h d' for something more useful
>     and to bind `apropos-documentation' to a new key prefix `C-h a'?
>
> Things are complex enough already, so I don't want to go that way.

Other useful apropos command are still unbound, so allocating a prefix
key for them would be good.  If not existing `C-h a', then maybe another
prefix key like `C-h A' or `C-h C-a'.

As for `C-h d', it might be useful to reserve it for other Help keys.
For example, I think that `describe-char' which is currently on `C-u
C-x =' is a typical Help command like other `describe-...' commands
(`describe-key', `describe-function', `describe-mode', ...).  I think
it needs a key binding on the `C-h' keymap and also to be mentioned in
`help-for-help-internal' and in the Help menu.

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

Re: new apropos feature in Emacs-22

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> As for `C-h d', it might be useful to reserve it for other Help keys.

IMO, apropos-documentation is often more useful than apropos-command
currently on C-h a, and for a novice user, it makes little sense to
restrict the search to just the command name.

Perhaps we could put apropos-documenation on C-h a.

That said, I also think that it would be very useful if C-h C-a was a
prefix for the various apropos commands.

> For example, I think that `describe-char' which is currently on `C-u
> C-x =' is a typical Help command like other `describe-...' commands
> (`describe-key', `describe-function', `describe-mode', ...).  I think
> it needs a key binding on the `C-h' keymap and also to be mentioned in
> `help-for-help-internal' and in the Help menu.

We have both C-h k and C-h c to describe key bindings (full and short
story), so perhaps the C-h c binding could be used for "describe char
at point".

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk