gollum 1.1.1 → 1.2.0

data/lib/gollum/frontend/public/javascript/MathJax/docs/rst/api/outputjax.rst

@@ -0,0 +1,100 @@
+.. _api-output-jax:
+
+***************************
+The MathJax.OutputJax Class
+***************************
+
+Output jax are the components of MathJax that translate
+mathematics from the MathJax internal format (an `element jax`)
+to whatever output is required to represent the mathematics (e.g.,
+MathML elements, or HTML-with-CSS that formats the mathematics on screen).
+
+An output jax is stored as a pair of files in a subdirectory of the
+the ``jax/output`` directory, with the subdirectory name being the
+name of the output jax.  For example, the NativeMML output jax is
+stored in `jax/output/NativeMML`.  The first file, ``config.js``, is
+loaded when MathJax is being loaded and configured, and is indicated
+by listing the input jax directory in the `jax` array of the MathJax
+configuration.  The ``config.js`` file creates a subclass of the
+`MathJax.OutputJax` object for the new output jax and registers it
+with MathJax, along with the MIME-type of the element jax that it can
+process.
+
+The main body of the output jax is stored in the second file, ``jax.js``,
+which is loaded when the output jax is first called on to translate
+some mathematics.  This file augments the original output jax
+subclass with the additional methods needed to produce the output.
+MathJax calls the input jax's :meth:`Translate()` method when it needs
+the output jax to translate an element jax to produce output.
+
+The `MathJax.OutputJax` class is a subclass of the :ref:`MathJax Jax
+<api-jax>` class, and inherits the properties and methods of that
+class.  Those listed below are the additional or overridden ones from
+that class.
+
+
+Properties
+==========
+
+.. describe:: name
+
+    The name of the jax.
+
+.. describe:: version
+
+    The version number of the jax.
+
+.. describe:: directory
+
+    The directory where the jax files are stored (e.g., ``"[MathJax]/jax/output/HTML-CSS"``);
+
+
+Methods
+=======
+
+.. Method:: Translate(script)
+    :noindex:
+
+    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.
+
+    You should use ``MathJax.Hub.getJaxFor(script)`` to obtain the
+    element jax for the given script.  The translation process may add
+    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.
+
+    :Parameters:
+        - **script**  --- the ``<script>`` element to be translated
+    :Returns: the `element jax` resulting from the translation
+ 
+.. Method:: Register(mimetype)
+    :noindex:
+
+    This registers the MIME-type for the element jax associated with
+    this output jax so that MathJax knows to call this jax when it
+    wants to display an element jax of that type.  Several output jax
+    may register for the same input jax, in which case the first one
+    to register will be the default one for that type.
+
+    :Parameters:
+        - **mimetype** --- the MIME-type of the input this jax processes
+    :Returns: ``null``
+
+.. Method:: Remove(jax)
+    :noindex:
+
+    Removes the output associated with the given element jax.  The
+    routine can use ``jax.SourceElement()`` to locate the ``<script>``
+    tag associated with the element jax.
+
+    :Parameters:
+        - **jax** --- the element jax whose display should be removed
+    :Returns: ``null``

data/lib/gollum/frontend/public/javascript/MathJax/docs/rst/api/queue.rst

