From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Improving describe-mode and discoverability Date: Thu, 23 Jun 2016 16:15:37 -0700 (PDT) Message-ID: References: <576C2A6C.3090908@gmail.com> <576C59AF.7080902@gmail.com> <9c928ea6-6799-d096-de54-b2bf7ac140ec@yandex.ru> <576C6256.6060708@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1466723798 28188 80.91.229.3 (23 Jun 2016 23:16:38 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 23 Jun 2016 23:16:38 +0000 (UTC) To: =?utf-8?B?Q2zDqW1lbnQgUGl0LS1DbGF1ZGVs?= , Dmitry Gutov , Emacs developers Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jun 24 01:16:25 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bGDrE-0000JA-3t for ged-emacs-devel@m.gmane.org; Fri, 24 Jun 2016 01:16:24 +0200 Original-Received: from localhost ([::1]:39958 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGDrD-0007KJ-1T for ged-emacs-devel@m.gmane.org; Thu, 23 Jun 2016 19:16:23 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41971) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGDqh-0007K3-2q for emacs-devel@gnu.org; Thu, 23 Jun 2016 19:15:52 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bGDqc-0007DQ-Qp for emacs-devel@gnu.org; Thu, 23 Jun 2016 19:15:50 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:44958) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGDqc-0007D6-II for emacs-devel@gnu.org; Thu, 23 Jun 2016 19:15:46 -0400 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u5NNFeLq011096 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 23 Jun 2016 23:15:41 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0022.oracle.com (8.13.8/8.13.8) with ESMTP id u5NNFeJl012207 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 23 Jun 2016 23:15:40 GMT Original-Received: from abhmp0015.oracle.com (abhmp0015.oracle.com [141.146.116.21]) by aserv0122.oracle.com (8.13.8/8.13.8) with ESMTP id u5NNFcTT011942; Thu, 23 Jun 2016 23:15:39 GMT In-Reply-To: <576C6256.6060708@gmail.com> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6744.5000 (x86)] X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 156.151.31.81 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:204713 Archived-At: > >>> Of course, we could put this behaviour behind a flag. > >> > >> If it is a new construct instead of a replacement for \\{...} > >> then there is no need for a flag. > > > > I'd prefer a flag (or just the new behavior). There's no need to split = the > > community here: if I user likes this output, they'll want to see it in = all > > mode descriptions, not just the ones that opted in. >=20 > I think I agree. Drew, wouldn't you think that this is something the user > should choose, instead of the mode author? > As a user, I'd like consistent rendering; as a mode author, I'd rather no= t > argue with my users about one which one looks best for each one of my mod= es. I probably don't have a good enough idea of what you have in mind. I think: 1. A writer of a mode should be able to decide what is said in the mode doc. 2. Ideally, a user should be able to decide what that looks like, including perhaps, what parts of it to show. What do we do TODAY? See (elisp) `Major Mode Conventions'. There it says: "The documentation string may include the special documentation substrings, `\[COMMAND]', `\{KEYMAP}', and `\', which allow the help display to adapt automatically to the user's own key bindings. *Note Keys in Documentation::." Note: *MAY* include `\{KEYMAP}'. We do not automatically and systematically show a list of the bindings in the help for every mode. The decision of whether to include that for any given mode is up to the mode writer. It is not up to the user, today. I would probably have no problem with that being changed to being a user option. But in that case, if a user turns this display of keys off, does that override the current situation of a mode writer having deemed that the keys should be shown for some mode? There are really a few issues raised implicitly by Clement: 1. Whether to replace \\{...} with Clement's alternative representation or to provide a different construct to show it. 2. Whether to let users choose to show the result of \\{...} differently (i.e., as it is shown currently or in Clement's way). 3. Whether to include \\{...} automatically for all modes, whether it uses the original representation or Clement's alternative. 4. Whether including \\{...} automatically for all modes should be a user option (regardless of which representation is used). I don't have answers now for all of those, and I'm not even sure which of them are are actually being proposed. Personally, I have no problem with the _current_ situation, and so far I have not heard a clear alternative proposal that sounds better to me.