Redmine Wiki External Filter Plugin
                 ===================================
              Copyright (C) 2010 Alexander Tsvyashchenko,
              http://www.ndl.kiev.ua - see COPYRIGHT.txt

Overview
========

This plugin allows defining macros that process macro argument using
external filter program and render its result in Redmine wiki.

For every filter two macros are defined: <macro> and <macro>_include.
The first one directly processes its argument using filter, while the
second one assumes its argument is wiki page name, so it reads that wiki page
content and processes it using the filter.

Macros already bundled with current release are listed below, but adding new
ones is typically as easy as adding several lines in plugin config file.

Installation
============

See [Installing a plugin](http://www.redmine.org/wiki/redmine/Plugins) on
Redmine site.

Additionally, copy wiki_external_filter.yml from config folder of plugin
directory to the config folder of your redmine installation.

After installation it's **strongly recommended** to go to plugin settings and
configure caching. Note that RoR file-based caching suggested by default does
not implement proper cache expiration: you should either setup a cron task to
clean cache or do it manually from time to time.

To successfully use macros with complex argument expressions, it's necessary
to patch core Redmine components as follows:
 * [Change MACROS_RE](http://www.redmine.org/issues/3061) regexp not to stop
   too early - in the issue description textile wiki formatter is mentioned,
   but in fact this change should be done for whatever wiki formatter you use.
 * [Change arguments parsing](http://www.redmine.org/boards/3/topics/4987#message-9854) - again, should be done for whatever wiki formatter you use.
 * Additionally, for some of the formatters escaping should be avoided for
   macro arguments.

Specific filters installation instructions are below.

Prefedined Macros
=================

plantuml
--------

[PlantUML](http://plantuml.sourceforge.net/) is a tool to render UML diagrams
from their textual representation. It's assumed that it can be invoked via
wrapper /usr/bin/plantuml, here's its example content:

    #!/bin/bash
    /usr/bin/java -Djava.io.tmpdir=/var/tmp -jar /usr/share/plantuml/lib/plantuml.jar ${@}

Result is rendered as PNG file. SVG support seems to be under development for
PlantUML but so far looks like it's still unusable.

Example of usage:

    {{plantuml(
    Alice -> Bob: Authentication Request
    alt successful case
      Bob -> Alice: Authentication Accepted
    else some kind of failure
      Bob -> Alice: Authentication Failure
      opt
        loop 1000 times
          Alice -> Bob: DNS Attack
        end
      end
    else Another type of failure
      Bob -> Alice: Please repeat
    end
    )}}

graphviz
--------
[Graphviz](http://www.graphviz.org/) is a tool for graph-like structures
visualization. It's assumed that it can be called as /usr/bin/dot.

Result is rendered as SVG file.

Example of usage:

    {{graphviz(
    digraph finite_state_machine {
        rankdir=LR;
        size="8,5"
        node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
        node [shape = circle];
        LR_0 -> LR_2 [ label = "SS(B)" ];
        LR_0 -> LR_1 [ label = "SS(S)" ];
        LR_1 -> LR_3 [ label = "S($end)" ];
        LR_2 -> LR_6 [ label = "SS(b)" ];
        LR_2 -> LR_5 [ label = "SS(a)" ];
        LR_2 -> LR_4 [ label = "S(A)" ];
        LR_5 -> LR_7 [ label = "S(b)" ];
        LR_5 -> LR_5 [ label = "S(a)" ];
        LR_6 -> LR_6 [ label = "S(b)" ];
        LR_6 -> LR_5 [ label = "S(a)" ];
        LR_7 -> LR_8 [ label = "S(b)" ];
        LR_7 -> LR_5 [ label = "S(a)" ];
        LR_8 -> LR_6 [ label = "S(b)" ];
        LR_8 -> LR_5 [ label = "S(a)" ];
    }
    )}}

ritex
-----

Combination of [Ritex: a Ruby WebTeX to MathML converter](http://ritex.rubyforge.org/) and [SVGMath](http://www.grigoriev.ru/svgmath/) that takes WebTeX
formula specification as input and produces SVG file as output.

Both ritex and SVGMath require some patches/wrappers.

Additionally working installation of xmllint from libxml2 with configured
MathML catalog is required: for Gentoo use [this ebuild](http://bugs.gentoo.org/194501).

Example of usage:

    {{ritex(
    G(y) = \left\{\array{ 1 - e^{-\lambda x} & \text{ if } y \geq 0 \\ 0 & \text{ if } y < 0 }\right.
    )}}

fortune
-------

[Fortune](http://en.wikipedia.org/wiki/Fortune_(Unix)) is a simple program
that displays a random message from a database of quotations.

Not strictly a filter on its own (as it does not require any input), but it
plays nice with external filtering approach and is fun to use, hence it's here
;-)

Example of usage:

    {{fortune}}

Writing new macros
==================

New macros can easily be added via wiki_external_filter.yml config file.

Wiki external filter uses standard Unix approach for filtering: input is fed
to the command via stdin and output is read on stdout. If command return
status is zero, content type is assumed to be of content_type specified in
config, otherwise it's assumed it's plain error text.

You can use prolog/epilog config parameters to add standard text before/after
actual macro content passed to filter.

Additionally, cache_seconds parameter specifies the number of seconds command
output result should be cached, use zero to disable caching for this
particular command.

Macro argument is de-escaped via CGI.unescapeHTML call prior to being fed to
filter.

The way filter output is visualized is controlled via
app/views/wiki_external_filter/macro_*.html.erb files.

By default all 'image/*' content types are rendered as <img>, 'text/plain'
is included in resulting HTML page with escaping, all '*/*xml*'
and '*/*html*' content types are included directly into output page without
escaping, all other content types are embedded as <object>.

Current bugs/issues
===================

1. Redmine core requires patching to get things work. In fact, the whole
   wiki formatting design as of now seems to be quite messy.
2. FireFox has broken implementation of SVG rendering: <img> tag for SVG
   inclusion does not work: see the [related bug](https://bugzilla.mozilla.org/show_bug.cgi?id=276431) dated back to 2004 (sic!).
   WebKit browsers, on the other hand, are too fragile with <object> SVG
   embedding, having problems with resulting image size.
   Considering I do not use FireFox but use WebKit-based browsers - guess
   which route I've chosen ;-)
   If you insist on making it work for FireFox (and breaking things for
   WebKit-based browsers) - copy <object> embedding code in the views
   templates under the `when /image\/svg\+xml/ then` clause (put it before
   generic 'image' case).
   Alternatively, you can use some JavaScript-based trickery to use different
   embedding ways depending on browser version.
   Of course, IE does not support SVG at all, but who really uses it these
   days anyway? ;-)
3. For formula support, theoretically ritex alone is sufficient if you have
   MathML-capable browser, however in practice there are too many issues with
   this approach: for example Firefox (actually the onlt MathML-capable
   browser so far, it seems) requires specific DOCTYPE additions that Redmine
   currently lacks; additionally, Redmine emits text/html, while Firefox
   expects text/xml in order to parse MathML. Changing content type alone is
   not sufficient as Redmine HTML output does not pass more strict checks
   required for XML output. Hence, the double conversion (WebTeX to MathML
   and then MathML to SVG) is necessary. Once (if ever?) MathML support
   matures in other browser, possibly this can be revisited.
4. SVGs could have been embedded into HTML page directly (thus allowing to use
   redmine links there) but I'm afraid there are similar problems
   as with MathML embedding attempts.
5. RoR caching support is a mess: no way to expire old files from file-based
   cache??? Are you joking???

Additional info
===============

1. Somewhat similar plugins (although with narrower scope) are [graphviz plugin](http://github.com/tckz/redmine-wiki_graphviz_plugin) and [latex plugin](http://www.redmine.org/boards/3/topics/4987).
  Graphviz functionality is mostly covered by current version of
  wiki_external_filter. Latex is not, but only due to the fact I do not have
  latex installed nor currently have a need in that: adding macro that
  performs latex filtering should be trivial.