Merge 5ae1f5a into 6e69693

CHANGES.rst

@@ -4,7 +4,8 @@ Changes
 2.0b3 (unreleased)
 ------------------
 
-- Nothing changed yet.
+- Replaced the example RMLFormatter with a more generic HTML formatter,
+  although it only handles HTML snippets at the moment.
 
 
 2.0b2 (2018-09-06)

MANIFEST.in

@@ -5,7 +5,7 @@ include .coveragerc
 include Makefile
 recursive-include tests *.py
 recursive-include tests *.xml
-recursive-include tests *.rml
+recursive-include tests *.html
 recursive-include docs *.bat
 recursive-include docs *.py
 recursive-include docs *.rst

docs/source/api.rst

@@ -11,13 +11,11 @@ you just import and call one of the three main API methods.
   :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
 
   >>> from xmldiff import main
-  >>> main.diff_files("../tests/test_data/insert-node.left.rml",
-  ...                 "../tests/test_data/insert-node.right.rml")
-  [UpdateTextIn(node='/document/story[1]', text=None),
-   InsertNode(target='/document/story[1]', tag='h1', position=0),
-   UpdateTextIn(node='/document/story/h1[1]', text='Inserted '),
-   InsertNode(target='/document/story/h1[1]', tag='i', position=0),
-   UpdateTextIn(node='/document/story/h1/i[1]', text='Node')]
+  >>> main.diff_files("../tests/test_data/insert-node.left.html",
+  ...                 "../tests/test_data/insert-node.right.html")
+  [UpdateTextIn(node='/body/div[1]', text=None),
+   InsertNode(target='/body/div[1]', tag='p', position=0),
+   UpdateTextIn(node='/body/div/p[1]', text='Simple text')]
 
 Which one you choose depends on if the XML is contained in files,
 text strings or ``lxml`` trees.
@@ -62,7 +60,7 @@ If no formatter is specified the diff functions will return a list of actions.
 Such a list is called an edit script and contains all changes needed to transform the "left" XML into the "right" XML.
 
 If a formatter is specified that formatter determines the result.
-The included formatters, ``diff``, ``xml``, and ``rml`` all return a Unicode string.
+The included formatters, ``diff``, ``xml``, and ``html`` all return a Unicode string.
 
 
 Unique Attributes
@@ -88,7 +86,7 @@ Using Formatters
 By default the diff functions will return an edit script,
 but if you pass in a formatter the result will be whatever that formatter returns.
 
-The three included formatters, ``diff``, ``xml`` and ``rml``,
+The three included formatters, ``diff``, ``xml`` and ``html``,
 all return Unicode strings.
 The ``diff`` formatter will return a string with the edit script printed out,
 one action per line.
@@ -103,14 +101,12 @@ so the output is not compatible.
 
   >>> from xmldiff import formatting
   >>> formatter = formatting.DiffFormatter()
