vbLatex

Download vbLatex (449 downloads)

What is it?

vbLatex is a plugin for the popular vBulletin forum software, enabling users to render snippets of LaTeX code in their posts and private messages. It is based partly from Steve Mayer’s latexrender package, but has been adapted to use dvipng instead of the convert utility.

The original implementation was for the Science Forums Network, a forum of which I am now an administrator. I’d encourage you all to pay them a visit, as it’s a very nice community to be a part of! You can see some good examples of vbLatex in action in this thread.


Disclaimer

vbLatex should be considered beta at best, and as such is completely unsupported. I will try to respond to any e-mails I receive, but I have very little time on my hands these days to dedicate to improving it. As it works on SFN I generally don’t touch it that much.

There is a very real possibility that this may break your board, especially if not installed correctly. As such, I cannot be held responsible for any loss of data or inconvenience encountered during the operation of this plugin (even though it is extremely unlikely this could happen).

Features

vbLatex was originally conceived as a generalised tool for rending LaTeX images. It’s designed so that additional environments could easily be added, so that – for example – a pstricks environment could be added with the use of a [pst] tag. Currently implemented are:

  • Normal display math – i.e. the $$ … $$ environment (math tag)
  • Inline math – i.e. the $ … $ environment (imath tag).
  • Chemistry typesetting with mhchem (ce tag)
  • xyfig support (which is not enabled and is considered experimental – uses the fig tag).

An overview of the key features is listed below.

  • Supports rendering of both regular and inline LaTeX through the math and imath tags.
  • The ce tag can be used to render chemical equations with the mhchem package.
  • Both PNG and GIF output supported.
  • Reasonably easy configuration.
  • Hopefully small overhead – uses dvipng to process files quickly.

Great: what do I need?

  • A working distribution of LaTeX. This kind of goes without saying – if you’re using Linux, look into the TeXlive distribution.
  • You absolutely must have a copy of dvipng installed. This plugin will not work without it.
  • If you want GIF output, then dvipng must have GIF support compiled into it. Things may otherwise break. Versions supplied as a part of many distributions will have this support.
  • The mhchem package needs to be accessible by LaTeX; either put the mhchem.sty file in the tmp directory (see below) or install the package properly. It is not bundled with vbLatex by default (although this may change in the future).
  • Although the plugin should theoretically work with vBulletin 3.5, it is not tested nor supported with this version. As such, I highly recommended that you use vBulletin 3.6 or later.

I don’t have dvipng!

Then vbLatex won’t work. This is intentional: dvipng is much faster than the equivalent convert call, which invokes ghostscript and is very memory-intensive. You should talk to your friendly system-administrator as it only takes a few minutes to compile and install!

Installation

Please note: these are very vague instructions since I don’t have a lot of time to create good ones. If you run into problems, please e-mail me.

  1. Create a folder somewhere web-accessible to hold all of your generated images. You need to create two sub-directories called tmp and img inside this folder, and make them both world-writable.
  2. Extract the archived ZIP file somewhere. Carefully read through the configuration file and fill in all required sections. Make sure your paths are correct and agree with step 1.
  3. Upload the class.latex.php file to the includes directory of your vBulletin installation.
  4. Upload the latex.js file to the clientscript directory of your vBulletin includes, and modify your header template to include this JavaScript file. (This will be done automatically in the future at some point).
  5. Install the supplied .xml plugin file using the vBulletin admin control panel.
  6. Turn on LaTeX rendering in the vBulletin Options.
  7. You’re done!

Usage and Examples

The plugin is very easy to use; simply wrap any LaTeX strings with math, imath or ce tags as appropriate.

  • A simple integral:
  • The Fourier transform of :
  • The derviative of a function at a point :

Legal and Usage

As I am a big believer in open-source code, vbLatex is released under the LGPLv2 license, included in the file. You can use it under whatever conditions the license deems acceptable, but I would ask that you try to acknowledge me and/or link back to this page!

To-do

  • The JavaScript hack is a little buggy in terms of the post cache and this needs to be sorted out.
  • Implement the baseline hack for aligning inline images properly by Mike Doyle.
  • Use vBulletin admin control panel for setting options instead of manually editing the file.
  • Improve this documentation.
  • Better caching of images in sub-directories.
  • Create a cache cleanup script.
  • If you encounter bugs, then let me know!

Acknowledgements

I must thank Steve Mayer for his continued support and efforts with the inspiration for this project, latexrender. Also, the users of SFN for their patience with my constant tinkering; in particular, John for letting me test the project in the first place!