Mscgen文档翻译：Mscgen

这是什么？

Mscgen 是一个小小的程序，它解析消息流图（Message Sequence Chart）说明代码，然后生成对应的PNG、SVG、EPS或服务器端图片映射(ismaps)。消息流图（Message Sequence Charts (MSCs)），是一种，表示实体及实体间在某段时间内的交互情况的手段，经常与SDL配套使用。MSCs在通信行业狠流行，被用来说明协议是如何工作的，但是，MSCs本身并不复杂，狠容易创建及使用。Mscgen致力于提供一种简单的文本语言，易于创建、编辑、理解，并且能够被转换成通用的图片格式，以便显示或打印。

这个程序，和它所解析的语言， 是受 Graphviz Dot 的启发而设计的，后者提供 了一种非常好的手段来表达状态迁移图（State Transition Diagrams）、数据结构和有向图。 与 Graphviz 不同的是， 这个程序 不会进行智能的布局，也不会进行线条绑束（spline routing），因为对于MSCs 来说不需要这些东西，于是 呢，实现起来就简单得多了。 Doxygen  ( 自版本 1.5.2之后) 也允许像加入dot 图那样向文档中直接嵌入MSCs ， 这样，就可以狠容易地利用消息 流图（message sequence charts）来提升Doxygen 生成的文档的可读性了。

示例

以下是一些示例，展示了原始输入代码和生成的对应的图片，图片格式都是PNG。

# MSC，表示某种想像中的进程 msc { hscale = "2"; 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"]; }

# 想像中的客户端/服务器协议 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"]; |||; }

Mscgen 语言说明

一个消息流图（message sequence chart）的一般格式，由以下带注释的示例来说明。注意，空白字符和换行符会被输入解析器忽略掉。

语法狠简单。要注意的是，开头的几行用来指定消息流图（message sequence chart）中的各个选项和实体，后续的代码，都是表示消息弧。下面的表格中，列出了所有可能的消息弧类型，包括那些所谓的“特殊”弧，它们显示的不是实体之间的关系，而是，在图表上以水平方式描述某个整体的东西。

图形	源代码表示	意义
	-> 或 <-	消息
	=> 或 <=	方法或函数调用
	>> 或 <<	方法或函数的返回值
	=>> 或 <<=	回调
	:> 或 <:	强调消息
	-x 或 x-	丢失的消息
	...	表示，该msc 中的某些信号被省略，或者，已经过去了狠长一段时间。
	---	用来向一砣信号加上注释，或者，表示发生了某个动作或进入了某个状态。
	|||	在不同的行之间加入额外的空间。
	->* 或 *<-	广播弧，该弧会延伸到除源实体之外的所有实体。弧的说明文字会以整个图表为参考进行水平居中。
	box	框状弧，原来的弧会被替换成选中的实体之间的一个框框。弧的说明文字会在框中居中显示，并且会发生必要的自动换行。
	rbox	圆角框状弧，原来的弧会被替换成选中的实体之间的一个框框。弧的说明文字会在框中居中显示，并且会发生必要的自动换行。
	abox	六角框状弧，原来的弧会被替换成选中的实体之间的一个框框。弧的说明文字会在框中居中显示，并且会发生必要的自动换行。
	note	注释框状弧，原来的弧会被替换成选中的实体之间的一个框框。弧的说明文字会在框中居中显示，并且会发生必要的自动换行。

利用框框类型，可以添加状态及条件框。在源代码中，写法仍然是，不同实体之间的一个关系，但是，在输出的图片中，框框会被拉伸以涵盖源实体和目的实体。

# 带框框的示例MSC msc { # 实体 A, B, C, D; # 在框框之前加入一砣小的空白 |||; # 下面 4个框位于同一行，因为行尾是 ',' A box A [label="box"], B rbox B [label="rbox"], C abox C [label="abox"], D note D [label="note"]; # 带背景色的框框示例 A abox B [label="abox", textbgcolour="#ff7f7f"]; B rbox C [label="rbox", textbgcolour="#7fff7f"]; C note D [label="note", textbgcolour="#7f7fff"]; }

除了这些弧类型之外，还可以向每条消息弧或实体添加若干属性。这些属性是以方括号包围，紧跟在实体名或消息弧之后的，不同属性之间以逗号分隔：

a->b [label="A to B", textcolour="red", linecolour="#ffb011"];

下表列出了所有可能的属性及它们的意义，注意，每个属性，都可以用于特殊的'...'和'---'弧类型，当然也可以用于其它弧或用于实体。

颜色，可像一样HTML 以#前缀加上RGB 颜色代码来表示，或者，也可使用下面示例中列出的预定义颜色名来表示。

最后，可向输入文件中加入一些选项，以控制所生成的图片的各个方面的东西。目前，只支持少数几个选项，并且，这些选项必须在输入文件的顶部指定，就像下面的示例中这样。表格中列出了所有可用的选项。

msc {

# 选项区域

hscale="1.5", arcgradient="5";

# 实 体

A, B;

# 弧

A -> B;

}

mscgen 语言 的语法 在 这里 。

下载

当前版本 是 0.20 ( 变更记录 ) 。最新版本 可在以下链接下载：

开发源代码

开发 源代码可在 谷歌代码 获取， 也可在线 浏览 ，或使用匿名 SVN 获取。

Doxygen集成

最初 ，我对 Doxygen 做了些修改， 这样，它就可以调用其它 的命令行工具了。作为响应 ， Doxygen版本1.5.2 ( 于 4-4-2007 发布 ) 由Dimitri 做了一些改进，开始支持 \msc 和 \endmsc 命令 。 这就意味着， 可利用以下代码来向Doxygen 文档中加入MSCs：

/** Request a fandango on core.

* Sending this signal to the Iberian dance task will cause it to create a

* wild pointer which is then used to corrupt the malloc arena leading to

* mysterious failures later on in the program execution.

*

*\msc

*  T,"Iberian Dance Task";

*

*  T->"Iberian Dance Task" [label="IbFandangoReq", URL="\ref IbFandangoReq"];

*  T<<"Iberian Dance Task" [label="IbFandangoCnf", URL="\ref IbFandangoCnf", ID="1"];

*\endmsc

*

* <OL>

* <LI>In some cases, the system may have failed before this signal is sent

*     or received, in which case the confirm maybe lost.

* </OL>

*/

typedef struct IbFandangoReqTag

{

TaskId reqTaskId;

}

IbFandangoReq;

可在 此 观摩上面示例代码的输出结果。 在 Doxygen手册 中也给出了一个使用此命令的例子。