* bug#40773: newsticker documentation @ 2020-04-22 15:55 Boruch Baum 2020-04-28 13:08 ` Ulf Jasper 0 siblings, 1 reply; 11+ messages in thread From: Boruch Baum @ 2020-04-22 15:55 UTC (permalink / raw) To: 40773 I just discovered the existence of `newsticker' bundled into emacs; however, I see not even a cursory mention of it in the emacs manual. At the very least, there should be a short stub entry in the emacs manual, next to the index entry for * Gnus:: A flexible mail and news reader. BTW: I'm finding newsticker frustrating, unintuitive, not honoring its own customization commands without restart, and not intuitively stopping itself upon 'quit'. If this package is meant to be a supported part of emacs, let me know, and when I make a second attempt at using it, I can compose a few bug reports. -- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-22 15:55 bug#40773: newsticker documentation Boruch Baum @ 2020-04-28 13:08 ` Ulf Jasper 2020-04-29 4:18 ` Boruch Baum 0 siblings, 1 reply; 11+ messages in thread From: Ulf Jasper @ 2020-04-28 13:08 UTC (permalink / raw) To: Boruch Baum; +Cc: 40773 Am 22.04.2020 um 11:55 (-0400) schrieb Boruch Baum: > I just discovered the existence of `newsticker' bundled into emacs; > however, I see not even a cursory mention of it in the emacs manual. At > the very least, there should be a short stub entry in the emacs manual, > next to the index entry for > > * Gnus:: A flexible mail and news reader. You should find newsticker documentation in its own manual: * Newsticker: (newsticker). A feed reader for Emacs. > BTW: I'm finding newsticker frustrating, unintuitive, not honoring > its own customization commands without restart, and not intuitively > stopping itself upon 'quit'. If this package is meant to be a supported > part of emacs, let me know, and when I make a second attempt at using > it, I can compose a few bug reports. newsticker still is part of Emacs, so please go ahead, compose bug reports. Regards, ulf ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-28 13:08 ` Ulf Jasper @ 2020-04-29 4:18 ` Boruch Baum 2020-04-29 7:58 ` Eli Zaretskii 0 siblings, 1 reply; 11+ messages in thread From: Boruch Baum @ 2020-04-29 4:18 UTC (permalink / raw) To: Ulf Jasper; +Cc: 40773 On 2020-04-28 15:08, Ulf Jasper wrote: > Am 22.04.2020 um 11:55 (-0400) schrieb Boruch Baum: > > I just discovered the existence of `newsticker' bundled into emacs; > > however, I see not even a cursory mention of it in the emacs manual. At > > the very least, there should be a short stub entry in the emacs manual, > > next to the index entry for > > > > * Gnus:: A flexible mail and news reader. > > You should find newsticker documentation in its own manual: > > * Newsticker: (newsticker). A feed reader for Emacs. That's great, but the point of my report is that there should be a reference to it in the emacs manual, and that reference should be alongside similar emacs packages (eg. gnus). It's not intuitive to check outside of the emacs manual from inside emacs. A user (ahem, me) discovers newsticker in emacs, and by habit looks for it by instinctively typing C-h R. I can understand the situation needs to be different for emacs-related packages that are not bundled into emacs itself and aren't 'part of emacs', but for packages that have become part of the default emacs distribution, the documentation should be withing the emacs manual. IMO, that should be the standard behavior for all similar packages. Further, as a corollary, I suggest that packages bundled in the default emacs distribution should NOT have info nodes in the emacs section of the root info index, ie. no duplication. Either the emacs section of the 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 should have a section for external packages. -- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-29 4:18 ` Boruch Baum @ 2020-04-29 7:58 ` Eli Zaretskii 2020-04-29 9:12 ` Boruch Baum 2022-02-07 1:19 ` Lars Ingebrigtsen 0 siblings, 2 replies; 11+ messages in thread From: Eli Zaretskii @ 2020-04-29 7:58 UTC (permalink / raw) To: Boruch Baum; +Cc: 40773 > Date: Wed, 29 Apr 2020 00:18:15 -0400 > From: Boruch Baum <boruch_baum@gmx.com> > Cc: 40773@debbugs.gnu.org > > On 2020-04-28 15:08, Ulf Jasper wrote: > > Am 22.04.2020 um 11:55 (-0400) schrieb Boruch Baum: > > > I just discovered the existence of `newsticker' bundled into emacs; > > > however, I see not even a cursory mention of it in the emacs manual. At > > > the very least, there should be a short stub entry in the emacs manual, > > > next to the index entry for > > > > > > * Gnus:: A flexible mail and news reader. > > > > You should find newsticker documentation in its own manual: > > > > * Newsticker: (newsticker). A feed reader for Emacs. > > That's great, but the point of my report is that there should be a > reference to it in the emacs manual, and that reference should be > alongside similar emacs packages (eg. gnus). I'm sorry, but that's impractical. Emacs comes with 58 manuals (and 2 FAQ files in Info format) in addition to the 3 "standard" ones. We mention the most important of them in the Emacs manual, but we cannot possible mention all of them. 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. 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 command offers completion, so it will tell you very quickly whether a given package has an Info manual. 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. > Further, as a corollary, I suggest that packages bundled in the default > emacs distribution should NOT have info nodes in the emacs section of > the root info index, ie. no duplication. Either the emacs section of the > 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 should > 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, or is that the top-level menu in the emacs.info file? ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-29 7:58 ` Eli Zaretskii @ 2020-04-29 9:12 ` Boruch Baum 2020-04-29 9:34 ` Eli Zaretskii 2022-02-07 1:19 ` Lars Ingebrigtsen 1 sibling, 1 reply; 11+ messages in thread From: Boruch Baum @ 2020-04-29 9:12 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 40773 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 default > > emacs distribution should NOT have info nodes in the emacs section of > > the root info index, ie. no duplication. Either the emacs section of the > > 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 should > > 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'. -- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-29 9:12 ` Boruch Baum @ 2020-04-29 9:34 ` Eli Zaretskii 2020-04-29 18:55 ` Boruch Baum 2020-04-29 19:13 ` Boruch Baum 0 siblings, 2 replies; 11+ messages in thread From: Eli Zaretskii @ 2020-04-29 9:34 UTC (permalink / raw) To: Boruch Baum; +Cc: 40773 > Date: Wed, 29 Apr 2020 05:12:13 -0400 > From: Boruch Baum <boruch_baum@gmx.com> > Cc: ulf.jasper@web.de, 40773@debbugs.gnu.org > > > 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? I don't think a single line for a package will do. Compare with the descriptions we do have for the manuals we do mention in the Emacs manual. > > > Further, as a corollary, I suggest that packages bundled in the default > > > emacs distribution should NOT have info nodes in the emacs section of > > > the root info index, ie. no duplication. Either the emacs section of the > > > 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 should > > > 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'. Then I don't understand the rationale for removing the entries from there. What useful purpose would that serve? ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-29 9:34 ` Eli Zaretskii @ 2020-04-29 18:55 ` Boruch Baum 2020-04-29 19:14 ` Eli Zaretskii 2020-04-29 19:13 ` Boruch Baum 1 sibling, 1 reply; 11+ messages in thread From: Boruch Baum @ 2020-04-29 18:55 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 40773 On 2020-04-29 12:34, Eli Zaretskii wrote: > > Date: Wed, 29 Apr 2020 05:12:13 -0400 > > > > Further, as a corollary, I suggest that packages bundled in the default > > > > emacs distribution should NOT have info nodes in the emacs section of > > > > the root info index, ie. no duplication. Either the emacs section of the > > > > 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 should > > > > 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'. > > Then I don't understand the rationale for removing the entries from > there. What useful purpose would that serve? It manages and guides users' expectations. Emacs should have a single authoritative manual, and users should feel confident that they can turn to a single place for the comprehensive documentation. When you partially duplicate components in a second place, you confuse beginner users as to where to turn for documentation. If it were up to me, the entire Emacs section for M-x info would have just three entries: Emacs * The emacs manual All the features of the default emacs * Your emacs extensions Docs for the add-ons you've installed * Other emacs help Ways to quickly find information The third entry would point to content similar to what is displayed by M-x help-for-help (C-h ?), but also mentioning M-x info-display-manual, and whatever other constructive input gets suggested. -- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-29 18:55 ` Boruch Baum @ 2020-04-29 19:14 ` Eli Zaretskii 2020-04-29 19:25 ` Boruch Baum 0 siblings, 1 reply; 11+ messages in thread From: Eli Zaretskii @ 2020-04-29 19:14 UTC (permalink / raw) To: Boruch Baum; +Cc: 40773 > Date: Wed, 29 Apr 2020 14:55:54 -0400 > From: Boruch Baum <boruch_baum@gmx.com> > Cc: ulf.jasper@web.de, 40773@debbugs.gnu.org > > > Then I don't understand the rationale for removing the entries from > > there. What useful purpose would that serve? > > It manages and guides users' expectations. Emacs should have a single > authoritative manual, and users should feel confident that they can turn > to a single place for the comprehensive documentation. When you > partially duplicate components in a second place, you confuse beginner > users as to where to turn for documentation. > > If it were up to me, the entire Emacs section for M-x info would have just > three entries: > > Emacs > * The emacs manual All the features of the default emacs > * Your emacs extensions Docs for the add-ons you've installed > * Other emacs help Ways to quickly find information What you describe is very different from how the Info system is supposed to be used. We have commands like info-apropos and info-display-manual and info-lookup to free us from the need to browse the top-level Info directory menu. That's because starting from DIR implies a top-down search for what you want, and that is very inefficient. The DIR node also tends to be very large if you have many manuals installed. For example, installing GNU Coreutils will cause DIR to have an entry for every command in that package, and installing glibc will have an entry for every standard C library function there. That's why Info have commands to land you where you want to be, either directly or in a very small number of steps. Basically, an efficient use of Info should cause you to seldom if ever look at DIR; I don't remember when I last looked at it on my system, and I use Info every day. DIR exists to help Info commands find what I'm looking for, not for me to read through it, certainly not frequently. So maybe we should improve the Info commands and the databases they use to make the various packages described in separate manuals more discoverable, but the specific measures you propose look to me like steps in the wrong direction. ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-29 19:14 ` Eli Zaretskii @ 2020-04-29 19:25 ` Boruch Baum 0 siblings, 0 replies; 11+ messages in thread From: Boruch Baum @ 2020-04-29 19:25 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 40773 On 2020-04-29 22:14, Eli Zaretskii wrote: > > Date: Wed, 29 Apr 2020 14:55:54 -0400 > > What you describe is very different from how the Info system is > supposed to be used. No, I'm not making any suggestion how it should be used. Continue to use all the tools you already use. I'm just suggesting how to organize the document, as a book that can be read and browsed through. This brings us back to the initial purpose of this bug report: A person encountering a subject (eg. gnus) should easily see 'nearby' whether similar features exist (eg. newsticker), both part of default emacs. -- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-29 9:34 ` Eli Zaretskii 2020-04-29 18:55 ` Boruch Baum @ 2020-04-29 19:13 ` Boruch Baum 1 sibling, 0 replies; 11+ messages in thread From: Boruch Baum @ 2020-04-29 19:13 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 40773 On 2020-04-29 12:34, Eli Zaretskii wrote: > Then I don't understand the rationale for removing the entries from > there. What useful purpose would that serve? I hit 'send' too soon; no corrections necessary, but some additional comments follow... 1] The section for emacs add-ons should make clear that for features FSF/GNU/emacs has no control over the content and its licensing, can't be depended to offer support, and whatever mumble mumble lawyers insist on including. 2] The proposal neatly divides default emacs from extensions, and is a nice solution, but it is 'lazy' and 'easy' at the expense of trying to provide a single integrated manual that organizes ALL components of any single user's individual emacs by related subject. This more difficult alternative would be a cross between an info index page and the output of M-x info-display-manual. In that case, the root info page would just have a single entry for emacs, maybe even not justifying a separate section labeled emacs. -- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#40773: newsticker documentation 2020-04-29 7:58 ` Eli Zaretskii 2020-04-29 9:12 ` Boruch Baum @ 2022-02-07 1:19 ` Lars Ingebrigtsen 1 sibling, 0 replies; 11+ messages in thread From: Lars Ingebrigtsen @ 2022-02-07 1:19 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Boruch Baum, 40773 Eli Zaretskii <eliz@gnu.org> writes: >> That's great, but the point of my report is that there should be a >> reference to it in the emacs manual, and that reference should be >> alongside similar emacs packages (eg. gnus). > > I'm sorry, but that's impractical. Emacs comes with 58 manuals (and 2 > FAQ files in Info format) in addition to the 3 "standard" ones. So the conclusion here is that we don't want to add this to the Emacs manual, and I'm therefore closing this bug report. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2022-02-07 1:19 UTC | newest] Thread overview: 11+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2020-04-22 15:55 bug#40773: newsticker documentation Boruch Baum 2020-04-28 13:08 ` Ulf Jasper 2020-04-29 4:18 ` Boruch Baum 2020-04-29 7:58 ` Eli Zaretskii 2020-04-29 9:12 ` Boruch Baum 2020-04-29 9:34 ` Eli Zaretskii 2020-04-29 18:55 ` Boruch Baum 2020-04-29 19:14 ` Eli Zaretskii 2020-04-29 19:25 ` Boruch Baum 2020-04-29 19:13 ` Boruch Baum 2022-02-07 1:19 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).