`C-h v' may offer too many symbols

`C-h v' may offer too many symbols

[Ted Zlatanov]

`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

Re: `C-h v' may offer too many symbols

[Juanma Barranquero]

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 "")

Re: `C-h v' may offer too many symbols

[Stefan Monnier]

> 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))))

Re: `C-h v' may offer too many symbols

[Juanma Barranquero]

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

Re: `C-h v' may offer too many symbols

[Stefan Monnier]

> 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

public APIs and private ones (Re: `C-h v' may offer too many symbols)

[Kenichi Handa]

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

RE: public APIs and private ones (Re: `C-h v' may offer too manysymbols)

[Drew Adams]

> 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.

Re: public APIs and private ones (Re: `C-h v' may offer too many symbols)

[Ted Zlatanov]

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

Re: public APIs and private ones (Re: `C-h v' may offer too many symbols)

[Stefan Monnier]

> 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