Subject: use and doc of function symbol properties [was: bug#11381: 23.3; isearch-search-and-update issue?]

From: "Drew Adams" <[email-masked]>
Date: Mon, 28 May 2012 10:34:34 -0700

The question you (Eli) raise is not specific to isearch or to delsel.  The
proper place to discuss it is emacs-devel - especially if you propose to change
things.  So I'm ccing emacs-devel - but bug #11381 should be dropped from the cc
list from now on.

> Actually, I very much dislike this "feature" of putting properties on
> function symbols, or at least the way we use it.  The problem is
> documentation:

We agree that that is the problem.  It is not something else.

> there's no good place visible to users where to
> document the possible values of these properties and their meanings,
> so they are only documented in the code.

Yes.  Documentation could be improved.

But the use of symbol properties, including for function symbols, is nothing
special.  It is similar to using attributes or methods with objects in OOP.
What's sometimes missing perhaps is better documentation/discoverability.

Emacs Lisp symbols are rudimentary objects, and, yes, there is not a lot of
built-in support for discovering or navigating them - how particular properties
are used in various contexts etc.

> This makes maintenance much harder and error-prone than
> it needs to be.

If Emacs maintainers substitute basic Emacs keys/commands here and there then
they need to be aware of `delete-selection-mode' - yes.  The same is true for
other modes that users might use - whether visual lines or whatever.  Changing
one thing can affect another.

The consequence for delsel if that advice is ignored is to risk making it a
no-op in some cases: you can neuter `delete-selection-mode' if you do not pay
attention when you replace commands with new ones (e.g. in some mode).

Wrt the user, and visibility of this information:

In some cases, the user (yes, user) is an Elisp programmer, and s?he would
sometimes need to consult the code anyway, depending on what s?he wants to do.

A user of delsel can be someone who never changes such a property on any
function symbol (most users), or it can be someone who does.  For the latter, it
would probably not be necessary to consult the delsel code if the documentation
included some information that is currently only in the delsel.el Commentary.

[This is not unique to delsel.el, BTW - there are other libraries for which a
programming user must consult the Commentary in order to understand - even when
it might not be necessary to read the code itself.  IOW, there are other cases
where some of the Commentary info might fruitfully be added to the doc.

Library thingatpt.el comes to mind - e.g., the doc strings where we say "See the
file `thingatpt.el' for documentation on how to define a symbol as a valid
THING."  That's almost as long as the info in the Commentary.]

Typically, someone minimally familiar with using delsel as a programmer can
easily answer a question from a user about what's happening or how to change the
behavior.  This info could be added to the `delete-selection-mode' doc string.
The doc could include info about programming/customizing the behavior.  That
info is not a big deal IMO, either to present or to understand.

Some libraries have whole Info manuals that delve into such
programming/customization aspects.  Library delsel.el is very simple, so that
info could just be added to the doc string for the mode.  The entire Commentary
text that explains it is only a few lines long (labeled "Interface"), and that
is all that is needed, I think.

> Look at delsel.el, for one such example.  The various uses of the
> related properties, scattered through half a dozen other Lisp
> packages, are completely obfuscated, and the only place you can really
> understand what these properties mean is by looking at the code in
> delsel.el that handles them, because even the commentary in delsel.el
> leaves a lot of place for improvement.

Not sure I agree, though it is hard to disagree that the application of
properties to function symbols is scattered.  It is of course the case that the
place to look for understanding delete-selection mode is function
`delete-selection-mode'.  And it is true that today that means looking also at
the delsel.el Commentary.  Moving that info to the doc string would help.

Can you be more specific about what is missing from the Commentary in delsel.el?
It seems to me that how delsel works and how to customize the behavior is pretty
well explained there, if a bit succinctly.  What else would you like to see
documented in this regard?

> I say, either we start documenting these properties in the doc strings
> and in the manual, or we should deprecate and discourage the practice
> of using them.

OK for the former.  I disagree with the latter.  Let's not throw out the baby
with the bathwater.

I really don't think this is a big deal.  I've seen a few user questions about
delsel behavior in help-gnu-emacs over the years, and IIRC all of them had an
obvious explanation to someone familiar with the behavior of delsel (which is
quite simple).  Putting the info about that behavior into the doc string would
be helpful - and sufficient, I think.

But of course that won't stop a few "end" users from having the occasional
question because some library they picked up effectively customizes delsel
behavior without saying so.

A typical question comes from someone who already uses delsel (and who is used
to using it), who then picks up a library that changes some key bindings,
effectively replacing some commands that are handled by delsel with some
commands that are not.

This case is not a big deal.  Such a user can tell right away that something has
changed the delsel behavior, and a quick question to help-gnu-emacs - or a quick
check of the new doc string - would likely turn on the light.

But a user who has never used delsel before, and who already uses some library
that substitutes keys/commands so that delsel becomes a no-op for them, will
perhaps not understand why delsel does not seem to behave as advertised.  IOW,
trying to understand the expected vanilla behavior of delsel (having never used
it), and trying to understand a modified behavior at the same time, might be
more difficult.

But even that user, if s?he consults the new doc string, would have a good
chance of understanding the situation.

Attaching properties to Lisp function symbols in order to affect behavior is as
old as Lisp symbols themselves.  Please do not try to discourage this practice.
But it is fine to try to improve the documentation or discoverability.

[Belongs in a separate thread, at another time, but if `delete-selection-mode'
were the default (yes) then: (a) users new to Emacs would find behavior much
closer to what they are used to, and (b) Emacs developers (including 3rd-party)
would be more conscious of delsel, so would likely DTRT wrt it more often.]

(Just one opinion.)