Add output formats section to README

and add additional specs.

README.md

@@ -180,6 +180,76 @@ The available extensions are:
 * `:autolink` - This provides support for automatically converting URLs to anchor tags.
 * `:tagfilter` - This escapes [several "unsafe" HTML tags](https://github.github.com/gfm/#disallowed-raw-html-extension-), causing them to not have any effect.
 
+## Output formats
+
+Like CMark, CommonMarker can generate output in several formats: HTML, XML, plaintext, and commonmark are currently supported.
+
+### HTML
+
+The default output format, HTML, will be generated when calling `to_html` or using `--to=html` on the command line.
+
+```ruby
+doc = CommonMarker.render_doc('*Hello* world!', :DEFAULT)
+puts(doc.to_html)
+
+<p><em>Hello</em> world!</p>
+```
+
+### XML
+
+XML will be generated when calling `to_xml` or using `--to=xml` on the command line.
+
+```ruby
+doc = CommonMarker.render_doc('*Hello* world!', :DEFAULT)
+puts(doc.to_xml)
+
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document SYSTEM "CommonMark.dtd">
+<document xmlns="http://commonmark.org/xml/1.0">
+  <paragraph>
+    <emph>
+      <text xml:space="preserve">Hello</text>
+    </emph>
+    <text xml:space="preserve"> world!</text>
+  </paragraph>
+</document>
+```
+
+### Plaintext
+
+Plaintext will be generated when calling `to_plaintext` or using `--to=plaintext` on the command line.
+
+```ruby
+doc = CommonMarker.render_doc('*Hello* world!', :DEFAULT)
+puts(doc.to_plaintext)
+
+Hello world!
+```
+
+### Commonmark
+
+Commonmark will be generated when calling `to_commonmark` or using `--to=commonmark` on the command line.
+
+``` ruby
+text = <<-TEXT
+1. I am a numeric list.
+2. I continue the list.
+* Suddenly, an unordered list!
+* What fun!
+TEXT
+
+doc = CommonMarker.render_doc(text, :DEFAULT)
+puts(doc.to_commonmark)
+
+1.  I am a numeric list.
+2.  I continue the list.
+
+<!-- end list -->
+
+  - Suddenly, an unordered list\!
+  - What fun\!
+```
+
 ## Developing locally
 
 After cloning the repo:

bin/commonmarker

@@ -57,7 +57,11 @@ def parse_options
 
     opts.on('-tFORMAT', '--to=FORMAT', String, 'Specify output FORMAT') do |value|
       value = value.to_sym
-      options.output_format = value if format_options.include?(value)
+      if format_options.include?(value)
+        options.output_format = value
+      else
+        abort("format '#{value}' not found")
+      end
     end
 
     opts.on('--html-renderer', 'Use the HtmlRenderer renderer rather than the native C renderer (only valid when format is html)') do
@@ -96,6 +100,11 @@ def parse_options
 end
 
 options = parse_options
+
+if options.renderer && options.output_format != :html
+  abort("format '#{options.output_format}' does not support using the HtmlRenderer renderer")
+end
+
 doc = CommonMarker.render_doc(ARGF.read, options.active_parse_options, options.active_extensions)
 
 case options.output_format

test/test_commands.rb

@@ -29,6 +29,13 @@ def test_understands_multiple_extensions
     %w[<table> <tr> <th> a </th> <td> c </td>].each { |html| assert_includes out, html }
   end
 
+  def test_understands_html_format_with_renderer_and_extensions
+    out = make_bin('table.md', '--to=html --extension=table,strikethrough --html-renderer')
+    refute_includes out, '| a'
+    assert_includes out, '<p><del>hi</del>'
+    %w[<table> <tr> <th> a </th> <td> c </td>].each { |html| assert_includes out, html }
+  end
+
   def test_understands_xml_format
     out = make_bin('strong.md', '--to=xml')
     assert_includes out, '<?xml version="1.0" encoding="UTF-8"?>'
@@ -44,4 +51,22 @@ def test_understands_plaintext_format
     out = make_bin('strong.md', '--to=plaintext')
     assert_equal('I am strong', out)
   end
+
+  def test_aborts_invalid_format
+    _out, err = capture_subprocess_io do
+      make_bin('strong.md', '--to=unknown')
+    end
+
+    assert_match "format 'unknown' not found", err
+  end
+
+  def test_aborts_format_and_html_renderer_combinations
+    (CommonMarker::Config::OPTS[:format] - [:html]).each do |format|
+      _out, err = capture_subprocess_io do
+        make_bin('strong.md', "--to=#{format} --html-renderer")
+      end
+
+      assert_match "format '#{format}' does not support using the HtmlRenderer renderer", err
+    end
+  end
 end

test/test_encoding.rb

@@ -9,6 +9,9 @@ def test_encoding
     doc = CommonMarker.render_doc(contents, :SMART)
     render = doc.to_html
     assert_equal('<p>This curly quote “makes commonmarker throw an exception”.</p>', render.rstrip)
+
+    render = doc.to_xml
+    assert_includes(render, '<text xml:space="preserve">This curly quote “makes commonmarker throw an exception”.</text>')
   end
 
   def test_string_content_is_utf8

test/test_xml.rb

@@ -24,7 +24,7 @@ def render_doc(doc)
     CommonMarker.render_doc(doc, :DEFAULT, [:table])
   end
 
-  def test_to_commonmark
+  def test_to_xml
     compare = render_doc(@markdown).to_xml(:SOURCEPOS)
 
     assert_equal <<~XML, compare
@@ -90,4 +90,18 @@ def test_to_commonmark
       </document>
     XML
   end
+
+  def test_to_xml_with_quotes
+    compare = render_doc('"quotes" should be escaped').to_xml(:DEFAULT)
+
+    assert_equal <<~XML, compare
+      <?xml version="1.0" encoding="UTF-8"?>
+      <!DOCTYPE document SYSTEM "CommonMark.dtd">
+      <document xmlns="http://commonmark.org/xml/1.0">
+        <paragraph>
+          <text xml:space="preserve">&quot;quotes&quot; should be escaped</text>
+        </paragraph>
+      </document>
+    XML
+  end
 end