This Time Self-Hosted
dark mode light mode Search

Do I have a doc fetish?

I hope not, as it sounds a pretty nasty thing to have, so I’ll just stick with my version, that is that I like documentation because it is a good thing. At least this way I can explain why I spent the whole last night writing DocBook documentation for autoepatch, starting from the reason we have elibtoolize, through the design choice, toward the actual documentation to create new patchsets.

Now of course, the reasons why I like writing documentation are mostly practical, but I suppose I can summarise them in one reason: I cannot tell when I’m going to retire, or even worse to die (which I hope will happen in something like 100 or 120 years), worse because in the latter case I can’t even give suggestions to whoever replaces me. As autoepatch is something that I count will be pretty important for all the developers, I want it to be easy to maintain, and I want to avoid the current situation where Martin (azarah), the main author of libtool eclass, is missing and almost nobody dares to touch it, or document its functionality, even if it’s an important piece of the big puzzle that working autotools represent in Portage.

Luckily thanks to dfa on #gentoo-it, I now know of emacs’s tramp support, that’s lovely to work with from the Mac Book Pro, while sitting on the couch and watching Star Trek Deep Space 9.

Unfortunately, other than writing the documentation of autoepatch, I have quite a few of missing maintainers’ guides that I should have updated or written in the past weeks that are now waiting in my TODO list. I hope I’ll be able to ix most of the in the first weeks of 2007 before resuming my apaid job for good.

Anyway, this post was not only to say that I’m not dead or retired yet and that the reason why I’m writing the documentation is not that I’ll be leaving that soon (instead, I’m not sure whether and when I’ll be retiring, that’s why I want to keep my packages always cleaned up and ready for new maintainers to take them up), but also to tell my Amarok users that are currently using the MTP support, that they risk to lose their functionality.

The reasoning is again the same, Thomas left Gentoo, so libmtp is currently unmaintained in the tree; to make it worse, next Amarok release (1.4.5) will require libmtp 0.1.0 or later, which is not yet in portage. So unless I can find some developer to take up libmtp (hint hint fellows, if you’re a developer and you have an MTP-capable device, I’m looking for you), or somebody is going to send me an MTP device, the libmtp useflag will be missing in the next ebuild version. I really hope to find a solution for this soon.

Comments 4
  1. You seem to be a paranoid (well, a little bit) with a doc fetish, but at least you do good stuff, as opposed to some of devs who are just slacking around (not pointing at anyone here ;>).

  2. It’s the MTP device I recently got was bug-fixed in Amarok SVN, I was hoping that I’d finally have playlist support for it in Linux (or at all, for that matter). Unfortunate, really.

  3. We need to figure out a good way to create self-documenting code, using Doxygen or something along those lines. Perhaps we can stick DocBook into the bash comments somehow? That way the docs will be a lot easier to keep in sync.

  4. I thought about it Donnie, the problem is that if we fill the documentation in the ebuilds we might easily get them out of sync between versions, and there’s a quite big extra overhead on users, for ALSA stuff, I’d probably have 4 times the size of the ebuilds in documentation, to be on the safe side of leaving the ebuilds to someone else.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.