@@ -0,0 +1,99 @@
+.. _api-queue:
+
+********************************
+The MathJax.Callback.Queue Class
+********************************
+
+The ``MathJax.Callback.Queue`` object is one of the key mechanisms
+used by MathJax to synchronize its actions with those that occur
+asynchronously, like loading files and stylesheets.  A `Queue` obejct
+is used to coordinate a sequence of actions so that they are performed
+one after another, even when one action has to wait for an
+asynchronous process to complete.  This guarantees that operations are
+performed in the right order even when the code must wait for some
+other action to occur.  See :ref:`Synchronizing with MathJax
+<synchronization>` for more details, and :ref:`Using Queues
+<using-queues>` in particular for examples of how to specify and use
+MathJax `Queue` objects.
+
+
+Properties
+----------
+
+.. describe:: pending
+        
+    This is non-zero when the queue is waiting for a command to
+    complete, i.e. a command being processed returns a `Callback`
+    object, indicating that the queue should wait for that action to
+    complete before processing additional commands.
+        
+.. describe:: running
+
+    This is non-zero when the queue is executing one of the commands in
+    the queue.
+
+.. describe:: queue
+
+    An array containing the queued commands that are yet to be performed.
+
+
+Methods
+-------
+
+.. method:: Push(callback,...)
+
+    Adds commands to the queue and runs them (if the queue is not
+    pending or running another command).  If one of the callbacks is
+    an actual `Callback` object rather than a callback specification,
+    then the command queued is an internal command to wait for the
+    given callback to complete.  That is, that callback is not itself
+    queued to be executed, but a wait for that callback is queued.
+    The :meth:`Push()` method returns the last callback that was
+    added to the queue (so that it can be used for further
+    synchronization, say as an entry in some other queue).
+        
+    :Parameters:
+        - **callback** --- the callback specifications to be added to the queue
+    :Returns: the last callback object added to the queue
+
+.. method:: Process()
+   :noindex:
+
+    Process the commands in the queue, provided the queue is not
+    waiting for another command to complete.  This method is used
+    internally; you should not need to call it yourself.
+
+.. method:: Suspend()
+
+    Increments the `running` property, indicating that any commands that
+    are added the queue should not be executed immediately, but should
+    be queued for later execution (when its :meth:`Resume()` is
+    called).  This method is used internally; you should not need to
+    call it yourself.
+
+.. method:: Resume()
+
+    Decrements the `running` property, if it is positive.  When it is
+    zero, commands can be processed, but that is not done
+    automatically --- you would need to call :meth:`Process()` to make
+    that happen.  This method is used internally; you should not need
+    to call it yourself.
+
+.. method:: wait(callback)
+
+    Used internally when an entry in the queue is a `Callback` object
+    rather than a callback specification.  A callback to this function
+    (passing it the original callback) is queued instead, and it
+    simply returns the callback it was passed. Since the queue will
+    wait for a callback if it is the return value of one of the
+    commands it executes, this effectively make the queue wait for the
+    original callback at that point in the command queue.
+
+    :Parameters:
+        - **callback** --- the function to complete before returning to the queue
+    :Returns: the passed callback function
+
+.. method:: call()
+
+    An internal function used to restart processing of the queue after
+    it has been waiting for a command to complete.

data/lib/gollum/frontend/public/javascript/MathJax/docs/rst/api/signal.rst

