+[[!template id=plugin name=mscgen author="[[users/Tjgolubi]]"]]
[[!tag type/widget]]
-This plugin provides the mscgen [[ikiwiki/directive]].
+## NAME
+
+IkiWiki::Plugin::mscgen - embed message sequence chart
+
+## SYNOPSIS
+
+In the ikiwiki setup file, enable this plugin by adding it to the list of active plugins.
+
+ add_plugins:
+ - mscgen
+
+## DESCRIPTION
+
+This plugin provides the msc [[ikiwiki/directive]].
This directive allows embedding [mscgen](http://www.mcternan.me.uk/mscgen/)
-message sequence chart graphs in a page.
+message sequence chart graphs in an ikiwiki page.
-Here's an mscgen source example.
+Here's an example that shows how an mscgen message sequence chart is embedded into an ikiwiki page.
\[[!msc src="""
arcgradient = 8;
|||;
"""]]
-And here's the resulting graph.
+Security implications: to be determined.
-[[!msc src=<<"""
- arcgradient = 8;
+This plugin borrows heavily from the [[graphviz|plugins/graphviz]] plugin written by [[JoshTriplett]].
- a [label="Client"],b [label="Server"];
+## PREREQUISITES
+ IkiWiki
+ mscgen
+ Digest::SHA
- a=>b [label="data1"];
- a-xb [label="data2"];
- a=>b [label="data3"];
- a<=b [label="ack1, nack2"];
- a=>b [label="data2", arcskip="1"];
- |||;
- a<=b [label="ack3"];
- |||;
-"""]]
+## DOWNLOAD
-Security implications: to be determined.
+* browse at GitHub: <http://github.com/tjgolubi/ikiwiki.mscgen>
+* repo at git://github.com/tjgolubi/ikiwiki.mscgen.git
-This plugin uses the [[!cpan Digest::SHA]] perl module.
-
-This plugin borrows heavily from the [[graphviz|plugins/graphviz]] plugin written by [[JoshTriplett]].
-I couldn't upload an attachment, so here's the plugin source.
-
-[[!format perl """
-#!/usr/bin/perl
-# mscgen plugin for ikiwiki: render mscgen source as an image.
-# Terry Golubiewski
-# Derived from graphviz plugin by Josh Triplett.
-package IkiWiki::Plugin::mscgen;
-
-use warnings;
-use strict;
-use IkiWiki 3.00;
-use IPC::Open2;
-
-sub import {
- hook(type => "getsetup", id => "mscgen", call => \&getsetup);
- hook(type => "preprocess", id => "msc", call => \&graph);
-}
-
-sub getsetup () {
- return
- plugin => {
- safe => 1,
- rebuild => undef,
- section => "widget",
- },
-}
-
-sub render_graph (\%) {
- my %params = %{(shift)};
-
- my $src = "msc {\n";
- $src .= $params{src};
- $src .= "\n}\n";
-
- # Use the sha1 of the mscgen code as part of its filename.
- eval q{use Digest::SHA};
- error($@) if $@;
- my $dest=$params{page}."/msc-".
- IkiWiki::possibly_foolish_untaint(Digest::SHA::sha1_hex($src)).
- ".png";
- will_render($params{page}, $dest);
-
- if (! -e "$config{destdir}/$dest") {
- my $pid;
- my $sigpipe=0;
- $SIG{PIPE}=sub { $sigpipe=1 };
- $pid=open2(*IN, *OUT, 'mscgen', '-Tpng', '-i-', '-o-');
-
- # open2 doesn't respect "use open ':utf8'"
- binmode (OUT, ':utf8');
-
- print OUT $src;
- close OUT;
-
- my $png;
- {
- local $/ = undef;
- $png = <IN>;
- }
- close IN;
-
- waitpid $pid, 0;
- $SIG{PIPE}="DEFAULT";
- error gettext("failed to run mscgen") if $sigpipe;
-
- if (! $params{preview}) {
- writefile($dest, $config{destdir}, $png, 1);
- }
- else {
- # in preview mode, embed the image in a data uri
- # to avoid temp file clutter
- eval q{use MIME::Base64};
- error($@) if $@;
- return "<img src=\"data:image/png;base64,".
- encode_base64($png)."\" />";
- }
- }
-
- return "<img src=\"".urlto($dest, $params{destpage})."\" />\n";
-}
-
-sub graph (@) {
- my %params=@_;
- $params{src} = "" unless defined $params{src};
- return render_graph(%params);
-}
-
-1
-"""]]