From 0d75176f597c80c8273ec80d372d4dae8a862b34 Mon Sep 17 00:00:00 2001
From: Robin Krahl <robin.krahl@ireas.org>
Date: Fri, 24 Jul 2020 12:36:49 +0200
Subject: [PATCH] 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 | 45 ++++++++++++++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 2936442..c78a34d 100644
--- a/README.md
+++ b/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>);
-
-A strong reference to a node.
+You don’t have to specificy the full item name:
+```
+$ 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.