Continues updating documentation, in particular the Advanced Topics a…

…nd API documents. Added a number of new example files.

docs/html/_sources/api/callback.txt

@@ -58,7 +58,7 @@ A callback specification is any one of the following:
         the given function, and it would return their sum, ``5``, when
         the callback is executed.
 
-	.. describe:: [object, fn]
+    .. describe:: [object, fn]
 
         An array containing an object to use as `this` and a function to
         call for the callback.  For example,
@@ -75,7 +75,7 @@ A callback specification is any one of the following:
 	Similar to the previous case, but with data that is passed to
 	the function as well.
 
-    ..describe:: ["method", object]
+    .. describe:: ["method", object]
 
         Here, `object` is an object that has a method called `method`, and
         the callback will execute that method (with the object as
@@ -220,6 +220,26 @@ MathJax.Callback Methods
         - **callback** --- the callback specification
     :Returns: the callback object
 
+.. method:: Queue([callback,...])
+
+    Creates a `MathJax.CallBack.Queue` object and pushes the given
+    callbacks into the queue.  See :ref:`Using Queues <using-queues>`
+    for more details about MathJax queues.
+
+    :Parameters:
+        - **callback** --- one or more callback specifications
+    :Returns: the `Queue` object
+
+.. method:: Signal(name)
+
+    Looks for a named signal, creates it if it doesn't already exist,
+    and returns the signal object.  See
+    :ref:`Using Signals <using-signals>` for more details.
+
+    :Parameters:
+        - **name** --- name of the signal to get or create
+    :Returns: the `Signal` object
+
 .. method:: ExecuteHooks(hooks[, data[,reset]])
 
     Calls each callback in the `hooks` array (or the single hook if it
@@ -231,29 +251,54 @@ MathJax.Callback Methods
     execute when all the ones returned by the hooks have been
     completed.  Otherwise, :meth:`MathJax.Callback.ExecuteHooks()`
     returns ``null``.
-        
+
     :Parameters:
         - **hooks** --- array of hooks to be called, or a hook
         - **data** --- array of arguments to pass to each hook in turn
         - **reset** --- ``true`` if the :meth:`reset()` method should be called
     :Returns: callback that waits for all the hooks to complete, or ``null``
 
-.. method:: Queue([callback,...])
+.. method:: Hooks(reset)
 
-    Creates a `MathJax.CallBack.Queue` object and pushes the given
-    callbacks into the queue.  See :ref:`Using Queues <using-queues>`
-    for more details about MathJax queues.
+    Creates a prioritized list of hooks that are called in order based
+    on their priority (low priority numbers are handled first).  This
+    is meant to replace :meth:`MathJax.Callback.ExecuteHooks()` and is
+    used internally for signal callbacks, pre- and post-filters, and
+    other lists of callbacks.
 
     :Parameters:
-        - **callback** --- one or more callback specifications
-    :Returns: the `Queue` object
+        - **reset** --- ``true`` if callbacks can be called more than once
+    :Returns: the `Hooks` object
 
-.. method:: Signal(name)
-
-    Looks for a named signal, creates it if it doesn't already exist,
-    and returns the signal object.  See
-    :ref:`Using Signals <using-signals>` for more details.
-
-    :Parameters:
-        - **name** --- name of the signal to get or create
-    :Returns: the `Signal` object
+    The list has the following methods:
+
+    .. method:: Add(hook[,priority])
+
+        Add a callback to the prioritized list.  If ``priority`` is
+        not provided, the default is 10.  The ``hook`` is a `Callback`
+        specification as described above.
+
+        :Parameters:
+            - **hook** --- callback specification to add to the list
+	    - **priority** --- priority of the hook in the list (default: 10)
+	:Returns: the callback object being added
+
+    .. method:: Remove(hook)
+        :noindex:
+
+        Remove a given hook (as returned from :meth:`Add()` above)
+        from the prioritized list.
+
+	:Parameters:
+	    - **hook** --- the callback to be removed
+	:Returns: ``null``
+
+    .. method:: Execute()
+
+        Execute the list of callbacks, resetting them if requested.
+        If any of the hooks return callbacks, then ``Execute()``
+        returns a callback that will be executed when they all have
+        completed.
+
+	:Returns: a callback object or ``null``
+

docs/html/_sources/api/elementjax.txt

@@ -42,13 +42,11 @@ Instance Properties
 
 .. describe:: inputJax
 
-    A reference to the input jax that created the element.  (In the 
-    future, this will be changed to the name of the input jax.)
+    The name of the input jax that created the element.
 
 .. describe:: outputJax
 
-    A reference to the output jax that has processed this element.  (In 
-    the future, this will be changed to the name of the output jax.)
+    The name of the output jax that has processed this element.
 
 .. describe:: inputID
 
@@ -89,13 +87,25 @@ Methods
 	- **callback** --- the callback specification
     :Returns: the callback object
 
+.. Method:: Rerender([callback])
+    :noindex:
+
+    Removes the output and produces it again (for example, if CSS has
+    changed that would alter the spacing of the mathematics).  Note
+    that the internal representation isn't regenerated; only the
+    output is.  The `callback`, if any, is called when the process
+    completes.
+
+    :Parameters:
+	- **callback** --- the callback specification
+    :Returns: the callback object
+
 .. Method:: Reprocess([callback])
     :noindex:
 
-    Removes the output and produces it again.  This may be necessary if
-    there are changes to the CSS styles that would affect the layout
-    of the mathematics, for example.  The `callback`, if any, is
-    called when the process completes.
+    Removes the output and then retranslates the input into the
+    internal form and reredners the output again.  The `callback`, if
+    any, is called when the process completes.
 
     :Parameters:
 	- **callback** --- the callback specification
@@ -118,6 +128,16 @@ Methods
 
     :Returns: the ``<script>`` element
 
+.. Method:: needsUpdate()
+
+    Indicates whether the mathematics has changed so that its output
+    needs to be updated.
+
+    :Returns: ``true`` if the mathematics needs to be reprocessed,
+              ``false`` otherwise
+
+
+
 Output jax may add new methods to the base element jax class to
 perform exporting to other formats.  For example, a MathML output jax
 could add ``toMathML()``, or an accessibility output jax could add

docs/html/_sources/api/html.txt

@@ -92,6 +92,15 @@ Methods
         - **text** --- the text that is to be the script's new content
     :Returns: ``null``
 
+.. method:: getScript(script)
+
+    Gets the contents of the ``script`` element, properly taking into
+    account the browser limitations and bugs.
+
+    :Parameters:
+        - **script** --- the script whose content is to be retrieved
+    :Returns: the text of the ``script``
+
 .. describe:: Cookie.Set(name,data)
 
     Creates a MathJax cookie using the ``MathJax.HTML.Cookie.prefix``

docs/html/_sources/api/hub.txt

@@ -31,7 +31,17 @@ Properties
 .. describe:: processUpdateTime: 250
 
     The minimum time (in milliseconds) between updates of the
-    "Processing Math" message.
+    "Processing Math" message.  After this amount of time has passed,
+    and after the next equation has finished being processed, 
+    MathJax will stop processing momentarily so that the update
+    message can be displayed, and so that the browser can handle user
+    interaction.
+
+.. describe:: processUpdateDelay: 10
+
+   The amount of time (in milliseconds) that MathJax pauses after
+   issuing its processing message before starting the processing again
+   (to give browsers time to handle user interaction).
 
 .. describe:: signal
 
@@ -60,6 +70,11 @@ Properties
         running on a Macintosh computer or a Windows computer.  They
         will both be ``false`` for a Linux computer.
 
+    .. describe:: isMobile
+
+        This is ``true`` when MathJax is running a mobile version of a
+        WebKit or Gecko-based browser.
+
     .. describe:: isFirefox, isSafari, isChrome, isOpera, isMSIE, isKonqueror
 
         These are ``true`` when the browser is the indicated one, and
@@ -97,6 +112,18 @@ Properties
 	      }
 	    );
 