@@ -0,0 +1,154 @@
+.. _api-signal:
+
+*********************************
+The MathJax.Callback.Signal Class
+*********************************
+
+The ``MathJax.Callback.Signal`` object is one of the key mechanisms
+used by MathJax to synchronize its actions with those that occur
+asynchronously, like loading files and stylesheets.  A `Signal` object
+is used to pulicise the fact that MathJax has performed certain
+actions, giving other code running the the web page the chance to
+react to those actions.  See :ref:`Synchronizing with MathJax
+<synchronization>` for more details, and :ref:`Using Signals
+<using-signals>` in particular for examples of how to specify and use
+MathJax `Signal` objects.
+
+The `Callback Signal` object is a subclass of the :ref:`Callback Queue
+<api-queue>` object.
+
+
+Properties
+----------
+
+.. describe:: name
+
+    The name of the signal.  Each signal is named so that
+    various components can access it.  The first one to request a
+    particular signal causes it to be created, and other requests for
+    the signal return references to the same object.
+
+.. describe:: posted
+
+    Array used internally to stored the post history so that when new
+    listeners express interests in this signal, they can be informed
+    of the signals that have been posted so far.  This can be cleared
+    using the signal's :meth:`Clear()` method.
+
+.. describe:: listeners
+
+    Array of callbacks to the listeners who have expressed interest in
+    hearing about posts to this signal.  When a post occurs, the
+    listeners are called in each turn, passing them the message that
+    was posted.
+
+
+Methods
+-------
+
+.. method:: Post(message[,callback])
+
+    Posts a message to all the listeners for the signal.  The listener
+    callbacks are called in turn (with the message as an argument),
+    and if any return a `Callback` object, the posting will be
+    suspended until the callback is exectured.  In this way, the
+    :meth:`Post()` call can operate asynchronously, and so the
+    `callback` parameter is used to synchronize with its operation;
+    the `callback` will be called when all the listeners have responded
+    to the post.
+        
+    If a :meth:`Post()` to this signal occurs while waiting for the
+    response from a listener (either because a listener returned a
+    `Callback` object and we are waiting for it to complete when the
+    :meth:`Post()` occurred, or because the listener itself called the
+    ``Post()`` method), the new message will be queued and will be
+    posted after the current message has been sent to all the
+    listeners, and they have all responded.  This is another way in
+    which posting can be asynchronous; the only sure way to know that
+    a posting has occurred is through its `callback`. When the posting
+    is complete, the callback is called, passing it the signal object
+    that has just completed.
+        
+    Returns the callback object (or a blank callback object if none
+    was provided).
+
+    :Parameters:
+        - **message** --- the message to send through the signal
+        - **callback** --- called after the message is posted
+    :Returns: the callback or a blank callback
+
+.. method:: Clear([callback])
+    :noindex:
+
+    This causes the history of past messages to be cleared so new
+    listeners will not receive them.  Note that since the signal may
+    be operating asynchronously, the :meth:`Clear()` may be queued for
+    later.  In this way, the :meth:`Post()` and :meth:`Clear()`
+    operations will be performed in the proper order even when they
+    are delayed.  The `callback` is called when the :meth:`Clear()`
+    operation is completed.
+        
+    Returns the callback (or a blank callback if none is provided).
+
+    :Parameters:
+	- **callback** --- called after the signal history is cleared
+    :Returns: the callback or a blank callback
+
+.. method:: Interest(callback[,ignorePast])
+
+    This method registers a new listener on the signal.  It creates a
+    `Callback` object from the callback specification, attaches it to
+    the signal, and returns that `Callback` object.  When new messages
+    are posted to the signal, it runs the callback, passing it the
+    message that was posted.  If the callback itself returns a
+    `Callback` object, that indicates that the listener has started an
+    asynchronous operation and the poster should wait for that
+    callback to complete before allowing new posts on the signal.
+
+    If `ignorePast` is ``false`` or not present, then before
+    :meth:`Interest()` returns, the callback will be called with all
+    the past messages that have been sent to the signal.
+
+    :Parameters:
+	- **callback** --- called whenever a message is posted (past or present)
+	- **ignorePast** --- ``true`` means ignore previous messages
+    :Returns: the callback object
+        
+.. method:: NoInterest(callback)
+
+    This removes a listener from the signal so that no new messages
+    will be sent to it.  The callback should be the one returned by
+    the original :meth:`Interest()` call that attached the listener to
+    the signal in the first place.  Once removed, the listener will no
+    longer receive messages from the signal.
+
+    :Parameters:
+	- **callback** --- the listener to be removed from signal
+    :Returns: ``null``
+
+.. method:: MessageHook(message, callback)
+
+    This creates a callback that is called whenever the signal posts
+    the given message.  This is a little easier than having to write a
+    function that must check the message each time it is called.
+    Although the `message` here is a string, if a message posted to the
+    signal is an array, then only the first element of that array is
+    used to match against message.  That way, if a message contains an
+    identifier plus arguments, the hook will match the identifier and
+    still get called with the complete set of arguments.
+        
+    Returns the `Callback` object that was produced.
+
+    :Parameters:
+        - **message** --- the message to look for from the signal
+	- **callback** --- called when the message is posted
+    :Returns: the callback object
+
+.. method:: ExecuteHook(message)
+
+    Used internally to call the listeners when a particular
+    message is posted to the signal.
+
+    :Parameters:
+        - **message** --- the posted message
+    :Returns: ``null``

