% file: maintenance.tex
% Copyright 2002 V. Bos and S. Mauw
% This file is part of the MSC Macro Package.
%
% RCS version: $Id: maintenance.tex,v 1.11 2004/03/15 11:40:27 vbos Exp $
%
\documentclass{article}
\usepackage{a4wide}
\usepackage{msc}

\title{
  A {\LaTeX{}} macro package for Message Sequence Charts---Maintenance 
  document
}

\author{
  \begin{tabular}{cc}
  Victor Bos  & Sjouke Mauw\\
  \footnotesize Turku Centre for Computer Science &
  \footnotesize Eindhoven University of Technology \\ [-0.8ex]
  \footnotesize Software Construction Laboratory &
  \footnotesize Department of Mathematics and Computing Science \\ [-0.8ex]
  \footnotesize Lemminkäisenkatu 14 & 
  \footnotesize P.O.\ Box 513 \\ [-0.8ex]
  \footnotesize FIN--20520 Turku &
  \footnotesize NL--5600 MB Eindhoven \\ [-0.8ex] 
  \footnotesize Finland & 
  \footnotesize The Netherlands \\
  \footnotesize \texttt{vbos@abo.fi} &
  \footnotesize \texttt{sjouke@win.tue.nl}
  \end{tabular}
}


\begin{document}

\date{\small Version \mscversion, last update \today}

\maketitle

\begin{abstract}
\noindent
The MSC macro package facilitates the \LaTeX\ user to easily include
Message Sequence Charts in his texts. This document contains
information which supports the maintenance of the package.
\end{abstract}

\section{Introduction}
This document contains three lists related to the maintenance of the
MSC macro package. This is a \LaTeX\ package for drawing Message
Sequence Charts.
For additional information consult the following URL:
\verb+http://www.win.tue.nl/~sjouke/mscpackage.html+.

The first list contains an overview of all publicly released versions 
of the MSC macro package. The second list contains all known (yet
unresolved) bugs of the MSC macro package. The third list is the wish
list, containing wishes expressed by the users of the package w.r.t.
desired additional functionality.

\section{Versions}
\begin{itemize}
\item Version 1.0, First public release, 1999/03/16.

Supports drawing of the following MSC constructs: MSC frame,
instances, messages (including self and env messages), coregions.
Includes some parameters for fine tuning of the drawing.

\item Version 1.1, Public release, 1999/03/24.

Minor bug fixes.
Additionally supports: timers (singular events), lost and found
messages, generalized ordering. Extra parameters:
\verb+\lostsymbolradius+, \verb+\timerwidth+. The macro
\verb+\setfootcolor+ replaces \verb+\setfootgrayness+, and the macro
\verb+\setmscvalues+ replaces \verb+\resetmsclengths+.
Some default values have been adjusted.

\item Version 1.2, Public release, 1999/03/29.

Minor bug fixes.
Code restructuring.
Additionally supports: Actions.\\
Extra parameters:
\verb+\actionheight+, \verb+\actionwidth+.

\item Version 1.3, Public release, 1999/04/10.

Minor bug fixes.
Additionally supports: Conditions, combined timer symbols, instance
stop.\\
Extra parameters:
\verb+\conditionheight+, \verb+\conditionoverlap+, \verb+\stopwidth+.
Leveloffset can be specified in \verb+nextlevel+ command.

\item Version 1.4, Public release, 1999/04/23.

Minor bug fixes.\\
Additionally supports: Instance creation, MSC references, and inline
expressions.\\
Extra parameters:
\verb+\referenceoverlap+, \verb+\inlineoverlap+, \verb+\stopwidth+.\\
Adjustment of default values. There are now three sizes
(large/normal/small) instead of two. The middle size is now default.\\
New command \verb+\setmscscale+ to scale the complete MSC up/down.



\item Version 1.10, Public release, 2002/04/10.

Major improvements: support for two new types of diagrams: High-level
MSCs and MSC documents. Additional MSC constructs: fat (double line)
instances, gates, time measurements, comments, instance regions
(activation, suspension, and co-regions), method replies (dashed
message arrows). Left and right overlap of inline expressions and MSC
references in an MSC diagram can be specified separately.

Reference manual. For a list of (all) commands and lengths, see
reference manual.

Package now also available at CTAN.

\item Version 1.10a, Public release, 2002/04/11.

Minor bug fixes.\\ 
The email addresses and websites mentioned in the files have been
corrected (if necessary).

The problem with the german package (german.sty) has been solved. This
bug was found by Christian Kaeunicke. The german package redefines the
meaning of the " symbol in order to type german texts more
efficiently. However, this was not compatible with the msc package
(before version 1.10a), because it uses the " symbol in
(error)-messages. The new version (1.10a) uses the ' symbol instead of
the " symbol. This seems to solve the problem with the german
package. However, there are probably packages assigning special
meaning to the ' symbol and which will therefore not work properly
with the msc package.