+.. describe:: inputJax
+
+    An object storing the MIME types associated with the various
+    registered input jax (these are the types of the ``<script>`` tags
+    that store the math to be processed by each input jax).
+
+.. describe:: outputJax
+
+    An object storing the output jax associate with the various
+    element jax MIME types for the registered output jax.
+
+
 Methods
 =======
 
@@ -243,13 +270,31 @@ Methods
 
 .. method:: Reprocess([element[,callback]])
 
-    Removes any typeset mathematics from the document or DOM element (or
-    elements if it is an array of elements), and then processes the
-    mathematics again, re-typesetting everything.  This may be necessary,
-    for example, if the CSS styles have changed and those changes would
-    affect the mathematics.  The `element` is either the DOM `id` of the
-    element to scan, a reference to the DOM element itself, or an array of
-    id's or references.  The `callback` is called when the processing is
+    Removes any typeset mathematics from the document or DOM element
+    (or elements if it is an array of elements), and then processes
+    the mathematics again, re-typesetting everything.  This may be
+    necessary, for example, if the CSS styles have changed and those
+    changes would affect the mathematics.  Reprocess calls both the
+    input and output jax to completely rebuild the data for
+    mathematics.  The `element` is either the DOM `id` of the element
+    to scan, a reference to the DOM element itself, or an array of
+    id's or references.  The `callback` is called when the processing
+    is complete.
+
+    :Parameters:
+        - **element** --- the element(s) to be reprocessed
+        - **callback** --- the callback specification
+    :Returns: the callback object
+
+.. method:: Rerender([element[,callback]])
+
+    Removes any typeset mathematics from the document or DOM element
+    (or elements if it is an array of elements), and then renders the
+    mathematics again, re-typesetting everything from the current
+    internal version (without calling the input jax again).  The
+    `element` is either the DOM `id` of the element to scan, a
+    reference to the DOM element itself, or an array of id's or
+    references.  The `callback` is called when the processing is
     complete.
 
     :Parameters:
