RE: Lisp mode doc, and Lisp indentation props

[Drew Adams <drew.adams@oracle.com>]

> > I don't know the proper way to achieve this.
> 
> There is absolutely no magic behind this; just call `put' (and
> `get') on the symbol.  The `declare' specification is just a
> convenient way to set the property in the function definition.

I think that there _is_ something missing from the doc, which might
help a bit in this case.  I agree that this kind of thing is not so
easy to discover.  You really have to find it in the code and see
how it is used.

This is the original request/question:

> The specific information I'm after is about those little properties
> on symbols that make some forms indent specially.

There are a few places in Emacs Lisp where some programming takes place
by setting and getting properties on symbols.  This just involves a
function of two symbols, one of which is used as a property of the other.
The function is `get'.  Since other code can change the property value
dynamically, this, like dynamically scoped variables, is one way for some
code to manipulate or otherwise affect other code.  It is an old technique.

Some places where this technique is used include the following:

* Customize - Things like the standard, customized, and set-but-not-saved
  value of a user option are stored on the option symbol (see properties
  `standard-value', `customized-value', and `custom-set').

* Lisp indentation - The case that was asked about.  Properties like
  `common-lisp-indent-function' with values like `(4 4 4 2 &body)'.
  The values are documented in (elisp) `Indenting Macros', but
  nothing there tells you that these are the same values that are
  used by `(declare (indent...))'.

* Byte-compiler - This used to be hinted at, if only indirectly, in
  the Elisp manual, node `Property Lists'.  Before Emacs 24.3 it said:

   Here is an example of a property list, found on the symbol `progn'
   when the compiler is loaded:

     (lisp-indent-function 0 byte-compile byte-compile-progn)

   Here `lisp-indent-function' and `byte-compile' are property names,
   and the other two elements are the corresponding values.

  In the byte-compiler code you will see code like this: 

  (put 'defvar 'byte-hunk-handler 'byte-compile-file-form-defvar)

* Delete-Selection Mode - Property `delete-selection' on a command
  symbol tells `delete-selection-mode' how to treat it, depending on
  its value: `yank' (a yank command - make sure the region to be
  deleted is not yanked), `supersede' (just delete the region),
  `kill' (kill the region), and `t' (delete the region and let
  the command insert a replacement).

Stefan will no doubt chime in to say that this is not a great way
to control or organize code.  For one thing, it cannot be used
for anonymous functions (Emacs Lisp does not allow property lists
for such things).  More importantly, a Lisp symbol is not a Lisp
function; it is just a name (one name) for a function.

This technique is what it is.  IMO, it can be handy, including for
users (for `delete-selection-mode', for instance, though Stefan
will disagree). But it is somewhat primitive and fragile, and not
always easy to discover/notice/analyze/manage.