From 690de83bb4a8d800b37b938f6cbd1953fd88d5a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kat=20March=C3=A1n?= Date: Sun, 27 Dec 2020 17:24:52 -0800 Subject: [PATCH] add FAQ --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 103 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index b27ba93..ba7a04a 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ # KDL - The KDL Document Language KDL is a document language with xml-like semantics that looks like you're -invoking a bunch of CLI commands! +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. -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 various +[implementations](#implementations). You can also check out the [FAQ](#faq) to +answer all your burning questions! -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. +The language is based on [SDLang](https://sdlang.org), with a number of +modifications and clarifications on its syntax and behavior. ## Design and Discussion @@ -17,14 +18,6 @@ KDL is still extremely new, and discussion about the format should happen over on the [discussions page](https://github.com/kdl-org/kdl/discussions). Feel free to jump in and give us your 2 cents! -## Design Principles - -1. Maintainability -1. Flexibility -1. Cognitive simplicity and Learnability -1. Ease of de/serialization -1. Ease of implementation - ## Implementations * Rust: [kdl-rs](https://github.com/kdl-org/kdl-rs) @@ -198,7 +191,101 @@ foo123~!@#$%^&*.:'|/?+ "weeee" foo bar=true "baz" quux=false 1 2 3 ``` +## Design Principles + +1. Maintainability +1. Flexibility +1. Cognitive simplicity and Learnability +1. Ease of de/serialization +1. Ease of implementation + +## FAQ + +#### Why yet another document language? + +Because nothing out there felt quite right. The closest one I found was +SDLang, but that had some design choices I disagreed with. + +#### Ok, then, why not SDLang? + +SDLang is designed for use cases that are not interesting to me, but are very +relevant to the D-lang community. KDL is very similar in many ways, but is +different in the following ways: + +* The grammar and expected semantics are [well-defined and specified](SPEC.md). +* There is only one "number" type. KDL does not prescribe representations. +* Slashdash (`/-`) comments are great and useful! +* I am not interested in having first-class date types, and SDLang's are very + non-standard. +* Values and properties can be interspersed with each other, rather than one + having to follow the other. +* KDL does not have a first-class binary data type. Just use strings with base64. +* All strings in KDL are multi-line, and raw strings are written with + Rust-style syntax (`r"foo"`), instead of backticks. +* KDL identifiers can use UTF-8 and are much more lax about symbols than SDLang. +* KDL does not support "anonymous" nodes. +* Instead, KDL supports arbitrary identifiers for node names and attribute + names, meaning you can use arbitrary strings for those: `"123" "value"=1` is + a valid node, for example. This makes it easier to use KDL for + representing arbitrary key/value pairs. + +#### Have you seen that one XKCD comic about standards? + +Yes. I have. Please stop linking me to it. + +#### What about YAML? + +YAML is a great, widespread language. Unlike KDL, which is node-based (like +XML or HTML), it's based on map and array data structures, which can provide +an easier serialization experience in some cases. + +At the same time, YAML can be ambiguous about what types the data written into +it is. There's also a persistent issue where very large YAML files become +unmanageable, especially due to the significant indentation feature. + +KDL is designed to avoid these particular pitfalls by always being explicit +about types, and having clearly-delimited scope (and the ability to +auto-indent/auto-format). Syntax errors are easier to catch, and large files +are (hopefully!) much more manageable. + +#### What about JSON? + +JSON is a great serialization language, but it can be very difficult to use as +a human configuration language. This is largely due to its very specific, very +strict syntax, as well as its lack of support for comments. + +KDL, on the other hand, has great comment support, and has a much more +forgiving syntax without being so flexible as to allow certain classes of +unfortunate mistakes. It also has much more flexibility around how to +represent data. + +#### What about TOML? + +It nests very poorly. It doesn't fare well with large files. + +#### What about XML? + +XML is actually pretty fantastic, and has long been a standard for data +exchange across many industries. At the same time, XML is known to be very +verbose, and editing it involves writing (and updating) matching tags. Another +large pitfall with XML is its lack of direct support for arbitrary string +key/value pairs, so what would be a simple `foo: x` in some languages has to +be represented as `` or something similar. XML +also functions great as a **markup** language. That is, it is easy to +intersperse with text, like HTML. + +KDL, just like XML, is a node/element-based language, but with much more +lightweight syntax. It also adds the ability to apply anonymous values +directly to a node, rather than as children. That is, `nodename 1 2 3` instead +of `12(etc)`. This can make +it much more manageable and readable as a human configuration language, and is +also less verbose when exchanging documents across APIs! + +Finally, KDL is **not** a markup language. XML or HTML do a much better job of +"marking up" a text document with special tags, although KDL can still be +useful for templating engines that want to be more strict about text +fragments. + ## License Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. -