One manpage a day...

I first heard of this in a Google Doc, which was linked to by a wiki page in Swedish I was shown by someone on IRC. Unfortunately, I can't find any of these links anymore...

Documentation in some areas of Ubuntu is sorely lacking. Have you ever ran into a case where you tried to use this shiny new program, or do a one-shot use of some obscure old thing, without managing to find any documentation for it?

One of the first things we're trained to do as Unix users is to look for the manpage for a command. Many packages are missing manpages. Any missing manpage can be considered as a bug for a program, since it means we're missing documentation for it, and people who might use that software would have no idea how to use it, or perhaps would have no idea how to use it effectively, how to make the most of the available features.

Two such examples I found on my own system, looking at the contents of /usr/bin are ubuntu-drivers (pkg:ubuntu-drivers-common) and ubuntu-support-status (pkg:update-manager-core). I'm not trying to point fingers at anything (in fact, I've contributed to ubuntu-drivers before, too), just showing that examples of commands missing a manpage can be trivially found.

Let's all try to find one manpage to write a day, and we'll quickly improve the state of documentation in Ubuntu by a noticeable amount. Try to write the manpage, but otherwise at least file a bug for the fact that it's missing, against the package that contains that binary.

For convenience; here's a command to get a list of commands that man couldn't find a manpage for in /usr/bin (there may well be a better way to do this, and it will list some false-positives):

ls -1 --file-type /usr/bin | sed 's/@//' | LC_ALL=C xargs -n1 man -w >/dev/null

Then, to find out which package contains that binary, use dpkg -S with the name of the command.

Thanks to Stefan Bader, Colin King and Louis Bouchard for a stimulating discussion on documentation this morning. :)

Installer session at UOS

If you're interested in how Ubuntu gets installed on systems, want to ask about specific features, or have already filed bugs that you'd like to bring to our attention, watch for my session on the calendar:

http://summit.ubuntu.com/uos-1505/meeting/22512/core-1505-installer-healthcheck/

It's currently scheduled for Tuesday May 5th at 18:00 UTC (that's in a little bit more than 24 hours!); but just in case it changes time, make sure you're marked as attending and subscribed to the blueprint.

As stated in the blueprint summary, I can't guarantee we'll get to everything, but it will be the right place to see what has to be done, and for anyone to pitch in time if they're interested in helping out!

Preseeding installations

In early February, I completed a move from Canonical's Phonedations team to the Foundations team. Part of this new work means debugging a lot of different failure cases in the installer, grub, and other early boot or low-level sofware, some of which requiring careful reproduction steps and probably quite a few install runs in VMs on on hardware.

Given the number of installations I do I've started to keep around preseed files; the text files used to configure automatic installations. I've made them available at http://people.canonical.com/~mtrudel/preseed/ so that they can be reused as necessary. Most of these preseed files make heavy use of the network to get the installation data and packages from the web, so they will need to be tweaked for use in an isolated network. They are annotated enough that it should be possible for anyone to improve on them to suit their own needs. I will add to these files as I run across things to test and automate. I hope we can use some of them soon in new automated QA tests where appropriate, so that it can help catch regressions.

For those not familiar with preseeding, these files can be used and referred to in the installation command-line when starting from a network PXE boot or a CDROM or pretty much any other installation medium. They are useful to tell the installer how you want the installation to be done without having to answer all of the individual questions one by one in the forms in ubiquity or debian-installer. The installer will read the preseed file and use these answers without showing the prompts. This also means some of the files I make available should not be used lightly, as they will happily wipe disks without asking. You've been warned :)

To use this, you'll want to specify "preseed/file=/path/to/file" (or just file=) for a file directly accessible as a file system or through TFTP, or "preseed/url=http://URI/to/file" (or just url=) if it's available using HTTP. On d-i installs, this means you may also need to add "auto=true priority=critical" to avoid having to fill in language settings and the like (since the preseeds are typically only read after language, country, and network have been configured); and on ubiquity installs (for example, using a CD), you'll want to add 'only-ubiquity automatic-ubiquity' to the kernel command-line, again to keep the automated, minimal look and feel.

I plan on writing another entry soon on how to debug early boot issues in VMs or hardware using serial. Stay tuned.