Update readme

This patch updates the readme with better usage examples and with the
documentation for rusty-man itself.

Signed-off-by: Robin Krahl <robin.krahl@ireas.org>

README.md

@@ -5,29 +5,42 @@ SPDX-License-Identifier: MIT
 
 # rusty-man
 
-A command-line viewer for documentation generated by `rustdoc`.
+```
+$ rusty-man rusty-man | head -4
+rusty-man                                 Module rusty-man                                 rusty-man
+
+DESCRIPTION
+      rusty-man is a command-line viewer for documentation generated by `rustdoc`.
+```
 
 ## Example Usage
 
+Before running rusty-man, make sure that you generated the documentation with
+`cargo doc`:
 ```
 $ cd rusty-man && cargo doc
+```
+
+Then you can open the documentation for an item:
+```
 $ rusty-man kuchiki::NodeRef
-# Struct kuchiki::NodeRef
+```
 
-pub struct NodeRef(pub Rc<Node>);
+You don’t have to specificy the full item name:
-
+```
-A strong reference to a node.
+$ rusty-man NodeRef
+```
 
+If the documentation is not placed in `./target/doc` or
+`/usr/share/doc/rust{,-doc}/html`, you have to manually set the source path
+using the `-s`/`--source` option:
+```
 $ rusty-man --source ~/.rustup/toolchains/stable-*/share/doc/html io::Error
-# Struct std::io::Error
+```
-
-pub struct Error { /* fields omitted */ }
-
-The error type for I/O operations of the `Read`, `Write`, `Seek`, and associated traits.
-
-Errors mostly originate from the underlying OS, but custom instances of `Error` can be created with
-crafted error messages and a particular value of `ErrorKind`.
 
+If there are multiple matches for the keyword, rusty-man will show you a list
+of all matching items:
+```
 $ rusty-man --source ~/.rustup/toolchains/stable-*/share/doc/rust/html u8
 Found mulitple matches for u8 – select one of:
 
@@ -35,12 +48,10 @@ Found mulitple matches for u8 – select one of:
 [ 1 ] std::u8: The 8-bit unsigned integer type.
 
 > 1
-
-# Primitive Type u8
-
-The 8-bit unsigned integer type.
 ```
 
+For more usage information, run `rusty-man --help`.
+
 ## Installation
 
 To install rusty-man, clone this repository and use cargo to build the project.