Skip to content

Commit 4332291

Browse files
committed
Continues updating documentation, in particular the Advanced Topics and API documents. Added a number of new example files.
1 parent 77e84ff commit 4332291

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+2312
-577
lines changed

docs/html/_sources/api/callback.txt

Lines changed: 63 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ A callback specification is any one of the following:
5858
the given function, and it would return their sum, ``5``, when
5959
the callback is executed.
6060

61-
.. describe:: [object, fn]
61+
.. describe:: [object, fn]
6262

6363
An array containing an object to use as `this` and a function to
6464
call for the callback. For example,
@@ -75,7 +75,7 @@ A callback specification is any one of the following:
7575
Similar to the previous case, but with data that is passed to
7676
the function as well.
7777

78-
..describe:: ["method", object]
78+
.. describe:: ["method", object]
7979

8080
Here, `object` is an object that has a method called `method`, and
8181
the callback will execute that method (with the object as
@@ -220,6 +220,26 @@ MathJax.Callback Methods
220220
- **callback** --- the callback specification
221221
:Returns: the callback object
222222

223+
.. method:: Queue([callback,...])
224+
225+
Creates a `MathJax.CallBack.Queue` object and pushes the given
226+
callbacks into the queue. See :ref:`Using Queues <using-queues>`
227+
for more details about MathJax queues.
228+
229+
:Parameters:
230+
- **callback** --- one or more callback specifications
231+
:Returns: the `Queue` object
232+
233+
.. method:: Signal(name)
234+
235+
Looks for a named signal, creates it if it doesn't already exist,
236+
and returns the signal object. See
237+
:ref:`Using Signals <using-signals>` for more details.
238+
239+
:Parameters:
240+
- **name** --- name of the signal to get or create
241+
:Returns: the `Signal` object
242+
223243
.. method:: ExecuteHooks(hooks[, data[,reset]])
224244

225245
Calls each callback in the `hooks` array (or the single hook if it
@@ -231,29 +251,54 @@ MathJax.Callback Methods
231251
execute when all the ones returned by the hooks have been
232252
completed. Otherwise, :meth:`MathJax.Callback.ExecuteHooks()`
233253
returns ``null``.
234-
254+
235255
:Parameters:
236256
- **hooks** --- array of hooks to be called, or a hook
237257
- **data** --- array of arguments to pass to each hook in turn
238258
- **reset** --- ``true`` if the :meth:`reset()` method should be called
239259
:Returns: callback that waits for all the hooks to complete, or ``null``
240260

241-
.. method:: Queue([callback,...])
261+
.. method:: Hooks(reset)
242262

243-
Creates a `MathJax.CallBack.Queue` object and pushes the given
244-
callbacks into the queue. See :ref:`Using Queues <using-queues>`
245-
for more details about MathJax queues.
263+
Creates a prioritized list of hooks that are called in order based
264+
on their priority (low priority numbers are handled first). This
265+
is meant to replace :meth:`MathJax.Callback.ExecuteHooks()` and is
266+
used internally for signal callbacks, pre- and post-filters, and
267+
other lists of callbacks.
246268

247269
:Parameters:
248-
- **callback** --- one or more callback specifications
249-
:Returns: the `Queue` object
270+
- **reset** --- ``true`` if callbacks can be called more than once
271+
:Returns: the `Hooks` object
250272

251-
.. method:: Signal(name)
252-
253-
Looks for a named signal, creates it if it doesn't already exist,
254-
and returns the signal object. See
255-
:ref:`Using Signals <using-signals>` for more details.
256-
257-
:Parameters:
258-
- **name** --- name of the signal to get or create
259-
:Returns: the `Signal` object
273+
The list has the following methods:
274+
275+
.. method:: Add(hook[,priority])
276+
277+
Add a callback to the prioritized list. If ``priority`` is
278+
not provided, the default is 10. The ``hook`` is a `Callback`
279+
specification as described above.
280+
281+
:Parameters:
282+
- **hook** --- callback specification to add to the list
283+
- **priority** --- priority of the hook in the list (default: 10)
284+
:Returns: the callback object being added
285+
286+
.. method:: Remove(hook)
287+
:noindex:
288+
289+
Remove a given hook (as returned from :meth:`Add()` above)
290+
from the prioritized list.
291+
292+
:Parameters:
293+
- **hook** --- the callback to be removed
294+
:Returns: ``null``
295+
296+
.. method:: Execute()
297+
298+
Execute the list of callbacks, resetting them if requested.
299+
If any of the hooks return callbacks, then ``Execute()``
300+
returns a callback that will be executed when they all have
301+
completed.
302+
303+
:Returns: a callback object or ``null``
304+

docs/html/_sources/api/elementjax.txt

Lines changed: 28 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -42,13 +42,11 @@ Instance Properties
4242

4343
.. describe:: inputJax
4444

45-
A reference to the input jax that created the element. (In the
46-
future, this will be changed to the name of the input jax.)
45+
The name of the input jax that created the element.
4746

4847
.. describe:: outputJax
4948

50-
A reference to the output jax that has processed this element. (In
51-
the future, this will be changed to the name of the output jax.)
49+
The name of the output jax that has processed this element.
5250

5351
.. describe:: inputID
5452

@@ -89,13 +87,25 @@ Methods
8987
- **callback** --- the callback specification
9088
:Returns: the callback object
9189

90+
.. Method:: Rerender([callback])
91+
:noindex:
92+
93+
Removes the output and produces it again (for example, if CSS has
94+
changed that would alter the spacing of the mathematics). Note
95+
that the internal representation isn't regenerated; only the
96+
output is. The `callback`, if any, is called when the process
97+
completes.
98+
99+
:Parameters:
100+
- **callback** --- the callback specification
101+
:Returns: the callback object
102+
92103
.. Method:: Reprocess([callback])
93104
:noindex:
94105

95-
Removes the output and produces it again. This may be necessary if
96-
there are changes to the CSS styles that would affect the layout
97-
of the mathematics, for example. The `callback`, if any, is
98-
called when the process completes.
106+
Removes the output and then retranslates the input into the
107+
internal form and reredners the output again. The `callback`, if
108+
any, is called when the process completes.
99109

100110
:Parameters:
101111
- **callback** --- the callback specification
@@ -118,6 +128,16 @@ Methods
118128

119129
:Returns: the ``<script>`` element
120130

131+
.. Method:: needsUpdate()
132+
133+
Indicates whether the mathematics has changed so that its output
134+
needs to be updated.
135+
136+
:Returns: ``true`` if the mathematics needs to be reprocessed,
137+
``false`` otherwise
138+
139+
140+
121141
Output jax may add new methods to the base element jax class to
122142
perform exporting to other formats. For example, a MathML output jax
123143
could add ``toMathML()``, or an accessibility output jax could add

docs/html/_sources/api/html.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,15 @@ Methods
9292
- **text** --- the text that is to be the script's new content
9393
:Returns: ``null``
9494

95+
.. method:: getScript(script)
96+
97+
Gets the contents of the ``script`` element, properly taking into
98+
account the browser limitations and bugs.
99+
100+
:Parameters:
101+
- **script** --- the script whose content is to be retrieved
102+
:Returns: the text of the ``script``
103+
95104
.. describe:: Cookie.Set(name,data)
96105

97106
Creates a MathJax cookie using the ``MathJax.HTML.Cookie.prefix``

docs/html/_sources/api/hub.txt

Lines changed: 68 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,17 @@ Properties
3131
.. describe:: processUpdateTime: 250
3232

3333
The minimum time (in milliseconds) between updates of the
34-
"Processing Math" message.
34+
"Processing Math" message. After this amount of time has passed,
35+
and after the next equation has finished being processed,
36+
MathJax will stop processing momentarily so that the update
37+
message can be displayed, and so that the browser can handle user
38+
interaction.
39+
40+
.. describe:: processUpdateDelay: 10
41+
42+
The amount of time (in milliseconds) that MathJax pauses after
43+
issuing its processing message before starting the processing again
44+
(to give browsers time to handle user interaction).
3545

3646
.. describe:: signal
3747

@@ -60,6 +70,11 @@ Properties
6070
running on a Macintosh computer or a Windows computer. They
6171
will both be ``false`` for a Linux computer.
6272

73+
.. describe:: isMobile
74+
75+
This is ``true`` when MathJax is running a mobile version of a
76+
WebKit or Gecko-based browser.
77+
6378
.. describe:: isFirefox, isSafari, isChrome, isOpera, isMSIE, isKonqueror
6479

6580
These are ``true`` when the browser is the indicated one, and
@@ -97,6 +112,18 @@ Properties
97112
}
98113
);
99114

