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 19:39:18 -0400
Message-ID: <576C7326.1020502@gmail.com>
References: <576C2A6C.3090908@gmail.com>
	<f0894c67-1eda-4cee-8614-1c2d79d349a9@default>
	<576C59AF.7080902@gmail.com>
	<a9f2f153-f3d0-4bf6-826a-aa13648259f6@default>
	<9c928ea6-6799-d096-de54-b2bf7ac140ec@yandex.ru>
	<576C6256.6060708@gmail.com>
	<bed3fbb5-e222-404a-8343-e6947b55deb0@default>
NNTP-Posting-Host: plane.gmane.org
Mime-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha1;
	protocol="application/pgp-signature";
	boundary="mlemLrhJjC72fejnQRc5Hona0xVHjJF8L"
X-Trace: ger.gmane.org 1466725318 16433 80.91.229.3 (23 Jun 2016 23:41:58 GMT)
X-Complaints-To: usenet@ger.gmane.org
NNTP-Posting-Date: Thu, 23 Jun 2016 23:41:58 +0000 (UTC)
To: Drew Adams <drew.adams@oracle.com>, Dmitry Gutov <dgutov@yandex.ru>,
	Emacs developers <emacs-devel@gnu.org>
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jun 24 01:41:43 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 1bGEFh-0005JU-75
	for ged-emacs-devel@m.gmane.org; Fri, 24 Jun 2016 01:41:41 +0200
Original-Received: from localhost ([::1]:40028 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 1bGEFg-0003f0-I1
	for ged-emacs-devel@m.gmane.org; Thu, 23 Jun 2016 19:41:40 -0400
Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46470)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <clement.pit@gmail.com>) id 1bGEDc-0002br-6r
	for emacs-devel@gnu.org; Thu, 23 Jun 2016 19:39:33 -0400
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <clement.pit@gmail.com>) id 1bGEDW-00046c-6d
	for emacs-devel@gnu.org; Thu, 23 Jun 2016 19:39:31 -0400
Original-Received: from mout.kundenserver.de ([212.227.17.10]:59429)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <clement.pit@gmail.com>) id 1bGEDV-000463-SS
	for emacs-devel@gnu.org; Thu, 23 Jun 2016 19:39:26 -0400
Original-Received: from [18.26.2.123] ([18.26.2.123]) by mrelayeu.kundenserver.de
	(mreue103) with ESMTPSA (Nemesis) id 0LhTpQ-1bl73A10iG-00maQg;
	Fri, 24 Jun 2016 01:39:20 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
	Thunderbird/38.8.0
In-Reply-To: <bed3fbb5-e222-404a-8343-e6947b55deb0@default>
X-Provags-ID: V03:K0:YkOWfWNjj58E82myVywCcA8vvU9HweaTjAD2oBSCuP/63DjVteG
	eS+vRdhHShwh0Yl342Qdmcbq17KC5ZRHCqy4kEZ7BzAPBYp1mxxJkVSmctssDOXHRbjBEc5
	EyC+bMdCzeqbhU/2bLPAu01kZno2jBEyBA5SpYraS+IiMNZk58nR6OTpbWRIiaqsNWKT7fn
	Q84F1AQTrASp9RO8fpDkA==
X-UI-Out-Filterresults: notjunk:1;V01:K0:zdu0yQ8wyQ4=:qsrrf63bUnrpK+FRdY/y2U
	dXVF6DV/zIH5/D4zoL0wgag9aRHtpdc21tmz/rqYywFG0Kl82NYPhBt+bZxw8vPegOgMP8vQj
	5dEFy3lX7B3y926Vx2kMABK0SrrANsul5/gTYU3eUqdN9x3D6qCYslHGvw7i3FZsm2Yu0jomX
	8NKVsLyyPgdyMsLvOCwxUB0TiBzmEcKLFCVeIrYQ+wDhG5poihZu4cVXmorPrQEEiVkBiAzel
	38Hh6KLOpnJhEheNAa4gciVCAC8neI0vpLLKmmqmAWL52Edxh3WilwzR7wm3fWQ9ka3CZWISN
	xE+hhWAgRUMlsXMBW0tgIHfhk3fSMDX+Ln2tA4dgtbrFYDeHjtbA3PGonaVoeqXvGDmpIlGPv
	6X7VgTFQ5cbl9DhgWCD8VRy5izpBhGPFiwq5RatIX49e0BD3OCSvroDrYDVsU4JCgxZsBtd+N
	muakqTfpCiL67PdJzwG/Pbv4ShMB/EqX7MyZbuhoOptz/ZNZnSrA+4AyCSXmd710hMOiTRS3f
	PC6xCjDGYQztr3kaeDMyfwqq4I3RPsT1EBjdtl71beNPSOjwlBQYr7rj3Rl61xpl2Kyaoq0E+
	KyoDPRAk65/4kVIWquwUol3ohFHYEAsjGVSFPg8O8cWT7KbEnrwWq6N73bZrUxGdsJTN9d3XW
	qxa8qLCfsBA4f9WFe/kHCR2gi9kQm/0wg3F3TA0b2H1vmlYRK+RGJGy+SDBsUHcBdLZI=
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]
X-Received-From: 212.227.17.10
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:204714
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/204714>

This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--mlemLrhJjC72fejnQRc5Hona0xVHjJF8L
Content-Type: multipart/mixed; boundary="OJN6g0GgbNB5sRLLVK7FJRr3qRL4fhnc0"
From: =?UTF-8?Q?Cl=c3=a9ment_Pit--Claudel?= <clement.pit@gmail.com>
To: Drew Adams <drew.adams@oracle.com>, Dmitry Gutov <dgutov@yandex.ru>,
 Emacs developers <emacs-devel@gnu.org>
Message-ID: <576C7326.1020502@gmail.com>
Subject: Re: Improving describe-mode and discoverability
References: <576C2A6C.3090908@gmail.com>
 <f0894c67-1eda-4cee-8614-1c2d79d349a9@default> <576C59AF.7080902@gmail.com>
 <a9f2f153-f3d0-4bf6-826a-aa13648259f6@default>
 <9c928ea6-6799-d096-de54-b2bf7ac140ec@yandex.ru> <576C6256.6060708@gmail.com>
 <bed3fbb5-e222-404a-8343-e6947b55deb0@default>
In-Reply-To: <bed3fbb5-e222-404a-8343-e6947b55deb0@default>

--OJN6g0GgbNB5sRLLVK7FJRr3qRL4fhnc0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

On 2016-06-23 19:15, Drew Adams wrote:
> 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.

Possibly because I was hoping for your help (and that of others, of cours=
e) to come up with a clear proposal :)

Here's an attempt. I propose that we:

1. Introduce a new function variable `format-keymap-function'. It should =
be set to a function accepting one argument (a keymap) and rendering that=
 keymap for display to the user.

2. Change the way \\{...} formatting works to make it call out to the val=
ue of format-keymap-function.

3. Set the default value of format-keymap-function to a new function, imp=
lemented to render keymaps as I demoed in previous messages.

I think this responds to your four points:

> 1. Whether to replace \\{...} with Clement's alternative
> representation or to provide a different construct to show it.

I propose to replace the existing \\{} construct.

> 2. Whether to let users choose to show the result of \\{...}
> differently (i.e., as it is shown currently or in Clement's
> way).

I propose to let user customize the result, using `format-keymap-function=
'.

> 3. Whether to include \\{...} automatically for all modes,
> whether it uses the original representation or Clement's
> alternative.

I propose to not include it automatically; this is left to the mode autho=
r, or in any case to a separate proposal.

> 4. Whether including \\{...} automatically for all modes
> should be a user option (regardless of which representation
> is used).

I propose to not create such an option. This could be a separate proposal=
=2E

The current proposal is to not hardcode \\{} to produce a two-columns dis=
play, but instead to make it customizable. In addition, the proposal is t=
o change the default to include the headers of docstrings, as demoed in p=
revious emails.

Let me know if I can make this clearer :)
Cl=C3=A9ment.


--OJN6g0GgbNB5sRLLVK7FJRr3qRL4fhnc0--

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

iQIcBAEBAgAGBQJXbHMmAAoJEPqg+cTm90wjOx0P/0TFDcWP1KGmqzJl2+ASaZq7
/rje0JTxXv8Z2IZxzY5cWUsw8ltF4DoewWlAuLh7BbC1YJyY9wYzI68/RljQzOU1
OPISsrokVpCkwmXRbwK8dlwy8R87W6LUztr/ktyr+4vsVdxnHDojBhEpopnU7HFh
17rr7vvacoIkE9SB6a1x/fJTsoAGQzzcgUgNR9RtY/7Uc3rApqN714Yw00e1EUgJ
bNbiigyiI1T1H8GCb6FOu17EzfwGITx+3wzbjJYwSdaeTHUwal0oA7EcY7w8HLzd
LU3r+h0+vUQsU988zfJSfIz3U2txVdlq/WtZwfCLgiFrosijGCakEevKBkS3LGM9
mbPNZ2keNWUg2ZWuollCKkqJcddfWyrt4Ay0ShUV/KhZkynbJ8gNufhQaggV9NUi
6fZnM8GHbF5mk68GVhQ9wHaM6VUurE9uqbNz/GEQN+qise5gxgpAe7lhyUqsQqxn
pK8mIuFxY/PEbbpdcrhuoLAFvXxwqoduJJ74Q6qINLv+Gdt9Bq72BscISQ5SmWyH
SLJ4SNmxhyN2vHd4EiciMb5V1cqJrRMEdhcVgKAg9fsb8GTFGjepO1LbDn9U+zBV
LLwFBZ1i0b/D9bFE0ZE0C5GW0ESU+e02Dq9F1ZeY93hroAXwv4VdHsO3lLIgQrW6
o+kNnIy3NX0U8clFDRGz
=Uqph
-----END PGP SIGNATURE-----

--mlemLrhJjC72fejnQRc5Hona0xVHjJF8L--