gollum 1.1.1 → 1.2.0

data/lib/gollum/frontend/public/javascript/MathJax/docs/rst/platforms/wordpress.rst

@@ -0,0 +1,42 @@
+.. _platform-wordpress:
+
+===============================
+Installing MathJax in WordPress
+===============================
+
+These instructions assume you already have placed the MathJax files on
+your server (see :ref:`Installing MathJax <installation>`).
+
+1. Open the WordPress admin interface.
+
+2. In the administration menu on the left, open up the `Appearance`
+   menu and click on the `Editor` submenu option.
+ 
+     .. image:: ../images/wp_menu.png
+ 
+   When you click on the editor option, WordPress should open up the
+   first stylesheet in the current theme.
+ 
+3. In the template list on the right side of the page, click on the
+   header file (it should be ``header.php``).
+ 
+     .. image:: ../images/wp_templates.png
+ 
+   This part depends slightly on how your current theme is written.
+   In the ``header.php`` file, look for the end-of-head tag,
+   ``</head>``. If you find it, insert
+
+   .. code-block:: html
+
+       <script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>
+
+   just before that.  Otherwise, insert the same code at the very
+   bottom of the file.  Here, ``path-to-MathJax`` should be replaced
+   by the web-address of the main MathJax directory on your server,
+   e.g., ``src="/mathjax/MathJax.js"``.
+ 
+4. Save the file.  This should enable MathJax, so you should be able to
+   start adding mathematical content to your pages.  Use the
+   ``config/MathJas.js`` file in the MathJax directory to configure
+   MathJax to your needs (see :ref:`Configuring MathJax
+   <configuration>` for details).

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

