From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.devel Subject: Re: Proposal for an improved `help-for-help' Date: Wed, 7 Apr 2021 17:41:24 -0500 Message-ID: References: <838s7hxqkr.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="2074"; mail-complaints-to="usenet@ciao.gmane.io" To: Howard Melman , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Apr 08 00:42:05 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 1lUGs9-0000QL-Hb for ged-emacs-devel@m.gmane-mx.org; Thu, 08 Apr 2021 00:42:05 +0200 Original-Received: from localhost ([::1]:47368 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lUGs8-0001zU-Go for ged-emacs-devel@m.gmane-mx.org; Wed, 07 Apr 2021 18:42:04 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59198) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lUGra-0001Zx-Iz for emacs-devel@gnu.org; Wed, 07 Apr 2021 18:41:30 -0400 Original-Received: from mail-pl1-x62f.google.com ([2607:f8b0:4864:20::62f]:47076) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lUGrY-0006O9-MG for emacs-devel@gnu.org; Wed, 07 Apr 2021 18:41:30 -0400 Original-Received: by mail-pl1-x62f.google.com with SMTP id t20so10072076plr.13 for ; Wed, 07 Apr 2021 15:41:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:in-reply-to:references:mime-version:date:message-id:subject:to; bh=oIqDymftE6rUaAX8oQ5/2z/1Dp3SFpY2zg9Jgy5rQAo=; b=eZdBOnx1kxBYcUzAlJW8x84OGFGZKWr533rPcw7/UeUlNB8CpwPOKn4r/74hZSZzTy IzLdV9TKVCtEEmFVTn2ZOrqguraIWZRJpRadpSAJDtEL/lpNIrB/UyaN1/9D4A25b5Cp zWI2NmjwmIbBrSDLi0XWIRRiPozskUUDlN+x4JLElott0ScHjQJ9iKBw9dpXASWA2zSQ dZ2NnIrMNH3Um69qCnWRRM1NSocLeUrxPOpr/zkcCWzpcuR2xUyI28W28r3uAQYGGt3L fnhnoxXdoxJwwbjv+n9P35cGvBdyLA1pVRGcz6sTb6sPNsWMIz1X6j5loc9g2soHwruk R18Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:in-reply-to:references:mime-version:date :message-id:subject:to; bh=oIqDymftE6rUaAX8oQ5/2z/1Dp3SFpY2zg9Jgy5rQAo=; b=V4/fJ6VEpy4l9bIm4pA6UBZ1JcmqedGkPVoradrIh2m5AWqbUNcbPXRl278Ywwvi82 +lGkkowB72W1+e/6TLNQVijUMpTaE1MqitvQ4l1/b0anxsR43A7Qq2a2NUKOq+go0mBw JwzjGgUzTNA4RkKVrUVJVRs9ubcOQSJtUKnNJCoAwdE13Acojr0YtXES9g1iIlrQKPdZ 8lD3Yf7rOyNtbDKnWZDl3zPZpLzG8L6jVt0yQWye+T41bIFIkN2pQxE2jbv0KFARI/Ot B412SXxXDdx1eC7bOMtOQPWwZOc70Kr+ExXsE3GWmLEjlm70xwRvpo/hpEnpaTkmKsWM F+KQ== X-Gm-Message-State: AOAM531/NnaeXeJywwvNzDbfXZy8Eqie5rwqZNlEuWIRniBVoA8izjua PbTnWNsh4qPPDbTorHi+hMdwnjvDtWtWpTZ6pcI= X-Google-Smtp-Source: ABdhPJx2uHjzu096QTBKvKtxuiqkFvEz4LvnTTKQQTIZQjcE2dWVp0QcqPa/SniwbZcsGoTHyQZXmYtjmNq9cuXpidE= X-Received: by 2002:a17:902:b093:b029:e8:fc61:f428 with SMTP id p19-20020a170902b093b02900e8fc61f428mr5123187plr.39.1617835285273; Wed, 07 Apr 2021 15:41:25 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Wed, 7 Apr 2021 17:41:24 -0500 In-Reply-To: Received-SPF: pass client-ip=2607:f8b0:4864:20::62f; envelope-from=stefankangas@gmail.com; helo=mail-pl1-x62f.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham 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:267581 Archived-At: Howard Melman writes: > I had missed this and it looks great. I have a few small comments. Thanks! >> 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. > Also I'd say "major and minor" since it shows the major mode first. Fixed. >> 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. >> f Show help for function >> o Show help for function or variable > > I would move this one either above f or below v. It seem > odd to me be to placed between them. Agreed, changed. >> Info Manuals >> >> r Show Emacs manual >> F Show Emacs manual section for command >> K Show Emacs manual section for command bound to key >> i Show all included manuals > > I feel like the word info should be here, as that's the > mnemonic (not "included"). I'm fine with that. (Eli has also pointed out it should say "installed" rather than "included".) >> R Show given manual > > Is this a new function in Emacs 28? I don't see it in Emacs > 27. For w above you say "a given command" maybe these two > should match? I think it's new, yes. 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. >> 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. Whereas "Find" implies that we must first see if there even exists any documentation for this particular symbol/identifier/name. >> 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. >> t Start the Emacs tutorial > > I understand that the tuturial is probably the least used > command here, but I'll make the case that for a new user, > the ones most likely to use C-h C-h, it's perhaps the most > important one. I'd put it first in this section. Sure, why not? My initial concern was that this gives a less prominent place to Emacs packages, but having tested it I think it is perfectly okay this way. >> 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? Thanks a lot for these detailed comments. 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.