\item Version 1.11, Public release, 2002/06/06.

Minor bug fix.\\ The \verb+\stepcounter+ problem that occurred while
using the MSC Macro Package together with overlays (slides) is solved.

\item Version 1.12, beta release, 2002/06/18.

In this version, the user has more control over the positioning of
message labels. Implementation not finished yet.

\item Version 1.13, beta release, 2002/06/27.

The label positioning of version 1.12 is reimplemented. In fact, the
implementation of messages is rewritten completely. The same method to
compute the location of labels is used in \verb+\mess+, \verb+create+,
\verb+lost+, and \verb+found+. The new implementation is backward
compatible, meaning that old documents using the MSC Macro Package
will still look the same.

In addition, the bounding box bug is partly fixed. An \verb+\fbox+ is
drawn around each msc, hmsc, and mscdoc diagram. This enables dvips to
compute the right bounding box. Since the \verb+\fbox+ is drawn in
white, there is no visible result as long as the background is white,
too. A consequence of this bug fix is that the MSC Macro package
requires the \textsf{color} package. Just like the other required
packages, \textsf{pstricks}, \textsf{calc}, and \textsf{ifthen}, this
is a standard \LaTeXe{} package.

\item Version 1.14, Public release, 2004/03/15.

This version fixes a bug in the drawing routine of messages. In
earlier versions, the arrow heads of messages were sometimes
positioned at the center of an instance axis, even though the instance
was an activation region.

\end{itemize}

\section{Bugs}
The MSC macro package contains numerous bugs (and hidden features).
As of now, these are the only ones that have revealed themselves in public.

\begin{itemize}

\item Some starred versions of commands of the MSC Macro package do
not cooperate with the \textsf{amsbsy} package. The problem is that
the latter package redefined the macro \verb+\@ifstar+. This bug was
dicovered by Sjouke Mauw.

\item The size of msc diagrams is computed incorrectly. After
generating an eps file (dvips -E) from a dvi file containing exactly
one msc diagram, the diagram is clipped incorrectly. This bug was
dicovered by Tim Willemse.

\item There are \LaTeX{} packages that assign special meaning to some
characters. Consequently, the  MSC Macro package might not function properly
with such packages. Since we cannot anticipate on these semantical
changes of symbols, we don't know of a good solution to it. However,
we try to find solutions for these problems if they originated from
packages that are in the standard \LaTeX{} distribution.

A concrete example was the \textsf{german} package, as pointed out by
Christian Kaeunicke. This package assigns special meaning to the "
symbol. If you issue \verb+\usepackage{german}+ \emph{before}
\verb+\usepackage{msc}+, you will get an error as soon as your first
msc diagram is compiled. As Christian also mentioned, the error does
not occur if the import order of the packages is reversed.

As of MSC Macro package version 1.10a, this concrete bug with the
\textsf{german} package has been solved and the order between
\textsf{msc} and \textsf{german} is not restricted anymore.

\item The MSC Macro Package (version $\leq 1.10a$) crashes with the
overlay environment of the slides document class. The bug is due to a
redefinition of the \verb+\refstepcounter+ macro by the slides
documentclass.  This bug was discovered by Volker Stolz. He and Markus
Mohnen proposed a solution: increase the counters used by the MSC
macro package manually. In Version~1.11 this solution is
implemented. Thanks Volker and Markus!

\item The MSC Macro Package (version $\leq 1.13$) sometimes draws
arrow heads at the wrong place. Paulo S\'ergio Almeida discovered this
for messages drawn from right to left and for which the receiver
instance is an activation region. In fact, as Paulo noticed, the
manual contains an example of this bug, see Section~6.12 of the
manual. He also provided some \LaTeX{} code to fix the big. In
version~1.14, this code replaces the erroneous code.

\end{itemize}

\section{Wishes}
\begin{itemize}

\item Make the parameters of the MSC Macro package more
consistent. For example, the \verb+\mess+ macro and the
\verb+\measure+ have similar positioning parameters, but they cannot
have the same values. (V. Bos 2002/06/16)

\item Add a section to the user manual describing how to generate
other formats (like html, PostScript, pdf).  (S. Mauw 2002/06/14)

\item Add to the user manual a figure describing the various HMSC lengths.
      (S. Mauw 2002/06/14)

\item Add automatic resizing of action symbols, as described in one of
the tricks in the reference manual.  (S. Mauw 2002/06/14)

\item Add UML extensions to the MSC Macro package. Describe clearly
which UML diagrams we support.(S. Mauw, 2002/06/13)

\item Add option to messages to determine relative position of
label. S. Mauw (sjouke@win.tue.nl), 1999/04/15.

\item A possibility to change the color of instance regions. V. Bos
(09/04/2002).

\end{itemize}

\end{document}
