HCoder.org

After a couple of (unrelated) recent events, I remembered that some/most people use some desktop “word processor” for writing and maintaining documentation. After years of working with Wikis for virtually all documentation, I have to say that I don’t understand why people still use those dinosaurs. Using a word processor for documentation feels so nineties.

When working in technical teams, I think the advantages of the Wikis are amazing:

1. You know you’re always reading/modifying the latest version. Uploading to a central server or a shared folder, although theoretically possible (and I’m sure some people do), I don’t think it works as well.
2. You can link all content to any other content (and if you keep all your documentation in the same Wiki, you can link to other project documentation or general company/team guidelines or conventions, for example).
3. You can keep bits of documentation that don’t fit in a standalone “document”, like collections of small tips, lists of things to take into account when you do this or that, checklists, configuration/code snippets and examples, journals, etc. And of course link all that to any other part of the documentation, as stated above.
4. You think “globally”, in terms of the content, not in terms of “documents” that are (usually artificially) independent from each other. Also, it’s mentally cheaper to browse through wiki pages than it is to browse word processor documents, so the documentation is more visible and more used.
5. You focus on content, not on formatting or the way things are presented. It’s also easier to keep the same consistent look and feel for all your documentation, if you wanted to change it.
6. As you don’t have “documents”, just “documentation”, people feel free to edit and update it whenever is necessary, instead of feeling the need to ask the “author” of each document.
7. You don’t need any special program that might not be available in all platforms, or at least not interpret the document in exactly the same way. It’s also easier to access it from other computers.
8. Documents don’t get lost or become obsolete because of the format.
9. You usually get revision control for free (revision control that makes it trivial to see the whole change history for the documentation, review which exact changes some person has made in a given moment, etc). And if you’re using a Wiki that doesn’t support version control, you should use a different Wiki ;-)

Of course, I’m not saying Wikis are the perfect solution, let alone independently of the team, company, project and context you’re using them in, but I think in general they are quite superior as technical documentation repository for a software development team.

I have always thought that systems should be something integrated. Each “system” has its own conventions, cultural values, etc. and I think you have to respect that. I believe in the Debian way (adapting programs to an integrated system, not just creating a large collection of packages that are identical to the upstream versions), I like to adapt my style of programming to the language (indentation conventions, identifiers, tools for building and testing, etc.), I prefer cross-platform applications that look and feel like each platform they run on, etc.

In the same way, I feel that the mere idea of having a programming-language-dependent packaging system is a broken idea. I know it has advantages, and I know that being specific to the language, some things work better or are more flexible, but I just don’t believe in that idea. Why should I use a different packaging system for certain things just because they’re written in Ruby? Why do I, as a user of those programs/modules, even have to know that there’s some Ruby-specific packaging system, that doesn’t integrate at all with my system’s packaging system, and mixing both leads to a mess?

Not only that, but Rubygems in particular is quite hostile to repackaging into a platform-specific packaging system. A lot of people only provide the gems for their software, which are harder to work with than “normal” tarballs. They also use their own conventions for directories, that break the FHS (for example) and basically only make sense in the context of Rubygems. In that sense, CPAN is much better (although I think using it for application deployment is a very bad idea, but that’s a different matter), because at least it installs everything in sane directories, it doesn’t change Perl in any way, and it’s not a special format, just a repository of easy-to-install, easy-to-work-with, easy-to-hack, easy-to-repackage “distributions”.

Why, oh, why?

Today I was playing with GnuPG, trying to add a couple of public keys to an “external” keyring (some random file, not my own keyring). Why? you ask. Well, I was preparing some Debian package containing GPG keys for APT repository signing (like debian-archive-keyring and such).

The point is, I was really confused for quite a bit because, after reading the gpg manpage, I was trying things like:

gpg --no-default-keyring --keyring keys.gpg --import ...     # Wrong!

But that wouldn’t add anything to the keys.gpg, which I swear I had in the current directory. After a lot of wondering, I realised that gpg interprets paths for keyrings as relative to… ~/.gnupg, not the current directory. I guess it’s because of security reasons, but I find it really confusing.

The lesson learned, always use --keyring ./keys.gpg or, better, never use keys.gpg as filename for external keyrings, but something more explicit and “non-standard” like my-archive-keyring.gpg or whatever.

The other day I was talking about upgrading Typo. The update itself went well, true, and the site was up and running without too much downtime, but then I started using it again… and I have noticed two things so far (both about writing posts) that I really dislike:

First, the good old editor is not there anymore: the Typo editor used to be really good, because on the left hand side you had a very reliable and easy to use textarea with Wiki syntax (you can choose which exact syntax you want), and on the right hand side you had a “live preview” of your post, automatically updated with Ajax, that showed you how the post was going to look like. Well, that’s gone. Now there are two options: some retarded WYSIWYG box, that I tried to use and failed, and some good old textarea… without the damn live preview. That sucks big time, because there is no other preview (that I have seen: please enlighten me if there is indeed one), so I just blindly write things in a Wiki format, and hope that it’s going to look OK when I press “Publish”.

