RubyGems - gollum - Versions diffs - 1.1.1 → 1.2.0 - Mend

gollum 1.1.1 → 1.2.0

Potentially problematic release.

This version of gollum might be problematic. Click here for more details.

Files changed (765) hide show

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

@@ -0,0 +1,44 @@
+.. _mathjax-api:
+===============
+The MathJax API
+===============
+The following links document the various components that make up
+MathJax.  These are implemented as JavaScript objects contained within
+the single global variable, ``MathJax``.  Although JavaScript includes
+an objects with some inheritance capabilities, they do not constitute
+a full object-oriented programming model, so MathJax implements
+its own object library.  This means there is an ambiguity when we
+speak of an "object", as it could be either a native JavaScript
+object, or a MathJax object.  We will use `Object` (capitalized) or
+`MathJax.Object` for, when the distinction is important.
+You may also want to view the :ref:`advanced topics <advanced-topics>`
+on the main MathJax documentation page.
+.. toctree::
+    :maxdepth: 1
+    The MathJax variable <variable>
+    The MathJax.Hub object <hub>
+    The MathJax.Ajax object <ajax>
+    The MathJax.Message object <message>
+    The MathJax.HTML object <html>
+    The MathJax.CallBack class <callback>
+    The MathJax.CallBack.Queue class <queue>
+    The MathJax.CallBack.Signal class <signal>
+.. toctree::
+    :maxdepth: 1
+    The MathJax.InputJax class <inputjax>
+    The MathJax.OutputJax class <outputjax>
+    The MathJax.ElementJax class <elementjax>
+    The base Jax class <jax>
+.. toctree::
+    :maxdepth: 1
+    The MathJax Object-Oriented Programming Model <object>

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

