Subject: Re: bug#40773: newsticker documentation

From: Eli Zaretskii <[email-masked]>
Date: Wed, 29 Apr 2020 10:58:47 +0300

> Date: Wed, 29 Apr 2020 00:18:15 -0400
> From: Boruch Baum <[email-masked]>
> Cc: [email-masked]
> 
> 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?