diff --git a/README b/README
deleted file mode 100644
--- a/README
+++ /dev/null
@@ -1,37 +0,0 @@
-INFO
-====
-
-haskdogs is a small shellscript-like tool which creates tag file for entire
-haskell project directory. It takes into account first-level dependencies by
-recursively scanning imports and adding matching packages to the final
-tag list.
-
-As a result, programmer can use his/her text editor supporting tags (vim, for
-example) to jump directly to definition of any standard or foreign function
-he/she uses.
-
-Note, that haskdogs calls some Unix shell commands like 'test' or 'mkdir'
-so this tool will run, but probably fail to work on pure Windows platforms.
-
-INSTALL
-=======
-
-0. cabal install hasktags
-1. git clone https://github.com/ierton/haskdogs
-2. cd haskdogs
-3. cabal install
-4. export PATH="$HOME/.cabal/bin:$PATH"
-
-RUNNING
-=======
-
-1. Make sure yoy have installed hasktags and put it in PATH. Hasktags is being
-called by haskdogs by name.  
-2. cd to your Haskell project dir
-3. run haskdogs (cmdline args will be passed to hasktags followed by a filelist generated)
-
---
-Sergey 
-<ierton@gmail.com>
-
-
diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+HaskDogs
+========
+
+Haskdogs is a shellscript-like tool which creates tag file for entire
+haskell project directory. It takes into account first-level dependencies by
+recursively scanning imports and adding matching packages to the final
+tag list.
+
+As a result, programmer can use his/her text editor supporting tags (vim, for
+example) to jump directly to definition of any standard or foreign function
+he/she uses.
+
+Note, that haskdogs relies on some GNU programs as well as on Unix shell
+commands such as 'cd', 'mkdir' and so on. Also it would run 'cabal' and ghc-pkg'
+in order to obtain package information.
+
+INSTALL
+-------
+
+Check the dependencies. Currently they are: cabal, ghc, hasktags, GNU find,
+which and shell.
+
+0. cabal install hasktags haskdogs
+1. git clone https://github.com/ierton/haskdogs
+2. cd haskdogs
+3. cabal configure && cabal install
+4. export PATH="$HOME/.cabal/bin:$PATH"
+
+RUNNING
+-------
+
+1. Make sure yoy have installed hasktags and put it in PATH.
+
+2. cd to your Haskell project dir
+
+    $ cd $HOME/my-haskell-project
+
+3. run haskdogs (cmdline args will be passed to hasktags followed by a filelist generated)
+
+    $ haskdogs
+
+VIM HINT
+--------
+
+Hasdogs (and underlying Hasktags) use simple scanning algorithm so it may become
+confused facing functions with identical names. In this case Hasktags includes
+all of them in the output file so user has to decide which tag to jump to. Vim
+offers :tag and :ts commands to deal with such situations but it is somewhat
+cumbersome to type them every time.
+
+To speedup things a bit I use the following vim binding. It iterates over all
+same tags quickly with just one C-] command.
+
+    " Cyclic tag navigation {{{
+	let g:rt_cw = ''
+	function! RT()
+		let cw = expand('<cword>')
+		try
+			if cw != g:rt_cw
+				execute 'tag ' . cw
+				call search(cw,'c',line('.'))
+			else
+				try
+					execute 'tnext'
+				catch /.*/
+					execute 'trewind'
+				endtry
+				call search(cw,'c',line('.'))
+			endif
+			let g:rt_cw = cw
+		catch /.*/
+			echo "no tags on " . cw
+		endtry
+	endfunction
+	map <C-]> :call RT()<CR>
+    " }}}
+
+Just copy the code above to your ~/.vimrc and reload the vim.
+
+--
+Sergey 
+<ierton@gmail.com>
+
+
diff --git a/haskdogs.cabal b/haskdogs.cabal
--- a/haskdogs.cabal
+++ b/haskdogs.cabal
@@ -3,7 +3,7 @@
 -- http://www.haskell.org/cabal/release/cabal-latest/doc/users-guide/authors.html#pkg-descr.
 -- The name of the package.
 Name:                haskdogs
-Version:             0.3.1
+Version:             0.3.2
 Synopsis:            Generate ctags file for haskell project directory and it's deps
 Homepage:            http://github.com/ierton/haskdogs
 License:             BSD3
@@ -13,7 +13,7 @@
 Category:            Development
 Build-type:          Simple
 Cabal-version:       >=1.6
-extra-source-files:  README
+extra-source-files:  README.md
 Description:
     haskdogs is a small shellscript-like tool which creates tag file for entire
     haskell project directory. It takes into account first-level dependencies by
diff --git a/src/haskdogs.hs b/src/haskdogs.hs
--- a/src/haskdogs.hs
+++ b/src/haskdogs.hs
@@ -36,7 +36,7 @@
 grepImports ("import":x:_) = x
 grepImports _ = []
 
--- Maps import name to haskel package name
+-- Maps import name to haskell package name
 iname2module :: String -> IO String
 iname2module m = run $ ghc_pkg_find m -|- egrep "^ +[a-zA-Z]" -|- map (head . words) -|- highver
     where highver [] = []