add test and document about diff params in literalinclude.

3 files changed, 28 insertions, 0 deletions

diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index 936080d6..c1d9c25f 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -180,6 +180,16 @@ Includes
    ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
    highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
 
+
+   If you want to show the diff of the code, you can specify the old
+   file by giving a ``diff`` option::
+
+      .. literalinclude:: example.py
+         :diff: example.py.orig
+
+   This shows the diff between example.py and example.py.orig with unified diff format.
+
+
    .. versionadded:: 0.4.3
       The ``encoding`` option.
    .. versionadded:: 0.6
@@ -187,6 +197,8 @@ Includes
       as well as support for absolute filenames.
    .. versionadded:: 1.0
       The ``prepend`` and ``append`` options, as well as ``tab-width``.
+   .. versionadded:: 1.3
+      The ``diff`` option.
 
 
 Showing a file name
diff --git a/tests/root/includes.txt b/tests/root/includes.txt
index 08917811..2a0d8b70 100644
--- a/tests/root/includes.txt
+++ b/tests/root/includes.txt
@@ -58,6 +58,9 @@ Literalinclude options
 .. literalinclude:: literal.inc
    :end-before: class Foo
 
+.. literalinclude:: literal.inc
+   :diff: literal.inc.orig
+
 .. cssclass:: inc-tab3
 .. literalinclude:: tabs.inc
    :tab-width: 3
diff --git a/tests/root/literal.inc.orig b/tests/root/literal.inc.orig
new file mode 100644
index 00000000..14fd214c
--- /dev/null
+++ b/tests/root/literal.inc.orig
@@ -0,0 +1,13 @@
+# Literally included file using Python highlighting
+# -*- coding: utf-8 -*-
+
+foo = "Including Unicode characters: üöä"  # This will be changed
+
+class FooOrig:
+    pass
+
+class BarOrig:
+    def baz():
+        pass
+
+def bar(): pass