Read Me

LatexRender-ng Project
----------------------

INTRODUTION

LatexRender-ng is the new generation of the popular LatexRender, a filter that will render images for LaTeX fragments aimed for use on the Web. LatexRender-ng introduces many improvements over its predecessor, including:

- Correct alignment of the images with respect to the base line of text.
- Cache abstraction allows the images to be cached on the server in a variety of ways, by means of cache managers. The present distribution includes a disk cache manager and a mysql cache manager.
- Local preamble allows for packages to be included and used throughout by the fragments on a page, facilitating authoring. If security is an issue, this feature can be restricted or disables all together.
- The possibility to render formulas in svg vector graphics on supported browsers with graceful fall back to raster graphics on browsers which do not support svg natively. The supported graphics formats are png, gif and svg. The svg can be embedded in the xhtml code for greater performance, and allows for the page to be stored and viewed in offline mode.
- New and more efficient tools like dvipng and dvisvgm are used to convert dvi directly to image, proviging a great speedup on the initial rendering process. Rendered formulas are kept on a cache to avoid unecessary processing.
- Just like on LatexRender, formulas fragments are enclosed by the [tex] and [/tex] tags. For instance, one could write [tex]ax^2+bx+c=0[/tex] and this quadratic equation would be renderd and displayed beautifully.
- LatexRender adds the possibility of passing parameters in the [tex] tag. For instance [tex cache="true"] prevents the image from being cache, [tex class="formula"] assigns the CSS class "formula" to the rendered object, etc, allowing for better integration of the rendered object with the html/xhtml code.

INSTALLATION

Prerequistes

LatexRender-ng requires the following packes/programs to work:

1. A fully configured and working LaTeX installation, including the preview package (preview.sty must be present on your system).

2. The dvipng package must be installed. Depending on your distro this should be as easy as issuing a command on the command-line, say somehting like sudo apt-get install dvipng, on ubuntu and debian, or yum -y install dvipng, on fedora core or redhat linux.

3. If you  are planning to use svg rendering, you will additionally require the dvisvgm package with, at the time of this writting, is not part of any repositories. The sourcecode must be downloaded from its website and compiled on the local machine.

The latest version of dvisvgm (0.8 at this time) can be downloaed from dvisvgm.sourceforge.net. To compile it on ubuntu, you must first do the following:

apt-get install build-essential freetype1-dev libkpathsea-dev

Then uncompress the dvisvgm source distribution on a local folder, cd into that folder and type:

./configure --prefix=/usr
make
sudo make install

LatexRender-ng Installation

Simply unpack the package on a folder that is accessible to the web-server and change the permission of the ./tmp folder allowing to the server the write access. If you are using disk caching, do the same with the ./picture folder. This folder will contain the cached images and other information relevant to LatexRender-ng.

Next, open class.latexrender.php and review the values of the variables on the top of that file to better reflect your installation and intended use. It is likely that it will work without changes, but it is possible that you will have to tweak a few of them. For instance if your text size is 10pt you might want to change _default_font_size to 10.

The file latex.php is a filter prototype. You give it a html page containing [tex]...[/tex] constructs and it will replace those with html code for images. Individual pages can be filtered this way, but it is likely that you otherwise wish to integrate the filter in a CMS (Content Management System). Use latexrender.php as a prototype to writing a filter for your CMS. Below we provide filters for Moodle and Joomla.

INSTALLATION ON MOODLE

Two files are relevant on moodle: filter.php and pix.php. Both files require you to adjust the paths and choose the appropriated cache mechanism to be used, and filter.php is the actual moodle content filter. Its installation is standard.

On the other hand, pix is responsible for fetching the image, adjusting the http headers and sending each image to the user. Howerver, its use is optional and can be replaced by direct access to the folder where the image is stored, if disk caching is used.

SUPPORTED OPTIONS
In the middle of a [tex]...[/tex] construct, only valid LaTeX code is allowed. However, there are a few options that can be used with the [tex] tag. These are:

- class="..." 	- defile the CSS class of the image object.
			example: [tex class="centered-formula"]
- style="..." 	- append the given styles to the CSS styles of the object.
			example: [tex style="border: 1px solid; padding: 5px;"] 
- nocache="true" - prevents the image from being permanently store in the cache
			example: [tex nocache="true"]...
- fontsize="..." - overrides the default font size in pts, example
			[tex fontsize="10"]...
		   Note: the css text-size: declaration is ignored: use fontsize

Multiple options can be specified, for example:
		[tex class="big-formula" style="padding: 5px;"]...


PREAMBLE

If enabled, the user can specify a local preamble, valid only in the scope of
the document being shown. For that one can use the tags [preamb]...[/preamb].
All text enclosed between these tags is passed on literally to LaTeX and is appended to its preamble. As as result, all LaTeX fragments on the same document will share that preamble. This is useful for authoring for it allows for the use of special LaTeX packages or to the definition of shorthand expressions to be used elsewhere.

This feature is unsafe for it could be exploited for cross-site scripting purposes, so use it with care. We are working on a filter that will allow only certain non-harmful constructions to be present inm the preamble, but this will take some time.

Other than that, enjoy

Waldeck Schutzer
Sao Carlos, SP, Brazil
August 8, 2009