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: Sat, 24 Apr 2021 08:21:49 -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="37656"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Apr 24 15:22:36 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 1laIF1-0009Tz-KG for ged-emacs-devel@m.gmane-mx.org; Sat, 24 Apr 2021 15:22:35 +0200 Original-Received: from localhost ([::1]:59252 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1laIF0-0005CA-Mo for ged-emacs-devel@m.gmane-mx.org; Sat, 24 Apr 2021 09:22:34 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:52666) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1laIEM-0004kq-FU for emacs-devel@gnu.org; Sat, 24 Apr 2021 09:21:54 -0400 Original-Received: from mail-pg1-f172.google.com ([209.85.215.172]:35648) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1laIEK-0002bc-HC; Sat, 24 Apr 2021 09:21:54 -0400 Original-Received: by mail-pg1-f172.google.com with SMTP id q10so37038524pgj.2; Sat, 24 Apr 2021 06:21:50 -0700 (PDT) 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:cc; bh=IibuBQy3hLFTW+am240Pq4T/dcVx87o81kWdHQMaems=; b=QwSvD/0hE8HGGLnv0HNxs5FXYHvmTDqvPPjyxl88Vly+ADLOQcsIOtm+KubUV2ewh5 LUGRF2949vyyy8k+TsDI/IOXOEZOMEGP476PuJtIkvN2pFOEnvH33A4yjGjdJWix/BJs mpPPvwmE0+f/N8LVMcfgzPpJ0rDfCHxMGqesIR5REtHXxdNo9jAo57n9lqczl1cSvcii KW8To+GiL3ylgn56iDwz8fAbL19CiNu8ZE9Rcf6UhFAcu7qpVL0PO17B4cF/ZMGuOwUq VH98XWNMbX5Z5GZZxvw+oNlEVJ/V0LKDcEi7tBC38zL71OAiZsRWyUYAHVHVCGH2xiRq jeBg== X-Gm-Message-State: AOAM532x0lpDsgirTCrUm7HAxujGKLyUDfIBBcBtc2I4tFHwfoNaTDT/ nPTj+sNOECxuOwFBZ9nf1C/34JoKNhEwRa/Opteyk6x8 X-Google-Smtp-Source: ABdhPJyssBRLi6UikPramI9cSS2pMqJL4YIWcvWWQmLR+qGFZEqlxB6BPfTj1+JJsCvxbherGKNYRy0C7quvpsg0KTM= X-Received: by 2002:a63:942:: with SMTP id 63mr8549043pgj.67.1619270509614; Sat, 24 Apr 2021 06:21:49 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sat, 24 Apr 2021 08:21:49 -0500 In-Reply-To: Received-SPF: pass client-ip=209.85.215.172; envelope-from=stefankangas@gmail.com; helo=mail-pg1-f172.google.com X-Spam_score_int: -13 X-Spam_score: -1.4 X-Spam_bar: - X-Spam_report: (-1.4 / 5.0 requ) BAYES_00=-1.9, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, 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:268334 Archived-At: Stefan Kangas writes: > Stefan Kangas writes: > >> Stefan Kangas writes: >> >>> If the general direction here is okay, I will provide a full proposal, >>> including thinking through the order. >> >> Please find attached an updated proposal. >> >> My overarching goal here has been to design this as an _overview_ of >> _important_ and _non-obvious_ information. >> >> This is a summary of the changes: >> >> - Added sections. >> >> - Drastically shortened descriptions of the command. >> >> - Changed ordering to be roughly based on: order of importance, logical >> grouping of related items, and the Emacs manual. >> >> - Removed the indication about which commands will show a prompt. >> [Rationale: I find that information overly pedantic, messy and fully >> redundant; it will either be obvious from context or, at the very >> least, when invoking a given help command.] >> >> I'm not sure what is considered a large attachment these days, so I >> posted a screenshot at some image host: >> >> https://i.imgur.com/Cv67yUN.png >> >> To facilitate the discussion, I have also pasted below the plain text of >> the help buffer. The patch is attached below. > > There have been no further comments here within 4 weeks. > > I intend to finish this up and push this to master in the next couple of > days. Please send any further comments soon, or we will have to > consider them after this lands on master. Thanks in advance. That was 2 weeks ago. Based on the feedback I received at the time, I have now pushed my final version of this patch to master. There is of course still time for further tweaks before Emacs 28. I invite anyone to report bugs in case they can see any opportunities for improving this. (Feel free to CC me if you do as I'm currently not subscribed to the bug list.) Thank you to everyone who contributed to the discussion!