### Clone Repository and Setup Development Environment

Source: https://xmldiff.readthedocs.io/en/stable/_sources/contributing.rst

Instructions to clone the xmldiff repository and install development dependencies using make. This sets up the local environment for development and testing.

```bash
git clone git@github.com:Shoobx/xmldiff.git
cd xmldiff
make devenv
```

--------------------------------

### InsertAttrib Action Example in Python

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Demonstrates the InsertAttrib action, which adds a new attribute with a specified name and value to a target node in an XML document.

```python
>>> left = '<document><node/></document>'
>>> right = '<document newattr="newvalue"><node/></document>'
>>> main.diff_texts(left, right)
[InsertAttrib(node='/document[1]', name='newattr',
                value='newvalue')]
```

--------------------------------

### RenameAttrib Action Example in Python

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Shows the RenameAttrib action, which renames an existing attribute of a node. It requires the node, the old attribute name, and the new attribute name.

```python
>>> left = '<document attrib="value"><node/></document>'
>>> right = '<document newattrib="value"><node/></document>'
>>> main.diff_texts(left, right)
[RenameAttrib(node='/document[1]', oldname='attrib',
                newname='newattrib')]
```

--------------------------------

### DeleteNode Action Example in Python

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Illustrates the DeleteNode action for removing a specified node from an XML document. The 'node' argument indicates which node to delete.

```python
>>> left = '<document><node>Content</node></document>'
>>> right = '<document/>'
>>> main.diff_texts(left, right)
[DeleteNode(node='/document/node[1]')]
```

--------------------------------

### MoveNode Action Example in Python

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Shows how to use the MoveNode action to relocate a node to a different parent or position within the same parent. The 'position' argument determines the new child index (0-based).

```python
>>> left = '<document><node>Content</node><movenode/></document>'
>>> right = '<document><movenode/><node>Content</node></document>'
>>> main.diff_texts(left, right)
[MoveNode(node='/document/node[1]', target='/document[1]',
            position=1)]
```

--------------------------------

### Run xmldiff Command-Line Tool

Source: https://xmldiff.readthedocs.io/en/stable/_sources/commandline.rst

Execute the xmldiff command-line tool to compare two XML files. This is the most basic usage. Ensure the xmldiff tool is installed and accessible in your system's PATH.

```bash
$ xmldiff file1.xml file2.xml
```

--------------------------------

### DiffFormatter Usage Example

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Demonstrates the use of DiffFormatter to output an edit script detailing differences between two HTML files. The output format is one action per line, enclosed in brackets with the action and its arguments. It requires the xmldiff.formatting module and the main diff_files function.

```python
from xmldiff import formatting

formatter = formatting.DiffFormatter()
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

--------------------------------

### DeleteNode Action Example in Python

Source: https://xmldiff.readthedocs.io/en/stable/api

Illustrates the DeleteNode edit action, which signifies the removal of a specified node from the XML tree.

```python
from xmldiff import main

left = '<document><node>Content</node></document>'
right = '<document/>'
print(main.diff_texts(left, right))
```

--------------------------------

### InsertNode Action Example in Python

Source: https://xmldiff.readthedocs.io/en/stable/api

Demonstrates the InsertNode edit action, which represents adding a new node as a child to a specified target node in the XML tree.

```python
from xmldiff import main

left = '<document><node>Content</node></document>'
right = '<document><node>Content</node><newnode/></document>'
print(main.diff_texts(left, right))
```

--------------------------------

### InsertNode Action Example in Python

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Demonstrates how to use the InsertNode action to add a new node to an XML document. The 'position' argument specifies the insertion point, with 0 being the first child. This differs from XPath's 1-based indexing.

```python
>>> left = '<document><node>Content</node></document>'
>>> right = '<document><node>Content</node><newnode/></document>'
>>> main.diff_texts(left, right)
[InsertNode(target='/document[1]', tag='newnode', position=1)]
```

--------------------------------

### xmldiff XML Formatter Example

Source: https://xmldiff.readthedocs.io/en/stable/_sources/commandline.rst

Use the 'xml' formatter to output differences marked up with tags from the 'diff' namespace. This formatter is useful for programmatic processing of differences. It also supports pretty-printing for human readability.

```xml
<document>
  <story>Some content</story>
  <story>
    <para>This is some simple text with <i>formatting</i>.</para>
  </story>
