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: company-dabbrev variable documentation Date: Wed, 3 Aug 2022 20:50:44 +0200 (CEST) Message-ID: References: <878ro74pz5.fsf@rfc20.org> <87y1w7ymiu.fsf@gnus.org> <87sfmd2mqk.fsf@rfc20.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="16143"; mail-complaints-to="usenet@ciao.gmane.io" Cc: YE , uzibalqa , Lars Ingebrigtsen , 56870@debbugs.gnu.org To: Matt Armstrong Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Aug 03 20:51:22 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 1oJJSj-00042S-VP for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 03 Aug 2022 20:51:22 +0200 Original-Received: from localhost ([::1]:49226 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oJJSj-0007HM-2O for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 03 Aug 2022 14:51:21 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:45396) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oJJST-0007H5-Dd for bug-gnu-emacs@gnu.org; Wed, 03 Aug 2022 14:51:05 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60218) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oJJSQ-0007kQ-BJ for bug-gnu-emacs@gnu.org; Wed, 03 Aug 2022 14:51:05 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oJJSQ-0002Of-6i for bug-gnu-emacs@gnu.org; Wed, 03 Aug 2022 14:51: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: Wed, 03 Aug 2022 18:51: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.16595526549199 (code B ref 56870); Wed, 03 Aug 2022 18:51:02 +0000 Original-Received: (at 56870) by debbugs.gnu.org; 3 Aug 2022 18:50:54 +0000 Original-Received: from localhost ([127.0.0.1]:49967 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJJSH-0002OI-Vt for submit@debbugs.gnu.org; Wed, 03 Aug 2022 14:50:54 -0400 Original-Received: from w1.tutanota.de ([81.3.6.162]:36600) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJJSF-0002O3-0P for 56870@debbugs.gnu.org; Wed, 03 Aug 2022 14:50:52 -0400 Original-Received: from w3.tutanota.de (unknown [192.168.1.164]) by w1.tutanota.de (Postfix) with ESMTP id E6FBBFBF96C; Wed, 3 Aug 2022 18:50:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1659552644; 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=Ibi0Lg+9737UuCHPRVP5yUp24U0ZAs5oIHniFamvbf4=; b=ndFLc9ZbsqdvDx6hxAkv1TUQB6xsdQJzgBBUOyFjlpHYcvrwAPvRCbsI9lIxiejR vwyor4OxA6G2/8h7+IMGJLgB+nizpkiVn39rI5Xh0temEHw9q8Sl1pDYSaxjLcqf61X u/oZbZdQeL0aRi0954Y0PJyhZE8OwdS8zhaI4wN97IlYaaZCW6QxgrppgU4eXHi3oBD 3itWSKmQWXiefNSqvj63ob6BZIqkZULmJMrDTdsVM7KJoEiL8gmIn6eNcoRUEMCz27j bT0nA6ZGBAJX/hLANGbQlx3qMeIA5+uttg8nFOpdUY1IhoSYt9dQHIoe1s2cif75EhK pLW74v6ePg== In-Reply-To: <87sfmd2mqk.fsf@rfc20.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:238646 Archived-At: Aug 3, 2022, 18:41 by matt@rfc20.org: > YE writes: > >>> So I don't think there's anything to fix in Emacs here -- we sometimes >>> say "the symbol `all'" if there's an unusual amount of possible >>> confusion present -- and I'm therefore closing this bug report. >>> >> >> I'd still suggest considering documentation improvement in this regard. >> Probably because I had the same confusion when started with Emacs, even >> after having read the whole manual. >> >> [Well, the info node `(elisp) Documentation Tips)' clarifies how to >> document symbols : >> >>> When a documentation string refers to a Lisp symbol, write it as it >>> would be printed (which usually means in lower case), surrounding >>> it with curved single quotes (=E2=80=98..=E2=80=99) >>> >> But Emacs beginner users don't seem to be the target auditory of this >> page. And it still won't -- naturally -- explain how to _use_ such >> symbols.] >> >> One such possible place to adjust is the info node `(emacs) Examining'. >> Maybe replace 'fill-column' example with the one that accepts a >> documented symbol (f.i. 'default-justification', 'diff-refine', >> 'tab-always-complete') and use the symbol in the code below? >> >> Another: info node `(emacs) Init Syntax' could probably state more >> explicitly how to deal with the symbols. >> >> Or mention symbols documentation/usage at the end of the info node >> `(emacs) Variables', after the line "check the variable=E2=80=99s docume= ntation >> string to see what kind of value it expects". >> >> WDYT? >> > > People learn in different ways, so perhaps we should do all of those > things? > > I think improving the various manuals is always a good idea. The hard > part is finding and encouraging people to contribute the work! :-) I > think the maintainers are quite receptive to improvements like this. > I completely disagree.=C2=A0 The experience with maintainers has shown how = unreceptive they often get towards improvements like this.=C2=A0 Lars thought there isn= 't anything to fix in Emacs and decided to close this bug report. > Another thing to keep in mind: most of the common languages these days > do not have symbols, so the very concept might be unfamiliar to new > users. > > Another place that might improve is "An Introduction to Programming in > Emacs Lisp" > (https://www.gnu.org/software/emacs/manual/html_mono/eintr.html). In my > opinion, it could do a better job explaining what a symbol is, how to > express them in code, quote them, how they are often used as "magic > values", etc. It talks about them in context with "atoms" but that is > fairly esoteric. > > FWIW I find that the classic book "A Gentle Introduction to Symbolic > Computaton" does a great job explaining what a symbol is. It introduces > the idea of a symbol as the second fundamental concept of the language, > in the first chapter, right after functions. > > https://www.cs.cmu.edu/~dst/LispBook/book.pdf > > Turning back to Emacs' help system, I wonder if it could be made more > clear that all of these quoted "things" in help text are intended to be > lisp symbols. Wild idea: always turn them into links. An arbitrary > `foo' that isn't a function or variable would link to a synthetic help > page explaining that it is a symbol, how it might appear in lisp code, > link to an appropriate manual, etc. Perhaps this would be too noisy... >