Skip to content
13 June 32010 / Robin Wellner

Vim and manual blindness

Vim logo

Several months ago, I had a shocking revelation: for tasks like text processing, I was completely reliant on GUI applications. This was not good. In the two years or so before that, I had learned the value of the command line, the power you have at your fingertips when you see that $ prompt. (The >>> prompt as well, but I’m not talking about that right now.)

Sure, I knew how to use nano, but that is seriously underpowered. It’s pretty much the Notepad of CLI editors.

After a short period of research, I realized there were really only two options here.

As stated countless times before, my computer is seriously underpowered (and makes too much noise, but that is a different story altogether). That led me to shun Emacs, although its clunkiness was probably mainly an issue in simpler times, when eight megabytes was still a huge amount of memory. Nevertheless, I decided to take up vi. Or, to be precise, Vim, because that seemed to be the variant everyone was using.

So I did. I learned HJKL, :w, :q, :s, /, … you get the idea.

However, I rarely used Vim: to edit Git commit messages, I used Nano; when programming, I ran SciTE; when writing fiction, was loaded; when editing lousy text files, I started Mousepad; when writing Markdown, I launched MEdit. There was not much to use Vim for in that time. I was just not comfortable with it yet, just like what happened with the command line before.

To get over it, I forced myself to use Vim whenever possible (of course it can’t handle ODT files, but I’m writing a Vim clone that will). Lo and behold, my Vim skills grew, slowly but surely, as I became more comfortable with the different modes and learned more and more short cuts.

“Sure,” you’ll say, “I get that. But what is that ‘manual blindness’ all about?”

Well, I was just getting to that. Please keep your comments to yourself until you finished reading this entry. I’m writing a blog here.

You’d answer: “But it’s really you that’s writing all this, so you’re basically arguing with youself.” I’d reply: shut up, shut up!

Anyway, I especially started using Vim for the Dol Pi source and Wrong stories.

“Why don’t I write some syntax highlighting for them?” I thought.

You can guess what I did next. Wrong syntax in action No, just kidding. I wrote syntax files for (Dol Pi) src.ecsv files and Wrong files. It took a whole lot of effort to get them right, but I’m really satisfied. Note they ignore whatever theme you have, because neither of them really has keywords, comments, identifiers, etcetera. They do have ellipses, separators, headers, italic, @code@, … So that meant I had to write my own styles for them. You can see (part of) the result on the right.

There was one problem: when I opened a Wrong file or src.ecsv, nothing happened. It just showed as plain old white text.

What was I doing wrong? I had the .vim files in ~/.vim/syntax/, along with filetype.vim. The manual had to have something on this. So I read, and read, and found nothing. I was doing everything right. Were the scripts crashing? I put an echo statement at the top of the .vim files. Nothing. Nothing was printed. “Hey,” I thought, “this is something. I now know my precious .vim files are not read at all.” But how to get Vim to read them? For some reason it couldn’t find those files. RTFM, RTFM: nothing. Was filetype.vim even executed? A quick check confirmed it wasn’t. So how could I get Vim to read it? I knew I shouldn’t have to enable some option, because Python, Lua and so on were highlighted just fine. I carefully re-read what the Vim documentation had to say on making new filetypes (scroll down to point C2):

   2. Create a file that contains autocommands to detect the file type.
	" my filetype file
	if exists("did_load_filetypes")
	augroup filetypedetect
	  au! BufRead,BufNewFile *.mine		setfiletype mine
	  au! BufRead,BufNewFile *.xyz		setfiletype drawing
	augroup END
      Write this file as "filetype.vim" in your user runtime directory.  For
      example, for Unix:
	:w ~/.vim/filetype.vim

Yes, that’s exactly what I—wait a minute… it says ~/.vim/filetype.vim? I thought it was ~/.vim/syntax/filetype.vim!

D'oh!And just a single mv filetype.vim .. did the trick. I started Vim with a Wrong file, and it crashed. The wrong.vim script was utter crap. But that didn’t matter, because now I could at least see what to fix.

So why didn’t I see where that file was supposed to go?

It is a typical example of manual blindness, a specific example of perceptual blindness. This is something we need to deal with, again and again, both as blinded user and unsuspecting documentation writer.

There are several ways to fight this what I can think of:

  • Remove clutter in documentation. Don’t put in unnecessary details that might distract.
  • Use bold text and bullets to point to important information, but don’t over-use them.
  • Do Repeat Yourself. When something is relevant, say it, even if you already said it just two pages ago.
  • Don’t treat your users as if they are stupid, but do treat them like they are sleep-deprived, slow readers, or anxious to have hot, sweaty, tangled-bedsheets-fingertips-digging-into-the-back sex.

I’ll leave you with that. For now, I will only say:




Leave a Comment
  1. Luiji Maryo / Jun 13 2010 19:50

    Ah, manual blindness, the scourge of documentation readers and writers. I have had the same problem, like, five times before, it is SO ANNOYING!

    Also, what was that link to at the bottom? Based on the title of the link, I didn’t want to click it…

    • Robin Wellner / Jun 13 2010 20:16

      Don’t worry about the link — it is from xkcd, so it’s safe for work.

    • qubodup / Jun 14 2010 1:20

      Are you using a browser that does not show you the url of the hovered link at the bottom/in the status bar? 🙂

  2. qubodup / Jun 14 2010 1:19

    Such nice a post!

    > (of course it can’t handle ODT files, but I’m writing a Vim clone that will)
    My lols to you!

    • Robin Wellner / Jun 14 2010 9:26

      Such nice a post!


      My lols to you!

      Heh, ok.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: