From 846ebaa4d733cecd0c9c7fc2e40f5b4eb2fd6851 Mon Sep 17 00:00:00 2001
From: "Davide P. Cervone" <dpvc@union.edu>
Date: Fri, 4 Mar 2011 14:57:25 -0500
Subject: [PATCH] Update API documents to match current implementation

---
 docs/source/api/elementjax.rst | 11 ++++---
 docs/source/api/hub.rst        |  9 ++++++
 docs/source/api/inputjax.rst   | 18 ++++++------
 docs/source/api/jax.rst        | 52 ++++++++++++++++++++--------------
 docs/source/api/outputjax.rst  | 15 ++++------
 docs/source/community.rst      |  2 +-
 docs/source/model.rst          |  2 ++
 7 files changed, 63 insertions(+), 46 deletions(-)

diff --git a/docs/source/api/elementjax.rst b/docs/source/api/elementjax.rst
index 8ef996273..a2a2eee1a 100644
--- a/docs/source/api/elementjax.rst
+++ b/docs/source/api/elementjax.rst
@@ -24,7 +24,7 @@ that class.
 Class Properties
 ================
 
-.. describe:: name
+.. describe:: id
 
     The name of the jax.
 
@@ -42,11 +42,13 @@ Instance Properties
 
 .. describe:: inputJax
 
-    A reference to the input jax that created the element.
+    A reference to the input jax that created the element.  (In the 
+    future, this will be changed to the name of the input jax.)
  
 .. describe:: outputJax
 
-    A reference to the output jax that has processed this element.
+    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.)
  
 .. describe:: inputID
 
@@ -61,7 +63,8 @@ Instance Properties
 .. describe:: originalText
 
     A string indicating the original input text that was processed for
-    this element.
+    this element.  (In the future, this may be managed by the input jax 
+    rather than ``MathJax.Hub``.)
 
 .. describe:: mimeType
 
diff --git a/docs/source/api/hub.rst b/docs/source/api/hub.rst
index a226f8c0b..f751815ee 100644
--- a/docs/source/api/hub.rst
+++ b/docs/source/api/hub.rst
@@ -106,6 +106,15 @@ Methods
         - **options** --- object containing options to be set
     :Returns: ``null``
 
+.. describe:: Configured()
+
+    When ``delayStartupUntil`` is specified in the configuration file or
+    in the script that loads ``MathJax.js``, MathJax's startup sequence is 
+    delayed until this routine is called.  See :ref:`Configuring MathJax 
+    <configuration>` for details on how this is used.
+
+    :Returns: ``null``
+
 .. describe:: Register.PreProcessor(callback)
 
     Used by preprocessors to register themselves with MathJax so that
diff --git a/docs/source/api/inputjax.rst b/docs/source/api/inputjax.rst
index 26660f886..52419ad71 100644
--- a/docs/source/api/inputjax.rst
+++ b/docs/source/api/inputjax.rst
@@ -35,7 +35,7 @@ that class.
 Properties
 ==========
 
-.. describe:: name
+.. describe:: id
 
     The name of the jax.
 
@@ -54,15 +54,12 @@ Methods
 .. Method:: Translate(script)
     :noindex:
 
-    This is the main routine called by MathJax when a ``<script>`` of
-    the appropriate type is found.  The default :meth:`Translate()`
-    method simply loads the ``jax.js`` file and returns that callback
-    for that load function so that MathJax will know when to try
-    the :meth:`Translate()` action again.  When the ``jax.js`` file
-    loads, it should override the default :meth:`Translate()` with its
-    own version that does the actual translation; that way, when the
-    second Translate call is made, it will be to the actual
-    translation routine rather than the default loader.
+    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
+    default :meth:`Translate()` with its own version that does the actual
+    translation. 
 
     The translation process should include the creation of an
     :ref:`Element Jax <api-element-jax>` that stores the data needed
@@ -84,3 +81,4 @@ Methods
     :Parameters:
         - **mimetype** --- the MIME-type of the input this jax processes
     :Returns: ``null``
+
diff --git a/docs/source/api/jax.rst b/docs/source/api/jax.rst
index 12bc4a6e4..ebb667f26 100644
--- a/docs/source/api/jax.rst
+++ b/docs/source/api/jax.rst
@@ -15,7 +15,7 @@ Unlike most MathJax.Object classes, calling the class object creates a
 .. code-block:: javascript
 
     MathJax.InputJax.MyInputJax = MathJax.InputJax({
-      name: "MyInputJax",
+      id: "MyInputJax",
       version: "1.0",
       ...
     });
@@ -40,7 +40,7 @@ Class Properties
 Instance Properties
 ===================
 
-.. describe:: name
+.. describe:: id
 
     The name of the jax.
 
@@ -67,35 +67,40 @@ Instance Properties
 Methods
 =======
 
-.. Method:: Translate(script)
+.. Method:: Process(script)
 
-    This is the method that the ``MathJax.Hub`` calls when it needs
-    the input or output jax to process the given math ``<script>``
-    call.  Its default action is to start loading the jax's ``jax.js``
-    file, and redefine the :meth:`Translate()` method to be the
-    :meth:`noTranslate()` method below.  The ``jax.js`` file should
-    redefine the :meth:`Translate()` method to perform the translation
-    operation for the specific jax.  For an input jax, it should
-    return the `ElementJax` object that it created.
+    This is the method that the ``MathJax.Hub`` calls when it needs the 
+    input or output jax to process the given math ``<script>``.  Its 
+    default action is to start loading the jax's ``jax.js`` file, and 
+    redefine itself to simplu return the callback for the laod 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 :meth:`Translate()` method, so that subsequent calls 
+    to :meth:`Process()` will perform the appropriate translation.
 
     :Parameters:
         - **script** --- reference to the DOM ``<script>`` object for
                          the mathematics to be translated
     :Returns: an `ElementJax` object, or ``null``
 
-.. Method:: noTranslate(script)
+.. Method:: Translate(script)
 
-    This is a temporary routine that is used while the ``jax.js`` file
-    is loading.  It throws an error indicating the the
-    :meth:`Translate()` method hasn't been redefined.  That way, if
-    the ``jax.js`` file failes to load for some reason, you will
-    receive an error trying to process mathematics with this input
-    jax.
+    This is a stub for a routine that should be defined by the jax's
+    ``jax.js`` file when it is loaded.  It should perform the translation
+    action for the specific jax.  For an input jax, it should return the
+    `ElementJax` object that it created.  The :meth:`Translate()` mehtod is
+    never called directly by MathJax; during the :meth:`loadComplete()`
+    call, this funciton is copied to the :meth:`Process()` method, and is
+    called via that name.  The default :meth:`Translate()` method throws an
+    error indicating that the :meth:`Translate()` meth was not been
+    redefined.  That way, if the ``jax.js`` file fails to load for some
+    reason, you will receive an error trying to process mathematics with
+    this jax.
 
     :Parameters:
         - **script** --- reference to the DOM ``<script>`` object for
                          the mathematics to be translated
-    :Returns: ``null``
+    :Returns: an `ElementJax` object, or ``null``
 
 .. Method:: Register(mimetype)
 
@@ -136,13 +141,16 @@ Methods
        1. Post the "[name] Jax Config" message to the startup signal.
        2. Perform the jax's :meth:`Config()` method.
        3. Post the "[name] Jax Require" message to the startup signal.
-       4. Load the files from the jax's ``require`` array (which may
-          have been modified during the configuration process).
+       4. Load the files from the jax's ``require`` and 
+          ``config.extensions`` arrays.
        5. Post the "[name] Jax Startup" message to the startup signal.
        6. Perform the jax's :meth:`Startup()` method.
        7. Post the "[name] Jax Ready" message to the startup signal.
        8. perform the :meth:`MathJax.Ajax.loadComplete()` call for the
           ``jax.js`` file.
 
-
+    Note that the configuration process (the :meth:`Config()` call) can 
+    modify the ``require`` or ``config.extensions`` arrays to add more 
+    files that need to be loaded, and that the :meth:`Startup()` method 
+    isn't called until those files are completely loaded.
 
diff --git a/docs/source/api/outputjax.rst b/docs/source/api/outputjax.rst
index 0cfd6725b..8dc6fcb85 100644
--- a/docs/source/api/outputjax.rst
+++ b/docs/source/api/outputjax.rst
@@ -36,7 +36,7 @@ that class.
 Properties
 ==========
 
-.. describe:: name
+.. describe:: id
 
     The name of the jax.
 
@@ -57,16 +57,13 @@ Methods
 
     This is the main routine called by MathJax when an element jax is
     to be converted to output.  The default :meth:`Translate()`
-    method simply loads the ``jax.js`` file and returns that callback
-    for that load function so that MathJax will know when to try
-    the :meth:`Translate()` action again.  When the ``jax.js`` file
-    loads, it should override the default :meth:`Translate()` with its
-    own version that does the actual translation; that way, when the
-    second Translate call is made, it will be to the actual
-    translation routine rather than the default loader.
+    method throws an error indicating that :meth:`Translate()` hasn't been
+    redefined, so when the ``jax.js`` file loads, it should override the
+    default :meth:`Translate()` with its own version that does the actual
+    translation.
 
     You should use ``MathJax.Hub.getJaxFor(script)`` to obtain the
-    element jax for the given script.  The translation process may add
+    element jax for the given script.  The translation process may 
     modify the element jax (e.g., if it has data that needs to be
     stored with the jax), and may insert DOM elements into the
     document near the jax's ``<script>`` tag.
diff --git a/docs/source/community.rst b/docs/source/community.rst
index c2b2f5df9..ceb635627 100644
--- a/docs/source/community.rst
+++ b/docs/source/community.rst
@@ -40,7 +40,7 @@ Issue tracking
 ==============
 
 Found a bug or want to suggest an improvement? Post it to our `issue tracker
-<http://github.com/mathjax/mathjax/issues>`_. We monitor the tracker closely,
+<http://github.com/mathjax/MathJax/issues>`_. We monitor the tracker closely,
 and work hard to respond to problems quickly.
 
 Before you create a new issue, however, please search the issues to see if it
diff --git a/docs/source/model.rst b/docs/source/model.rst
index acc7ea240..1eaf6b670 100644
--- a/docs/source/model.rst
+++ b/docs/source/model.rst
@@ -50,6 +50,8 @@ and it also avoids the conflict between the use of the less-than sign,
 an HTML tag).
 
 
+.. _mathjax-script-tags:
+
 How mathematics is stored in the page
 =====================================