# Blosxom Plugin: maruku -*-cperl-*-
# Author(s): Jason Blevins <jrblevin@sdf.lonestar.org>
# Version: 2007-12-02
# Documentation is included below: type "perldoc maruku", or scroll down.

package maruku;

use File::Temp qw(tempfile);
use strict;

# ----- Configuration -----

my $maruku = "/usr/bin/maruku";

# ----- Optional Configuration -----

# Set this to 1 to enable LaTeX-style itex math expressions to be converted
# to MathML.  This requires the itex2MML ruby bindings to be installed.  If
# $use_meta is 0, all documents will be parsed using itex.  If $use_meta is
# 1, then only documents with meta-math: itex will be processed.
my $use_itex = 0;

# Set this to 1 to allow use of the meta plugin or 0 to automatically process
# all files.  If set to 1, only story files with "meta-markup: maruku" will
# be processed.  Furthermore, only files with "meta-math: itex" will be
# processed in math mode (only when $use_itex is nonzero).
my $use_meta = 0;

# Set this to add a directory to your RUBYLIB environment variable to help
# ruby locate maruku or itextomml.  If multiple directories are given,
# separate them with colons (:).
my $rubylib = '';

# ----- End configuration -----

sub start { 1; }

sub story {
    my($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;

    # If we are not using the meta plugin, or if we are using meta and
    # meta-markup is either 'maruku' or 'markdown', then process the body.
    if ((!$use_meta) or
	(defined($meta::markup) and ($meta::markup =~ /^\s*(maruku|markdown)\s*$/i))) {

	# Generate a temporary file for input to Maruku.
	my ($in, $infile) = tempfile(UNLINK => 0);

	# Write the body text to the 'input' (to Maruku) temp file.
	print $in $$body_ref;
	close $in or die "cannot close  $infile: $!";

	# Set the name of the output file.
	my $outfile = $infile . ".out";

	# By default, we only generate an HTML fragment, ignoring any math.
	my @args = ($maruku, "--html-frag");

	# Should we convert itex expressions to MathML?
	if (($use_itex) and
	    ((!$use_meta) or
	     (defined($meta::math) and ($meta::math =~ /^\s*itex\s*$/i)))) {
	    push @args, '-m', 'itex2mml';
	}

	# Add the output and input files to the argument list.
	push @args, "-o", $outfile, $infile;

	# Set the RUBYLIB environment variable if needed.
	$ENV{'RUBYLIB'} = $rubylib if ($rubylib);

	# Call maruku.
	system(@args) == 0 or die "system @args failed: $?";

	# Read the output.
	$$body_ref = '';
	open OUT, $outfile or die "can't open $outfile: $!";
	while (my $line = <OUT>) {
	    $$body_ref .= $line;
	}

	# Close the output file
	close OUT or die "cannot close  $outfile: $!";
    }
    1;
}

sub end { 1; }

__END__

=head1 NAME

Blosxom Plug-in: maruku

=head1 SYNOPSIS

Maruku is a Markdown superset interpreter.  It parses documents written in
Markdown and Markdown Extra but also supports extended metadata and embedded
mathematics.  This plugin also supports the use of itex2MML for converting
mathematics to MathML.

=head1 VERSION

2007-12-02

=head1 AUTHORS

Jason Blevins <jrblevin@sdf.lonestar.org>,

=head1 INSTALLATION AND CONFIGURATION

The maruku plugin requires the Maruku and itex2MML Ruby libraries and the
corresponding maruku binary.  You must set B<$maruku> to the full path of
maruku binary.  Additionally, if you installed the ruby libraries in a
non-standard location, you can set B<$rubylib> and the RUBYLIB environment
variable will be set before maruku is called.

You can obtain Maruku at http://maruku.rubyforge.org and itex2MML at
http://golem.ph.utexas.edu/~distler/blog/itex2MML.html.

If you want to enable MathML output via itex2MML, set B<$use_itex> to 1.  If
you only want Maruku and (optionally) itex to process certain entries, you
can install the meta plugin and set B<$use_meta> to 1.  Then, only documents
with "meta-markup: maruku" will be processed by Maruku and only those with
"meta-math: itex" will be processed using the itex2MML math engine.

=head1 SEE ALSO

Blosxom Home/Docs/Licensing:
http://blosxom.sourceforge.net

Blosxom Plugin Docs:
http://blosxom.sf.net/documentation/developers/plugins.html

Maruku:
http://maruku.rubyforge.org

itex2MML:
http://golem.ph.utexas.edu/~distler/blog/itex2MML.html

=head1 BUGS

Send bug reports and comments to Jason Blevins <jrblevin@sdf.lonestar.org>.

=head1 VERSION HISTORY

2007-12-02: Revised file IO for, hopefully, faster execution.x
2007-10-24: Initial revision.

=head1 LICENSE

Copyright (C) 2007 Jason Blevins

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.