updated readme

README.md

@@ -9,39 +9,55 @@ npm install -g arch-wiki-man
 
 # Usage & Examples
 
-Use the `awman` command (it stands for arch wiki man)
+## `awman`
 
 ```
 awman beginners guide
 ```
---> Just one match for `beginners guide` so the article will open with `man`
+
+Just one match for `beginners guide` so the article will open with `man`. By the way, `awman` stands for arch wiki man.
+
+## Multiple matches
 
 ```
 awman guide
 ```
---> Multiple matches for `guide` so a selection menu will be displayed
+
+There are multiple matches for `guide` so a selection menu will be displayed. Use the arrow keys or vim-style keybindings (j/k) to select the one to read.
+
+## Search in descriptions
 
 ```
 awman -d i3
 ```
---> `-d` or `--desc-search` option searches in the descriptions for a match as well as in the titles
+
+The `-d` or `--desc-search` option causes searches to scan both the titles _and_ the descriptions for a match.
+
+## Apropos
 
 ```
 awman -k wayland
 ```
---> `-k` or `--apropos` option searches in the contents for a match.
+
+The familiar `-k` or `--apropos` option causes searches to scan the contents for a match as well. This option makes searches run significantly slower.
+
+## Open in a browser
 
 ```
 awman -w tmux
 ```
---> `-w` or `--web` option opens the resulting match in a web browser rather than with `man`
+
+The `-w` or `--web` option opens the resulting match in a web browser rather than with `man`. It uses `xdg-open` to open the relevant url in your default browser.
 
 # Updating
+
 ```
 npm install -g arch-wiki-man
 
 ```
+
 Updates are pushed automatically every two days to `https://github.com/greg-js/arch-wiki-md-repo`, a dependency for this project. Whenever the install command is run, the changes will be fetched.
 
 # License
+
 Licensed under GPLv3