Made logical order of the availiable math hacks.

Added link to Alan's raw->itex2mml HOWTO.


git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2859 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 60 insertions, 21 deletions

diff --git a/FAQ.txt b/FAQ.txt
index 78f86b5e8..74dd8a3a9 100644
--- a/FAQ.txt
+++ b/FAQ.txt
@@ -451,27 +451,66 @@ Here's the `to-do list entry`__.
 
 __ http://docutils.sourceforge.net/docs/dev/todo.html#math-markup
 
-There are several quick & dirty ways to include equations in
-documents:
-
-* For HTML there is MathML but its rendering is still quite broken (or
-  absent) on most browsers.  See an `example of raw MathML
-  <http://sf.net/mailarchive/message.php?msg_id=2177102>`__.
-
-* If you use LaTeX output only, a simple way is to use the "raw"
-  directive; examples are `here
-  <http://article.gmane.org/gmane.text.docutils.devel/521>`__.
-
-* Images of the equations can be used, typically generated by TeX.
-  Beni Cherniavsky has written some `preprocessing scripts`__ for
-  making inline TeX (for LaTeX and other [HTML etc.] output) math much
-  easier; `instructions here`__.
-
-  __ http://docutils.sourceforge.net/sandbox/cben/rolehack/
-  __ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html
-
-* Here is an example of potential `itex math markup
-  <http://article.gmane.org/gmane.text.docutils.user/118>`__.
+There are several quick & dirty ways to include equations in documents.
+They all presently use LaTeX syntax or dialects of it.
+
+* For LaTeX output, nothing beats raw LaTeX math.  A simple way is to
+  use the `raw directive`_::
+
+      .. raw:: latex
+
+          \[ x^3 + 3x^2a + 3xa^2 + a^3, \]
+          
+  For inline math you could use substitutions of the raw directive but
+  the recently added `raw role`_ is more convenient.  You must define a
+  custom role based on it once in your document::
+
+      .. role:: raw-latex(raw)
+          :format: latex
+
+  and then you can just use the new role in your text::
+
+      the binomial expansion of :raw-latex:`$(x+a)^3$` is
+
+  .. _raw directive: http://docutils.sourceforge.net/docs/ref/rst/
+                     directives.html#raw-data-pass-through
+  .. _raw role: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw
+
+* For HTML the "Right" w3c-standard way to include math is MathML_.
+  Unfortunately its rendering is still quite broken (or absent) on many
+  browsers but it's getting better.  Another bad problem is that typing
+  or reading raw MathML by humans is *really* painful, so embedding it
+  in a reST document with the raw directive would defy the goals of
+  readability and editability of reST (see an `example of raw MathML
+  <http://sf.net/mailarchive/message.php?msg_id=2177102>`__).
+
+  A much less painful way to generate HTML+MathML is to use itex2mml_ to
+  convert a dialect of LaTeX syntax to presentation MathML.  Here is an
+  example of potential `itex math markup
+  <http://article.gmane.org/gmane.text.docutils.user/118>`__.  The
+  simplest way to use it is to add ``html`` to the format lists for the
+  raw directive/role and postprocess the resulting document with
+  itex2mml.  This way you can *generate LaTeX and HTML+MathML from the
+  same source*, but you must limit yourself to the intersection of LaTeX
+  and itex markups for this to work.  Alan G. Isaac wrote a detailed
+  HOWTO_ for this approach.
+
+  .. _MathML: http://www.w3.org/Math/
+  .. _itex2mml: http://pear.math.pitt.edu/mathzilla/itex2mml.html
+  .. _HOWTO: http://www.american.edu/econ/itex2mml/mathhack.rst
+
+  * The other way to add math to HTML is to use images of the equations,
+    typically generated by TeX.  This is inferior to MathML in the long
+    term but is perhaps more accessible nowdays.
+
+    Of course, doing it by hand is too much work.  Beni Cherniavsky has
+    written some `preprocessing scripts`__ for converting the
+    ``texmath`` role/directive into images for HTML output and raw
+    directives/subsitution for LaTeX output.  This way you can *generate
+    LaTeX and HTML+images from the same source*.  `Instructions here`__.
+
+    __ http://docutils.sourceforge.net/sandbox/cben/rolehack/
+    __ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html
 
 
 Is nested inline markup possible?