transition: prefix_directives
[homepage.git] / blog / posts / 2008 / 03 / indeed_we_should_use_doc-base_more.mdwn
1 # Long live to doc-base
2
3 [Runa wonders: «Why aren't we using
4 doc-base?»](http://www.indentedlines.net/2008/03/01/why-arent-we-using-doc-base/).
5 It's indeed a good question.
6
7 In the past I've pushed for using doc-base in several places, including
8 obviously packages of mine, but also recently generating by default [[!debpkg
9 doc-base]] entries from OCaml libraries using debpkg ocamldoc, and finally also
10 more than 100 doc-base entries shipped by [[!debpkg w3-recs]] alone for the
11 contained W3C recommendations.
12
13 doc-base is based on a good idea, i.e. annotating the doc we ship with metadata
14 so that it can be more easily browsed, and is (potentially) far better than
15 asking our users to dig into `/usr/share/doc/foo`. Still, it is sadly true that
16 in Debian is way underused.
17
18 My best bet at the *reason* is that in the past the tools floating around
19 doc-base were sucky. However, in 2007 some of them has dramatically improved
20 their quality, with the noteworthy example of [[!debpkg dhelp]] which has been
21 rewritten from scratch in Ruby by Esteban Manchado Velázquez closing tens and
22 tens of bugs.
23
24 My *exhortation*: please, maintainers, go back and consider (again, if needed)
25 to register your documentation with doc-base, it is helpful and it does work.
26
27 The next (needed) step for the doc-base world domination will be decoupling its
28 *classification hierarchy* from that of the Debian menu system, keeping the 2
29 bound is nonsense.
30
31 **Update** Runa submitted [[!debbug 469018]]; cool, because I was just going to
32 do that by myself :-)
33
34 [[!tag lang/english planet/debian debian]]