data/lib/gollum/frontend/public/javascript/MathJax/docs/rst/api/variable.rst

@@ -0,0 +1,83 @@
+********************
+The MathJax variable
+********************
+
+MathJax has a single global variable, ``MathJax``, in which all its
+data, and the data for loaded components, are stored.  The MathJax
+variable is a nested structure, with its top-level properties being
+objects themselves.
+
+
+Main MathJax Components
+=======================
+
+.. describe:: MathJax.Hub
+
+    Contains the MathJax hub code and variables, including the startup
+    code, the onload handler, the browser data, and so forth.
+    
+.. describe:: MathJax.Ajax
+
+    Contains the code for loading external modules and creating
+    stylesheets.  Most of the code that causes most of MathJax to
+    operate asynchronously is handled here.
+
+.. describe:: MathJax.Message
+
+   Contains the code to handle the intermittant message window that
+   periodically appears in the lower left-hand corner of the window.
+
+.. describe:: MathJax.HTML
+
+   Contains support code for creating HTML elements dynamically from
+   descriptions stored in JavaScript objects.
+    
+.. describe:: MathJax.CallBack
+
+    Contains the code for managing MathJax callbacks, queues and
+    signals.
+
+.. describe:: MathJax.Extensions
+
+    Initially empty, this is where extensions can load their code.
+    For example, the `tex2jax` preprocessor creates
+    ``MathJax.Extensions.tex2jax`` for its code and variables.
+
+.. describe:: MathJax.Object
+
+    Contains the code for the MathJax object-oriented programming model.
+
+
+.. describe:: MathJax.InputJax
+
+    The base class for all input `jax` objects.  Subclasses for
+    specific input jax are created as sub-objects of
+    ``MathJax.InputJax``. For example, the TeX input jax loads itself
+    as ``MathJax.InputJax.TeX``.
+
+.. describe:: MathJax.OutputJax
+
+    The base class for all output `jax` objects.  Subclasses for
+    specific output jax are created as sub-objects of
+    ``MathJax.OutputJax``.  For example, the HTML-CSS output jax loads
+    itself as ``MathJax.OutputJax["HTML-CSS"]``.
+
+.. describe:: MathJax.ElementJax
+
+    The base class for all element `jax` objects.  Subclasses for
+    specific element jax are creates as sub-objects of
+    ``MathJax.ElementJax``.  For example, the mml element jax loads
+    itself as ``MathJax.ElementJax.mml``.
+
+
+Properties
+==========
+
+.. describe:: MathJax.version
+
+    The version number of the MathJax library.
+
+.. describe:: MathJax.isReady
+
+    This is set to ``true`` when MathJax is set up and ready to
+    perform typesetting actions (and is ``null`` otherwise).

data/lib/gollum/frontend/public/javascript/MathJax/docs/rst/callbacks.rst

