fixed mathjax doc page

1 files changed, 31 insertions, 23 deletions

diff --git a/askbot/doc/source/mathjax.rst b/askbot/doc/source/mathjax.rst
index 4dfc8aad..a5ea2d22 100644
--- a/askbot/doc/source/mathjax.rst
+++ b/askbot/doc/source/mathjax.rst
@@ -1,36 +1,44 @@
-.. _mathjax:
+.. _enable_mathjax:
 
-===================
-Installing MathJax
-===================
+==========================
+Enabling MathJax in Askbot
+==========================
 
-MathJax_ is a browser independent javascript rendering engine for mathematical
-expressions. On a MathJax-enabled site, such as Askbot :) you can display
+MathJax_ is a rendering engine for mathematical
+expressions (based on cross-browser javascript code). On a MathJax-enabled site, such as Askbot you can display
 perfectly formatted mathematical formulae.
 
-However, MathJax distribution is very large and because of the size is not
-shipped with Askbot.
+However, MathJax distribution is very large and is not shipped with Askbot.
 
-To enable MathJax on your site, three things need to be done:
+To enable MathJax on your site, please do the following:
 
-* download MathJax to some directory on your server
-* edit webserver configuration so that url `http://example.com/mathjax`
-  points to that directory and file `MathJax.js` is available at 
-  `http://example.com/mathjax/MathJax.js`. For Apache, a following line 
-  in the apache configuration file (maybe a VirtualHost section) will do::
+Decide where you want to store mathjax (e.g. to share it with other applications as well)::
 
-  Alias /mathjax/ /filesystem/path/to/mathjax/
+   cd /some/directory
 
-* in Askbot "settings" -> "Optional components", check "Enable MathJax" and
-  enter url `http://example.com/mathjax`
+Follow `mathjax installation instructions`_
 
-Note: your actual forum site must in this case be available at `http://example.com`.
-It is **very important** to serve MathJax media **from the same domain**, otherwise
-mathematics rendering will be very slow in Firefox and some other browsers (those 
-using the "same origin" policy for the HTTP cookies - MathJax does use sookies to
-store some Math display settings)
+Edit webserver configuration so that url `http://example.com/mathjax`
+points to that directory and file `MathJax.js` is available at 
+`http://example.com/mathjax/MathJax.js`. 
+  
+For Apache, a following line in the configuration file (maybe within a VirtualHost section) will do::
+
+    Alias /mathjax/ /filesystem/path/to/mathjax/
+
+Finally, enable MathJax in Askbot: "settings" -> "Optional components", check "Enable MathJax" and
+enter url `http://example.com/mathjax` (link "settings" is available to site administrators in the upper right corner of the forum pages).
+
+.. note::
+
+    your actual forum site must be served from the **same domain and subdomain**
+    as mathjax. This is **very important** for Firefox and some other browsers adhering
+    to the `same origin policy`_ for the browser cookies. Mathjax does use cookies to 
+    store math display settings.
 
 One day enabling MathJax will be even easier, but `some more work`_ needs to be done for this to happen.
 
-.. _MathJax: http://mathjax.org
+.. _MathJax: http://www.mathjax.org/
 .. _`some more work`: http://bugs.askbot.org/issues/27
+.. _`mathjax installation instructions`: http://www.mathjax.org/resources/docs/?installation.html
+.. _`same origin policy`: http://en.wikipedia.org/wiki/Same_origin_policy