# Use XML for the spec examples and tests? (comments welcome)

**URL:** <https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994>\
**Category:** Spec\
**Created:** [January 4, 2015, 4:36pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994 "2015-01-04T16:36:16Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [January 4, 2015, 4:36pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/1 "2015-01-04T16:36:16Z")

</div>

Currently the examples in the spec (which comprise the test suite) use HTML for the intended results. This has the advantage of being familiar, and of being directly useable for testing by parsers that generate HTML (though a normalization step is needed, and provided by `spec_tests.py`).

The problem is that this output is the result of two things, parsing the CommonMark input into an AST, and rendering the AST to HTML. It would make more sense, I think, to use a direct representation of the AST that matches it exactly. cmark now has a `-t xml` option that produces an XML representation of the AST (there is even a `dtd` for the format, `commonmark.dtd`).

Here’s an example:

```auto
% ./cmark -t xml
Hi *there*.
A new line

A new paragraph.

    f >>= g

<div>
  raw html
</div>

A [link](/url "title")
^D
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE CommonMark SYSTEM "CommonMark.dtd">
<document>
  <paragraph>
    <text>Hi </text>
    <emph>
      <text>there</text>
    </emph>
    <text>.</text>
    <softbreak />
    <text>A new line</text>
  </paragraph>
  <paragraph>
    <text>A new paragraph.</text>
  </paragraph>
  <code_block>f &gt;&gt;= g
</code_block>
  <html>&lt;div&gt;
  raw html
&lt;/div&gt;
</html>
  <paragraph>
    <text>A </text>
    <link url="/url" title="title">
      <text>link</text>
    </link>
  </paragraph>
</document>

```

(If the `--sourcepos` option is used, start and end line and column information will be included as attributes.)

So, the proposal for consideration is to replace the HTML parts of the spec examples with this XML format. To make it more compact, we’d strip out the `<?xml` declaration, the `DOCTYPE`, and the top `<document>` element.

It’s probably a good idea to retain the ability for people to test a converter that just produces HTML against the spec. We could do this by providing a standalone pipe that converts HTML to CommonMark’s XML format, raising an error if structures are encountered that can’t be converted. The test suite could then have an option that would run the HTML output of the program being tested through this pipe. (This would, in effect, replace normalization.)

Note that currently the parser sometimes produces adjacent text elements. For example, `hi&lo` turns into:

```auto
  <paragraph>
    <text>hi</text>
    <text>&amp;</text>
    <text>lo</text>
  </paragraph>

```

This is equivalent to

```auto
  <paragraph>
    <text>hi&amp;lo</text>
  </paragraph>

```

It would probably be good to tweak the parser so that adjacent text nodes are never produced, but we could also just add a normalization step to the test suite.

Comments on this?

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [January 4, 2015, 4:43pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/2 "2015-01-04T16:43:09Z")

</div>

Links to related discussions:

- [First steps towards an AST](http://talk.commonmark.org/t/first-steps-towards-an-ast/218) (@riking, I’d completely missed your effort when I added the XML export format and DTD; I see from your DTD some ways I can improve mine, so thanks!)

- [A handful of small spec issues](http://talk.commonmark.org/t/a-handful-of-small-spec-issues/109/4)

Here is the DTD for the XML format:

> <https://github.com/commonmark/CommonMark/blob/master/CommonMark.dtd>

---

<div class="post-metadata">

**Author:** ![Knagis](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/k/ba9def/32.png) [@Knagis](https://talk.commonmark.org/u/Knagis)\
**Post date:** [January 4, 2015, 9:33pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/3 "2015-01-04T21:33:42Z")

</div>

Could the spec contain both HTML and XML? Or at least, can the spec that will be put on the website show both (or allow the user to switch between formats)?

Perhaps the spec could contain a slightly simpler format for others to parse from the .txt by putting an extended XML there:

```
<example id="123">
  <source> **foo** </source>
  <html>&lt;strong&gt;foo&lt;/strong&gt;</html> <!--either encoded text or xhtml-->
  <document><strong><text>foo</text></strong></document>
<example>
```

---

<div class="post-metadata">

**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\
**Post date:** [January 4, 2015, 11:33pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/4 "2015-01-04T23:33:52Z")

</div>

I know 2 real cases to solve with XML:

- `\n` between tags. 0.13 solved almost everyting, but there are still couple of cases, where `\n` removal is preferable (imho).
- XML-like output (and kludge option) in `markdown-it` is needed for CM tests only. Default renderer is targeted for HTML5.

In general should be good. But i never worked with such kind of specs (with embedded xml), and don’t know about possible difficulties.

---

<div class="post-metadata">

**Author:** ![lu\_zero](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/lu_zero/32/557_2.png) [@lu\_zero](https://talk.commonmark.org/u/lu_zero)\
**Post date:** [January 5, 2015, 6:50pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/5 "2015-01-05T18:50:24Z")

</div>

xml for that is surely better than other serialization even if pretty-printed json usually is nicer to read.

---

<div class="post-metadata">

**Author:** ![colinodell](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/colinodell/32/343_2.png) [@colinodell](https://talk.commonmark.org/u/colinodell)\
**Post date:** [January 7, 2015, 8:13pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/6 "2015-01-07T20:13:56Z")

</div>

> [@Knagis](#):
>
> Could the spec contain both HTML and XML?

+1

I think both formats would be incredibly valuable. XML is a great idea for verifying the AST, whereas HTML is beneficial for human understanding and libraries who’d like to maintain similar output as the reference implementations.

On the website, perhaps the users could toggle between HTML and XML renderings, similar to how [Microsoft shows code examples in C# and VB](http://msdn.microsoft.com/en-us/library/hh191443.aspx#BKMK_HowtoWriteanAsyncMethod)?

---

<div class="post-metadata">

**Author:** ![zudov](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/z/ed655f/32.png) [@zudov](https://talk.commonmark.org/u/zudov)\
**Post date:** [February 23, 2015, 1:32am UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/7 "2015-02-23T01:32:58Z")

</div>

> [@Knagis](#):
>
> Could the spec contain both HTML and XML?

That would be nice. For myself, I’ve added this script to `spec.html` to replace html with xml:

```javascript
<script type="text/javascript">
var reader = new commonmark.Parser();
var writer = new commonmark.XmlRenderer();

var examples = $(".example");
var toAST = function(el, example) {
    example = $(example);
    var markdown = example.find(".language-markdown"),
        html = example.find(".language-html");
    html.text(writer.render(reader.parse(markdown.text())));
}
examples.map(toAST);
});

```

(js is not my language)

---

<div class="post-metadata">

**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\
**Post date:** [March 11, 2015, 1:32pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/8 "2015-03-11T13:32:32Z")

</div>

@jgm, we finished refactoring renterer of `markdown-it`, and i’d like to summarize my personal impressions, related to this topic:

- I don’t need XML. Current HTML samples are ok for my needs and more simple.

Details:

1. Links.

- Current links of 0.18 spec a friendly enougth to “critical” normalizations
- In href we encode hostname with IDNa, and percent-encode the rest. No conflicts.
- In link texts (autolinks, linkify - not manually typed) we decode hostname with IDNa and percent-decode text. No conflicts, because spec has no conditions and tests for that…

1. Line breaks between tags:

- the only difference if that you add `\n` in emply blockquote. We update fixtures by stupid regexp, that’s enougth.

So, i have nothing against XML, but vote to keep HTML too and leave choice to developpers what to use. For examples HTML is more convenient. For tests - depends on implementation.

---

<div class="post-metadata">

**Author:** ![tin-pot](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tin-pot/32/810_2.png) [@tin-pot](https://talk.commonmark.org/u/tin-pot)\
**Post date:** [October 25, 2015, 6:28pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/9 "2015-10-25T18:28:06Z")

</div>

Excuse me for “unearthing” this old post; but it relates to some questions and experiences I recently made in my [own project](https://github.com/tin-pot/cmark).

I think the “right thing” to concentrate on when it comes to testing is a representation which is independant of the vagaries of mark-up: the “[Canonical XML](http://www.w3.org/TR/xml-c14n)” form seems to be exactly that.

So in order to compare actual output with reference material (eg for regression testing), one would either

- devise a mode in which _Canonical XML_ is output; or
- “canonicalize” the actual output and _then_ compare with the (canonical) reference.

As long as the output has the same canonical form, any remaining differences in the regular XML output should be immaterial.

Note however that the current output of `cmark -t xml` _does_ include white space which _will_ show up in the canonical form—only when validating against the DTD can the decision be made that this white space is _in fact_ irrelevant (eg inside elements that do _not_ have character data content). So from a testing perspective, and for “sanitary” reasons generally, probably `cmark` _should_ write XML that does _not_ have this gratuitous white space _in it’s canonical form_. Or do it optionally, if the resulting XML would be “too ugly”.

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [October 27, 2015, 8:49pm UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/10 "2015-10-27T20:49:55Z")

</div>

See [https://github.com/jgm/CommonMark/issues/274](https://github.com/jgm/CommonMark/issues/274)

I’ll note that having white space is very useful for diffs.

---

<div class="post-metadata">

**Author:** ![tin-pot](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tin-pot/32/810_2.png) [@tin-pot](https://talk.commonmark.org/u/tin-pot)\
**Post date:** [December 23, 2015, 2:48am UTC](https://talk.commonmark.org/t/use-xml-for-the-spec-examples-and-tests-comments-welcome/994/11 "2015-12-23T02:48:45Z")

</div>

I have added some remarks on the issue over there at [https://github.com/jgm/CommonMark/issues/274](https://github.com/jgm/CommonMark/issues/274).

Btw, what do you mean by “having white space is very useful for diffs”? Maybe that “having the text broken into lines” is very useful for diffs, because diffs are usually line-oriented?