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