path: root/macros/latex/contrib/msc/refman.tex

% 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}