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
