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: Re: Perhaps rearrange *Help* buffer a bit? Date: Tue, 09 Jul 2019 00:38:42 +0200 Message-ID: References: <871rz0i5ik.fsf@tcd.ie> 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="6909"; 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: "Basil L. Contovounesios" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jul 09 00:39:31 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 1hkcIE-0001gF-VY for ged-emacs-devel@m.gmane.org; Tue, 09 Jul 2019 00:39:31 +0200 Original-Received: from localhost ([::1]:45382 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hkcID-00006h-Sy for ged-emacs-devel@m.gmane.org; Mon, 08 Jul 2019 18:39:29 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:52494) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hkcHa-00006A-3J for emacs-devel@gnu.org; Mon, 08 Jul 2019 18:38:51 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hkcHY-00046r-KU for emacs-devel@gnu.org; Mon, 08 Jul 2019 18:38:50 -0400 Original-Received: from quimby.gnus.org ([80.91.231.51]:57540) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hkcHY-00046K-DJ for emacs-devel@gnu.org; Mon, 08 Jul 2019 18:38:48 -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 1hkcHT-0005qA-54; Tue, 09 Jul 2019 00:38:45 +0200 Face: iVBORw0KGgoAAAANSUhEUgAAADAAAAAwBAMAAAClLOS0AAAAHlBMVEXo5eYZDQqSh4f6+flC NDNfU1L////+//4tHx3MwsVeAwEFAAACWklEQVQ4jWXUzW+bMBQAcNQsMG5zRSXvllKoyg0tLVlu gxmN3hpqKnJDQXsRt2hTqXorGUj0hsgn/+3cLU1wCxebH+a9Zz0jwO6K1MArSzxev0ymAMIrXDk6 tXHmVLv5K0Qh1ekclaX6BiZu0NPzUUhzkYduYc+7dHlMynMeVoVHDHeuuNl3HnTFcx03HGX2Jx60 E0qoRjOEnjmIRie1G/gFQuiag8Q+fnR054KteOLgp3cNS526GKE/HFyWNxAZ0tEoQ3ccLJFjVFOV niLM17HMbuogVetTVK450PBYr9Ij9RSX3JZEvnKrbiAee1nIQeznT3UHzOYtJAZ5bhYPcu1hnYsx UT1H6PTNbo51LqtEDWlvALNuofhnXIw6dG8jVfxKCpZDO90VJePYgC3JVb6OIy0IRDAvNNrwkOgk ODMHvqrLFgfQ6MEaktromcDDUFVFiOV6V16r4eSKPdu8tlsLYjMFkOA99BcwSIfvoW+ZZlMJAqQc yB0rFppGln4LfIHaOZhyx6jkNA7be5Vo84dKEnxBMr8UZguGV0XPMoeFIE61eZQeYDFR1lNzpVQW XH6OxQNsklyMpW3ZS2HyPD1ALCbHbGTb7NBEDhwgshLW4sNMKecWqDx8g1/EZof2GlZpG+5vYZsj O0NYvLI6LfiwnnoKOxsI/0jE2R5maQ2Jgtj7CLFsoz0I7L4vcWmjDJ+AdIAOS2TrYeyhHOfp7H+F L7BgQ+qxD2FSjsTI2sMmgihXwlwpiBeew2AP6z5MSoXkbuHl5A5iYQdxR4SPOaEuJSTw2Y/hX/S/ tCOIddpcQdUAAAAASUVORK5CYII= In-Reply-To: <871rz0i5ik.fsf@tcd.ie> (Basil L. Contovounesios's message of "Mon, 08 Jul 2019 22:24:35 +0100") 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:238420 Archived-At: "Basil L. Contovounesios" writes: > And in the case of variables, the trailing "You can _customize_ this > variable" which indicates a user option. Oh yeah, let's bikeshed the variable help buffers, too. Here's a random example: --- gnus-summary-article-delete-hook is a variable defined in =E2=80=98gnus-sum= .el=E2=80=99. Its value is nil Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*; global value = is the same. This variable may be risky if used as a file-local variable. Documentation: A hook called after an article is deleted. You can customize this variable. This variable was introduced, or its default value was changed, in version 22.1 of Emacs. --- Let's see... Along the lines of what Stefan bikeshod (that's the correct past tense of "bikeshed"), we could have... --- The value of `gnus-summary-article-delete-hook' value is nil ... Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*; global value is the same. A hook called after an article is deleted. --- The "..." is a button that will reveal this text: --- `gnus-summary-article-delete-hook' is a variable defined in =E2=80=98gnus= -sum.el=E2=80=99. This variable may be risky if used as a file-local variable. This variable was introduced, or its default value was changed, in version 22.1 of Emacs. You can customize this variable. --- > 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. Probably; there's a lot of variations. :-) >> 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. That's true, so perhaps that line should stay at the start of the buffer. Let's look at one of these, and I choose at random: --- insert-char is an interactive built-in function in =E2=80=98C source code= =E2=80=99. It is bound to C-x 8 RET. (insert-char CHARACTER &optional COUNT INHERIT) Probably introduced at or before Emacs version 18. [documentation here] --- What about... --- (insert-char CHARACTER &optional COUNT INHERIT) ... This is an interactive function bound to C-x 8 RET. [documentation here] --- --=20 (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no