Bug#991668: [RFC] proposal for solving the discoverability problem (eg: eintr.info !)
Package: emacs-common-non-dfsg
Version: 1:27.1+1-2
Severity: normal
Control: affects -1 emacs
Control: owner -1 !
Hi,
I recently became aware that "An Introduction to Programming in Emacs
Lisp" is non-discoverable, to the point that I doubt that any of the
target audience will be able to find it; I think this is something
that is hurting Emacs adoption rate, and there is some overlap between
this RFC and my DebConf17 documentation improvement proposal. Looking
at the existing bugs (what users want), here is what I propose:
1. I think it's worth having a "too long" long description for
bin:emacs (and maybe emacs-nox) that notes the most significant
documentation that new users will need. Eintr.info is one of these,
and I think that that document in particular is essential to
empowering new users, and that without this empowerment, learning
Emacs is a lot of work for a very distant dream. Being able to
keyword or pattern search from apt, or a GUI frontend is invaluable,
and because in Debian we want users to avoid non-free whenever
possible, the manual titles (or keywords) need to be in bin:emacs. I
would assume that it's not needed in emacs-nox, unless blind users
prefer the -nox variant and having the titles (or keywords) in
bin:emacs but not bin:emacs-nox would reduce accessibility for these
users.
2. As for #627434, I'm not sure if a package rename would be best, or
if emacs-common-non-dfsg should "Provide: emacs-doc", and maybe also
create a symlink to /usr/share/doc/emacs-doc. It would be nice if
src:emacs documentation could be more unified, but the maintenance
burden and regression risk of this is higher, so I'm not sure if
proceeding along a "more unified documentation" avenue would be wise.
3. I fully support #893711 with one specific qualifier: I think the
single vs multiple page question should be decided by whichever is a
better source for conversion to ePubs; I suspect this will be the
multiple page variant. On this topic, I still think that ePub is a
superior format to plain HTML, because readers are ubiquitous, and
because it provides a more book-like (yet reflowable) experience with
the option for an ever present table of contents (like PDF, and more
visibly than Info). And of course, this format provides a more
consistent experience across many different types of devices. I may
be biased, but it seems to me that the only advantage of HTML is that
it can be grepped/silversearched/etc; however, desktop indexers
(Tracker, Baloo, Recoll) handle ePub just fine. But I digress...
Other than to say that many (most?) DDs outside of the Python Team
don't seem to know about the alleged consensus of Policy §12.4. Yes
really, I've asked many over the years, but admittedly this is
anecdotal. To be clear, whatever the case, I think that
discoverability for new users should be the focus, because everyone
else knows where to ask, or what to search for...unless we have a
morbid discoverability problem!
4. Now for more experienced users, we also have docbase. Yeah, it has
become optional rather than recommended, but maybe it would be nice to
have?
5. Did I miss anything? Is there any hope of getting these
documentation discoverability fixes into bullseye as a stable-update?
Comments welcome! I am volunteering for this work; however, I cannot
commit to it before October, and I would sincerely appreciate if any
interested parties would ping me at that time. Oh, and of course I'll
submit an MR, subject to Rob's approval :-)
Sincerely,
Nicholas
Reply to: