From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Howard Melman Newsgroups: gmane.emacs.devel Subject: Re: Proposal for an improved `help-for-help' Date: Wed, 07 Apr 2021 19:15:58 -0400 Message-ID: References: <838s7hxqkr.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="36597"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (darwin) To: emacs-devel@gnu.org Cancel-Lock: sha1:IJXynPF3K4RbNf/QRxBngLbXyH4= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Apr 08 01:16:47 2021 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lUHPj-0009Nn-9p for ged-emacs-devel@m.gmane-mx.org; Thu, 08 Apr 2021 01:16:47 +0200 Original-Received: from localhost ([::1]:56906 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lUHPi-0002S1-9y for ged-emacs-devel@m.gmane-mx.org; Wed, 07 Apr 2021 19:16:46 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37622) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lUHP6-0001xh-AA for emacs-devel@gnu.org; Wed, 07 Apr 2021 19:16:08 -0400 Original-Received: from ciao.gmane.io ([116.202.254.214]:37062) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lUHP4-0002q4-QQ for emacs-devel@gnu.org; Wed, 07 Apr 2021 19:16:08 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1lUHP2-0008XY-TT for emacs-devel@gnu.org; Thu, 08 Apr 2021 01:16:04 +0200 X-Injected-Via-Gmane: http://gmane.org/ Received-SPF: pass client-ip=116.202.254.214; envelope-from=ged-emacs-devel@m.gmane-mx.org; helo=ciao.gmane.io X-Spam_score_int: 5 X-Spam_score: 0.5 X-Spam_bar: / X-Spam_report: (0.5 / 5.0 requ) BAYES_00=-1.9, DKIM_ADSP_CUSTOM_MED=0.001, FORGED_GMAIL_RCVD=1, FREEMAIL_FORGED_FROMDOMAIN=0.249, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, NML_ADSP_CUSTOM_MED=0.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:267588 Archived-At: Stefan Kangas writes: >>> Getting Help >>> >>> m Help for current minor and major modes and their commands >> >> Why not "Show help for" like the others? > > Basically to keep it short, and I feel it reads better. I'm not sure > the consistency is overly important here. > > Perhaps we should even remove all instances of "Show", as it is fairly > obvious that help commands will show something. Long ago a technical writer told me of the importance of consistency in technical writing as opposed to other prose writing where redundancy is more of an issue. I agree it's not critically important here and that there are other considerations, but I did want to point the inconsistencies when I saw them. >>> a Search for commands (see also M-x apropos) >>> d Search documentation of functions, variables, and other items >> >> In other places you use the word "help" instead of >> "documentation". I agree "Search documentation" reads >> better than "Search help" but by using a different word it >> suggests to me that it searches differen text than what is >> shown by other help commands. Maybe "Seach help text" would >> be better? > > I see what you're saying, but OTOH "documentation" is the mnemonic for > "d". So I'm not sure what's best here. The mnemonic is a good point. I might go with "help documentation" or "help docstrings". If you don't like either of those, then I'd just leave it as you have it. >>> R Show given manual >> >> For w above you say "a given command" maybe these two >> should match? > > Eli suggested "Show specified command", which I think is okay. I'm not > sure they should match as they are far apart, and IMHO they read a bit > better this way. I prefer the word "specified" too. I don't think their distance makes any difference. I'd used specified in both places. >>> S Find symbol in Info manual for current programming language >> >> With the construction used above for F and K this would >> read: "Show current programming language manual section for >> symbol" If that's too long, perhaps those commands should >> use this construction with "Find..." > > Hmm. I'm not sure we need the consistency, as the "Show" implies that > exactly what you're looking for will always be there: The Emacs Manual > won't go anywhere. It won't, but what you're looking for may not be in it. > Whereas "Find" implies that we must first see if there even exists any > documentation for this particular symbol/identifier/name. I may be wrong, but I think these commands behave the same way, the difference is in which manuals are checked. >>> Misc Help >>> >>> p Search for packages matching topic >>> P Describe Emacs Lisp package >>> e Show recent messages >> >> I'd like to see word the "echo" in here as the mnemonic. Perhaps >> "Show recent messages from the echo area" or "Show recently >> echoed messages" > > It basically becomes a decision of where to strike the balance between > brevity and mnemonics. > > We have below: > >>> l Show last 300 input keystrokes (lossage) > > So I'd suggest: "Show recent messages (from echo area)" > > It reads better (and faster), I think. I agree. >>> Help Files >>> >>> C-a About Emacs >>> C-c Emacs copying permission (GNU General Public License) >>> C-d Debugging GNU Emacs >> >> The "GNU" seems unnecessary here, particularly compared to >> the other lines. > > The problem is that the license is the "GNU GPL", while the "General > Public License" could refer to anything... I think? Could we just use > "GNU GPL"? Perhaps Richard has something to add? I was just referring to it use in "Debugging GNU Emacs". I think that should be "Debugging Emacs". The "GNU" should stay in "(GNU General Public License)" and also in the warranty description. > Thanks a lot for these detailed comments. Thanks for your work on this. > This is all very subjective, so please bare with me as I'm trying to > take into account all the comments and work out a coherent whole. Yes and please take my comments as just one person's opinion. -- Howard