additional usage text.

README.md

@@ -7,7 +7,65 @@
 
 A fancy compiler diagnostics crate.
 
-## Example
+## Usage
+
+For each error you wish to report:
+* Call [`Report::build()`] to start a [`ReportBuilder`].
+* Assign whatever details are appropriate to the error using the various
+  methods, and then call the [`finish`](ReportBuilder::finish) method to get a
+  [`Report`] value.
+* For each `Report`, call [`print`](Report::print) or [`eprint`](Report::eprint)
+  to send the report directly to `stdout` or `stderr`. Alternately, you can use
+  [`write`](Report::write) to send the report to any other
+  [`Write`](std::io::Write) destinarion (such as a file).
+
+A program such as this:
+
+```rust
+fn main() {
+    let mut colors = ColorGenerator::new();
+
+    // Generate & choose some colours for each of our elements
+    let a = colors.next();
+    let b = colors.next();
+    let out = Color::Fixed(81);
+    let out2= colors.next();
+
+    Report::build(ReportKind::Error, "sample.tao", 12)
+        .with_code(3)
+        .with_message(format!("Incompatible types"))
+        .with_label(Label::new(("sample.tao", 32..33))
+            .with_message(format!("This is of type {}", "Nat".fg(a)))
+            .with_color(a))
+        .with_label(Label::new(("sample.tao", 42..45))
+            .with_message(format!("This is of type {}", "Str".fg(b)))
+            .with_color(b))
+        .with_label(Label::new(("sample.tao", 11..48))
+            .with_message(format!(
+                "The values are outputs of this {} expression",
+                "match".fg(out),
+            ))
+            .with_color(out))
+        .with_label(Label::new(("sample.tao", 0..48))
+            .with_message(format!(
+                "The {} has a problem",
+                "definition".fg(out2),
+            ))
+            .with_color(out2))
+        .with_label(Label::new(("sample.tao", 50..76))
+            .with_message(format!(
+                "Usage of {} here",
+                "definition".fg(out2),
+            ))
+            .with_color(out2))
+        .with_note(format!("Outputs of {} expressions must coerce to the same type", "match".fg(out)))
+        .finish()
+        .print(("sample.tao", Source::from(include_str!("sample.tao"))))
+        .unwrap();
+}
+```
+
+Gives us the following printout in the terminal:
 
 <a href = "https://github.com/zesterer/ariadne/blob/main/examples/multiline.rs">
 <img src="https://raw.githubusercontent.com/zesterer/ariadne/main/misc/example.png" alt="Ariadne supports arbitrary multi-line spans"/>