@@ -0,0 +1,254 @@
+.. _using-queues:
+
+************
+Using Queues
+************
+
+The `callback queue` is one of MathJax's main tools for synchronizing
+its actions, both internally, and with external programs, like
+javascript code that you may write as part of dynamic web pages.
+Because many actions in MathJax (like loading files) operate
+asynchornously, MathJax needs a way to coordinate those actions so
+that they occur in the right order.  The
+`MathJax.Callback.Queue` object provides that mechanism.
+
+A `callback queue` is a list of commands that will be performed one at
+a time, in order.  If the return value of one of the commands is a
+`Callback` object, processing is suspended until that callback is
+called, and then processing of the commands is resumed.  In this way,
+if a command starts an asynchronous operation like loading a file, it
+can return the callback for that file-load operation and the queue
+will wait until the file has loaded before continuing.  Thus a queue
+can be used to guarantee that commands don't get performed until other
+ones are known to be finished, even if those commands usually operate
+asynchronously.
+
+
+Constructing Queues
+===================
+
+A queue is created via the :meth:`MathJax.Callback.Queue()` command,
+which returns a `MathJax.Callback.Queue` object. The queue
+itself consists of a series of commands given as callback
+specifications (see :ref:`Using Callbacks <using-callbacks>` for
+details on callbacks), which allow you to provide functions (together
+with their arguments) to be executed.  You can provide the collection
+of callback specifications when the queue is created by passing them
+as arguments to :meth:`MathJax.Callback.Queue()`, or you can create an
+empty queue to which commands are added later.  Once a
+`MathJax.Callback.Queue` object is created, you can push
+additional callbacks on the end of the queue; if the queue is empty,
+the command will be performed immediately, while if the queue is
+waiting for another command to complete, the new command will be
+queued for later processing.
+
+For example,
+
+.. code-block:: javascript
+
+    function f(x) {alert(x)}
+    var queue = MathJax.Callback.Queue([f, 15], [f, 10], [f, 5]);
+    queue.Push([f, 0]);
+
+would create a queue containing three commands, each calling the
+function ``f`` with a different input, that are performed in order.  A
+fourth command is then added to the queue, to be performed after the
+other three.  In this case, the result will be four alerts, the first
+with the number 15, the second with 10, the third with 5 and the
+fourth with 0.  Of course ``f`` is not a function that operates
+asynchronously, so it would have been easier to just call ``f`` four
+times directly.  The power of the queue comes from calling commands
+that could operate asynchronously.  For example:
+
+.. code-block:: javascript
+
+    function f(x) {alert(x)}
+    MathJax.Callback.Queue(
+      [f, 1],
+      ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"],
+      [f, 2]
+    );
+
+Here, the command ``MathJax.Ajax.require("extensions/AMSmath.js")`` is
+queued between two calls to ``f``.  The first call to ``f(1)`` will be
+made immediately, then the :meth:`MathJax.Ajax.Require` statement will
+be performed.  Since the ``Require`` method loads a file, it operates
+asynchronously, and its return value is a `MathJax.Callback`
+object that will be called when the file is loaded.  The call to
+``f(2)`` will not be made until that callback is performed,
+effectively synchronizing the second call to ``f`` with the completion
+of the file loading.  This is equivalent to
+
+.. code-block:: javascript
+
+    f(1);
+    MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js", [f, 2]);
+
+since the ``Require()`` command allows you to specify a (single)
+callback to be performed on the completion of the file load.  Note,
+however, that the queue could be used to synchronize several file
+loads along with multiple function calls, so is more flexible.
+
+For example,
+
+.. code-block:: javascript
+
+    MathJax.Callback.Queue(
+      ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"],
+      [f, 1],
+      ["Require", MathJax.Ajax, "[MathJax]/config/local/AMSmathAdditions.js"],
+      [f, 2]
+    );
+
+would load the AMSmath extension, then call ``f(1)`` then load the
+local AMSmath modifications, and then call ``f(2)``, with each action
+waiting for the previous one to complete before being performed
+itself.
+
+
+Callbacks versus Callback Specifications
+========================================
+
+If one of the callback specifications is an actual callback object
+itself, then the queue will wait for that action to be performed
+before proceeding.  For example,
+
+.. code-block:: javascript
+
+    MathJax.Callback.Queue(
+        [f, 1],
+        MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js"),
+        [f, 2],
+   );
+
+starts the loading of the AMSmath extension before the queue is
+created, and then creates the queue containing the call to ``f``, the
+callback for the file load, and the second call to ``f``.  The queue
+performs ``f(1)``, waits for the file load callback to be called, and
+then calls ``f(2)``.  The difference between this and the second
+example above is that, in this example the file load is started before
+the queue is even created, so the file is potentially loaded and
+executed before the call to ``f(1)``, while in the example above, the
+file load is guaranteed not to begin until after ``f(1)`` is executed.
+
+As a further example, consider
+
+.. code-block:: javascript
+
+    MathJax.Callback.Queue(
+      MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js"),
+      [f, 1],
+      MathJax.Ajax.Require("[MathJax]/config/local/AMSmathAdditions.js"),
+      [f, 2]
+    );
+
+in comparison to the example above that uses ``["Require",
+MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"]`` and ``["Require",
+MathJax.Ajax, "[MathJax]/config/local/AMSmathAdditions.js"]`` instead.  In that
+example, ``AMSmath.js`` is loaded, then ``f(1)`` is called, then the
+local additions are loaded, then ``f(2)`` is called.
+
+Here, however, both file loads are started before the queue is
+created, and are operating in parallel (rather than sequentially as in
+the earlier example).  It is possible for the loading of the local
+additions to complete before the AMSmath extension is loaded in this
+case, which was guaranteed **not** to happen in the other example.
+Note, however, that ``f(1)`` is guaranteed not to be performed until
+after the AMSmath extensions load, and ``f(2)`` will not occur until
+after both files are loaded.
+
+In this way, it is possible to start asynchronous loading of several
+files simultaneously, and wait until all of them are loaded (in
+whatever order) to perform some command.  For instance,
+
+.. code-block:: javascript
+
+    MathJax.Callback.Queue(
+        MathJax.Ajax.Require("file1.js"),
+        MathJax.Ajax.Require("file2.js"),
+        MathJax.Ajax.Require("file3.js"),
+        MathJax.Ajax.Require("file4.js"),
+        [f, "all done"]
+    );
+
+starts four files loading all at once, and waits for all four to
+complete before calling ``f("all done")``. The order in which they
+complete is immaterial, and they all are being requested
+simultaneously.
+
+
+The MathJax Processing Queue
+============================
+
+MathJax uses a queue stored as ``MathJax.Hub.queue`` to regulate its
+own actions so that they operate in the right order even when some
+of them include asynchronous operations.  You can take advantage of
+that queue when you make calls to MathJax methods that need to be
+synchronized with the other actions taken by MathJax.  It may not
+always be apparent, however, which methods fall into that category.
+
+The main source of asynchronous actions in MathJax is the loading of
+external files, so any action that may cause a file to be loaded may
+act asynchronously.  Many important actions do so, including some that
+you might not expect; e.g., typesetting mathematics can cause files to
+be loaded.  This is because some TeX commands, for example, are rare
+enough that they are not included in the core TeX input processor, but
+instead are defined in extensions that are loaded automatically when
+needed.  The typesetting of an expression containing one of these TeX
+commands can cause the typesetting process to be suspended while the
+file is loaded, and then restarted when the extension has become
+evailable.
+
+As a result, any call to :meth:`MathJax.Hub.Typeset()` (or
+:meth:`MathJax.Hub.Process()`, or :meth:`MathJax.Hub.Update()`, etc.)
+could return long before the mathematics is actually typeset, and the
+rest of your code may run before the mathematics is available.  If you
+have code that relys on the mathematics being visible on screen, you
+will need to break that out into a separate operation that is
+synchronized with the typesetting via the MathJax queue.
+
+Furthermore, your own typesetting calls may need to wait for file loading
+to occur that is already underway, so even if you don't need to access
+the mathematics after it is typeset, you may still need to queue the
+typeset command in order to make sure it is properly synchronized with
+*previous* typeset calls.  For instance, if an earlier call
+started loading an extension and you start another typeset call before
+that extension is fully loaded, MathJax's internal state may be in
+flux, and it may not be prepared to handle another typeset operation
+yet.  This is even more important if you are using other libraries
+that may call MathJax, in which case your code may not be aware of the
+state that MathJax is in.
+
+For these reasons, it is always best to perform typesetting operations
+through the MathJax queue, and the same goes for any other action
+that could cause files to load.  A good rule of thumb is that, if a
+MathJax function includes a callback argument, that function may operate
+asynchronously; you should use the MathJax queue to perform it and
+any actions that rely on its results.
+
+To place an action in the MathJax queue, use the
+:meth:`MathJax.Hub.Queue()` command.  For example
+
+.. code-block:: javascript
+
+    MathJax.Hub.Queue(["Typeset",MathJax.Hub,"MathDiv"]);
+
+would queue the command ``MathJax.Hub.Typeset("MathDiv")``, causing
+the contents of the DOM element with `id` equal to ``MathDiv`` to be
+typeset.
+
+One of the uses of the MathJax queue is to allow you to synchronize an
+action with the startup process for MathJax.  If you want to have a
+function performed after MathJax has become completely set up (and
+performed its initial typesetting of the page), you can push it onto
+the ``MathJax.Hub.queue`` so that it won't be performed until MathJax
+finishes everything it has queued when it was loaded.  For example,
+
+.. code-block:: html
+
+    <script type="text/javascript" src="/MathJax/MathJax.js"></script>
+    <script>
+      MathJax.Hub.Queue(function () {
+        // ... your startup commands here ...
+      });
+    </script>

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

@@ -0,0 +1,161 @@
+.. _using-signals:
+
+*************
+Using Signals
+*************
+
+Because much of MathJax operates asynchronously, it is important for
+MathJax to be able to indicated to other components operating on the
+page that certain actions have been taken.  For example, as MathJax is
+starting up, it loads external files such as its configuration files
+and the various input and output :term:`jax` that are used on the
+page.  This means that MathJax may not be ready to run until well
+after the ``<script>`` tag that loads ``MathJax.js`` has executed.  If
+another component on the page needs to call MathJax to process some
+mathematics, it will need to know when MathJax is ready to do that.
+Thus MathJax needs a way to signal other components that it is
+initialized and ready to process mathematics.  Other events that might
+need to be signaled include the appearance of newly processed
+mathematics on the web page, the loading of a new extension, and so
+on.
+
+The mechanism provided by MathJax for handling this type of
+communication is the :term:`Callback Signal`.  The `Callback Signal`
+object provides a standardized mechanism for sending and receiving
+messages between MathJax and other code on the page.  A signal acts
+like a mailbox where MathJax places messages for others to read.
+Those interested in seeing the messages can register an interest in
+receiving a given signal, and when MathJax posts a message on that
+signal, all the interested parties will be notified.  No new posts to
+the signal will be allowed until everyone who is listening to the
+signal has had a chance to receive the first one.  If a signal causes
+a listener to begin an asynchronous operation (such as loading a
+file), the listener can indicate that its reply to the signal is going
+to be delayed, and MathJax will wait until the asynchronous action is
+complete before allowing additional messages to be posted to this
+signal.  In this way, posting a signal may itself be an asynchronous
+action.
+
+The posts to a signal are cached so that if a new listener expresses
+an interest in the signal, it will receive all the past posts as well
+as any future ones.  For example, if a component on the page needs to
+know when MathJax is set up, it can express an interest in the startup
+signal's ``End`` message.  If MathJax is not yet set up, the component
+will be signaled when MathJax is ready to begin, but if MathJax is
+already set up, the component will receive the ``End`` message
+immediately, since that message was cached and is available to any new
+listeners.  In this way, signals can be used to pass messages without
+worrying about the timing of when the signaler and listener are ready
+to send or receive signals:  a listener will receive messages even if
+it starts listening after they were sent.
+
+One way that MathJax makes use of this feature is in configuring its
+various extensions.  The extension may not be loaded when the user's
+configuration code runs, so the configuration code can't modify the
+extension because it isn't there yet.  Fortunately, most extensions
+signal when they are set up via an ``Extension [name] Ready`` message,
+so the configuration code can set up a listener for that message, and
+have the listener perform the configuration when the message arrives.
+But even if the extension *has* already been loaded, this will still
+work, because the listener will receive the ready signal even if it
+has already been posted.  In this way, listening for signals is a
+robust method of synchonizing code components no matter when they are
+loaded and run.
+
+In some cases, it may be inappropriate for a new listener to receive
+past messages that were sent to a signal object. There are two ways to
+handle this: first, a new listener can indicate that it doesn't want
+to hear old messages when it attaches itself to a signal object.  The
+sender can also indicate that past messages are not appropriate for
+new listeners.  It does this by clearing the message history so that
+new listeners have no old posts to hear.
+
+The actual message passed along the signal can be anything, but is
+frequently a string constant indicating the message value.  It could
+also be a JavaScript array containing data, or an object containing
+`key:value` pairs.  All the listeners receive the data as part of the
+message, and can act on it in whatever ways they see fit.
+
+Creating a Listener
+===================
+
+MathJax maintains two separate signal channels: the `startup signal`
+and the `processing signal` (or the `hub signal`).  The startup signal
+is where the messages about different components startup up and
+becoming ready appear.  The processing signal is where the messages
+are sent about processing mathematics, like the ``New Math`` messages
+for when newly typeset mathematics appears on the page.  The latter is
+cleared when a new processing pass is started (so messages from past
+processing runs are not kept).
+
+The easiest way to create a listener is to use either
+:meth:`MathJax.Hub.Register.StartupHook()` or
+:meth:`MathJax.Hub.Register.MessageHook()`.  The first sets a listener
+on the startup signal, and the latter on the hub processing signal.
+You specify the message you want to listen for, and a callback to be
+called when it arrives.  For example
+
+.. code-block:: javascript
+
+    MathJax.Hub.Register.StartupHook("TeX Jax Ready ",function () {
+      alert("The TeX input jax is loaded and ready!");
+    });
+
+See the :ref:`MathJax Startup Sequence <startup-sequence>` page for
+details of the messages sent during startup.  See also the
+``test/sample-signals.html`` file (and its source) for examples of
+using signals.  This example lists all the signals that occur while
+MathJax is processing that page, so it gives useful information about
+the details of the signals produced by variuous components.
+
+In this example, the listener starts loading an extra configuration
+file (from the same directory as the web page).  Since it returns
+the callback from that request, the signal processing will wait until
+that file is completely loaded before it continues; that is, the
+configuration process is suspended until the extra configuration file
+has loaded.
+
+.. code-block:: javascript
+
+    MathJax.Hub.Register.StartupHook("Begin Config",
+      function () {return MathJax.Ajax.Require("myConfig.js")}
+    );
+
+Here is an example that produces an alert each time new mathematics
+is typeset on the page.  The message includes the DOM `id` of the
+element on the page that contains the newly typeset mathematics as its
+second element, so this listener locates the ``<script>`` tag
+for the math, and displays the original source mathematics for it.
+
+.. code-block:: javascript
+
+    MathJax.Hub.Register.MessageHook("New Math", function (message) {
+      var script = MathJax.Hub.getJaxFor(message[1]).SourceElement();
+      alert(message.join(" ")+": '"+script.text+"'");
+    })
+
+
+Listening for All Messages
+==========================
+
+If you want to process *every* message that passes through a signal
+channel, you can do that by registering an interest in the signal
+rather than registering a message hook.  You do this by calling the
+signal's :meth:`Interest()` method, as in the following example.
+
+.. code-block:: javascript
+
+    MathJax.Hub.Startup.signal.Interest(
+      function (message) {alert("Startup: "+message)}
+    );
+    MathJax.Hub.signal.Interest(
+      function (message) {alert("Hub: "+message)}
+    );
+
+This will cause an alert for every signal that MathJax produces.  You
+probably don't want to try this out, since it will produce a *lot* of
+them; instead, use the ``test/sample-signals.html`` file, which
+displays them in the web page.
+
+See the :ref:`Signal Object <api-signal>` reference page for details on the
+structure and methods of the signal object.