* `C-h v' may offer too many symbols
@ 2011-03-10 18:52 Ted Zlatanov
2011-03-10 19:39 ` Juanma Barranquero
0 siblings, 1 reply; 9+ messages in thread
From: Ted Zlatanov @ 2011-03-10 18:52 UTC (permalink / raw
To: emacs-devel
`C-h v' offers completion candidates like :AFTER and :border which are
not documented and self-quoting. Is that a good idea? They don't seem
useful to me. Maybe at least self-quoting symbols without a docstring
should be excluded.
Ted
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: `C-h v' may offer too many symbols
2011-03-10 18:52 `C-h v' may offer too many symbols Ted Zlatanov
@ 2011-03-10 19:39 ` Juanma Barranquero
2011-03-11 2:10 ` Stefan Monnier
0 siblings, 1 reply; 9+ messages in thread
From: Juanma Barranquero @ 2011-03-10 19:39 UTC (permalink / raw
To: Ted Zlatanov; +Cc: emacs-devel
2011/3/10 Ted Zlatanov <tzz@lifelogs.com>:
> `C-h v' offers completion candidates like :AFTER and :border which are
> not documented and self-quoting. Is that a good idea? They don't seem
> useful to me. Maybe at least self-quoting symbols without a docstring
> should be excluded.
Yes, it is a bit silly complete keywords, which are not variables by definition.
I'm going to install this trivial fix.
Juanma
2011-03-10 Juanma Barranquero <lekktu@gmail.com>
* help-fns.el (describe-variable): Don't complete keywords.
Suggested by Teodor Zlatanov <tzz@lifelogs.com>.
=== modified file 'lisp/help-fns.el'
--- lisp/help-fns.el 2011-02-24 08:26:25 +0000
+++ lisp/help-fns.el 2011-03-10 19:32:46 +0000
@@ -593,8 +593,9 @@
"Describe variable: ")
obarray
'(lambda (vv)
- (or (boundp vv)
- (get vv 'variable-documentation)))
+ (unless (keywordp vv)
+ (or (boundp vv)
+ (get vv 'variable-documentation))))
t nil nil
(if (symbolp v) (symbol-name v))))
(list (if (equal val "")
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: `C-h v' may offer too many symbols
2011-03-10 19:39 ` Juanma Barranquero
@ 2011-03-11 2:10 ` Stefan Monnier
2011-03-11 2:27 ` Juanma Barranquero
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
0 siblings, 2 replies; 9+ messages in thread
From: Stefan Monnier @ 2011-03-11 2:10 UTC (permalink / raw
To: Juanma Barranquero; +Cc: Ted Zlatanov, emacs-devel
> Yes, it is a bit silly complete keywords, which are not variables by
> definition. I'm going to install this trivial fix.
Sounds good. FWIW, here's a patch I have pending for the lexbind branch
(where special-variable-p is t only for vars that have been defvar'd
or defconst'd).
Stefan
=== modified file 'lisp/help-fns.el'
--- lisp/help-fns.el 2011-03-06 21:22:16 +0000
+++ lisp/help-fns.el 2011-03-11 02:07:37 +0000
@@ -618,8 +618,8 @@
"Describe variable (default %s): " v)
"Describe variable: ")
obarray
- '(lambda (vv)
- (or (boundp vv)
+ (lambda (vv)
+ (or (special-variable-p vv)
(get vv 'variable-documentation)))
t nil nil
(if (symbolp v) (symbol-name v))))
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: `C-h v' may offer too many symbols
2011-03-11 2:10 ` Stefan Monnier
@ 2011-03-11 2:27 ` Juanma Barranquero
2011-03-11 4:29 ` Stefan Monnier
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
1 sibling, 1 reply; 9+ messages in thread
From: Juanma Barranquero @ 2011-03-11 2:27 UTC (permalink / raw
To: Stefan Monnier; +Cc: Ted Zlatanov, emacs-devel
On Fri, Mar 11, 2011 at 03:10, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> Sounds good.
I've installed it.
> FWIW, here's a patch I have pending for the lexbind branch
> (where special-variable-p is t only for vars that have been defvar'd
> or defconst'd).
It makes sense, in a lexical world. However, currently you can do
(defconst :mykeyword :mykeyword)
and even if you add a docstring to that, I'm not sure it is sensible
to show it as a completion of describe-variable...
Juanma
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: `C-h v' may offer too many symbols
2011-03-11 2:27 ` Juanma Barranquero
@ 2011-03-11 4:29 ` Stefan Monnier
0 siblings, 0 replies; 9+ messages in thread
From: Stefan Monnier @ 2011-03-11 4:29 UTC (permalink / raw
To: Juanma Barranquero; +Cc: Ted Zlatanov, emacs-devel
> It makes sense, in a lexical world. However, currently you can do
> (defconst :mykeyword :mykeyword)
> and even if you add a docstring to that, I'm not sure it is sensible
> to show it as a completion of describe-variable...
Actually, if it has a docstring, it definitely makes sense. And if it
doesn't, then it's not that much of a problem to include those rare
cases in the completion.
Stefan
^ permalink raw reply [flat|nested] 9+ messages in thread
* public APIs and private ones (Re: `C-h v' may offer too many symbols)
2011-03-11 2:10 ` Stefan Monnier
2011-03-11 2:27 ` Juanma Barranquero
@ 2011-03-11 4:31 ` Kenichi Handa
2011-03-11 5:41 ` public APIs and private ones (Re: `C-h v' may offer too manysymbols) Drew Adams
` (2 more replies)
1 sibling, 3 replies; 9+ messages in thread
From: Kenichi Handa @ 2011-03-11 4:31 UTC (permalink / raw
To: Stefan Monnier; +Cc: lekktu, tzz, emacs-devel
In article <jwv7hc6e7dg.fsf-monnier+emacs@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca> writes:
> > Yes, it is a bit silly complete keywords, which are not variables by
> > definition. I'm going to install this trivial fix.
> Sounds good. FWIW, here's a patch I have pending for the lexbind branch
> (where special-variable-p is t only for vars that have been defvar'd
> or defconst'd).
This is a little bit different topic, but shouldn't we have
a way to distinguish functions/macros/variables for public
API from those for internal (i.e. only within a specific
package) use only. For instance, as basic-save-buffer-1 is
just a helper function of basic-save-buffer, there's no need
to list it by C-h f TAB.
In addition, and this is more important, such a
distinguishment makes it easier to maintain a package. For
instance, when I improve the MIME handling of rmailmm.el,
the most difficult thing was to keep backward compatibility
of existing functions. It seems that most of them are
intended for internal use only. If that is clear, I could
have renamed or changed the behaviour of some of them.
---
Kenichi Handa
handa@m17n.org
^ permalink raw reply [flat|nested] 9+ messages in thread
* RE: public APIs and private ones (Re: `C-h v' may offer too manysymbols)
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
@ 2011-03-11 5:41 ` Drew Adams
2011-03-11 19:08 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Ted Zlatanov
2011-03-11 20:28 ` Stefan Monnier
2 siblings, 0 replies; 9+ messages in thread
From: Drew Adams @ 2011-03-11 5:41 UTC (permalink / raw
To: 'Kenichi Handa', 'Stefan Monnier'
Cc: lekktu, tzz, emacs-devel
> shouldn't we have a way to distinguish functions/macros/
> variables for public API from those for internal (i.e. only
> within a specific package) use only.
I have no problem with that in principle. From my point of view, "internal"
here would be something definable (e.g. declarable) by the coder.
IOW, it has no intrinsic meaning; it can only be defined by someone, in some
context, with some purpose. Its only value is relative to those things.
It expresses the coder's intention that most users will probably not want or
need to use the stuff designated "internal" most of the time. Nothing more than
that.
> For instance, as basic-save-buffer-1 is just a helper function
> of basic-save-buffer, there's no need to list it by C-h f TAB.
I sure disagree here. "No need" isn't something the coder can decide. "You
probably aren't very interested in this" is different from "you don't need
this".
Personally, I want `C-h f' to include all functions as candidates. This is
`describe-function', not `describe-user-function' or some such.
I have no problem with someone adding a new command to do what you describe. I
would prefer that it not be bound to `C-h f', but that's another matter (and I
certainly wouldn't go to the barricades about it).
Or a prefix arg might be acceptable for distinguishing the two. Then we would
be arguing only over the default behavior (behavior with no prefix arg).
But my personal preference, used in my own version of `C-h f', is for a prefix
arg to mean use only _commands_ as completion candidates. Perhaps a distinction
via different prefix-arg values would be appropriate: all functions, only
commands, only "external" functions.
> In addition, and this is more important, such a
> distinguishment makes it easier to maintain a package. For
> instance, when I improve the MIME handling of rmailmm.el,
> the most difficult thing was to keep backward compatibility
> of existing functions. It seems that most of them are
> intended for internal use only. If that is clear, I could
> have renamed or changed the behaviour of some of them.
Again, "internal" means nothing (especially) for a language like Lisp
(especially a Lisp that has no packages/modules), other than as an expression of
a coder's intention. That's not nothing, of course. And there's nothing wrong
with expressing such an intention - it can be helpful. But "internal" can (and
should) never be more than that: expression of intended use by most users in
most situations.
People are users at different levels at different times or in different
contexts. Something is language in one context and metalanguage in another
context. Same with internal and external. One person's or one context's
internal is another person's or another context's external.
That does not mean that such terms are meaningless or useless; it just means
that they are far from absolute. Sooner or later someone (and not only the
maintainer) will want to use "internal" functions for something - possibly
something "external" or unintended originally. Code manipulation (by code) is
just one example.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: public APIs and private ones (Re: `C-h v' may offer too many symbols)
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
2011-03-11 5:41 ` public APIs and private ones (Re: `C-h v' may offer too manysymbols) Drew Adams
@ 2011-03-11 19:08 ` Ted Zlatanov
2011-03-11 20:28 ` Stefan Monnier
2 siblings, 0 replies; 9+ messages in thread
From: Ted Zlatanov @ 2011-03-11 19:08 UTC (permalink / raw
To: emacs-devel
On Fri, 11 Mar 2011 13:31:30 +0900 Kenichi Handa <handa@m17n.org> wrote:
KH> In article <jwv7hc6e7dg.fsf-monnier+emacs@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> > Yes, it is a bit silly complete keywords, which are not variables by
>> > definition. I'm going to install this trivial fix.
>> Sounds good. FWIW, here's a patch I have pending for the lexbind branch
>> (where special-variable-p is t only for vars that have been defvar'd
>> or defconst'd).
KH> This is a little bit different topic, but shouldn't we have
KH> a way to distinguish functions/macros/variables for public
KH> API from those for internal (i.e. only within a specific
KH> package) use only. For instance, as basic-save-buffer-1 is
KH> just a helper function of basic-save-buffer, there's no need
KH> to list it by C-h f TAB.
KH> In addition, and this is more important, such a
KH> distinguishment makes it easier to maintain a package. For
KH> instance, when I improve the MIME handling of rmailmm.el,
KH> the most difficult thing was to keep backward compatibility
KH> of existing functions. It seems that most of them are
KH> intended for internal use only. If that is clear, I could
KH> have renamed or changed the behaviour of some of them.
I think (or autoloaded-p called-interactively-p) functions are
implicitly intended for public consumption so maybe that's the criteria
you're looking for (I'm inventing some of these predicate names).
But maybe it also makes sense to add filtering by `autoloaded-p' and
`called-interactively-p' (which is currently available with M-x TAB) and
`has-docstring-p' to `C-h f' somehow, either by making parallel commands
or by adding filtering inside it. So then public-API-p can be part of
that system, if it's different from (or autoloaded-p called-interactively-p).
Ted
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: public APIs and private ones (Re: `C-h v' may offer too many symbols)
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
2011-03-11 5:41 ` public APIs and private ones (Re: `C-h v' may offer too manysymbols) Drew Adams
2011-03-11 19:08 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Ted Zlatanov
@ 2011-03-11 20:28 ` Stefan Monnier
2 siblings, 0 replies; 9+ messages in thread
From: Stefan Monnier @ 2011-03-11 20:28 UTC (permalink / raw
To: Kenichi Handa; +Cc: lekktu, tzz, emacs-devel
> This is a little bit different topic, but shouldn't we have
> a way to distinguish functions/macros/variables for public
> API from those for internal (i.e. only within a specific
> package) use only.
I try to follow the convention that I use "<package>--" for
functions/macros/variables internal to <package>. It's just
a convention and it's currently very little used, but I encourage people
to use it more systematically.
We also use the "internal-" prefix for things that are "internal to
Emacs core" (typically functions exported from C meant only for use in
subr.el, tho I also used it in lexbind for operations that only appear
in some intermediate form of the code manipulated by the compiler).
> For instance, as basic-save-buffer-1 is just a helper function of
> basic-save-buffer, there's no need to list it by C-h f TAB.
I'm not completely sure if it would be a good idea: I also use C-h f to
find such internal functions.
> In addition, and this is more important, such a distinguishment makes
> it easier to maintain a package.
Fully agreed. It also makes it easier for users of the package to
figure out what are the intended entry points.
Stefan
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2011-03-11 20:28 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-03-10 18:52 `C-h v' may offer too many symbols Ted Zlatanov
2011-03-10 19:39 ` Juanma Barranquero
2011-03-11 2:10 ` Stefan Monnier
2011-03-11 2:27 ` Juanma Barranquero
2011-03-11 4:29 ` Stefan Monnier
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
2011-03-11 5:41 ` public APIs and private ones (Re: `C-h v' may offer too manysymbols) Drew Adams
2011-03-11 19:08 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Ted Zlatanov
2011-03-11 20:28 ` Stefan Monnier
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).