Second, I was playing with the Wiki format for the articles, and I changed it to “Markdown” (I always mix “Textile” with “Markdown”, and never remember which is which; the one I prefer is Textile). After I hit “Save”, not only the next article was parsed in Markdown format by default, but every single blog post. It’s like, you select the parser the system is going to use to interpret your whole blog. How retarded is that? Once you have written posts, it doesn’t make sense to change their syntax (unless you do it manually editing the post itself). Clearly the format is a property of each blog post, not of the whole blog installation.

Not everything is bad though: it seems that now you finally have a “Draft” concept, so I can start writing a blog post and just save as a draft, instead of unticking the “Online” property and saving as a normal post. Also, the drafts are saved automatically, so I don’t have to remember to hit “Save” from time to time just in case the browser crashes or I hit something stupid and erase the contents of the post. Yay for that.

In my recent trip to Copenhagen, I recorded a small video of the subway (it’s really cool, because it’s completely automatic, it doesn’t have drivers or anything). I wanted to edit the video to remove people that were reflected on the window, so I wondered if I could do that on Linux. I imagined it wouldn’t be trivial, but it was more frustrating than I thought. Maybe I’m too old for this.

The first thing I tried was looking in APT’s cache for “video editing”. The most promising was kino. I had tried that some time ago a couple of times, and I never made it to work, but I figured I would try again. Unfortunately, same result: I just can’t figure out how to import my videos. Maybe I’m just hitting the wrong button or whatever, but it’s really frustrating.

Second thing was having a look in the internet. I found the (dead and being rewritten?) Cinelerra, as always, and I didn’t feel like installing the old one from source, only to lose my time and not get it to work, so I just ignored it. Maybe they had it in debian-multimedia and wouldn’t have been a tough install after all. Anyway.

Next thing, I found some program called openmovieeditor. This one apparently worked, but I couldn’t figure out how to crop the image (or almost any other thing for that matter).

Next, some neat program written in Python, called pitivi. When I tried to run it though, it just said Error: Icon 'misc' not present in theme on the console and died. I later figured out that I had to install gnome-icon-theme for it to work (yeah, Debian maintainer’s fault). It’s funny, because on the webpage it says that it has some “advanced view” that you can access via the “View” menu… but I couldn’t find it. My menu only had one entry: “Fullscreen”. Great.

Oh, wait, there’s a gimp-gap. I could just import my animation in Gimp, crop the frames, and convert again to video. Easier said than done. I needed some programs that I didn’t have, and I wasn’t sure if they were so easy/quick/clean to install (sure, I could have exported to GIF animation and probably convert to video, I just didn’t want to lose so much color quality in the GIF step). Forget for now. At least I had the images, so if I could just turn them into a movie…

So, I started wondering if, given that I had decided to just crop, and especially now that I had a lot of images that were the frames, maybe I could just use some command line tool or something. So I found this tiny little program, images2mpg. Long story short, after installing some dependencies from source (that gave compilation errors, but luckily I could compile only the binaries I really needed) that program was completely retarded and didn’t even do what I wanted (it wanted at least one second between images, but I didn’t want a slideshow, just a normal movie from the frames). It looks some simple and it’s so buggy. Gah.

So I started wondering if I could just crop with mplayer... Hmmm… after a couple of problems (like documented switches that were not there and other crap), I ended up with this command line:

mencoder -vf crop=320:200:0:40 MVI_2160.AVI \
         -ovc lavc -nosound -o metro-crop.avi

That was reasonably quick and easy but it was so frustrating after all that lost time.

In any case, I ended up with the video I wanted, so I went to YouTube to upload it. When uploading, I realised that there was some option I had never seen: annotations.

YouTube annotations are really cool. They are like the notes on Flickr, but on a video :-D Actually I kind of wanted to make a note like that on this video, to show the automatic doors on the Metro station, so I was really happy to see that I could actually do it. And the interface is really easy to use and very clear. I really like it! You can see the result here:

EDIT: WTF? The annotations don’t appear on the embedded videos? You’ll have to go to the video page to see them, then…

So, today I was working normally, and suddenly I mispress something… and I can’t switch to other desktops anymore.

First thing I think: maybe some KDE global shortcut manager or whatever went nuts, and redefined my “Switch to Desktop” keys. So I go and check the preferences, and I find that everything is alright.

So I try to redefine the shortcuts again, and I notice that according to KDE, F1 produces XF86Launch0, and the rest of my F-keys just don’t do anything. I panic, think for a moment about changing the shortcuts to Ctrl-1, Ctrl-2, etc., discard the idea because sooner or later I’ll need the F-keys anyway… and decide to reboot. But still I can’t use my F-keys.

Totally desperate, I ask on IRC and someone says “F Lock”. And I go “WTF is that?” but look at my keyboard, and see some key that is indeed labelled “F Lock”. I press it and everything goes back to normal.

Then, the person goes on to explain that Microsoft has very retarded keyboards (in particular, I was using a Microsoft Natural Keyboard) that “feature” a key called “F Lock”, that redefines the “F keys” (F1, F2, ...) to be some “useful” idiotic retarded shortcuts for Office applications or who knows what. I was also told that apparently some of those keyboards, when they boot, they are by default in “retarded mode” (mine seemed to somehow remember the setting in my last reboot, because it has never done that).

I just had to blog about this. Amazing.