[IPython-dev] magic docstrings

Stefan van der Walt stefan at sun.ac.za
Thu Nov 3 08:02:22 CST 2005


I compiled the iPython docs earlier today, and found some problems in
the generated magic.tex.

One problem is that LaTeX # character is not escaped, which can be
easily fixed:

Index: Magic.py
===================================================================
--- Magic.py    (revision 920)
+++ Magic.py    (working copy)
@@ -264,7 +264,7 @@
         """Format a string for latex inclusion."""

         # Characters that need to be escaped for latex:
-        escape_re = re.compile(r'(%|_|\$)',re.MULTILINE)
+        escape_re = re.compile(r'(%|_|\$|#)',re.MULTILINE)
         # Magic command names as headers:
         cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
                                  re.MULTILINE)


The more tricky problem, however, is the use of "\\" in the
docstrings.  In Python, you do not want "\\" in your docstrings, since
they display as "\", but without the "\\" LaTeX won't print a
line-feed.

Then, there are a few "\n" symbols that need to be printed as is.  In
Python, they are correctly escaped as "\\n", but under LaTeX they need
to be "\textbackslash{}n".  I fixed this using

@@ -274,10 +274,14 @@
         # Paragraph continue
         par_re = re.compile(r'\\$',re.MULTILINE)

+        # The "\n" symbol
+        newline_re = re.compile('\\\\n')
+
         str = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',str)
         str = cmd_re.sub(r'\\texttt{\g<cmd>}',str)
         str = par_re.sub(r'\\\\',str)
         str = escape_re.sub(r'\\\1',str)
+        str = newline_re.sub(r'\\textbackslash{}n',str)
         return str

but you might want to use a more generic solution to, for example,
replace all escaped characters like \n, \t, \b.

Regards
Stéfan




More information about the IPython-dev mailing list