@@ -315,6 +360,21 @@ Methods
         - **element** --- the element to inspect
     :Returns: integer (-1, 0, 1)
 
+.. Method:: setRenderer(renderer[,type])
+
+    Sets the output jax for the given element jax ``type`` (or ``jax/mml``
+    if none is specified) to be the one given by ``renderer``, which
+    must be the name of a renderer, such as ``NativeMML`` or
+    ``HTML-CSS``.  Note that this does not cause the math on the page
+    to be rerendered; it just sets the renderer for output in the
+    future (call :meth:``Rerender()`` above to replace the current
+    renderings by new ones).
+
+    :Parameters:
+        - **renderer** --- the name of the output jax to use for rendering
+	- **type** --- the element jax MIME type whose renderer to set
+    :Returns: ``null``
+
 .. Method:: Insert(dst,src)
 
     Inserts data from the `src` object into the `dst` object.  The

docs/html/_sources/api/inputjax.txt

@@ -56,13 +56,40 @@ Properties
 Methods
 =======
 
-.. Method:: Translate(script)
+.. Method:: Process(script,state)
+    :noindex:
+
+    This is the method that the ``MathJax.Hub`` calls when it needs
+    the input jax to process the given math ``<script>``.  Its default
+    action is to do the following:
+
+    1. Start loading any element jax  specified in the ``elementJax`` array;
+    2. Start loading the jax's ``jax.js`` file;
+    3. Start loading the required output jax (so it is ready when needed); and
+    4. Redefine itself to simply return the callback for the load operation 
+       (so that further calls to it will cause the processing to wait for the 
+       callback).
+
+    Once the ``jax.js`` file has loaded, this method is replaced by
+    the jax's ``Translate()`` method (see below), so that
+    subsequent calls to ``Process()`` will perform the appropriate
+    translation.
+
+    :Parameters:
+        - **script** --- reference to the DOM ``<script>`` object for
+                         the mathematics to be translated
+        - **state** --- a structure containing information about the
+                        current proccessing state of the mathematics
+                        (internal use)
+    :Returns: an `ElementJax` object, or ``null``
+
+.. Method:: Translate(script,state)
     :noindex:
 
     This is the main routine called by MathJax when a ``<script>`` of the
     appropriate type is found.  The default :meth:`Translate()` method
     throws an error indicating that :meth:`Translate()` hasn't been
-    redefined, so when the ``jax.js`` file loads, it should override the
+    defined, so when the ``jax.js`` file loads, it should override the
     default :meth:`Translate()` with its own version that does the actual
     translation. 
 
@@ -72,6 +99,9 @@ Methods
 
     :Parameters:
         - **script**  --- the ``<script>`` element to be translated
+        - **state** --- a structure containing information about the
+                        current proccessing state of the mathematics
+                        (internal use)
     :Returns: the `element jax` resulting from the translation
 
 .. Method:: Register(mimetype)
@@ -87,3 +117,14 @@ Methods
         - **mimetype** --- the MIME-type of the input this jax processes
     :Returns: ``null``
 
+.. Method:: needsUpdate(jax)
+    :noindex:
+
+    This implements the element jax's ``needsUpdate()`` method, and
+    returns ``true`` if the ``jax`` needs to be rerendered (i.e., the
+    text has changed), and ``false`` otherwise.
+
+    :Perameters:
+        - **jax** --- the element jax to be checked
+    :Returns: ``true`` if the jax's text has changed, ``false`` otherwise
+