diff --git a/JSON-IN-KDL.md b/JSON-IN-KDL.md index 5340cce..7ccf76b 100644 --- a/JSON-IN-KDL.md +++ b/JSON-IN-KDL.md @@ -13,7 +13,7 @@ JSON-in-KDL (JiK from now on) is a kdl microsyntax consisting of three types of ---- -Literal nodes are used to represent a JSON literal, which luckily KDL's literal syntax is a superset of. They contain a single value, the literal they're representing. For example, to represent the JSON literal `true`, you'd write `- true` in JiK. +Literal nodes are used to represent a JSON literal, which luckily KDL's literal syntax is a superset of. They contain a single value, the literal they're representing. For example, to represent the JSON literal `true`, you'd write `- #true` in JiK. (In many cases this isn't necessary, and KDL literals can be directly used instead. Literal nodes are necessary only for a top-level literal, or to intersperse literals with arrays or objects inside an array or object node.) @@ -26,7 +26,7 @@ This means that simple arrays of literals can be written compactly and simply; a ```kdl array { - 1 - array true false + array #true #false - 3 } ``` @@ -35,7 +35,7 @@ The two methods of writing children can be mixed, pulling the prefix of the arra ```kdl array 1 { - array true false + array #true #false - 3 } ``` @@ -44,14 +44,14 @@ array 1 { Object nodes are used to represent a JSON object. They can contain zero or more named properties, followed by zero or more child nodes; these are taken as the key/value pairs of the object, in order of appearance. -If the value of a key/value pair is a literal, it can be encoded as a named property on the object. For example, the JSON object `{"foo": 1, "bar": true}` could be written in JiK as `object foo=1 bar=true`. +If the value of a key/value pair is a literal, it can be encoded as a named property on the object. For example, the JSON object `{"foo": 1, "bar": true}` could be written in JiK as `object foo=1 bar=#true`. Alternately, key/value pairs can be encoded as child nodes, using a type annotation on the node name to encode the key, and the node itself as the value. The preceding example could instead have been written as: ```kdl object { (foo)- 1 - (bar)- true + (bar)- #true } ``` diff --git a/XML-IN-KDL.md b/XML-IN-KDL.md index 8cb64fa..32ce487 100644 --- a/XML-IN-KDL.md +++ b/XML-IN-KDL.md @@ -25,7 +25,7 @@ XML elements and KDL nodes have a direct correspondence. In XiK, an XML element * making the attributes into KDL properties * making the child nodes as KDL child nodes -For example, the XML `` is encoded into XiK as `element foo="bar" { child baz="qux" }`. +For example, the XML `` is encoded into XiK as `element foo=bar { child baz=quux }`. XML namespaces are encoded the same as XML: the node name simply contains a `:` character. Note that KDL identifier syntax allows `:` directly in an ident, so a name like `xml:space` or `xlink:href` is a valid node or property name. @@ -35,9 +35,9 @@ Raw text contents of an element can be encoded in two possible ways. If the element contains *only* text, it should be encoded as a final string unnamed argument. For example, the XML `here's a link` can be encoded as `a href="http://example.com" "here's a link"`. -If the element contains mixed text and element children, the text can be encoded as a KDL node with the name `-` with a single string unnamed argument. For example, the XML `some bold text` can be encoded as `span { - "some "; b "bold"; - " text" }`. +If the element contains mixed text and element children, the text can be encoded as a KDL node with the name `-` with a single string unnamed argument. For example, the XML `some bold text` can be encoded as `span { - "some "; b bold; - " text" }`. -An element that contains only text *is allowed to* encode it as `-` children. For example, `foo` *may* be encoded as `span { - "foo" }` instead of `span "foo"`. However, an element cannot mix the "final string attribute" with child nodes; `span "foo" { b "bar" }` is an **invalid** encoding of `foobar`. (It must be encoded as `span { - "foo"; b "bar" }`.) +An element that contains only text *is allowed to* encode it as `-` children. For example, `foo` *may* be encoded as `span { - foo }` instead of `span foo`. However, an element cannot mix the "final string attribute" with child nodes; `span foo { b bar }` is an **invalid** encoding of `foobar`. (It must be encoded as `span { - foo; b bar }`.) CDATA sections are not preserved in this encoding, as they are merely a source convenience so you don't have to escape a bunch of characters. They are encoded as normal textual contents would be. @@ -53,13 +53,13 @@ Processing instructions and XML declarations (nodes that look like ` The contents of a PI are technically completely unstructured. However, in practice most PIs' contents look like start-tag attributes. If this is the case, they should be encoded as properties on the node, with string values. For example, `` is encoded as `?xml version="1.0"`. -If the contents of a PI do *not* look like attributes, then instead the entire contents (from the end of the whitespace following the PI name, to the closing `?>` characters) are encoded as a single unnamed string value. For example, the preceding XML declaration *could* be alternately encoded as `?xml r#"version="1.0""#` (but shouldn't be). +If the contents of a PI do *not* look like attributes, then instead the entire contents (from the end of the whitespace following the PI name, to the closing `?>` characters) are encoded as a single unnamed string value. For example, the preceding XML declaration *could* be alternately encoded as `?xml #"version="1.0""#` (but shouldn't be). (Note that XML declarations are not needed when writing XiK directly; the version is always 1.0, and the encoding is always UTF-8 since it's KDL.) ---- -Doctypes (nodes that look like ``) are encoded similarly to unstructured Processing Instructions. They have a node name of `!doctype`, and the entire contents of the node, from the end of the whitespace following the "DOCTYPE" to the closing `>`, are encoded as a single unnamed string value. For example, the HTML doctype `` is encoded as `!doctype "html"`, while the XHTML 1 Strict doctype would be encoded as `!doctype r#"html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd""#` +Doctypes (nodes that look like ``) are encoded similarly to unstructured Processing Instructions. They have a node name of `!doctype`, and the entire contents of the node, from the end of the whitespace following the "DOCTYPE" to the closing `>`, are encoded as a single unnamed string value. For example, the HTML doctype `` is encoded as `!doctype html`, while the XHTML 1 Strict doctype would be encoded as `!doctype #"html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd""#` ----