From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Lars Ingebrigtsen Newsgroups: gmane.emacs.devel Subject: Perhaps rearrange *Help* buffer a bit? Date: Mon, 08 Jul 2019 22:18:58 +0200 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="236553"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jul 08 22:19:20 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hka6Z-000zOJ-Ka for ged-emacs-devel@m.gmane.org; Mon, 08 Jul 2019 22:19:19 +0200 Original-Received: from localhost ([::1]:44514 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hka6Y-0002gw-Mt for ged-emacs-devel@m.gmane.org; Mon, 08 Jul 2019 16:19:18 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48174) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hka6T-0002gd-N0 for emacs-devel@gnu.org; Mon, 08 Jul 2019 16:19:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hka6R-0000R2-LU for emacs-devel@gnu.org; Mon, 08 Jul 2019 16:19:13 -0400 Original-Received: from quimby.gnus.org ([80.91.231.51]:55536) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hka6L-0000N3-5h for emacs-devel@gnu.org; Mon, 08 Jul 2019 16:19:07 -0400 Original-Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=stories) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hka6E-0004rR-OE for emacs-devel@gnu.org; Mon, 08 Jul 2019 22:19:01 +0200 Face: iVBORw0KGgoAAAANSUhEUgAAADAAAAAwBAMAAAClLOS0AAAAHlBMVEUIBQUHBQQGAwPT8oPL aLpVL0IJBwe4mHoHBAQFAgJ0MKEkAAACbElEQVQ4jVWUPW/bMBCGjwFCcNR5ENzN4hBQs2H4DyjV WqCS05EBHCadHUcrTcAGvRWawn/bIyUZ8sEfIB+990kKTDStvAwhfIsiQ0SjaQt4BB9euF7K8sQQ c8xZBKsIhHOlkh5oOzOvnp7WAIYbACtccZUKkykEcQViRgDDPAUrFvnr4pIBBJAXzVjGHg9rsg3g mEwJ0lqB5zztrzcc39rWaE2uEMC7/e+0v95qbNv2V8a8peAPsmjWI+AMM0oZr0+gV1o8VYebAnHR I8IFrFf+XE+Ap3xLtAZ6F4p93Y0AMAQpe08xnO9lcwMGf1DPKCEA4cunqu4O621HVrV/YwyIWXn1 eAOfVfW8pCDwwQGc2BPoJlD9kacFFUEC39yBn2yhLtRBKS+06rrDBJ61XloC3p9pVc+BclasyNm+ SpIJVJB5SwUa3VRJclN8WFjqOPPq3mrqb0szh8e73S7ZUVMd3DQzMoBdPAfAmzvJ10t3jMcHBMxB kuwi8FY0t6epi93xJQpIwSfFELg+JgEpvGrmcT8pQjq78NA380y7OgkMaGdHMM79fUftMLElY4xu HC+54ukagJ9Akmy7MTjVfgdiQ4YY/A5sbwUKr+dg6GEEdupVCr4dmxjrAD1Ld6zlmFxBKsi8D9lu hlVUGLiqa/jOB/DFJyCkCtKVWLwPpzfT2dBEUfaylAVb5HSttjvMciNsVDgp5T8XeonZW2uWeEK6 AQRcGQJ9HHlblVI5RNbboe2hL3tlgekHtvQ24+g5JQAFuVJOKU+3ZcnovZGRL5oUhJ4ul1rFgWmj vfNCyuQqJCvjjyrTP31PJ/MfKLtSOTzMvLkAAAAASUVORK5CYII= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 80.91.231.51 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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:238413 Archived-At: I think Drew (or somebody?) mentioned this in a bug report the other day: The way the automated stuff is arranged in the *Help* buffer is perhaps not optimal. Consider: ---- cadr is a compiled Lisp function in =E2=80=98subr.el=E2=80=99. (cadr X) This function has a compiler macro =E2=80=98internal--compiler-macro-cXXr= =E2=80=99. Probably introduced at or before Emacs version 20. Return the car of the cdr of X. ---- car is a built-in function in =E2=80=98C source code=E2=80=99. (car LIST) Probably introduced at or before Emacs version 1.2. This function does not change global state, including the match data. Return the car of LIST. If arg is nil, return nil. Error if arg is not nil and not a cons cell. See also =E2=80=98car-safe=E2= =80=99. See Info node =E2=80=98(elisp)Cons Cells=E2=80=99 for a discussion of relat= ed basic Lisp concepts such as car, cdr, cons cell and list. ---- So the thought here is that those indented lines isn't what's most interesting to the user. The compiler macro stuff is interesting to about two people in the world, and the "introduced at or before" to seven. What people want to know is the calling convention (line 3) and the stuff a human has lovingly written (starting in line 8 in both these examples). The first line is perhaps not vital for people to know either, but since that's what I use to jump to function definitions, it's useful. (But perhaps a command that's just take us there is even better.) Anyway, what about rearranging this a bit so that the stuff the users are interested in comes first? So... something like... ---- cadr is a compiled Lisp function in =E2=80=98subr.el=E2=80=99. (cadr X) Return the car of the cdr of X. -- (This function has a compiler macro =E2=80=98internal--compiler-macro-cXXr= =E2=80=99. Probably introduced at or before Emacs version 20.) ---- The automatic coda separated out in a separate parenthetical section? Or with a dimmer colour? Let the bike-shedding commence! --=20 (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no