bug#40773: newsticker documentation

bug#40773: newsticker documentation

[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.

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

bug#40773: newsticker documentation

[Ulf Jasper]

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

bug#40773: newsticker documentation

[Boruch Baum]

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

bug#40773: newsticker documentation

[Eli Zaretskii]

> 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?

bug#40773: newsticker documentation

[Boruch Baum]

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

bug#40773: newsticker documentation

[Eli Zaretskii]

> 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?

bug#40773: newsticker documentation

[Boruch Baum]

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

bug#40773: newsticker documentation

[Boruch Baum]

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

bug#40773: newsticker documentation

[Eli Zaretskii]

> 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.

bug#40773: newsticker documentation

[Boruch Baum]

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

bug#40773: newsticker documentation

[Lars Ingebrigtsen]

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