@@ -0,0 +1,228 @@
+.. _using-callbacks:
+
+***************
+Using Callbacks
+***************
+
+A "callback" is a function that MathJax calls when it completes an
+action that may occur asynchronously (like loading a file).  Many of
+MathJax's functions operate asynchronously, and MathJax uses callbacks
+to allow you to synchronize your code with the action of those
+functions.  The `MathJax.Callback` structure manages these callbacks.
+Callbacks can include not only a function to call, but also data to be
+passed to the function, and an object to act as the JavaScript `this`
+value in the resulting call (i.e., the object on which the callback is
+to execute).
+
+Callbacks can be collected into :ref:`Queues <using-queues>` where the
+callbacks will be processed in order, with later callbacks waiting
+until previous ones have completed before they are called.  They are
+also used with :ref:`Signals <using-signals>` as the means of
+receiving information about the signals as they occur.  
+
+A number of methods in `MathJax.Hub` and `MathJax.Ajax` accept
+callback specifications as arguments and return callback structures.
+These routines always will return a callback even when none was
+specified in the arguments, and in that case, the callback is a "do
+nothing" callback.  The reason for this is so that the resulting
+callback can be used can be used in a `MathJax.Callback.Queue` for
+synchronization purposes, so that the actions following it in the
+queue will not be performed until after the callback has been fired.
+
+For example, the :meth:`MathJax.Ajax.Require()` method can be used to
+load external files, and it returns a callback that is called when the
+file has been loaded and executed.  If you want to load several files
+and wait for them all to be loaded before performing some action, you
+can create a `Queue` into which you push the results of the
+:meth:`MathJax.Ajax.Require()` calls, and then push a callback for the
+action.  The final action will not be performed until all the
+file-load callbacks (which preceed it int he queue) have been called;
+i.e., the action will not occur until all the files are loaded.
+
+
+Specifying a Callback
+---------------------
+
+Callbacks can be specified in a number of different ways, depending on
+the functionality that is required of the callback.  The easiest case
+is to simply provide a function to be called, but it is also possible
+to include data to pass to the function when it is called, and to
+specify the object that will be used as `this` when the function is
+called.
+
+For example, the :meth:`MathJax.Ajax.Require()` method can accept a
+callback as its second argument (it will be called when the file given
+as the first argument is loaded and executed).  So you can call
+
+.. code-block:: javascript
+
+    MathJax.Ajax.Require("[MathJax]/config/myConfig.js",function () {
+      alert("My configuration file is loaded");
+    });
+
+and an alert will appear when the file is loaded.  An example of
+passing arguments to the callback function includes the following:
+
+.. code-block:: javascript
+
+    function loadHook (x) {alert("loadHook: "+x)}
+    MathJax.Ajax.Require("[MathJax]/config/myConfig.js",[loadHook,"myConfig"]);
+
+Here, the ``loadHook()`` function accepts one argument and generates
+an alert that includes the value passed to it.  The callback in the
+:meth:`MathJax.Ajax.Require()` call is ``[loadHook,"myConfig"]``,
+which means that (the equivalent of) ``loadHook("myConfig")`` will be
+performed when the file is loaded.  The result should be an alert with
+the text `loadHook: myConfig`.
+
+The callback for the :meth:`MathJax.Ajax.Require()` method actually
+gets called with a status value, in addition to any parameters already
+included in the callback specification, that indicates whether the
+file loaded successfully, or failed for some reason (perhaps the file
+couldn't be found, or it failed to compile and run).  So you could use
+
+.. code-block:: javascript
+
+    MathJax.Ajax.Require("[MathJax]/config/myConfig.js",function (status) {
+      if (status === MathJax.Ajax.STATUS.OK) {
+        alert("My configuration file is loaded");
+      } else {
+        alert("My configuration file failed to load!");
+      }
+    });
+
+to check if the file loaded properly.  With additional parameters, the
+example might be
+
+.. code-block:: javascript
+
+    function loadHook (x,status) {alert("loadHook: "+x+" has status "+status)}
+    MathJax.Ajax.Require("[MathJax]/config/myConfig.js",[loadHook,"myConfig"]);
+
+Note that the parameters given in the callback specification are used
+first, and then additional parameters from the call to the callback
+come afterward.
+
+
+Callbacks to Object Methods
+===========================
+
+When you use a method of a JavaScript object, a special variable
+called `this` is defined that refers to the object whose method is
+being called.  It allows you to access other methods or properties of
+the object without knowing explicitly where the object is stored.
+
+For example,
+
+.. code-block:: javascript
+
+    var aPerson = {
+      firstname: "John",
+      lastname: "Smith",
+      showName: function () {alert(this.firstname+" "+this.lastname)}
+    };
+
+creates an object that contains three items, a `firstname`, and
+`lastname`, and a method that shows the person's full name in an
+alert.  So ``aPerson.fullName()`` would cause an alert with the text
+``John Smith`` to appear.  Note, however that this only works if the
+method is called as ``aPerson.showName()``; if instead you did
+
+.. code-block:: javascript
+
+    var f = aPerson.showName;  // assign f the function from aPerson
+    f();                       // and call the function
+
+the association of the function with the data in ``aPerson`` is lost,
+and the alert will probably show ``undefined undefined``.  (In this
+case, ``f`` will be called with ``this`` set to the ``window``
+variable, and so ``this.firstname`` and ``this.lastname`` will refer
+to undefined values.)
+
+Because of this, it is difficult to use an object's method as a
+callback if you refer to it as a function directly.  For example,
+
+.. code-block:: javascript
+
+    var aFile = {
+      name: "[MathJax]/config/myConfig.js",
+      onload: function (status) {
+        alert(this.name+" is loaded with status "+status);
+      }
+    };
+
+    MathJax.Ajax.Require(aFile.name,aFile.onload);
+
+would produce an alert indicating that "undefined" was loaded with a
+particular status.  That is because ``aFile.onload`` is a reference to
+the `onload` method, which is just a function, and the association
+with the `aFile` object is lost.  One could do 
+
+.. code-block:: javascript
+
+    MathJax.Ajax.Require(aFile.name,function (status) {aFile.onload(status)});
+
+but that seems needlessly verbose, and it produces a closure when one
+is not really needed.  Instead, MathJax provides an alternative
+specification for a callback that allows you to specify both the
+method and the object it comes from:
+
+.. code-block:: javascript
+
+    MathJax.Ajax.Require(aFile.name,["onload",aFile]);
+
+This requests that the callback should call ``aFile.onload`` as the
+function, which will maintain the connection between ``aFile`` and its
+method, thus preserving the correct value for `this` within the method.
+
+As in the previous cases, you can pass parameters to the method as
+well by including them in the array that specifies the callback:
+
+.. code-block:: javascript
+
+    MathJax.Ajax.Require("filename",["method",object,arg1,arg2,...]);
+
+This approach is useful when you are pushing a callback for one one
+MathJax's Hub routines into the MathJax processing queue.  For example,
+
+.. code-block:: javascript
+
+    MathJax.Hub.Queue(["Typeset",MathJax.Hub,"MathDiv"]);
+
+pushes the equivalent of ``MathJax.Hub.Typeset("MathDiv")`` into the
+processing queue.
+
+See the :ref:`Callback Object <api-callback>` reference pages for more
+information about the valid methods of specifying a callback.
+
+
+Creating a Callback Explicitly
+==============================
+
+When you call a method that accpets a callback, you usually pass it a
+callback specification (like in the examples above), which *describes*
+a callback (the method will create the actual `Callback` object, and
+return that to you as its return value).  You don't usually create
+`Callback` objects directly yourself.
+
+There are times, however, when you may wish to create a callback
+object for use with functions that don't create callbacks for you.
+For example, the ``setTimeout()`` function can take a function as its
+argument, and you may want that function to be a method of an object,
+and would run into the problem described in the previous section if
+you simply passed the object's method to ``setTimeout()``.  Or you
+might want to pass an argument to the function called by
+``setTimeout()``.  (Altough the ``setTimeout()`` function can accept
+additional arguements that are supposed to be passed on to the code
+when it is called, Internet Explorer does not implement that feature,
+so you can't rely on it.)  You can use a `Callback` object to
+do this, and the :meth:`MathJax.Callback()` method will create one for
+you.  For example,
+
+.. code-block:: javascript
+
+    function myTimer (x) {alert("x = "+x)}
+    setTimeout(MathJax.Callback([f,"Hello World!"]),500);
+
+would create a callback that calls ``f("Hello World!")``, and
+schedules it to be called in half a second.