[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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.

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: