---+!! !MessageSequenceChartPlugin

<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/MessageSequenceChartPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MessageSequenceChartPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.

One line description, required for extensions repository catalog.
   * Set SHORTDESCRIPTION = Draw message sequence charts (MSCs) using the mscgen utility
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>

%SHORTDESCRIPTION%

---++ Introduction

A TWiki plugin for the [[http://www.mcternan.me.uk/mscgen/][mscgen]] utility. Parses message sequence chart (MSC) descriptions and produces PNG images as the output. MSCs are described using a simple markup language written between =%<nop>MSC%= and =%<nop>ENDMSC%= tags.

MSC is an interaction diagram from the SDL family very similar to UML's sequence diagram. MSCs are popular for describing communication behaviour in real-time systems, telecommunication, protocol software etc.

<sticky>
<table>
<tr>
<th>Input:</th>
<th>Output:</th>
</tr>
<tr>
<td>
<verbatim>
%MSC%
msc {
    width="300";

    a [label="Alice"],b [label="Bob"];

    a=>b [label="INVITE"];
    a<=b [label="180 Ringing"];
    a<=b [label="200 OK"];
    a=>b [label="ACK"];
}
%ENDMSC%
</verbatim>
</td>
<td>
<img src="%ATTACHURLPATH%/example2.png" alt="Example graph generated by <nop>MessageSequenceChartPlugin" title="Example graph generated by <nop>MessageSequenceChartPlugin" width="300" height="154" />
</td>
</tr>
</table>
</sticky>

---++ Syntax Rules

Enclose the description for your MSC within =%<nop>MSC%= and =%<nop>ENDMSC%= tags.

*mscgen language:*
   * [[http://www.mcternan.me.uk/mscgen/][Description of the language]]
   * [[http://www.mcternan.me.uk/mscgen/grammar.txt][Grammar of the language]]

---++ Examples

---+++ Fictional process

<sticky>
<table>
<tr>
<th>You type:</th>
<th>You get:</th>
</tr>
<tr>
<td>
<verbatim>
%MSC%
msc {
  a,b,c;

  a->b [ label = "ab()" ] ;
  b->c [ label = "bc(TRUE)"];
  c=>c [ label = "process(1)" ];
  c=>c [ label = "process(2)" ];
  ...;
  c=>c [ label = "process(n)" ];
  c=>c [ label = "process(END)" ];
  a<<=c [ label = "callback()"];
  ---  [ label = "If more to run", ID="*" ];
  a->a [ label = "next()"];
  a->c [ label = "ac1()\nac2()"];
  b<-c [ label = "cb(TRUE)"];
  b->b [ label = "stalled(...)"];
  a<-b [ label = "ab() = FALSE"];
}
%ENDMSC%
</verbatim>
</td>
<td>
<img src="%ATTACHURLPATH%/example0.png" alt="example0.png" width="600" height="448"  />
</td>
</tr>
</table>
</sticky>

---+++ Fictional client-server protocol

<sticky>
<table>
<tr>
<th>You type:</th>
<th>You get:</th>
</tr>
<tr>
<td>
<verbatim>
%MSC%
msc {
 arcgradient = 8;

 a [label="Client"],b [label="Server"];

 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"];
 |||;
}
%ENDMSC%
</verbatim>
</td>
<td>
<img src="%ATTACHURLPATH%/example1.png" alt="example1.png" width="600" height="328" />
</td>
</tr>
</table>
</sticky>

---++ Plugin Installation & Configuration

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

---+++ 1. Install mscgen

Instructions and installation packages can be found from [[http://www.mcternan.me.uk/mscgen/]].

---+++ 2. Install <nop>MessageSequenceChartPlugin

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.

   * Or, follow these __manual installation__ steps: 
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
| *File:* | *Description:* |
| ==data/TWiki/%TOPIC%.txt== | Plugin topic |
| ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
   * 
      * Set the ownership of the extracted directories and files to the webserver user.
      * Install the dependencies (if any).

   * Plugin __configuration and testing__: 
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Configure additional plugin settings in the __Extensions__ section if needed. All settings start with =$TWiki::cfg{Plugins}{MessageSequenceChartPlugin}=, and on many systems, these are optional.
| *Setting* | *Description* |
| ={mscGenCmd}= | Path to [[http://www.mcternan.me.uk/mscgen/][mscgen]] executable on your system. Default value is =/usr/bin/mscgen=. |
| ={mscScript}= | Path to the <nop>MessageSequenceChart.pl script (should be in your tools directory). E.g. =/var/www/twiki/tools/MessageSequenceChart.pl=. |
| ={Debug}= | Debug plugin. See output in data/debug.txt. |
      * Test if the installation was successful: See example above.

---++ Plugin Info

|  Plugin Author: | TWiki:Main.AnttiHaapakangas |
|  Copyright: | &copy; 2012 TWiki:Main.AnttiHaapakangas<br />&copy; 2012 TWiki:TWiki.TWikiContributor |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Plugin Version: | 22613 (2012-02-13) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2012-02-13: | Fixed error handling and reporting |
|  2012-02-09: | Checked in to SVN |
|  2012-02-08: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  Dependencies | <table border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Digest::MD5</td><td align="left">&gt;=0</td><td align="left">Required</td></tr><tr><td align="left">File::Path</td><td align="left">&gt;=0</td><td align="left">Required</td></tr><tr><td align="left">File::Spec</td><td align="left">&gt;=0</td><td align="left">Required</td></tr><tr><td align="left">File::Temp</td><td align="left">&gt;=0</td><td align="left">Required</td></tr><tr><td align="left">mscgen</td><td align="left">&gt;=0</td><td align="left">Required. Available from http://www.mcternan.me.uk/mscgen/.</td></tr></table> |
|  Plugin Home: | http://twiki.org/cgi-bin/view/Plugins/MessageSequenceChartPlugin |
|  Feedback: | http://twiki.org/cgi-bin/view/Plugins/MessageSequenceChartPluginDev |
|  Appraisal: | http://twiki.org/cgi-bin/view/Plugins/MessageSequenceChartPluginAppraisal |

__Related Topics:__ %TWIKIWEB%.TWikiPlugins, %TWIKIWEB%.DeveloperDocumentationCategory, %TWIKIWEB%.AdminDocumentationCategory, %TWIKIWEB%.TWikiPreferences

<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the feedback topic on twiki.org instead. -->
