From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: =?UTF-8?Q?Cl=c3=a9ment_Pit--Claudel?= Newsgroups: gmane.emacs.devel Subject: Re: Improving describe-mode and discoverability Date: Thu, 23 Jun 2016 17:50:39 -0400 Message-ID: <576C59AF.7080902@gmail.com> References: <576C2A6C.3090908@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="ljKoVo4vvnrlXhLs8tEc0dtPvQcA2xWLD" X-Trace: ger.gmane.org 1466718676 17277 80.91.229.3 (23 Jun 2016 21:51:16 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 23 Jun 2016 21:51:16 +0000 (UTC) To: Drew Adams , Emacs developers Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jun 23 23:51:03 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 1bGCWc-0002nx-NB for ged-emacs-devel@m.gmane.org; Thu, 23 Jun 2016 23:51:02 +0200 Original-Received: from localhost ([::1]:39610 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGCWY-0007Sf-I1 for ged-emacs-devel@m.gmane.org; Thu, 23 Jun 2016 17:50:58 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50432) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGCWR-0007SY-Oq for emacs-devel@gnu.org; Thu, 23 Jun 2016 17:50:53 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bGCWN-0002rQ-E2 for emacs-devel@gnu.org; Thu, 23 Jun 2016 17:50:50 -0400 Original-Received: from mout.kundenserver.de ([212.227.126.130]:63701) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGCWN-0002rJ-34 for emacs-devel@gnu.org; Thu, 23 Jun 2016 17:50:47 -0400 Original-Received: from [128.30.9.95] ([128.30.9.95]) by mrelayeu.kundenserver.de (mreue004) with ESMTPSA (Nemesis) id 0MMJXF-1bHYMe1zPZ-0085iU; Thu, 23 Jun 2016 23:50:41 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.8.0 In-Reply-To: X-Provags-ID: V03:K0:TcOR4YP36u8tnL2Dy67c+2uwAJr+kCnfKvKfYQI5YHIgWtH40ys WBAzqOZfK4BQftcS/vXSclTLYqxByEbdq40dsPsH4RHDux9EfCJStuRnV2YNXGWqQgM0hpL CB4MfQuPFtouHabfx69TgvavVNSq+i3za7/JOBUu1Hh0N963L+GPSn8DseT7I69GVtxkVFs XTXpUte6jU1gaDRVHNF4Q== X-UI-Out-Filterresults: notjunk:1;V01:K0:hNTY3lCIt+8=:G6ST5opp8ktpvVCmP4lr47 9NoiGaFGAa/4tJVXbqgcxpPH1MOtBGOsIjTyjpFnR+gRaeyHT8V6EqdRiSeBEJQejxwUke5Za TqXm9L1yOJ5bfeXcaRAwyVzO4yHZZiK40+ZPPwWK5lzDZjgbaNWtytIZyfqphRwL+ORdM0Wx1 amn5LfoOXMzJ0XFl/FnkgZWWb0nfuUYaZC4+JDzncmkIJzNo26/3wUqT1kv00t+TWu+mJe6lk J4BZSyGB9bSC4PpL+EU4SuW8suCpi8C5cfa3a7NoxO84BhAUb65HuILnJlOCWJ0Lyz0nnpOon HFYJk0FQokntkXEYPfiogNsZUQ1j09EqzLdUSrwGzNAlwvNHJcsTYFDbTkko2TUIjTyOa6DhL x3HAUqpP704XklrC5sZvOnxAHgGwM2lVpbfjwE5r37ntSHveKj57/Fd/Ky2Va2/uc4Jpxn8IY bfn0GgGZGTLvpUDa/62b7l34AYzcL6kyDdB8Tj+hwOxsNxqvuLlNnZXgGY2L0nGipvCscDnz6 ct6napOSojJ/muMKEoBoko857BqdlxmBe12cySH3mM+H4cx/bjTZ9qljupZiuVr9F7ki1/RG3 YSAhSbaYxu4Zh0wV7XSHfKfTSvYxokHzFt2Qv5PAyVDc9UzlrW3QXhSa0NdOxkF/HYWF260Wk X+Wkqj/dvLwvh+7pBVQT2C6lxScQLDgz714NwDmpGBjuG1xOF4EC15z3RAiP4hVetqG0= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.126.130 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:204709 Archived-At: This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --ljKoVo4vvnrlXhLs8tEc0dtPvQcA2xWLD Content-Type: multipart/mixed; boundary="tWpQEilmd0clA7x2MdlbaBmJNHxuWoDdi" From: =?UTF-8?Q?Cl=c3=a9ment_Pit--Claudel?= To: Drew Adams , Emacs developers Message-ID: <576C59AF.7080902@gmail.com> Subject: Re: Improving describe-mode and discoverability References: <576C2A6C.3090908@gmail.com> In-Reply-To: --tWpQEilmd0clA7x2MdlbaBmJNHxuWoDdi Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi Drew, Thanks for your opinion. Maybe my proposal wasn't clear, though, and lead= to confusion. I'm not proposing to replace mode docstrings by auto-generated text; in o= ther words, the output that I displayed was not intended to be the only t= hing displayed on C-h m. Instead, my proposal is to keep displaying mode docstrings. However, when= a mode docstring includes a \\{mode-map} (which seems to be a very commo= n thing to do), my proposal is to enhance the rendering of that \\{mode-m= ap} construct to print an actually useful table. Of course, we could put this behaviour behind a flag. My hunch is that modes that do things very well, and the description of k= eybindings into the mode docstring as you describe, don't include the \\{= mode-map} at the end. For the other ones, though, the ones that don't de= scribe the mode's bindings too well, we can make the life of users nicer = by making the rendering of \\{...} more readable. To sum up: we could just transform one kind of automatic output into anot= her kind of automatic output. What do you think? Does this make the proposal more clear? Cl=C3=A9ment. On 2016-06-23 16:26, Drew Adams wrote: >> 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 alwa= ys >> works, but it's not very nice to use: it just gives you a list of func= tion >> names and the associated bindings. >=20 > No, it gives you whatever is in the doc string for the `*-mode' functio= n. >=20 >> 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 f= or >> each binding not only the name of the associated function, but also th= e >> 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 example= s of >> the output for several other modes to this email, as well as the code = used >> to generate this example. Contrast with the default output of C-h m fo= r >> 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 = demoed >> above would be very useful. Most interactive functions are already >> documented, so we'd be tapping into a large body of existing docs, mak= ing >> them more accessible. >> >> What do you think? I would be happy to get help in refining this code = (and >> this proposal). For example, we could consider hyperlinking the functi= on >> names to their sources, or letting users expand the first line of the >> documentation to show the full docstring. We could also think about wa= ys to >> cover functions that are not bound to a key by default, but which user= s may >> want to bind (e.g. by looking for interactive functions starting with = the >> mode's name). >=20 > My two cents: We should not do such a thing automatically. >=20 > 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. >=20 > 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. >=20 > Different modes serve different purposes. A doc string should be > handwritten for a given mode. >=20 > 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). >=20 > 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. >=20 > 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. >=20 > 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. >=20 > There is no royal road to doc strings. >=20 > Just one opinion. >=20 --tWpQEilmd0clA7x2MdlbaBmJNHxuWoDdi-- --ljKoVo4vvnrlXhLs8tEc0dtPvQcA2xWLD Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (GNU/Linux) iQIcBAEBAgAGBQJXbFmvAAoJEPqg+cTm90wjDKgQAJ4LfRz+rMY6bckC9oKG6FAI nrubBqPNItFZu66aYdKSOyMtU1niODJbR8MxHkjG8CgS37//sjnHihUDFI85ft1h 0Pr4DCg6WHoBxoMyHxCeLI7o1p+rrfQZb8WkPTfXkPPWRYS6ewoJ1c3eFLL0yc38 i+jL9D5wd6VEB4C5URDud3jeEOWJmxqgBX3mGy2dplv0GWpGS+7GKHqrx5XhpdQu 1q1uQR2eCyTQf6geoRn3IaRnIwniB+S4VdSj+kTScMYFxXWpFKE/hKx+M25K3X2O FtiqEoLAoIYKuDPPOit5vE2cTaZucs92J0GFIRr+2RKQT/GyqVtliJbv5RwAEMK2 yzIx3g1a/jbkWczAEoG/TfawK4atHUzOH9jzvcNFE8Laps14j/wz9LBpFX4UXsHE OuX85jvz8mU7w05Olas7j+zgHI/a5e0bSYjCFr04SxkS2oUV/zRAzBqCUWQPBlQx mcho7IXnoatG513d+8NvoeWqS6gTd/hGYEaHw1BXOC9J0Bh6bWk6RWEpjnDVi5HT 5Oqr9ps49Z4h8j2HD1FqfMk7H8wTIxZ6nlr7TNjTsiqv9b2M8heGMxKBZgpG0UCz IzD89vPtrwHJiqXs7nrW1qp6Pu1uSB3ZnkP2QOSoJtQ5uGNIPHeNKdkRaX3aMfx6 WC6vDG3j5wdBukQiEpvQ =GRbq -----END PGP SIGNATURE----- --ljKoVo4vvnrlXhLs8tEc0dtPvQcA2xWLD--