115+
.. describe:: inputJax
116+
117+
An object storing the MIME types associated with the various
118+
registered input jax (these are the types of the ``<script>`` tags
119+
that store the math to be processed by each input jax).
120+
121+
.. describe:: outputJax
122+
123+
An object storing the output jax associate with the various
124+
element jax MIME types for the registered output jax.
125+
126+
100127
Methods
101128
=======
102129

@@ -243,13 +270,31 @@ Methods
243270

244271
.. method:: Reprocess([element[,callback]])
245272

246-
Removes any typeset mathematics from the document or DOM element (or
247-
elements if it is an array of elements), and then processes the
248-
mathematics again, re-typesetting everything. This may be necessary,
249-
for example, if the CSS styles have changed and those changes would
250-
affect the mathematics. The `element` is either the DOM `id` of the
251-
element to scan, a reference to the DOM element itself, or an array of
252-
id's or references. The `callback` is called when the processing is
273+
Removes any typeset mathematics from the document or DOM element
274+
(or elements if it is an array of elements), and then processes
275+
the mathematics again, re-typesetting everything. This may be
276+
necessary, for example, if the CSS styles have changed and those
277+
changes would affect the mathematics. Reprocess calls both the
278+
input and output jax to completely rebuild the data for
279+
mathematics. The `element` is either the DOM `id` of the element
280+
to scan, a reference to the DOM element itself, or an array of
281+
id's or references. The `callback` is called when the processing
282+
is complete.
283+
284+
:Parameters:
285+
- **element** --- the element(s) to be reprocessed
286+
- **callback** --- the callback specification
287+
:Returns: the callback object
288+
289+
.. method:: Rerender([element[,callback]])
290+
291+
Removes any typeset mathematics from the document or DOM element
292+
(or elements if it is an array of elements), and then renders the
293+
mathematics again, re-typesetting everything from the current
294+
internal version (without calling the input jax again). The
295+
`element` is either the DOM `id` of the element to scan, a
296+
reference to the DOM element itself, or an array of id's or
297+
references. The `callback` is called when the processing is
253298
complete.
254299

