From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Matt Armstrong Newsgroups: gmane.emacs.bugs Subject: bug#56870: company-dabbrev variable documentation Date: Wed, 03 Aug 2022 11:41:39 -0700 Message-ID: <87sfmd2mqk.fsf@rfc20.org> References: <878ro74pz5.fsf@rfc20.org> <87y1w7ymiu.fsf@gnus.org> 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="12672"; mail-complaints-to="usenet@ciao.gmane.io" Cc: uzibalqa , 56870@debbugs.gnu.org To: YE , Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Aug 03 20:42:25 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 1oJJK3-00036e-Ol for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 03 Aug 2022 20:42:24 +0200 Original-Received: from localhost ([::1]:44722 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oJJK2-0003KP-ID for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 03 Aug 2022 14:42:22 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43708) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oJJJj-0003Dc-90 for bug-gnu-emacs@gnu.org; Wed, 03 Aug 2022 14:42:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60204) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oJJJj-0005eS-0A for bug-gnu-emacs@gnu.org; Wed, 03 Aug 2022 14:42:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oJJJi-00027p-SD for bug-gnu-emacs@gnu.org; Wed, 03 Aug 2022 14:42:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Matt Armstrong Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 03 Aug 2022 18:42: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.16595521168141 (code B ref 56870); Wed, 03 Aug 2022 18:42:02 +0000 Original-Received: (at 56870) by debbugs.gnu.org; 3 Aug 2022 18:41:56 +0000 Original-Received: from localhost ([127.0.0.1]:49951 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJJJc-00027F-8f for submit@debbugs.gnu.org; Wed, 03 Aug 2022 14:41:56 -0400 Original-Received: from relay2-d.mail.gandi.net ([217.70.183.194]:45989) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJJJX-00026x-4N for 56870@debbugs.gnu.org; Wed, 03 Aug 2022 14:41:55 -0400 Original-Received: (Authenticated sender: matt@rfc20.org) by mail.gandi.net (Postfix) with ESMTPSA id 96B4B40005; Wed, 3 Aug 2022 18:41:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=rfc20.org; s=gm1; t=1659552104; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=F+kIMMFofqW++pzVJwezOuRoDTk+D5encyFxVfmRAQ0=; b=Zdw2u6NI5hJ+LKB2JOiPvSOY9Q2+BEUw7quGV6/iLlDuWVkR1jBQsWUMh5g2TQb0GL/ef9 1zi9OcABBQJ72Pq2NUXpnviVkRRAjRbHOC1Tzf6a8BDnE2Qg4xnZGPmDIz2QLCCanRRqbO 1RUguSKyG2+F5OvDS5+SYAT7AZZpmjdFOGG9f9KEB+a4+blUpFVhdGLSRAtYdxt1AJDhG+ Zv74Ul0ygZE0rR90Hrc5IxrSavVwaExyUn3sgxzcmFbD5WaqU+QnWO40zgbKC6Z/qc/0PZ DX9TnQBRf350DpMaljG0omxk5b5A/cGX2nXpxnvBs7+pU/BtoYYeXsPU9Gd1QA== Original-Received: from matt by naz with local (Exim 4.96) (envelope-from ) id 1oJJJL-0020M7-2S; Wed, 03 Aug 2022 11:41:39 -0700 In-Reply-To: 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:238644 Archived-At: 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 documen= tation > 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. 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...