-  >>> print(main.diff_files("../tests/test_data/insert-node.left.rml",
-  ...                       "../tests/test_data/insert-node.right.rml",
+  >>> print(main.diff_files("../tests/test_data/insert-node.left.html",
+  ...                       "../tests/test_data/insert-node.right.html",
   ...                       formatter=formatter))
-  [update-text, /document/story[1], null]
-  [insert, /document/story[1], h1, 0]
-  [update-text, /document/story/h1[1], "Inserted "]
-  [insert, /document/story/h1[1], i, 0]
-  [update-text, /document/story/h1/i[1], "Node"]
+  [update-text, /body/div[1], null]
+  [insert, /body/div[1], p, 0]
+  [update-text, /body/div/p[1], "Simple text"]
 
 
 The other two differs return XML with tags describing the changes.
@@ -121,17 +117,17 @@ for example with XSLT replacing the tags with the format you need.
   :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
 
   >>> from xmldiff import formatting
-  >>> formatter = formatting.RMLFormatter()
-  >>> print(main.diff_files("../tests/test_data/insert-node.left.rml",
-  ...                       "../tests/test_data/insert-node.right.rml",
+  >>> formatter = formatting.HTMLFormatter()
+  >>> print(main.diff_files("../tests/test_data/insert-node.left.html",
+  ...                       "../tests/test_data/insert-node.right.html",
   ...                       formatter=formatter))
-  <document xmlns:diff="http://namespaces.shoobx.com/diff" title="insert-node">
-    <story id="id">
-      <h1 diff:insert="">
-        <diff:insert>Inserted <i>Node</i></diff:insert>
-      </h1>
-    </story>
-  </document>
+  <body xmlns:diff="http://namespaces.shoobx.com/diff">
+    <div id="id">
+      <p diff:insert="">
+        <diff:insert>Simple text</diff:insert>
+      </p>
+    </div>
+  </body>
 
 
 The Edit Script

docs/source/commandline.rst

@@ -63,14 +63,11 @@ since the whitespace there occurs inside a tag:
   <data count="1">    </data><data count="2"></data>
 
 In some XML formats, whitespace inside some tags is also not significant.
-The ``rml`` formatter is an example of this.
-It's a format that can be used to generate documents,
-and has a ``<para>`` tag for formatted text,
-similar to HTML's ``<p>`` tag.
-The ``rml`` formatter is aware of this,
+The ``html`` formatter is an example of this.
+ It is aware of that ``<p>`` tags contain text where whitespace isn't significant,
 and will by default normalize whitespace inside these tags before comparing it,
 effectively replacing any whitespace inside those tags to a single space.
-This is so that when diffing two versions of RML files you will not see changes that would not be visible in the final document.
+This is so that when diffing two versions of HTML files you will not see changes that would not be visible in the final document.
 
 Both of these types of whitespace can be preserved with the ``--keep-whitespace`` argument.
 The third case of whitespace,
@@ -87,7 +84,7 @@ The term "pretty printing" refers to making an output a bit more human readable
 In the case of XML this means inserting ignorable whitespace into the XML,
 yes, the same in-between whitespace that is ignored by ``xmldiff`` when detecting changes between two files.
 
-``xmldiff``'s ``xml`` and ``rml`` formatters understand the ``--pretty-print`` argument and will insert whitespace to make the output more readable.
+``xmldiff``'s ``xml`` and ``html`` formatters understand the ``--pretty-print`` argument and will insert whitespace to make the output more readable.
 
 For example, an XML output that would normally look like this:
 

tests/test_data/complex-text-update.expected.html

@@ -0,0 +1,5 @@
+<body xmlns:diff="http://namespaces.shoobx.com/diff">
+  <div id="id">
+    <p><diff:insert>Let's see. </diff:insert>This is some simple text demonstrating the features of the <b diff:delete-formatting=""><i diff:insert-formatting="">human text differ</i></b>. This <u diff:delete-formatting="">feature</u> attempts to make changelog readable for humans. The <i diff:insert-formatting="">human text differ</i> uses sentences as its first order matching. <diff:delete>Let's see.</diff:delete><invalid><diff:insert>It should handle unknown tags just fine.</diff:insert></invalid></p>
+  </div>
+</body>

tests/test_data/complex-text-update.left.rml → tests/test_data/complex-text-update.left.html

@@ -1,12 +1,12 @@
-<document title="insert-node">
-  <story id="id">
+<body>
+  <div id="id">
 
-    <para>
+    <p>
       This is some simple text demonstrating the features of the <b>human text
       differ</b>. This <u>feature</u> attempts to make changelog readable for
       humans. The human text differ uses sentences as its first order
       matching. Let's see.
-    </para>
+    </p>
 
-  </story>
-</document>
+  </div>
+</body>

tests/test_data/complex-text-update.right.rml → tests/test_data/complex-text-update.right.html

@@ -1,12 +1,12 @@
-<document title="insert-node">
-  <story id="id">
+<body>
+  <div id="id">
 
-    <para>
+    <p>
       Let's see. This is some simple text demonstrating the features of the
       <i>human text differ</i>. This feature attempts to make changelog
       readable for humans. The <i>human text differ</i> uses sentences as its
-      first order matching.
-    </para>
+      first order matching. <invalid>It should handle unknown tags just fine.</invalid>
+    </p>
 
-  </story>
-</document>
+  </div>
+</body>

tests/test_data/insert-node.expected.html

@@ -0,0 +1,7 @@
+<body xmlns:diff="http://namespaces.shoobx.com/diff">
+  <div id="id">
+    <p diff:insert="">
+      <diff:insert>Simple text</diff:insert>
+    </p>
+  </div>
+</body>

tests/test_data/insert-node.left.html

@@ -0,0 +1,4 @@
+<body>
+  <div id="id">
+  </div>
+</body>

tests/test_data/insert-node.right.html

@@ -0,0 +1,5 @@
+<body>
+  <div id="id">
+    <p>Simple text</p>
+  </div>
+</body>