Re: doc elisp intro cross reference fixes

[Juri Linkov]

Per Abrahamsen <address@hidden> writes:
> 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

I just grepped the emacs/lisp/ file tree and results clearly
demonstrate that programmers use * quite randomly.  There are even
24 constants (defconst) and 33 faces (defface) with * in their docstrings!
And most defvars with * undoubtedly should be changed to defcustom.
All this indicate that * for its current purpose is a useless feature.

I want to note also that currently there are many defvar variables
that are intended for customization but have no * in their docstrings.
Their values are either too complicated or by some other reasons they
are not suited for interactive modification and are intended for change
from Lisp programs (mostly in .emacs).  There should be some way
to distinguish them from internal variables (whose only purpose is
to communicate global values between functions and some other purely
internal purpose).  I suppose that there is such implicit convention
already exists that internal variables should have no docstrings.
Is it true?

-- 
http://www.jurta.org/emacs/