From 7b7d57bf29d1b2f103373cbab4d416899554f615 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kat=20March=C3=A1n?= <kzm@zkat.tech>
Date: Tue, 17 Oct 2023 09:55:32 -0700
Subject: [PATCH] lead with a more complete example in the readme

---
 README.md | 39 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 78cfcb7..090fdf8 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,42 @@
 # The KDL Document Language
 
-KDL is a document language with xml-like semantics that looks like you're
-invoking a bunch of CLI commands! It's meant to be used both as a
+KDL is a small, pleasing document language with xml-like semantics that looks
+like you're invoking a bunch of CLI commands! It's meant to be used both as a
 serialization format and a configuration language, much like JSON, YAML, or
-XML.
+XML. It looks like this:
+
+```kdl
+package {
+  name "my-pkg"
+  version "1.2.3"
+
+  dependencies {
+    // Nodes can have standalone values as well as key/value pairs.
+    lodash "^3.2.1" optional=true alias="underscore"
+  }
+
+  scripts {
+    // "Raw" and multi-line strings are supported.
+    build r#"
+      echo "foo"
+      node -c "console.log('hello, world!');"
+      echo "foo" > some-file.txt
+    "#
+  }
+
+  // `\` breaks up a single node across multiple lines.
+  the-matrix 1 2 3 \
+             4 5 6 \
+             7 8 9
+
+  // "Slashdash" comments operate at the node level, with just `/-`.
+  /-this-is-commented {
+    this "entire" "node" {
+      "is" "gone"
+    }
+  }
+}
+```
 
 There's a living [specification](SPEC.md), as well as various
 [implementations](#implementations). You can also check out the [FAQ](#faq) to