bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable documentation

[Eli Zaretskii]

> From: YE <yet@ego.team>
> Cc: yet@ego.team, matt@rfc20.org, uzibalqa@proton.me, larsi@gnus.org,
>       56870@debbugs.gnu.org
> Date: Fri, 05 Aug 2022 12:10:33 +0300
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Thanks.  However, this basically adds to the Emacs manual stuff whose
> > place is in the ELisp manual.
> 
> This patch clarifies _existing_ node of the Emacs manual:
> 1. Adds indexes.
> 2. Adds links to the ELisp manual for further reading.
> 3. Clarifies how to use _wide-spread_ symbols (extensively used by newbies).
> 
> Which part _exactly_ you don't find suitable for the Emacs manual?

All of it.  You explain some basics of Emacs Lisp, which any user who
is serious about customizing his/her Emacs should already know about,
by reading the relevant parts of the ELisp manual.

It goes without saying that this node of the Emacs manual is
intentionally incomplete, but making it complete would mean we'd need
to repeat a significant portion of text that is already in the ELisp
manual, because the missing bits are about Emacs Lisp, not about
anything special to the init files.

> Don't Symbols deserve the same attention as Numbers, Strings,
> Characters described extensively in `(emacs) Init Syntax'?

No, I don't think so.  And this is a slippery slope anyway, because
there's more about Lisp objects than just telling what you suggest to
tell.

> Maybe, according to your point of view, this node should be removed from
> the Emacs manual altogether, (linking to the ELisp manual)?

That'd be too drastic, IMO.  Simple customizations don't need detailed
knowledge of Lisp, and the node attempts to strike a balance between
being useful to beginners and including too much of ELisp.

> Or should I submit a new bug report with the vague: `(emacs) Init File'
> is confusing and isn't instructive enough for the newbies?

If you explain clearly enough what is confusing in that node, we could
try making it less confusing and more instructive, yes.

> > So I'm not sure we should start on this
> > slippery slope.
> 
> We start on the slippery slope when the reported issues aren't resolved.

That's a different slippery slope.

And I disagree that issues aren't resolved.  You might think they
aren't, because your opinions aren't accepted, but we don't promise we
will accept any opinion without considering its advantages and
disadvantages.

> > Users who need to write complex Lisp in their init
> > files need to read the ELisp manual anyway.
> 
> What part of the patch touches the "complex Lisp"?

This one, for example:

  +@item Other Lisp symbols:
  +@cindex Lisp symbol syntax
  +@cindex symbol syntax
  +Write a single-quote (@code{'}) followed by the symbol name
  +(@pxref{Symbols,,, elisp, The Emacs Lisp Reference Manual}).  Note
  +that documentation strings refer to symbols by their names only,
  +without the single-quote (@pxref{Documentation Tips,,, elisp, The
  +Emacs Lisp Reference Manual}).

Why does this text have to talk about doc strings, and what does it
have to do with the syntax of the init file?  And the node to which
you refer is a large and complex node, which is too much for simple
customizations that Init Syntax intends to cover.