From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: carlmarcos--- via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable documentation Date: Fri, 5 Aug 2022 13:36:35 +0200 (CEST) Message-ID: References: <878ro74pz5.fsf@rfc20.org> <87y1w7ymiu.fsf@gnus.org> <87sfmd2mqk.fsf@rfc20.org> <83czdg2c7x.fsf@gnu.org> <83a68j0wwy.fsf@gnu.org> Reply-To: carlmarcos@tutanota.com Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15067"; mail-complaints-to="usenet@ciao.gmane.io" Cc: matt@rfc20.org, YE , uzibalqa@proton.me, larsi@gnus.org, 56870@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Aug 05 13:37:21 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 1oJvdp-0003l0-CU for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 05 Aug 2022 13:37:21 +0200 Original-Received: from localhost ([::1]:43164 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oJvdm-00030T-RQ for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 05 Aug 2022 07:37:18 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:39922) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oJvdY-0002yZ-0B for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 07:37:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38400) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oJvdW-0005QA-IK for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 07:37:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oJvdW-0004qR-85 for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 07:37:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: carlmarcos@tutanota.com Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 05 Aug 2022 11:37:02 +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.165969940318598 (code B ref 56870); Fri, 05 Aug 2022 11:37:02 +0000 Original-Received: (at 56870) by debbugs.gnu.org; 5 Aug 2022 11:36:43 +0000 Original-Received: from localhost ([127.0.0.1]:56382 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJvdD-0004pu-48 for submit@debbugs.gnu.org; Fri, 05 Aug 2022 07:36:43 -0400 Original-Received: from w1.tutanota.de ([81.3.6.162]:47904) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJvdB-0004pd-5r for 56870@debbugs.gnu.org; Fri, 05 Aug 2022 07:36:41 -0400 Original-Received: from w3.tutanota.de (unknown [192.168.1.164]) by w1.tutanota.de (Postfix) with ESMTP id 81A01FBF81D; Fri, 5 Aug 2022 11:36:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1659699395; s=s1; d=tutanota.com; h=From:From:To:To:Subject:Subject:Content-Description:Content-ID:Content-Type:Content-Type:Content-Transfer-Encoding:Content-Transfer-Encoding:Cc:Cc:Date:Date:In-Reply-To:In-Reply-To:MIME-Version:MIME-Version:Message-ID:Message-ID:Reply-To:References:References:Sender; bh=/dAKM5HheUSrnMbADbUenB2iHQx4kFQ9N4JSTJiy9IA=; b=hOn50G1XLMeVE7ziHqy+lKiqpmZlKKXNRKj9jIKZZ7clctDDyFxm9eg79T4EWcLY KWY38Ju3zWeLp2D9y2r7GZapFVrPegJ1+OOcnQ5CGpXlf7RosVl4E6mLjTPCgranKpX yMFaOh5HX7lK68z6dXH4Cfv4Z5QDVB8EsGfZc/7XceqTsJ4n2ILNApiFyo9DmoY+lAr +dXyQaqohnX3HWb5rMdVM5HmIEusnLN5v5dCqHVFmgWVZ1+djn3LfHzGTcCO5YVlAlF Uipf6+3otD5xtRQ7SgTMCV/uE6SVo3l2HJ/1kC0FbPN6CCz2Uqx0oLkF6fu4Lbsq9jU KVHBZ5AquA== In-Reply-To: <83a68j0wwy.fsf@gnu.org> 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:238862 Archived-At: Aug 5, 2022, 11:09 by eliz@gnu.org: >> 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 newbi= es). >> >> 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.= =C2=A0=20 >> 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. >