bug#8422: 24.0.50; doc of `apropos-internal'

bug#8422: 24.0.50; doc of `apropos-internal'

[Drew Adams]

Please add to the doc string some info about what the context is
when/where PREDICATE is invoked.  Suppose, for instance, you wanted to
use a PREDICATE such as this:
 
(lambda (c)
  (and (commandp c)
       (where-is-internal c overriding-local-map 'non-ascii))
 
The behavior of the PREDICATE depends on which buffer is current when it
is invoked.  Can we assume that the buffer is the same one as when
`apropos-internal' was invoked?  Likewise wrt the selected window.
 
To find this info, users currently need to look at the C source code.

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-04-04 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8422: 24.0.50; doc of `apropos-internal'

[Lars Magne Ingebrigtsen]

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

> Please add to the doc string some info about what the context is
> when/where PREDICATE is invoked.  Suppose, for instance, you wanted to
> use a PREDICATE such as this:
>
> (lambda (c)
>   (and (commandp c)
>        (where-is-internal c overriding-local-map 'non-ascii))
>
> The behavior of the PREDICATE depends on which buffer is current when it
> is invoked.  Can we assume that the buffer is the same one as when
> `apropos-internal' was invoked?  Likewise wrt the selected window.
>
> To find this info, users currently need to look at the C source code.

That sounds reasonable, but I'm not quite sure that's how the predicate
is meant to be used.  That is, I'm not sure it's an implementation
detail what buffer the predicate is called from, or whether it's
supposed to be that way.

Anybody know?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8422: 24.0.50; doc of `apropos-internal'

[Lars Ingebrigtsen]

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

> Please add to the doc string some info about what the context is
> when/where PREDICATE is invoked.  Suppose, for instance, you wanted to
> use a PREDICATE such as this:
>
> (lambda (c)
>   (and (commandp c)
>        (where-is-internal c overriding-local-map 'non-ascii))
>
> The behavior of the PREDICATE depends on which buffer is current when it
> is invoked.  Can we assume that the buffer is the same one as when
> `apropos-internal' was invoked?  Likewise wrt the selected window.
>
> To find this info, users currently need to look at the C source code.

Uhm...  no.  As far as I can see, apropos-internal does nothing weird
like changing buffers or windows?  So it would be rather odd to document
that it doesn't do <one weird thing>.  Other mapping functions like
`sort' certainly doesn't.  Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#8422: 24.0.50; doc of `apropos-internal'

[Drew Adams]

> Uhm...  no.  As far as I can see, apropos-internal does nothing weird
> like changing buffers or windows?  So it would be rather odd to document
> that it doesn't do <one weird thing>.  Other mapping functions like
> `sort' certainly doesn't.  Closing.

That contradicts what a certain Lars Ingebrigtsen wrote in
this bug thread in 2011:

  > To find this info, users currently need to look at the C source code.

  That sounds reasonable, but I'm not quite sure that's how the predicate
  is meant to be used.  That is, I'm not sure it's an implementation
  detail what buffer the predicate is called from, or whether it's
  supposed to be that way.

  Anybody know?

Of course, we all have the right to change our minds. ;-)