diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/msc/manual.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/msc/manual.tex | 2834 |
1 files changed, 2834 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/msc/manual.tex b/Master/texmf-dist/doc/latex/msc/manual.tex new file mode 100644 index 00000000000..a032b52de25 --- /dev/null +++ b/Master/texmf-dist/doc/latex/msc/manual.tex @@ -0,0 +1,2834 @@ +% file: manual.tex +% Copyright 2002 V. Bos and S. Mauw +% This file is part of the MSC Macro Package. +% +% RCS version: $Id: manual.tex,v 1.9 2004/03/15 11:35:47 vbos Exp $ +% +\documentclass[12pt,a4paper]{article} +\usepackage{a4wide} +\usepackage{url} +\usepackage{moreverb} +\usepackage{graphicx} +\usepackage{multicol} +\usepackage{msc} + +% we allow a ragged right +\setlength{\rightskip}{0pt plus 0.05\linewidth minus 0pt} + + + + + +\newlength{\rpwidth} +\setlength{\rpwidth}{.5cm} +\newlength{\rpheight} +\setlength{\rpheight}{0.5\levelheight} +\newcommand{\rpN}{% + \psframe(-0.5\rpwidth,-\rpheight)(0.5\rpwidth,0\rpheight)% + \rput[B](0\rpwidth,-0.8\rpheight){\tiny \textsc{n}}% + \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% +} +\newcommand{\rpNE}{% + \psframe(-\rpwidth,-\rpheight)(0\rpwidth,0\rpheight)% + \rput[B](-.5\rpwidth,-0.8\rpheight){\tiny \textsc{ne}}% + \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% +} +\newcommand{\rpE}{% + \psframe(-\rpwidth,-.5\rpheight)(0\rpwidth,.5\rpheight)% + \rput[B](-.5\rpwidth,-0.3\rpheight){\tiny \textsc{e}}% + \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% +} +\newcommand{\rpSE}{% + \psframe(-\rpwidth,0\rpheight)(0\rpwidth,\rpheight)% + \rput[B](-.5\rpwidth,0.2\rpheight){\tiny \textsc{se}}% + \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% +} +\newcommand{\rpS}{% + \psframe(-.5\rpwidth,\rpheight)(.5\rpwidth,0\rpheight)% + \rput[t](0\rpwidth,0.8\rpheight){\tiny \textsc{s}}% + \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% +} +\newcommand{\rpSW}{% + \psframe(0\rpwidth,0\rpheight)(\rpwidth,\rpheight)% + \rput[B](.5\rpwidth,0.2\rpheight){\tiny \textsc{sw}}% + \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% +} +\newcommand{\rpW}{% + \psframe(0\rpwidth,-.5\rpheight)(\rpwidth,.5\rpheight)% + \rput[B](.5\rpwidth,-0.3\rpheight){\tiny \textsc{w}}% + \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% +} +\newcommand{\rpNW}{% + \psframe(0\rpwidth,-\rpheight)(\rpwidth,0\rpheight)% + \rput[B](.5\rpwidth,-0.8\rpheight){\tiny \textsc{nw}}% + \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% +} + + + + + +% The following code is taken from the doc package. It defines a global +% macro \bslash that produces a bslash (if present in the current font). +\makeatletter +{\catcode`\|=\z@ \catcode`\\=12 |gdef|bslash{\}} +\makeatother +\newcommand{\cmd}[1]{\texttt{\bslash #1}} + +\newcommand{\acro}[1]{{#1}} + +\newcommand{\MSC}{\acro{MSC}} +\newcommand{\HMSC}{\acro{HMSC}} +\newcommand{\MSCdoc}{\MSC{}doc} +\newcommand{\mscpack}{\MSC{} macro package} + +\newcommand{\env}[1]{\texttt{#1}} +\newcommand{\opt}[1]{[#1]} +\newcommand{\cmdarg}[1]{\{\emph{#1}\}} +\newcommand{\coordarg}[1]{\emph{#1}} +\newcommand{\coordargs}[2]{(\coordarg{#1},\coordarg{#2})} +\newcommand{\lnsvalue}[3]{large/normal/small value #1/#2/#3} + +\newenvironment{defs}{% + \begin{list}{}% + {\setlength{\labelwidth}{0pt}% + \setlength{\labelsep}{1em}% + \setlength{\leftmargin}{1em}% + \setlength{\parsep}{1ex}% + \setlength{\listparindent}{0pt}% + \setlength{\rightmargin}{0pt}% + \renewcommand{\makelabel}[1]{##1}% + \raggedright% + }% + }{% + \end{list}} + + + +\title{ + A \LaTeX\ macro package for Message Sequence Charts\\{\large User Manual} +} + +\author{ + \begin{tabular}{cc} + Victor Bos & Sjouke Mauw\\ + \footnotesize Turku Centre for Computer Science & + \footnotesize Eindhoven University of Technology \\ [-0.8ex] + \footnotesize Software Construction Laboratory & + \footnotesize Department of Mathematics and Computing Science \\ [-0.8ex] + \footnotesize Lemmink\"aisenkatu 14 & + \footnotesize P.O.\ Box 513 \\ [-0.8ex] + \footnotesize FIN--20520 Turku & + \footnotesize NL--5600 MB Eindhoven \\ [-0.8ex] + \footnotesize Finland & + \footnotesize The Netherlands \\ + \footnotesize \texttt{vbos@abo.fi} & + \footnotesize \texttt{sjouke@win.tue.nl} + \end{tabular} +} + +\date{\small Version \mscversion, last update \today\\ + Describing \mscpack{} version \mscversion} + +\begin{document} + + +\maketitle + +\begin{abstract} +\noindent +The \mscpack{} facilitates the \LaTeX\ user to easily include +Message Sequence Charts in his texts. This document describes the +design and use of the \mscpack. +\end{abstract} + +\tableofcontents +\section{New} +\label{new} + +\paragraph{Version~1.13} has a reimplementation of message commands in MSC +diagrams. The affected commands are: \verb+\create+, \verb+\found+, +\verb+\lost+, \verb+\mess+, and \verb+\order+. The new implementation +provides more control over the placement of message labels. + +The command \verb+\selfmesslabelpos+ has been removed. + +The bounding box bug has been partly solved. Now, a white \verb+\fbox+ +is drawn around every (msc, mscdoc, hmsc) diagram. This makes it +possible for \texttt{dvips -E} to compute the correct bounding box for +the diagrams. Due to the \verb+\fbox+, each diagram is extended with +0.3pt on each side (left, top, right, and bottom). This bugfix fails +if the background is not white. The xdvi program shows the white +\verb+\fbox+ in black with the result that diagrams have two visible +frames. This seems to be a bug of xdvi. + +The lines around comments (\verb+\msccomment+, Section~\ref{comments}) +are changed from gray into black. The reason for this is that the gray +lines became invisible after converting the document to HTML. + +\paragraph{Version~1.12} is a non-public version. It features a preliminary +implementation of message label position control. + +\paragraph{Version~1.11} is a mainly a bugfix of version~1.10a, see~\cite{BM02b}. +The next list shows the new features of version~1.10a compared to +version 1.4. + +\begin{itemize} +\item Support for method replies (dashed message arrows):\cmd{mess*} (Section~\ref{messages}) +\item Fat instances, i.e., double line instances (Section~\ref{instances}) +\item Comments (Section~\ref{comments}) +\item Coregions are now special cases of regions (which includes also +activation and suspension regions). The \cmd{coregionstart} and +\cmd{coregionend} commands are obsolete and the \cmd{coregionbarwidth} +is replaced by \cmd{regionbarwidth}. +\item Gates (Section~\ref{gates}) +\item High-level \MSC{}'s (Section~\ref{hmsc}) +\item \cmd{inlinestart} has additional optional argument to allow for different left and right overlap (Section~\ref{inlines}) +\item \MSCdoc{}s (Section~\ref{mscdoc}) +\item Reference manual~\cite{BM02} +\item \cmd{referencestart} has additional optional argument to allow for different left and right overlap (Section~\ref{references}) +\item Regions: generalization of coregions supporting activations, suspension, and coregions (Section~\ref{regions}) +\item Time measurements (Section~\ref{measurements}) +\end{itemize} + + +\section{Introduction} +\label{introduction} + +The \MSC{} language is a visual language for the description of the +interaction between different components of a system. +This language is standardized by the ITU (International +Telecommunication Union) in Recommendation Z.120~\cite{z120}. An +introductory text on \MSC{} can be found +in~\cite{RudolphGrabowskiGraubmann96}. \MSC{}s have a +wide application domain, ranging from requirements specification to +testing and documentation. +An example of a Message Sequence Chart is in Figure~\ref{quick}. + +In order to support easy drawing of \MSC{}s in \LaTeX\ documents, we have +developed the \mscpack. The current version of the \mscpack{} +supports the following \MSC{} constructs: \MSC{} frame, instances (both +single line width and double line width), messages (including +self-messages and messages to the environment), actions, singular and +combined timer events (set, timeout, reset, set-timeout, set-stop), +lost and found messages, generalized order, conditions, coregions, +activation regions, suspension regions, gates, instance creation, +instance stop, time measurements, references, and inline +expressions. In addition, there is support for \HMSC{}'s (high-level +\MSC{}s) and \MSCdoc{}s. + +In this manual we explain the design and the use of the \mscpack. For +a complete overview of all features, we refer to the reference +manual~\cite{BM02}, which is included in the distribution under the +name \verb+refman.ps+. Another way to learn how to use the \mscpack{} +is to have a look at the \LaTeX{} source code of the manual and the +source code of the reference manual. They are included in the +distribution under the names \verb+manual.tex+ and \verb+refman.tex+, +respectively. The \MSC{} constructs are simply introduced as +syntactic constructs. This paper is not meant to describe their use or +meaning. + +We list the backgrounds of the package and some design decisions in +Section~\ref{background}. +Section~\ref{install} contains notes on installing the +package. Section~\ref{quickstart} contains an example of using the +package. It allows the impatient reader to quickly start using the +package. The details of using the package are explained in +Section~\ref{use}. In Section~\ref{parameters} the parameters are +explained which determine detailed layout of the various symbols. +A large but meaningless example is given in +Section~\ref{example}. + + +\section{Background and motivation} +\label{background} +Several commercial and non-commercial tools are available, which +support drawing or generating Message Sequence Charts. However, these +tools are in general not freely available and often not flexible +enough to satisfy all user's wishes with respect to the layout and +graphical appearance of an \MSC{}. +Therefore, people often use general drawing tools, such as {\em xfig} +to draw \MSC{}s. However flexible this approach is, it takes quite some +effort to produce nice \MSC{} drawings in a tool which is not dedicated +to \MSC{}s. Furthermore, when drawing a number of \MSC{}s it requires some +preciseness in order to obtain a consistent set of \MSC{}s. + +For these reasons, we have started the design of a set of +\LaTeX\ macros which support the drawing of \MSC{}s. In this way, an \MSC{} can be +represented in \LaTeX\ in a textual format and compiled into +e.g.\ PostScript. + +We aimed at satisfying the following requirements and design +decisions. +\begin{itemize} +\item +The package should follow the ITU standard with respect to shape and +placement of the symbols. (The current version supports +the \MSC2000 standard.) +\item +Static and dynamic semantics are not considered. The user is allowed +to violate all semantical restrictions and draw inconsistent \MSC{}s. +The package only supports elementary syntactical requirements. +\item +The package should offer functionality at the right level of +abstraction. Rather than supplying coordinates of pixels, the +user should be able to express the placement of symbols in terms of +{\em levels}. +Nevertheless, the textual representation of \MSC{}s as defined by the ITU +standard has a level of abstraction which is too high for our purposes. +It lacks information about the actual positioning of the \MSC{} symbols, +while we think that in our package this should be under user control. +\item +There should be only minimal automatic restructuring and layout of the +\MSC{} (e.g.\ the relative positioning of two messages should be as +defined by the user, even if the messages are not causally ordered). +\item +The user can customize the appearance of the \MSC{}s by manipulating +an appropriate set of parameters. +\end{itemize} + +\section{Installation, copyright and system requirements} +\label{install} + +The \mscpack{} is still under development. The authors +appreciate any comments and suggestions for improvements. The most +recent version of the package can be downloaded from +\url{http://www.win.tue.nl/~sjouke/mscpackage.html}. + + +The \mscpack{} has a \emph{LaTeX Project Public License} +(LPPL), see~\url{http://www.latex-project.org/lppl.txt}: +{\small +\verbatiminput{COPYRIGHT} +} As such, it is free of charge and can be freely +distributed. Furthermore, it is allowed to make modifications to the +package, provided that modified versions get different names. The +authors accept no liability with respect to the functioning of the +package. + +The \mscpack{} runs with \LaTeXe. It has been tested with \LaTeXe\ +version dated 1998/06/01 using \TeX\ version 3.14159. The following +additional packages are required: \textsf{pstricks}, \textsf{calc}, +\textsf{ifthen}, and \textsf{color}. These packages are in general +part of the standard \LaTeXe\ distribution. These additional packages +can be obtained from the {\em ctan} database for \LaTeX\, e.g.\ via +the following URL: \url{http://www.tex.ac.uk/}. The \textsf{pstricks} +package is described in~\cite[Chapter~4]{GSM97}. The generated output +can only be previewed with recent previewing software (e.g.\ xdvi +version 20c). It may be needed to update all \LaTeX\ related software +to a more recent version in order to smoothly work with the \mscpack. + +The \mscpack{} can be installed easily. Just put the file +\verb+msc.sty+ in a directory which is searched by \LaTeX{} for style +files. The set of directories actually searched depends on the \TeX\ +installation, but often the {\em current directory} is included. UNIX +users may have to set the environment variable \texttt{\$TEXINPUTS} to +an appropriate value. For more details on this topic consult +documentation of your \TeX\ installation. + +%The following text is currently not applicable -sm +% +%A problem may occur when using more packages than the \MSC{} macro +%package in your \LaTeX\ document. This happens, e.g.\ when using the +%{\em epsfig} package. These problems are due to the combination of +%several packages which are required (but not provided) by the \MSC{} +%macro package. The solution is to change the order of the +%\verb+usepackage+ clauses. + +\section{Quick start} +\label{quickstart} +The \mscpack{} is easy to use. +Below is an example of the use of the package and +Figure~\ref{quick} shows the generated \MSC{}. + +{\small +\begin{verbatim} +\documentclass{article} +\usepackage{msc} +\begin{document} + +\begin{msc}{Example} + +\declinst{usr}{User}{} +\declinst{m1}{Machine 1}{control} +\declinst{m2}{Machine 2}{drill} +\declinst{m3}{Machine 3}{test} + +\mess{startm1}{usr}{m1} +\nextlevel +\mess{startm2}{m1}{m2} +\nextlevel +\mess{continue}{m2}{m3} +\mess{log}{m1}{envleft} +\nextlevel +\mess{output}{m3}{usr}[2] +\nextlevel +\mess{free}{m1}{usr} +\nextlevel + +\end{msc} + +\end{document} + +\end{verbatim} +} + +\begin{figure}[htb] +\begin{center} + +\begin{msc}{Example} + +\declinst{usr}{User}{} +\declinst{m1}{Machine 1}{control} +\declinst{m2}{Machine 2}{drill} +\declinst{m3}{Machine 3}{test} + +\mess{startm1}{usr}{m1} +\nextlevel +\mess{startm2}{m1}{m2} +\nextlevel +\mess{continue}{m2}{m3} +\mess{log}{m1}{envleft} +\nextlevel +\mess{output}{m3}{usr}[2] +\nextlevel +\mess{free}{m1}{usr} +\nextlevel + +\end{msc} + +\end{center} +\caption{The generated \MSC{}} +\label{quick} +\end{figure} + +The \mscpack{} is activated by the clause +\verb+\usepackage{msc}+. +This package contains, among others, a +definition of the environment \verb+msc+. +This environment is used to draw \MSC{}s. The \MSC{} definition is surrounded by +the clauses \verb+\begin{msc}{Example}+ and \verb+\end{msc}+. The name of +the \MSC{}, {\tt Example}, is displayed in the upper-left corner of the +\MSC{}. + +The next four lines define the \emph{instances}: +\verb+\declinst{m1}{Machine 1}{control}+ defines an instance with +\emph{nickname} \verb+m1+ and a description consisting of two parts, +namely, \verb+Machine 1+ and \verb+control+. The nickname is used in +all subsequent references to this instance. The first part of the +description is drawn above the rectangular instance head symbol, and +the second part of the description is drawn inside the instance head +symbol. + +The following lines contain the definitions of the messages. Every +message has a source and a destination instance. The clause +\verb+\mess{startm1}{usr}{m1}+ defines a message with name {\tt +startm1}, which goes from instance {\tt usr} to instance {\tt m1}. + +In order to control the vertical placement of the messages, the \MSC{} is +divided into levels. At every level, any number of messages may start. +The vertical position of the end point of a message is determined +by the optional fourth argument of the message definition, as in the +clause \verb+\mess{output}{m2}{user}[2]+. +This argument is the vertical offset (in number of levels) between the +start point of the message (i.e.\ the current level) and its end point. +If the value is 0 the message is drawn horizontally. A negative offset +means that the arrow has an upward slope. + +The clause \verb+\nextlevel+ is used to advance to the next level. + +\section{Use of the \mscpack} +\label{use} + +\subsection{The \MSC{} frame} +\label{mscframe} +The \verb+msc+ environment is used for making \MSC{} definitions. Thus, such a +definition looks as follows. + +\begin{verbatim} +\begin{msc}[headerpos]{mscname} +...definition of the MSC... +\end{msc} +\end{verbatim} + +This draws the frame and the header of the \MSC{}. +The argument \verb+mscname+ is the name of the \MSC{}. +The header of an \MSC{} is formed from the keyword \verb+msc+, followed +by the \verb+mscname+. Positioning of this header is controlled by +the optional argument \verb+headerpos+. This argument can have values +\verb+l+ (for a left aligned header), \verb+c+ (for a centered header) +and \verb+r+ (for a right aligned header). +The default value of \verb+headerpos+ is \verb+l+. + +The size of the \MSC{} frame is determined vertically by the number of levels +occurring in the \MSC{} (see Section~\ref{levels}) and horizontally by +the number of instances (see Section~\ref{instances}). + +The parameter \verb+\topnamedist+ controls the distance between the +top of the \MSC{} frame and the header (see Section~\ref{parameters}). +The parameter \verb+\leftnamedist+ controls the distance between the +left of the \MSC{} frame and the header if the \verb+headerpos+ is +\verb+l+ and it controls the distance between the right of the \MSC{} +frame and the header if \verb+headerpos+ is \verb+r+ (see +Section~\ref{parameters}). + +\subsection{Levels} +\label{levels} +An \MSC{} is vertically divided in {\em levels}. All events in an \MSC{} are +attached to a certain level, or stretch out over several levels. +Any number of events can be drawn at a certain level. +An event will always be drawn (or started) at the current level, unless a level +offset is specified (see e.g.\ the \verb+\mess+ command in +Section~\ref{messages}). The level offset is an integer number, which +denotes at which level, relative to the current level, an event should +be drawn. +Drawing starts at level 0. +The following command is used to advance to the next level. +\begin{verbatim} +\nextlevel[leveloffset] +\end{verbatim} + +The \verb+leveloffset+ is an integer value which denotes the number of +levels to advance. By default, the value of \verb+leveloffset+ is 1, +which means drawing continues at the next level. Setting +\verb+leveloffset+ to a negative value may result in unexpected +drawings, however, see the \emph{Tricks} section in the reference +manual~\cite{BM02}. + +There are three parameters which control the size of the levels (see +Section~\ref{parameters}). These are \verb+\firstlevelheight+ (the +distance between the instance start symbol and the first level), +\verb+\levelheight+ (the distance between two consecutive levels), and +\verb+\lastlevelheight+ (the distance between the last level and the +instance end symbol). Figure~\ref{parametersfig} on +page~\pageref{parametersfig} shows all lengths of the \mscpack. + +\subsection{Instances} +\label{instances} +All instances have to be declared before they can be used. An instance +consists of an instance head symbol with an associated name, an +instance axis and an instance end symbol. Normal instances have a +single line axis. Fat instances have a double line axis. The order of +the instance declarations determines the order in which the instances +occur in the drawing. + +An instance is declared with the following command. + +\begin{verbatim} +\declinst(*){nickname}{instancenameabove}{instancenamewithin} +\end{verbatim} + +The starred version produces a fat instance. +The \verb+nickname+ is used for referring to this instance in the rest of the +\MSC{} definition. +The \verb+instancenameabove+ is put above the instance head symbol. +The \verb+instancenamewithin+ is put inside the instance head symbol. + +Several parameters allow the user to customize the shape and +positioning of instances (see Section~\ref{parameters}). These are +\verb+\topheaddist+ (the distance between the top of the \MSC{} and the +instance head symbol), \verb+\instheadheight+ (the height of the +instance head symbol), \verb+\instfootheight+ (the height of the +instance foot symbol), \verb+\bottomfootdist+ (the distance between +the instance foot symbol and the bottom of the \MSC{} frame), +\verb+\instwidth+ (the width of the instance head and foot symbols), +\verb+\instdist+ (the distance between two instance axes), +\verb+\envinstdist+ (the distance between the edge of the \MSC{} and the +first/last instance axis), and \verb+\labeldist+ (the distance between +the instance head symbol and the part of the instance name drawn above +the head symbol). The command \verb+\setfootcolor{color}+ sets the +fill color of the footer symbol. Valid color values are, e.g., +\texttt{black} (default), \texttt{white}, and \texttt{gray}. + +The following \MSC{} shows the declaration of an \MSC{} with three +instances. The first and the last are normal instances (one line axis) +whereas the second is a fat instance (double line axis). The second +line, \verb+\setmscvalues{small}+, indicates that the small drawing +style should be used (see Section~\ref{parameters}). + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}[l]{instances} +\setmscvalues{small} + +\declinst{i}{above}{within} +\declinst*{j}{}{j} +\declinst{k}{k}{} + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\small +\begin{verbatim} +\begin{msc}{instances} +\setmscvalues{small} + +\declinst{i}{above}{within} +\declinst*{j}{}{j} +\declinst{k}{k}{} + +\end{msc} +\end{verbatim} +} +\end{minipage} + + +\subsection{Messages} +\label{messages} +A message is denoted by an arrow from the sending instance to the +receiving instance. The instances are referred to by their nicknames. +A message is defined with the following command. + +\begin{verbatim} +\mess(*)[pos]{name}[labelpos]{sender}[placement]{receiver}[leveloffset] +\end{verbatim} +The \verb+name+ of the message may be any string. The \mscpack{} +processes the \verb+name+ argument in LR-mode, +see~\cite[page~36]{Lam94}. This means that the string will consist of +one line. To generate multi-line message names, use the standard +\cmd{parbox} command, see the \emph{Tricks} section in the reference +manual~\cite{BM02}. By default, the name of a message label is drawn +above the center of the arrow, but the optional parameters \verb+pos+, +\verb+labelpos+, and \verb+placement+ influence the actual location, +as described below. The arrow starts at the current level at the +sending instance. The arrow ends at the current level plus the +\verb+leveloffset+, at the receiving instance. The \verb+leveloffset+ +is an optional integer argument with default value 0. The +\verb+sender+ and \verb+receiver+ should be the nicknames of declared +instances. + +In case the sending and the receiving instance are the same, the +message is a \emph{self message}. A self message is drawn as a +polyline connecting the instance axis to itself. + +The starred version of the command, \verb+\mess*+, produces the same +result as \verb+\mess+, except that the arrow is drawn with a dashed +line. This can be used to draw a {\em method reply} (see~\cite{z120}). + +As mentioned above, placement of the message and its label is +controlled by the optional parameters \verb+pos+, \verb+labelpos+, and +\verb+placement+. In case of a self message, \verb+pos+ denotes the +position of the arrow with respect to the instance axis. Valid values +are \verb+l+ (left) and \verb+r+ (right). The default value is +\verb+l+. In case of a non-self message, the \verb+pos+ parameter is +ignored. + +Whereas the \verb+pos+ parameter defines the position of the arrow +symbol with respect to the instance axis, the \verb+labelpos+ +parameter defines the position of the message label with +respect to the message arrow. In case of a self message, valid values +for \verb+labelpos+ are \verb+l+ (left) and~\verb+r+ (right). The +default value is equal to the, possibly user defined, value of the +\verb+pos+ parameter. In case of a non-self message, valid values for +\verb+labelpos+ are \verb+t+ (on top) and~\verb+b+ (below). The +default value is~\verb+t+. + +Finally, the \verb+placement+ parameter defines the relative distance +of the message label to the beginning of the message. Valid values are +real numbers in the closed interval $[0,1]$. The default value +is~$0.5$. While drawing a message, the \mscpack{} computes the +coordinates of the message label using \verb+placement+ and the length +and coordinates of the arrow. It then computes a \emph{reference +point} for the message label and places it on the coordinates just +computed. Figures \ref{fig:refpoints} (page~\pageref{fig:refpoints}) +and~\ref{fig:refpoints:B} (page~\pageref{fig:refpoints:B}) +schematically show the reference points for message labels. In the +first figure, the labels are located at the default position. In the +second figure, all labels are shifted along the arrow by setting +$\verb+placement+ = 0.9$. The \verb+\lost+ and \verb+\found+ commands +(Section~\ref{lostfound}) and the \verb+\create+ +(Section~\ref{createstop}) command use the same method to determine +reference points and message label locations. Note that the boxes with +the location of the reference points are not generated by the \LaTeX{} +code given in Figures \ref{fig:refpoints} and~\ref{fig:refpoints:B}; +we enriched the \LaTeX{} code with some extra \textsf{pstricks} code +(see \LaTeX{} source code of this document). + +In addition to label position control, there are three ways to control +the shape of messages (see Section~\ref{parameters}). These are: +\verb+\selfmesswidth+ (a parameter to specify the width of the +polyline used for drawing self-messages), \verb+\labeldist+ (a +parameter to specify the distance between the label of a message and +the message arrow), and \verb+\messarrowscale{size}+ (a command to set +the size of the arrow head of a message). \verb+size+ should be +positive real number. + +Messages to or from the environment (i.e.\ the left or the right side +of the \MSC{} frame) can be +specified by setting the sender or the receiver argument to one of the values +\verb+envleft+ or \verb+envright+. (Note: Since instances and +environments are treated equally in the implementation, at every position +where the nickname of an instance is required, also +\verb+envleft+ and \verb+envright+ are allowed.) + +The following \MSC{} shows an example of the use of messages. +In this sample \MSC{} and the following \MSC{}s in this section we will +not list the complete textual representations of the \MSC{}s. For brevity +we omit the environment call and the declarations of the instances. +Note the final \verb+\nextlevel+ command which is needed +to make the instance axis long enough to receive message +\verb+a+. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{messages} +\setmscvalues{small} +\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} + +\mess{a}{j}{i}[3] +\mess{self}{i}{i} +\nextlevel +\mess*{b}{j}{k} +\mess[b]{c}{k}{envright} +\nextlevel +\mess{d}{k}[.6]{i} +\nextlevel + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\small +\begin{verbatim} +\mess{a}{j}{i}[3] +\mess{self}{i}{i} +\nextlevel +\mess*{b}{j}{k} +\mess[b]{c}{k}{envright} +\nextlevel +\mess{d}{k}[.6]{i} +\nextlevel +\end{verbatim} +} +\end{minipage} + +\begin{figure}[htb] +\begin{minipage}{\linewidth} +\setmscvalues{small} +\begin{multicols}{2} +\begin{msc}{Label reference points} +\declinst{m0}{I0}{} +\declinst{m1}{I1}{} +\declinst{m2}{I2}{} +\nextlevel + +\mess{\rpS}{m0}{m1} +\nextlevel +\mess{\rpN}[b]{m1}{m2} +\nextlevel[2] + +\mess{\rpS}{m1}{m0} +\nextlevel +\mess{\rpN}[b]{m2}{m1} +\nextlevel[2] + +\mess{\rpE}{m0}{m0}[2] +\mess[r]{\rpW}{m2}{m2}[2] +\nextlevel[4] +\mess{\rpW}[r]{m0}{m0}[2] +\mess[r]{\rpE}[l]{m2}{m2}[2] +\nextlevel[6] + +\mess{\rpE}{m0}{m0}[-2] +\mess[r]{\rpW}{m2}{m2}[-2] +\nextlevel[4] +\mess{\rpW}[r]{m0}{m0}[-2] +\mess[r]{\rpE}[l]{m2}{m2}[-2] +\nextlevel[2] + +\mess{\rpSW}{m0}{m1}[2] +\mess{\rpNE}[b]{m1}{m2}[2] +\nextlevel[6] + +\mess{\rpSW}{m1}{m0}[-2] +\mess{\rpNE}[b]{m2}{m1}[-2] +\nextlevel[2] + +\mess{\rpSE}{m1}{m0}[2] +\mess{\rpNW}[b]{m2}{m1}[2] +\nextlevel[6] + +\mess{\rpSE}{m0}{m1}[-2] +\mess{\rpNW}[b]{m1}{m2}[-2] +\nextlevel[2] +\end{msc} +\bigskip + +\scriptsize +\begin{verbatim} +\begin{msc}{Label reference points} +\declinst{m0}{I0}{} +\declinst{m1}{I1}{} +\declinst{m2}{I2}{} +\nextlevel + +\mess{S}{m0}{m1} +\nextlevel +\mess{N}[b]{m1}{m2} +\nextlevel[2] + +\mess{S}{m1}{m0} +\nextlevel +\mess{N}[b]{m2}{m1} +\nextlevel[2] + +\mess{E}{m0}{m0}[2] +\mess[r]{W}{m2}{m2}[2] +\nextlevel[4] +\mess{W}[r]{m0}{m0}[2] +\mess[r]{E}[l]{m2}{m2}[2] +\nextlevel[6] + +\mess{E}{m0}{m0}[-2] +\mess[r]{W}{m2}{m2}[-2] +\nextlevel[4] +\mess{W}[r]{m0}{m0}[-2] +\mess[r]{E}[l]{m2}{m2}[-2] +\nextlevel[2] + +\mess{SW}{m0}{m1}[2] +\mess{NE}[b]{m1}{m2}[2] +\nextlevel[6] + +\mess{SW}{m1}{m0}[-2] +\mess{NE}[b]{m2}{m1}[-2] +\nextlevel[2] + +\mess{SE}{m1}{m0}[2] +\mess{NW}[b]{m2}{m1}[2] +\nextlevel[6] + +\mess{SE}{m0}{m1}[-2] +\mess{NW}[b]{m1}{m2}[-2] +\nextlevel[2] +\end{msc} +\end{verbatim} +\end{multicols} +\end{minipage} +\caption{Reference points of message labels} +\label{fig:refpoints} +\end{figure} + + +\begin{figure}[htb] +\begin{minipage}{\linewidth} +\setmscvalues{small} +\begin{multicols}{2} +\begin{msc}{Label reference points (2)} +\declinst{m0}{I0}{} +\declinst{m1}{I1}{} +\declinst{m2}{I2}{} +\nextlevel + +\mess{\rpS}{m0}[.9]{m1} +\nextlevel +\mess{\rpN}[b]{m1}[.9]{m2} +\nextlevel[2] + +\mess{\rpS}{m1}[.9]{m0} +\nextlevel +\mess{\rpN}[b]{m2}{m1} +\nextlevel[2] + +\mess{\rpE}{m0}[.9]{m0}[2] +\mess[r]{\rpW}{m2}[.9]{m2}[2] +\nextlevel[4] +\mess{\rpW}[r]{m0}[.9]{m0}[2] +\mess[r]{\rpE}[l]{m2}[.9]{m2}[2] +\nextlevel[6] + +\mess{\rpE}{m0}[.9]{m0}[-2] +\mess[r]{\rpW}{m2}[.9]{m2}[-2] +\nextlevel[4] +\mess{\rpW}[r]{m0}[.9]{m0}[-2] +\mess[r]{\rpE}[l]{m2}[.9]{m2}[-2] +\nextlevel[2] + +\mess{\rpSW}{m0}[.9]{m1}[2] +\mess{\rpNE}[b]{m1}[.9]{m2}[2] +\nextlevel[6] + +\mess{\rpSW}{m1}[.9]{m0}[-2] +\mess{\rpNE}[b]{m2}[.9]{m1}[-2] +\nextlevel[2] + +\mess{\rpSE}{m1}[.9]{m0}[2] +\mess{\rpNW}[b]{m2}[.9]{m1}[2] +\nextlevel[6] + +\mess{\rpSE}{m0}[.9]{m1}[-2] +\mess{\rpNW}[b]{m1}[.9]{m2}[-2] +\nextlevel[2] +\end{msc} +\bigskip + +\scriptsize +\begin{verbatim} +\begin{msc}{Label reference points (2)} +\declinst{m0}{I0}{} +\declinst{m1}{I1}{} +\declinst{m2}{I2}{} +\nextlevel + +\mess{S}{m0}[.9]{m1} +\nextlevel +\mess{N}[b]{m1}[.9]{m2} +\nextlevel[2] + +\mess{S}{m1}[.9]{m0} +\nextlevel +\mess{N}[b]{m2}{m1} +\nextlevel[2] + +\mess{E}{m0}[.9]{m0}[2] +\mess[r]{W}{m2}[.9]{m2}[2] +\nextlevel[4] +\mess{W}[r]{m0}[.9]{m0}[2] +\mess[r]{E}[l]{m2}[.9]{m2}[2] +\nextlevel[6] + +\mess{E}{m0}[.9]{m0}[-2] +\mess[r]{W}{m2}[.9]{m2}[-2] +\nextlevel[4] +\mess{W}[r]{m0}[.9]{m0}[-2] +\mess[r]{E}[l]{m2}[.9]{m2}[-2] +\nextlevel[2] + +\mess{SW}{m0}[.9]{m1}[2] +\mess{NE}[b]{m1}[.9]{m2}[2] +\nextlevel[6] + +\mess{SW}{m1}[.9]{m0}[-2] +\mess{NE}[b]{m2}[.9]{m1}[-2] +\nextlevel[2] + +\mess{SE}{m1}[.9]{m0}[2] +\mess{NW}[b]{m2}[.9]{m1}[2] +\nextlevel[6] + +\mess{SE}{m0}[.9]{m1}[-2] +\mess{NW}[b]{m1}[.9]{m2}[-2] +\nextlevel[2] +\end{msc} +\end{verbatim} +\end{multicols} +\end{minipage} +\caption{Reference points of shifted message labels} +\label{fig:refpoints:B} +\end{figure} + + +\subsection{Comments} +\label{comments} + +Comments are additional texts to clarify (events on) an instance. The +following command can be used to add comments to an \MSC{} diagram. + +\begin{verbatim} +\msccomment[position]{text}{instname} +\end{verbatim} + +The \verb|instname| parameter defines the instance to which the +comment is attached. The text of the comment is specified by the +\verb|text| parameter and is processed in LR-mode. The \verb|position| +parameter defines the horizontal position of the comment relative to +its instance. Valid values of \verb|position| are \verb|l| (left), +\verb|r| (right), or any \LaTeX{} length. Its default value +is~\verb|l|. If the value of \verb|position| is \verb|l| +(or~\verb|r|), the comment will be placed \verb|\msccommentdist| units +to the left (or right) of the \verb|instname| instance. If +\verb|position| is a \LaTeX{} length, the comment will be placed +\verb|position| units from the \verb|instname| instance. A negative +length puts the comment to the left and a positive length puts the +comment to the right of the instance. + +The following diagram shows how to use comments. In this diagram, the +distance between the frame and the instances (\verb|\envinstdist|) is +doubled in order to fit the comments inside the frame. + +\medskip +\begin{minipage}[c]{0.4\linewidth} +\setmscvalues{small} +\begin{msc}{comments} +\setlength{\envinstdist}{2\envinstdist} +\declinst{i}{}{i} +\declinst{j}{}{j} +\mess{a}{i}{j}[2] +\msccomment{start}{i} +\nextlevel[2] +\msccomment[r]{end}{j} +\nextlevel +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.54\linewidth} +{\small +\begin{verbatim} +\setlength{\envinstdist}{2\envinstdist} +\declinst{i}{}{i} +\declinst{j}{}{j} +\mess{a}{i}{j}[2] +\msccomment{start}{i} +\nextlevel[2] +\msccomment[r]{end}{j} +\nextlevel +\end{verbatim} +} +\end{minipage} + + + + +\subsection{Actions} +\label{actions} +An instance can perform an action, which is denoted by a rectangle. + +\begin{verbatim} +\action{name}{instance} +\end{verbatim} + +The action is attached at the current level to the \verb+instance+. +The \verb+name+ is centered inside the action symbol and is processed +in LR-mode. + +The following parameters determine the detailed drawing of the action +symbol (see Section~\ref{parameters}): +\verb+\actionwidth+ (the width of the action symbol), and +\verb+\actionheight+ (the height of the action symbol). + +The next example shows that after an action often a multiple level +increment is needed to obtain nice pictures. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{action} +\setmscvalues{small} +%\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\declinst{j}{}{j} + +\mess{a}{j}{i} +\nextlevel +\action{doit}{i} +\nextlevel[2] +\mess{b}{i}{j} + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\small +\begin{verbatim} +\mess{a}{j}{i} +\nextlevel +\action{doit}{i} +\nextlevel[2] +\mess{b}{i}{j} +\end{verbatim} +} +\end{minipage} + + +\subsection{Timers} +\label{timers} +There are five commands to draw timer events. +\begin{verbatim} +\settimer[placement]{name}{instance} +\timeout[placement]{name}{instance} +\stoptimer[placement]{name}{instance} +\settimeout[placement]{name}{instance}[offset] +\setstoptimer[placement]{name}{instance}[offset] +\end{verbatim} + +Setting of a timer is drawn as a line connecting the \verb+instance+ +to the {\em hour glass} symbol. The \verb+name+ is put near this +symbol. A time-out is represented by an arrow from an +{\em hour glass} symbol to the \verb+instance+. Stopping a timer is +drawn as a line connecting the \verb+instance+ with the timer stop +symbol (denoted by a cross). +The command \verb+\settimeout+ is a combination of the setting of a +timer and a time out. The \verb+offset+ denotes the number of levels +between the two events. The default value for \verb+offset+ is 2. +Likewise, \verb+\setstoptimer+ is a combination +of the setting of a timer and stopping a timer. + +The optional argument \verb+placement+ can have values +\verb+l+ (meaning that the timer is drawn left of the instance axis) +and \verb+r+ (meaning that the timer is drawn right of the instance +axis). By default it is drawn at the left side of the instance. + +Several parameters can be used to control the detailed layout of timer +symbols (see Section~\ref{parameters}): +\verb+\timerwidth+ (the width of the hour glass and time out symbols), +\verb+\selfmesswidth+ (the length of the arm between the symbol +and the instance axis), and +\verb+\labeldist+ (the distance between the name and the timersymbol). +Furthermore, the size of the arrow head can be controlled with the +command \verb+\messarrowscale{size}+. + +The various timer symbols are shown in the following example. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{timers} +\setmscvalues{small} +\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} + +\settimer{T,50}{j} +\setstoptimer[r]{V}{k}[6] +\nextlevel[2] +\timeout{T}{j} +\settimeout{U}{i} +\nextlevel[2] +\settimer[r]{T,20}{j} +\nextlevel[2] +\stoptimer[r]{T}{j} + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\small +\begin{verbatim} +\settimer{T,50}{j} +\setstoptimer[r]{V}{k}[6] +\nextlevel[2] +\timeout{T}{j} +\settimeout{U}{i} +\nextlevel[2] +\settimer[r]{T,20}{j} +\nextlevel[2] +\stoptimer[r]{T}{j} +\end{verbatim} +} +\end{minipage} + +\subsection{Time measurements} +\label{measurements} +There are several commands to add time measurements to an \MSC{}. + +\begin{verbatim} +\mscmark[placement]{name}{instance} +\measure(*)[placement]{name}{instance1}{instance2}[offset] +\measurestart(*)[placement]{name}{instance}{gate} +\measureend(*)[placement]{name}{instance}{gate} +\end{verbatim} + +An absolute time stamp is attached to an event on an \verb+instance+ +with the command +\verb+mscmark+. The \verb+name+ is the text attached to the mark symbol, +which is a dashed polyline. +The position of the mark symbol relative to the marked event is +determined by the \verb+placement+. +(\verb+tl+ means top-left, \verb+tr+ means top-right, \verb+ml+ means +middle-left, \verb+mr+ means middle-right, +\verb+bl+ means bottom-left, and \verb+br+ means bottom-right). + +A \verb+\measure+ connects two events from \verb+instance1+ and +\verb+instance2+. The first event is at the current level. The second +event is \verb+offset+ levels lower than the first event. The +\verb+name+ is attached to the measure symbol. The measure symbol can +be placed at the left or at the right of \verb+instance1+. This is +controlled by the optional argument \verb+placement+, which can have +values \verb+l+ and \verb+r+. + +In case the two events are far apart, the measure may be split in two +parts. The first part is drawn with the \verb+\measurestart+ command +and the second part with the \verb+\measureend+ command. The points +where these two parts should be connected are drawn by a small circle, +to which the text \verb+gate+ is attached. + +There are two equivalent forms of the measurement symbol. The first +form, where the arrow heads are at the inside of the measured +interval, is the default form. The second form, where the arrow heads +are at the outside of the measured interval, is obtained by the +commands \verb+\measure*+, \verb+\measurestart*+, and +\verb+\measureend*+. + + +Several parameters can be used to control the detailed layout of the +time measurement symbols (see Section~\ref{parameters}): +\verb+\labeldist+ (a parameter to specify the distance between the +label of a measurement and the measurement symbol), +\verb+\messarrowscale{size}+ (a command to set the size of the arrow +head), +\verb+\selfmesswidth+ (specifies the width of the measurement +symbols). + +The following example illustrates marks and measurements in an \MSC{}. In +order to include the marks inside the frame of the diagram, the +distance between the frame and the instances (called +\verb+\envinstdist+) is increased (before the instances are declared). + +\medskip + +\begin{minipage}[c]{0.5\linewidth} +\begin{msc}{Time measurements} +\setmscvalues{small} +\setlength{\envinstdist} + {2\envinstdist} + +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} + +\mess{m1}{i}{j}[1] +\mscmark{t=0.0}{i} +\measure{0.6}{i}{j}[4] +\nextlevel +\mscmark[tr]{t=0.3}{j} +\nextlevel[3] +\mess{m2}{j}{k} +\measurestart*[r]{0.2}{k}{g} +\nextlevel[6] +\mess{m3}{k}{i} +\mscmark[bl]{t=1.0}{i} +\measureend*[r]{0.2}{k}{g} +\nextlevel +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.44\linewidth} +{\small +\begin{verbatim} +\setlength{\envinstdist} + {2\envinstdist} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\mess{m1}{i}{j}[1] +\mscmark{t=0.0}{i} +\measure{0.6}{i}{j}[4] +\nextlevel +\mscmark[tr]{t=0.3}{j} +\nextlevel[3] +\mess{m2}{j}{k} +\measurestart*[r]{0.2}{k}{g} +\nextlevel[6] +\mess{m3}{k}{i} +\mscmark[bl]{t=1.0}{i} +\measureend*[r]{0.2}{k}{g} +\nextlevel +\end{verbatim} +} +\end{minipage} + + +\subsection{Lost and found messages} +\label{lostfound} +A lost message is denoted by an arrow starting at an instance and +ending at a filled circle. A found message is denoted by an arrow +starting at an open circle and ending at an instance. + +The following commands are used to define lost and found messages. +\begin{verbatim} +\lost[pos]{name}[labelpos]{gate}{instance}[placement] +\found[pos]{name}[labelpos]{gate}{instance}[placement] +\end{verbatim} + +The argument \verb+instance+ determines the instance to which the +arrow is attached. The \verb+name+ of the message is put above the +message arrow. The \verb+gate+ is a text associated to the circle. +The optional arguments \verb+pos+, \verb+labelpos+, and +\verb+placement+ have the same function as in the \verb+\mess+ command +(Section~\ref{messages}). That is, \verb+pos+ controls the placement +of the lost or or found message with respect to the instance +axis. Valid values are \verb+l+ (left) and~\verb+r+ (right). The +default value is~\verb+l+. The optional parameters \verb+labelpos+ +and \verb+placement+ control the placement of \verb+name+ with respect +to the message arrow. Valid values for \verb+labelpos+ are \verb+t+ +(on top) and~\verb+b+ (below). The default value is~\verb+t+. Valid +values for \verb+placement+ are real numbers in the closed interval +$[0,1]$ and denote the relative distance of the message label +\verb+name+ to the beginning of the arrow. The default value for +\verb+placement+ is~$0.5$. + +Several parameters can be used to control the detailed layout of lost +and found messages (see Section~\ref{parameters}): +\verb+\lostsymbolradius+ (the radius of the circle), +\verb+\selfmesswidth+ (the length of the arrow), and +\verb+\labeldist+ (the distance between the name and the arrow). +Furthermore, the size of the arrow head can be controlled with the +command \verb+\messarrowscale{size}+. + +The following example shows a found and a lost message. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{lost and found} +\setmscvalues{small} +\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\declinst{j}{}{j} + +\found{m}{g}{i} +\nextlevel +\mess{p}{i}{j} +\nextlevel +\lost[r]{n}{}{j} + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\small +\begin{verbatim} +\found{m}{g}{i} +\nextlevel +\mess{p}{i}{j} +\nextlevel +\lost[r]{n}{}{j} +\end{verbatim} +} +\end{minipage} + + + +\subsection{Conditions} +\label{conditions} +A condition is denoted by a hexagon. It is used to express that the +system has entered a certain state. A condition relates to a number of +instances. All conditions which take part in the condition are covered +by the condition symbol. The other instances are drawn through the +condition symbol. +The following command is used to draw a condition. + +\begin{verbatim} +\condition{text}{instancelist} +\end{verbatim} + +The \verb+text+ is placed in the center of the condition. The +\verb+instancelist+ expresses which instances take part in the +condition. It is a list of nicknames of instances, separated by +commas. Take care not to add extra white space around the nicknames, +since this is considered part of the nickname in \LaTeX. +The order in which the instances are listed is immaterial. + +There are two parameters which control the shape of the condition +symbol (see Section~\ref{parameters}): +\verb+\conditionheight+ (the height of the condition symbol), and +\verb+\conditionoverlap+ (the width of the part of the condition +symbol which extends over the rightmost/leftmost contained instance +axis). + +The following example contains some conditions. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{conditions} +\setmscvalues{small} +\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} + +\condition{some condition}{i,k} +\nextlevel[3] +\mess{m}{i}{j} +\action{a}{k} +\nextlevel +\condition{C}{i} +\nextlevel[2] +\condition{A, B, C}{i,j,k} +\nextlevel[2] + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\small +\begin{verbatim} +\condition{some condition}{i,k} +\nextlevel[3] +\mess{m}{i}{j} +\action{a}{k} +\nextlevel +\condition{C}{i} +\nextlevel[2] +\condition{A, B, C}{i,j,k} +\nextlevel[2] +\end{verbatim} +} +\end{minipage} + +\subsection{Generalized ordering} +\label{ordering} +A generalized order is treated much like a regular message (see +Section~\ref{messages}). There +are three differences: a generalized order is drawn with a +dotted line, it has no label, and the arrow head is in the middle of +the line. A generalized order is defined with the following command. +\begin{verbatim} +\order[pos]{sender}{receiver}[leveloffset] +\end{verbatim} +The \verb+sender+ and \verb+receiver+ are the nicknames of the +instances which are connected by the generalized ordering symbol. +At the \verb+receiver+ instance, the generalized ordering symbol ends +at the current level plus the \verb+leveloffset+. The +\verb+leveloffset+ is an optional integer value, with default 0. + +In case \verb+sender+ and \verb+receiver+ denote the same instance, +the order is a \emph{self order}. The placement of the order arrow of +a self order is controlled by the optional argument \verb+pos+. It +can have values \verb+l+ (meaning that the ordering symbol is drawn +left of the instance axis) and \verb+r+ (meaning that the ordering +symbol is drawn right of the instance axis). By default it is drawn at +the left side of the instance. For non-self orders, the \verb+pos+ +argument is ignored. + +Additionally, there are two ways to control the shape +of the generalized ordering symbol (see Section~\ref{parameters}). +These are: +\verb+\selfmesswidth+ (a parameter to specify the width of the polyline used for +drawing orderings on a single instance axis). +and +\verb+\messarrowscale{size}+ (a command to set the size of the arrow +head in the ordering symbol). + +Orderings to or from the environment (i.e.\ the left or the right side +of the \MSC{} frame) can be +specified by setting the sender or the receiver argument to the value +\verb+envleft+ or \verb+envright+. + +An example of a generalized order is given in the following diagram. + + + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{generalized order} +\setmscvalues{normal} +\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\declinst{j}{}{j} + +\mess{m}{envleft}{i} +\order{i}{j}[1] +\nextlevel +\mess{k}{j}{envright} +\nextlevel +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\small +\begin{verbatim} +\mess{m}{envleft}{i} +\order{i}{j}[1] +\nextlevel +\mess{k}{j}{envright} +\end{verbatim} +} +\end{minipage} + + +\subsection{Instance regions} +\label{regions} +A part of the instance axis can be drawn in a different style. Such a +part is called an {\em instance region}. The following +regions are supported: +{\em coregion} (the instance axis is dashed, which means that the order of the +attached instances is immaterial), +{\em suspension region} (a small rectangle with dashed left and right +sides, which denotes that the instance is suspended), +{\em activation region} (a small filled rectangle, which denotes that +the instance has control). + +The following commands are used to draw an instance region. + +\begin{verbatim} +\regionstart{type}{instname} +\regionend{instname} +\end{verbatim} + +If the \verb+\regionstart+ command is used the instance axis of +\verb+instname+ is drawn in the shape determined by \verb+type+, +starting from the current level. The type can have values +\verb+coregion+, \verb+suspension+, and \verb+activation+. + +The shape of an instance region can be controlled with the following +parameters (see Section~\ref{parameters}): +\verb+\regionbarwidth+ (the width of the coregion start and end +symbol), +\verb+\instwidth+ (the width of the fat instance rectangle), +\verb+\regionwidth+ (the width of the activation and suspension rectangle). + +In the following example, several instance regions are demonstrated. +Notice the relative order of \verb|\mess|, \verb|\regionstart|, and +\verb|\regionend| commands. Interchanging lines +\verb|\regionstart{activation}{i}| and \verb|\mess{q}{j}{i}| makes the +arrow head of the~`q' message partly invisible. Also note that the +second activation region on~$i$ ends with a method reply +(which is produced by the command \cmd{mess*}). + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{regions} +\setmscvalues{small} +\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} + +\regionstart{activation}{i} +\nextlevel[3] +\regionend{i} +\mess{m}{i}{j} +\nextlevel +\regionstart{coregion}{j} +\nextlevel +\regionstart{suspension}{k} +\mess{p}{j}{k} +\nextlevel +\regionstart{activation}{i} +\mess{q}{j}{i} +\nextlevel +\regionend{j} +\nextlevel[3] +\regionend{i} +\mess*{r}{i}{j} +\nextlevel +\mess{s}{j}{k} +\regionend{k} +\nextlevel +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\scriptsize +\begin{verbatim} +\regionstart{activation}{i} +\nextlevel[3] +\regionend{i} +\mess{m}{i}{j} +\nextlevel +\regionstart{coregion}{j} +\nextlevel +\regionstart{suspension}{k} +\mess{p}{j}{k} +\nextlevel +\regionstart{activation}{i} +\mess{q}{j}{i} +\nextlevel +\regionend{j} +\nextlevel[3] +\regionend{i} +\mess*{r}{i}{j} +\nextlevel +\mess{s}{j}{k} +\regionend{k} +\nextlevel +\end{verbatim} +} +\end{minipage} + +In some situations, the gray-colored activation regions can hide +message-labels. \emph{Level back-up} can help in these situations, see +the \emph{Tricks} section in the reference manual~\cite{BM02}. + +\subsection{Instance creation and instance stop} +\label{createstop} +The \MSC{} language offers constructs for dynamic instance creation and +instance destruction. +An instance can dynamically create another instance by issuing a +create command. An instance creation is drawn as a dashed message +arrow. At the side of the arrow head, the instance head symbol for the +created instance is drawn. +An instance end symbol does not denote the end of the specified +process, but merely the end of its current description. Therefore, a +different symbol is needed which denotes that an instance stops before +the end of the \MSC{} in which it is contained. +The instance stop symbol is a cross. + +The following commands are used for instance creation and instance +stop. + +\begin{verbatim} +\dummyinst{createdinst} +\create{name} + [labelpos] + {creator} + [placement] + {createdinst} + {instancenameabove} + {instancenamewithin} +\stop{instance} +\end{verbatim} + +In order to reserve space for an instance which will be created +dynamically, the command \verb+dummyinst+ must be used. This command +is mixed with the declarations of normal instances (see the +\verb+declinst+ command, Section~\ref{instances}). +The argument \verb+createdinst+ is the nickname of the instance that +will be created later. + +An instance can be created with the \verb+\create+ command. +This command results in a dashed horizontal message arrow labeled with +\verb+name+. The arrow starts at the current level at the instance +with nickname \verb+creator+ and ends at the current level at the +instance head of the instance with nickname \verb+createdinst+. This +instance must have been declared first with the \verb+dummyinst+ +command. +The name of the created instance consists of two parts. The part +called \verb+instancenameabove+ is placed above the instance head and the +\verb+instancenamewithin+ is centered within the instance head. + +As with normal messages, placement of the message label is controlled +by the optional parameters \verb+labelpos+ and \verb+placement+. That +is, \verb+labelpos+ denotes the relative position of the message label +with respect to the message arrow. Valid values are \verb+t+ (on top) +and \verb+b+ (below). The default value is \verb+t+. The optional +parameter \verb+placement+ denotes the relative distance of the +message label with respect to the beginning of the arrow. Valid values +are real numbers in the closed interval $[0,1]$. The default value +is~$0.5$. See Figure~\ref{fig:refpoints} +(page~\pageref{fig:refpoints}) and its description in +Section~\ref{messages} for more information on the placement of +message labels. + +An instance is stopped with the \verb+\stop+ command. +The \verb+instance+ is the nickname of the stopped instance. The +instance axis is not drawn any further below the level at which the +\verb+\stop+ command is issued. Also, the instance foot symbol is not +drawn. + +The size of the stop symbol is determined by the parameter +\verb+\stopwidth+ (see Section~\ref{parameters}). +The following parameters apply to the instance head symbol: +\verb+\instheadheight+ (the height of the instance head symbol), +\verb+\instwidth+ (the width of the instance head symbol), +and +\verb+\labeldist+ (the distance between the instance head symbol and +the part of the instance name drawn above the head symbol). + +Take care not to specify any events on an instance which has not yet +been created or which has already +been stopped. This may lead to unexpected drawings. +However, it is possible to create an instance after it has stopped, +as showed in the next example. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{dynamic instances} +\setmscvalues{small} +\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\dummyinst{j} +\declinst{k}{}{k} + +\mess{p}{i}{k} +\nextlevel[3] +\create{kick}{k}{j}{}{j} +\nextlevel +\stop{k} +\nextlevel +\mess{ok}{j}{i} +\nextlevel +\stop{j} +\nextlevel[2] +\create{start}[b]{i}[.75]{k}{}{again} +\nextlevel[2] + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\small +\begin{verbatim} +\declinst{i}{}{i} +\dummyinst{j} +\declinst{k}{}{k} + +\mess{p}{i}{k} +\nextlevel[3] +\create{kick}{k}{j}{}{j} +\nextlevel +\stop{k} +\nextlevel +\mess{ok}{j}{i} +\nextlevel +\stop{j} +\nextlevel[2] +\create{start}[b]{i}[.75]{k}{}{again} +\nextlevel[2] +\end{verbatim} +} +\end{minipage} + +\subsection{\MSC{} references} +\label{references} +Within an \MSC{} a reference to other \MSC{}s can be included. Such a +reference is drawn as a rectangle with rounded corners, covering part +of the \MSC{}. The following commands are used to draw \MSC{} references. + +\begin{verbatim} +\referencestart[lo][ro]{nickname}{text}{leftinstance}{rightinstance} +\referenceend{nickname} +\end{verbatim} + +The reference symbol starts at the level where the +\verb+\referencestart+ command is used, and ends at the level where +the corresponding \verb+\referenceend+ command occurs. These commands +correspond if they have the same \verb+nickname+. The \verb+text+ is +placed in the center of the reference symbol. The reference covers all +instances from \verb+leftinstance+ to \verb+rightinstance+. The +distance between the left (right) edge of the reference symbol and the +leftmost (rightmost) covered instance axis is defined by the optional +overlap value \verb+lo+. The default value for \verb+lo+ in large/normal/small +\MSC{}s is 1.5/1/0.75 (see Section~\ref{parameters} for selecting +large, normal or small drawing mode). If the second optional value +\verb+ro+ is present too, the optional value \verb+lo+ defines the left +overlap and the optional value \verb+ro+ defines the right overlap. + +The left and right edge of the reference symbol are +\verb+nicknameleft+ and \verb+nicknameright+, where \verb+nickname+ is +the nickname of the \MSC{} reference as defined in the +\verb+\referencestart+ command. +These names can be used at every place where the nickname of an +instance is required, e.g.\ as the sender or receiver of a message. +This is shown in the following example. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{references} +\setmscvalues{small} +\setlength{\topheaddist}{0.8cm} + +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} + +\mess{a}{j}{k} +\nextlevel +\referencestart{r}{a reference}{i}{j} +\nextlevel +\mess{b}{rright}{k} +\nextlevel +\referenceend{r} +\nextlevel +\referencestart{p}{another reference}{i}{k} +\nextlevel +\mess{c}{envright}{pright} +\nextlevel[3] +\referenceend{p} + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.55\linewidth} +{\small +\begin{verbatim} +\mess{a}{j}{k} +\nextlevel +\referencestart{r}{a reference}{i}{j} +\nextlevel +\mess{b}{rright}{k} +\nextlevel +\referenceend{r} +\nextlevel +\referencestart{p}{another reference}{i}{k} +\nextlevel +\mess{c}{envright}{pright} +\nextlevel[3] +\referenceend{p} +\end{verbatim} +} +\end{minipage} + +\subsection{Inline expressions} +\label{inlines} +An inline expression is a part of an \MSC{} on which an operation is +defined. A rectangle surrounds the part of the \MSC{} containing the +operands. The operands are separated by horizontal dashed lines. +The operator is placed in the upper left corner of the inline +expression symbol. +The following commands are used to draw inline expressions. + +\begin{verbatim} +\inlinestart[lo][ro]{nickname}{operator}{leftinstance}{rightinstance} +\inlineseparator{nickname} +\inlineend(*){nickname} +\end{verbatim} + +The inline expression starts at the level where the \verb+\inlinestart+ +command occurs. The inline expression spans over the instances from +\verb+leftinstance+ to \verb+rightinstance+. The \verb+operand+ is +placed in the upper left corner of the rectangle. At every level where +a corresponding \verb+\inlineseparator+ command occurs, a dashed line +is drawn. The inline expression ends at the level where the +\verb+\inlineend+ command occurs. The \verb+nickname+ is used to match +corresponding commands. +The command \verb+\inlineend*+ does the same as the command +\verb+\inlineend+, except that the bottom line of the rectangle is +dashed. This is used to indicate that the operand is optional. + +The left and right edge of the inline expression symbol are named +\verb+nicknameleft+ and \verb+nicknameright+, where \verb+nickname+ is +the nickname of the inline expression as defined in the +\verb+\inlinestart+ command. +These names can be used at every place where the nickname of an +instance is required, e.g.\ as the sender or receiver of a message. + +The distance between the left (right) edge of the inline expression +symbol and +the leftmost (rightmost) included instance axis is defined by +the optional overlap value \verb+lo+. The default value for +large/normal/small \MSC{}s is +1.5/1/0.75 (see Section~\ref{parameters} for selecting large, normal or small +drawing mode). +If the second optional value +\verb+ro+ is present too, the optional value \verb+lo+ defines the left +overlap and the optional value \verb+ro+ defines the right overlap. +These options make it possible to easily draw nested inline expressions +as in the following example. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{inline expressions} +\setmscvalues{small} +\setlength{\topheaddist}{0.8cm} + + +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} + + +\inlinestart{exp1}{par}{i}{k} +\nextlevel +\mess{a}{k}{j} +\nextlevel +\inlinestart[0.6cm]{exp2}{alt}{i}{j} +\nextlevel[2] +\mess{b}{j}{i} +\nextlevel +\inlineseparator{exp2} +\nextlevel +\mess{c}{j}{i} +\nextlevel +\inlineend{exp2} +\nextlevel +\inlineseparator{exp1} +\nextlevel +\mess{d}{j}{k} +\nextlevel +\inlineend{exp1} +\nextlevel +\inlinestart{exp3}{opt}{i}{j} +\nextlevel +\mess{e}{envright}{exp3right} +\mess{e}{exp3right}{j} +\nextlevel +\mess{f}{j}{i} +\nextlevel +\inlineend*{exp3} + + +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\scriptsize +\begin{verbatim} +\inlinestart{exp1}{par}{i}{k} +\nextlevel +\mess{a}{k}{j} +\nextlevel +\inlinestart[0.6cm]{exp2}{alt}{i}{j} +\nextlevel[2] +\mess{b}{j}{i} +\nextlevel +\inlineseparator{exp2} +\nextlevel +\mess{c}{j}{i} +\nextlevel +\inlineend{exp2} +\nextlevel +\inlineseparator{exp1} +\nextlevel +\mess{d}{j}{k} +\nextlevel +\inlineend{exp1} +\nextlevel +\inlinestart{exp3}{opt}{i}{j} +\nextlevel +\mess{e}{envright}{exp3right} +\mess{e}{exp3right}{j} +\nextlevel +\mess{f}{j}{i} +\nextlevel +\inlineend*{exp3} +\end{verbatim} +} +\end{minipage} + +\subsection{Gates} +\label{gates} + +A gate determines a connection point for messages. + +The following command can be used to draw gates. + +\begin{verbatim} +\gate(*)[hpos][vpos]{gatename}{instname} +\end{verbatim} + +The unstarred version produces a normal (invisible) gate. The starred +version produces a visible gate (a small dot). The gate is drawn at the +current level at the instance \verb+instname+ (which can also be the +left and right edge of e.g.\ an \MSC{} reference). The +\verb+gatename+ is attached to the gate. The positioning of the +\verb+gatename+ relative to the gate is determined by the values of +\verb+hpos+ (horizontal position) and \verb+vpos+ (vertical position). +Possible values for \verb+hpos+ are \verb+l+ (left, default) and +\verb+right+ (right). Possible values for \verb+vpos+ are \verb+t+ +(top, default), \verb+c+ (center), and \verb+b+ (bottom). + +There are several parameters to control the size and shape of the +gate symbol (see Section~\ref{parameters}). These are +\verb+\gatesymbolradius+ (sets the radius of the gate symbol), +\verb+\labeldist+ (the vertical distance between the gate name and +the gate). + +The next example shows a number of gates. + +\medskip + +\begin{minipage}[c]{0.4\linewidth} +\begin{msc}{gates} +\setmscvalues{small} + +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\referencestart{r}{ref}{i}{j} +\nextlevel +\gate{$g$}{rright} +\mess{b}{rright}{envright} +\gate[r][c]{$h$}{envright} +\nextlevel +\nextlevel +\mess{c}{rright}{k} +\gate*[l][b]{$h'$}{rright} +\nextlevel[2] +\referenceend{r} +\end{msc} +\end{minipage} +% +\begin{minipage}[c]{0.5\linewidth} +{\footnotesize +\begin{verbatim} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\referencestart{r}{ref}{i}{j} +\nextlevel +\gate{$g$}{rright} +\mess{b}{rright}{envright} +\gate[r][c]{$h$}{envright} +\nextlevel +\nextlevel +\mess{c}{rright}{k} +\gate*[l][b]{$h'$}{rright} +\nextlevel[2] +\referenceend{r} +\end{verbatim} +} +\end{minipage} + + +\subsection{High-level \MSC{}s} +\label{hmsc} +A High-level \MSC{} (\HMSC{}) is a drawing which defines the relation between +a number of \MSC{}s. It is composed of a start symbol (an upside down +triangle), a number of end symbols (represented by triangles), a +number of \MSC{} references (these are rectangles with rounded corners), +a number of conditions (hexagons) and possibly several connection +points (circles). These symbols are connected by arrows. + +The following commands can be used to draw \HMSC{}s. + +\begin{verbatim} +\begin{hmsc}[headerpos]{hmscname}(llx,lly)(urx,ury) +\end{hmsc} +\hmscstartsymbol{nickname}(x,y) +\hmscendsymbol{nickname}(x,y) +\hmscreference{nickname}{text}(x,y) +\hmsccondition{nickname}{text}(x,y) +\hmscconnection{nickname}(x,y) +\arrow{from-nickname}[coord-list]{to-nickname} +\end{verbatim} + +In order to draw \HMSC{}s, a new environment is defined, which is called +\verb+hmsc+. The command to begin this environment has several +arguments. The argument \verb+headerpos+ is optional. It controls +positioning of the header of the \HMSC{}. This argument can have values +\verb+l+ (for a left aligned header), \verb+c+ (for a centered header) +and \verb+r+ (for a right aligned header). The header of an \HMSC{} is +formed from the keyword \verb+msc+, followed by the +\verb+hmscname+. The size of the \HMSC{} frame is determined by the +coordinates of the lower-left corner, \verb+(llx,lly)+, and the +coordinates of the upper-right corner, \verb+(urx,ury)+. + +The \HMSC{} grid is not drawn, but used to control the positioning of the +\HMSC{} symbols (\verb+startsymbol+, \verb+endsymbol+, \verb+reference+, +\verb+condition+, and \verb+connection+). +The center of each symbol is drawn on the grid point +with coordinates \verb+{x,y}+. Each symbol also has a \verb+nickname+ +for later reference. + +\HMSC{} symbols can be connected by means of the \verb+arrow+ command. +This draws an arrow from the symbol with nickname \verb+from-nickname+ +to the symbol with nickname \verb+to-nickname+. The optional argument +\verb+coord-list+ can be used if the line connecting the source and +the destination should not be straight. The \verb+coord-list+ has +the following syntax: \verb+(x1,y1)(x2,y2)...(xk,yk)+. This means +that the connecting line goes through the points with coordinates +(x1,y1), (x2,y2), \ldots, (xk,yk). + +Arrows always leave the start symbol at the bottom. They enter the end symbol +at the top. +Arrows start and end either at the middle of the top or at the middle +of the bottom of a reference and condition symbol. The incoming +(outgoing) direction of the arrow determines whether it will start +(end) at the top or at the bottom. + +There are several parameters to control the size and shape of the +symbols (see Section~\ref{parameters}). These are +\verb+\hmscconditionheight+ (the height of the condition symbol), +\verb+\hmscconditionwidth+ (the width of the condition symbol, +excluding the left and right angular parts), +\verb+\hmscreferenceheight+ (the height of the reference symbol), +\verb+\hmscreferencewidth+ (the width of the reference symbol), +\verb+\messarrowscale{size}+ (a command to set the size of the arrow +head of a connection line); +\verb+setconnectiontype(type)+ (set the shape of the polyline +connection the symbols; \verb+type+ can be \verb+straight+, +\verb+rounded+, and \verb+curved+), +\verb+\startsymbolwidth+ (the width of the start and end symbol), +\verb+\topnamedist+ (sets the distance between the top of the \HMSC{} frame +and the \HMSC{} header). + +An example of an \HMSC{} is in the following diagram. Notice that the +width and height of reference symbols are changed locally (i.e., +between \verb+{+ and \verb+}+ braces) just before the big +reference~\verb+b+ is defined. + +\medskip + +\noindent +\begin{minipage}[c]{0.375\linewidth} + +\begin{hmsc}{High level}(-3,0)(3,12) +\hmscstartsymbol{s}(0,10) +\hmscreference{a}{A}(0,9) +\hmscconnection{c}(0,7.5) +{ +\setlength{\hmscreferencewidth}{2cm} +\setlength{\hmscreferenceheight}{3\baselineskip} +\hmscreference{b}{\parbox{1.9cm} + {\centering + this is a big + hmsc reference} + }(0,6) +} +\hmsccondition{t}{Again}(1,4.25) +\hmsccondition{ok}{Ok}(0,3.5) +\hmsccondition{q}{\textit{Break}}(-2,3.5) +\hmscendsymbol{e1}(-2,2) +\hmscreference{do}{Do it!}(0,2) +\hmscendsymbol{e2}(0,1) + +\arrow{s}{a} +\arrow{a}{c} +\arrow{c}{b} +\arrow{c}[(-2,7.5)]{q} +\arrow{b}{q} +\arrow{q}{e1} +\arrow{b}{ok} +\arrow{ok}{do} +\arrow{do}{e2} +\arrow{b}{t} +\arrow{t}[(1,3.5)(2.5,3.5)(2.5,7.5)]{c} +\end{hmsc} +\end{minipage}\hfill +\begin{minipage}[c]{0.6\linewidth} +{\footnotesize +\begin{verbatim} +\begin{hmsc}{High level}(-3,0)(3,12) +\hmscstartsymbol{s}(0,10) +\hmscreference{a}{A}(0,9) +\hmscconnection{c}(0,7.5) +{\setlength{\hmscreferencewidth}{2cm} + \setlength{\hmscreferenceheight} + {3\baselineskip} + \hmscreference{b}{\parbox{1.9cm} + {\centering this is a big hmsc reference} + }(0,6)} +\hmsccondition{t}{Again}(1,4.5) +\hmsccondition{ok}{Ok}(0,3.5) +\hmsccondition{q}{\textit{Break}}(-2,3.5) +\hmscendsymbol{e1}(-2,2) +\hmscreference{do}{Do it!}(0,2) +\hmscendsymbol{e2}(0,1) +\arrow{s}{a} +\arrow{a}{c} +\arrow{c}{b} +\arrow{c}[(-2,7.5)]{q} +\arrow{b}{q} +\arrow{q}{e1} +\arrow{b}{ok} +\arrow{ok}{do} +\arrow{do}{e2} +\arrow{b}{t} +\arrow{t}[(1,3.5)(2.5,3.5)(2.5,7.5)]{c} +\end{hmsc} +\end{verbatim} +} +\end{minipage} + + +\subsection{\MSC{} documents} +\label{mscdoc} +An \MSCdoc{} is a drawing which contains various declarations +of objects used in the \MSC{} description. For drawing \MSCdoc{}s +he following commands are provided. + +\begin{verbatim} +\begin{mscdoc}[headerpos]{mscdocname}{text}(llx,lly)(urx,ury) +\end{mscdoc} +\reference{text}(x,y) +\separator{y} +\end{verbatim} + +As for \MSC{} and \HMSC{}, a new environment is defined, which is named +\verb+mscdoc+. The command to begin an \MSCdoc{} has several +arguments. The argument \verb+headerpos+ is optional. It controls +positioning of the header of the \MSCdoc{}. +This argument can have values +\verb+l+ (for a left aligned header), \verb+c+ (for a centered header) +and \verb+r+ (for a right aligned header). +The header of an \MSCdoc{} is formed from the keyword \verb+mscdocument+, +followed by the \verb+mscdocname+. +The \verb+text+ is placed left-aligned below the \MSCdoc{} header. +The size of the \MSCdoc{} frame is determined by +coordinates of the lower-left corner, \verb+(llx,lly)+, and the +coordinates of the upper-right corner, \verb+(urx,ury)+. + +The \MSCdoc{} grid is not drawn, but used to control the positioning of the +\MSC{} references. +The center of such a reference is drawn on the grid point +with coordinates \verb+{x,y}+. + +The \verb+separator+ command draws a dashed horizontal line. The \MSC{} +references above the separator are the exported, while the ones below +the separator are local. + +There are several parameters to control the size and shape of the +symbols (see Section~\ref{parameters}). +\verb+\mscdocreferenceheight+ (the height of the reference symbol), +\verb+\mscdocreferencewidth+ (the width of the reference symbol), +\verb+\topnamedist+ (sets the distance between the top of the \MSCdoc{} +frame and the \MSCdoc{} header). + +An example of an \MSCdoc{} is in the following diagram. Notice that +the size of references in an \MSCdoc{} had to be changed for the last +reference. + +\medskip + + +\begin{minipage}{0.4\linewidth} +\begin{mscdoc}{My declarations}% + (0,0)(6,8) +\reference{a}(1,6) +\reference{b}(3,6) +\reference{c}(1,4) +\reference{d}(3,4) +\separator{3} +\setlength{\mscdocreferencewidth}{4.5\mscunit} +\setlength{\mscdocreferenceheight}{2\baselineskip} +\reference{% + \parbox{4\mscunit}% + {\raggedright This is a + two-line reference}} + (3,1.5) +\end{mscdoc} +\end{minipage} +% +\begin{minipage}{0.5\linewidth} +{\small +\begin{verbatim} +\begin{mscdoc}{My declarations}% + (0,0)(6,8) +\reference{a}(1,6) +\reference{b}(3,6) +\reference{c}(1,4) +\reference{d}(3,4) +\separator{3} +\setlength{\mscdocreferencewidth} + {4.5\mscunit} +\setlength{\mscdocreferenceheight} + {2\baselineskip} +\reference{% + \parbox{4\mscunit}% + {\raggedright This is a + two-line reference}} + (3,1.5) +\end{mscdoc} +\end{verbatim} +} +\end{minipage} + + + +\section{Style parameters} +\label{parameters} + +By means of a collection of parameters, the graphical appearance of +an \MSC{} can be fine tuned to the user's taste. +The general parameters +are displayed in Figure~\ref{parametersfig} on page~\pageref{parametersfig}. + +%======================== +\begin{figure}[htb] +\vspace{2ex} %Needed to get enough white space before the top label of + %the figure. + +\newcommand{\printlength}[1]{\mbox{\footnotesize\ttfamily \char`\\#1}} +\begin{center} +\setmscvalues{normal} +\begin{msc}{Lengths} +\psset{linewidth=.4pt,dotsep=1pt} +\newlength{\lta} +\newlength{\ltb} +% \topnamedist +\psline[linestyle=dotted](1.5cm,-\topnamedist)(2.5cm,-\topnamedist) +\psline[arrowscale=1.3]{->}(2.5cm,.2cm)(2.5cm,0cm) +\setlength{\lta}{\topnamedist+.2cm} +\psline[arrowscale=1.3]{->}(2.5cm,-\lta)(2.5cm,-\topnamedist) +\rput[tl](2.5cm,.4cm){\printlength{topnamedist}} + +% \leftnamedist +\setlength{\lta}{\leftnamedist+10pt} +\setlength{\ltb}{\topnamedist} +\psline[linestyle=dotted,arrowscale=1.0]{->}(-10pt,-\ltb)(0,-\ltb) +\psline[linestyle=dotted,arrowscale=1.0]{->}(\lta,-\ltb)(\leftnamedist,-\ltb) +\psline[linestyle=dotted](\leftnamedist,10pt)(\leftnamedist,-\baselineskip) +\rput[br](-10pt,-\ltb){\printlength{leftnamedist}} + +% \topheaddist +\setlength{\lta}{\envinstdist+\instdist-.5\instwidth} +\psline[arrowscale=1.3,linestyle=dotted]{<->}(\lta,0cm)(\lta,-\topheaddist) +\rput[l](\lta,-.5\topheaddist){ \printlength{topheaddist}} + +% \bottomfootdist +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\lastlevelheight+\instfootheight+\levelheight*12} +\setlength{\lta}{\envinstdist+2\instdist-.5\instwidth} +\rput[tl](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\bottomfootdist)} +\setlength{\ltb}{\ltb+.5\bottomfootdist} +\rput[l](\lta,-\ltb){\printlength{bottomfootdist}} + +% \instheadheight +\setlength{\lta}{\envinstdist+2\instdist+.5\instwidth+.2cm} +\setlength{\ltb}{\topheaddist} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\instheadheight)} +\setlength{\ltb}{\ltb+.5\instheadheight} +\rput[l](\lta,-\ltb){\printlength{instheadheight}} + +% \firstlevelheight +\setlength{\lta}{\envinstdist+\instdist+.2cm} +\setlength{\ltb}{\topheaddist+\instheadheight} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,-\firstlevelheight)} +\setlength{\ltb}{\ltb+.5\firstlevelheight} +\rput[l](\lta,-\ltb){\printlength{firstlevelheight}} + +% \levelheight +\setlength{\lta}{\envinstdist+\instdist+.2cm} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\levelheight)} +\setlength{\ltb}{\ltb+.5\levelheight} +\rput[l](\lta,-\ltb){\printlength{levelheight}} + +% \actionheight +\setlength{\lta}{\envinstdist+2\instdist+0.5\actionwidth+.2cm} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*7} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\actionheight)} +\setlength{\ltb}{\ltb+.7\actionheight} +\rput[bl](\lta,-\ltb){\printlength{actionheight}} + +% \actionwidth +\setlength{\lta}{\envinstdist+2\instdist-0.5\actionwidth} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*7-.2cm} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\actionwidth,0)} +\setlength{\lta}{\lta+.5\actionwidth} +\setlength{\ltb}{\ltb-.1cm} +\rput[bl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{actionwidth}} + +% \conditionheight +\setlength{\lta}{\envinstdist+2\instdist+\conditionoverlap+0.8\conditionheight} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*10} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\conditionheight)} +\setlength{\ltb}{\ltb+.7\conditionheight} +\rput[bl](\lta,-\ltb){\printlength{conditionheight}} + +% \inlineoverlap +\setlength{\lta}{\envinstdist} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*5-.2cm} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\inlineoverlap,0)} +%\setlength{\lta}{\lta+\inlineoverlap} +\setlength{\ltb}{\ltb-.1cm} +\rput[bl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{inlineoverlap}} + +% \referenceoverlap +\setlength{\lta}{\envinstdist} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*7-.2cm} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\referenceoverlap,0)} +%\setlength{\lta}{\lta+\referenceoverlap} +\setlength{\ltb}{\ltb-.1cm} +\rput[bl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{referenceoverlap}} + +% \conditionoverlap +\setlength{\lta}{\envinstdist+2\instdist} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*10-.2cm} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\conditionoverlap,0)} +%\setlength{\lta}{\lta+\conditionoverlap} +\setlength{\ltb}{\ltb-.1cm} +\rput[bl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{conditionoverlap}} + +% \lastlevelheight +\setlength{\lta}{\envinstdist+2\instdist+.2cm} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*12} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\lastlevelheight)} +%\setlength{\ltb}{\ltb+.5\lastlevelheight} +\rput[bl](\lta,-\ltb){\printlength{lastlevelheight}} + +% \instfootheight +\setlength{\lta}{\envinstdist+2\instdist+.5\instwidth+.1cm} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*12+\lastlevelheight} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3]{->}(0,.3cm)(0,0)} +\setlength{\ltb}{\ltb+\instfootheight} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3]{->}(0,-.3cm)(0,0)} +\rput[tl](\lta,-\ltb){ \printlength{instfootheight}} + +% \selfmesswidth +\setlength{\lta}{\envinstdist-\selfmesswidth} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*2-.2cm} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\selfmesswidth,0)} +%\setlength{\lta}{\lta+\selfmesswidth} +\rput[r](\lta,-\ltb){\printlength{selfmesswidth}} + +% \regionbarwidth +\setlength{\lta}{\envinstdist+2\instdist-.5\regionbarwidth} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*2-.2cm} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\regionbarwidth,0)} +\setlength{\lta}{\lta+\regionbarwidth} +\rput[l](\lta,-\ltb){\printlength{regionbarwidth}} + +% \instwidth +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\lastlevelheight+\instfootheight+\levelheight*12+.2cm} +\setlength{\lta}{\envinstdist-0.5\instwidth} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\instwidth,0)} +\rput[tl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{instwidth}} + +% \instdist +\setlength{\lta}{\envinstdist} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+2.5\levelheight} +\rput[l](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\instdist,0)} +\setlength{\lta}{\lta+.5\instdist} +\setlength{\ltb}{\ltb-.1cm} +\rput[b](\lta,-\ltb){\printlength{instdist}} + +% \envinstwidth +\setlength{\lta}{0cm} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+.5\levelheight} +\rput[l](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\envinstdist,0)} +\rput[tl](\lta,-\ltb){ \printlength{envinstdist}} + + +% \labeldist +\setlength{\lta}{\envinstdist-.5\instwidth} +\setlength{\ltb}{\topheaddist-\labeldist} +\rput[l](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted](-.2cm,0)(.5cm,0)} +\rput[b](\lta,-\ltb){\psline[arrowscale=1.3]{->}(-.1cm,.3cm)(-.1cm,0)} +\setlength{\ltb}{\topheaddist} +\rput[l](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted](-.2cm,0)(.5cm,0)} +\rput[b](\lta,-\ltb){\psline[arrowscale=1.3]{->}(-.1cm,-.3cm)(-.1cm,0)} +\rput[tr](\lta,-\ltb){\printlength{labeldist} } + +% \timerwidth +\setlength{\lta}{\envinstdist-\selfmesswidth-0.5\timerwidth} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*4+.4cm} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\timerwidth,0)} +%\setlength{\lta}{\lta+\selfmesswidth} +\rput[r](\lta,-\ltb){\printlength{timerwidth}} + +% \stopwidth +\setlength{\lta}{\envinstdist+\instdist-0.5\stopwidth} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*4+0.5\stopwidth+.1cm} +\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\stopwidth,0)} +\setlength{\lta}{\lta+\stopwidth} +\rput[l](\lta,-\ltb){\printlength{stopwidth}} + +% \lostsymbolradius +\setlength{\lta}{\envinstdist+2\instdist+\selfmesswidth+2\lostsymbolradius+0.1cm} +\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*4} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3]{->}(0,.3cm)(0,0)} +\setlength{\ltb}{\ltb+\lostsymbolradius} +\rput[t](\lta,-\ltb){\psline[arrowscale=1.3]{->}(0,-.3cm)(0,0)} +\rput[tl](\lta,-\ltb){ \printlength{lostsymbolradius}} + +\psset{linewidth=.8pt,dotsep=3pt} + +\declinst{m1}{aname}{iname} +\declinst{st}{}{} +\declinst{m2}{}{} + +\mess{msg1}{m1}{st} +\nextlevel +\mess{msg2}{m1}{st} +\nextlevel +\mess{self}{m1}{m1} +\coregionstart{m2} +\nextlevel +\coregionend{m2} +\nextlevel +\lost[r]{x}{}{m2} +\stop{st} +\settimer{T}{m1} +\nextlevel +\inlinestart{alt}{alt}{m1}{m1} +\nextlevel[2] +\inlineend{alt} +\action{a}{m2} +\nextlevel +\referencestart{ref}{reference}{m1}{m1} +\nextlevel +\referenceend{ref} +\nextlevel +\condition{cond1}{m1,m2} +\nextlevel +\nextlevel +\mess{msg3}{m2}{m1} +\end{msc} +\end{center} + + +\caption{User controllable parameters} +\label{parametersfig} +\end{figure} + +The value of a parameter can be changed using standard +\LaTeX\ commands, e.g. +\begin{verbatim} +\setlength{\levelheight}{1cm} +\end{verbatim} + +The following list describes all parameters. +The default values for drawing \MSC{}s at large, normal and small size are +included. See the command \verb+\setmscvalues{size}+ below for +restoring the parameters to their original values. + +%======================== +\begin{defs} + +\item[\cmd{actionheight}] +Height of action symbols.\\ +(\lnsvalue{0.75}{0.6}{0.5} cm.) + +\item[\cmd{actionwidth}] +Width of action symbol.\\ +(\lnsvalue{1.25}{1.25}{1.2} cm.) + +\item[\cmd{bottomfootdist}] +Distance between bottom of foot symbol and frame.\\ +(\lnsvalue{1.0}{0.7}{0.5} cm.) + +\item[\cmd{commentdist}] +Distance between a comment and its instance.\\ +(\lnsvalue{0.5}{0.5}{0.5} cm.) + +\item[\cmd{conditionheight}] +Height of condition symbols.\\ +(\lnsvalue{0.75}{0.6}{0.5} cm.) + +\item[\cmd{conditionoverlap}] +Overlap of condition symbol.\\ +(\lnsvalue{0.6}{0.5}{0.4} cm.) + +\item[\cmd{envinstdist}] +Distance between environments and nearest instance line.\\ +(\lnsvalue{2.5}{2.0}{1.2} cm.) + +\item[\cmd{firstlevelheight}] Height of level just below head +symbols. Should not be changed inside the \MSC{} environment.\\ +(\lnsvalue{0.75}{0.6}{0.4} cm.) + +\item[\cmd{hmscconditionheight}] +Height of \HMSC{} condition symbol.\\ +(\lnsvalue{0.375}{0.3}{0.25} cm.) + +\item[\cmd{hmscconditionwidth}] +Width of \HMSC{} condition symbol.\\ +(\lnsvalue{1.0}{0.8}{0.7} cm.) + +\item[\cmd{hmscconnectionradius}] +Radius of \HMSC{} connection symbol.\\ +(\lnsvalue{0.06}{0.05}{0.04} cm.) + +\item[\cmd{hmscreferenceheight}] +Height of \HMSC{} reference symbol.\\ +(\lnsvalue{0.375}{0.3}{0.25} cm.) + +\item[\cmd{hmscreferencewidth}] +Width of \HMSC{} reference symbol.\\ +(\lnsvalue{1.0}{0.8}{0.7} cm.) + +\item[\cmd{hmscstartsymbolwidth}] +Width of \HMSC{} start symbol.\\ +(\lnsvalue{0.75}{0.6}{0.3} cm.) + +\item[\cmd{inlineoverlap}] +Overlap of inline symbol.\\ +(\lnsvalue{1.5}{1.0}{0.75} cm.) + +\item[\cmd{instbarwidth}] +Default width of vertical instance bars (applies to fat instances only).\\ +(\lnsvalue{0.0}{0.0}{0.0} cm.) + +\item[\cmd{instdist}] +Distance between instance axes.\\ +(\lnsvalue{3.0}{2.2}{1.5} cm.) + +\item[\cmd{instfootheight}] Height of foot symbols. Should not be +changed inside the \MSC{} environment.\\ +(\lnsvalue{0.25}{0.2}{0.15} cm.) + +\item[\cmd{instheadheight}] Height of head symbols. Should not be +changed inside the \MSC{} environment.\\ +(\lnsvalue{0.6}{0.55}{0.5} cm.) + +\item[\cmd{instwidth}] +Width of header and foot symbols.\\ +(\lnsvalue{1.75}{1.6}{1.2} cm.) + +\item[\cmd{labeldist}] +Distance between labels and the symbols to which they belong (for instance, message labels and arrows).\\ +(\lnsvalue{1.0}{1.0}{1.0} ex.) + +\item[\cmd{lastlevelheight}] Height of level just above foot +symbols. Should not be changed inside the \MSC{} environment.\\ +(\lnsvalue{0.5}{0.4}{0.3} cm.) + +\item[\cmd{leftnamedist}] Distance between left of the frame and +(left of) \MSC, \HMSC, or \MSCdoc{} title.\\ +(\lnsvalue{0.3}{0.2}{0.1} cm.) + +\item[\cmd{levelheight}] +Height of a level.\\ +(\lnsvalue{0.75}{0.5}{0.4} cm.) + +\item[\cmd{lostsymbolradius}] +Radius of the lost and found symbols.\\ +(\lnsvalue{0.15}{0.12}{0.08} cm.) + +\item[\cmd{markdist}] +Horizontal distance from a mark to its instance.\\ +(\lnsvalue{1.0}{1.0}{1.0} cm.) + +\item[\cmd{measuredist}] +Horizontal distance from a measure to its (closest) instance.\\ +(\lnsvalue{1.0}{1.0}{1.0} cm.) + +\item[\cmd{measuresymbolwidth}] +Width of a measure symbol.\\ +(\lnsvalue{0.75}{0.6}{0.4} cm.) + +\item[\cmd{mscdocreferenceheight}] +Height of reference symbol in an \MSCdoc.\\ +(\lnsvalue{0.375}{0.3}{0.25} cm.) + +\item[\cmd{mscdocreferencewidth}] +Width of reference symbol in an \MSCdoc.\\ +(\lnsvalue{1.0}{0.8}{0.7} cm.) + +\item[\cmd{referenceoverlap}] +Overlap of reference symbol.\\ +(\lnsvalue{1.5}{1.0}{0.75} cm.) + +\item[\cmd{regionbarwidth}] +Width of region bars.\\ +(\lnsvalue{0.5}{0.4}{0.2} cm.) + +\item[\cmd{selfmesswidth}] +Length of horizontal arms of self messages.\\ +(\lnsvalue{0.75}{0.6}{0.4} cm.) + +\item[\cmd{stopwidth}] +Width of the stop symbol.\\ +(\lnsvalue{0.6}{0.5}{0.3} cm.) + +\item[\cmd{timerwidth}] +Width of the \emph{timer} symbols.\\ +(\lnsvalue{0.4}{0.3}{0.2} cm.) + +\item[\cmd{topheaddist}] +Distance between top of head symbols and frame.\\ +(\lnsvalue{1.5}{1.3}{1.2} cm.) + +\item[\cmd{topnamedist}] Distance between top of the frame and +(top of) \MSC, \HMSC, or \MSCdoc{} title.\\ +(\lnsvalue{0.3}{0.2}{0.2} cm.) + +\end{defs} + +In addition there are several commands which allow the user to adjust +the \MSC{} drawing to his own taste. + +\begin{defs} + +\item[\cmd{messarrowscale}\{\emph{scalefactor}\}] Sets the scale +factor (a positive real number) of message arrow +heads. (\lnsvalue{2}{1.5}{1.2}) + +\item[\cmd{setmscscale}\{\emph{scalefactor}\}] Sets the scale factor +of the \MSC{} environment to \emph{scalefactor}. the scale factor is +supposed to be a real number. Scaling is done when the \MSC{} +environment ends (\verb|\end{msc}|). The default of \emph{scalefactor} +is~1. A more consistent way for +varying the size of the \MSC{} can be obtained by using the +\verb+\setmesvalues+ command as described below. +(default value 1.) + +\item[\cmd{psset}\{\texttt{linewidth=D}\}] This command sets the width +of all lines in \MSC{}s, \HMSC{}s, and \MSCdoc{}s to length \verb+D+. If +this command is issued outside the msc environment, then the value is +set for the complete document. If it is used directly after the start +of the msc environment it only holds for this \MSC{}.\\ +(large/normal/small value 0.8/0.7/0.6 pt.) + +\item[\cmd{setfootcolor}\{\emph{color}\}] Sets the color of the foot +symbols of \MSC{} instances. Possible values are \emph{black}, +\emph{white}, \emph{gray}, or \emph{lightgray}. For more color values, +see the documentation of the \LaTeXe{} \textsf{color} package. + +\end{defs} + +The following command can be used to set the above mentioned +style parameters to suitable values. + +\begin{defs} +\item[\cmd{setmscvalues}\{\emph{size}\}] Sets all parameters of the \mscpack{} to + predefined values. Valid values for \emph{size} are: +\verb|small|, \verb|normal|, and \verb|large|. +(The default value of \verb+size+ is \verb+normal+. +This can be used for drawings with at maximum six instances on a +sheet of A4 paper. +For sizes \verb+large+ and \verb+small+, a maximum of four and nine +instances respectively fit on a sheet of A4 paper.) +\end{defs} + +Caution has to be taken when changing the value of a parameter within +the \MSC{} definition. The following parameters can be changed within an +\MSC{} definition without unexpected side effects: + +\begin{flushleft} +\verb+\actionheight+, +\verb+\actionwidth+, +\verb+\bottomfootdist+, +\verb+\conditionheight+, +\verb+\conditionoverlap+, +\verb+\inlineoverlap+, +\verb+\instfootheight+, +\verb+\instwidth+ (however, this may cause different sizes of +corresponding instance header and footer symbols), +\verb+\labeldist+, +\verb+\lastlevelheight+, +\verb+\levelheight+, +\verb+\lostsymbolradius+, +\verb+\referenceoverlap+, +\verb+\regionbarwidth+, +\verb+\selfmesswidth+, +\verb+\stopwidth+, +\verb+\timerwidth+, and +\verb+\topnamedist+. +\end{flushleft} + + +In addition to the parameters specific to the \mscpack, +standard \LaTeX\ commands can be used to change the type style and +other details. +For example, if the command \verb+\sffamily+ is included directly after +the start of the msc environment, the text in the \MSC{} +is drawn using a {\sf sans serif} font. Likewise, the text size can be +changed by inserting, e.g., the command \verb+\small+. +The \verb+\raisebox+ and \verb+\parbox+ commands +can also be used to position and format names. + + +\section{Example} +\label{example} +Figure~\ref{ex} on page~\pageref{ex} shows the \MSC{} defined in the +following \LaTeX\ fragment. + +{\small +\begin{verbatim} +\begin{msc}{Example} +\declinst{usr}{The user}{User} +\declinst{m1}{Control}{M1} +\dummyinst{m2} +\declinst{m3}{Another Machine}{M3} + +\create{start}{m1}{m2}{Processing}{M2} +\mess{msg 0}{envleft}{usr} +\mess{msg 1}{envright}{m2}[1] +\nextlevel + +\mess{msg 2}{usr}{m1} +\order{m1}{m2}[4] +\action{a}{m3} + +\nextlevel +\found{msg x}{}{usr} +\nextlevel + +\mess{msg 3}{usr}{m2}[-1] +\coregionstart{m1} +\settimeout{S}{m3}[2] +\nextlevel + + +\mess{msg 4}{m1}{usr} +\coregionstart{m2} +\settimer[r]{T}{m3} +\nextlevel + +\mess[r]{msg 5}{m2}{m2}[3] +\mess{msg 6}{usr}{usr}[2] +\nextlevel + +\mess{msg 7}{m2}{usr} +\timeout[r]{T}{m3} +\nextlevel + +\coregionend{m2} +\nextlevel + +\coregionend{m1} +\stoptimer[r]{T'}{m3} +\nextlevel + +\lost[r]{msg y}{Mach 1}{usr} +\mess{msg 8}{m1}{envright} +\nextlevel + +\condition{condition 1}{usr,m2} +\setstoptimer[r]{U}{m3} +\nextlevel[2] +\stop{usr} + +\end{msc} +\end{verbatim} +} + +\begin{figure}[htb] +\begin{center} +\begin{msc}{Example} +\declinst{usr}{The user}{User} +\declinst{m1}{Control}{M1} +\dummyinst{m2} +\declinst{m3}{Another Machine}{M3} + +\create{start}{m1}{m2}{Processing}{M2} +\mess{msg 0}{envleft}{usr} +\mess{msg 1}{envright}{m2}[1] +\nextlevel + +\mess{msg 2}{usr}{m1} +\order{m1}{m2}[4] +\action{a}{m3} + +\nextlevel +\found{msg x}{}{usr} +\nextlevel + +\mess{msg 3}{usr}{m2}[-1] +\coregionstart{m1} +\settimeout{S}{m3}[2] +\nextlevel + + +\mess{msg 4}{m1}{usr} +\coregionstart{m2} +\settimer[r]{T}{m3} +\nextlevel + +\mess[r]{msg 5}{m2}{m2}[3] +\mess{msg 6}{usr}{usr}[2] +\nextlevel + +\mess{msg 7}{m2}{usr} +\timeout[r]{T}{m3} +\nextlevel + +\coregionend{m2} +\nextlevel + +\coregionend{m1} +\stoptimer[r]{T'}{m3} +\nextlevel + +\lost[r]{msg y}{Mach 1}{usr} +\mess{msg 8}{m1}{envright} +\nextlevel + +\condition{condition 1}{usr,m2} +\setstoptimer[r]{U}{m3} +\nextlevel[2] +\stop{usr} + +\end{msc} + +\caption{A menagerie of \MSC{} symbols} +\label{ex} +\end{center} +\end{figure} + + +\section{Acknowledgments} +Thanks are due to the following people for providing us with useful +input: Peter Peters, Michel Reniers. In addition, we +thank the people who have submitted bugs, and sometimes even +bug-fixes. These people are mentioned in the \emph{Maintenance} +document of the \mscpack{} (Section~3, \emph{Bugs}). + +\bibliographystyle{plain} +\bibliography{biblio} + +\end{document} |