update content a bit

src/_includes/partials/description.md

@@ -1,10 +1,14 @@
 <section class="kdl-section" id="description">
 
-kdl is a document language, mostly based on
+KDL is a document language with xml-like semantics that looks like you're
-[SDLang](https://sdlang.org), with xml-like semantics that looks
+invoking a bunch of CLI commands!
-like you're invoking a bunch of CLI commands!
 
 It's meant to be used both as a serialization format and a configuration
 language, and is relatively light on syntax compared to XML.
 
+There's a living [specification](SPEC.md), as well as
+[implementations](#implementations). The language is based on
+[SDLang](https://sdlang.org), with a number of modifications and
+clarifications on its syntax and behavior.
+
 </section>

src/_includes/partials/design-and-discussion.md

@@ -2,9 +2,8 @@
 
 ## Design and Discussion
 
-kdl is still extremely new, and discussion about the format should happen
+KDL is still extremely new, and discussion about the format should happen over
-over on the
+on the [discussions](https://github.com/kdl-org/kdl/discussions) page in the
-[discussions](https://github.com/kdoclang/kdl/discussions) page
+Github repo. Feel free to jump in and give us your 2 cents!
-in the Github repo. Feel free to jump in and give us your 2 cents!
 
 </section>

src/_includes/partials/design-principles.md

@@ -8,10 +8,4 @@
 1. Ease of de/serialization
 1. Ease of implementation
 
-These are the guiding principles behind the design of KDL, in order of
-importance. These principles will hopefully be useful in tie-breaking and
-otherwise directing specific decisions when it comes down to it. They are
-intentionally vague when it comes to specifics, but more concrete
-definitions for each one will be settled on as the project matures.
-
 </section>

src/_includes/partials/overview.md

@@ -2,44 +2,149 @@
 
 ## Overview
 
-The basic syntax is similar to SDLang:
+### Basics
+
+A KDL node is a node name, followed by zero or more "arguments", and
+children.
 
 ```kdl
-// This is a node with a single string value
 title "Hello, World"
+```
 
-// Multiple values are supported, too
+You can also have multiple values in a single node!
+
+```kdl
 bookmarks 12 15 188 1234
+```
 
-// Nodes can have properties
+Nodes can have properties.
+
+```kdl
 author "Alex Monad" email="alex@example.com" active=true
+```
 
-// Nodes can be arbitrarily nested
+And they can have nested child nodes, too!
+
+```kdl
 contents {
   section "First section" {
     paragraph "This is the first paragraph"
     paragraph "This is the second paragraph"
   }
 }
+```
 
-// Nodes can be separated into multiple lines
+Nodes without children are terminated by a newline, a semicolon, or the end of
-title \
+a file stream:
-  "Some title"
 
-// Comment formats:
+```kdl
+node1; node2; node3;
+```
 
-// C++ style
+### Values
+
+KDL supports 4 data types:
+
+* Strings: `"hello world"`
+* Numbers: `123.45`
+* Booleans: `true` and `false`
+* Null: `null`
+
+#### Strings
+It supports two different formats for string input: escaped and raw.
+
+```kdl
+node "this\nhas\tescapes"
+other r"C:\Users\zkat\"
+```
+Both types of string can be multiline as-is, without a different syntax:
+
+```kdl
+string "my
+multiline
+value"
+```
+
+And for raw strings, you can add any number of # after the r and the last " to
+disambiguate literal " characters:
+
+```kdl
+other-raw r#"hello"world"#
+```
+
+#### Numbers
+
+There's 4 ways to represent numbers in KDL. KDL does not prescribe any
+representation for these numbers, and it's entirely up to individual
+implementations whether to represent all numbers with a single type, or to
+have different representations for different forms.
+
+KDL has regular decimal-radix numbers, with optional decimal part, as well as
+an optional exponent.
+
+```kdl
+num 1.234e-42
+```
+
+And using the appropriate prefix, you can also enter hexadecimal, octal, and
+binary literals:
+
+```kdl
+my-hex 0xdeadbeef
+my-octal 0o755
+my-binary 0b10101101
+```
+
+Finally, all numbers can have underscores to help readability:
+
+```kdl
+bignum 1_000_000
+```
+
+### Comments
+
+KDL supports C-style comments, both line-based and multiline. Multiline
+comments can be nested.
+
+```kdl
+// C style
 
 /*
 C style multiline
 */
 
 tag /*foo=true*/ bar=false
+
+/*/*
+hello
+*/*/
 ```
 
-But kdl changes a few details:
+On top of that, KDL supports `/-` "slashdash" comments, which can be used to
+comment out individual nodes, arguments, or children:
 
 ```kdl
+// This entire node and its children are all commented out.
+/-mynode "foo" key=1 {
+  a
+  b
+  c
+}
+
+mynode /-"commented" "not commented" /-key="value" /-{
+  a
+  b
+}
+```
+
+### More Details
+
+```kdl
+// Nodes can be separated into multiple lines
+title \
+  "Some title"
+
+
 // Files must be utf8 encoded!
 smile "😁"
 
@@ -48,62 +153,14 @@ smile "😁"
 "!@#$@$%Q#$%~@!40" "1.2.3" "!!!!!"=true
 
 // The following is a legal bare identifier:
-foo123~!@#$%^&*.:'|<>/?+ "weeee"
+foo123~!@#$%^&*.:'|/?+ "weeee"
+
+// And you can also use unicode!
+ノード　お名前＝"☜(ﾟヮﾟ☜)"
 
 // kdl specifically allows properties and values to be
 // interspersed with each other, much like CLI commands.
 foo bar=true "baz" quux=false 1 2 3
-
-// strings can be multiline as-is, without a different syntax.
-string "my
-multiline
-value"
-
-// raw/unescaped strings use the "r" prefix on string literals and
-// otherwise behave the same, including multiline support.
-raw r"C:\Users\kdl"
-
-// You can add any number of # after the r and the last " to
-// disambiguate literal " characters.
-other-raw r#"hello"world"#
-
-// There is a single decimal number type, much like JSON's.
-num 1.234e-42
-
-// Numbers can have underscores to help readability:
-bignum 1_000_000
-
-// There is additional support for literal hexadecimal, octal, and binary input.
-my-hex 0xdeadbeef
-my-octal 0o755
-my-binary 0b1010_1101
-
-// You can comment out individual nodes with /-. In the case below, everything
-// up until the closing `}` becomes commented.
-/-mynode "foo" key=1 {
-  a
-  b
-  c
-}
-
-// You can apply /- ("slashdash") comments to individual values, properties,
-// or child blocks, too:
-mynode /-"commented" "not commented" /-key="value" /-{
-  a
-  b
-}
 ```
 
-The following SDLang features are removed altogether:
-
-- "Anonymous" nodes
-- Binary data literals
-- Date/time formats
-- `on` and `off` booleans
-- Backtick strings
-- Semicolons
-- Namespaces with `:`
-- Shell style (`#`) and Lua style (`--`) comments
-- Distinction between 32/64/128-bit numbers. There's just numbers.
-
 </section>

src/index.md

@@ -1,10 +1,10 @@
 ---
 layout: base.html
-title: kdl - Kat's Document Language
+title: KDL - KDL Document Language
 ---
 
 <header class="py-10 bg-gray-300">
-  <h1 class="text-4xl text-center">kdl - Kat's Document Language</h1>
+  <h1 class="text-4xl text-center">KDL - KDL Document Language</h1>
 </header>
 
 {% include partials/description.md %}