post about doc-base
authorStefano Zacchiroli <zack@upsilon.cc>
Sun, 2 Mar 2008 15:57:14 +0000 (16:57 +0100)
committerStefano Zacchiroli <zack@upsilon.cc>
Sun, 2 Mar 2008 15:57:14 +0000 (16:57 +0100)
blog/archives/2008/03.mdwn [new file with mode: 0644]
blog/posts/2008/03.mdwn [new file with mode: 0644]
blog/posts/2008/03/indeed_we_should_use_doc-base_more.mdwn [new file with mode: 0644]

diff --git a/blog/archives/2008/03.mdwn b/blog/archives/2008/03.mdwn
new file mode 100644 (file)
index 0000000..fb97892
--- /dev/null
@@ -0,0 +1 @@
+[[template id=archive_month year="2008" month="03"]]
diff --git a/blog/posts/2008/03.mdwn b/blog/posts/2008/03.mdwn
new file mode 100644 (file)
index 0000000..28b1342
--- /dev/null
@@ -0,0 +1 @@
+[[meta redir=archives/2008/03]]
diff --git a/blog/posts/2008/03/indeed_we_should_use_doc-base_more.mdwn b/blog/posts/2008/03/indeed_we_should_use_doc-base_more.mdwn
new file mode 100644 (file)
index 0000000..f9b65bc
--- /dev/null
@@ -0,0 +1,31 @@
+# Long live to doc-base
+
+[Runa wonders: «Why aren't we using
+doc-base?»](http://www.indentedlines.net/2008/03/01/why-arent-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 [[debpkg
+doc-base]] entries from OCaml libraries using debpkg ocamldoc, and finally also
+more than 100 doc-base entries shipped by [[debpkg 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 [[debpkg 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.
+
+[[tag lang/english planet/debian debian]]