</document>
```

--------------------------------

### XmlDiffFormatter Usage Example

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Shows how to use XmlDiffFormatter to produce an XML-like output representing the differences between two HTML files. This formatter's output is more similar to older versions of xmldiff. It utilizes the xmldiff.formatting module and the main diff_files function, with an option to disable whitespace normalization.

```python
from xmldiff import formatting

formatter = formatting.XmlDiffFormatter(normalize=formatting.WS_NONE)
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

--------------------------------

### Run Flake8 Code Linter

Source: https://xmldiff.readthedocs.io/en/stable/_sources/contributing.rst

Command to run the flake8 linter, which checks for style guide enforcement and potential errors in the Python code. This is part of the quality assurance process.

```bash
make flake
```

--------------------------------

### XMLFormatter Usage Example

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Illustrates the use of XMLFormatter to generate an XML output that highlights changes between two HTML files. This formatter can be configured with parameters like `text_tags` and `formatting_tags` to better represent human-readable and formatting elements. It uses the xmldiff.formatting module and the main diff_files function, with whitespace normalization enabled.

```python
from xmldiff import formatting

formatter = formatting.XMLFormatter(normalize=formatting.WS_BOTH)
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

--------------------------------

### InsertNode Action Example

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Defines the InsertNode action within the xmldiff edit script. This action signifies that a new subnode needs to be added to a specified target node, with the tag name for the new node also provided.

```python
InsertNode(target, tag, position)
```

--------------------------------

### Python: Diff XML Strings using xmldiff Main API

Source: https://xmldiff.readthedocs.io/en/stable/api

Compares two XML strings and returns the differences as an edit script or a formatted string. The `xmldiff` library must be installed. Input is expected as Unicode strings.

```python
from xmldiff import main

xml_string1 = "<root><item id=\"1\">Old text</item></root>"
xml_string2 = "<root><item id=\"1\">New text</item></root>"

# Diff two XML strings
diff_result = main.diff_texts(xml_string1, xml_string2)
print(diff_result)
```

--------------------------------

### Python: Diff XML Trees using xmldiff Main API

Source: https://xmldiff.readthedocs.io/en/stable/api

Compares two lxml XML trees and returns the differences. This function is suitable when XML is already parsed into tree objects. Ensure lxml is installed and import `etree`.

```python
from xmldiff import main
from lxml import etree

xml_tree1 = etree.fromstring("<root><element>A</element></root>")
xml_tree2 = etree.fromstring("<root><element>B</element></root>")

# Diff two lxml trees
tree_diff = main.diff_trees(xml_tree1, xml_tree2)
print(tree_diff)
```

--------------------------------

### Python Setup.py Test Command

Source: https://xmldiff.readthedocs.io/en/stable/_sources/contributing.rst

This command executes the test suite using the setuptools 'test' command. It's a standard way to run tests for Python packages.

```python
python setup.py test
```

--------------------------------

### Generate Sphinx Documentation

Source: https://xmldiff.readthedocs.io/en/stable/_sources/contributing.rst

Commands to navigate to the docs directory and generate the HTML documentation using Sphinx. This process builds the project's official documentation.

```bash
cd docs
make html
```

--------------------------------

### Run Development Environment Tests and Checks

Source: https://xmldiff.readthedocs.io/en/stable/_sources/contributing.rst

Commands to execute the test suite, syntax checkers, and style checkers within the development environment. These commands ensure the project's integrity and adherence to coding standards.

```bash
make test
make check
make
```

--------------------------------

### DiffFormatter Usage in Python

Source: https://xmldiff.readthedocs.io/en/stable/api

Demonstrates using the DiffFormatter to output an edit script as a string with one action per line. This formatter is suitable for command-line use.

```python
from xmldiff import formatting
from xmldiff import main

formatter = formatting.DiffFormatter()
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

--------------------------------

### Diff Texts with Complex HTML Formatting (Python)

Source: https://xmldiff.readthedocs.io/en/stable/advanced

Demonstrates diffing text with embedded HTML formatting using the XMLFormatter. Shows how unoptimized formatting can lead to verbose diffs.

```python
formatter=formatting.XMLFormatter()
left = '<body><p>My Fine Content</p></body>'
right = '<body><p><b>My <i>Fine</i> Content</b></p></body>'
result = main.diff_texts(left, right, formatter=formatter)
print(result)
```

--------------------------------

### Python Unittest Module

Source: https://xmldiff.readthedocs.io/en/stable/_sources/contributing.rst

This command directly invokes the unittest module from the Python standard library to discover and run tests. It's a fundamental way to execute tests without external runners.

```python
python -m unittest
```

--------------------------------

### Diffing HTML with Default Options

Source: https://xmldiff.readthedocs.io/en/stable/advanced

Compares two HTML strings using the default xmldiff algorithm. The output shows node movements, indicating that paragraphs are recognized as distinct blocks that have been reordered.

```python
left = u"""<html><body>
  <p>The First paragraph</p>
  <p>A Second paragraph</p>
  <p>Last paragraph</p>
</body></html>"""
right = u"""<html><body>
  <p>Last paragraph</p>
  <p>A Second paragraph</p>
  <p>The First paragraph</p>
</body></html>"""
result = main.diff_texts(left, right)
print(result)
```

--------------------------------

### XMLFormatter Usage in Python

Source: https://xmldiff.readthedocs.io/en/stable/api

Illustrates using the XMLFormatter to generate an XML output representing the differences, with options for pretty printing and text/formatting tag identification.

```python
from xmldiff import formatting
from xmldiff import main

formatter = formatting.XMLFormatter(normalize=formatting.WS_BOTH)
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

--------------------------------

### Python: Diff XML Files using xmldiff

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Compares two XML files and returns a list of differences or a formatted string. It takes file paths as input and allows customization of diffing behavior through `diff_options`.

```python
from xmldiff import main

# Example usage for diff_files
differences = main.diff_files("path/to/file1.xml", "path/to/file2.xml", diff_options={'F': 0.5, 'ratio_mode': 'fast'})
print(differences)
```

--------------------------------

### Diff HTML with basic formatting

Source: https://xmldiff.readthedocs.io/en/stable/_sources/advanced.rst

Demonstrates diffing two HTML strings and printing the result with basic formatting tags like bold and italics inserted.

```python
from xmldiff import main
from xmldiff.formatting import HTMLFormatter

left = u"""<html><body>
  <p>The First paragraph</p>
  <p>A Second paragraph</p>
  <p>Last paragraph</p>
</body></html>"""
right = u"""<html><body>
  <p>Last paragraph</p>
  <p>A Second paragraph</p>
  <p>The First paragraph</p>
</body></html>"""

formatter = HTMLFormatter(
    formatting_tags=('b', 'u', 'i', 'strike', 'em', 'super',
                     'sup', 'sub', 'link', 'a', 'span'))
result = main.diff_texts(left, right, formatter=formatter)
print(result)
```

--------------------------------

### Diffing HTML with Fast Match and HTMLFormatter

Source: https://xmldiff.readthedocs.io/en/stable/advanced

Compares two HTML strings using the 'fast_match' option and an HTMLFormatter. The output shows text differences within paragraphs using <del> and <ins> tags, offering a more granular and readable diff.

```python
result = main.diff_texts(left, right,
    diff_options={'fast_match': True},
    formatter=formatter)
print(result)
```

--------------------------------

### Diffing HTML with Fast Match Algorithm

Source: https://xmldiff.readthedocs.io/en/stable/advanced

Compares two HTML strings using the 'fast_match' performance option. This algorithm identifies text updates within nodes rather than whole node movements, leading to a different diff result.

```python
result = main.diff_texts(left, right,
    diff_options={'fast_match': True})
print(result)
```

--------------------------------

### Generate Code Coverage Report

Source: https://xmldiff.readthedocs.io/en/stable/_sources/contributing.rst

Command to generate an HTML report detailing code coverage for the xmldiff project. This is useful for identifying areas of the code that are not adequately tested.

```bash
make coverage
```

--------------------------------

### Reformat XML with xmldiff

Source: https://xmldiff.readthedocs.io/en/stable/_sources/commandline.rst

Utilize the 'xml' formatter with the '--pretty-print' option to reformat an XML file, making it more human-readable. This command takes an XML file and outputs a reformatted version of the same file.

```bash
$ xmldiff -f xml -p uglyfile.xml uglyfile.xml
```

--------------------------------

### Diffing HTML with HTMLFormatter

Source: https://xmldiff.readthedocs.io/en/stable/advanced

Compares two HTML strings using the default xmldiff algorithm and an HTMLFormatter. The output is formatted as HTML, marking moved paragraphs with diff:delete and diff:insert attributes.

```python
formatter = HTMLFormatter(
    normalize=formatting.WS_BOTH)
result = main.diff_texts(left, right, formatter=formatter)
print(result)
```

--------------------------------

### XmlDiffFormatter Usage in Python

Source: https://xmldiff.readthedocs.io/en/stable/api

Shows how to use the XmlDiffFormatter with different normalization options. This formatter produces output similar to older versions of xmldiff.

```python
from xmldiff import formatting
from xmldiff import main

formatter = formatting.XmlDiffFormatter(normalize=formatting.WS_NONE)
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

--------------------------------

### Python: Diff XML Files using xmldiff Main API

Source: https://xmldiff.readthedocs.io/en/stable/api

Compares two XML files and returns a list of edit actions to transform the left file into the right file. Supports custom diff options for matching and comparison. Requires the `xmldiff` library.

```python
from xmldiff import main

# Example usage comparing two HTML files
result = main.diff_files("../tests/test_data/insert-node.left.html",
                       "../tests/test_data/insert-node.right.html",
                       diff_options={'F': 0.5, 'ratio_mode': 'fast'})
print(result)
```

--------------------------------

### Diff Texts with Default Formatter (Python)

Source: https://xmldiff.readthedocs.io/en/stable/advanced

Compares two text strings and returns a list of differences using the default xmldiff formatter. Treats text content as simple values.

```python
from xmldiff import main, formatting
left = '<body><p>Old Content</p></body>'
right = '<body><p>New Content</p></body>'
main.diff_texts(left, right)
```

--------------------------------

### Main Diffing Functions

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

The xmldiff library provides three main functions for comparing XML content: `diff_files` for files or streams, `diff_texts` for strings, and `diff_trees` for lxml trees. These functions accept common parameters for configuring the diffing process.

```APIDOC
## `xmldiff.main.diff_files()`

### Description
Compares two XML files or file streams and returns the differences.

### Method
`diff_files(left, right, **kwargs)`

### Endpoint
N/A (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (Common to all diff functions)
- **left** (str or file-like object) - Required - The "left", "old" or "from" XML content.
- **right** (str or file-like object) - Required - The "right", "new" or "target" XML content.
- **check** (bool) - Optional - If true, returns error code 1 if there are any differences.
- **diff_options** (dict) - Optional - A dictionary of options passed to the `Differ()` class:
  - **F** (float, 0-1) - Threshold for node similarity. Defaults to 0.5.
  - **uniqueattrs** (list) - Attributes that uniquely identify a node. Defaults to `['{http://www.w3.org/XML/1998/namespace}id']`.
  - **ratio_mode** (str) - Accuracy of similarity calculation ('accurate', 'fast', 'faster'). Defaults to 'fast'.
  - **ignored_attrs** (list) - Attributes to ignore during comparison.
- **fast_match** (bool) - Optional - Enables a faster node matching algorithm. Defaults to False.
- **formatter** (object) - Optional - An object to format the output (e.g., `xmldiff.formatting.diff`, `xmldiff.formatting.xml`). If not specified, returns a list of edit actions.

### Request Example
```python
from xmldiff import main

# Example using diff_files
diff_result = main.diff_files("path/to/old.xml", "path/to/new.xml", diff_options={'F': 0.7})

# Example using diff_texts
diff_result = main.diff_texts("<root>old</root>", "<root>new</root>")
```

### Response
#### Success Response (200)
- **edit_script** (list) - A list of actions (e.g., `UpdateTextIn`, `InsertNode`, `DeleteNode`) to transform the left XML into the right XML, if no formatter is specified.
- **formatted_output** (str) - A formatted string representing the differences, if a formatter is specified.

#### Response Example
```json
[
  {
    "action": "update_text_in",
    "node": "/root",
    "text": "new content"
  }
]
```
```

--------------------------------

### Patching XML File with xmldiff

Source: https://xmldiff.readthedocs.io/en/stable/api

Shows how to use the `patch_file` function from the xmldiff library to apply a diff file to an XML file. This function takes the paths to the diff and the original file, returning the patched XML content as a string.

```python
>>> from xmldiff import main
>>> print(main.patch_file("../tests/test_data/insert-node.diff",
...                       "../tests/test_data/insert-node.left.html"))
<body>
  <div id="id">
    <p>Simple text</p>
  </div>
</body>
```

--------------------------------

### Patching XML Files with xmldiff

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

The patching API allows applying diff outputs to modify XML. The patch_file function takes paths to a diff file and a left-side file, returning the patched XML as a string. This is useful for automated updates of XML content.

```python
>>> from xmldiff import main
>>> print(main.patch_file("../tests/test_data/insert-node.diff",
...                       "../tests/test_data/insert-node.left.html"))
<body>
    <div id="id">
      <p>Simple text</p>
    </div>
  </body>
```

--------------------------------

### Patching API

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

The patching API allows applying diffs to XML documents. It provides methods for patching files, text strings, and lxml trees.

```APIDOC
## Patching API

### Description
Provides functionality to patch XML documents using diff output. It includes methods for patching files, text strings, and lxml trees, all returning the patched XML as a string.

### Method
N/A (This describes a set of functions, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
from xmldiff import main

# Example using patch_file
# Assuming 'insert-node.diff' and 'insert-node.left.html' exist
# result = main.patch_file("../tests/test_data/insert-node.diff", "../tests/test_data/insert-node.left.html")
# print(result)

# Example using patch_text
# diff_script = [{"action": "InsertNode", "target": "/root", "position": 0, "name": "newNode"}]
# xml_string = "<root></root>"
# result = main.patch_text(diff_script, xml_string)
# print(result)

# Example using patch_tree
# from lxml import etree
# diff_script = [...]
# xml_tree = etree.fromstring("<root></root>")
# result_tree = main.patch_tree(diff_script, xml_tree)
# print(etree.tostring(result_tree))
```

### Response
#### Success Response (200)
Returns a string representing the patched XML tree.

#### Response Example
```xml
<body>
  <div id="id">
    <p>Simple text</p>
  </div>
</body>
```
```

--------------------------------

### Diff Texts with Optimized HTML Formatting (Python)

Source: https://xmldiff.readthedocs.io/en/stable/advanced

Compares text with HTML formatting using an optimized XMLFormatter that specifies text and formatting tags. Produces more concise diffs for structured HTML.

```python
formatter=formatting.XMLFormatter(
    text_tags=('p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'li'),
    formatting_tags=('b', 'u', 'i', 'strike', 'em', 'super',
                     'sup', 'sub', 'link', 'a', 'span'))
left = '<body><p>My Fine Content</p></body>'
right = '<body><p><b>My <i>Fine</i> Content</b></p></body>'
result = main.diff_texts(left, right, formatter=formatter)
print(result)
```

--------------------------------

### Patching XML Text and Trees with xmldiff

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

xmldiff provides patch_text and patch_tree for applying edits to XML represented as strings or lxml trees, respectively. patch_text accepts Unicode strings, while patch_tree operates on an edit script and an lxml tree object. All patching methods return the resulting XML as a string.

```python
# Example usage for patch_text and patch_tree would go here, but are not provided in the input text.
```

--------------------------------

### Diff Formatted Text with Standard Formatter (Python)

Source: https://xmldiff.readthedocs.io/en/stable/_sources/advanced.rst

Compares two text strings representing XML content and shows the diff using the default text formatter. The default formatter treats text as a simple value, resulting in insert/delete operations for changed text.

```python
from xmldiff import main, formatting
left = '<body><p>Old Content</p></body>'
right = '<body><p>New Content</p></body>'
print(main.diff_texts(left, right))
```

--------------------------------

### InsertNamespace Action

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

The InsertNamespace action adds a new namespace declaration to the XML document, specified by its prefix and URI.

```APIDOC
## InsertNamespace Action

### Description
Adds a new namespace to the XML document. This is necessary before adding nodes that utilize a namespace not present in the original XML tree. It requires the namespace prefix and its corresponding URI.

### Method
N/A (This describes a diff action, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
# This is a conceptual example based on the provided doctest
# Actual usage would be within the diff_texts function
left = '<document></document>'
right = '<document xmlns:new="http://theuri"></document>'
# Assuming a function call like:
diff_result = main.diff_texts(left, right)
# Which might produce:
# [InsertNamespace(prefix='new', uri='http://theuri')]
```

### Response
#### Success Response (200)
N/A (This describes a diff action, not an API response)

#### Response Example
```json
{
  "action": "InsertNamespace",
  "prefix": "new",
  "uri": "http://theuri"
}
```
```

--------------------------------

### Diff HTML with normalized whitespace

Source: https://xmldiff.readthedocs.io/en/stable/_sources/advanced.rst

Compares two HTML strings and generates a diff, applying whitespace normalization to the formatter. The output highlights deleted and inserted paragraphs.

```python
from xmldiff import main
from xmldiff.formatting import HTMLFormatter
from xmldiff import formatting

left = u"""<html><body>
  <p>The First paragraph</p>
  <p>A Second paragraph</p>
  <p>Last paragraph</p>
</body></html>"""
right = u"""<html><body>
  <p>Last paragraph</p>
  <p>A Second paragraph</p>
  <p>The First paragraph</p>
</body></html>"""

formatter = HTMLFormatter(
    normalize=formatting.WS_BOTH)
result = main.diff_texts(left, right, formatter=formatter)
print(result)
```

--------------------------------

### Diff Formatted Text with Configured XML Formatter (Python)

Source: https://xmldiff.readthedocs.io/en/stable/_sources/advanced.rst

Compares XML content with formatting tags using a custom configured XMLFormatter. This configuration allows specifying which tags should be treated as text content and which as formatting, leading to a more meaningful diff.

```python
from xmldiff import main, formatting
formatter=formatting.XMLFormatter(
    text_tags=('p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'li'),
    formatting_tags=('b', 'u', 'i', 'strike', 'em', 'super',
                     'sup', 'sub', 'link', 'a', 'span'))
left = '<body><p>My Fine Content</p></body>'
right = '<body><p><b>My <i>Fine</i> Content</b></p></body>'
result = main.diff_texts(left, right, formatter=formatter)
print(result)
```

--------------------------------

### Diff HTML with fast match and formatter

Source: https://xmldiff.readthedocs.io/en/stable/_sources/advanced.rst

Compares two HTML strings using the 'fast_match' option and an HTML formatter. This combination results in a diff that updates text within nodes rather than moving entire nodes, using '<ins>' and '<del>' tags.

```python
from xmldiff import main
from xmldiff.formatting import HTMLFormatter
from xmldiff import formatting

left = u"""<html><body>
  <p>The First paragraph</p>
  <p>A Second paragraph</p>
  <p>Last paragraph</p>
</body></html>"""
right = u"""<html><body>
  <p>Last paragraph</p>
  <p>A Second paragraph</p>
  <p>The First paragraph</p>
</body></html>"""

formatter = HTMLFormatter(
    normalize=formatting.WS_BOTH)
result = main.diff_texts(left, right,
    diff_options={'fast_match': True},
    formatter=formatter)
print(result)
```

--------------------------------

### Diff Complex Formatted Text with XML Formatter (Python)

Source: https://xmldiff.readthedocs.io/en/stable/_sources/advanced.rst

Demonstrates diffing XML content with nested formatting tags (like bold and italics) using the XMLFormatter. It highlights how the default XMLFormatter might represent complex changes as full text replacements.

```python
from xmldiff import main, formatting
formatter=formatting.XMLFormatter()
left = '<body><p>My Fine Content</p></body>'
right = '<body><p><b>My <i>Fine</i> Content</b></p></body>'
result = main.diff_texts(left, right, formatter=formatter)
print(result)
```

--------------------------------

### Diff HTML using fast match algorithm

Source: https://xmldiff.readthedocs.io/en/stable/_sources/advanced.rst

Compares two HTML strings using the 'fast_match' option, which can alter the diff result by favoring text updates over node moves. The output shows text update operations.

```python
from xmldiff import main

left = u"""<html><body>
  <p>The First paragraph</p>
  <p>A Second paragraph</p>
  <p>Last paragraph</p>
</body></html>"""
right = u"""<html><body>
  <p>Last paragraph</p>
  <p>A Second paragraph</p>
  <p>The First paragraph</p>
</body></html>"""

result = main.diff_texts(left, right,
    diff_options={'fast_match': True})
print(result)
```

--------------------------------

### Python: Diff XML Trees using xmldiff

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

Compares two lxml XML trees and returns a list of differences or a formatted string. This method is efficient when XML content is already parsed into lxml tree objects.

```python
from xmldiff import main
from lxml import etree

xml_tree1 = etree.fromstring("<root><item id='1'/></root>")
xml_tree2 = etree.fromstring("<root><item id='2'/></root>")

differences = main.diff_trees(xml_tree1, xml_tree2)
print(differences)
```

--------------------------------

### Diff Texts with HTMLFormatter for Visual Diffs (Python)

Source: https://xmldiff.readthedocs.io/en/stable/advanced

Utilizes the custom HTMLFormatter to generate diffs with visual cues for formatting changes and inserted/deleted text, suitable for HTML rendering. Requires CSS for styling.

```python
formatter = HTMLFormatter(
    text_tags=('p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'li'),
    formatting_tags=('b', 'u', 'i', 'strike', 'em', 'super',
                     'sup', 'sub', 'link', 'a', 'span'))
left = '<body><p>My Fine Content</p></body>'
right = '<body><p><b>My <i>Fine</i> Content</b></p></body>'
result = main.diff_texts(left, right, formatter=formatter)
print(result)
```

--------------------------------

### Patching XML Text with xmldiff

Source: https://xmldiff.readthedocs.io/en/stable/api

Illustrates the usage of the `patch_text` function for applying XML patches directly to string inputs. It takes two Unicode strings (the diff script and the original XML) and returns the patched XML as a string. This is useful for in-memory XML manipulation.

```python
# Example for patch_text function (not directly provided in text, but described)
# from xmldiff import main
# diff_script = "..."
# original_xml = "..."
# patched_xml = main.patch_text(diff_script, original_xml)
# print(patched_xml)
```

--------------------------------

### XSLT Template for Visual Diffing (XML/XSLT)

Source: https://xmldiff.readthedocs.io/en/stable/advanced

An XSLT stylesheet designed to transform XML diff results into HTML-friendly attributes, such as 'class' for inserted formatting and 'del'/'ins' tags.

```xml
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
   xmlns:diff="http://namespaces.shoobx.com/diff"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

   <xsl:template match="@diff:insert-formatting">
       <xsl:attribute name="class">
         <xsl:value-of select="'insert-formatting'"/>
       </xsl:attribute>
   </xsl:template>

   <xsl:template match="diff:delete">
       <del><xsl:apply-templates /></del>
   </xsl:template>

   <xsl:template match="diff:insert">
       <ins><xsl:apply-templates /></ins>
   </xsl:template>

   <xsl:template match="@* | node()">
     <xsl:copy>
       <xsl:apply-templates select="@* | node()"/>
     </xsl:copy>
   </xsl:template>
</xsl:stylesheet>
```

--------------------------------

### DiffFormatter

Source: https://xmldiff.readthedocs.io/en/stable/api

The DiffFormatter returns a string with the edit script printed, one action per line, enclosed in brackets.

```APIDOC
## DiffFormatter

### Description
This formatter is used when specifying `-f diff` on the command line. It returns a string with the edit script printed out, one action per line. Each line is enclosed in brackets and consists of a string describing the action, and the action's arguments.

### Class
`xmldiff.formatting.DiffFormatter(_normalize=WS_TAGS_, _pretty_print=False_)`

### Parameters
*   **normalize** (enum: `WS_NONE`, `WS_TAGS`, `WS_TEXT`, `WS_BOTH`) - Determines whitespace normalizing.
*   **pretty_print** (bool) - Determines if the output should be compact (`False`) or readable (`True`).

### Request Example
```python
from xmldiff import formatting, main

formatter = formatting.DiffFormatter()
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

### Response Example
```
[update-text, /body/div[1], null]
[insert, /body/div[1], p, 0]
[update-text, /body/div/p[1], "Simple text"]
```
```

--------------------------------

### XMLFormatter

Source: https://xmldiff.readthedocs.io/en/stable/api

The XMLFormatter returns XML with tags describing the changes, designed for easy rendering with XSLT.

```APIDOC
## XMLFormatter

### Description
This formatter returns XML with tags describing the changes. These tags are designed so they easily can be changed into something that will render nicely, for example with XSLT replacing the tags with the format you need.

### Class
`xmldiff.formatting.XMLFormatter(normalize=WS_NONE, pretty_print=True, text_tags=(), formatting_tags=())`

### Parameters
*   **normalize** (enum: `WS_NONE`, `WS_TAGS`, `WS_TEXT`, `WS_BOTH`) - Determines whitespace normalizing.
*   **pretty_print** (bool) - Determines if the output should be compact (`False`) or readable (`True`).
*   **text_tags** (list of str) - A list of XML tags that contain human-readable text, e.g., `('para', 'li')`.
*   **formatting_tags** (list of str) - A list of XML tags that are tags that change text formatting, e.g., `('strong', 'i', 'u')`.

### Request Example
```python
from xmldiff import formatting, main

formatter = formatting.XMLFormatter(normalize=formatting.WS_BOTH)
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

### Response Example
```xml
<body xmlns:diff="http://namespaces.shoobx.com/diff">
  <div id="id">
    <p diff:insert="">Simple text</p>
  </div>
</body>
```
```

--------------------------------

### InsertComment Action

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

The InsertComment action is used to insert comments into an XML document. It takes a target node, a position, and the comment text as arguments.

```APIDOC
## InsertComment Action

### Description
Inserts comments into an XML document. This action is specific to comments as they do not have tags, differing from the general InsertNode action. It requires a target node, a position, and the text content of the comment.

### Method
N/A (This describes a diff action, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
# This is a conceptual example based on the provided doctest
# Actual usage would be within the diff_texts function
left = '<document><node>Content</node></document>'
right = '<document><!-- A comment --><node>Content</node></document>'
# Assuming a function call like:
diff_result = main.diff_texts(left, right)
# Which might produce:
# [InsertComment(target='/document[1]', position=0, text=' A comment ')]
```

### Response
#### Success Response (200)
N/A (This describes a diff action, not an API response)

#### Response Example
```json
{
  "action": "InsertComment",
  "target": "/document[1]",
  "position": 0,
  "text": " A comment "
}
```
```

--------------------------------

### InsertAttrib Action in xmldiff

Source: https://xmldiff.readthedocs.io/en/stable/api

The InsertAttrib action adds a new attribute to an existing XML node. It requires the target node, the attribute name, and the attribute value as parameters. This is useful for adding metadata or configuration to nodes.

```python
>>> left = '<document><node/></document>'
>>> right = '<document newattr="newvalue"><node/></document>'
>>> main.diff_texts(left, right)
[InsertAttrib(node='/document[1]', name='newattr',
              value='newvalue')]
```

--------------------------------

### XmlDiffFormatter

Source: https://xmldiff.readthedocs.io/en/stable/api

The XmlDiffFormatter works like DiffFormatter but provides an output format similar to older xmldiff versions (0.x and 1.x).

```APIDOC
## XmlDiffFormatter

### Description
This formatter works like the DiffFormatter, but the output format is different and more similar to the `xmldiff` output in versions 0.x and 1.x.

### Class
`xmldiff.formatting.XmlDiffFormatter(_normalize=WS_TAGS_, _pretty_print=False_)`

### Parameters
*   **normalize** (enum: `WS_NONE`, `WS_TAGS`, `WS_TEXT`, `WS_BOTH`) - Determines whitespace normalizing.
*   **pretty_print** (bool) - Determines if the output should be compact (`False`) or readable (`True`).

### Request Example
```python
from xmldiff import formatting, main

formatter = formatting.XmlDiffFormatter(normalize=formatting.WS_NONE)
print(main.diff_files("../tests/test_data/insert-node.left.html",
                      "../tests/test_data/insert-node.right.html",
                      formatter=formatter))
```

### Response Example
```
[update, /body/div[1]/text()[1], "\n    "]
[insert-first, /body/div[1],
<p/>]
[update, /body/div/p[1]/text()[1], "Simple text"]
[update, /body/div/p[1]/text()[2], "\n  "]
```
```

--------------------------------

### UpdateTextAfter Action

Source: https://xmldiff.readthedocs.io/en/stable/_sources/api.rst

The UpdateTextAfter action modifies the text that trails a specified node. The 'text' argument provides the new value for this trailing text.

```APIDOC
## UpdateTextAfter Action

### Description
Modifies the text that trails a specified node. The 'text' argument provides the new value for this trailing text.

### Method
N/A (This describes a diff action, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
# This is a conceptual example based on the provided doctest
# Actual usage would be within the diff_texts function
left = '<document><node>Content</node></document>'
right = '<document><node>Content</node>Trailing text</document>'
# Assuming a function call like:
diff_result = main.diff_texts(left, right)
# Which might produce:
# [UpdateTextAfter(node='/document/node[1]', text='Trailing text')]
```

### Response
#### Success Response (200)
N/A (This describes a diff action, not an API response)

#### Response Example
```json
{
  "action": "UpdateTextAfter",
  "node": "/document/node[1]",
  "text": "Trailing text"
}
```
```