convert docs to markdown and remove built doc artifacts (#153)

convert docs to markdown and remove built doc artifacts
merged-on-behalf-of: BBasile <BBasile@users.noreply.github.com>

docs/articles/spec_differences.md

@@ -0,0 +1,64 @@
+# Differences between D:YAML and the YAML specification
+
+There are some differences between D:YAML and the YAML 1.1
+specification. Some are caused by difficulty of implementation of some
+features, such as multiple Unicode encodings within single stream, and
+some by unnecessary restrictions or ambiguities in the specification.
+
+Still, D:YAML tries to be as close to the specification as possible. It
+should never load documents with different meaning than according to the
+specification, and documents that fail to load should be very rare (for
+instance, very few files use multiple Unicode encodings).
+
+## List of known differences:
+
+Differences that can cause valid YAML documents not to load:
+
+  - No support for byte order marks and multiple Unicode encodings in a
+    stream.
+
+  - Plain scalars in flow context cannot contain `,`, `:` and `?`. This
+    might change with `:` in the future. See
+    <http://pyyaml.org/wiki/YAMLColonInFlowContext> for details.
+
+  - The specification does not restrict characters for anchors and
+    aliases. This may lead to problems, for instance, the document:
+
+        [ *alias, value ]
+
+    can be interpteted in two ways, as:
+
+        [ "value" ]
+
+    and:
+
+        [ *alias , "value" ]
+
+    Therefore we restrict aliases and anchors to ASCII alphanumeric
+    characters.
+
+  - The specification is confusing about tabs in plain scalars. We don't
+    use tabs in plain scalars at all.
+
+  - There is no support for recursive data structures in DYAML.
+
+Other differences:
+
+  - Indentation is ignored in the flow context, which is less
+    restrictive than the specification. This allows code such as:
+
+        key: {
+        }
+
+  - Indentation rules for quoted scalars are loosed: They don't need to
+    adhere indentation as `"` and `'` clearly mark the beginning and the
+    end of them.
+
+  - We allow `_` in tag handles.
+
+  - Right now, two mappings with the same contents but different
+    orderings are considered unequal, even if they are unordered
+    mappings. This is because all mappings are ordered in the D:YAML
+    implementation. This should change in future, once D associative
+    arrays work with variant types or a map class or struct appears in
+    Phobos.