deploy: 21008f9f02

index.html

@@ -31,7 +31,7 @@
 </section>
 
 <section class="kdl-section" id="design-and-discussion">
-  <h2>Design and discussion</h2>
+  <h2>Design and Discussion</h2>
   <p>
     kdl is still extremely new, and discussion about the format should happen
     over on the
@@ -40,6 +40,139 @@
   </p>
 </section>
 
+<section class="kdl-section" id="design-principles">
+  <h2>Design Principles</h2>
+  <ol>
+    <li>Maintainability</li>
+    <li>Flexibility</li>
+    <li>Cognitive simplicity and Learnability</li>
+    <li>Ease of de/serialization</li>
+    <li>Ease of implementation</li>
+  </ol>
+
+  <p>
+    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.
+  </p>
+</section>
+
+<section class="kdl-section" id="overview">
+  <h2>Overview</h2>
+
+  <p>The basic syntax is similar to SDLang:</p>
+
+  <pre>
+    <code>
+// This is a node with a single string value
+title "Hello, World"
+
+// Multiple values are supported, too
+bookmarks 12 15 188 1234
+
+// Nodes can have properties
+author "Alex Monad" email="alex@example.com" active=true
+
+// Nodes can be arbitrarily nested
+contents {
+  section "First section" {
+    paragraph "This is the first paragraph"
+    paragraph "This is the second paragraph"
+  }
+}
+
+// Nodes can be separated into multiple lines
+title \
+  "Some title"
+
+// Comment formats:
+
+// C++ style
+
+/*
+C style multiline
+*/
+
+tag /*foo=true*/ bar=false
+    </code>
+  </pre>
+
+  <p>But kdl changes a few details:</p>
+
+  <pre>
+    <code>
+// Files must be utf8 encoded!
+smile "😁"
+
+// Instead of anonymous nodes, nodes and properties can be wrapped
+// in "" for arbitrary node names.
+"!@#$@$%Q#$%~@!40" "1.2.3" "!!!!!"=true
+
+// The following is a legal bare identifier:
+foo123~!@#$%^&*.:'|<>/?+ "weeee"
+
+// 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
+}
+    </code>
+  </pre>
+
+  <p>The following SDLang features are removed altogether:</p>
+
+  <ul>
+    <li>"Anonymous" nodes</li>
+    <li>Binary data literals</li>
+    <li>Date/time formats</li>
+    <li><code>on</code> and <code>off</code> booleans</li>
+    <li>Backtick strings</li>
+    <li>Semicolons</li>
+    <li>Namespaces with <code>:</code></li>
+    <li>Shell style (<code>#</code>) and Lua style (<code>--</code>) comments</li>
+    <li>Distinction between 32/64/128-bit numbers. There's just numbers.</li>
+  </ul>
+</section>
+
 </main>
   </body>
 </html>

styles/global.css

@@ -519,6 +519,10 @@ video {
   display: table;
 }
 
+.contents {
+  display: contents;
+}
+
 .text-4xl {
   font-size: 2.25rem;
   line-height: 2.5rem;