From 825955d855aef61808affc3ec2984f35ec558bd0 Mon Sep 17 00:00:00 2001
From: Jeremy Wall <jeremy@marzhillstudios.com>
Date: Wed, 12 Dec 2018 20:26:42 -0600
Subject: [PATCH] DOCS: Add xml converter documentation to the docsite.

---
 docsite/site/content/reference/converters.md | 109 +++++++++++++++++++
 1 file changed, 109 insertions(+)

diff --git a/docsite/site/content/reference/converters.md b/docsite/site/content/reference/converters.md
index cd51a8b..b88f948 100644
--- a/docsite/site/content/reference/converters.md
+++ b/docsite/site/content/reference/converters.md
@@ -144,4 +144,113 @@ exec my-app --log-level debug --maxMem 2048M serve --port 8080
 The items in the args should be either strings or tuples. The tuples are turned into
 flags using the builtin flag converter.
 
+XML
+---
+
+XML can be output using a custom xml DSL.
+
+XML documents start with a tuple defining the document declaration and a root element.
+
+```
+{
+    version = "1.1" // Optional, Defaults to 1.1
+    encoding = "utf-8" // Optional, Defaults to UTF-8
+    standalone = true // Optional Defaults to false
+    root = { // Required defines the root element of the document.
+        name = "top",
+    }
+};
+```
+
+Nodes in the document can be defined as either xml elements or text nodes. An
+xml element is defined as a tuple with a required `name` field and the three
+optional fields `attrs`, `ns`, and `children`. 
+
+The `name` field is required and may optionally contain a namespace prefix like so:
+`prefix:element-name`.
+
+`attrs` if set is required to be a
+tuple or NULL. If NULL then no attributes are emitted If a tuple then each
+field is turned into an attribute on the element. The tuple should have only
+string values or null for each field. If NULL then the attribute is not set.
+
+`ns` if set is required to be either a string in which case the default xml namespace
+is set or a tuple with `prefix` and `uri` fields. which will define the prefix and uri for a namespace on that element.
+
+`children` is required to be a list of elements and text nodes or NULL. If NULL then no children are output.
+
+```
+{
+    name = "ns:element-name",
+    ns = {
+        prefix = "myns",
+        uri = "http://example.org",
+    },
+    attrs = {
+        id = "foo",
+    },
+    children = [
+        // child elements go here.
+    ],
+};
+```
+
+Text nodes can be output via two ways. Either just a string or as a tuple with a
+single field named text.
+
+```
+{
+    text = "This is a valid text node",
+};
+
+"This is also a valid text node";
+```
+
+### Example document
+```
+let doc = {
+    root = {
+        ns = {
+            prefix = "myns",
+            uri = "http://example.com",
+        },
+        name = "top",
+        attrs = {id = "foo"},
+        children = [
+            {
+                name = "child1",
+                ns = "http://example.org",
+                attrs = { attr1 = "value1", attr2 = "value2"},
+                children = [
+                    "inner text node",
+                    {
+                        name = "myns:grandchild",
+                        children = [
+                            {
+                                text = "Another text node",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    },
+};
+
+out xml doc;
+```
+This will result in the following xml document.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<top xmlns:myns="http://example.com" id="foo">
+  <child1 xmlns="http://example.org/" attr1="value1" attr2="value2">inner text node<myns:grandchild>Another text node</myns:grandchild>
+  </child1>
+</top>
+```
+
+### Caveats
+
+We don't support character CDATA sections in our xml document DSL at this time.
+
 Next: <a href="/how-to">HowTo Guides</a>
\ No newline at end of file