Shallow Thoughts : tags : help

Friendlier error messages for shell newbies

Helping people get started with Linux shells, I've noticed they tend to make two common mistakes vastly more than any others:

1. Typing a file path without a slash, like etc/fstab
2. typing just a filename, without a command in front of it

The first boils down to a misunderstanding of how the Linux file system hierarchy works. (For a refresher, you might want to check out my Linux Planet article Navigating the Linux Filesystem.)

The second problem is due to forgetting the rules of shell grammar. Every shell sentence needs a verb, just like every sentence in English. In the shell, the command is the verb: what do you want to do? The arguments, if any, are the verb's direct object: What do you want to do it to?

(For grammar geeks, there's no noun phrase for a subject because shell commands are imperative. And yes, I ended a sentence with a preposition, so go ahead and feel superior if you believe that's incorrect.)

The thing is, both mistakes are easy to make, especially when you're new to the shell, perhaps coming from a "double-click on the file and let the computer decide what you should do with it" model. The shell model is a lot more flexible and (in my opinion) better -- you, not the computer, gets to decide what you should do with each file -- but it does take some getting used to.

But as a newbie, all you know is that you type a command and get some message like "Permission denied." Why was permission denied? How are you to figure out what the real problem was? And why can't the shell help you with that?

And a few days ago I realized ... it can! Bash, zsh and similar shells have a fairly flexible error handling mechanism. Ubuntu users have seen one part of this, where if you type a command you don't have installed, Ubuntu gives you a fancy error message suggesting what you might have meant and/or what package you might be missing:

$ catt /etc/fstab
No command 'catt' found, did you mean:
 Command 'cat' from package 'coreutils' (main)
 Command 'cant' from package 'swap-cwm' (universe)
catt: command not found

What if I tapped into that same mechanism and wrote a more general handler that could offer helpful suggestions when it looked like the user forgot the command or the leading slash?

It turns out that Ubuntu's error handler uses a ridiculously specific function called command_not_found_handle that can't be used for other errors. Some helpful folks I chatted with on #bash felt, as I did, that such a specific mechanism was silly. But they pointed me to a more general error trapping mechanism that turned out to work fine for my purposes.

It took some fussing and fighting with bash syntax, but I have a basic proof-of-concept. Of course it could be expanded to cover a lot more types of error cases -- and more types of files the user might want to open.

Here are some sample errors it catches:

$ schedule.html
bash: ./schedule.html: Permission denied

schedule.html is an HTML file. Did you want to run: firefox schedule.html

$ screenshot.jpg
bash: ./screenshot.jpg: Permission denied

screenshot.jpg is an image file. Did you want to run:
    pho screenshot.jpg
    gimp screenshot.jpg

$ .bashrc
bash: ./.bashrc: Permission denied

.bashrc is a text file. Did you want to run:
    less .bashrc
    vim .bashrc

$ ls etc/fstab
/bin/ls: cannot access etc/fstab: No such file or directory

Did you forget the leading slash?
etc/fstab doesn't exist, but /etc/fstab does.

You can find the code here: Friendly shell errors and of course I'm happy to take suggestions or contributions for how to make it friendlier to new shell users.

Tags: linux, shell, help, education, programming
[ 15:07 Nov 08, 2009    More linux | permalink to this entry | ]

Installing Flash on Linux, for Newbies

Dear Adobe: Please update your instructions when you update your install packages

I had a circus a few nights ago trying to help my mom get her flash plugin updated. Not because of anything she was doing; because Adobe's out of date instructions were just plain wrong.

It gave me more insight into why people say "Linux is hard to use" ... which has little to do with Linux, and everything to do with outside forces that seem to go out of their way to make things hard for Linux users.

See, Mom's Firefox auto-updated to a new version, which started whining about her flash version being insecure and telling her to update it. It pointed her to Adobe's site, get.adobe.com/flashplayer.

She went there and was presented with a long list of options for different types of download. She's on Ubuntu, so the Ubuntu deb might have worked -- but it might not, since she's running a Firefox from Mozilla.org rather than the one from Ubuntu. (Ubuntu's Firefox on Hardy was notoriously crashy, and she has enough problems with the Mozilla version crashing.)

I told her I usually use the tarball, and install it as myself, not as root. In the past, the flash installer has always been very good about noticing I'm not root and installing to ~/.mozilla/plugins. I didn't expect problems.

So she downloaded the tarball and tried to follow their instructions, which look like this:

1. Click the download link to begin installation. A dialog box will appear asking you where to save the file.
2. Save the .tar.gz file to your desktop and wait for the file to download completely.
3. Unpackage the file. A directory called install_flash_player_10_linux will be created.
4. In terminal, navigate to this directory and type ./flashplayer-installer to run the installer. Click Enter. The installer will instruct you to shut down your browser(s).
5. Once the installation is complete, the plug-in will be installed in your Mozilla browser. To verify, launch Mozilla and choose Help > About Plug-ins from the browser menu.

The first problem is "Unpackage the file." Honestly, how hard is it to give people a hint that "unpackage" means "type tar xf install_flash_player_10_linux.tar.gz"? As long as you're writing instructions anyway, why not tell people the actual command instead of expecting them to figure it out somehow?

"In terminal, navigate to this directory" -- if you know your user will be typing shell commands in a terminal, why not tell them to cd rather than expecting them to figure that out from "navigate"? (Mom figured that one out -- go Mom! -- but a lot of users wouldn't.)

Except -- OOPS! try following the instructions and you can't cd ... because it turns out the flash 10 "installer" doesn't contain a directory, or indeed an installer, at all. It's a tarball containing one file, libflashplayer.so.

Now, setting aside the question of why anyone would use tar to package a single file -- why not just make the file available for download and tell users where to put it? -- they give you no hint as to where this libflashplayer.so file is supposed to go. If you don't happen to know how Firefox sets up its plugins, you're out of luck.

Fortunately, I happen to know where the file goes. I told Mom to mv libflashplayer.so ~/.mozilla/plugins/ and all was well. But ... sheesh! With instructions like this on something as (unfortunately) widely needed as the Flash plugin, how can a newbie ever expect to get anywhere?

For newbies reading this, the real instructions for installing Adobe's flash 10 tarball are:

1. Download their file, which is named install_flash_player_10_linux.tar.gz
2. Open a terminal and cd to wherever you downloaded it, e.g. cd ~/Desktop
3. tar xf install_flash_player_10_linux.tar.gz
4. mv libflashplayer.so ~/.mozilla/plugins/
5. Restart firefox, make sure flash works, and (once you're sure, at your option)
   rm install_flash_player_10_linux.tar.gz

Tags: linux, help, newbie, flash
[ 23:53 Sep 13, 2009    More linux | permalink to this entry | ]