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?= <clement.pit@gmail.com>
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>
	<f0894c67-1eda-4cee-8614-1c2d79d349a9@default>
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 <drew.adams@oracle.com>, Emacs developers <emacs-devel@gnu.org>
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jun 23 23:51:03 2016
Return-path: <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>
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 <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>)
	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 <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>)
	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 <clement.pit@gmail.com>) 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 <clement.pit@gmail.com>) 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 <clement.pit@gmail.com>) 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: <f0894c67-1eda-4cee-8614-1c2d79d349a9@default>
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." <emacs-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/emacs-devel/>
List-Post: <mailto:emacs-devel@gnu.org>
List-Help: <mailto:emacs-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=subscribe>
Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org
Original-Sender: "Emacs-devel" <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>
Xref: news.gmane.org gmane.emacs.devel:204709
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/204709>

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?= <clement.pit@gmail.com>
To: Drew Adams <drew.adams@oracle.com>, Emacs developers <emacs-devel@gnu.org>
Message-ID: <576C59AF.7080902@gmail.com>
Subject: Re: Improving describe-mode and discoverability
References: <576C2A6C.3090908@gmail.com>
 <f0894c67-1eda-4cee-8614-1c2d79d349a9@default>
In-Reply-To: <f0894c67-1eda-4cee-8614-1c2d79d349a9@default>

--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--