Re: doc elisp intro cross reference fixes

[Per Abrahamsen]

Stefan Monnier <address@hidden> writes:

> Could someone explain to me the subtle differences between:
> - defvar with a * in the docstring.
> - defcustom with no * in the docstring.
> - defcustom with a * in the docstring.

The way I have treated them are:

If the variable has a value that the user is likely to want to save
between sessions, use defcustom.

If the variable has a value that the user is likely to want to change
multiple times in a single session during normal use, use *.

Something like "foo-mime-type-alist" should be defcustom without *, as
it is something pretty complex you'd want to define once, and then use
for ever after.  You'd change it only to get it right, not as part of
normal use.  But something like case-fold-search would be a
prototypical example of an option the user may want to change several
times in a session.

On the other hand, it should also be clear that

1) programmers don't understand the distinction

I spend a lot of time fixing removing or adding "*" from Gnus options,
most other developers seemed to either add it always or never.  Even
to the degree of adding or removing * from old code so everything was
the same.

2) programmers can't judge when an option is something users would
   want to change as part of normal use

3) having too many choices for set-variable is much less of a
   problem than having too few.
   
so I think it would be best to retire the "*" convention entirely.
Actually enforcing it would be too much work for too little gain.