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

[carlmarcos]

Aug 5, 2022, 11:09 by eliz@gnu.org:

>> 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.
>
The docstring should mention that variable settings use symbol arguments.  


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