h1. Syntax highlighting using pygments

This plugin adds syntax hightlighting to textpattern. You can embed code in
articles. The plugin is based on "Pygments":http://pygments.org/.

h2. Installation

# Add jea_pygments_txp plugin to textpattern
# Install python on your webserver
# Install pygments on your webserver

h3. Optional dependencies

* Support for customization:
    Install textpattern plugin "soo_plugin_pref":http://ipsedixit.net/txp/92/soo_plugin_pref

h3. Troubleshooting

If you run into troubles, simply ask! Here are some tips that might help:

* Verify that pygmentize is correctly installed and accessible from the server's shell
* Make sure '/usr/bin/pygmentize' is available. If you have a local python environment
  (e.g. _virtualenv_) you have to specify the script location manually in
  the plugin options tab in your admin area. You might have to hit save on the
  article where you use the highlighting tag in order to prevent textpattern from serving
  the cached version of your article output.
* When in doubt: do not waste time and ask. That might save you some time.
* Make sure that your Pygments installation supports the language of the file you
  want to highlight.

h2. Usage

For embedding highlighted code in a textpattern article, use the tag *<txp:jea_highlight />*.
It supports the following parameters:

* *file* - The name of an uploaded file in <textpattern>/files. Paths are
    not allowed. File names are restricted to alphanumerical characters,
    underscores, dots, and hyphens. Files must not begin with a dot.
* *linenos* - Enables line numbers if set to 'true'. Corresponds to Pygments'
    linenos=inline option.
* *from* - The first line to display. 
* *to* - The last line to display.
* *lang* - Specifies the language of the code to embed. If not given
    Pygments tries to guess the language by looking at the file name or even at
    the content (which might fail). Find out with 'pygmentize -L lexers' or go
    to plugin options to see what languages are available.

You can also embed and highlight code directly in articles. Therefore, simply wrap the code to highlight
like this:

pre. <txp:jea_highlight lang='python'><notextile>
def hypotenuse(a, b):
    return sqrt(a*a + b*b);

The 'notextile' tags ensure that textpattern will not process the tag content using
the textile markup generation engine. Be careful though, if you try to highlight
textile markup that contains 'notextile' tags itself! And do not include any whitespace
between the 'notextile' and the 'txp:jea_highlight' tags. If in doubt, highlight 
code using the 'file' attribute.

h3. Examples

pre. <txp:jea_highlight file='join.sql' />
<txp:jea_highlight file='oca.ml' linenos='true' />
<txp:jea_highlight file='NotTheIsland.java' linenos='false' />
<txp:jea_highlight file='ramide.py' from='3' to='14'/>

h3. Customization

The plugin can be customized in several ways. You can go to the plugin options
tab and change the default values for most of the parameters used by the
'txp:jea_highlight' tag.

* *Pygmentize script location* - Specify the location of your pygmentize script
    that is shipped with Pygments. Note that for security reasons the script's file
    name must be 'pygmentize'.

* *Line numbers* - See parameter 'linenos'.

* *Inline CSS* - This causes Pygments to create inline style information instead
    of class names. Use this if you do not plan to include an extra style sheet
    to format the highlighted code.

* *Highlighting style* - There are several predefined styles available. Find
   out with 'pygmentize -L styles' what styles are available, or look in the
   plugin options.

h2. Known issues

* styles should be listed in a drop-box on the preferences panel
* caching should make things go faster
* character encoding not thorougly tested