bug#56870: company-dabbrev variable documentation

[Matt Armstrong]

YE <yet@ego.team> writes:

>> So I don't think there's anything to fix in Emacs here -- we sometimes
>> say "the symbol `all'" if there's an unusual amount of possible
>> confusion present -- and I'm therefore closing this bug report.
>
> I'd still suggest considering documentation improvement in this regard.
> Probably because I had the same confusion when started with Emacs, even
> after having read the whole manual.
>
> [Well, the info node `(elisp) Documentation Tips)' clarifies how to
> document symbols :
>>  When a documentation string refers to a Lisp symbol, write it as it
>>      would be printed (which usually means in lower case), surrounding
>>      it with curved single quotes (‘..’)
> But Emacs beginner users don't seem to be the target auditory of this
> page. And it still won't -- naturally -- explain how to _use_ such
> symbols.]
>
> One such possible place to adjust is the info node `(emacs) Examining'.
> Maybe replace 'fill-column' example with the one that accepts a
> documented symbol (f.i. 'default-justification', 'diff-refine',
> 'tab-always-complete') and use the symbol in the code below?
>
> Another: info node `(emacs) Init Syntax' could probably state more
> explicitly how to deal with the symbols.
>
> Or mention symbols documentation/usage at the end of the info node
> `(emacs) Variables', after the line "check the variable’s documentation
> string to see what kind of value it expects".
>
> WDYT?

People learn in different ways, so perhaps we should do all of those
things?

I think improving the various manuals is always a good idea.  The hard
part is finding and encouraging people to contribute the work!  :-)  I
think the maintainers are quite receptive to improvements like this.

Another thing to keep in mind: most of the common languages these days
do not have symbols, so the very concept might be unfamiliar to new
users.

Another place that might improve is "An Introduction to Programming in
Emacs Lisp"
(https://www.gnu.org/software/emacs/manual/html_mono/eintr.html).  In my
opinion, it could do a better job explaining what a symbol is, how to
express them in code, quote them, how they are often used as "magic
values", etc.  It talks about them in context with "atoms" but that is
fairly esoteric.

FWIW I find that the classic book "A Gentle Introduction to Symbolic
Computaton" does a great job explaining what a symbol is.  It introduces
the idea of a symbol as the second fundamental concept of the language,
in the first chapter, right after functions.

https://www.cs.cmu.edu/~dst/LispBook/book.pdf

Turning back to Emacs' help system, I wonder if it could be made more
clear that all of these quoted "things" in help text are intended to be
lisp symbols.  Wild idea: always turn them into links.  An arbitrary
`foo' that isn't a function or variable would link to a synthetic help
page explaining that it is a symbol, how it might appear in lisp code,
link to an appropriate manual, etc.  Perhaps this would be too noisy...