255300
:Parameters:
@@ -315,6 +360,21 @@ Methods
315360
- **element** --- the element to inspect
316361
:Returns: integer (-1, 0, 1)
317362

363+
.. Method:: setRenderer(renderer[,type])
364+
365+
Sets the output jax for the given element jax ``type`` (or ``jax/mml``
366+
if none is specified) to be the one given by ``renderer``, which
367+
must be the name of a renderer, such as ``NativeMML`` or
368+
``HTML-CSS``. Note that this does not cause the math on the page
369+
to be rerendered; it just sets the renderer for output in the
370+
future (call :meth:``Rerender()`` above to replace the current
371+
renderings by new ones).
372+
373+
:Parameters:
374+
- **renderer** --- the name of the output jax to use for rendering
375+
- **type** --- the element jax MIME type whose renderer to set
376+
:Returns: ``null``
377+
318378
.. Method:: Insert(dst,src)
319379

320380
Inserts data from the `src` object into the `dst` object. The

docs/html/_sources/api/inputjax.txt

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,40 @@ Properties
5656
Methods
5757
=======
5858

59-
.. Method:: Translate(script)
59+
.. Method:: Process(script,state)
60+
:noindex:
61+
62+
This is the method that the ``MathJax.Hub`` calls when it needs
63+
the input jax to process the given math ``<script>``. Its default
64+
action is to do the following:
65+
66+
1. Start loading any element jax specified in the ``elementJax`` array;
67+
2. Start loading the jax's ``jax.js`` file;
68+
3. Start loading the required output jax (so it is ready when needed); and
69+
4. Redefine itself to simply return the callback for the load operation
70+
(so that further calls to it will cause the processing to wait for the
71+
callback).
72+
73+
Once the ``jax.js`` file has loaded, this method is replaced by
74+
the jax's ``Translate()`` method (see below), so that
75+
subsequent calls to ``Process()`` will perform the appropriate
76+
translation.
77+
78+
:Parameters:
79+
- **script** --- reference to the DOM ``<script>`` object for
80+
the mathematics to be translated
81+
- **state** --- a structure containing information about the
82+
current proccessing state of the mathematics
83+
(internal use)
84+
:Returns: an `ElementJax` object, or ``null``
85+
86+
.. Method:: Translate(script,state)
6087
:noindex:
6188

6289
This is the main routine called by MathJax when a ``<script>`` of the
6390
appropriate type is found. The default :meth:`Translate()` method
6491
throws an error indicating that :meth:`Translate()` hasn't been
65-
redefined, so when the ``jax.js`` file loads, it should override the
92+
defined, so when the ``jax.js`` file loads, it should override the
6693
default :meth:`Translate()` with its own version that does the actual
6794
translation.
6895

@@ -72,6 +99,9 @@ Methods
7299

73100
:Parameters:
74101
- **script** --- the ``<script>`` element to be translated
102+
- **state** --- a structure containing information about the
103+
current proccessing state of the mathematics
104+
(internal use)
75105
:Returns: the `element jax` resulting from the translation
76106

77107
.. Method:: Register(mimetype)
@@ -87,3 +117,14 @@ Methods
87117
- **mimetype** --- the MIME-type of the input this jax processes
88118
:Returns: ``null``
89119

120+
.. Method:: needsUpdate(jax)
121+
:noindex:
122+
123+
This implements the element jax's ``needsUpdate()`` method, and
124+
returns ``true`` if the ``jax`` needs to be rerendered (i.e., the
125+
text has changed), and ``false`` otherwise.
126+
127+
:Perameters:
128+
- **jax** --- the element jax to be checked
129+
:Returns: ``true`` if the jax's text has changed, ``false`` otherwise
130+

0 commit comments

Comments
 (0)