From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Gregory Heytings via "Emacs development discussions." Newsgroups: gmane.emacs.devel Subject: RE: How to make Emacs popular again. Date: Thu, 08 Oct 2020 23:13:58 +0000 Message-ID: References: <20200926163008.GS1349@protected.rcdrun.com> <749c3394-ec9a-43a5-aad6-942a5583d072@default> <39e60177-7d71-489a-a39c-38b3cf291266@default> Reply-To: Gregory Heytings Mime-Version: 1.0 Content-Type: text/plain; format=flowed; charset=US-ASCII Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="27917"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Alpine 2.22 (NEB 394 2020-01-19) Cc: Robert Pluim , emacs-devel@gnu.org, bobnewell@bobnewell.net, Richard Stallman , =?ISO-8859-15?Q?Jo=E3o_T=E1vora?= To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Oct 09 01:14:56 2020 Return-path: Envelope-to: ged-emacs-devel@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 1kQf7g-00079L-51 for ged-emacs-devel@m.gmane-mx.org; Fri, 09 Oct 2020 01:14:56 +0200 Original-Received: from localhost ([::1]:32938 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kQf7f-0002AQ-6v for ged-emacs-devel@m.gmane-mx.org; Thu, 08 Oct 2020 19:14:55 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49584) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kQf6v-0001jm-Rp for emacs-devel@gnu.org; Thu, 08 Oct 2020 19:14:09 -0400 Original-Received: from mx.sdf.org ([205.166.94.24]:54521) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kQf6s-0001fY-Sm; Thu, 08 Oct 2020 19:14:09 -0400 Original-Received: from sdf.org (IDENT:ghe@otaku.sdf.org [205.166.94.8]) by mx.sdf.org (8.15.2/8.14.5) with ESMTPS id 098NE0TC022314 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits) verified NO); Thu, 8 Oct 2020 23:14:01 GMT Original-Received: (from ghe@localhost) by sdf.org (8.15.2/8.12.8/Submit) id 098NE0nX022725; Thu, 8 Oct 2020 23:14:00 GMT In-Reply-To: <39e60177-7d71-489a-a39c-38b3cf291266@default> Received-SPF: pass client-ip=205.166.94.24; envelope-from=ghe@sdf.org; helo=mx.sdf.org X-detected-operating-system: by eggs.gnu.org: First seen = 2020/10/08 15:58:48 X-ACL-Warn: Detected OS = ??? X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:257238 Archived-At: > > That one should be covered by an explicit sentence with a link to the > manual. I already mentioned that (and said I do that in help-fns+.el). > Sorry, I did not know you already do that in help-fns+.el when I answered RMS' email a few hours ago. As I mentioned earlier, there are however two important difference between what you do in help-fns+ (which I just tried) and what I proposed: 1. I do not think this can be done programmatically, the meaning of the proposal was to do this by adding information in docstrings manually. 2. I do think that a link to the place where the function/variable/... is being defined in the manual is the best solution, a link to the chapter would be better. I just tried it with "kill-buffer", the additional information (additional wrt to the docstring) I get by entering the two manual sections is nil. > > But even that one could be handled instead, or also, the same way. > It's not quoted (`...'), but it's easy to find where it is and give it > go-to-manual behavior. > IMO this would not be optimal. I think an explicit link (like the one at the end of the docstring of defcustom) makes it clear that if you follow it you leave the "built-in" documentation and open a "manual" (in another window). >> Not a pile, one or two. The point is to make manuals more accessible. > > Both would be useful: > > 1. Link(s) to manual(s) for the name that is the subject of the help. > This can be in an explicit sentence that makes clear what it does - as > mentioned earlier. > Yes. > > 2. Links to manuals for each quoted, linked name in the buffer (or each > known to be doc'd in a manual, if that's known when the buffer is > created). > > For #2, such names already have inline links where they occur. It > suffices to (1) give users an easy way to get to the manual(s) from that > location, preferably by both mouse and key, and (2) let users know about > this possibility. > Perhaps I don't understand what you mean, but I don't see why this would be useful. The current system (docstrings with links to other docstrings) works well. If links to manual chapters are added at the end of each docstring, why would it be necessary to duplicate that information after the docstrings that refer to a given docstring? For example, why would it be useful to add a link (info "(elisp)Processes") in kill-buffer because it mentions 'process-buffer', when following the link on 'process-buffer' already opens (or rather, would open) a help buffer with a link to (info "(elisp)Processes")?