improved documentation of the Python interface

c/texcaller.h

@@ -51,6 +51,13 @@
  *  \verbatim
 git clone https://github.com/vog/texcaller.git
 \endverbatim
+ *
+ *  \section release-0_7 Release 0.7
+ *
+ *  <a href="http://www.profv.de/texcaller/texcaller-0.7.tar.gz">Download</a> |
+ *  <a href="https://github.com/vog/texcaller/commits/0.7">ChangeLog</a>
+ *
+ *  This release provides an improved documentation.
  *
  *  \section release-0_6 Release 0.6
  *

python/example_ur_1.py

@@ -0,0 +1,5 @@
+latex = ur'''
+\documentclass{article}
+\u005cusepackage{amsmath}
+\begin{document} Hello math! \end{document}
+'''

python/example_ur_2.py

@@ -0,0 +1,5 @@
+latex = r'''
+\documentclass{article}
+\usepackage{amsmath}
+\begin{document} Hello math! \end{document}
+'''.decode('utf-8')

swig/texcaller.i

@@ -24,6 +24,25 @@ texcaller.escape_latex(s)
  *  \par Example
  *
  *  \include example.py
+ *
+ *  \par Beware of \c \\u
+ *
+ *  Unfortunately,
+ *  Python always interprets \c \\uXXXX sequences in unicode strings
+ *  (even in raw unicode strings),
+ *  which interferes badly with common LaTeX commands such as \c \\usepackage{}.
+ *  This means every backslash \c \\ which is followed by the character \c u
+ *  needs to be escaped via \c \\u005c,
+ *  which looks really strange:
+ *
+ *  \include example_ur_1.py
+ *
+ *  Fortunately,
+ *  this problem is easily solved by
+ *  using raw byte strings, and
+ *  converting those to unicode strings via the \c decode() method:
+ *
+ *  \include example_ur_2.py
  */
 
 /*! \cond */