@@ -0,0 +1,86 @@
+.. _api-input-jax:
+**************************
+The MathJax.InputJax Class
+**************************
+Input jax are the components of MathJax that translate
+mathematics from its original format (like :term:`TeX` or
+:term:`MathML`) to the MathJax internal format (an `element jax`).
+An input jax is stored as a pair of files in a subdirectory of the
+``jax/input`` directory, with the subdirectory name being the name of
+the input jax.  For example, the TeX input jax is stored in
+`jax/input/TeX`.  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.InputJax` object for the new input jax and registers that
+with MathJax, along with the MIME-type that will be used to indicate
+the mathematics that is to be processed by the input jax.
+The main body of the input jax is stored in the second file,
+``jax.js``, which is loaded when the input jax is first called on to
+translate some mathematics.  This file augments the original input jax
+subclass with the additional methods needed to do the translation.
+MathJax calls the input jax's :meth:`Translate()` method when it needs
+the input jax to translate the contents of a math ``<script>`` tag.
+The `MathJax.InputJax` 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/input/TeX"``);
+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.
+    The translation process should include the creation of an
+    :ref:`Element Jax <api-element-jax>` that stores the data needed
+    for this element.
+    :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 associated with this input jax so
+    that MathJax knows to call this input jax when it sees a
+    ``<script>`` of that type.  An input jax can register more than
+    one type, but it will be responsible for distinguishing elements
+    of the various types from one another.
+    :Parameters:
+        - **mimetype** --- the MIME-type of the input this jax processes
+    :Returns: ``null``

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

@@ -0,0 +1,148 @@
+.. _api-jax:
+******************
+The Base Jax Class
+******************
+The `MathJax.InputJax`, `MathJax.OutputJax` and `MathJax.ElementJax`
+classes are all subclasses of the base `Jax` class in MathJax.  This
+is a private class that implements the methods common to all three
+other jax classes.
+Unlike most MathJax.Object classes, calling the class object creates a
+*subclass* of the class, rather than an instance of the class.  E.g.,
+.. code-block:: javascript
+    MathJax.InputJax.MyInputJax = MathJax.InputJax({
+      name: "MyInputJax",
+      version: "1.0",
+      ...
+    });
+creates ``MathJax.InputJax.MyInputJax`` as a subclass of ``MathJax.InputJax``.
+Class Properties
+================
+.. describe:: directory
+    The name of the jax directory (usually ``"[MathJax]/jax").
+    Overridden in the subclass to be the specific directory for the
+    class, e.g. ``"[MathJax]/jax/input"``.
+.. describe:: extensionDir
+    The name of the extensions directory (usually ``"[MathJax]/extensions"``).
+Instance Properties
+===================
+.. describe:: name
+    The name of the jax.
+.. describe:: version
+    The version number of the jax.
+.. describe:: directory
+    The directory for the jax (e.g., ``"[MathJax]/jax/input/TeX"``).
+.. describe:: require: null
+    An array of files to load before the ``jax.js`` file calls the
+    :meth:`MathJax.Ajax.loadComplete()` method.
+.. describe:: config: {}
+    An object that contains the default configuration options for the
+    jax.  These can be modified by the author by including a
+    configuration subsection for the specific jax in question.
+Methods
+=======
+.. Method:: Translate(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.
+    :Parameters:
+        - **script** --- reference to the DOM ``<script>`` object for
+                         the mathematics to be translated
+    :Returns: an `ElementJax` object, or ``null``
+.. Method:: noTranslate(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.
+    :Parameters:
+        - **script** --- reference to the DOM ``<script>`` object for
+                         the mathematics to be translated
+    :Returns: ``null``
+.. Method:: Register(mimetype)
+    This method is overridden in the `InputJax`, `OutputJax` and
+    `ElementJax` subclasses to handle the registration of those
+    classes of jax.
+    :Parameters:
+        - **mimetype** --- the MIME-type to be associated with the jax
+    :Returns: ``null``
+.. Method:: Config()
+    :noindex:
+    Inserts the configuration block for this jax from the author's
+    configuration specification into the jax's ``config`` property.
+    If the configuration includes an ``Augment`` object, that is used
+    to augment the jax (that is, the configuration can override the
+    methods of the object, as well as the data).  This is called
+    automatically during the loading of the ``jax.js`` file.
+.. Method:: Startup()
+    This is a method that can be overridden in the subclasses to
+    perform initialization at startup time (after the configuration
+    has occurred).
+.. Method:: loadComplete (file)
+    :noindex:
+    This is called by the ``config.js`` and ``jax.js`` files when they
+    are completely loaded and are ready to signal that fact to
+    MathJax.  For ``config.js``, this simply calls the
+    :meth:`MathJax.Ajax.loadComplete()` method for the ``config.js``
+    file.  For ``jax.js``, the actions performed here are the
+    following:
+       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).
+       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.

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

@@ -0,0 +1,86 @@
+.. _api-message:
+**************************
+The MathJax.Message Object
+**************************
+The ``MathJax.Message`` object contains the methods used to manage the
+small message area that appears at the lower-left corner of the
+window.  MathJax uses this area to inform the user of time-consuming
+actions, like loading files and fonts, or how far along in the
+typesetting process it is.
+The page author can customize the look of the message window by
+setting styles for the ``#MathJax_Message`` selector (which can be
+set via
+.. code-block:: javascript
+    MathJax.Hub.Config({
+      styles: {
+        "#MathJax_Message": {
+	  ...
+	}
+      }
+    });
+Because of a bug in Internet Explorer, in order to change the side of
+the screen where the the message occurs, you must also set the side
+for ``#MathJax_MSIE_Frame``, as in
+.. code-block:: javascript
+    MathJax.Hub.Config({
+      styles: {
+        "#MathJax_Message": {left: "", right: 0},
+	"#MathJax_MSIE_Frame": {left: "", right: 0}
+      }
+    });
+It is possible that a message is already being displayed when another
+message needs to be posted.  For this reason, when a message is
+displayed on screen, it gets an id number that is used when you want
+to remove or change that message.  That way, when a message is
+removed, the previous message (if any) can be redisplayed if it hasn't
+been removed.  This allows for intermittent messages (like file
+loading messages) to obscure longer-term message (like "Processing
+Math" messages) temporarily.
+Methods
+=======
+.. method:: Set(message,[n,[delay]])
+    This sets the message being displayed to the given `message`
+    string.  If `n` is not ``null``, it represents a message id
+    number and the text is set for that message id, otherwise a new id
+    number is created for this message.  If `delay` is provided, it is
+    the time (in milliseconds) to display the message before it is
+    cleared.  If `delay` is not provided, the message will not be
+    removed automatically; you must call the
+    :meth:`MathJax.Messsage.Clear()` method by hand to remove it.
+    :Parameters:
+        - **message** --- the text to display in the message area
+        - **n** --- the message id number
+        - **delay** --- amout of time to display the message
+    :Returns: the message id nuber for this message.
+.. method:: Clear(n[,delay])
+    This causes the message with id `n` to be removed after the given
+    `delay`, in milliseconds.  The default delay is 600 milliseconds.
+    :Parameters:
+        - **n** --- the message id number
+        - **delay** --- the delay before removing the message
+    :Returns: ``null``
+.. method:: Log()
+    Returns a string of all the messages issued so far, separated by
+    newlines.  This is used in debugging MathJax operations.
+    :Returns: string of all messages so far

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

@@ -0,0 +1,210 @@
+.. _api-object:
+*********************************************
+The MathJax Object-Oriented Programming Model
+*********************************************
+MathJax uses an object-oriented programming model for its main
+components, such as the `Input jax`, `Output jax`, and `Element jax`.
+The model is intended to be light-weight and is based on JavaScript's
+prototype inheritance mechanism.  Object classes are created by making
+subclasses of `MathJax.Object` or one of its subclasses, and are
+instantiated by calling the object class as you would a function.
+For example:
+.. code-block:: javascript
+      MathJax.Object.Foo = MathJax.Object.Subclass({
+        Init: function (x) {this.SetX(x)},
+        getX: function () {return this.x},
+        setX: function (x) {this.x = x}
+      });
+      var foo = MathJax.Object.Foo("bar");
+      foo.getX();                // returns "bar"
+      foo.setX("foobar");
+      foo.getX();                // returns "foobar"
+Object classes can have static properties and methods, which are
+accessed via the object class variable. E.g.,
+``MathJax.Object.Foo.SUPER`` or ``MathJax.Object.Foo.Augment()`` for
+the object in the example above.  Static values are not inherited by
+subclasses.
+Static Properties
+=================
+.. describe:: SUPER
+   Pointer to the super class for this subclass.  (It is a reference to
+   `MathJax.Object` in the example above.)
+Static Methods
+==============
+.. method:: Subclass(def[,static])
+    Creates a subclass of the given class using the contents of the
+    `def` object to define new methods and properties of the object
+    class, and the contents of the optional `static` object to define
+    new static methods and properties.
+    :Parameters:
+        - **def** --- object that defines the properties and methods
+	- **static** --- object that defines static properties and methods
+    :Returns: the new object class
+.. method:: Augment(def[,static])
+    Adds new properties and methods to the class prototype.  All
+    instances of the object already in existence will receive the new
+    properties and methods automatically.
+    :Parameters:
+        - **def** --- object that defines the properties and methods
+	- **static** --- object that defines static properties and methods
+    :Returns: the object class itself
+Properties
+==========
+.. describe:: constructor
+    Pointer to the constructor function for this class. E.g.,
+    ``foo.constructor`` would be a reference to ``MathJax.Object.Foo``
+    in the example above.
+Methods
+=======
+.. method:: Init([data])
+    An optional function that is called when an instance of the class
+    is created.  When called, the `this` variable is set to the newly
+    instantiated object, and the `data` is whatever was passed to the
+    object constructor.  For instance, in the example above, the
+    variable ``foo`` is created by calling
+    ``MathJax.Object.Foo("bar")``, which calls the
+    ``MathJax.Object.Foo`` object's :meth:`Init()` method with `data`
+    equal to ``"bar"``.  If desired, the :meth:`Init()` method can
+    create a *different* object, and return that, in which case this
+    becomes the return value for the object constructor.
+    :Parameters:
+        - **data** --- the data from the constructor call
+    :Returns: ``null`` or the object to be returned by the constructor
+.. method:: isa(class)
+    Returns ``true`` if the object is an instance of the given class,
+    or of a subclass of the given class, and ``false`` otherwise.  So
+    using the ``foo`` value defined above,
+    .. code-block:: javascript
+      foo.isa(MathJax.Object);      // returns true
+      foo.isa(MathJax.Object.Foo);  // returns true
+      foo.isa(MathJax.InputJax);    // returns false
+.. method:: can(method)
+    Checks if the object has the given `method` and returns ``true``
+    if so, otherwise returns ``false``.  This allows you to test if an
+    object has a particular function available before trying to call
+    it (i.e., if an object implements a particular feature).  For example:
+    .. code-block:: javascript
+        foo.can("getX");  // returns true
+	foo.can("bar");   // returns false
+.. method:: has(property)
+    Checks if the object has the given `property` and returns ``true``
+    if so, otherwise returns ``false``.  This allows you to test if an
+    object has a particular property available before trying to use
+    it.  For example:
+    .. code-block:: javascript
+        foo.has("getX");  // returns true
+  	foo.has("x");     // returns true
+  	foo.has("bar");   // returns false
+Accessing the Super Class
+=========================
+If a subclass overrides a method of its parent class, it may want to
+call the original function as part of its replacement method.  The
+semantics for this are a bit awkward, but work efficiently.  Within a
+method, the value ``arguments.callee.SUPER`` refers to the super
+class, so you can access any method of the superclass using that.  In
+order to have `this` refer to the current object when you call the
+super class, however, you need to use ``call()`` or
+``apply()`` to access the given method.
+For example, ``arguments.callee.SUPER.method.call(this,data)`` would
+call the superclass' `method` and pass it `data` as its argument,
+properly passing the current object as `this`.  Alternatively, you can
+use ``this.SUPER(arguments)`` in place of ``arguments.callee.SUPER``.
+It is also possible to refer to the super class explicitly rather than
+through ``arguments.callee.SUPER``, as in the following example:
+.. code-block:: javascript
+      MathJax.Class1 = MathJax.Object.Subclass({
+	Init: function(x) {this.x = x},
+	XandY: function(y) {return "Class1: x and y = " + this.x + " and " + y}
+      });
+      MathJax.Class2 = MathJax.Class1.Subclass({
+	XandY: function (y) {return "Class2: "+arguments.callee.SUPER.XandY.call(this,y)}
+      });
+      MathJax.Class3 = MathJax.Class2.Subclass({
+	XandY: function (y) {return "Class3: "+MathJax.Class2.prototype.XandY.call(this,y)}
+      });
+      MathJax.Class4 = MathJax.Class1.Subclass({
+	XandY: function (y) {return "Class4: "+this.SUPER(arguments).XandY.call(this,y)}
+      });
+      var foo = MathJax.Class2("foo");
+      foo.XandY("bar");   // returns "Class2: Class1: x and y = foo and bar"
+      var bar = MathJax.Class3("bar");
+      bar.XandY("foo");   // returns "Class3: Class2: Class1: x and y = bar and foo"
+      var moo = MathJax.Class4("moo");
+      moo.XandY("cow");   // returns "Class4: Class1: x and y = moo and cow"
+Since both of these mechanisms are rather awkward, MathJax provides an
+alternative syntax that is easier on the programmer, but at the cost
+of some inefficiency in creating the subclass and in calling methods
+that access the super class.
+Since most calls to the super class are to the overridden method, not
+to some other method, the method name and the ``call()`` are
+essentially redundant.  You can get a more convenient syntax by
+wrapping the `def` for the :meth:`Subclass()` call in a call to
+``MathJax.Object.SimpleSUPER()``, as in the following example:
+.. code-block:: javascript
+      MathJax.Class1 = MathJax.Object.Subclass({
+	Init: function (x) {this.x = x},
+	XandY: function (y) {return "Class1: x and y = " + this.x + " and " + y}
+      });
+      MathJax.Class2 = MathJax.Class1.Subclass(
+	MathJax.Object.SimpleSUPER({
+	  XandY: function (y) {return "Class2: "+this.SUPER(y)},
+	  AnotherMethod: function () {return this.x}              // it's OK if a method doesn't use SUPER
+	})
+      );
+      var foo = MathJax.Class2("foo");
+      foo.XandY("bar");     // returns "Class2: Class1: x and y = foo and bar"