From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: "Basil L. Contovounesios" Newsgroups: gmane.emacs.devel Subject: Re: Perhaps rearrange *Help* buffer a bit? Date: Mon, 08 Jul 2019 22:24:35 +0100 Message-ID: <871rz0i5ik.fsf@tcd.ie> References: 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="50137"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: emacs-devel@gnu.org To: Lars Ingebrigtsen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jul 08 23:43:58 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 1hkbQS-000CZm-7z for ged-emacs-devel@m.gmane.org; Mon, 08 Jul 2019 23:43:56 +0200 Original-Received: from localhost ([::1]:44846 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hkb8x-0007T2-A1 for ged-emacs-devel@m.gmane.org; Mon, 08 Jul 2019 17:25:51 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:35134) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hkb7t-0007Sn-4L for emacs-devel@gnu.org; Mon, 08 Jul 2019 17:24:46 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hkb7r-0000yQ-UL for emacs-devel@gnu.org; Mon, 08 Jul 2019 17:24:44 -0400 Original-Received: from mail-wr1-x42a.google.com ([2a00:1450:4864:20::42a]:34776) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hkb7r-0000ur-Gs for emacs-devel@gnu.org; Mon, 08 Jul 2019 17:24:43 -0400 Original-Received: by mail-wr1-x42a.google.com with SMTP id 31so1885902wrm.1 for ; Mon, 08 Jul 2019 14:24:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tcd-ie.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=uN9Dw9N53AHf38BKQNvm39K3TYKWwVzONXmeRmlLZLY=; b=Hcsu7a6L2TjJ53C0hDsPzNKef3K3K8B1/5FWDtB3W0Z1phl2GxadzZKtiIHjzZY6O2 RHVk5yv9PfVH1mPKb0GZBVa7MjOV+ebeJErVTDUXodx7ySCQiPAdDzx2B59UJvOdKsIG 9tYE4eDFMSOTfcTFnOtgr+CNP3aJvxFFdqoxwe6ZfraLoNUK1ETj9bL597oDKsqBt3yG GEhhXTZKBX7Jv0y51UFPFrmbHf5FQG2ThSyIqVtg0imFEQ86wWmON4XxBqZN9QWZndkA PbEK2YLLsPYY/haZ6dLlenc0bNPefEiFZvYLHjJjl6cq65uYsavUt4Y9qtleToC+7zcd 2asA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=uN9Dw9N53AHf38BKQNvm39K3TYKWwVzONXmeRmlLZLY=; b=Yk7Plf6XYSEEe5HgdATrGywjOdyBjMtUiAJk3FZzhmtoB61iNomMk5DEuckmLkCU+W dAdBFznaQ2T7zPW9tTL1q+/XesAgzkOSW6rXUziQoEiafovW6Sd58k4oY1ClVdMxOiRV ewZ3QGrPD1wPbHCdNCTtwAfO0YtmvXv3Pe31GjQwAWhsvBTdIcIF+6R+z3ryF2pujtiU shJxX3YJPyqcdzJZKiTZNUCudgQZ0rlJrTZk2Q2CsglmZq9jQKOeloOAigzJ1+Femt36 SzSNGOjSDjuEIazhKpg6zbbhD+XDh24ntTJ9o+/ZFRKSUztrJ4HQEMnCvbIM4F/XbR+Q ym3w== X-Gm-Message-State: APjAAAVeHPhQH98MzSgG0DgdLV0HsArabQvjeSNYcnOIg2rAlCe716si qcmHkZCKaFGlONQj2fLQROW3bc1Ht80= X-Google-Smtp-Source: APXvYqxK0rJKAIo7ug05L8MA5yTN+mOMsYI4XWdG3nsxMLWozClruW8A+boNMMZxxhkf8NKiMKDgxw== X-Received: by 2002:adf:eb06:: with SMTP id s6mr21140329wrn.151.1562621077535; Mon, 08 Jul 2019 14:24:37 -0700 (PDT) Original-Received: from localhost ([2a02:8084:20e2:c380:92bd:1bfd:38fc:fae2]) by smtp.gmail.com with ESMTPSA id o7sm515716wmf.43.2019.07.08.14.24.36 (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Mon, 08 Jul 2019 14:24:36 -0700 (PDT) In-Reply-To: (Lars Ingebrigtsen's message of "Mon, 08 Jul 2019 22:18:58 +0200") X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42a 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:238418 Archived-At: Lars Ingebrigtsen writes: > 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-cX= Xr=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 rel= ated 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. Don't forget me! > 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). And in the case of variables, the trailing "You can _customize_ this variable" which indicates a user option. And maybe also the indication of the presence of some advice on a named function: ":around advice: `some-function@my-advice'" And maybe some other usual suspects I'm forgetting about. > 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.) The first line also indicates whether a function is interactive, so I think it is useful for the average user. > Anyway, what about rearranging this a bit so that the stuff the users > are interested in comes first? No objections here. Thanks, --=20 Basil