Linux Documentation

I have complained before about the really crappy documentation that you encounter when trying to trawl through linux manuals. Two recent examples may shed some light on the nature of my complaint.

Firstly, in my last post I talked about the xdg-mime command and how it is used to change the default application for various filetypes. What I did not say was how frustrating the documentation was to deal with. For instance, go and look at the manual page for xdg-mime. It all starts well enough:

xdg-mime — command line tool for querying information about file type handling and adding descriptions for new file types

That's a nice intro, and sets the scene well. We know what we are talking about. Also, the description gives us some more useful information:

The xdg-mime program can be used to query information about file types and to add descriptions for new file types.

Good. Good. Keep it coming. Lets have a look at the synopsis of the command:

xdg-mime query { filetype | default }

Right, so we type "xdg-mime query" and then what? Oh - filetype. Right, so I am interested in PDFs. Lets try:

xdg-mime query pdf

Aaaaaaand:

xdg-mime: unknown query type 'pdf'

Fucking great. The system must know about PDFs because it is opening them now (with GIMP, which is fucking annoying and the whole point of this little command line adventure). What could I be doing wrong?

Slowly the light dawns. When it says 'filetype' that is not a variable, that is literally what you type. So you follow 'xdg-mime query' with the word 'filetype'. Right, brilliant. So why the fuck could the error report not say:

xdg-mime: unknown query type 'pdf'.  Valid querys are 'filetype' and 'default'.

It's not that hard to type out six words.

OK, so we follow 'xdg-mime query' with either "filetype" or "default". I can follow that. Fine. So what do I type after filetype or default? Lets see...

query filetype FILE: Returns the file type of FILE in the form of a MIME type.

Right, so I now try:

xdg-mime query filetype forfuckssake.pdf:

Aaaaaand:

xdg-mime: file 'forfuckssake.pdf:' does not exist

Yes it fucking does I am looking at it! So I check the spelling, and the path. I try "./" before the filename, because god knows linux gets picky about finding stuff not in the path - even when you are in the same fecking directory as the file you want to use! Nada.

Then a further little light dawns. See the colon at the end of the filename? What if maybe, just maybe, that shouldn't be fucking there? What if the instructions, which specifically appended a colon to the end of the filename, and which I am following carefully, not just being slap happy with my colons in general, were put together with all the skill and panache of a recovering alcoholic with the DTs trying to construct a house of cards? Leave off the colon = command works as it should. Genius.

Secondly, I have been farting around with the larch system for making live usb installations of Arch. One of which I am using to post this, as a matter of fact. To cut a long story short, I wanted to add some extra packages to the install which were not in the repositories. The Larch manual states:

It is possible to include your own 'custom' packages in the installation. Maybe ones you have compiled yourself, e.g. from the AUR, or modified versions (fixes or customizations) of standard packages. To do this you need to put your packages in a directory and run gen-repo - which requires python - on this directory (run it without arguments to get usage instructions). Then place an entry for this new repository in your 'pacman.conf' (in the profile or else in the working directory). If your packages replace some in the existing repositories, your custom repository needs to come before those repositories in 'pacman.conf'. Any packages you want installed now just need to be listed in addedpacks.

Larch also sets up a pacman.conf file which contains this little nugget of information:

# An example of a custom package repository. See the pacman manpage for
# tips on creating your own repositories.
#[custom]
#Server = file:///path/to/custom

This sounds promising and looks straightforwards. So I put my packages in a directory, run gen-repo and make a change to pacman.conf. Only I can't fucking find gen-repo. I mean it is not in the directory I installed larch into. Where the fuck can it be? I eventually trace it to ./larch/run/ where I find it is actually called gen_repo, not gen-repo. Fan-fucking-tastic waste of time.

So I then run the command on the directory I have assembled my custom packages in. It makes a new file in that directory called nameofdirectory.db.tar.gz.

Right so I ask you now - how do I "place an entry for this new repository in" my pacman.conf file? I try referencing this new file directly in the Server: line. That doesn't work. I try just making the server line link to the directory the new file is in. That still doesn't work.

I eventually discover, through trial and error no less, that what I should have been doing was to have the Server: line point to the directory the new file was in, uncomment the line #[custom] above AND change the word 'custom' in it to the NAME of the new file LESS the .db.tar.gz bit. Oh - of course, silly me, how fucking simple. I mean, it is all laid out so clearly in those helpful manual files. All these steps are so fucking transparent I nearly walked right into them.

Give me fucking strength. Is it something to do with linux? Are the developers so fucking delighted to get their software to actually work that they piss off down the pub as soon as it compiles? With the inevitable result that they are shit-faced drunk when it comes to writing the documentation? And then, THEN, when you ask a question you are told to RTFM? Really? Well stick your RTFM right UYFA.