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 13:26:44 -0700 (PDT) Message-ID: References: <576C2A6C.3090908@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 1466713643 1013 80.91.229.3 (23 Jun 2016 20:27:23 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 23 Jun 2016 20:27:23 +0000 (UTC) To: =?utf-8?B?Q2zDqW1lbnQgUGl0LS1DbGF1ZGVs?= , Emacs developers Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jun 23 22:27:10 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 1bGBDP-0007Fb-Ql for ged-emacs-devel@m.gmane.org; Thu, 23 Jun 2016 22:27:08 +0200 Original-Received: from localhost ([::1]:39202 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGBDO-0000Tb-PT for ged-emacs-devel@m.gmane.org; Thu, 23 Jun 2016 16:27:06 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54668) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGBDD-0000Pu-AP for emacs-devel@gnu.org; Thu, 23 Jun 2016 16:26:56 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bGBD9-0005rd-3z for emacs-devel@gnu.org; Thu, 23 Jun 2016 16:26:54 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:48802) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGBD8-0005rS-Sq for emacs-devel@gnu.org; Thu, 23 Jun 2016 16:26:51 -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 u5NKQl6c010038 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 23 Jun 2016 20:26:47 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 u5NKQkAU016326 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 23 Jun 2016 20:26:47 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 u5NKQiYM011628; Thu, 23 Jun 2016 20:26:45 GMT In-Reply-To: <576C2A6C.3090908@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:204707 Archived-At: > Among the many ways to get information about a package (READMEs, > Commentaries, manuals, menu-bar menus, and describe-mode; are there > others?), describe-mode is the only universally available one. It always > works, but it's not very nice to use: it just gives you a list of functio= n > names and the associated bindings. No, it gives you whatever is in the doc string for the `*-mode' function. > Recently I added an extra documentation feature to one of my packages, > biblio.el. It's a single function that walks a keymap, and displays for > each binding not only the name of the associated function, but also the > first line of the documentation of each function. Here's how it looks in > haskell-mode: ... > It's not much, but I think it looks much better. I've attached examples o= f > the output for several other modes to this email, as well as the code use= d > to generate this example. Contrast with the default output of C-h m for > haskell-mode: ... > My implementation is rather brittle (I don't have sufficient knowledge of > keymaps), but I think a documentation facility in the line of the one dem= oed > above would be very useful. Most interactive functions are already > documented, so we'd be tapping into a large body of existing docs, making > them more accessible. >=20 > What do you think? I would be happy to get help in refining this code (an= d > this proposal). For example, we could consider hyperlinking the function > names to their sources, or letting users expand the first line of the > documentation to show the full docstring. We could also think about ways = to > cover functions that are not bound to a key by default, but which users m= ay > want to bind (e.g. by looking for interactive functions starting with the > mode's name). My two cents: We should not do such a thing automatically. Instead, if you think that some of what you envisage or you have implemented can usefully be factored into useful building blocks that are not already available for use in doc strings, then consider adding those as separate functions. For literal doc strings there are already the constructs \\[...], \\<...>, and \\{..}. For strings that you might create dynamically you can use `substitute-command-keys'. Anything automatic is likely to be less than helpful, I think: overkill, underkill, or both. Different modes serve different purposes. A doc string should be handwritten for a given mode. Of course, some kinds of modes have some things in common, which can be _added_ to the doc string automatically. That's the case for `define-minor-mode', for example. But there is no substitute for the _specific_ description of the mode (what you provide to `define-minor-mode' as input, for example). Generally, a mode's doc string calls out particular features of the mode, which might include some particularly important commands or keys. Just listing descriptions of all keys and commands is not the way to go, in general, even if it might be useful for some modes. The particular descriptions used for the important commands and variables can be tailored to fit the general presentation of the mode, saying what is most appropriate for it as a whole. IOW, in a mode doc string the keys or commands are described _together_. That description can be more/better than just an independent one-liner for each command and variable. A mode is more than the sum of its parts. And a writer of a mode is not limited to barebones descriptions or to just showing which commands are bound to which keys. There is no royal road to doc strings. Just one opinion.