From 5ae8eab91357e9d41ee953d9f6acb142dbd01dd4 Mon Sep 17 00:00:00 2001
From: Leonora Tindall <nora@nora.codes>
Date: Sun, 2 Apr 2023 22:02:15 -0500
Subject: [PATCH] Add examples and clarify documentation

---
 README | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README b/README
index 5d345b6..e3be355 100644
--- a/README
+++ b/README
@@ -21,10 +21,35 @@ Usage: utf8-norm [--nfc | --nfd | --nfkc | --nfkd] [--stream-safe] [--crlf] <inf
     -b, --buffered  - read the entire input file into memory before operating on it.
     -V, --version - output version information and exit.
 
+utf8-norm operates linewise on the input unless --buffered is specified.
+
 The --buffered option is primarily useful for reading and writing to the same file. It will
 read bytes from the input until end of file and only then begin processing lines of the
 input.
 
+EXAMPLES
+
+Write the contents of input.txt, compatibly decomposed, with CRLF line endings,
+to output.txt:
+
+utf8-norm --nfkd --crlf input.txt output.txt
+
+Normalize file.md, in the canonical composition, buffering the file in memory to
+avoid overwriting it with zeros:
+
+utf8-norm --buffered file.md file.md
+
+Emit the output of my_program to stdout, in the canonical composition, linewise.
+
+my_program | utf8-norm
+
+Buffer the entire output of my_program in memory, and emit it to
+my_program.output in the canonical composition after receiving end-of-file.
+
+my_program | utf8-norm --buffered - my_program.out
+
+ABOUT
+
 utf8-norm was created at Rust Belt Rust 2019 in Dayton, OH. Thanks to @j41manning for her
 excellent talk regarding Unicode handling in Rust.