From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable documentation Date: Fri, 05 Aug 2022 14:09:17 +0300 Message-ID: <83a68j0wwy.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="21563"; mail-complaints-to="usenet@ciao.gmane.io" Cc: matt@rfc20.org, larsi@gnus.org, uzibalqa@proton.me, 56870@debbugs.gnu.org To: YE Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Aug 05 13:14:13 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1oJvHR-0005Qa-0o for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 05 Aug 2022 13:14:13 +0200 Original-Received: from localhost ([::1]:46530 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oJvHP-0001vq-RT for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 05 Aug 2022 07:14:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:35218) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oJvDO-00075s-5n for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 07:10:05 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38387) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oJvDN-0008FK-Td for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 07:10:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oJvDN-00022h-LP for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 07:10:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 05 Aug 2022 11:10:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56870 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: notabug Original-Received: via spool by 56870-submit@debbugs.gnu.org id=B56870.16596977737813 (code B ref 56870); Fri, 05 Aug 2022 11:10:01 +0000 Original-Received: (at 56870) by debbugs.gnu.org; 5 Aug 2022 11:09:33 +0000 Original-Received: from localhost ([127.0.0.1]:56369 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJvCv-00021w-3z for submit@debbugs.gnu.org; Fri, 05 Aug 2022 07:09:33 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:50472) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJvCp-00021g-OO for 56870@debbugs.gnu.org; Fri, 05 Aug 2022 07:09:31 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:50064) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oJvCj-0008BT-5e; Fri, 05 Aug 2022 07:09:21 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=jaPt0wginXVjdsOeTsCebv20ZtAyEdbc/7nK6kz64g0=; b=mSSagcX/Hqdq EyO0E+D0wpSZiT9k49xgv2lJPRXfuS/+MMvAtjTRol1A7V1lDsENDbQlTHbOT+DFjMm5nNQKVs1NC LfuhJmaToLNhbQ7bcStg6a70cAfis6PK5/PGheF0oQoN5Lz5VDJce/3CTuY7fETATKCOPchr4Cmzt Gz9cTifFzzF/j2te7vUaZbIMmwAnQYzWy6QoFTSLn5i+QuoSotOdE9b2TyuoJfxHMU8XqZjCOIbv8 dLlpS43Es1U1g70MaxXXQN79IG/51seSV8udd0k18ALwvvMrz3n3bFrOxSda8Zv2cO1M2niB2A2pH iR3kiXFey05IvPA47z6VrQ==; Original-Received: from [87.69.77.57] (port=2371 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oJvCi-0004fg-Ii; Fri, 05 Aug 2022 07:09:20 -0400 In-Reply-To: (message from YE on Fri, 05 Aug 2022 12:10:33 +0300) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:238860 Archived-At: > From: YE > 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 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.