% file: refman.tex % Copyright 2008 V. Bos, T. van Deursen, and S. Mauw % This file is part of the MSC Macro Package. % \documentclass[a4paper]{article} \usepackage{a4wide} \usepackage{multicol} \usepackage{msc} \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){\footnotesize \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){\footnotesize \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){\footnotesize \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){\footnotesize \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){\footnotesize \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){\footnotesize \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){\footnotesize \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){\footnotesize \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}} \usepackage{url} \newcommand{\acro}[1]{{\scshape\lowercase{#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 Reference Manual} } \author{ \begin{tabular}{c} \begin{tabular}{ccc} Victor Bos & Ton van Deursen & Sjouke Mauw \\ & \scriptsize Universit\'e du Luxembourg & \scriptsize Universit\'e du Luxembourg \\[-0.8ex] \scriptsize \texttt{vbos@abo.fi} & \scriptsize \texttt{ton.vandeursen@uni.lu} & \scriptsize \texttt{sjouke.mauw@uni.lu} \end{tabular}\\ \end{tabular} } \date{\small Version \mscversion, last update \today\\ Describing \mscpack{} version \mscversion} \begin{document} \maketitle \tableofcontents \section{Introduction} The \mscpack{} was developed to draw (actually, to write) \emph{Message Sequence Charts} (\MSC{}s) with \LaTeX. The current version supports most of the \MSC{} language standardized in~\cite{z120}. The manual~\cite{BM02a} describes how to use the \mscpack{} and is illustrated with numerous examples. This reference manual briefly describes the main concepts of the package and it provides lists of all available environments and commands. In addition, it lists both the user-definable lengths and the internal lengths that are used by the package to compute the layout of \MSC{}s. \section{Concepts} The \mscpack{} offers three different kinds of diagrams: \begin{itemize} \item \MSC{} diagrams (normal \MSC{}s) \item \HMSC{} diagrams (high level \MSC{}s) \item \MSCdoc{} diagrams (\MSC{} documents) \end{itemize} For each of these diagrams, the package provides a \LaTeX{} environment. Figure~\ref{fig:types:of:diagrams} shows an example of each diagram. The source code for these diagrams is given in Figure~\ref{fig:sources}. Depending on the environment, different \mscpack{} commands can be used. Furthermore, since each environment is implemented as a \texttt{pspicture} (see \textsf{pstricks} documentation), it is possible to use \textsf{pstricks} commands inside the \MSC{} environments. \begin{figure} \begin{center} \setmscvalues{small} \begin{tabular}{ccc} \begin{msc}% {Example 1}% \declinst{i}{$i$}{} \declinst{j}{$j$}{} \nextlevel \mess{a}{i}{j} \nextlevel[2] \mess{b}{j}{i} \nextlevel \end{msc}% % & \begin{hmsc}% {Example 2}% (0,0)(4,4.65) \hmscstartsymbol{S}(2,3.75) \hmscconnection{c}(2,3.25) \hmscreference{R1}{A}(2,2.5) \hmsccondition{C}{?}(2,1.5) \hmscendsymbol{E}(1.5,0.5) \arrow{S}{c} \arrow{c}{R1} \arrow{R1}{C} \arrow{C} [(2.5,1)(3,1)(3,3.25)] {c} \arrow{C}[(1.5,1)]{E} \end{hmsc}% & \begin{mscdoc}% {Example 3}% (0,0)(4,4.65) \reference{A}(1,3.0) \reference{B}(3,3.0 ) \separator{2.0} \reference{C}(2,1.0) \end{mscdoc}% \\ (a) \MSC{} diagram & (b) \HMSC{} diagram & (c) \MSCdoc{} diagram \end{tabular} \end{center} \caption{Examples of different diagrams} \label{fig:types:of:diagrams} \end{figure} \begin{figure}[htb] \hrulefill \begin{center} \begin{minipage}[t]{0.3\linewidth} \small \begin{verbatim} \begin{msc}% {Example 1} \declinst{i}{$i$}{} \declinst{j}{$j$}{} \nextlevel \mess{a}{i}{j} \nextlevel[2] \mess{b}{j}{i} \nextlevel \end{msc} \end{verbatim} \end{minipage} \hfil \begin{minipage}[t]{0.3\linewidth} \small \begin{verbatim} \begin{hmsc}% {Example 2}% (0,0)(4,4.65) \hmscstartsymbol{S}(2,3.75) \hmscconnection{c}(2,3.25) \hmscreference{R1}{A}(2,2.5) \hmsccondition{C}{?}(2,1.5) \hmscendsymbol{E}(1.5,0.5) \arrow{S}{c} \arrow{c}{R1} \arrow{R1}{C} \arrow{C} [(2.5,1)(3,1)(3,3.25)] {c} \arrow{C}[(1.5,1)]{E} \end{hmsc} \end{verbatim} \end{minipage} \hfil \begin{minipage}[t]{0.3\linewidth} \small \begin{verbatim} \begin{mscdoc}% {Example 3}% (0,0)(4,4.65) \reference{A}(1,3.0) \reference{B}(3,3.0 ) \separator{2.0} \reference{C}(2,1.0) \end{mscdoc} \end{verbatim} \end{minipage} \end{center} \hrulefill \caption{Source code for diagrams of Figure~\ref{fig:types:of:diagrams}} \label{fig:sources} \end{figure} The \MSC{} environment provides most functionality of the package. The following concepts should help in understanding the user-commands of this environment. \begin{defs} \item[\emph{current height}] The \emph{current height} of an \MSC{} is a length that indicates the y-postion relative to the top of the msc frame. The \MSC{} drawing commands use this y-position to draw msc symbols, e.g., instance heads, messages, actions, and instance feet. The internal length \verb|\msc@currentheight| is the current height. This variables is changed whenever the command \verb|\nextlevel| is invoked. \item[\emph{current width}] The \emph{current width} of an \MSC{} is the distance from the left side of the \MSC{} frame to the right side of the \MSC{} frame. As such, it depends on the lengths \verb|\envinstdist| and \verb|\instdist| as well as on the number of instances. The internal length \verb|\msc@currentwidth| is the current width. During construction of an msc, that is, in between \verb|\begin{msc}| and \verb|\end{msc}|, \verb|\msc@currentwidth| is equal to $\verb|\envinstdist| + (n \times \verb|instdist|)$, provided that~$n$ is the number of instances defined so far (see \verb|\mscinstcnt| in the section \emph{Internal counters} below) and the length \verb|\instdist| is not changed between instances. At the end of an \MSC{} construction, an additional \verb|\envinstdist| is added to \verb|\msc@currentwidth|. The \verb|\msc@currentwidth| determines the x-position of new \MSC{} instances. \item[\emph{level}] A level is a horizontal layer in an \MSC{} which is used to construct msc's in a top-down fashion. Each level is \verb|\levelheight| units high and spans the complete width of the msc. The first level starts at $\verb|\topheaddist| + \verb|\instheadheight| + \verb|\firstlevelheight|$ units below the top of the \MSC{} frame. The \verb|\nextlevel| commands advances the \MSC{} to the next (lower) level. \item[\emph{\MSC{} instance}] The main building blocks of MSC diagrams are \emph{instances}. Instances are represented by vertical bars. \emph{Fat} instances are represented by two vertical lines. Usually, an instance has both a head symbol and a foot symbol. In the \mscpack, each \MSC{} instance has a \emph{nickname} by which the instance is identified. In the \mscpack{} there are special instances: \begin{itemize} \item The left environment (nickname \verb|envleft|). \item The right environment (nickname \verb|envright|). \item The left side of an inline expression. If the nickname of the inline expression is \verb|nm|, the nickname of the left side is \verb|nmleft|. \item The right side of an inline expression. If the nickname of the inline expression is \verb|nm|, the nickname of the left side is \verb|nmright|. \item The left side of an reference expression. If the nickname of the reference expression is \verb|nm|, the nickname of the left side is \verb|nmleft|. \item The right side of an reference expression. If the nickname of the reference expression is \verb|nm|, the nickname of the left side is \verb|nmright|. \item A \emph{dummy} instance is an instance that is invisible; it reserves space needed to draw an instance. It is useful to create (see \verb|create| command) instances with create-messages. \end{itemize} \item[\emph{nickname}] A nickname is a unique identification of an \emph{instance}. \item[\emph{message label reference points}] In order to place a message label somewhere near the message arrow, the \mscpack{} computes a \emph{reference point} for each message label. This is a location on the bounding box of the label such that the distance between the arrow and the reference point is minimized. Figures \ref{fig:refpoints} (page~\pageref{fig:refpoints}) and~\ref{fig:refpoints:B} (page~\pageref{fig:refpoints:B}) show the location of reference points for all possible locations of message labels. Note that the boxes with the location of the reference points are not generated by the \LaTeX{} code given in these figures; we enriched the \LaTeX{} code with some extra \textsf{pstricks} code (see \LaTeX{} source code of this document). \end{defs} \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 \footnotesize \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 \footnotesize \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} \section{Environments} \begin{defs} \item[\cmd{begin}\texttt{\{msc\}}\opt{titlepos}\{\emph{title}\}\texttt{...\cmd{end}\{msc\}}] The environment to draw msc's. The parameter \emph{title} defines the title of the msc. The optional parameter \emph{titlepos} defines the position of the title relative to the frame of the msc. Valid positions are \verb|l|~(left), \verb|c|~(center), and \verb|r|~(right). The default position is~\verb|l|. \item[\cmd{begin}\texttt{\{hmsc\}}\opt{titlepos}\{\emph{title}\}\texttt{...\cmd{end}\{hmsc\}}\coordargs{llx}{lly}\coordargs{urx}{ury}] The environment to draw \HMSC's. The parameter \emph{title} defines the title of the \HMSC. The optional parameter \emph{titlepos} defines the position of the title relative to the frame of the \HMSC. Valid positions are \verb|l|~(left), \verb|c|~(center), and \verb|r|~(right). The default position is~\verb|l|. The size of the \HMSC{} is determined by two pairs of coordinates. The coordinates \coordargs{llx}{lly} define the lower left corner of the \HMSC. The coordinates \coordargs{urx}{ury} define the upper right corner of the \HMSC. \item[\cmd{begin}\texttt{\{mscdoc\}}\opt{titlepos}\{\emph{title}\}\texttt{...\cmd{end}\{mscdoc\}}\coordargs{llx}{lly}\coordargs{urx}{ury}] The environment to draw \MSCdoc{} documents. The parameter \emph{title} defines the title of the \MSCdoc{} document. The optional parameter \emph{titlepos} defines the position of the title relative to the frame of the \MSCdoc{} document. Valid positions are \verb|l|~(left), \verb|c|~(center), and \verb|r|~(right). The default position is~\verb|l|. The size of the \MSCdoc{} is determined by two pairs of coordinates. The coordinates \coordargs{llx}{lly} define the lower left corner of the \MSCdoc. The coordinates \coordargs{urx}{ury} define the upper right corner of the \MSCdoc. \end{defs} \section{Commands} \begin{defs} \item[\cmd{action(*)}\{\emph{txt}\}\{\emph{nm}\}] Draws an \emph{action} symbol on the instance with nickname \emph{nm}. The parameter \emph{txt} defines the name of the action. The size of the action symbol is controlled by the \verb|\actionheight| and \verb|\actionwidth| lengths. The starred version adjusts the height and width of the action symbol to the size of the contents. \item[\cmd{arrow}\cmdarg{nm0}\opt{\coordargs{xpos${}_1$}{ypos${}_1$}$\ldots$\coordargs{xpos${}_n$}{ypos${}_n$}}\cmdarg{nm1}] Draws an arrow in an \HMSC{} diagram. The arrow starts at the symbol with nickname~\emph{nm0} and ends at the symbol with nickname~\emph{nm1}. The optional parameter \coordargs{xpos${}_1$}{ypos${}_1$}$\ldots$\coordargs{xpos${}_n$}{ypos${}_n$} is a list of intermediate points the arrow should pass through. \item[\cmd{changeinstbarwidth}\{\emph{nm}\}\{\emph{wd}\}] Changes the bar width of instance \emph{nm} to \emph{wd}. The parameter \emph{wd} should be a valid \LaTeX{} length. \item[\cmd{msccomment}\opt{\emph{pos}}\{\emph{txt}\}\{\emph{nm}\}] Puts a comment at instance \emph{nm}. The parameter \emph{txt} is the comment. The optional parameter \emph{pos} defines the horizontal position of the comment relative to instance \emph{nm}. Valid positions are \verb|l|~(left), \verb|r|~(right), and all valid lengths. If the position is \verb|l| or~\verb|r|, the comment will be put at \verb|\msccommentdist| units to the left or right, respectively, from the instance axis. If \emph{pos} is a length, the comment will be put \emph{pos} units from the instance axis. A negative \emph{pos} puts the comment to the left and a positive \emph{pos} puts it to the right of the instance axis. \item[\cmd{condition(*)}\{\emph{txt}\}\{\emph{instancelist}\}] Draws a \emph{condition} symbol on the instances occurring in \emph{instancelist}. The parameter \emph{txt} defines the text to be placed in the \emph{condition} symbol. The parameter \emph{instancelist} is a comma separated list of instance nicknames. Note that there should be no white space between the commas and the nicknames; only if a nickname contains white space is a white space allowed in \emph{instancelist}. The starred version adjusts the height and width of the condition symbol to the size of the contents. \item[\cmd{coregionend}\{\emph{nm}\}] Ends the co-region on the instance \emph{nm}. This command is obsolete (see \verb|\regionend|). \item[\cmd{coregionstart}\{\emph{nm}\}] Starts a co-region on the instance \emph{nm}. This command is obsolete (see \verb|\regionstart|). \item[\cmd{create}\{\emph{msg}\}\opt{\emph{labelpos}}\{\emph{creator}\}\opt{\emph{placement}}\{\emph{nm}\}\{\emph{na}\}\{\emph{in}\}] Instance with nickname \emph{creator} sends a create message with label \emph{msg} to instance \emph{nm}. Instance \emph{nm} should be a dummy (invisible) instance at the time of the create message, see \cmd{dummyinst}. The head symbol of \emph{nm} is drawn at \verb|\msc@currentheight|. The parameter \emph{an} (above name) is put above the head symbol. The parameter \emph{in} (inside name) is put inside the head symbol. \emph{nm}'s y-position is set to \verb|\msc@currentheight| $+$ \verb|\instheadheight|. The optional parameter \emph{labelpos} defines the position of the message label. Valid values are \verb|t| and~\verb|b|, denoting a label position on top of the arrow and a label position below the arrow, respectively. The optional parameter \emph{placement} defines the relative position of the message label along the message arrow. Valid values are real numbers in the closed interval $[0,1]$, where~$0$ corresponds to the beginning of the arrow and~$1$ corresponds to the end of the arrow. The default value is~$0.5$. \item[\cmd{declinst(*)}\{\emph{nm}\}\{\emph{an}\}\{\emph{in}\}] Defines an instance with nickname \emph{nm}. The starred version makes a \emph{fat instance}. The x-position is \verb|\instdist| to the right of \verb|\msc@currentwidth|. The head symbol of the instance is drawn at \verb|\msc@currentheight|. The parameter \emph{an} (above name) is put above the head symbol. The parameter \emph{in} (inside name) is put inside the head symbol. The instance y-position is set to \verb|\msc@currentheight| $+$ \verb|\instheadheight|. \item[\cmd{drawframe}\{\emph{str}\}] A command to turn on/off the drawing of the frame around msc's, hmsc's, and mscdoc's. If \emph{str} is `yes', the frame will be drawn, otherwise the frame will not be drawn. \item[\cmd{drawinstfoot}\{\emph{str}\}] A command to turn on/off drawing of instance foot symbols. If \emph{str} is `yes', the foot symbols will be drawn, otherwise they will not be drawn. \item[\cmd{drawinsthead}\{\emph{str}\}] A command to turn on/off drawing of instance head symbols. If \emph{str} is `yes', the head symbols will be drawn, otherwise they will not be drawn. \item[\cmd{dummyinst(*)}\{\emph{nm}\}] Defines a \emph{dummy instance} with nickname \emph{nm}. The starred version makes a \emph{fat instance}. The x-position is \verb|\instdist| to the right of \verb|\msc@currentwidth|. No head symbol is drawn. The instance y-position is undefined. \item[\cmd{found}\opt{\emph{pos}}\{\emph{label}\}\opt{\emph{labelpos}}\{\emph{gate}\}\{\emph{nm}\}\opt{\emph{placement}}] Draws a \emph{found message} to instance \emph{nm}. The \emph{label} parameter defines the message name. The \emph{gate} parameter defines the gate name. The optional parameter \emph{pos} defines the position of the message relative to instance \emph{nm}. Valid positions are \verb|l| (left) and \verb|r| (right). The default position is \verb|l|. The optional parameter \emph{labelpos} defines the position of the message label with respect to the arrow. Valid values are \verb+t+ (on top) and \verb+b+ (below). The default value is \verb+t+. The optional parameter \emph{placement} defines the relative position of the message label along the message arrow. Valid values are real numbers in the closed interval $[0,1]$, where~$0$ corresponds to the beginning of the arrow and~$1$ corresponds to the end of the arrow. The default value is~$0.5$. The length of the arrow is determined by \verb+\selfmesswidth+. \item[\cmd{gate(*)}\opt{\emph{hpos}}\opt{\emph{vpos}}\{\emph{txt}\}\{\emph{nm}\}] Draws a gate at instance \emph{nm}. The parameter \emph{txt} defines the name of the gate. The starred version produces a visible gate by drawing a black circle at instance \emph{nm}. The unstarred version produces an invisible gate. The position of the parameter \emph{txt} is controlled by the optional parameters \emph{hpos} and \emph{vpos}: \emph{hpos} defines the horizontal position relative to instance \emph{nm} and \emph{vpos} defines the vertical position relative to the current height (\verb|\msc@currentheight|). Valid horizontal positions are \verb|l|~(left) and \verb|r|~(right). The default horizontal position is~\verb|l|. Valid vertical positions are \verb|t|~(top), \verb|c|~(center), and \verb|b|~(bottom). The default vertical is~\verb|t|. \item[\cmd{hmsccondition}\cmdarg{nm}\cmdarg{txt}\coordargs{xpos}{ypos}] Draws an \HMSC{} condition symbol with nickname \emph{nm} at position \coordargs{xpos}{ypos}. The \emph{txt} parameter is placed inside the condition symbol. \item[\cmd{hmscconnection(*)}\cmdarg{nm}\coordargs{xpos}{ypos}] Draws an \HMSC{} connection symbol with nickname \emph{nm} at position \coordargs{xpos}{ypos}. The unstarred version produces an invisible connection symbol. The starred version produces a visible connection symbol (i.e., a small circle). \item[\cmd{hmscendsymol}\cmdarg{nm}\coordargs{xpos}{ypos}] Draws an \HMSC{} end symbol with nickname \emph{nm} at position \coordargs{xpos}{ypos}. \item[\cmd{hmsckeyword}] The \HMSC{} keyword. The default value is `hmsc'. \item[\cmd{hmsckeywordstyle}\{\emph{kw}\}] A one-parameter command to typeset the \HMSC{} keyword. The command can expect \verb|\hmsckeyword| to be the value of \emph{kw}. The default `value' is \verb|\textbf|. \item[\cmd{hmscreference}\cmdarg{nm}\cmdarg{txt}\coordargs{xpos}{ypos}] Draws an \HMSC{} reference symbol with nickname \emph{nm} at position \coordargs{xpos}{ypos}. The \emph{txt} parameter is placed inside the condition symbol. \item[\cmd{hmscstartsymbol}\cmdarg{nm}\coordargs{xpos}{ypos}] \HMSC{} start symbol with nickname \emph{nm} at position \coordargs{xpos}{ypos}. \item[\cmd{inlineend(*)}\{\emph{nm}\}] Ends the matching inline expression (matching means equal nicknames). The unstarred version draws a solid line to close the inline expression. The starred version draws a dashed line to close the inline expression. \item[\cmd{inlineseparator}\{\emph{nm}\}] Draws an inline separator line at the inline expression with nickname \emph{nm}. The separator is drawn at \verb|\msc@currentheight|. \item[\cmd{inlinestart}\opt{\emph{lo}}\opt{\emph{ro}}\{\emph{nm}\}\{\emph{txt}\}\{\emph{fi}\}\{\emph{li}\}] Defines an \emph{inline expression} with nickname \emph{nm}. The inline expression is started at \verb|\msc@currentheight| and continues until the level where a matching \cmd{inlineend} command is found (matching means equal nicknames). The \emph{txt} parameter defines the text of the inline expression. The first instance of the inline expression is \emph{fi}. The last instance of the inline expression is \emph{li}. The optional parameter \emph{lo} defines the left and right overlap of the inline expression. If the second optional parameter, \emph{ro}, is present, \emph{lo} defines the left and \emph{ro} defines the right overlap. \item[\cmd{inststart}\{\emph{nm}\}\{\emph{an}\}\{\emph{in}\}] Starts instance with nickname \emph{nm}. Instance \emph{nm} should be a dummy (invisible) instance at the time of the \cmd{inststart} command, see \cmd{dummyinst}. The head symbol is drawn at \verb|\msc@currentheight|. The parameter \emph{an} (above name) is put above the head symbol. The parameter \emph{in} (inside name) is put inside the head symbol. The instance y-position is set to \verb|\msc@currentheight| $+$ \verb|\instheadheight|. \item[\cmd{inststop}\{\emph{nm}\}] Stops instance with nickname \emph{nm}. The foot symbol is drawn at \verb|\msc@currentheight|. The instance y-position is undefined after this command. \item[\cmd{lost}\opt{\emph{pos}}\{\emph{label}\}\opt{\emph{labelpos}}\{\emph{gate}\}\{\emph{nm}\}\opt{\emph{placement}}] Draws a \emph{lost message} from instance \emph{nm}. The \emph{label} parameter defines the message name. The \emph{gate} parameter defines the gate name. The optional parameter \emph{pos} defines the position of the message relative to instance \emph{nm}. Valid positions are \verb|l| (left) and \verb|r| (right). The default position is \verb|l|. The optional parameter \emph{labelpos} defines the position of the message label with respect to the arrow. Valid values are \verb+t+ (on top) and \verb+b+ (below). The default value is \verb+t+. The optional parameter \emph{placement} defines the relative position of the message label along the message arrow. Valid values are real numbers in the closed interval $[0,1]$, where~$0$ corresponds to the beginning of the arrow and~$1$ corresponds to the end of the arrow. The default value is~$0.5$. The length of the arrow is determined by \verb+\selfmesswidth+. \item[\cmd{measure(*)}\opt{\emph{pos}}\{\emph{txt}\}\{\emph{nm1}\}\{\emph{nm2}\}\opt{\emph{offset}}] Puts a \emph{measure} at instances \emph{nm1} and \emph{nm2}. The parameter \emph{txt} defines the label of the measure. The starred version puts the triangular measure symbols outside the measure; the unstarred version puts the triangular measure symbols inside the measure. The optional \emph{pos} parameter defines the horizontal position of the measure relative to instances \emph{nm1} and~\emph{nm2}. Valid positions are \verb|l|~(left), \verb|r|~(right), and all valid lengths. If the position is \verb|l| or~\verb|r|, the measure will be put at \verb|\measuredist| units to the left or right, respectively, from the closest instance axis. If \emph{pos} is a length, the measure will be put \emph{pos} units from the closest instance axis. A negative \emph{pos} puts the measure to the left and a positive \emph{pos} puts it to the right of the instances. The optional parameter \emph{offset} defines the number of levels the measure should extend vertically. The default value for \emph{offset} is~1. \item[\cmd{measureend(*)}\opt{\emph{pos}}\{\emph{txt}\}\{\emph{nm}\}\{\emph{gate}\}] Puts a \emph{measure end} symbol at instance \emph{nm}. The starred version puts the triangular measure symbol outside the measure; the unstarred version puts the triangular measure symbol inside the measure. The \emph{txt} parameter defines the label of the measure. The \emph{gate} parameter defines the name of the gate of the measure end symbol. The optional \emph{pos} parameter defines the horizontal position of the measure relative to the \emph{nm} instance. Valid positions are \verb|l|~(left), \verb|r|~(right), and all valid lengths. If the position is \verb|l| or~\verb|r|, the measure will be put at \verb|\measuredist| units to the left or right, respectively, from the instance axis. If \emph{pos} is a length, the measure will be put \emph{pos} units from the instance axis. A negative \emph{pos} puts the measure to the left and a positive \emph{pos} puts it to the right of the instance. \item[\cmd{measurestart(*)}\opt{\emph{pos}}\{\emph{txt}\}\{\emph{nm}\}\{\emph{gate}\}] Puts a \emph{measure start} symbol at instance \emph{nm}.The starred version puts the triangular measure symbol outside the measure; the unstarred version puts the triangular measure symbol inside the measure. The \emph{txt} parameter defines the label of the measure. The \emph{gate} parameter defines the name of the gate of the measure start symbol. The optional parameter \emph{pos} defines the horizontal position of the measure relative to instance \emph{nm}. Valid positions are \verb|l|~(left), \verb|r|~(right), and all valid lengths. If the position is \verb|l| or~\verb|r|, the measure will be put at \verb|\measuredist| units to the left or right, respectively, from the instance axis. If \emph{pos} is a length, the measure will be put \emph{pos} units from the instance axis. A negative \emph{pos} puts the measure to the left and a positive \emph{pos} puts it to the right of the instance. \item[\cmd{mess(*)}\opt{\emph{pos}}\{\emph{label}\}\opt{\emph{labelpos}}\{\emph{sender}\}\opt{\emph{placement}}\{\emph{receiver}\}\opt{\emph{offset}}] Draws a message from \emph{sender} instance to \emph{receiver} instance. The starred version draws a dashed line arrow, instead of a solid arrow. This can be used to distinguish method calls from method replies. The \emph{sender} and \emph{receiver} may be the same instance, in which case the message is a \emph{self message}. The parameter \emph{label} defines the message name. The message starting y-position is \verb|\msc@currentheight| and the ending y-position of the message is defined by \verb|\msc@currentheight| $+$ $(\textit{offset}\ \times $ \verb|\levelheight|$)$. The optional parameter \emph{pos} defines the position of self messages with respect to the instance axis. Valid values are \verb+l+ (left) and \verb+r+ (right). The default value is \verb+l+. The optional parameter \emph{labelpos} defines the position of the message label. In case of a self message, valid values are \verb|l| and \verb|r|, denoting a label position left from the arrow and right from the arrow, respectively. For self-messages the default value of \verb+labelpos+ is the value of \verb+pos+. In case of a non-self message, valid values are \verb|t| (default) and \verb|b|, denoting a label position on top of the message arrow and below the message arrow, respectively. The optional parameter \emph{placement} defines the relative position of the message label along the message arrow. Valid values are real numbers in the closed interval $[0,1]$, where~$0$ corresponds to the beginning of the arrow and~$1$ corresponds to the end of the arrow. The default value is~$0.5$. The default value of the optional parameter \emph{offset} is~0 for normal messages and~1 for self messages. \item[\cmd{messarrowscale}\{\emph{scalefactor}\}] Sets the scale factor (a real number) of message arrow heads. The default value is~1.5 \item[\cmd{mscdate}] The date of the \mscpack. \item[\cmd{mscdockeyword}] The \MSCdoc{} keyword. The default value is `mscdoc'. \item[\cmd{mscdockeywordstyle}\{\emph{kw}\}] A one-parameter command to typeset the mscdoc keyword. The command can expect \verb|\mscdockeyword| to be the value of \emph{kw}. The default `value' is \verb|\textbf|. \item[\cmd{msckeyword}] The \MSC{} keyword. The default value is `msc'. \item[\cmd{msckeywordstyle}\{\emph{kw}\}] A one-parameter command to typeset the \MSC{} keyword. The command can expect \verb|\msckeyword| to be the value of \emph{kw}. The default `value' is \verb|\textbf|. \item[\cmd{mscmark}\opt{\emph{pos}}\{\emph{txt}\}\{\emph{nm}\}] Puts a mark at instance \emph{nm}. The parameter \emph{txt} is the name of the mark. The optional parameter \emph{pos} defines the horizontal and vertical position of the mark relative to instance \emph{nm} and the current height \verb|\msc@currentheight|. Valid positions are \verb|tl|~(top-left), \verb|tr|~(top-right), \verb|bl|~(bottom-left), and \verb|br|~(bottom-right). The default position is \verb|tl|. The horizontal distance between the mark and the instance is defined by \verb+\markdist+. \item[\cmd{mscunit}] A string denoting the (default) unit of all lengths used by the \mscpack. Valid values are \emph{cm}, \emph{em}, \emph{ex}, \emph{in}, \emph{mm}, \emph{pt}, etc. The default value is~\emph{cm}. \item[\cmd{setmscunit}\{\emph{unit}\}] Changes the value of \cmd{mscunit} into \emph{unit}. Valid values for \emph{unit} are \emph{cm}, \emph{em}, \emph{ex}, \emph{in}, \emph{mm}, \emph{pt}, etc. \item[\cmd{mscversion}] The version number of the \mscpack. \item[\cmd{nextlevel}\opt{\emph{offset}}] Increases the number of levels by the value of the optional parameter \emph{offset}. The default value of \emph{offset} is~1. Increasing the level number means that \verb|\msc@currentheight| is increased by $\textit{offset} \times \verb|\levelheight|$. The first time this macro is used, the actual increase of \verb|\msc@currentheight| is $\verb|\firstlevelheight| + ((\textit{offset} - 1) \times \verb|\levelheight|)$. Negative values of \emph{offset} back up a number of levels. There are situations where this is useful, see Section~\ref{sec:tricks}. \item[\cmd{nogrid}] Turns off grid drawing in \MSC, \HMSC, and \MSCdoc{} diagrams. This command should not be used inside an \MSC, \HMSC, or \MSCdoc{} evironment. \item[\cmd{order}\opt{\emph{pos}}\{\emph{sender}\}\{\emph{receiver}\}\opt{\emph{offset}}] Draws an \emph{order line} from the \emph{sender} instance to the \emph{receiver} instance. The \emph{sender} and \emph{receiver} may be the same instance, in which case the order is a \emph{self-order}. The order starting y-position is \verb|\msc@currentheight| and the ending y-position of the order is defined by \verb|\msc@currentheight| $+$ $(\textit{offset}\ \times $ \verb|\levelheight|$)$. In case of a self-order, the optional parameter \emph{pos} defines the position of the order relative to the \emph{sender} instance. Valid positions are \verb|l| (left) and \verb|r| (right). The default position is \verb|l|. In case of a non-self-order, the \emph{pos} parameter is ignored. The default value of the optional parameter \emph{offset} is~0 for normal orders and~1 for self orders. \item[\cmd{reference}\cmdarg{txt}\coordargs{xpos}{ypos}] Draws an \MSCdoc{} reference symbol. The \emph{txt} parameter defines the text to be placed inside the \MSCdoc{} reference symbol. The coordinates \coordargs{xpos}{ypos} define the position of the reference symbol. \item[\cmd{referenceend}\{\emph{nm}\}] Ends the reference expression with nickname \emph{nm}. \item[\cmd{referencestart}\opt{\emph{lo}}\opt{\emph{ro}}\{\emph{nm}\}\{\emph{txt}\}\{\emph{fi}\}\{\emph{li}\}] Defines a \emph{reference expression} with nickname \emph{nm}. The reference expression is started at \verb|\msc@currentheight| and continues until the level where a matching \verb|\referenceend| command is found. The \emph{txt} parameter defines the text of the reference expression. The first instance of the reference expression is \emph{fi}. The last instance of the reference expression is \emph{li}. The optional parameter \emph{lo} defines the left and right overlap of the reference expression. If the second optional parameter, \emph{ro}, is present, \emph{lo} defines the left and \emph{ro} defines the right overlap. \item[\cmd{regionend}\{\emph{nm}\}] Ends the current region on instance \emph{nm}. The region style of the instance \emph{nm} is reset to \emph{normal} again. Note: this command makes \verb|\coregionend| obsolete. \item[\cmd{regionstart}\{\emph{rstyle}\}\{\emph{nm}\}] Starts a region on the instance \emph{nm}. The style of the region is defined by the \emph{rstyle} parameter. Valid region styles are \emph{coregion}, \emph{suspension}, \emph{activation}, and \emph{normal}. Note: this command makes \verb|\coregionstart| obsolete. \item[\cmd{separator}\cmdarg{ypos}] Draws a separator in an \MSCdoc{} diagram. The \coordarg{ypos} parameter defines the vertical position of the separator in the \MSCdoc{} diagram. \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. \item[\cmd{sethmsckeyword}\{\emph{kw}\}] Sets the \HMSC{} keyword to \emph{kw}. For this command to be effective, it should be used outside the \HMSC{} environment. \item[\cmd{sethmsckeywordstyle}\{\emph{kwstylemacro}\}] Redefines the \verb|\hmsckeywordstyle| macro to the macro \emph{kwstylemacro}. This should be a 1-argument macro, like the standard \LaTeX{} \cmd{textbf} and \cmd{textit} commands. For this command to be effective, it should be used outside the \HMSC{} environment. \item[\cmd{setmscdockeyword}\{\emph{kw}\}] Sets the \MSCdoc{} keyword to \emph{kw}. For this command to be effective, it should be used outside the \MSCdoc{} environment. \item[\cmd{setmscdockeywordstyle}\{\emph{kwstylemacro}\}] Redefines the \verb|\mscdockeywordstyle| macro to the macro \emph{kwstylemacro}. This should be a 1-argument macro, like the standard \LaTeX{} \cmd{textbf} and \cmd{textit} commands. For this command to be effective, it should be used outside the \MSCdoc{} environment. \item[\cmd{setmsckeyword}\{\emph{kw}\}] Sets the \MSC{} keyword to \emph{kw}. For this command to be effective, it should be used outside the \MSC{} environment. \item[\cmd{setmsckeywordstyle}\{\emph{kwstylemacro}\}] Redefines the \verb|\msckeywordstyle| macro to the macro \emph{kwstylemacro}. This should be a 1-argument macro, like the standard \LaTeX{} \cmd{textbf} and \cmd{textit} commands. For this command to be effective, it should be used outside the \MSC{} environment. \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. \item[\cmd{setmscvalues}\{\emph{size}\}] Sets the msc-lengths to one of the predefined \emph{sizes}. Valid values for \emph{size} are: \verb|small|, \verb|normal|, and \verb|large|. \item[\cmd{setstoptimer}\opt{\emph{pos}}\{\emph{label}\}\{\emph{nm}\}\opt{\emph{offset}}] Draws both a \emph{timer} and a \emph{stop timer} symbol on the instance \emph{nm}. The parameter \emph{label} defines the name of the timer. The optional parameter \emph{pos} defines the position of the \emph{timer} relative to the \emph{nm} instance. Valid positions are \verb|l| (left) and \verb|r| (right). The default position is~\verb|l|. The horizontal distance between the timer symbol and the instance axis is defined by \verb+selfmesswidth+. \item[\cmd{settimeout}\opt{\emph{pos}}\{\emph{label}\}\{\emph{nm}\}\opt{\emph{offset}}] Draws a \emph{timer} symbol on the instance \emph{nm} and connects the \emph{timer} symbol and the instance with an arrow. The parameter \emph{label} defines the name of the \emph{timer}. The optional parameter \emph{pos} defines the position of the \emph{timer} relative to the \emph{nm} instance. Valid positions are \verb|l| (left) and \verb|r| (right). The default position is~\verb|l|. The optional parameter \emph{offset} defines the number of levels between the \emph{timer} symbol and the point where the arrow meets the \emph{nm} instance. The default \emph{offset} is~2. The horizontal distance between the timer symbol and the instance axis is defined by \verb+selfmesswidth+. \item[\cmd{settimer}\opt{\emph{pos}}\{\emph{label}\}\{\emph{nm}\}] Draws a \emph{timer} symbol on the instance \emph{nm}. The parameter \emph{label} defines the name of the timer. The optional parameter \emph{pos} defines the position of the \emph{timer} relative to the \emph{nm} instance. Valid positions are \verb|l| (left) and \verb|r| (right). The default position is~\verb|l|. The horizontal distance between the timer symbol and the instance axis is defined by \verb+selfmesswidth+. \item[\cmd{showgrid}] Turns on grid-drawing in \MSC, \MSCdoc, and \HMSC{} diagrams. This is useful to determine the values of the user definable lengths or if normal \textsf{pstricks} commands should be included in the diagram. (Note that the vertical axis of the \MSC{} grid has no positive labels.) This command should not be used inside an \MSC, \HMSC, or \MSCdoc{} evironment. \item[\cmd{stop}\{\emph{nm}\}] Stops the instance with nickname \emph{nm}. The instance line of \emph{nm} is drawn from its y-position to the current y-position of the \MSC{} (\verb|\msc@curentheight|). At the current height, a \emph{stop} symbol is drawn. \item[\cmd{stoptimer}\opt{\emph{pos}}\{\emph{label}\}\{\emph{nm}\}] Draws a \emph{stop timer} symbol on the instance \emph{nm}. The parameter \emph{label} defines the name of the timer. The optional parameter \emph{pos} defines the position of the \emph{timer} relative to the \emph{nm} instance. Valid positions are \verb|l| (left) and \verb|r| (right). The default position is~\verb|l|. The horizontal distance between the timer symbol and the instance axis is defined by \verb+selfmesswidth+. \item[\cmd{timeout}\opt{\emph{pos}}\{\emph{label}\}\{\emph{nm}\}] Draws a \emph{timer} symbol on the instance \emph{nm} and connects the symbol and the instance with an arrow. The parameter \emph{label} defines the name of the timeout. The optional parameter \emph{pos} defines the position of the \emph{timer} symbol relative to the \emph{nm} instance. Valid positions are \verb|l| (left) and \verb|r| (right). The default position is~\verb|l|. The horizontal distance between the timer symbol and the instance axis is defined by \verb+selfmesswidth+. \end{defs} \section{User definable lengths} This section lists the user-definable lengths of the \mscpack. For each length, the default values for large, normal, and small diagrams are given. The appearance of \MSC, \HMSC, and \MSCdoc{} diagrams can be changed by adjusting these lengths. Use the normal \cmd{setlength} command to change these lengths. \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.8}{0.7}{0.6} cm.) \item[\cmd{hmscreferencewidth}] Width of \HMSC{} reference symbol.\\ (\lnsvalue{1.6}{1.4}{1.2} cm.) \item[\cmd{hmscstartsymbolwidth}] Width of \HMSC{} start symbol.\\ (\lnsvalue{0.85}{0.7}{0.4} 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.8}{0.7}{0.6} cm.) \item[\cmd{mscdocreferencewidth}] Width of reference symbol in an \MSCdoc.\\ (\lnsvalue{1.6}{1.4}{1.2} 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, self-orders, lost messages and found messages as well as horizontal distance between instance axis and timer symbols.\\ (\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} \section{lnternal lengths} The \mscpack{} uses some scratch lengths to perform calculations. Below, these scratch lengths are listed. \begin{defs} \item[\cmd{msc@commentdist}] Internal length to compute distance between comments and instances. (This length should be removed in the future.) \item[\cmd{msc@currentheight}] The current height of the current \MSC{} environment. \item[\cmd{msc@currentwidth}] The current width of the current \MSC{} environment. \item[\cmd{msc@totalheight}] The final height of the current \MSC{} environment. \item[\cmd{msc@totalwidth}] The final width of the current \MSC{} environment. \item[\cmd{tmp@X}] Scratch length for intermediate computations. \item[\cmd{tmp@Xa}] Scratch length for intermediate computations. \item[\cmd{tmp@Xb}] Scratch length for intermediate computations. \item[\cmd{tmp@Xc}] Scratch length for intermediate computations. \item[\cmd{tmp@Xd}] Scratch length for intermediate computations. \item[\cmd{tmp@Y}] Scratch length for intermediate computations. \item[\cmd{tmp@Ya}] Scratch length for intermediate computations. \item[\cmd{tmp@Yb}] Scratch length for intermediate computations. \item[\cmd{tmp@Yc}] Scratch length for intermediate computations. \item[\cmd{tmp@Yd}] Scratch length for intermediate computations. \end{defs} \section{Internal boxes} \begin{defs} \item[\cmd{mscbox}] The box that contains the current \MSC{} just before it is put on paper. \item[\cmd{tmp@box}] Scratch box for intermediate computations \end{defs} \section{Internal counters} \begin{defs} \item[\cmd{mscinstcnt}] The \MSC{} instance counter. This counter is increased each time an instance is created. \item[\cmd{tmpcnt}] Scratch counter for intermediate computations. \end{defs} \section{Limitations} \begin{enumerate} \item The frames in an MSC do not automatically scale with the text inside the frame. However, the size of the frames can be set manually. \item Start and end points of messages are computed at the current level. This can give ill-looking effects if the width of the bar of an instance changes after the message is drawn, e.g., if an activation region starts or ends after the message is drawn. \item Messages that cause the start of a region should be drawn after the \verb|\regionstart| command, but in the same level. \item Messages that denote the end of a region should be drawn before the \verb|\regionend| command. \item Activation regions make crossing messages partly invisible. A solution for this problem is to first draw the instance foot symbols at the right level (using \verb|\inststop{i}|), then back up the total number of levels of the MSC (using \verb|\nextlevel[-n]|), and then drawing the messages. \item Documents using the \mscpack{} cannot be compiled with \emph{pdflatex}. The reason for this is that \textsf{pstricks} is not supported by \emph{pdflatex}. \item The source code of the \mscpack{} is only marginally documented. Therefore, changes/improvements by others are unlikely. \end{enumerate} \section{Tricks} \label{sec:tricks} In this section we describe some tricks to use the \mscpack{} efficiently. \paragraph{Multi-line text arguments} Many graphical objects in \MSC{} diagrams have text labels. In general, the commands to draw these objects put the text arguments on one line. If the text should consist of multiple lines, the \LaTeX{} \cmd{parbox} command can be used. For instance, to generate a message with a two-line label, write: \verb|\mess{\parbox{1cm}{two\\lines}}{s}{r}| \paragraph{Specifying lengths} The \mscpack{} imports the \textsf{calc} package in order to have a more natural syntax for arithmetical expressions. Consequently, if a command expects a \LaTeX{} length argument, it is possible to use the expression syntax offered by \textsf{calc}. For example, consider the \MSC{} of Figure~\ref{fig:specifying:lengths}. To make sure the comment for instance~$j$ appears 1ex to the right of the \MSC{} frame, the value of the optional \emph{pos} parameter of the \cmd{comment} command should be \[ \cmd{instdist} + \cmd{envinstdist} + 1\textrm{ex}. \] To express this in normal \LaTeX, one should write something like \begin{verbatim} \newlength{\l} \setlength{\l}{\instdist} \addtolength{\l}{\envinstdist} \addtolength{\l}{1ex} \msccomment[\l]{Comment for $j$}{j} \end{verbatim} inside the \MSC{} code. However, using \textsf{calc}'s expression syntax, it is also possible to write \begin{verbatim} \msccomment[\instdist + \envinstdist + 1ex]{Comment for $j$}{j} \end{verbatim} The complete code for the diagram of Figure~\ref{fig:specifying:lengths} is given below. Since the \textsf{calc} package is included in the standard \LaTeX{} distribution, there should be no compatibility problems. \begin{figure}[htb] \begin{center} \begin{msc}{Specifying lengths} \declinst{i}{$i$}{} \declinst{j}{$j$}{} \declinst{k}{$k$}{} \nextlevel \msccomment[\instdist + \envinstdist + 1ex]{Comment for $j$}{j} \nextlevel[2] \end{msc} \caption{Specifying lengths} \label{fig:specifying:lengths} \end{center} \end{figure} {\small \begin{verbatim} \begin{msc}{Specifying lengths} \declinst{i}{$i$}{} \declinst{j}{$j$}{} \declinst{k}{$k$}{} \nextlevel \msccomment[\instdist + \envinstdist + 1ex]{Comment for $j$}{j} \nextlevel[2] \end{msc} \end{verbatim} } \paragraph{Level backup} It is possible to back-up several levels: just use a negative value in the \cmd{nextlevel} command. This \emph{feature} can be useful to draw messages over regions instead of regions over messages. Compare the diagrams of Figure~\ref{fig:level:backup}. The code for these diagrams is given below. \begin{figure}[htb] \begin{center} \setmscvalues{small} \begin{tabular}{cc} \begin{msc}{Invisible message label} \declinst{i}{$i$}{} \declinst{j}{$j$}{} \declinst{k}{$k$}{} \regionstart{activation}{j} \nextlevel \mess{Message a}{i}[0.25]{k}[2] \nextlevel[2] \regionend{j} \nextlevel \end{msc} & \begin{msc}{Level backup makes it visible} \declinst{i}{$i$}{} \declinst{j}{$j$}{} \declinst{k}{$k$}{} \regionstart{activation}{j} \nextlevel[3] \regionend{j} \nextlevel[-2]% backing up \mess{Message a}{i}[0.25]{k}[2] \nextlevel[2]% fast forward \nextlevel \end{msc} \end{tabular} \caption{Level back-up} \label{fig:level:backup} \end{center} \end{figure} {\small \begin{verbatim} \begin{msc}{Invisible message label} \declinst{i}{$i$}{} \declinst{j}{$j$}{} \declinst{k}{$k$}{} \regionstart{activation}{j} \nextlevel \mess{Message a}{i}[0.25]{k}[2] \nextlevel[2] \regionend{j} \nextlevel \end{msc} \begin{msc}{Level backup makes it visible} \declinst{i}{$i$}{} \declinst{j}{$j$}{} \declinst{k}{$k$}{} \regionstart{activation}{j} \nextlevel[3] \regionend{j} \nextlevel[-2]% backing up \mess{Message a}{i}[0.25]{k}[2] \nextlevel[2]% fast forward \nextlevel \end{msc} \end{verbatim} } \bibliographystyle{plain} \bibliography{biblio} \end{document}