Long live to doc-base
Runa wonders: «Why aren't we using doc-base?». It's indeed a good question.
In the past I've pushed for using doc-base in several places, including obviously packages of mine, but also recently generating by default doc-base entries from OCaml libraries using debpkg ocamldoc, and finally also more than 100 doc-base entries shipped by w3-recs alone for the contained W3C recommendations.
doc-base is based on a good idea, i.e. annotating the doc we
ship with metadata so that it can be more easily browsed, and is
(potentially) far better than asking our users to dig into
/usr/share/doc/foo
. Still, it is sadly true that in
Debian is way underused.
My best bet at the reason is that in the past the tools floating around doc-base were sucky. However, in 2007 some of them has dramatically improved their quality, with the noteworthy example of dhelp which has been rewritten from scratch in Ruby by Esteban Manchado Velázquez closing tens and tens of bugs.
My exhortation: please, maintainers, go back and consider (again, if needed) to register your documentation with doc-base, it is helpful and it does work.
The next (needed) step for the doc-base world domination will be decoupling its classification hierarchy from that of the Debian menu system, keeping the 2 bound is nonsense.
Update Runa submitted Debian bug #469018; cool, because I was just going to do that by myself