## [Docutils-develop] Math Support Proposal

 [Docutils-develop] Math Support Proposal From: Jeff Anderson - 2008-04-23 18:43:33 Attachments: signature.asc Hello, I'm not a developer of docutils, but I've become a heavy user of reST and docutils. I use it for note taking at school. I one day decided to try to use latex math syntax and extend my note taking with reST to physics and math classes. I've read about, and tried just about every hack, sandbox, and patch that I can get my hands on to get cross-output format math. In doing this, I think I have an idea that combines the advantages of all the approaches I've seen. I think my idea fits well with the docutils design philosophy. Representing equations in reST: Math in reST will use latex math syntax. To denote that I am giving reST an equation, I will simply use a directive or role based on what type of math environment I want. The XML side of docutils could be extended to include a tag that denoted an equation to maximize the portability between output formats. Potential Syntax Examples: .. displaymath:: e = mc^2 \frac{1}{2} \times \frac{\pi}{e} --------------- .. alignmath:: &u = x & d&v = \sin x d&u = dx & &v = -\cos x --------------- To convert from degrees to radians, divide by 360, and multiply by :inlinemath:2 \pi. --------------- Notice the lack of  surrounding display math, and the lack of  surrounding inline math. There is also no \begin or \end. That should be done by the writer based on the format that is being written out. This syntax is an idea taken from the "cben/rolehack" sandbox. * Outputting to latex would appropriately handle the \begin{} \end{} environments based on what you've specified. * Outputting to xhtml + mathml would strip anything that itex2mml doesn't understand, like align. It might even be smart enough to try to "fake" the latex align environment with borderless tables, or divs. * An option could be given for the html writer to use latex to render equations as images instead of using mathml. It would also be useful to have the reader run the math through latex to make sure it is syntactically sane, and output any errors with line numbers that correspond to the rst source file. If I use the raw directive now, rst is happy, but when I run pdflatex, it complains and gives line numbers of the .tex file. This makes it more difficult to track down just which math block I messed up. With equations being a native part of the rst specification and the docutils XML DTD, it would create a decent number of possibilities for rst-- Output equations to plain text, send them to a math program to be evaluated, display them with JSmath, etc. This would all be possible with one rst source file. XML Potential Syntax:: Some simple kinematic equations: Displacement: \Delta x \equiv x_f - x_i[/itex] Average Speed: \text{Average speed} &= \text{total distance} \over \text{total time}\\ s_a &= \frac{\Delta d}{\Delta t}[/itex] I realize that this is a sizable code change I am proposing, as I am suggesting to change quite a few components to get this functionality. I think it would be wonderful to have math equations integrated so well into docutils. I haven't started writing a patch just yet. At this point, I am mostly curious to see what the developers think of this idea-- does it have a shot at ever getting merged? Thanks for your time! Jeff Anderson