GNU bug report logs -
#56870
company-dabbrev variable documentation
Previous Next
Reported by: uzibalqa <uzibalqa <at> proton.me>
Date: Mon, 1 Aug 2022 13:10:02 UTC
Severity: normal
Tags: notabug
Done: Lars Ingebrigtsen <larsi <at> gnus.org>
Bug is archived. No further changes may be made.
Full log
Message #66 received at 56870 <at> debbugs.gnu.org (full text, mbox):
Aug 5, 2022, 11:09 by eliz <at> gnu.org:
>> From: YE <yet <at> ego.team>
>> Cc: yet <at> ego.team, matt <at> rfc20.org, uzibalqa <at> proton.me, larsi <at> gnus.org,
>> 56870 <at> debbugs.gnu.org
>> Date: Fri, 05 Aug 2022 12:10:33 +0300
>>
>> Eli Zaretskii <eliz <at> 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.
>
This bug report was last modified 2 years and 349 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.