From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Boruch Baum Newsgroups: gmane.emacs.bugs Subject: bug#40773: newsticker documentation Date: Wed, 29 Apr 2020 05:12:13 -0400 Message-ID: <20200429091213.rtyoo537qgccbccz@E15-2016.optimum.net> References: <20200422155528.ccsjljhamqeaocsd@E15-2016.optimum.net> <87h7x33ggs.fsf@panama> <20200429041745.srdhgypy5v27e3mv@E15-2016.optimum.net> <838sie205k.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="19301"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: NeoMutt/20180716 Cc: 40773@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Apr 29 11:13:46 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1jTimm-0004sd-1q for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 29 Apr 2020 11:13:44 +0200 Original-Received: from localhost ([::1]:56240 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jTimk-0002rp-L1 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 29 Apr 2020 05:13:42 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60102) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jTim7-0002rT-CX for bug-gnu-emacs@gnu.org; Wed, 29 Apr 2020 05:13:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jTim6-0001qo-PD for bug-gnu-emacs@gnu.org; Wed, 29 Apr 2020 05:13:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:59115) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jTim6-0001qj-DL for bug-gnu-emacs@gnu.org; Wed, 29 Apr 2020 05:13:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jTim6-0005oH-9W for bug-gnu-emacs@gnu.org; Wed, 29 Apr 2020 05:13:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Boruch Baum Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 29 Apr 2020 09:13:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 40773 X-GNU-PR-Package: emacs Original-Received: via spool by 40773-submit@debbugs.gnu.org id=B40773.158815154522290 (code B ref 40773); Wed, 29 Apr 2020 09:13:02 +0000 Original-Received: (at 40773) by debbugs.gnu.org; 29 Apr 2020 09:12:25 +0000 Original-Received: from localhost ([127.0.0.1]:42428 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jTilV-0005nS-DH for submit@debbugs.gnu.org; Wed, 29 Apr 2020 05:12:25 -0400 Original-Received: from mout.gmx.net ([212.227.17.21]:35345) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jTilT-0005nD-CL for 40773@debbugs.gnu.org; Wed, 29 Apr 2020 05:12:23 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1588151536; bh=niJuYJUjlQgOkO5d1SJzA00+d7dOIfwOVWDlGXAUQzw=; h=X-UI-Sender-Class:Date:From:To:Cc:Subject:References:In-Reply-To; b=BQ57e4sRlYKRoW7Xq4QTNPaW2fx/Pd+mWW7Tt8Tolba6aTcpQ2QciBf5ACNVApeLl Nm5TLT2jK2QGB6i0rbkuk9zpT6OgGVxf4vNyPIn5VIBd6TSWfyhu+0otbVKDUqXKsz g60GF2NZEdGh0biKLxovKeDWoutSZhGdoW9rpu6E= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from E15-2016.optimum.net ([100.38.74.74]) by mail.gmx.com (mrgmx104 [212.227.17.174]) with ESMTPSA (Nemesis) id 1MWici-1jei9w1ZWq-00X1Qq; Wed, 29 Apr 2020 11:12:16 +0200 Content-Disposition: inline In-Reply-To: <838sie205k.fsf@gnu.org> X-Provags-ID: V03:K1:j+W8aNLtU6jRpRR5yzlrgpyfpa3fDmUUbcCKdN19lyOrY4DO7J1 LcGhgNA+H9MRBOdDjtFijhc3LL12YPEJVt+VuGfCL3PGVSDsRsQYhMDK4wfBGJS8BtSCl9R kdINiyR9uTZTAvCNJ6AqineXoR13sJEs5DP+39txqWy2Zj22RMaO1ELEv1bVG8Vaea4/q7f 7ygbZImQAoyQ9jvo7cxpg== X-UI-Out-Filterresults: notjunk:1;V03:K0:8dZYJHC6kuA=:YVkyVv9TmWvswb0QtMGXFe wOFCZQmxIeI6Koanq8bK/Z24zhckkiFU0oJEXdrq7qReVzaACtUue0BYK2jdXekiwFBwFCZAG gz3JGrTCCav5bda/Hap/WasYcFszUpcoFGCi92q3xctq3oTe2ZTL5blEXSSZeW2uoFsbWy9Nd 1IPFdd642mhJr1GUEkIbO0R1dawu+3UXHuYOCsy5cZZRu2nf/KZDoXiHmbktYur0HbZLhpeg6 uixq7ULcgLUfEyzIXgofiR8udUTfgX59+fMv/jb49j6ZilRsoO5hiu0p8iLaSDsX/BLlnSboX HRf/jNjm27agxqGJACE75uOVG68x5bF9Gw6rjirn4XE/w9+9N/sObPP7U3Fx6JUuJNet41yyn la4MR2cip2ml1vS1r2aWNKcap+eT14W2w77hWgeldf04sluMNN9Dqn4PX5Yk24dqcoUQe8uZe CjRF8Gm7+iqLiInt7mOdUTxEPdGMwTliLE31yTHtMlAExpyW5r7MgjfjWkwO+kmrH1BFzrntl dZiNOMmqj2vlL0nKvcAqKSb7xJEPzPJEHa3e5ZVlDONfBKA/RbyAk9xTSqGy4ybkY8yE0jh4n TV420x8/O/jIuZAuskhLqalfl09HNVvAW1YGacfVjuNr8QjwfVBTfxwgDdJj2VamM8ZfhrE0P YUy6IVUea6JcuT8xyhvRcobleiiEyOKOChCHaAfbnC4Gjp+ZMj2zbY9yGzekgATo9iMe7P9ql P+aQUSWboJI3yEhia6BuZF8hwGfwVEOLbRKX6qIunzIkMdCQzrCdnvJAWEYe4/SO5T3IuBfY X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:179293 Archived-At: On 2020-04-29 10:58, Eli Zaretskii wrote: > I'm sorry, but that's impractical. Impractical? Step back and re-read what you wrote: > Emacs comes with 58 manuals (and 2 FAQ files in Info format) in > addition to the 3 "standard" ones. That's practical? Certainly not from a user's perspective. My guess is that it's by far a world record for the number of manuals for a single package. I understand the evolutionary circumstances that led to the situation, but it's not intelligent design (bump). > We mention the most important of them in the Emacs manual, but we > cannot possible mention all of them. Why not? It's --only-- 58. They likely don't change very often. After the initial work, which I'm guessing will amount 58 text lines in a single .texi file (is that how it works?), how often will it need to be changed? > Gnus is so much larger and more important than newsticker that any > comparison of how we treat these two is IMO not useful for any > practical discussion. That attitude prejudices newsticker into guaranteed obscurity, when the developer attitude should be to promote and advertise. > Users should become acquainted with the info-display-manual command, > and use it whenever they find a package that may have a separate > manual. That sounds reasonable for info manuals of packages that aren't part of emacs. For such packages, because they are external, there is sense to keeping their associated info manuals external, if only as a quality measure since the emacs project can't dictate the editorial standards of those documents. Even so, it's not user-friendly to force all users to go through a two-step process to find a manual. And... If you feel strongly about the utility of the info-display-manual command, that command should have a keybinding by default and should appear in the output of the help-for-help command (C-h ?). > That command offers completion, so it will tell you very quickly > whether a given package has an Info manual. I pseudo-randomly tried and failed to find: emerge, calendar, diary, latex. Some time ago, maybe years ago, I pointed out in another bug report that package cua-rect-mode, which seemed to have powerful and useful features, lacked documentation, so I tried it also. Still nothing. At the very least, if even just a basic small documentation stub exists in a centralized single emacs manual, it: 1] becomes a launch point for expansion; 2] rescues a package from obscurity. > Another useful command in this context is "C-h p". E.g., select > "news" from the menu this displays, then select "newsticker", and you > will see some useful description of the package and its usage. Yep. It is very useful, but now we're up to a three-step process: `C-h r',= `M-x info-display-manual', and `C-h p'. > > Further, as a corollary, I suggest that packages bundled in the defaul= t > > emacs distribution should NOT have info nodes in the emacs section of > > the root info index, ie. no duplication. Either the emacs section of t= he > > root info index should be restricted to non-default emacs packages, or > > there shouldn't exist such a section at all, and the emacs manual shou= ld > > have a section for external packages. > > I don't think I understand what you propose here. What is "the root > info index"? is that the Emacs menu in the DIR file That sounds right. I meant what I see when I type `C-h i'. =2D- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0