GNU bug report logs - #56870
company-dabbrev variable documentation

Previous Next

Full log

View this message in rfc822 format

From: YE <yet <at> ego.team>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Matt Armstrong <matt <at> rfc20.org>, uzibalqa <uzibalqa <at> proton.me>, 56870 <at> debbugs.gnu.org
Subject: bug#56870: company-dabbrev variable documentation
Date: Wed, 03 Aug 2022 13:07:02 +0300

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.