bug#56870: company-dabbrev variable documentation

[carlmarcos]

Aug 3, 2022, 18:41 by matt@rfc20.org:

> 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.
>

I completely disagree.  The experience with maintainers has shown how 
unreceptive
they often get towards improvements like this.  Lars thought there isn't 
anything to fix
in Emacs and decided to close this bug report.



> 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...
>