Initial commit.

docsrc/articles/spec_differences.rst

@@ -0,0 +1,65 @@
+.. highlight:: yaml
+
+=====================================================
+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. D:YAML 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:
+
+* At the moment, all mappings in the internal representation are ordered,
+  and a comparison for equality between equal mappings with differing order
+  will return false. This will be fixed once Phobos has a usable map type or
+  D associative arrays work with variants.
+* 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.