
KSS plugin package "kss.plugin.jsmath"

Installation and Setup
======================

Read INSTALL.txt

Documentation
=============

kss.plugin.jsmath enables the use of the
`jsMath library <http://www.math.union.edu/locate/jsMath>`_
with KSS.

jsMath has its own markers for marking the beginning and end of
the formulas in your text content. In addition, this component 
provides a KSS action, that needs to be executed on the nodes, 
within which you want the conversion to be enabled. This action
will activate the conversion on the selected areas only.

For example the following rule activates conversion inside all
nodes that are marked with the "mathcontent" CSS class::

    .mathcontent:load {
        action-client: jsmath-activate;
    }

You can use this, for example, to enable seamless conversion of
the view of any of your widgets. In Zope, you can activate
this for certain fields of certain or all content types, with 
a properly choosen selector.

Since the conversion only affects the view results, the mechanism
works all the same, independently if the field is edited as a
text area input, or with an editor (like kupu). In the editor,
you are able to edit the LaTeX markup directly.


Markup
------

jsMath offers more variants for marking your content, these are
controllable by parameters on the action. According to defaults,
putting the formula between the markers ``\(`` and ``\)`` works out 
of the box::

  \( \textstyle \sqrt{x+2}\quad \underline 4\quad \overline{x+y}\quad x^{\underline n}\quad x^{\overline{m+n}} \quad \sqrt{x^2+\sqrt{\alpha}} \)

The markers only become active in the areas that you select with
KSS.

Dynamic loading
---------------

jsMath has a mechanism for loading its large javascript
dynamically, on demand. The package uses this mechanism combined
with custom code that helps dynamic loading integrate with KSS.

The following javascript files::

    /++resource++jsmath/jsMath.js
    /++resource++jsmath/plugins/tex2math.js

will be loaded dynamically, if you selected any conversion with
KSS in your page. This will cause a little delay before the first
conversion takes place but makes sure that the large javascript
is only loaded when needed. The works seamlessly in practice,
because the loading and the conversion takes place asynchronously
and it does not block access to the page from the browser.

However, it is also possible to include these resources
statically in the page header, as well. In this case the
resources will be used at once and will not be loaded
dynamically. You may choose this method, if you find it increases
overall performance on your site.

Browser compatibility
---------------------

jsMath is famous for working on all browsers including all the
ones that are supported by KSS. However if you find that the
plugin fails in your browser, please report the bug so that we
can attempt to fix it.

Caveats
-------

Since the conversion happens on client side, you will not be able
to use the same mechanism to convert your pages to PDF, on the
server side.

