Re: doc-base is hugely unloved; bug mass-filing needed?
On Sat, Aug 07, 2010 at 10:56:23AM -0700, Ian Zimmerman wrote:
> After years and years of waiting for packages to register their
> documents with doc-base, and filing individual bugs with some (not all
> -- I am not jidani, LOL) of those that didn't register, I am quite
> frustrated:
> [41]matica:doc$ pwd
> /usr/share/doc
> [42]matica:doc$ find -L . -name "*.html" -o -name "*.htm" \
> -o -name "*.pdf" -o -name "*.pdf.gz" | cut -d/ -f2 | sort | uniq | wc -l
> 273
> [43]matica:doc$ find -L . -name "*.html" -o -name "*.htm" \
> -o -name "*.pdf" -o -name "*.pdf.gz" | cut -d/ -f2 | sort |\
> uniq | while read p ; do if ! [ -e "/usr/share/doc-base/$p" ] ;\
> then echo "$p" ; fi ; done | wc -l
> 203
> So, out of 273 doc-containing packages on this system, just 70 bothered.
> I feel a strong urge to put the commands in a script that will auto-file
> a bug against any package in the output of the last command. How do
> maintainers feel about that?
This should only be a mass bug filing if you're going to provide patches for
each of the affected packages. Filing bugs telling maintainers to draft
doc-base install files is about as useful as filing bugs telling maintainers
to write manpages.
Actually, it's significantly less useful - most developers use manpages, but
I can't remember the last time I used the doc-base infrastructure to browse
documentation. Contrary to the concerns expressed up-list, my understanding
is that doc-base does integrate with scrollkeeper, which means the docs are
available under both GNOME and KDE desktop help interfaces; but on
non-desktop systems, I don't think we install a doc-base browser by default,
and I have never seen a text-mode browser for doc-base documentation that I
found worth using because browsing to /usr/share/doc/$package is always
quicker. Unless you find a way to make doc-base compelling enough that
developers will actually dogfood it when they want documentation, I think
package coverage here is always going to be rather poor.
(Also, I just tried to use yelp on Ubuntu 10.04 to test out the user
experience of looking for documentation provided by doc-base... Despite
having rarian-compat and doc-base properly installed, and despite doc-base
being an unmodified Debian package, *none* of the doc-base documentation
appears to turn up when I search. Assuming this isn't an Ubuntu-specific
bug, I think it needs to be fixed before you can expect much maintainer
interest in providing new doc-base files.
Cheers,
--
Steve Langasek Give me a lever long enough and a Free OS
Debian Developer to set it on, and I can move the world.
Ubuntu Developer http://www.debian.org/
slangasek@ubuntu.com vorlon@debian.org
Reply to: