[+] example of Dinant.match(..., debug=True).

README.md

@@ -18,6 +18,28 @@ capture( one_or_more(_any('a-z')) ) + zero_or_more(then('[') + capture( zero_or_
 
 becomes `((?:[a-z])+)(?:\[((?:[a-z])*)\])*` and not `([a-z]+)(?:\[([a-z]*)\])*`.
 
+One cool feature: a `Dinant` expression (object) can tell you which part of your
+expression fails:
+
+```
+# this is a real world example!
+In [1]: import dinant as d
+In [2]: s = """36569.12ms (cpu 35251.71ms) | rendering style for layer: 'terrain-small' and style 'terrain-small'"""
+In [3]: identifier_re = d.one_or_more(d.any_of('A-Za-z0-9-'))
+# can you spot the error?
+In [4]: render_time_re = ( d.bol + d.capture(d.float, name='wall_time') + 'ms ' +
+   ...:                    '(cpu' + d.capture(d.float, name='cpu_time') + 'ms)' + d.one_or_more(' ') + '| ' +
+   ...:                    "rendering style for layer: '" + d.capture(identifier_re, name='layer') + "' " +
+   ...:                    "and style '" + d.capture(identifier_re, name='style') + "'" + d.eol )
+
+
+In [5]: render_time_re.match(s, debug=True)
+# ok, this is too verbose (I hope next version will be more human readable)
+# but it's clear it's the second capture
+Out[5]: '^(?P<wall_time>(?:(?:\\-)?(?:(?:\\d)+)?\\.(?:\\d)+|(?:\\-)?(?:\\d)+\\.|(?:\\-)?(?:\\d)+))ms\\ \\(cpu(?P<cpu_time>(?:(?:\\-)?(?:(?:\\d)+)?\\.(?:\\d)+|(?:\\-)?(?:\\d)+\\.|(?:\\-)?(?:\\d)+))'
+# the error is that the text '(cpu' needs a space at the end
+```
+
 You might say that that expression is more difficult to read than a regular
 expression, and I half agree with you. You could split your expression in its
 components: