From 0f85f23c4357dafc839d1134885ada4c98071d30 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 13 May 2022 21:37:05 +0000 Subject: msc (13may22) git-svn-id: svn://tug.org/texlive/trunk@63291 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/msc/COPYRIGHT.txt | 17 +- Master/texmf-dist/doc/latex/msc/README | 42 - Master/texmf-dist/doc/latex/msc/README.txt | 16 + Master/texmf-dist/doc/latex/msc/biblio.bib | 76 + Master/texmf-dist/doc/latex/msc/maintenance.pdf | Bin 61584 -> 0 bytes Master/texmf-dist/doc/latex/msc/maintenance.tex | 250 -- Master/texmf-dist/doc/latex/msc/manual-macros.tex | 1003 ++++++++ Master/texmf-dist/doc/latex/msc/manual.pdf | Bin 229228 -> 0 bytes Master/texmf-dist/doc/latex/msc/manual.tex | 2841 --------------------- Master/texmf-dist/doc/latex/msc/msc.pdf | Bin 0 -> 338165 bytes Master/texmf-dist/doc/latex/msc/msc.tex | 2299 +++++++++++++++++ Master/texmf-dist/doc/latex/msc/refman.pdf | Bin 154934 -> 0 bytes Master/texmf-dist/doc/latex/msc/refman.tex | 1547 ----------- 13 files changed, 3399 insertions(+), 4692 deletions(-) delete mode 100644 Master/texmf-dist/doc/latex/msc/README create mode 100644 Master/texmf-dist/doc/latex/msc/README.txt create mode 100644 Master/texmf-dist/doc/latex/msc/biblio.bib delete mode 100644 Master/texmf-dist/doc/latex/msc/maintenance.pdf delete mode 100644 Master/texmf-dist/doc/latex/msc/maintenance.tex create mode 100644 Master/texmf-dist/doc/latex/msc/manual-macros.tex delete mode 100644 Master/texmf-dist/doc/latex/msc/manual.pdf delete mode 100644 Master/texmf-dist/doc/latex/msc/manual.tex create mode 100644 Master/texmf-dist/doc/latex/msc/msc.pdf create mode 100644 Master/texmf-dist/doc/latex/msc/msc.tex delete mode 100644 Master/texmf-dist/doc/latex/msc/refman.pdf delete mode 100644 Master/texmf-dist/doc/latex/msc/refman.tex (limited to 'Master/texmf-dist/doc/latex') diff --git a/Master/texmf-dist/doc/latex/msc/COPYRIGHT.txt b/Master/texmf-dist/doc/latex/msc/COPYRIGHT.txt index 3d7872812d5..c3b3d06a8b6 100644 --- a/Master/texmf-dist/doc/latex/msc/COPYRIGHT.txt +++ b/Master/texmf-dist/doc/latex/msc/COPYRIGHT.txt @@ -1,8 +1,7 @@ %% MSC Macro Package %% msc.sty -%% June 2, 2008 %% -%% Copyright 2008 V. Bos, T. van Deursen, and S. Mauw +%% Copyright 2022 V. Bos, T. van Deursen, and S. Mauw % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -14,18 +13,12 @@ % % This work has the LPPL maintenance status `maintained'. % -% The Current Maintainer of this work is T. van Deursen. +% The Current Maintainer of this work is Reynaldo Gil Pons. % % This program consists of the files % msc.sty % manual.tex -% manual.pdf -% refman.tex -% refman.pdf +% manual_macros.tex % biblio.bib -% maintenance.tex -% maintenance.pdf -% README -% COPYRIGHT - - +% README.txt +% COPYRIGHT.txt diff --git a/Master/texmf-dist/doc/latex/msc/README b/Master/texmf-dist/doc/latex/msc/README deleted file mode 100644 index 5388eceb50e..00000000000 --- a/Master/texmf-dist/doc/latex/msc/README +++ /dev/null @@ -1,42 +0,0 @@ -MSC Macro Package ------------------ -Version 1.16 -June 2, 2008 - ----------------------------------------------------------------------- -Copyright 2008 V. Bos, T. van Deursen, and S. Mauw - -This work may be distributed and/or modified under the -conditions of the LaTeX Project Public License, either version 1.3 -of this license or (at your option) any later version. -The latest version of this license is in - http://www.latex-project.org/lppl.txt -and version 1.3 or later is part of all distributions of LaTeX -version 2005/12/01 or later. - -This program consists of the files - msc.sty - manual.tex - manual.pdf - refman.tex - refman.pdf - biblio.bib - maintenance.tex - maintenance.pdf - README - COPYRIGHT - ----------------------------------------------------------------------- - -The MSC macro package is a LaTeX2e package to draw MSC diagrams. See -user manual (manual.pdf) and reference manual (refman.pdf) for more -information. - -Contact address: -Ton van Deursen -Universit\'e du Luxembourg -Facult\'e des Sciences, de la Technologie et de la Communication -6, rue Richard Coudenhove-Kalergi -L-1359 Luxembourg -Email: ton.vandeursen@uni.lu -Updates via: http://satoss.uni.lu/mscpackage/ diff --git a/Master/texmf-dist/doc/latex/msc/README.txt b/Master/texmf-dist/doc/latex/msc/README.txt new file mode 100644 index 00000000000..1f7ee0326e9 --- /dev/null +++ b/Master/texmf-dist/doc/latex/msc/README.txt @@ -0,0 +1,16 @@ +MSC Macro Package +----------------- +Version 2.00 +May 13, 2022 +---------------------------------------------------------------------- +The MSC macro package is a LaTeX2e package to draw MSC diagrams. See +user manual (manual.pdf) for more information. +---------------------------------------------------------------------- +Contact address: +Reynaldo Gil Pons +Université du Luxembourg +Maison du Nombre +6 Av. de la Fonte +L-4364 Esch-sur-Alzette +Email: reynaldo.gilpons@uni.lu +Website: http://satoss.uni.lu/mscpackage/ diff --git a/Master/texmf-dist/doc/latex/msc/biblio.bib b/Master/texmf-dist/doc/latex/msc/biblio.bib new file mode 100644 index 00000000000..a992bdb59d7 --- /dev/null +++ b/Master/texmf-dist/doc/latex/msc/biblio.bib @@ -0,0 +1,76 @@ +@InProceedings{RudolphGrabowskiGraubmann96, + author = {E. Rudolph and P.Graubmann and J. Grabowski}, + title = {Tutorial on Message Sequence Charts {(MSC'96})}, + booktitle = {FORTE}, + year = 1996 +} + +@Booklet{z120, + title = {{ITU-TS} {R}ecommendation {Z.120}: {M}essage {S}equence {C}hart {(MSC)}}, + author = {ITU-TS}, + address = {Geneva}, + year = 1997 +} + +@Book{GSM97, + AUTHOR = {Michel Goossens and Sebastian Rahtz and Frank Mittelbach}, + TITLE = {{T}he {\LaTeX} {G}raphics {C}ompanion}, + PUBLISHER = "Addison-Wesley", + YEAR = 1997 +} + + +@Book{Lam94, + author = {L. Lamport}, + title = {{\LaTeX}---A Document Preparation System---User's Guide and Reference Manual}, + publisher = {Adsison-Wesley}, + year = 1994, + edition = {2nd}, + note = {Updated for {\LaTeXe}} +} + +@Manual{BM02, + title = {A {\LaTeX{}} macro package for Message Sequence + Charts---Reference Manual---Describing {\mscpack} + version~{\mscversion}}, + author = {V. Bos and T. van Deursen and S. Mauw}, + year = {2010}, + month = {December}, + note = {Included in MSC macro package distribution} +} + +@Manual{BM02a, + title = {A {\LaTeX{}} macro package for Message Sequence + Charts---User Manual---Describing {\mscpack} + version~{\mscversion}}, + author = {V. Bos and T. van Deursen and S. Mauw}, + year = {2010}, + month = {January}, + note = {Included in MSC macro package distribution} +} + +@Manual{BM02b, + title = {A {\LaTeX{}} macro package for Message Sequence + Charts---Maintenance document---Describing {\mscpack} + version~{\mscversion}}, + author = {V. Bos and T. van Deursen and S. Mauw}, + year = {2010}, + month = {January}, + note = {Included in MSC macro package distribution} +} + +@article{mertz2007graphics, + title={Graphics with TikZ}, + author={Mertz, Andrew and Slough, William}, + journal={The PracTEX Journal}, + volume={1}, + year={2007} +} + +@manual{tantau2022pgf, + author = {Till Tantau}, + title = {The TikZ and PGF Packages}, + subtitle = {Manual for version 3.1.9a}, + url = {https://github.com/pgf-tikz/pgf/releases/download/3.1.9a/pgfmanual-3.1.9a.pdf}, + date = {2022-05-13}, +} \ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/msc/maintenance.pdf b/Master/texmf-dist/doc/latex/msc/maintenance.pdf deleted file mode 100644 index c050ebe05b0..00000000000 Binary files a/Master/texmf-dist/doc/latex/msc/maintenance.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/msc/maintenance.tex b/Master/texmf-dist/doc/latex/msc/maintenance.tex deleted file mode 100644 index 3e49133c6ee..00000000000 --- a/Master/texmf-dist/doc/latex/msc/maintenance.tex +++ /dev/null @@ -1,250 +0,0 @@ -% file: maintenance.tex -% Copyright 2008 V. Bos, T. van Deursen, and S. Mauw -% This file is part of the MSC Macro Package. -% -\documentclass{article} -\usepackage{a4wide} -\usepackage{msc} - -\title{ - A {\LaTeX{}} macro package for Message Sequence Charts---Maintenance - document -} - - -\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{victor.bos@ssf.fi} & - \scriptsize \texttt{ton.vandeursen@uni.lu} & - \scriptsize \texttt{sjouke.mauw@uni.lu} - \end{tabular}\\ - \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://satoss.uni.lu/mscpackage/+. - -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.16, beta release, 2008/06/02 - -The MSC package used old \verb+PSTricks+-syntax of the \verb+\scalebox+ -command. To prevent mismatches with the \verb+graphicx+ package, this -macro was renamed to \verb+\psscalebox+. - -The \verb+action+ and \verb+condition+ macros are extended with a -starred version, which automatically adjust the size of the rectangle -and hexagon based on the size of the contents. - -Name and address information has been updated. - -\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.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.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.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.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.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.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.2, Public release, 1999/03/29. - -Minor bug fixes. -Code restructuring. -Additionally supports: Actions.\\ -Extra parameters: -\verb+\actionheight+, \verb+\actionwidth+. - -\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.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. - -\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! - -\end{itemize} - -\section{Wishes} -\begin{itemize} - -\item Split MSCs over multiple pages (T. van Deursen, 2008/02/18) - -\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 A possibility to change the color of instance regions. V. Bos -(2002/04/09). - -\item Add option to messages to determine relative position of -label. (S. Mauw 1999/04/15). - -\end{itemize} - -\end{document} diff --git a/Master/texmf-dist/doc/latex/msc/manual-macros.tex b/Master/texmf-dist/doc/latex/msc/manual-macros.tex new file mode 100644 index 00000000000..b3caf71c78b --- /dev/null +++ b/Master/texmf-dist/doc/latex/msc/manual-macros.tex @@ -0,0 +1,1003 @@ +% \newcommand{\cmd}[1]{\texttt{\bslash #1}} + +\newcommand{\acro}[1]{{#1}} + +\newcommand{\MSC}{\acro{MSC}} +\newcommand{\HMSC}{\acro{HMSC}} +\newcommand{\MSCdoc}{\MSC{}doc} +\newcommand{\mscpack}{\MSC{} macro package} +% \newcommand{\env}[1]{\texttt{#1}} +\newcommand{\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}} +\newcommand{\tikzname}{Ti\emph{k}Z} +\newcommand{\beamer}{\textsc{beamer}} +\newcommand{\pdf}{\textsc{pdf}} +\newcommand{\eps}{\texttt{eps}} +\newcommand{\pgfname}{\textsc{pgf}} +% \newcommand{\prosper}{\textsc{prosper}} +% \newcommand{\seminar}{\textsc{seminar}} +% \newcommand{\texpower}{\textsc{texpower}} +% \newcommand{\foils}{\textsc{foils}} + +% \providecommand\href[2]{\texttt{#1}} +% \providecommand\hypertarget[2]{\texttt{#1}} +% \providecommand\hyperlink[2]{\texttt{#1}} + + +\colorlet{examplefill}{yellow!80!black} +\definecolor{graphicbackground}{rgb}{1,1,1} +\definecolor{codebackground}{rgb}{0.90,0.90,1} + +\newenvironment{pgfmanualentry}{\par\vspace*{-8pt}\list{}{\leftmargin=2em\itemindent-\leftmargin\def\makelabel##1{\hss##1}}}{\endlist\par\vspace*{-8pt}} +\newcommand\pgfmanualentryheadline[1]{\itemsep=0pt\parskip=0pt\item\strut{#1}\par\topsep=0pt} +\newcommand\pgfmanualbody{\parskip3pt\vspace*{-3pt}} + + + +\newenvironment{pgflayout}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{\texttt{\string\pgfpagesuselayout\char`\{\declare{#1}\char`\}}\oarg{options}} + \index{#1@\protect\texttt{#1} layout}% + \index{Page layouts!#1@\protect\texttt{#1}}% + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + + +\newenvironment{command}[1]{ + \begin{pgfmanualentry} + \extractcommand#1\@@ + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{commandlist}[1]{% + \begin{pgfmanualentry} + \foreach \xx in {#1} {% + \expandafter\extractcommand\xx\@@ + }% + \pgfmanualbody +}{% + \end{pgfmanualentry} +}% + +% \begin{internallist}[register]{\pgf@xa} +% \end{internallist} +% +% \begin{internallist}[register]{\pgf@xa,\pgf@xb} +% \end{internallist} +\newenvironment{internallist}[2][register]{% + \begin{pgfmanualentry} + \foreach \xx in {#2} {% + \expandafter\extractinternalcommand\expandafter{\xx}{#1}% + }% + \pgfmanualbody +}{% + \end{pgfmanualentry} +}% +\def\extractinternalcommand#1#2{% + \pgfmanualentryheadline{Internal #2 \declare{\texttt{\string#1}}}% + \removeats{#1}% + \index{Internals!\strippedat @\protect\myprintocmmand{\strippedat}}% + \index{\strippedat @\protect\myprintocmmand{\strippedat}}% + \pgfmanualpdflabel{\textbackslash\strippedat}{}% +} + +%% MW: START MATH MACROS +\def\mvar#1{{\ifmmode\textrm{\textit{#1}}\else\rmfamily\textit{#1}\fi}} + +\makeatletter + +\def\extractmathfunctionname#1{\extractmathfunctionname@#1(,)\tmpa\tmpb} +\def\extractmathfunctionname@#1(#2)#3\tmpb{\def\mathname{#1}} + +\makeatother + +\newenvironment{math-function}[1]{ + \def\mathdefaultname{#1} + \extractmathfunctionname{#1} + \edef\mathurl{{math:\mathname}}\expandafter\hypertarget\expandafter{\mathurl}{}% + \begin{pgfmanualentry} + \pgfmanualentryheadline{\texttt{#1}}% + \index{\mathname @\protect\texttt{\mathname} math function}% + \index{Math functions!\mathname @\protect\texttt{\mathname}}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\def\pgfmanualemptytext{} +\def\pgfmanualvbarvbar{\char`\|\char`\|} + +\newenvironment{math-operator}[4][]{% + \begin{pgfmanualentry} + \csname math#3operator\endcsname{#2}{#4} + \def\mathtest{#4}% + \ifx\mathtest\pgfmanualemptytext% + \def\mathtype{(#3 operator)} + \else% + \def\mathtype{(#3 operator; uses the \texttt{#4} function)} + \fi% + \pgfmanualentryheadline{\mathexample\hfill\mathtype}% + \def\mathtest{#1}% + \ifx\mathtest\pgfmanualemptytext% + \index{#2@\protect\texttt{#2} #3 math operator}% + \index{Math operators!#2@\protect\texttt{#2}}% + \fi% + \pgfmanualbody +} +{\end{pgfmanualentry}} + +\newenvironment{math-operators}[5][]{% + \begin{pgfmanualentry} + \csname math#4operator\endcsname{#2}{#3} + \def\mathtest{#5}% + \ifx\mathtest\pgfmanualemptytext% + \def\mathtype{(#4 operators)} + \else% + \def\mathtype{(#4 operators; use the \texttt{#5} function)} + \fi% + \pgfmanualentryheadline{\mathexample\hfill\mathtype}% + \def\mathtest{#1}% + \ifx\mathtest\pgfmanualemptytext% + \index{#2#3@\protect\texttt{#2\protect\ #3} #4 math operators}% + \index{Math operators!#2#3@\protect\texttt{#2\protect\ #3}}% + \fi% + \pgfmanualbody +} +{\end{pgfmanualentry}} + +\def\mathinfixoperator#1#2{% + \def\mathoperator{\texttt{#1}}% + \def\mathexample{\mvar{x}\space\texttt{#1}\space\mvar{y}}% +} + +\def\mathprefixoperator#1#2{% + \def\mathoperator{\texttt{#1}}% + \def\mathexample{\texttt{#1}\mvar{x}}% +} + +\def\mathpostfixoperator#1#2{% + \def\mathoperator{\texttt{#1}} + \def\mathexample{\mvar{x}\texttt{#1}}% +} + +\def\mathgroupoperator#1#2{% + \def\mathoperator{\texttt{#1\ #2}}% + \def\mathexample{\texttt{#1}\mvar{x}\texttt{#2}}% +} + +\expandafter\let\csname matharray accessoperator\endcsname=\mathgroupoperator +\expandafter\let\csname matharrayoperator\endcsname=\mathgroupoperator + +\def\mathconditionaloperator#1#2{% + \def\mathoperator{#1\space#2} + \def\mathexample{\mvar{x}\ \texttt{#1}\ \mvar{y}\ {\texttt{#2}}\ \mvar{z}} +} + +\newcommand\mathcommand[1][\mathdefaultname]{% + \expandafter\makemathcommand#1(\empty)\stop% + \expandafter\extractcommand\mathcommandname\@@% + \medskip +} +\makeatletter + +\def\makemathcommand#1(#2)#3\stop{% + \expandafter\def\expandafter\mathcommandname\expandafter{\csname pgfmath#1\endcsname}% + \ifx#2\empty% + \else% + \@makemathcommand#2,\stop, + \fi} +\def\@makemathcommand#1,{% + \ifx#1\stop% + \else% + \expandafter\def\expandafter\mathcommandname\expandafter{\mathcommandname{\ttfamily\char`\{#1\char`\}}}% + \expandafter\@makemathcommand% + \fi} +\makeatother + +\def\calcname{\textsc{calc}} +%% MW: END MATH MACROS + + +\def\extractcommand#1#2\@@{% + \pgfmanualentryheadline{\declare{\texttt{\string#1}}#2}% + \removeats{#1}% + \index{\strippedat @\protect\myprintocmmand{\strippedat}} + \pgfmanualpdflabel{\textbackslash\strippedat}{}% +} + + +% \begin{environment}{{name}\marg{arguments}} +\newenvironment{environment}[1]{ + \begin{pgfmanualentry} + \extractenvironement#1\@@ + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\def\extractenvironement#1#2\@@{% + \pgfmanualentryheadline{{\ttfamily\char`\\begin\char`\{\declare{#1}\char`\}}#2}% + \pgfmanualentryheadline{{\ttfamily\ \ }\meta{environment contents}}% + \pgfmanualentryheadline{{\ttfamily\char`\\end\char`\{\declare{#1}\char`\}}}% + \index{#1@\protect\texttt{#1} environment}% + \index{Environments!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% +} + + +\newenvironment{plainenvironment}[1]{ + \begin{pgfmanualentry} + \extractplainenvironement#1\@@ + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\def\extractplainenvironement#1#2\@@{% + \pgfmanualentryheadline{{\ttfamily\declare{\char`\\#1}}#2}% + \pgfmanualentryheadline{{\ttfamily\ \ }\meta{environment contents}}% + \pgfmanualentryheadline{{\ttfamily\declare{\char`\\end#1}}}% + \index{#1@\protect\texttt{#1} environment}% + \index{Environments!#1@\protect\texttt{#1}}% +} + + +\newenvironment{contextenvironment}[1]{ + \begin{pgfmanualentry} + \extractcontextenvironement#1\@@ + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\def\extractcontextenvironement#1#2\@@{% + \pgfmanualentryheadline{{\ttfamily\declare{\char`\\start#1}}#2}% + \pgfmanualentryheadline{{\ttfamily\ \ }\meta{environment contents}}% + \pgfmanualentryheadline{{\ttfamily\declare{\char`\\stop#1}}}% + \index{#1@\protect\texttt{#1} environment}% + \index{Environments!#1@\protect\texttt{#1}}} + + +\newenvironment{shape}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Shape {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} shape}% + \index{Shapes!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{shading}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Shading {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} shading}% + \index{Shadings!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + + +\newenvironment{dataformat}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Format {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} format}% + \index{Formats!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{handler}[1]{ + \begin{pgfmanualentry} + \extracthandler#1\@nil% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\def\gobble#1{} +\def\extracthandler#1#2\@nil{% + \pgfmanualentryheadline{Key handler \meta{key}{\ttfamily/\declare{#1}}#2}% + \index{\gobble#1@\protect\texttt{#1} handler}% + \index{Key handlers!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{/handlers/#1}% +} + + +\makeatletter + + +\newenvironment{stylekey}[1]{ + \begin{pgfmanualentry} + \def\extrakeytext{style, } + \extractkey#1\@nil% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\def\choicesep{$\vert$}% +\def\choicearg#1{\texttt{#1}} + +\newif\iffirstchoice + +% \mchoice{choice1,choice2,choice3} +\newcommand\mchoice[1]{% + \begingroup + \firstchoicetrue + \foreach \mchoice@ in {#1} {% + \iffirstchoice + \global\firstchoicefalse + \else + \choicesep + \fi + \choicearg{\mchoice@}% + }% + \endgroup +}% + +% \begin{key}{/path/x=value} +% \begin{key}{/path/x=value (initially XXX)} +% \begin{key}{/path/x=value (default XXX)} +\newenvironment{key}[1]{ + \begin{pgfmanualentry} + \def\extrakeytext{} + %\def\altpath{\emph{\color{gray}or}}% + \extractkey#1\@nil% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +% \insertpathifneeded{a key}{/pgf} -> assign mykey={/pgf/a key} +% \insertpathifneeded{/tikz/a key}{/pgf} -> assign mykey={/tikz/a key} +% +% #1: the key +% #2: a default path (or empty) +\def\insertpathifneeded#1#2{% + \def\insertpathifneeded@@{#2}% + \ifx\insertpathifneeded@@\empty + \def\mykey{#1}% + \else + \insertpathifneeded@#2\@nil + \ifpgfutil@in@ + \def\mykey{#2/#1}% + \else + \def\mykey{#1}% + \fi + \fi +}% +\def\insertpathifneeded@#1#2\@nil{% + \def\insertpathifneeded@@{#1}% + \def\insertpathifneeded@@@{/}% + \ifx\insertpathifneeded@@\insertpathifneeded@@@ + \pgfutil@in@true + \else + \pgfutil@in@false + \fi +}% + +% \begin{keylist}[default path] +% {/path/option 1=value,/path/option 2=value2} +% \end{keylist} +\newenvironment{keylist}[2][]{% + \begin{pgfmanualentry} + \def\extrakeytext{}% + \foreach \xx in {#2} {% + \expandafter\insertpathifneeded\expandafter{\xx}{#1}% + \expandafter\extractkey\mykey\@nil% + }% + \pgfmanualbody +}{% + \end{pgfmanualentry} +}% + +\def\extractkey#1\@nil{% + \pgfutil@in@={#1}% + \ifpgfutil@in@% + \extractkeyequal#1\@nil + \else% + \pgfutil@in@{(initial}{#1}% + \ifpgfutil@in@% + \extractequalinitial#1\@nil% + \else + \pgfmanualentryheadline{{\ttfamily\declare{#1}}\hfill(\extrakeytext no value)}% + \def\mykey{#1}% + \def\mypath{}% + \def\myname{}% + \firsttimetrue% + \decompose#1/\nil% + \fi + \fi% +} + +\def\extractkeyequal#1=#2\@nil{% + \pgfutil@in@{(default}{#2}% + \ifpgfutil@in@% + \extractdefault{#1}#2\@nil% + \else% + \pgfutil@in@{(initial}{#2}% + \ifpgfutil@in@% + \extractinitial{#1}#2\@nil% + \else + \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill(\extrakeytext no default)}% + \fi% + \fi% + \def\mykey{#1}% + \def\mypath{}% + \def\myname{}% + \firsttimetrue% + \decompose#1/\nil% +} + +\def\extractdefault#1#2(default #3)\@nil{% + \pgfmanualentryheadline{{\ttfamily\declare{#1}\opt{=}}\opt{#2}\hfill (\extrakeytext default {\ttfamily#3})}% +} + +\def\extractinitial#1#2(initially #3)\@nil{% + \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill (\extrakeytext no default, initially {\ttfamily#3})}% +} + +\def\extractequalinitial#1 (initially #2)\@nil{% + \pgfmanualentryheadline{{\ttfamily\declare{#1}}\hfill (\extrakeytext initially {\ttfamily#2})}% + \def\mykey{#1}% + \def\mypath{}% + \def\myname{}% + \firsttimetrue% + \decompose#1/\nil% +} + +% Introduces a key alias '/#1/' +% to be used inside of \begin{key} ... \end{key} +\def\keyalias#1{\vspace{-3pt}\item{\small alias {\ttfamily/#1/\myname}}\vspace{-2pt}\par + \pgfmanualpdflabel{/#1/\myname}{}% +} + +\newif\iffirsttime + +\makeatother + +\def\decompose/#1/#2\nil{% + \def\test{#2}% + \ifx\test\empty% + % aha. + \index{#1@\protect\texttt{#1} key}% + \index{\mypath#1@\protect\texttt{#1}}% + \def\myname{#1}% + \else% + \iffirsttime + \begingroup + % also make a pdf link anchor with full key path. + \def\hyperlabelwithoutslash##1/\nil{% + \pgfmanualpdflabel{##1}{}% + }% + \hyperlabelwithoutslash/#1/#2\nil + \endgroup + \def\mypath{#1@\protect\texttt{/#1/}!}% + \firsttimefalse + \else + \expandafter\def\expandafter\mypath\expandafter{\mypath#1@\protect\texttt{#1/}!}% + \fi + \def\firsttime{} + \decompose/#2\nil% + \fi% +} + +\def\indexkey#1{% + \def\mypath{}% + \decompose#1/\nil% +} + +\newenvironment{predefinedmethod}[1]{ + \begin{pgfmanualentry} + \extractpredefinedmethod#1\@nil + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} +\def\extractpredefinedmethod#1(#2)\@nil{% + \pgfmanualentryheadline{Method \declare{\ttfamily #1}\texttt(#2\texttt) \hfill(predefined for all classes)} + \index{#1@\protect\texttt{#1} method}% + \index{Methods!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% +} + + +\newenvironment{ooclass}[1]{ + \begin{pgfmanualentry} + \def\currentclass{#1} + \pgfmanualentryheadline{Class \declare{\texttt{#1}}} + \index{#1@\protect\texttt{#1} class}% + \index{Class #1@Class \protect\texttt{#1}}% + \index{Classes!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{method}[1]{ + \begin{pgfmanualentry} + \extractmethod#1\@nil + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} +\def\extractmethod#1(#2)\@nil{% + \def\test{#1} + \ifx\test\currentclass + \pgfmanualentryheadline{Constructor \declare{\ttfamily #1}\texttt(#2\texttt)} + \else + \pgfmanualentryheadline{Method \declare{\ttfamily #1}\texttt(#2\texttt)} + \fi + \index{#1@\protect\texttt{#1} method}% + \index{Methods!#1@\protect\texttt{#1}} + \index{Class \currentclass!#1@\protect\texttt{#1}}% + \pgfmanualpdflabel{#1}{}% +} + +\newenvironment{attribute}[1]{ + \begin{pgfmanualentry} + \extractattribute#1\@nil + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} +\def\extractattribute#1=#2;\@nil{% + \def\test{#2}% + \ifx\test\@empty + \pgfmanualentryheadline{Private attribute \declare{\ttfamily #1} \hfill (initially empty)} + \else + \pgfmanualentryheadline{Private attribute \declare{\ttfamily #1} \hfill (initially {\ttfamily #2})} + \fi + \index{#1@\protect\texttt{#1} attribute}% + \index{Attributes!#1@\protect\texttt{#1}} + \index{Class \currentclass!#1@\protect\texttt{#1}}% + \pgfmanualpdflabel{#1}{}% +} + + + +\newenvironment{predefinednode}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Predefined node {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} node}% + \index{Predefined node!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{coordinatesystem}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Coordinate system {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} coordinate system}% + \index{Coordinate systems!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{snake}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Snake {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} snake}% + \index{Snakes!#1@\protect\texttt{#1}} + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{decoration}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Decoration {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} decoration}% + \index{Decorations!#1@\protect\texttt{#1}} + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + + +\def\pgfmanualbar{\char`\|} +\makeatletter +\newenvironment{pathoperation}[3][]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\path}\ + \ \dots} + \declare{\texttt{#2}}#3\ \textcolor{gray}{\dots\texttt{;}}}% + \def\pgfmanualtest{#1}% + \ifx\pgfmanualtest\@empty% + \index{#2@\protect\texttt{#2} path operation}% + \index{Path operations!#2@\protect\texttt{#2}}% + \pgfmanualpdflabel{#2}{}% + \fi% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} +\newenvironment{datavisualizationoperation}[3][]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\datavisualization}\ + \ \dots} + \declare{\texttt{#2}}#3\ \textcolor{gray}{\dots\texttt{;}}}% + \def\pgfmanualtest{#1}% + \ifx\pgfmanualtest\@empty% + \index{#2@\protect\texttt{#2} (data visualization)}% + \index{Data visualization!#2@\protect\texttt{#2}}% + \pgfmanualpdflabel{#2}{}% + \fi% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} +\makeatother + +\def\extractcommand#1#2\@@{% + \pgfmanualentryheadline{\declare{\texttt{\string#1}}#2}% + \removeats{#1}% + \index{\strippedat @\protect\myprintocmmand{\strippedat}} + \pgfmanualpdflabel{\textbackslash\strippedat}{}% +} + + +\newenvironment{filedescription}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{File {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} file}% + \index{Packages and files!#1@\protect\texttt{#1}}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + + +\newenvironment{packageoption}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{{\ttfamily\char`\\usepackage[\declare{#1}]\char`\{pgf\char`\}}} + \index{#1@\protect\texttt{#1} package option}% + \index{Package options for \textsc{pgf}!#1@\protect\texttt{#1}}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + + + +\newcommand\opt[1]{{\color{black!50!green}#1}} +\newcommand\ooarg[1]{{\ttfamily[}\meta{#1}{\ttfamily]}} + +\def\pfgopt{\afterassignment\pgfmanualopt\let\next=} + + +{ + \makeatletter + \global\let\myempty=\@empty + \global\let\mygobble=\@gobble + \catcode`\@=12 + \gdef\getridofats#1@#2\relax{% + \def\getridtest{#2}% + \ifx\getridtest\myempty% + \expandafter\def\expandafter\strippedat\expandafter{\strippedat#1} + \else% + \expandafter\def\expandafter\strippedat\expandafter{\strippedat#1\protect\printanat} + \getridofats#2\relax% + \fi% + } + + \gdef\removeats#1{% + \let\strippedat\myempty% + \edef\strippedtext{\stripcommand#1}% + \expandafter\getridofats\strippedtext @\relax% + } + + \gdef\stripcommand#1{\expandafter\mygobble\string#1} +} + +\def\printanat{\char`\@} + +\def\declare{\afterassignment\pgfmanualdeclare\let\next=} +\def\pgfmanualdeclare{\ifx\next\bgroup\bgroup\color{red!75!black}\else{\color{red!75!black}\next}\fi} + + +\let\textoken=\command +\let\endtextoken=\endcommand + +\def\myprintocmmand#1{\texttt{\char`\\#1}} + +\def\example{\par\smallskip\noindent\textit{Example: }} +\def\themeauthor{\par\smallskip\noindent\textit{Theme author: }} + + +\def\indexoption#1{% + \index{#1@\protect\texttt{#1} option}% + \index{Graphic options and styles!#1@\protect\texttt{#1}}% +} + +\def\itemcalendaroption#1{\item \declare{\texttt{#1}}% + \index{#1@\protect\texttt{#1} date test}% + \index{Date tests!#1@\protect\texttt{#1}}% +} + +\makeatletter + +\ifx\scantokens\@undefined + \PackageError{pgfmanual-macros}{You need to use extended latex + (elatex) or (pdfelatex) to process this document}{} +\fi + +\begingroup +\catcode`|=0 +\catcode`[= 1 +\catcode`]=2 +\catcode`\{=12 +\catcode `\}=12 +\catcode`\\=12 |gdef|find@example#1\end{codeexample}[|endofcodeexample[#1]] +|endgroup + +% define \returntospace. +% +% It should define NEWLINE as {}, spaces and tabs as \space. +\begingroup +\catcode`\^=7 +\catcode`\^^M=13 +\catcode`\^^I=13 +\catcode`\ =13% +\gdef\returntospace{\catcode`\ =13\def {\space}\catcode`\^^I=13\def^^I{\space}} +\gdef\showreturn{\show^^M} +\endgroup + +\begingroup +\catcode`\%=13 +\catcode`\^^M=13 +\gdef\commenthandler{\catcode`\%=13\def%{\@gobble@till@return}} +\gdef\@gobble@till@return#1^^M{} +\gdef\@gobble@till@return@ignore#1^^M{\ignorespaces} +\gdef\typesetcomment{\catcode`\%=13\def%{\@typeset@till@return}} +\gdef\@typeset@till@return#1^^M{{\def%{\char`\%}\textsl{\char`\%#1}}\par} +\endgroup + +% Define tab-implementation functions +% \codeexample@tabinit@replacementchars@ +% and +% \codeexample@tabinit@catcode@ +% +% They should ONLY be used in case that tab replacement is active. +% +% This here is merely a preparation step. +% +% Idea: +% \codeexample@tabinit@catcode@ will make TAB active +% and +% \codeexample@tabinit@replacementchars@ will insert as many spaces as +% /codeexample/tabsize contains. +{ +\catcode`\^^I=13 +% ATTENTION: do NOT use tabs in these definitions!! +\gdef\codeexample@tabinit@replacementchars@{% + \begingroup + \count0=\pgfkeysvalueof{/codeexample/tabsize}\relax + \toks0={}% + \loop + \ifnum\count0>0 + \advance\count0 by-1 + \toks0=\expandafter{\the\toks0\ }% + \repeat + \xdef\codeexample@tabinit@replacementchars@@{\the\toks0}% + \endgroup + \let^^I=\codeexample@tabinit@replacementchars@@ +}% +\gdef\codeexample@tabinit@catcode@{\catcode`\^^I=13}% +}% + +% Called after any options have been set. It assigns +% \codeexample@tabinit@catcode +% and +% \codeexample@tabinit@replacementchars +% which are used inside of +%\begin{codeexample} +% ... +%\end{codeexample} +% +% \codeexample@tabinit@catcode is either \relax or it makes tab +% active. +% +% \codeexample@tabinit@replacementchars is either \relax or it inserts +% a proper replacement sequence for tabs (as many spaces as +% configured) +\def\codeexample@tabinit{% + \ifnum\pgfkeysvalueof{/codeexample/tabsize}=0\relax + \let\codeexample@tabinit@replacementchars=\relax + \let\codeexample@tabinit@catcode=\relax + \else + \let\codeexample@tabinit@catcode=\codeexample@tabinit@catcode@ + \let\codeexample@tabinit@replacementchars=\codeexample@tabinit@replacementchars@ + \fi +} + +\pgfqkeys{/codeexample}{% + width/.code= {\setlength\codeexamplewidth{#1}}, + graphic/.code= {\colorlet{graphicbackground}{#1}}, + code/.code= {\colorlet{codebackground}{#1}}, + execute code/.is if=code@execute, + code only/.code= {\code@executefalse}, + pre/.store in=\code@pre, + post/.store in=\code@post, + % #1 is the *complete* environment contents as it shall be + % typeset. In particular, the catcodes are NOT the normal ones. + typeset listing/.code= {#1}, + render instead/.store in=\code@render, + vbox/.code= {\def\code@pre{\vbox\bgroup\setlength{\hsize}{\linewidth-6pt}}\def\code@post{\egroup}}, + ignorespaces/.code= {\let\@gobble@till@return=\@gobble@till@return@ignore}, + leave comments/.code= {\def\code@catcode@hook{\catcode`\%=12}\let\commenthandler=\relax\let\typesetcomment=\relax}, + tabsize/.initial=0,% FIXME : this here is merely used for indentation. It is just a TAB REPLACEMENT. + every codeexample/.style={width=4cm+7pt}, +} + +\let\code@pre\pgfutil@empty +\let\code@post\pgfutil@empty +\let\code@render\pgfutil@empty +\def\code@catcode@hook{} + +\newdimen\codeexamplewidth +\newif\ifcode@execute +\newbox\codeexamplebox +\def\codeexample[#1]{% + \begingroup% + \code@executetrue + \pgfqkeys{/codeexample}{every codeexample,#1}% + \codeexample@tabinit% assigns \codeexample@tabinit@[catcode,replacementchars] + \parindent0pt + \begingroup% + \par% + \medskip% + \let\do\@makeother% + \dospecials% + \obeylines% + \@vobeyspaces% + \catcode`\%=13% + \catcode`\^^M=13% + \code@catcode@hook% + \codeexample@tabinit@catcode + \relax% + \find@example} +\def\endofcodeexample#1{% + \endgroup% + \ifcode@execute% + \setbox\codeexamplebox=\hbox{% + \ifx\code@render\pgfutil@empty% + {% + {% + \returntospace% + \commenthandler% + \xdef\code@temp{#1}% removes returns and comments + }% + \catcode`\^^M=9% + \colorbox{graphicbackground}{\color{black}\ignorespaces% + \code@pre\expandafter\scantokens\expandafter{\code@temp\ignorespaces}\code@post\ignorespaces}% + }% + \else% + \colorbox{graphicbackground}{\color{black}\ignorespaces% + \code@render}% + \fi% + }% + \ifdim\wd\codeexamplebox>\codeexamplewidth% + \def\code@start{\par}% + \def\code@flushstart{}\def\code@flushend{}% + \def\code@mid{\parskip2pt\par\noindent}% + \def\code@width{\linewidth-6pt}% + \def\code@end{}% + \else% + \def\code@start{% + \linewidth=\textwidth% + \parshape \@ne 0pt \linewidth + \leavevmode% + \hbox\bgroup}% + \def\code@flushstart{\hfill}% + \def\code@flushend{\hbox{}}% + \def\code@mid{\hskip6pt}% + \def\code@width{\linewidth-12pt-\codeexamplewidth}% + \def\code@end{\egroup}% + \fi% + \code@start% + \noindent% + \begin{minipage}[t]{\codeexamplewidth}\raggedright + \hrule width0pt% + \footnotesize\vskip-1em% + \code@flushstart\box\codeexamplebox\code@flushend% + \vskip-1ex + \leavevmode% + \end{minipage}% + \else% + \def\code@mid{\par} + \def\code@width{\linewidth-6pt} + \def\code@end{} + \fi% + \code@mid% + \colorbox{codebackground}{% + \begin{minipage}[t]{\code@width}% + {% + \let\do\@makeother + \dospecials + \frenchspacing\@vobeyspaces + \normalfont\ttfamily\footnotesize + \typesetcomment% + \codeexample@tabinit@replacementchars + \@tempswafalse + \def\par{% + \if@tempswa + \leavevmode \null \@@par\penalty\interlinepenalty + \else + \@tempswatrue + \ifhmode\@@par\penalty\interlinepenalty\fi + \fi}% + \obeylines + \everypar \expandafter{\the\everypar \unpenalty}% + \pgfkeysvalueof{/codeexample/typeset listing/.@cmd}{#1}\pgfeov + } + \end{minipage}}% + \code@end% + \par% + \medskip + \end{codeexample} +} + +\def\endcodeexample{\endgroup} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "beameruserguide" +%%% End: diff --git a/Master/texmf-dist/doc/latex/msc/manual.pdf b/Master/texmf-dist/doc/latex/msc/manual.pdf deleted file mode 100644 index 9cc6c420cf4..00000000000 Binary files a/Master/texmf-dist/doc/latex/msc/manual.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/msc/manual.tex b/Master/texmf-dist/doc/latex/msc/manual.tex deleted file mode 100644 index d6025770fe4..00000000000 --- a/Master/texmf-dist/doc/latex/msc/manual.tex +++ /dev/null @@ -1,2841 +0,0 @@ -% file: manual.tex -% Copyright 2008 V. Bos, T. van Deursen, and S. Mauw -% This file is part of the MSC Macro Package. -% -\documentclass[12pt,a4paper]{article} -\usepackage{a4wide} -\usepackage{url} -\usepackage{moreverb} -\usepackage{multicol} -\usepackage{msc} - -% we allow a ragged right -\setlength{\rightskip}{0pt plus 0.05\linewidth minus 0pt} - - - - - -\newlength{\rpwidth} -\setlength{\rpwidth}{.5cm} -\newlength{\rpheight} -\setlength{\rpheight}{0.5\levelheight} -\newcommand{\rpN}{% - \psframe(-0.5\rpwidth,-\rpheight)(0.5\rpwidth,0\rpheight)% - \rput[B](0\rpwidth,-0.8\rpheight){\tiny \textsc{n}}% - \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% -} -\newcommand{\rpNE}{% - \psframe(-\rpwidth,-\rpheight)(0\rpwidth,0\rpheight)% - \rput[B](-.5\rpwidth,-0.8\rpheight){\tiny \textsc{ne}}% - \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% -} -\newcommand{\rpE}{% - \psframe(-\rpwidth,-.5\rpheight)(0\rpwidth,.5\rpheight)% - \rput[B](-.5\rpwidth,-0.3\rpheight){\tiny \textsc{e}}% - \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% -} -\newcommand{\rpSE}{% - \psframe(-\rpwidth,0\rpheight)(0\rpwidth,\rpheight)% - \rput[B](-.5\rpwidth,0.2\rpheight){\tiny \textsc{se}}% - \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% -} -\newcommand{\rpS}{% - \psframe(-.5\rpwidth,\rpheight)(.5\rpwidth,0\rpheight)% - \rput[t](0\rpwidth,0.8\rpheight){\tiny \textsc{s}}% - \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% -} -\newcommand{\rpSW}{% - \psframe(0\rpwidth,0\rpheight)(\rpwidth,\rpheight)% - \rput[B](.5\rpwidth,0.2\rpheight){\tiny \textsc{sw}}% - \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% -} -\newcommand{\rpW}{% - \psframe(0\rpwidth,-.5\rpheight)(\rpwidth,.5\rpheight)% - \rput[B](.5\rpwidth,-0.3\rpheight){\tiny \textsc{w}}% - \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% -} -\newcommand{\rpNW}{% - \psframe(0\rpwidth,-\rpheight)(\rpwidth,0\rpheight)% - \rput[B](.5\rpwidth,-0.8\rpheight){\tiny \textsc{nw}}% - \pscircle[fillstyle=solid,fillcolor=black](0\rpwidth,0\rpheight){.5\labeldist}% -} - - - - - -% The following code is taken from the doc package. It defines a global -% macro \bslash that produces a bslash (if present in the current font). -\makeatletter -{\catcode`\|=\z@ \catcode`\\=12 |gdef|bslash{\}} -\makeatother -\newcommand{\cmd}[1]{\texttt{\bslash #1}} - -\newcommand{\acro}[1]{{#1}} - -\newcommand{\MSC}{\acro{MSC}} -\newcommand{\HMSC}{\acro{HMSC}} -\newcommand{\MSCdoc}{\MSC{}doc} -\newcommand{\mscpack}{\MSC{} macro package} - -\newcommand{\env}[1]{\texttt{#1}} -\newcommand{\opt}[1]{[#1]} -\newcommand{\cmdarg}[1]{\{\emph{#1}\}} -\newcommand{\coordarg}[1]{\emph{#1}} -\newcommand{\coordargs}[2]{(\coordarg{#1},\coordarg{#2})} -\newcommand{\lnsvalue}[3]{large/normal/small value #1/#2/#3} - -\newenvironment{defs}{% - \begin{list}{}% - {\setlength{\labelwidth}{0pt}% - \setlength{\labelsep}{1em}% - \setlength{\leftmargin}{1em}% - \setlength{\parsep}{1ex}% - \setlength{\listparindent}{0pt}% - \setlength{\rightmargin}{0pt}% - \renewcommand{\makelabel}[1]{##1}% - \raggedright% - }% - }{% - \end{list}} - - - -\title{ - A \LaTeX\ macro package for Message Sequence Charts\\{\large User Manual} -} - -\author{ - \begin{tabular}{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{victor.bos@ssf.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 - -\begin{abstract} -\noindent -The \mscpack{} facilitates the \LaTeX\ user to easily include -Message Sequence Charts in his texts. This document describes the -design and use of the \mscpack. -\end{abstract} - -\tableofcontents -\section{New} -\label{new} - -\paragraph{Version~1.16} solves a bug that was due to a change in -syntax of the \verb+scalebox+ macro in the \verb+PSTricks+ package. - -The \verb+action+ and \verb+condition+ macros are extended with a -starred option. The starred version of the macros automatically -adjusts the size of the rectangle and hexagon based on the size of the -contents. - -\paragraph{Version~1.13} has a reimplementation of message commands in MSC -diagrams. The affected commands are: \verb+\create+, \verb+\found+, -\verb+\lost+, \verb+\mess+, and \verb+\order+. The new implementation -provides more control over the placement of message labels. - -The command \verb+\selfmesslabelpos+ has been removed. - -The bounding box bug has been partly solved. Now, a white \verb+\fbox+ -is drawn around every (msc, mscdoc, hmsc) diagram. This makes it -possible for \texttt{dvips -E} to compute the correct bounding box for -the diagrams. Due to the \verb+\fbox+, each diagram is extended with -0.3pt on each side (left, top, right, and bottom). This bugfix fails -if the background is not white. The xdvi program shows the white -\verb+\fbox+ in black with the result that diagrams have two visible -frames. This seems to be a bug of xdvi. - -The lines around comments (\verb+\msccomment+, Section~\ref{comments}) -are changed from gray into black. The reason for this is that the gray -lines became invisible after converting the document to HTML. - -\paragraph{Version~1.12} is a non-public version. It features a preliminary -implementation of message label position control. - -\paragraph{Version~1.11} is a mainly a bugfix of version~1.10a, see~\cite{BM02b}. -The next list shows the new features of version~1.10a compared to -version 1.4. - -\begin{itemize} -\item Support for method replies (dashed message arrows):\cmd{mess*} (Section~\ref{messages}) -\item Fat instances, i.e., double line instances (Section~\ref{instances}) -\item Comments (Section~\ref{comments}) -\item Coregions are now special cases of regions (which includes also -activation and suspension regions). The \cmd{coregionstart} and -\cmd{coregionend} commands are obsolete and the \cmd{coregionbarwidth} -is replaced by \cmd{regionbarwidth}. -\item Gates (Section~\ref{gates}) -\item High-level \MSC{}'s (Section~\ref{hmsc}) -\item \cmd{inlinestart} has additional optional argument to allow for different left and right overlap (Section~\ref{inlines}) -\item \MSCdoc{}s (Section~\ref{mscdoc}) -\item Reference manual~\cite{BM02} -\item \cmd{referencestart} has additional optional argument to allow for different left and right overlap (Section~\ref{references}) -\item Regions: generalization of coregions supporting activations, suspension, and coregions (Section~\ref{regions}) -\item Time measurements (Section~\ref{measurements}) -\end{itemize} - - -\section{Introduction} -\label{introduction} - -The \MSC{} language is a visual language for the description of the -interaction between different components of a system. -This language is standardized by the ITU (International -Telecommunication Union) in Recommendation Z.120~\cite{z120}. An -introductory text on \MSC{} can be found -in~\cite{RudolphGrabowskiGraubmann96}. \MSC{}s have a -wide application domain, ranging from requirements specification to -testing and documentation. -An example of a Message Sequence Chart is in Figure~\ref{quick}. - -In order to support easy drawing of \MSC{}s in \LaTeX\ documents, we have -developed the \mscpack. The current version of the \mscpack{} -supports the following \MSC{} constructs: \MSC{} frame, instances (both -single line width and double line width), messages (including -self-messages and messages to the environment), actions, singular and -combined timer events (set, timeout, reset, set-timeout, set-stop), -lost and found messages, generalized order, conditions, coregions, -activation regions, suspension regions, gates, instance creation, -instance stop, time measurements, references, and inline -expressions. In addition, there is support for \HMSC{}'s (high-level -\MSC{}s) and \MSCdoc{}s. - -In this manual we explain the design and the use of the \mscpack. For -a complete overview of all features, we refer to the reference -manual~\cite{BM02}, which is included in the distribution under the -name \verb+refman.ps+. Another way to learn how to use the \mscpack{} -is to have a look at the \LaTeX{} source code of the manual and the -source code of the reference manual. They are included in the -distribution under the names \verb+manual.tex+ and \verb+refman.tex+, -respectively. The \MSC{} constructs are simply introduced as -syntactic constructs. This paper is not meant to describe their use or -meaning. - -We list the backgrounds of the package and some design decisions in -Section~\ref{background}. -Section~\ref{install} contains notes on installing the -package. Section~\ref{quickstart} contains an example of using the -package. It allows the impatient reader to quickly start using the -package. The details of using the package are explained in -Section~\ref{use}. In Section~\ref{parameters} the parameters are -explained which determine detailed layout of the various symbols. -A large but meaningless example is given in -Section~\ref{example}. - - -\section{Background and motivation} -\label{background} -Several commercial and non-commercial tools are available, which -support drawing or generating Message Sequence Charts. However, these -tools are in general not freely available and often not flexible -enough to satisfy all user's wishes with respect to the layout and -graphical appearance of an \MSC{}. -Therefore, people often use general drawing tools, such as {\em xfig} -to draw \MSC{}s. However flexible this approach is, it takes quite some -effort to produce nice \MSC{} drawings in a tool which is not dedicated -to \MSC{}s. Furthermore, when drawing a number of \MSC{}s it requires some -preciseness in order to obtain a consistent set of \MSC{}s. - -For these reasons, we have started the design of a set of -\LaTeX\ macros which support the drawing of \MSC{}s. In this way, an \MSC{} can be -represented in \LaTeX\ in a textual format and compiled into -e.g.\ PostScript. - -We aimed at satisfying the following requirements and design -decisions. -\begin{itemize} -\item -The package should follow the ITU standard with respect to shape and -placement of the symbols. (The current version supports -the \MSC2000 standard.) -\item -Static and dynamic semantics are not considered. The user is allowed -to violate all semantical restrictions and draw inconsistent \MSC{}s. -The package only supports elementary syntactical requirements. -\item -The package should offer functionality at the right level of -abstraction. Rather than supplying coordinates of pixels, the -user should be able to express the placement of symbols in terms of -{\em levels}. -Nevertheless, the textual representation of \MSC{}s as defined by the ITU -standard has a level of abstraction which is too high for our purposes. -It lacks information about the actual positioning of the \MSC{} symbols, -while we think that in our package this should be under user control. -\item -There should be only minimal automatic restructuring and layout of the -\MSC{} (e.g.\ the relative positioning of two messages should be as -defined by the user, even if the messages are not causally ordered). -\item -The user can customize the appearance of the \MSC{}s by manipulating -an appropriate set of parameters. -\end{itemize} - -\section{Installation, copyright and system requirements} -\label{install} - -The \mscpack{} is still under development. The authors -appreciate any comments and suggestions for improvements. The most -recent version of the package can be downloaded from -\url{http://satoss.uni.lu/mscpackage/}. - - -The \mscpack{} has a \emph{LaTeX Project Public License} -(LPPL), see~\url{http://www.latex-project.org/lppl.txt}: -{\small -\verbatiminput{COPYRIGHT} -} As such, it is free of charge and can be freely -distributed. Furthermore, it is allowed to make modifications to the -package, provided that modified versions get different names. The -authors accept no liability with respect to the functioning of the -package. - -The \mscpack{} runs with \LaTeXe. It has been tested with \LaTeXe\ -version dated 1998/06/01 using \TeX\ version 3.14159. The following -additional packages are required: \textsf{pstricks}, \textsf{calc}, -\textsf{ifthen}, and \textsf{color}. These packages are in general -part of the standard \LaTeXe\ distribution. These additional packages -can be obtained from the {\em ctan} database for \LaTeX\, e.g.\ via -the following URL: \url{http://www.tex.ac.uk/}. The \textsf{pstricks} -package is described in~\cite[Chapter~4]{GSM97}. The generated output -can only be previewed with recent previewing software (e.g.\ xdvi -version 20c). It may be needed to update all \LaTeX\ related software -to a more recent version in order to smoothly work with the \mscpack. - -The \mscpack{} can be installed easily. Just put the file -\verb+msc.sty+ in a directory which is searched by \LaTeX{} for style -files. The set of directories actually searched depends on the \TeX\ -installation, but often the {\em current directory} is included. UNIX -users may have to set the environment variable \texttt{\$TEXINPUTS} to -an appropriate value. For more details on this topic consult -documentation of your \TeX\ installation. - -%The following text is currently not applicable -sm -% -%A problem may occur when using more packages than the \MSC{} macro -%package in your \LaTeX\ document. This happens, e.g.\ when using the -%{\em epsfig} package. These problems are due to the combination of -%several packages which are required (but not provided) by the \MSC{} -%macro package. The solution is to change the order of the -%\verb+usepackage+ clauses. - -\section{Quick start} -\label{quickstart} -The \mscpack{} is easy to use. -Below is an example of the use of the package and -Figure~\ref{quick} shows the generated \MSC{}. - -{\small -\begin{verbatim} -\documentclass{article} -\usepackage{msc} -\begin{document} - -\begin{msc}{Example} - -\declinst{usr}{User}{} -\declinst{m1}{Machine 1}{control} -\declinst{m2}{Machine 2}{drill} -\declinst{m3}{Machine 3}{test} - -\mess{startm1}{usr}{m1} -\nextlevel -\mess{startm2}{m1}{m2} -\nextlevel -\mess{continue}{m2}{m3} -\mess{log}{m1}{envleft} -\nextlevel -\mess{output}{m3}{usr}[2] -\nextlevel -\mess{free}{m1}{usr} -\nextlevel - -\end{msc} - -\end{document} - -\end{verbatim} -} - -\begin{figure}[htb] -\begin{center} - -\begin{msc}{Example} - -\declinst{usr}{User}{} -\declinst{m1}{Machine 1}{control} -\declinst{m2}{Machine 2}{drill} -\declinst{m3}{Machine 3}{test} - -\mess{startm1}{usr}{m1} -\nextlevel -\mess{startm2}{m1}{m2} -\nextlevel -\mess{continue}{m2}{m3} -\mess{log}{m1}{envleft} -\nextlevel -\mess{output}{m3}{usr}[2] -\nextlevel -\mess{free}{m1}{usr} -\nextlevel - -\end{msc} - -\end{center} -\caption{The generated \MSC{}} -\label{quick} -\end{figure} - -The \mscpack{} is activated by the clause -\verb+\usepackage{msc}+. -This package contains, among others, a -definition of the environment \verb+msc+. -This environment is used to draw \MSC{}s. The \MSC{} definition is surrounded by -the clauses \verb+\begin{msc}{Example}+ and \verb+\end{msc}+. The name of -the \MSC{}, {\tt Example}, is displayed in the upper-left corner of the -\MSC{}. - -The next four lines define the \emph{instances}: -\verb+\declinst{m1}{Machine 1}{control}+ defines an instance with -\emph{nickname} \verb+m1+ and a description consisting of two parts, -namely, \verb+Machine 1+ and \verb+control+. The nickname is used in -all subsequent references to this instance. The first part of the -description is drawn above the rectangular instance head symbol, and -the second part of the description is drawn inside the instance head -symbol. - -The following lines contain the definitions of the messages. Every -message has a source and a destination instance. The clause -\verb+\mess{startm1}{usr}{m1}+ defines a message with name {\tt -startm1}, which goes from instance {\tt usr} to instance {\tt m1}. - -In order to control the vertical placement of the messages, the \MSC{} is -divided into levels. At every level, any number of messages may start. -The vertical position of the end point of a message is determined -by the optional fourth argument of the message definition, as in the -clause \verb+\mess{output}{m2}{user}[2]+. -This argument is the vertical offset (in number of levels) between the -start point of the message (i.e.\ the current level) and its end point. -If the value is 0 the message is drawn horizontally. A negative offset -means that the arrow has an upward slope. - -The clause \verb+\nextlevel+ is used to advance to the next level. - -\section{Use of the \mscpack} -\label{use} - -\subsection{The \MSC{} frame} -\label{mscframe} -The \verb+msc+ environment is used for making \MSC{} definitions. Thus, such a -definition looks as follows. - -\begin{verbatim} -\begin{msc}[headerpos]{mscname} -...definition of the MSC... -\end{msc} -\end{verbatim} - -This draws the frame and the header of the \MSC{}. -The argument \verb+mscname+ is the name of the \MSC{}. -The header of an \MSC{} is formed from the keyword \verb+msc+, followed -by the \verb+mscname+. Positioning of this header is controlled by -the optional argument \verb+headerpos+. This argument can have values -\verb+l+ (for a left aligned header), \verb+c+ (for a centered header) -and \verb+r+ (for a right aligned header). -The default value of \verb+headerpos+ is \verb+l+. - -The size of the \MSC{} frame is determined vertically by the number of levels -occurring in the \MSC{} (see Section~\ref{levels}) and horizontally by -the number of instances (see Section~\ref{instances}). - -The parameter \verb+\topnamedist+ controls the distance between the -top of the \MSC{} frame and the header (see Section~\ref{parameters}). -The parameter \verb+\leftnamedist+ controls the distance between the -left of the \MSC{} frame and the header if the \verb+headerpos+ is -\verb+l+ and it controls the distance between the right of the \MSC{} -frame and the header if \verb+headerpos+ is \verb+r+ (see -Section~\ref{parameters}). - -\subsection{Levels} -\label{levels} -An \MSC{} is vertically divided in {\em levels}. All events in an \MSC{} are -attached to a certain level, or stretch out over several levels. -Any number of events can be drawn at a certain level. -An event will always be drawn (or started) at the current level, unless a level -offset is specified (see e.g.\ the \verb+\mess+ command in -Section~\ref{messages}). The level offset is an integer number, which -denotes at which level, relative to the current level, an event should -be drawn. -Drawing starts at level 0. -The following command is used to advance to the next level. -\begin{verbatim} -\nextlevel[leveloffset] -\end{verbatim} - -The \verb+leveloffset+ is an integer value which denotes the number of -levels to advance. By default, the value of \verb+leveloffset+ is 1, -which means drawing continues at the next level. Setting -\verb+leveloffset+ to a negative value may result in unexpected -drawings, however, see the \emph{Tricks} section in the reference -manual~\cite{BM02}. - -There are three parameters which control the size of the levels (see -Section~\ref{parameters}). These are \verb+\firstlevelheight+ (the -distance between the instance start symbol and the first level), -\verb+\levelheight+ (the distance between two consecutive levels), and -\verb+\lastlevelheight+ (the distance between the last level and the -instance end symbol). Figure~\ref{parametersfig} on -page~\pageref{parametersfig} shows all lengths of the \mscpack. - -\subsection{Instances} -\label{instances} -All instances have to be declared before they can be used. An instance -consists of an instance head symbol with an associated name, an -instance axis and an instance end symbol. Normal instances have a -single line axis. Fat instances have a double line axis. The order of -the instance declarations determines the order in which the instances -occur in the drawing. - -An instance is declared with the following command. - -\begin{verbatim} -\declinst(*){nickname}{instancenameabove}{instancenamewithin} -\end{verbatim} - -The starred version produces a fat instance. -The \verb+nickname+ is used for referring to this instance in the rest of the -\MSC{} definition. -The \verb+instancenameabove+ is put above the instance head symbol. -The \verb+instancenamewithin+ is put inside the instance head symbol. - -Several parameters allow the user to customize the shape and -positioning of instances (see Section~\ref{parameters}). These are -\verb+\topheaddist+ (the distance between the top of the \MSC{} and the -instance head symbol), \verb+\instheadheight+ (the height of the -instance head symbol), \verb+\instfootheight+ (the height of the -instance foot symbol), \verb+\bottomfootdist+ (the distance between -the instance foot symbol and the bottom of the \MSC{} frame), -\verb+\instwidth+ (the width of the instance head and foot symbols), -\verb+\instdist+ (the distance between two instance axes), -\verb+\envinstdist+ (the distance between the edge of the \MSC{} and the -first/last instance axis), and \verb+\labeldist+ (the distance between -the instance head symbol and the part of the instance name drawn above -the head symbol). The command \verb+\setfootcolor{color}+ sets the -fill color of the footer symbol. Valid color values are, e.g., -\texttt{black} (default), \texttt{white}, and \texttt{gray}. - -The following \MSC{} shows the declaration of an \MSC{} with three -instances. The first and the last are normal instances (one line axis) -whereas the second is a fat instance (double line axis). The second -line, \verb+\setmscvalues{small}+, indicates that the small drawing -style should be used (see Section~\ref{parameters}). - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}[l]{instances} -\setmscvalues{small} - -\declinst{i}{above}{within} -\declinst*{j}{}{j} -\declinst{k}{k}{} - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\small -\begin{verbatim} -\begin{msc}{instances} -\setmscvalues{small} - -\declinst{i}{above}{within} -\declinst*{j}{}{j} -\declinst{k}{k}{} - -\end{msc} -\end{verbatim} -} -\end{minipage} - - -\subsection{Messages} -\label{messages} -A message is denoted by an arrow from the sending instance to the -receiving instance. The instances are referred to by their nicknames. -A message is defined with the following command. - -\begin{verbatim} -\mess(*)[pos]{name}[labelpos]{sender}[placement]{receiver}[leveloffset] -\end{verbatim} -The \verb+name+ of the message may be any string. The \mscpack{} -processes the \verb+name+ argument in LR-mode, -see~\cite[page~36]{Lam94}. This means that the string will consist of -one line. To generate multi-line message names, use the standard -\cmd{parbox} command, see the \emph{Tricks} section in the reference -manual~\cite{BM02}. By default, the name of a message label is drawn -above the center of the arrow, but the optional parameters \verb+pos+, -\verb+labelpos+, and \verb+placement+ influence the actual location, -as described below. The arrow starts at the current level at the -sending instance. The arrow ends at the current level plus the -\verb+leveloffset+, at the receiving instance. The \verb+leveloffset+ -is an optional integer argument with default value 0. The -\verb+sender+ and \verb+receiver+ should be the nicknames of declared -instances. - -In case the sending and the receiving instance are the same, the -message is a \emph{self message}. A self message is drawn as a -polyline connecting the instance axis to itself. - -The starred version of the command, \verb+\mess*+, produces the same -result as \verb+\mess+, except that the arrow is drawn with a dashed -line. This can be used to draw a {\em method reply} (see~\cite{z120}). - -As mentioned above, placement of the message and its label is -controlled by the optional parameters \verb+pos+, \verb+labelpos+, and -\verb+placement+. In case of a self message, \verb+pos+ denotes the -position of the arrow with respect to the instance axis. Valid values -are \verb+l+ (left) and \verb+r+ (right). The default value is -\verb+l+. In case of a non-self message, the \verb+pos+ parameter is -ignored. - -Whereas the \verb+pos+ parameter defines the position of the arrow -symbol with respect to the instance axis, the \verb+labelpos+ -parameter defines the position of the message label with -respect to the message arrow. In case of a self message, valid values -for \verb+labelpos+ are \verb+l+ (left) and~\verb+r+ (right). The -default value is equal to the, possibly user defined, value of the -\verb+pos+ parameter. In case of a non-self message, valid values for -\verb+labelpos+ are \verb+t+ (on top) and~\verb+b+ (below). The -default value is~\verb+t+. - -Finally, the \verb+placement+ parameter defines the relative distance -of the message label to the beginning of the message. Valid values are -real numbers in the closed interval $[0,1]$. The default value -is~$0.5$. While drawing a message, the \mscpack{} computes the -coordinates of the message label using \verb+placement+ and the length -and coordinates of the arrow. It then computes a \emph{reference -point} for the message label and places it on the coordinates just -computed. Figures \ref{fig:refpoints} (page~\pageref{fig:refpoints}) -and~\ref{fig:refpoints:B} (page~\pageref{fig:refpoints:B}) -schematically show the reference points for message labels. In the -first figure, the labels are located at the default position. In the -second figure, all labels are shifted along the arrow by setting -$\verb+placement+ = 0.9$. The \verb+\lost+ and \verb+\found+ commands -(Section~\ref{lostfound}) and the \verb+\create+ -(Section~\ref{createstop}) command use the same method to determine -reference points and message label locations. Note that the boxes with -the location of the reference points are not generated by the \LaTeX{} -code given in Figures \ref{fig:refpoints} and~\ref{fig:refpoints:B}; -we enriched the \LaTeX{} code with some extra \textsf{pstricks} code -(see \LaTeX{} source code of this document). - -In addition to label position control, there are three ways to control -the shape of messages (see Section~\ref{parameters}). These are: -\verb+\selfmesswidth+ (a parameter to specify the width of the -polyline used for drawing self-messages), \verb+\labeldist+ (a -parameter to specify the distance between the label of a message and -the message arrow), and \verb+\messarrowscale{size}+ (a command to set -the size of the arrow head of a message). \verb+size+ should be -positive real number. - -Messages to or from the environment (i.e.\ the left or the right side -of the \MSC{} frame) can be -specified by setting the sender or the receiver argument to one of the values -\verb+envleft+ or \verb+envright+. (Note: Since instances and -environments are treated equally in the implementation, at every position -where the nickname of an instance is required, also -\verb+envleft+ and \verb+envright+ are allowed.) - -The following \MSC{} shows an example of the use of messages. -In this sample \MSC{} and the following \MSC{}s in this section we will -not list the complete textual representations of the \MSC{}s. For brevity -we omit the environment call and the declarations of the instances. -Note the final \verb+\nextlevel+ command which is needed -to make the instance axis long enough to receive message -\verb+a+. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{messages} -\setmscvalues{small} -\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} - -\mess{a}{j}{i}[3] -\mess{self}{i}{i} -\nextlevel -\mess*{b}{j}{k} -\mess[b]{c}{k}{envright} -\nextlevel -\mess{d}{k}[.6]{i} -\nextlevel - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\small -\begin{verbatim} -\mess{a}{j}{i}[3] -\mess{self}{i}{i} -\nextlevel -\mess*{b}{j}{k} -\mess[b]{c}{k}{envright} -\nextlevel -\mess{d}{k}[.6]{i} -\nextlevel -\end{verbatim} -} -\end{minipage} - -\begin{figure}[htb] -\begin{minipage}{\linewidth} -\setmscvalues{small} -\begin{multicols}{2} -\begin{msc}{Label reference points} -\declinst{m0}{I0}{} -\declinst{m1}{I1}{} -\declinst{m2}{I2}{} -\nextlevel - -\mess{\rpS}{m0}{m1} -\nextlevel -\mess{\rpN}[b]{m1}{m2} -\nextlevel[2] - -\mess{\rpS}{m1}{m0} -\nextlevel -\mess{\rpN}[b]{m2}{m1} -\nextlevel[2] - -\mess{\rpE}{m0}{m0}[2] -\mess[r]{\rpW}{m2}{m2}[2] -\nextlevel[4] -\mess{\rpW}[r]{m0}{m0}[2] -\mess[r]{\rpE}[l]{m2}{m2}[2] -\nextlevel[6] - -\mess{\rpE}{m0}{m0}[-2] -\mess[r]{\rpW}{m2}{m2}[-2] -\nextlevel[4] -\mess{\rpW}[r]{m0}{m0}[-2] -\mess[r]{\rpE}[l]{m2}{m2}[-2] -\nextlevel[2] - -\mess{\rpSW}{m0}{m1}[2] -\mess{\rpNE}[b]{m1}{m2}[2] -\nextlevel[6] - -\mess{\rpSW}{m1}{m0}[-2] -\mess{\rpNE}[b]{m2}{m1}[-2] -\nextlevel[2] - -\mess{\rpSE}{m1}{m0}[2] -\mess{\rpNW}[b]{m2}{m1}[2] -\nextlevel[6] - -\mess{\rpSE}{m0}{m1}[-2] -\mess{\rpNW}[b]{m1}{m2}[-2] -\nextlevel[2] -\end{msc} -\bigskip - -\scriptsize -\begin{verbatim} -\begin{msc}{Label reference points} -\declinst{m0}{I0}{} -\declinst{m1}{I1}{} -\declinst{m2}{I2}{} -\nextlevel - -\mess{S}{m0}{m1} -\nextlevel -\mess{N}[b]{m1}{m2} -\nextlevel[2] - -\mess{S}{m1}{m0} -\nextlevel -\mess{N}[b]{m2}{m1} -\nextlevel[2] - -\mess{E}{m0}{m0}[2] -\mess[r]{W}{m2}{m2}[2] -\nextlevel[4] -\mess{W}[r]{m0}{m0}[2] -\mess[r]{E}[l]{m2}{m2}[2] -\nextlevel[6] - -\mess{E}{m0}{m0}[-2] -\mess[r]{W}{m2}{m2}[-2] -\nextlevel[4] -\mess{W}[r]{m0}{m0}[-2] -\mess[r]{E}[l]{m2}{m2}[-2] -\nextlevel[2] - -\mess{SW}{m0}{m1}[2] -\mess{NE}[b]{m1}{m2}[2] -\nextlevel[6] - -\mess{SW}{m1}{m0}[-2] -\mess{NE}[b]{m2}{m1}[-2] -\nextlevel[2] - -\mess{SE}{m1}{m0}[2] -\mess{NW}[b]{m2}{m1}[2] -\nextlevel[6] - -\mess{SE}{m0}{m1}[-2] -\mess{NW}[b]{m1}{m2}[-2] -\nextlevel[2] -\end{msc} -\end{verbatim} -\end{multicols} -\end{minipage} -\caption{Reference points of message labels} -\label{fig:refpoints} -\end{figure} - - -\begin{figure}[htb] -\begin{minipage}{\linewidth} -\setmscvalues{small} -\begin{multicols}{2} -\begin{msc}{Label reference points (2)} -\declinst{m0}{I0}{} -\declinst{m1}{I1}{} -\declinst{m2}{I2}{} -\nextlevel - -\mess{\rpS}{m0}[.9]{m1} -\nextlevel -\mess{\rpN}[b]{m1}[.9]{m2} -\nextlevel[2] - -\mess{\rpS}{m1}[.9]{m0} -\nextlevel -\mess{\rpN}[b]{m2}{m1} -\nextlevel[2] - -\mess{\rpE}{m0}[.9]{m0}[2] -\mess[r]{\rpW}{m2}[.9]{m2}[2] -\nextlevel[4] -\mess{\rpW}[r]{m0}[.9]{m0}[2] -\mess[r]{\rpE}[l]{m2}[.9]{m2}[2] -\nextlevel[6] - -\mess{\rpE}{m0}[.9]{m0}[-2] -\mess[r]{\rpW}{m2}[.9]{m2}[-2] -\nextlevel[4] -\mess{\rpW}[r]{m0}[.9]{m0}[-2] -\mess[r]{\rpE}[l]{m2}[.9]{m2}[-2] -\nextlevel[2] - -\mess{\rpSW}{m0}[.9]{m1}[2] -\mess{\rpNE}[b]{m1}[.9]{m2}[2] -\nextlevel[6] - -\mess{\rpSW}{m1}[.9]{m0}[-2] -\mess{\rpNE}[b]{m2}[.9]{m1}[-2] -\nextlevel[2] - -\mess{\rpSE}{m1}[.9]{m0}[2] -\mess{\rpNW}[b]{m2}[.9]{m1}[2] -\nextlevel[6] - -\mess{\rpSE}{m0}[.9]{m1}[-2] -\mess{\rpNW}[b]{m1}[.9]{m2}[-2] -\nextlevel[2] -\end{msc} -\bigskip - -\scriptsize -\begin{verbatim} -\begin{msc}{Label reference points (2)} -\declinst{m0}{I0}{} -\declinst{m1}{I1}{} -\declinst{m2}{I2}{} -\nextlevel - -\mess{S}{m0}[.9]{m1} -\nextlevel -\mess{N}[b]{m1}[.9]{m2} -\nextlevel[2] - -\mess{S}{m1}[.9]{m0} -\nextlevel -\mess{N}[b]{m2}{m1} -\nextlevel[2] - -\mess{E}{m0}[.9]{m0}[2] -\mess[r]{W}{m2}[.9]{m2}[2] -\nextlevel[4] -\mess{W}[r]{m0}[.9]{m0}[2] -\mess[r]{E}[l]{m2}[.9]{m2}[2] -\nextlevel[6] - -\mess{E}{m0}[.9]{m0}[-2] -\mess[r]{W}{m2}[.9]{m2}[-2] -\nextlevel[4] -\mess{W}[r]{m0}[.9]{m0}[-2] -\mess[r]{E}[l]{m2}[.9]{m2}[-2] -\nextlevel[2] - -\mess{SW}{m0}[.9]{m1}[2] -\mess{NE}[b]{m1}[.9]{m2}[2] -\nextlevel[6] - -\mess{SW}{m1}[.9]{m0}[-2] -\mess{NE}[b]{m2}[.9]{m1}[-2] -\nextlevel[2] - -\mess{SE}{m1}[.9]{m0}[2] -\mess{NW}[b]{m2}[.9]{m1}[2] -\nextlevel[6] - -\mess{SE}{m0}[.9]{m1}[-2] -\mess{NW}[b]{m1}[.9]{m2}[-2] -\nextlevel[2] -\end{msc} -\end{verbatim} -\end{multicols} -\end{minipage} -\caption{Reference points of shifted message labels} -\label{fig:refpoints:B} -\end{figure} - - -\subsection{Comments} -\label{comments} - -Comments are additional texts to clarify (events on) an instance. The -following command can be used to add comments to an \MSC{} diagram. - -\begin{verbatim} -\msccomment[position]{text}{instname} -\end{verbatim} - -The \verb|instname| parameter defines the instance to which the -comment is attached. The text of the comment is specified by the -\verb|text| parameter and is processed in LR-mode. The \verb|position| -parameter defines the horizontal position of the comment relative to -its instance. Valid values of \verb|position| are \verb|l| (left), -\verb|r| (right), or any \LaTeX{} length. Its default value -is~\verb|l|. If the value of \verb|position| is \verb|l| -(or~\verb|r|), the comment will be placed \verb|\msccommentdist| units -to the left (or right) of the \verb|instname| instance. If -\verb|position| is a \LaTeX{} length, the comment will be placed -\verb|position| units from the \verb|instname| instance. A negative -length puts the comment to the left and a positive length puts the -comment to the right of the instance. - -The following diagram shows how to use comments. In this diagram, the -distance between the frame and the instances (\verb|\envinstdist|) is -doubled in order to fit the comments inside the frame. - -\medskip -\begin{minipage}[c]{0.4\linewidth} -\setmscvalues{small} -\begin{msc}{comments} -\setlength{\envinstdist}{2\envinstdist} -\declinst{i}{}{i} -\declinst{j}{}{j} -\mess{a}{i}{j}[2] -\msccomment{start}{i} -\nextlevel[2] -\msccomment[r]{end}{j} -\nextlevel -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.54\linewidth} -{\small -\begin{verbatim} -\setlength{\envinstdist}{2\envinstdist} -\declinst{i}{}{i} -\declinst{j}{}{j} -\mess{a}{i}{j}[2] -\msccomment{start}{i} -\nextlevel[2] -\msccomment[r]{end}{j} -\nextlevel -\end{verbatim} -} -\end{minipage} - - - - -\subsection{Actions} -\label{actions} -An instance can perform an action, which is denoted by a rectangle. - -\begin{verbatim} -\action(*){name}{instance} -\end{verbatim} - -The action is attached at the current level to the \verb+instance+. -The \verb+name+ is centered inside the action symbol and is processed -in LR-mode. - -The following parameters determine the detailed drawing of the action -symbol (see Section~\ref{parameters}): -\verb+\actionwidth+ (the width of the action symbol), and -\verb+\actionheight+ (the height of the action symbol). - -The starred version of the command, \verb+\action*+, produces the same -result as \verb+\action+, except that the height and width of the -action symbol are adjusted to fit the contents of the rectangle. - -The next example shows that after an action often a multiple level -increment is needed to obtain nice pictures. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{action} -\setmscvalues{small} -%\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\declinst{j}{}{j} - -\mess{a}{j}{i} -\nextlevel -\action{doit}{i} -\nextlevel[2] -\mess{b}{i}{j} - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\small -\begin{verbatim} -\mess{a}{j}{i} -\nextlevel -\action{doit}{i} -\nextlevel[2] -\mess{b}{i}{j} -\end{verbatim} -} -\end{minipage} - - -\subsection{Timers} -\label{timers} -There are five commands to draw timer events. -\begin{verbatim} -\settimer[placement]{name}{instance} -\timeout[placement]{name}{instance} -\stoptimer[placement]{name}{instance} -\settimeout[placement]{name}{instance}[offset] -\setstoptimer[placement]{name}{instance}[offset] -\end{verbatim} - -Setting of a timer is drawn as a line connecting the \verb+instance+ -to the {\em hour glass} symbol. The \verb+name+ is put near this -symbol. A time-out is represented by an arrow from an -{\em hour glass} symbol to the \verb+instance+. Stopping a timer is -drawn as a line connecting the \verb+instance+ with the timer stop -symbol (denoted by a cross). -The command \verb+\settimeout+ is a combination of the setting of a -timer and a time out. The \verb+offset+ denotes the number of levels -between the two events. The default value for \verb+offset+ is 2. -Likewise, \verb+\setstoptimer+ is a combination -of the setting of a timer and stopping a timer. - -The optional argument \verb+placement+ can have values -\verb+l+ (meaning that the timer is drawn left of the instance axis) -and \verb+r+ (meaning that the timer is drawn right of the instance -axis). By default it is drawn at the left side of the instance. - -Several parameters can be used to control the detailed layout of timer -symbols (see Section~\ref{parameters}): -\verb+\timerwidth+ (the width of the hour glass and time out symbols), -\verb+\selfmesswidth+ (the length of the arm between the symbol -and the instance axis), and -\verb+\labeldist+ (the distance between the name and the timersymbol). -Furthermore, the size of the arrow head can be controlled with the -command \verb+\messarrowscale{size}+. - -The various timer symbols are shown in the following example. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{timers} -\setmscvalues{small} -\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} - -\settimer{T,50}{j} -\setstoptimer[r]{V}{k}[6] -\nextlevel[2] -\timeout{T}{j} -\settimeout{U}{i} -\nextlevel[2] -\settimer[r]{T,20}{j} -\nextlevel[2] -\stoptimer[r]{T}{j} - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\small -\begin{verbatim} -\settimer{T,50}{j} -\setstoptimer[r]{V}{k}[6] -\nextlevel[2] -\timeout{T}{j} -\settimeout{U}{i} -\nextlevel[2] -\settimer[r]{T,20}{j} -\nextlevel[2] -\stoptimer[r]{T}{j} -\end{verbatim} -} -\end{minipage} - -\subsection{Time measurements} -\label{measurements} -There are several commands to add time measurements to an \MSC{}. - -\begin{verbatim} -\mscmark[placement]{name}{instance} -\measure(*)[placement]{name}{instance1}{instance2}[offset] -\measurestart(*)[placement]{name}{instance}{gate} -\measureend(*)[placement]{name}{instance}{gate} -\end{verbatim} - -An absolute time stamp is attached to an event on an \verb+instance+ -with the command -\verb+mscmark+. The \verb+name+ is the text attached to the mark symbol, -which is a dashed polyline. -The position of the mark symbol relative to the marked event is -determined by the \verb+placement+. -(\verb+tl+ means top-left, \verb+tr+ means top-right, \verb+bl+ means -bottom-left, and \verb+br+ means bottom-right). - -A \verb+\measure+ connects two events from \verb+instance1+ and -\verb+instance2+. The first event is at the current level. The second -event is \verb+offset+ levels lower than the first event. The -\verb+name+ is attached to the measure symbol. The measure symbol can -be placed at the left or at the right of \verb+instance1+. This is -controlled by the optional argument \verb+placement+, which can have -values \verb+l+ and \verb+r+. - -In case the two events are far apart, the measure may be split in two -parts. The first part is drawn with the \verb+\measurestart+ command -and the second part with the \verb+\measureend+ command. The points -where these two parts should be connected are drawn by a small circle, -to which the text \verb+gate+ is attached. - -There are two equivalent forms of the measurement symbol. The first -form, where the arrow heads are at the inside of the measured -interval, is the default form. The second form, where the arrow heads -are at the outside of the measured interval, is obtained by the -commands \verb+\measure*+, \verb+\measurestart*+, and -\verb+\measureend*+. - - -Several parameters can be used to control the detailed layout of the -time measurement symbols (see Section~\ref{parameters}): -\verb+\labeldist+ (a parameter to specify the distance between the -label of a measurement and the measurement symbol), -\verb+\messarrowscale{size}+ (a command to set the size of the arrow -head), -\verb+\selfmesswidth+ (specifies the width of the measurement -symbols). - -The following example illustrates marks and measurements in an \MSC{}. In -order to include the marks inside the frame of the diagram, the -distance between the frame and the instances (called -\verb+\envinstdist+) is increased (before the instances are declared). - -\medskip - -\begin{minipage}[c]{0.5\linewidth} -\begin{msc}{Time measurements} -\setmscvalues{small} -\setlength{\envinstdist} - {2\envinstdist} - -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} - -\mess{m1}{i}{j}[1] -\mscmark{t=0.0}{i} -\measure{0.6}{i}{j}[4] -\nextlevel -\mscmark[tr]{t=0.3}{j} -\nextlevel[3] -\mess{m2}{j}{k} -\measurestart*[r]{0.2}{k}{g} -\nextlevel[6] -\mess{m3}{k}{i} -\mscmark[bl]{t=1.0}{i} -\measureend*[r]{0.2}{k}{g} -\nextlevel -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.44\linewidth} -{\small -\begin{verbatim} -\setlength{\envinstdist} - {2\envinstdist} -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} -\mess{m1}{i}{j}[1] -\mscmark{t=0.0}{i} -\measure{0.6}{i}{j}[4] -\nextlevel -\mscmark[tr]{t=0.3}{j} -\nextlevel[3] -\mess{m2}{j}{k} -\measurestart*[r]{0.2}{k}{g} -\nextlevel[6] -\mess{m3}{k}{i} -\mscmark[bl]{t=1.0}{i} -\measureend*[r]{0.2}{k}{g} -\nextlevel -\end{verbatim} -} -\end{minipage} - - -\subsection{Lost and found messages} -\label{lostfound} -A lost message is denoted by an arrow starting at an instance and -ending at a filled circle. A found message is denoted by an arrow -starting at an open circle and ending at an instance. - -The following commands are used to define lost and found messages. -\begin{verbatim} -\lost[pos]{name}[labelpos]{gate}{instance}[placement] -\found[pos]{name}[labelpos]{gate}{instance}[placement] -\end{verbatim} - -The argument \verb+instance+ determines the instance to which the -arrow is attached. The \verb+name+ of the message is put above the -message arrow. The \verb+gate+ is a text associated to the circle. -The optional arguments \verb+pos+, \verb+labelpos+, and -\verb+placement+ have the same function as in the \verb+\mess+ command -(Section~\ref{messages}). That is, \verb+pos+ controls the placement -of the lost or or found message with respect to the instance -axis. Valid values are \verb+l+ (left) and~\verb+r+ (right). The -default value is~\verb+l+. The optional parameters \verb+labelpos+ -and \verb+placement+ control the placement of \verb+name+ with respect -to the message arrow. Valid values for \verb+labelpos+ are \verb+t+ -(on top) and~\verb+b+ (below). The default value is~\verb+t+. Valid -values for \verb+placement+ are real numbers in the closed interval -$[0,1]$ and denote the relative distance of the message label -\verb+name+ to the beginning of the arrow. The default value for -\verb+placement+ is~$0.5$. - -Several parameters can be used to control the detailed layout of lost -and found messages (see Section~\ref{parameters}): -\verb+\lostsymbolradius+ (the radius of the circle), -\verb+\selfmesswidth+ (the length of the arrow), and -\verb+\labeldist+ (the distance between the name and the arrow). -Furthermore, the size of the arrow head can be controlled with the -command \verb+\messarrowscale{size}+. - -The following example shows a found and a lost message. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{lost and found} -\setmscvalues{small} -\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\declinst{j}{}{j} - -\found{m}{g}{i} -\nextlevel -\mess{p}{i}{j} -\nextlevel -\lost[r]{n}{}{j} - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\small -\begin{verbatim} -\found{m}{g}{i} -\nextlevel -\mess{p}{i}{j} -\nextlevel -\lost[r]{n}{}{j} -\end{verbatim} -} -\end{minipage} - - - -\subsection{Conditions} -\label{conditions} -A condition is denoted by a hexagon. It is used to express that the -system has entered a certain state. A condition relates to a number of -instances. All conditions which take part in the condition are covered -by the condition symbol. The other instances are drawn through the -condition symbol. -The following command is used to draw a condition. - -\begin{verbatim} -\condition{text}{instancelist} -\end{verbatim} - -The \verb+text+ is placed in the center of the condition. The -\verb+instancelist+ expresses which instances take part in the -condition. It is a list of nicknames of instances, separated by -commas. Take care not to add extra white space around the nicknames, -since this is considered part of the nickname in \LaTeX. -The order in which the instances are listed is immaterial. - -There are two parameters which control the shape of the condition -symbol (see Section~\ref{parameters}): -\verb+\conditionheight+ (the height of the condition symbol), and -\verb+\conditionoverlap+ (the width of the part of the condition -symbol which extends over the rightmost/leftmost contained instance -axis). - -The starred version of the command, \verb+\condition*+, produces the same -result as \verb+\condition+, except that the height and width of the -condition symbol are adjusted to fit the contents of the hexagon. - -The following example contains some conditions. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{conditions} -\setmscvalues{small} -\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} - -\condition{some condition}{i,k} -\nextlevel[3] -\mess{m}{i}{j} -\action{a}{k} -\nextlevel -\condition{C}{i} -\nextlevel[2] -\condition{A, B, C}{i,j,k} -\nextlevel[2] - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\small -\begin{verbatim} -\condition{some condition}{i,k} -\nextlevel[3] -\mess{m}{i}{j} -\action{a}{k} -\nextlevel -\condition{C}{i} -\nextlevel[2] -\condition{A, B, C}{i,j,k} -\nextlevel[2] -\end{verbatim} -} -\end{minipage} - -\subsection{Generalized ordering} -\label{ordering} -A generalized order is treated much like a regular message (see -Section~\ref{messages}). There -are three differences: a generalized order is drawn with a -dotted line, it has no label, and the arrow head is in the middle of -the line. A generalized order is defined with the following command. -\begin{verbatim} -\order[pos]{sender}{receiver}[leveloffset] -\end{verbatim} -The \verb+sender+ and \verb+receiver+ are the nicknames of the -instances which are connected by the generalized ordering symbol. -At the \verb+receiver+ instance, the generalized ordering symbol ends -at the current level plus the \verb+leveloffset+. The -\verb+leveloffset+ is an optional integer value, with default 0. - -In case \verb+sender+ and \verb+receiver+ denote the same instance, -the order is a \emph{self order}. The placement of the order arrow of -a self order is controlled by the optional argument \verb+pos+. It -can have values \verb+l+ (meaning that the ordering symbol is drawn -left of the instance axis) and \verb+r+ (meaning that the ordering -symbol is drawn right of the instance axis). By default it is drawn at -the left side of the instance. For non-self orders, the \verb+pos+ -argument is ignored. - -Additionally, there are two ways to control the shape -of the generalized ordering symbol (see Section~\ref{parameters}). -These are: -\verb+\selfmesswidth+ (a parameter to specify the width of the polyline used for -drawing orderings on a single instance axis). -and -\verb+\messarrowscale{size}+ (a command to set the size of the arrow -head in the ordering symbol). - -Orderings to or from the environment (i.e.\ the left or the right side -of the \MSC{} frame) can be -specified by setting the sender or the receiver argument to the value -\verb+envleft+ or \verb+envright+. - -An example of a generalized order is given in the following diagram. - - - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{generalized order} -\setmscvalues{normal} -\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\declinst{j}{}{j} - -\mess{m}{envleft}{i} -\order{i}{j}[1] -\nextlevel -\mess{k}{j}{envright} -\nextlevel -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\small -\begin{verbatim} -\mess{m}{envleft}{i} -\order{i}{j}[1] -\nextlevel -\mess{k}{j}{envright} -\end{verbatim} -} -\end{minipage} - - -\subsection{Instance regions} -\label{regions} -A part of the instance axis can be drawn in a different style. Such a -part is called an {\em instance region}. The following -regions are supported: -{\em coregion} (the instance axis is dashed, which means that the order of the -attached instances is immaterial), -{\em suspension region} (a small rectangle with dashed left and right -sides, which denotes that the instance is suspended), -{\em activation region} (a small filled rectangle, which denotes that -the instance has control). - -The following commands are used to draw an instance region. - -\begin{verbatim} -\regionstart{type}{instname} -\regionend{instname} -\end{verbatim} - -If the \verb+\regionstart+ command is used the instance axis of -\verb+instname+ is drawn in the shape determined by \verb+type+, -starting from the current level. The type can have values -\verb+coregion+, \verb+suspension+, and \verb+activation+. - -The shape of an instance region can be controlled with the following -parameters (see Section~\ref{parameters}): -\verb+\regionbarwidth+ (the width of the coregion start and end -symbol), -\verb+\instwidth+ (the width of the fat instance rectangle), -\verb+\regionwidth+ (the width of the activation and suspension rectangle). - -In the following example, several instance regions are demonstrated. -Notice the relative order of \verb|\mess|, \verb|\regionstart|, and -\verb|\regionend| commands. Interchanging lines -\verb|\regionstart{activation}{i}| and \verb|\mess{q}{j}{i}| makes the -arrow head of the~`q' message partly invisible. Also note that the -second activation region on~$i$ ends with a method reply -(which is produced by the command \cmd{mess*}). - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{regions} -\setmscvalues{small} -\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} - -\regionstart{activation}{i} -\nextlevel[3] -\regionend{i} -\mess{m}{i}{j} -\nextlevel -\regionstart{coregion}{j} -\nextlevel -\regionstart{suspension}{k} -\mess{p}{j}{k} -\nextlevel -\regionstart{activation}{i} -\mess{q}{j}{i} -\nextlevel -\regionend{j} -\nextlevel[3] -\regionend{i} -\mess*{r}{i}{j} -\nextlevel -\mess{s}{j}{k} -\regionend{k} -\nextlevel -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\scriptsize -\begin{verbatim} -\regionstart{activation}{i} -\nextlevel[3] -\regionend{i} -\mess{m}{i}{j} -\nextlevel -\regionstart{coregion}{j} -\nextlevel -\regionstart{suspension}{k} -\mess{p}{j}{k} -\nextlevel -\regionstart{activation}{i} -\mess{q}{j}{i} -\nextlevel -\regionend{j} -\nextlevel[3] -\regionend{i} -\mess*{r}{i}{j} -\nextlevel -\mess{s}{j}{k} -\regionend{k} -\nextlevel -\end{verbatim} -} -\end{minipage} - -In some situations, the gray-colored activation regions can hide -message-labels. \emph{Level back-up} can help in these situations, see -the \emph{Tricks} section in the reference manual~\cite{BM02}. - -\subsection{Instance creation and instance stop} -\label{createstop} -The \MSC{} language offers constructs for dynamic instance creation and -instance destruction. -An instance can dynamically create another instance by issuing a -create command. An instance creation is drawn as a dashed message -arrow. At the side of the arrow head, the instance head symbol for the -created instance is drawn. -An instance end symbol does not denote the end of the specified -process, but merely the end of its current description. Therefore, a -different symbol is needed which denotes that an instance stops before -the end of the \MSC{} in which it is contained. -The instance stop symbol is a cross. - -The following commands are used for instance creation and instance -stop. - -\begin{verbatim} -\dummyinst{createdinst} -\create{name} - [labelpos] - {creator} - [placement] - {createdinst} - {instancenameabove} - {instancenamewithin} -\stop{instance} -\end{verbatim} - -In order to reserve space for an instance which will be created -dynamically, the command \verb+dummyinst+ must be used. This command -is mixed with the declarations of normal instances (see the -\verb+declinst+ command, Section~\ref{instances}). -The argument \verb+createdinst+ is the nickname of the instance that -will be created later. - -An instance can be created with the \verb+\create+ command. -This command results in a dashed horizontal message arrow labeled with -\verb+name+. The arrow starts at the current level at the instance -with nickname \verb+creator+ and ends at the current level at the -instance head of the instance with nickname \verb+createdinst+. This -instance must have been declared first with the \verb+dummyinst+ -command. -The name of the created instance consists of two parts. The part -called \verb+instancenameabove+ is placed above the instance head and the -\verb+instancenamewithin+ is centered within the instance head. - -As with normal messages, placement of the message label is controlled -by the optional parameters \verb+labelpos+ and \verb+placement+. That -is, \verb+labelpos+ denotes the relative position of the message label -with respect to the message arrow. Valid values are \verb+t+ (on top) -and \verb+b+ (below). The default value is \verb+t+. The optional -parameter \verb+placement+ denotes the relative distance of the -message label with respect to the beginning of the arrow. Valid values -are real numbers in the closed interval $[0,1]$. The default value -is~$0.5$. See Figure~\ref{fig:refpoints} -(page~\pageref{fig:refpoints}) and its description in -Section~\ref{messages} for more information on the placement of -message labels. - -An instance is stopped with the \verb+\stop+ command. -The \verb+instance+ is the nickname of the stopped instance. The -instance axis is not drawn any further below the level at which the -\verb+\stop+ command is issued. Also, the instance foot symbol is not -drawn. - -The size of the stop symbol is determined by the parameter -\verb+\stopwidth+ (see Section~\ref{parameters}). -The following parameters apply to the instance head symbol: -\verb+\instheadheight+ (the height of the instance head symbol), -\verb+\instwidth+ (the width of the instance head symbol), -and -\verb+\labeldist+ (the distance between the instance head symbol and -the part of the instance name drawn above the head symbol). - -Take care not to specify any events on an instance which has not yet -been created or which has already -been stopped. This may lead to unexpected drawings. -However, it is possible to create an instance after it has stopped, -as showed in the next example. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{dynamic instances} -\setmscvalues{small} -\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\dummyinst{j} -\declinst{k}{}{k} - -\mess{p}{i}{k} -\nextlevel[3] -\create{kick}{k}{j}{}{j} -\nextlevel -\stop{k} -\nextlevel -\mess{ok}{j}{i} -\nextlevel -\stop{j} -\nextlevel[2] -\create{start}[b]{i}[.75]{k}{}{again} -\nextlevel[2] - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\small -\begin{verbatim} -\declinst{i}{}{i} -\dummyinst{j} -\declinst{k}{}{k} - -\mess{p}{i}{k} -\nextlevel[3] -\create{kick}{k}{j}{}{j} -\nextlevel -\stop{k} -\nextlevel -\mess{ok}{j}{i} -\nextlevel -\stop{j} -\nextlevel[2] -\create{start}[b]{i}[.75]{k}{}{again} -\nextlevel[2] -\end{verbatim} -} -\end{minipage} - -\subsection{\MSC{} references} -\label{references} -Within an \MSC{} a reference to other \MSC{}s can be included. Such a -reference is drawn as a rectangle with rounded corners, covering part -of the \MSC{}. The following commands are used to draw \MSC{} references. - -\begin{verbatim} -\referencestart[lo][ro]{nickname}{text}{leftinstance}{rightinstance} -\referenceend{nickname} -\end{verbatim} - -The reference symbol starts at the level where the -\verb+\referencestart+ command is used, and ends at the level where -the corresponding \verb+\referenceend+ command occurs. These commands -correspond if they have the same \verb+nickname+. The \verb+text+ is -placed in the center of the reference symbol. The reference covers all -instances from \verb+leftinstance+ to \verb+rightinstance+. The -distance between the left (right) edge of the reference symbol and the -leftmost (rightmost) covered instance axis is defined by the optional -overlap value \verb+lo+. The default value for \verb+lo+ in large/normal/small -\MSC{}s is 1.5/1/0.75 (see Section~\ref{parameters} for selecting -large, normal or small drawing mode). If the second optional value -\verb+ro+ is present too, the optional value \verb+lo+ defines the left -overlap and the optional value \verb+ro+ defines the right overlap. - -The left and right edge of the reference symbol are -\verb+nicknameleft+ and \verb+nicknameright+, where \verb+nickname+ is -the nickname of the \MSC{} reference as defined in the -\verb+\referencestart+ command. -These names can be used at every place where the nickname of an -instance is required, e.g.\ as the sender or receiver of a message. -This is shown in the following example. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{references} -\setmscvalues{small} -\setlength{\topheaddist}{0.8cm} - -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} - -\mess{a}{j}{k} -\nextlevel -\referencestart{r}{a reference}{i}{j} -\nextlevel -\mess{b}{rright}{k} -\nextlevel -\referenceend{r} -\nextlevel -\referencestart{p}{another reference}{i}{k} -\nextlevel -\mess{c}{envright}{pright} -\nextlevel[3] -\referenceend{p} - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.55\linewidth} -{\small -\begin{verbatim} -\mess{a}{j}{k} -\nextlevel -\referencestart{r}{a reference}{i}{j} -\nextlevel -\mess{b}{rright}{k} -\nextlevel -\referenceend{r} -\nextlevel -\referencestart{p}{another reference}{i}{k} -\nextlevel -\mess{c}{envright}{pright} -\nextlevel[3] -\referenceend{p} -\end{verbatim} -} -\end{minipage} - -\subsection{Inline expressions} -\label{inlines} -An inline expression is a part of an \MSC{} on which an operation is -defined. A rectangle surrounds the part of the \MSC{} containing the -operands. The operands are separated by horizontal dashed lines. -The operator is placed in the upper left corner of the inline -expression symbol. -The following commands are used to draw inline expressions. - -\begin{verbatim} -\inlinestart[lo][ro]{nickname}{operator}{leftinstance}{rightinstance} -\inlineseparator{nickname} -\inlineend(*){nickname} -\end{verbatim} - -The inline expression starts at the level where the \verb+\inlinestart+ -command occurs. The inline expression spans over the instances from -\verb+leftinstance+ to \verb+rightinstance+. The \verb+operand+ is -placed in the upper left corner of the rectangle. At every level where -a corresponding \verb+\inlineseparator+ command occurs, a dashed line -is drawn. The inline expression ends at the level where the -\verb+\inlineend+ command occurs. The \verb+nickname+ is used to match -corresponding commands. -The command \verb+\inlineend*+ does the same as the command -\verb+\inlineend+, except that the bottom line of the rectangle is -dashed. This is used to indicate that the operand is optional. - -The left and right edge of the inline expression symbol are named -\verb+nicknameleft+ and \verb+nicknameright+, where \verb+nickname+ is -the nickname of the inline expression as defined in the -\verb+\inlinestart+ command. -These names can be used at every place where the nickname of an -instance is required, e.g.\ as the sender or receiver of a message. - -The distance between the left (right) edge of the inline expression -symbol and -the leftmost (rightmost) included instance axis is defined by -the optional overlap value \verb+lo+. The default value for -large/normal/small \MSC{}s is -1.5/1/0.75 (see Section~\ref{parameters} for selecting large, normal or small -drawing mode). -If the second optional value -\verb+ro+ is present too, the optional value \verb+lo+ defines the left -overlap and the optional value \verb+ro+ defines the right overlap. -These options make it possible to easily draw nested inline expressions -as in the following example. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{inline expressions} -\setmscvalues{small} -\setlength{\topheaddist}{0.8cm} - - -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} - - -\inlinestart{exp1}{par}{i}{k} -\nextlevel -\mess{a}{k}{j} -\nextlevel -\inlinestart[0.6cm]{exp2}{alt}{i}{j} -\nextlevel[2] -\mess{b}{j}{i} -\nextlevel -\inlineseparator{exp2} -\nextlevel -\mess{c}{j}{i} -\nextlevel -\inlineend{exp2} -\nextlevel -\inlineseparator{exp1} -\nextlevel -\mess{d}{j}{k} -\nextlevel -\inlineend{exp1} -\nextlevel -\inlinestart{exp3}{opt}{i}{j} -\nextlevel -\mess{e}{envright}{exp3right} -\mess{e}{exp3right}{j} -\nextlevel -\mess{f}{j}{i} -\nextlevel -\inlineend*{exp3} - - -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\scriptsize -\begin{verbatim} -\inlinestart{exp1}{par}{i}{k} -\nextlevel -\mess{a}{k}{j} -\nextlevel -\inlinestart[0.6cm]{exp2}{alt}{i}{j} -\nextlevel[2] -\mess{b}{j}{i} -\nextlevel -\inlineseparator{exp2} -\nextlevel -\mess{c}{j}{i} -\nextlevel -\inlineend{exp2} -\nextlevel -\inlineseparator{exp1} -\nextlevel -\mess{d}{j}{k} -\nextlevel -\inlineend{exp1} -\nextlevel -\inlinestart{exp3}{opt}{i}{j} -\nextlevel -\mess{e}{envright}{exp3right} -\mess{e}{exp3right}{j} -\nextlevel -\mess{f}{j}{i} -\nextlevel -\inlineend*{exp3} -\end{verbatim} -} -\end{minipage} - -\subsection{Gates} -\label{gates} - -A gate determines a connection point for messages. - -The following command can be used to draw gates. - -\begin{verbatim} -\gate(*)[hpos][vpos]{gatename}{instname} -\end{verbatim} - -The unstarred version produces a normal (invisible) gate. The starred -version produces a visible gate (a small dot). The gate is drawn at the -current level at the instance \verb+instname+ (which can also be the -left and right edge of e.g.\ an \MSC{} reference). The -\verb+gatename+ is attached to the gate. The positioning of the -\verb+gatename+ relative to the gate is determined by the values of -\verb+hpos+ (horizontal position) and \verb+vpos+ (vertical position). -Possible values for \verb+hpos+ are \verb+l+ (left, default) and -\verb+right+ (right). Possible values for \verb+vpos+ are \verb+t+ -(top, default), \verb+c+ (center), and \verb+b+ (bottom). - -There are several parameters to control the size and shape of the -gate symbol (see Section~\ref{parameters}). These are -\verb+\gatesymbolradius+ (sets the radius of the gate symbol), -\verb+\labeldist+ (the vertical distance between the gate name and -the gate). - -The next example shows a number of gates. - -\medskip - -\begin{minipage}[c]{0.4\linewidth} -\begin{msc}{gates} -\setmscvalues{small} - -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} -\referencestart{r}{ref}{i}{j} -\nextlevel -\gate{$g$}{rright} -\mess{b}{rright}{envright} -\gate[r][c]{$h$}{envright} -\nextlevel -\nextlevel -\mess{c}{rright}{k} -\gate*[l][b]{$h'$}{rright} -\nextlevel[2] -\referenceend{r} -\end{msc} -\end{minipage} -% -\begin{minipage}[c]{0.5\linewidth} -{\footnotesize -\begin{verbatim} -\declinst{i}{}{i} -\declinst{j}{}{j} -\declinst{k}{}{k} -\referencestart{r}{ref}{i}{j} -\nextlevel -\gate{$g$}{rright} -\mess{b}{rright}{envright} -\gate[r][c]{$h$}{envright} -\nextlevel -\nextlevel -\mess{c}{rright}{k} -\gate*[l][b]{$h'$}{rright} -\nextlevel[2] -\referenceend{r} -\end{verbatim} -} -\end{minipage} - - -\subsection{High-level \MSC{}s} -\label{hmsc} -A High-level \MSC{} (\HMSC{}) is a drawing which defines the relation between -a number of \MSC{}s. It is composed of a start symbol (an upside down -triangle), a number of end symbols (represented by triangles), a -number of \MSC{} references (these are rectangles with rounded corners), -a number of conditions (hexagons) and possibly several connection -points (circles). These symbols are connected by arrows. - -The following commands can be used to draw \HMSC{}s. - -\begin{verbatim} -\begin{hmsc}[headerpos]{hmscname}(llx,lly)(urx,ury) -\end{hmsc} -\hmscstartsymbol{nickname}(x,y) -\hmscendsymbol{nickname}(x,y) -\hmscreference{nickname}{text}(x,y) -\hmsccondition{nickname}{text}(x,y) -\hmscconnection{nickname}(x,y) -\arrow{from-nickname}[coord-list]{to-nickname} -\end{verbatim} - -In order to draw \HMSC{}s, a new environment is defined, which is called -\verb+hmsc+. The command to begin this environment has several -arguments. The argument \verb+headerpos+ is optional. It controls -positioning of the header of the \HMSC{}. This argument can have values -\verb+l+ (for a left aligned header), \verb+c+ (for a centered header) -and \verb+r+ (for a right aligned header). The header of an \HMSC{} is -formed from the keyword \verb+msc+, followed by the -\verb+hmscname+. The size of the \HMSC{} frame is determined by the -coordinates of the lower-left corner, \verb+(llx,lly)+, and the -coordinates of the upper-right corner, \verb+(urx,ury)+. - -The \HMSC{} grid is not drawn, but used to control the positioning of the -\HMSC{} symbols (\verb+startsymbol+, \verb+endsymbol+, \verb+reference+, -\verb+condition+, and \verb+connection+). -The center of each symbol is drawn on the grid point -with coordinates \verb+{x,y}+. Each symbol also has a \verb+nickname+ -for later reference. - -\HMSC{} symbols can be connected by means of the \verb+arrow+ command. -This draws an arrow from the symbol with nickname \verb+from-nickname+ -to the symbol with nickname \verb+to-nickname+. The optional argument -\verb+coord-list+ can be used if the line connecting the source and -the destination should not be straight. The \verb+coord-list+ has -the following syntax: \verb+(x1,y1)(x2,y2)...(xk,yk)+. This means -that the connecting line goes through the points with coordinates -(x1,y1), (x2,y2), \ldots, (xk,yk). - -Arrows always leave the start symbol at the bottom. They enter the end symbol -at the top. -Arrows start and end either at the middle of the top or at the middle -of the bottom of a reference and condition symbol. The incoming -(outgoing) direction of the arrow determines whether it will start -(end) at the top or at the bottom. - -There are several parameters to control the size and shape of the -symbols (see Section~\ref{parameters}). These are -\verb+\hmscconditionheight+ (the height of the condition symbol), -\verb+\hmscconditionwidth+ (the width of the condition symbol, -excluding the left and right angular parts), -\verb+\hmscreferenceheight+ (the height of the reference symbol), -\verb+\hmscreferencewidth+ (the width of the reference symbol), -\verb+\messarrowscale{size}+ (a command to set the size of the arrow -head of a connection line); -\verb+setconnectiontype(type)+ (set the shape of the polyline -connection the symbols; \verb+type+ can be \verb+straight+, -\verb+rounded+, and \verb+curved+), -\verb+\startsymbolwidth+ (the width of the start and end symbol), -\verb+\topnamedist+ (sets the distance between the top of the \HMSC{} frame -and the \HMSC{} header). - -An example of an \HMSC{} is in the following diagram. Notice that the -width and height of reference symbols are changed locally (i.e., -between \verb+{+ and \verb+}+ braces) just before the big -reference~\verb+b+ is defined. - -\medskip - -\noindent -\begin{minipage}[c]{0.375\linewidth} - -\begin{hmsc}{High level}(-3,0)(3,12) -\hmscstartsymbol{s}(0,10) -\hmscreference{a}{A}(0,9) -\hmscconnection{c}(0,7.5) -{ -\setlength{\hmscreferencewidth}{2cm} -\setlength{\hmscreferenceheight}{3\baselineskip} -\hmscreference{b}{\parbox{1.9cm} - {\centering - this is a big - hmsc reference} - }(0,6) -} -\hmsccondition{t}{Again}(1,4.25) -\hmsccondition{ok}{Ok}(0,3.5) -\hmsccondition{q}{\textit{Break}}(-2,3.5) -\hmscendsymbol{e1}(-2,2) -\hmscreference{do}{Do it!}(0,2) -\hmscendsymbol{e2}(0,1) - -\arrow{s}{a} -\arrow{a}{c} -\arrow{c}{b} -\arrow{c}[(-2,7.5)]{q} -\arrow{b}{q} -\arrow{q}{e1} -\arrow{b}{ok} -\arrow{ok}{do} -\arrow{do}{e2} -\arrow{b}{t} -\arrow{t}[(1,3.5)(2.5,3.5)(2.5,7.5)]{c} -\end{hmsc} -\end{minipage}\hfill -\begin{minipage}[c]{0.6\linewidth} -{\footnotesize -\begin{verbatim} -\begin{hmsc}{High level}(-3,0)(3,12) -\hmscstartsymbol{s}(0,10) -\hmscreference{a}{A}(0,9) -\hmscconnection{c}(0,7.5) -{\setlength{\hmscreferencewidth}{2cm} - \setlength{\hmscreferenceheight} - {3\baselineskip} - \hmscreference{b}{\parbox{1.9cm} - {\centering this is a big hmsc reference} - }(0,6)} -\hmsccondition{t}{Again}(1,4.5) -\hmsccondition{ok}{Ok}(0,3.5) -\hmsccondition{q}{\textit{Break}}(-2,3.5) -\hmscendsymbol{e1}(-2,2) -\hmscreference{do}{Do it!}(0,2) -\hmscendsymbol{e2}(0,1) -\arrow{s}{a} -\arrow{a}{c} -\arrow{c}{b} -\arrow{c}[(-2,7.5)]{q} -\arrow{b}{q} -\arrow{q}{e1} -\arrow{b}{ok} -\arrow{ok}{do} -\arrow{do}{e2} -\arrow{b}{t} -\arrow{t}[(1,3.5)(2.5,3.5)(2.5,7.5)]{c} -\end{hmsc} -\end{verbatim} -} -\end{minipage} - - -\subsection{\MSC{} documents} -\label{mscdoc} -An \MSCdoc{} is a drawing which contains various declarations -of objects used in the \MSC{} description. For drawing \MSCdoc{}s -he following commands are provided. - -\begin{verbatim} -\begin{mscdoc}[headerpos]{mscdocname}{text}(llx,lly)(urx,ury) -\end{mscdoc} -\reference{text}(x,y) -\separator{y} -\end{verbatim} - -As for \MSC{} and \HMSC{}, a new environment is defined, which is named -\verb+mscdoc+. The command to begin an \MSCdoc{} has several -arguments. The argument \verb+headerpos+ is optional. It controls -positioning of the header of the \MSCdoc{}. -This argument can have values -\verb+l+ (for a left aligned header), \verb+c+ (for a centered header) -and \verb+r+ (for a right aligned header). -The header of an \MSCdoc{} is formed from the keyword \verb+mscdocument+, -followed by the \verb+mscdocname+. -The \verb+text+ is placed left-aligned below the \MSCdoc{} header. -The size of the \MSCdoc{} frame is determined by -coordinates of the lower-left corner, \verb+(llx,lly)+, and the -coordinates of the upper-right corner, \verb+(urx,ury)+. - -The \MSCdoc{} grid is not drawn, but used to control the positioning of the -\MSC{} references. -The center of such a reference is drawn on the grid point -with coordinates \verb+{x,y}+. - -The \verb+separator+ command draws a dashed horizontal line. The \MSC{} -references above the separator are the exported, while the ones below -the separator are local. - -There are several parameters to control the size and shape of the -symbols (see Section~\ref{parameters}). -\verb+\mscdocreferenceheight+ (the height of the reference symbol), -\verb+\mscdocreferencewidth+ (the width of the reference symbol), -\verb+\topnamedist+ (sets the distance between the top of the \MSCdoc{} -frame and the \MSCdoc{} header). - -An example of an \MSCdoc{} is in the following diagram. Notice that -the size of references in an \MSCdoc{} had to be changed for the last -reference. - -\medskip - - -\begin{minipage}{0.4\linewidth} -\begin{mscdoc}{My declarations}% - (0,0)(6,8) -\reference{a}(1,6) -\reference{b}(3,6) -\reference{c}(1,4) -\reference{d}(3,4) -\separator{3} -\setlength{\mscdocreferencewidth}{4.5\mscunit} -\setlength{\mscdocreferenceheight}{2\baselineskip} -\reference{% - \parbox{4\mscunit}% - {\raggedright This is a - two-line reference}} - (3,1.5) -\end{mscdoc} -\end{minipage} -% -\begin{minipage}{0.5\linewidth} -{\small -\begin{verbatim} -\begin{mscdoc}{My declarations}% - (0,0)(6,8) -\reference{a}(1,6) -\reference{b}(3,6) -\reference{c}(1,4) -\reference{d}(3,4) -\separator{3} -\setlength{\mscdocreferencewidth} - {4.5\mscunit} -\setlength{\mscdocreferenceheight} - {2\baselineskip} -\reference{% - \parbox{4\mscunit}% - {\raggedright This is a - two-line reference}} - (3,1.5) -\end{mscdoc} -\end{verbatim} -} -\end{minipage} - - - -\section{Style parameters} -\label{parameters} - -By means of a collection of parameters, the graphical appearance of -an \MSC{} can be fine tuned to the user's taste. -The general parameters -are displayed in Figure~\ref{parametersfig} on page~\pageref{parametersfig}. - -%======================== -\begin{figure}[htb] -\vspace{2ex} %Needed to get enough white space before the top label of - %the figure. - -\newcommand{\printlength}[1]{\mbox{\footnotesize\ttfamily \char`\\#1}} -\begin{center} -\setmscvalues{normal} -\begin{msc}{Lengths} -\psset{linewidth=.4pt,dotsep=1pt} -\newlength{\lta} -\newlength{\ltb} -% \topnamedist -\psline[linestyle=dotted](1.5cm,-\topnamedist)(2.5cm,-\topnamedist) -\psline[arrowscale=1.3]{->}(2.5cm,.2cm)(2.5cm,0cm) -\setlength{\lta}{\topnamedist+.2cm} -\psline[arrowscale=1.3]{->}(2.5cm,-\lta)(2.5cm,-\topnamedist) -\rput[tl](2.5cm,.4cm){\printlength{topnamedist}} - -% \leftnamedist -\setlength{\lta}{\leftnamedist+10pt} -\setlength{\ltb}{\topnamedist} -\psline[linestyle=dotted,arrowscale=1.0]{->}(-10pt,-\ltb)(0,-\ltb) -\psline[linestyle=dotted,arrowscale=1.0]{->}(\lta,-\ltb)(\leftnamedist,-\ltb) -\psline[linestyle=dotted](\leftnamedist,10pt)(\leftnamedist,-\baselineskip) -\rput[br](-10pt,-\ltb){\printlength{leftnamedist}} - -% \topheaddist -\setlength{\lta}{\envinstdist+\instdist-.5\instwidth} -\psline[arrowscale=1.3,linestyle=dotted]{<->}(\lta,0cm)(\lta,-\topheaddist) -\rput[l](\lta,-.5\topheaddist){ \printlength{topheaddist}} - -% \bottomfootdist -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\lastlevelheight+\instfootheight+\levelheight*12} -\setlength{\lta}{\envinstdist+2\instdist-.5\instwidth} -\rput[tl](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\bottomfootdist)} -\setlength{\ltb}{\ltb+.5\bottomfootdist} -\rput[l](\lta,-\ltb){\printlength{bottomfootdist}} - -% \instheadheight -\setlength{\lta}{\envinstdist+2\instdist+.5\instwidth+.2cm} -\setlength{\ltb}{\topheaddist} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\instheadheight)} -\setlength{\ltb}{\ltb+.5\instheadheight} -\rput[l](\lta,-\ltb){\printlength{instheadheight}} - -% \firstlevelheight -\setlength{\lta}{\envinstdist+\instdist+.2cm} -\setlength{\ltb}{\topheaddist+\instheadheight} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,-\firstlevelheight)} -\setlength{\ltb}{\ltb+.5\firstlevelheight} -\rput[l](\lta,-\ltb){\printlength{firstlevelheight}} - -% \levelheight -\setlength{\lta}{\envinstdist+\instdist+.2cm} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\levelheight)} -\setlength{\ltb}{\ltb+.5\levelheight} -\rput[l](\lta,-\ltb){\printlength{levelheight}} - -% \actionheight -\setlength{\lta}{\envinstdist+2\instdist+0.5\actionwidth+.2cm} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*7} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\actionheight)} -\setlength{\ltb}{\ltb+.7\actionheight} -\rput[bl](\lta,-\ltb){\printlength{actionheight}} - -% \actionwidth -\setlength{\lta}{\envinstdist+2\instdist-0.5\actionwidth} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*7-.2cm} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\actionwidth,0)} -\setlength{\lta}{\lta+.5\actionwidth} -\setlength{\ltb}{\ltb-.1cm} -\rput[bl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{actionwidth}} - -% \conditionheight -\setlength{\lta}{\envinstdist+2\instdist+\conditionoverlap+0.8\conditionheight} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*10} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\conditionheight)} -\setlength{\ltb}{\ltb+.7\conditionheight} -\rput[bl](\lta,-\ltb){\printlength{conditionheight}} - -% \inlineoverlap -\setlength{\lta}{\envinstdist} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*5-.2cm} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\inlineoverlap,0)} -%\setlength{\lta}{\lta+\inlineoverlap} -\setlength{\ltb}{\ltb-.1cm} -\rput[bl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{inlineoverlap}} - -% \referenceoverlap -\setlength{\lta}{\envinstdist} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*7-.2cm} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\referenceoverlap,0)} -%\setlength{\lta}{\lta+\referenceoverlap} -\setlength{\ltb}{\ltb-.1cm} -\rput[bl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{referenceoverlap}} - -% \conditionoverlap -\setlength{\lta}{\envinstdist+2\instdist} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*10-.2cm} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\conditionoverlap,0)} -%\setlength{\lta}{\lta+\conditionoverlap} -\setlength{\ltb}{\ltb-.1cm} -\rput[bl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{conditionoverlap}} - -% \lastlevelheight -\setlength{\lta}{\envinstdist+2\instdist+.2cm} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*12} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(0,-\lastlevelheight)} -%\setlength{\ltb}{\ltb+.5\lastlevelheight} -\rput[bl](\lta,-\ltb){\printlength{lastlevelheight}} - -% \instfootheight -\setlength{\lta}{\envinstdist+2\instdist+.5\instwidth+.1cm} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*12+\lastlevelheight} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3]{->}(0,.3cm)(0,0)} -\setlength{\ltb}{\ltb+\instfootheight} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3]{->}(0,-.3cm)(0,0)} -\rput[tl](\lta,-\ltb){ \printlength{instfootheight}} - -% \selfmesswidth -\setlength{\lta}{\envinstdist-\selfmesswidth} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*2-.2cm} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\selfmesswidth,0)} -%\setlength{\lta}{\lta+\selfmesswidth} -\rput[r](\lta,-\ltb){\printlength{selfmesswidth}} - -% \regionbarwidth -\setlength{\lta}{\envinstdist+2\instdist-.5\regionbarwidth} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*2-.2cm} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\regionbarwidth,0)} -\setlength{\lta}{\lta+\regionbarwidth} -\rput[l](\lta,-\ltb){\printlength{regionbarwidth}} - -% \instwidth -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\lastlevelheight+\instfootheight+\levelheight*12+.2cm} -\setlength{\lta}{\envinstdist-0.5\instwidth} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\instwidth,0)} -\rput[tl](\lta,-\ltb){\rule{0pt}{2ex}\printlength{instwidth}} - -% \instdist -\setlength{\lta}{\envinstdist} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+2.5\levelheight} -\rput[l](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\instdist,0)} -\setlength{\lta}{\lta+.5\instdist} -\setlength{\ltb}{\ltb-.1cm} -\rput[b](\lta,-\ltb){\printlength{instdist}} - -% \envinstwidth -\setlength{\lta}{0cm} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+.5\levelheight} -\rput[l](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\envinstdist,0)} -\rput[tl](\lta,-\ltb){ \printlength{envinstdist}} - - -% \labeldist -\setlength{\lta}{\envinstdist-.5\instwidth} -\setlength{\ltb}{\topheaddist-\labeldist} -\rput[l](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted](-.2cm,0)(.5cm,0)} -\rput[b](\lta,-\ltb){\psline[arrowscale=1.3]{->}(-.1cm,.3cm)(-.1cm,0)} -\setlength{\ltb}{\topheaddist} -\rput[l](\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted](-.2cm,0)(.5cm,0)} -\rput[b](\lta,-\ltb){\psline[arrowscale=1.3]{->}(-.1cm,-.3cm)(-.1cm,0)} -\rput[tr](\lta,-\ltb){\printlength{labeldist} } - -% \timerwidth -\setlength{\lta}{\envinstdist-\selfmesswidth-0.5\timerwidth} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*4+.4cm} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\timerwidth,0)} -%\setlength{\lta}{\lta+\selfmesswidth} -\rput[r](\lta,-\ltb){\printlength{timerwidth}} - -% \stopwidth -\setlength{\lta}{\envinstdist+\instdist-0.5\stopwidth} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*4+0.5\stopwidth+.1cm} -\rput(\lta,-\ltb){\psline[arrowscale=1.3,linestyle=dotted]{<->}(0,0)(\stopwidth,0)} -\setlength{\lta}{\lta+\stopwidth} -\rput[l](\lta,-\ltb){\printlength{stopwidth}} - -% \lostsymbolradius -\setlength{\lta}{\envinstdist+2\instdist+\selfmesswidth+2\lostsymbolradius+0.1cm} -\setlength{\ltb}{\topheaddist+\instheadheight+\firstlevelheight+\levelheight*4} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3]{->}(0,.3cm)(0,0)} -\setlength{\ltb}{\ltb+\lostsymbolradius} -\rput[t](\lta,-\ltb){\psline[arrowscale=1.3]{->}(0,-.3cm)(0,0)} -\rput[tl](\lta,-\ltb){ \printlength{lostsymbolradius}} - -\psset{linewidth=.8pt,dotsep=3pt} - -\declinst{m1}{aname}{iname} -\declinst{st}{}{} -\declinst{m2}{}{} - -\mess{msg1}{m1}{st} -\nextlevel -\mess{msg2}{m1}{st} -\nextlevel -\mess{self}{m1}{m1} -\coregionstart{m2} -\nextlevel -\coregionend{m2} -\nextlevel -\lost[r]{x}{}{m2} -\stop{st} -\settimer{T}{m1} -\nextlevel -\inlinestart{alt}{alt}{m1}{m1} -\nextlevel[2] -\inlineend{alt} -\action{a}{m2} -\nextlevel -\referencestart{ref}{reference}{m1}{m1} -\nextlevel -\referenceend{ref} -\nextlevel -\condition{cond1}{m1,m2} -\nextlevel -\nextlevel -\mess{msg3}{m2}{m1} -\end{msc} -\end{center} - - -\caption{User controllable parameters} -\label{parametersfig} -\end{figure} - -The value of a parameter can be changed using standard -\LaTeX\ commands, e.g. -\begin{verbatim} -\setlength{\levelheight}{1cm} -\end{verbatim} - -The following list describes all parameters. -The default values for drawing \MSC{}s at large, normal and small size are -included. See the command \verb+\setmscvalues{size}+ below for -restoring the parameters to their original values. - -%======================== -\begin{defs} - -\item[\cmd{actionheight}] -Height of action symbols.\\ -(\lnsvalue{0.75}{0.6}{0.5} cm.) - -\item[\cmd{actionwidth}] -Width of action symbol.\\ -(\lnsvalue{1.25}{1.25}{1.2} cm.) - -\item[\cmd{bottomfootdist}] -Distance between bottom of foot symbol and frame.\\ -(\lnsvalue{1.0}{0.7}{0.5} cm.) - -\item[\cmd{commentdist}] -Distance between a comment and its instance.\\ -(\lnsvalue{0.5}{0.5}{0.5} cm.) - -\item[\cmd{conditionheight}] -Height of condition symbols.\\ -(\lnsvalue{0.75}{0.6}{0.5} cm.) - -\item[\cmd{conditionoverlap}] -Overlap of condition symbol.\\ -(\lnsvalue{0.6}{0.5}{0.4} cm.) - -\item[\cmd{envinstdist}] -Distance between environments and nearest instance line.\\ -(\lnsvalue{2.5}{2.0}{1.2} cm.) - -\item[\cmd{firstlevelheight}] Height of level just below head -symbols. Should not be changed inside the \MSC{} environment.\\ -(\lnsvalue{0.75}{0.6}{0.4} cm.) - -\item[\cmd{hmscconditionheight}] -Height of \HMSC{} condition symbol.\\ -(\lnsvalue{0.375}{0.3}{0.25} cm.) - -\item[\cmd{hmscconditionwidth}] -Width of \HMSC{} condition symbol.\\ -(\lnsvalue{1.0}{0.8}{0.7} cm.) - -\item[\cmd{hmscconnectionradius}] -Radius of \HMSC{} connection symbol.\\ -(\lnsvalue{0.06}{0.05}{0.04} cm.) - -\item[\cmd{hmscreferenceheight}] -Height of \HMSC{} reference symbol.\\ -(\lnsvalue{0.375}{0.3}{0.25} cm.) - -\item[\cmd{hmscreferencewidth}] -Width of \HMSC{} reference symbol.\\ -(\lnsvalue{1.0}{0.8}{0.7} cm.) - -\item[\cmd{hmscstartsymbolwidth}] -Width of \HMSC{} start symbol.\\ -(\lnsvalue{0.75}{0.6}{0.3} cm.) - -\item[\cmd{inlineoverlap}] -Overlap of inline symbol.\\ -(\lnsvalue{1.5}{1.0}{0.75} cm.) - -\item[\cmd{instbarwidth}] -Default width of vertical instance bars (applies to fat instances only).\\ -(\lnsvalue{0.0}{0.0}{0.0} cm.) - -\item[\cmd{instdist}] -Distance between instance axes.\\ -(\lnsvalue{3.0}{2.2}{1.5} cm.) - -\item[\cmd{instfootheight}] Height of foot symbols. Should not be -changed inside the \MSC{} environment.\\ -(\lnsvalue{0.25}{0.2}{0.15} cm.) - -\item[\cmd{instheadheight}] Height of head symbols. Should not be -changed inside the \MSC{} environment.\\ -(\lnsvalue{0.6}{0.55}{0.5} cm.) - -\item[\cmd{instwidth}] -Width of header and foot symbols.\\ -(\lnsvalue{1.75}{1.6}{1.2} cm.) - -\item[\cmd{labeldist}] -Distance between labels and the symbols to which they belong (for instance, message labels and arrows).\\ -(\lnsvalue{1.0}{1.0}{1.0} ex.) - -\item[\cmd{lastlevelheight}] Height of level just above foot -symbols. Should not be changed inside the \MSC{} environment.\\ -(\lnsvalue{0.5}{0.4}{0.3} cm.) - -\item[\cmd{leftnamedist}] Distance between left of the frame and -(left of) \MSC, \HMSC, or \MSCdoc{} title.\\ -(\lnsvalue{0.3}{0.2}{0.1} cm.) - -\item[\cmd{levelheight}] -Height of a level.\\ -(\lnsvalue{0.75}{0.5}{0.4} cm.) - -\item[\cmd{lostsymbolradius}] -Radius of the lost and found symbols.\\ -(\lnsvalue{0.15}{0.12}{0.08} cm.) - -\item[\cmd{markdist}] -Horizontal distance from a mark to its instance.\\ -(\lnsvalue{1.0}{1.0}{1.0} cm.) - -\item[\cmd{measuredist}] -Horizontal distance from a measure to its (closest) instance.\\ -(\lnsvalue{1.0}{1.0}{1.0} cm.) - -\item[\cmd{measuresymbolwidth}] -Width of a measure symbol.\\ -(\lnsvalue{0.75}{0.6}{0.4} cm.) - -\item[\cmd{mscdocreferenceheight}] -Height of reference symbol in an \MSCdoc.\\ -(\lnsvalue{0.375}{0.3}{0.25} cm.) - -\item[\cmd{mscdocreferencewidth}] -Width of reference symbol in an \MSCdoc.\\ -(\lnsvalue{1.0}{0.8}{0.7} cm.) - -\item[\cmd{referenceoverlap}] -Overlap of reference symbol.\\ -(\lnsvalue{1.5}{1.0}{0.75} cm.) - -\item[\cmd{regionbarwidth}] -Width of region bars.\\ -(\lnsvalue{0.5}{0.4}{0.2} cm.) - -\item[\cmd{selfmesswidth}] -Length of horizontal arms of self messages.\\ -(\lnsvalue{0.75}{0.6}{0.4} cm.) - -\item[\cmd{stopwidth}] -Width of the stop symbol.\\ -(\lnsvalue{0.6}{0.5}{0.3} cm.) - -\item[\cmd{timerwidth}] -Width of the \emph{timer} symbols.\\ -(\lnsvalue{0.4}{0.3}{0.2} cm.) - -\item[\cmd{topheaddist}] -Distance between top of head symbols and frame.\\ -(\lnsvalue{1.5}{1.3}{1.2} cm.) - -\item[\cmd{topnamedist}] Distance between top of the frame and -(top of) \MSC, \HMSC, or \MSCdoc{} title.\\ -(\lnsvalue{0.3}{0.2}{0.2} cm.) - -\end{defs} - -In addition there are several commands which allow the user to adjust -the \MSC{} drawing to his own taste. - -\begin{defs} - -\item[\cmd{messarrowscale}\{\emph{scalefactor}\}] Sets the scale -factor (a positive real number) of message arrow -heads. (\lnsvalue{2}{1.5}{1.2}) - -\item[\cmd{setmscscale}\{\emph{scalefactor}\}] Sets the scale factor -of the \MSC{} environment to \emph{scalefactor}. the scale factor is -supposed to be a real number. Scaling is done when the \MSC{} -environment ends (\verb|\end{msc}|). The default of \emph{scalefactor} -is~1. A more consistent way for -varying the size of the \MSC{} can be obtained by using the -\verb+\setmesvalues+ command as described below. -(default value 1.) - -\item[\cmd{psset}\{\texttt{linewidth=D}\}] This command sets the width -of all lines in \MSC{}s, \HMSC{}s, and \MSCdoc{}s to length \verb+D+. If -this command is issued outside the msc environment, then the value is -set for the complete document. If it is used directly after the start -of the msc environment it only holds for this \MSC{}.\\ -(large/normal/small value 0.8/0.7/0.6 pt.) - -\item[\cmd{setfootcolor}\{\emph{color}\}] Sets the color of the foot -symbols of \MSC{} instances. Possible values are \emph{black}, -\emph{white}, \emph{gray}, or \emph{lightgray}. For more color values, -see the documentation of the \LaTeXe{} \textsf{color} package. - -\end{defs} - -The following command can be used to set the above mentioned -style parameters to suitable values. - -\begin{defs} -\item[\cmd{setmscvalues}\{\emph{size}\}] Sets all parameters of the \mscpack{} to - predefined values. Valid values for \emph{size} are: -\verb|small|, \verb|normal|, and \verb|large|. -(The default value of \verb+size+ is \verb+normal+. -This can be used for drawings with at maximum six instances on a -sheet of A4 paper. -For sizes \verb+large+ and \verb+small+, a maximum of four and nine -instances respectively fit on a sheet of A4 paper.) -\end{defs} - -Caution has to be taken when changing the value of a parameter within -the \MSC{} definition. The following parameters can be changed within an -\MSC{} definition without unexpected side effects: - -\begin{flushleft} -\verb+\actionheight+, -\verb+\actionwidth+, -\verb+\bottomfootdist+, -\verb+\conditionheight+, -\verb+\conditionoverlap+, -\verb+\inlineoverlap+, -\verb+\instfootheight+, -\verb+\instwidth+ (however, this may cause different sizes of -corresponding instance header and footer symbols), -\verb+\labeldist+, -\verb+\lastlevelheight+, -\verb+\levelheight+, -\verb+\lostsymbolradius+, -\verb+\referenceoverlap+, -\verb+\regionbarwidth+, -\verb+\selfmesswidth+, -\verb+\stopwidth+, -\verb+\timerwidth+, and -\verb+\topnamedist+. -\end{flushleft} - - -In addition to the parameters specific to the \mscpack, -standard \LaTeX\ commands can be used to change the type style and -other details. -For example, if the command \verb+\sffamily+ is included directly after -the start of the msc environment, the text in the \MSC{} -is drawn using a {\sf sans serif} font. Likewise, the text size can be -changed by inserting, e.g., the command \verb+\small+. -The \verb+\raisebox+ and \verb+\parbox+ commands -can also be used to position and format names. - - -\section{Example} -\label{example} -Figure~\ref{ex} on page~\pageref{ex} shows the \MSC{} defined in the -following \LaTeX\ fragment. - -{\small -\begin{verbatim} -\begin{msc}{Example} -\declinst{usr}{The user}{User} -\declinst{m1}{Control}{M1} -\dummyinst{m2} -\declinst{m3}{Another Machine}{M3} - -\create{start}{m1}{m2}{Processing}{M2} -\mess{msg 0}{envleft}{usr} -\mess{msg 1}{envright}{m2}[1] -\nextlevel - -\mess{msg 2}{usr}{m1} -\order{m1}{m2}[4] -\action{a}{m3} - -\nextlevel -\found{msg x}{}{usr} -\nextlevel - -\mess{msg 3}{usr}{m2}[-1] -\coregionstart{m1} -\settimeout{S}{m3}[2] -\nextlevel - - -\mess{msg 4}{m1}{usr} -\coregionstart{m2} -\settimer[r]{T}{m3} -\nextlevel - -\mess[r]{msg 5}{m2}{m2}[3] -\mess{msg 6}{usr}{usr}[2] -\nextlevel - -\mess{msg 7}{m2}{usr} -\timeout[r]{T}{m3} -\nextlevel - -\coregionend{m2} -\nextlevel - -\coregionend{m1} -\stoptimer[r]{T'}{m3} -\nextlevel - -\lost[r]{msg y}{Mach 1}{usr} -\mess{msg 8}{m1}{envright} -\nextlevel - -\condition{condition 1}{usr,m2} -\setstoptimer[r]{U}{m3} -\nextlevel[2] -\stop{usr} - -\end{msc} -\end{verbatim} -} - -\begin{figure}[htb] -\begin{center} -\begin{msc}{Example} -\declinst{usr}{The user}{User} -\declinst{m1}{Control}{M1} -\dummyinst{m2} -\declinst{m3}{Another Machine}{M3} - -\create{start}{m1}{m2}{Processing}{M2} -\mess{msg 0}{envleft}{usr} -\mess{msg 1}{envright}{m2}[1] -\nextlevel - -\mess{msg 2}{usr}{m1} -\order{m1}{m2}[4] -\action{a}{m3} - -\nextlevel -\found{msg x}{}{usr} -\nextlevel - -\mess{msg 3}{usr}{m2}[-1] -\coregionstart{m1} -\settimeout{S}{m3}[2] -\nextlevel - - -\mess{msg 4}{m1}{usr} -\coregionstart{m2} -\settimer[r]{T}{m3} -\nextlevel - -\mess[r]{msg 5}{m2}{m2}[3] -\mess{msg 6}{usr}{usr}[2] -\nextlevel - -\mess{msg 7}{m2}{usr} -\timeout[r]{T}{m3} -\nextlevel - -\coregionend{m2} -\nextlevel - -\coregionend{m1} -\stoptimer[r]{T'}{m3} -\nextlevel - -\lost[r]{msg y}{Mach 1}{usr} -\mess{msg 8}{m1}{envright} -\nextlevel - -\condition{condition 1}{usr,m2} -\setstoptimer[r]{U}{m3} -\nextlevel[2] -\stop{usr} - -\end{msc} - -\caption{A menagerie of \MSC{} symbols} -\label{ex} -\end{center} -\end{figure} - - -\section{Acknowledgments} -Thanks are due to the following people for providing us with useful -input: Peter Peters, Michel Reniers. - -\bibliographystyle{plain} -\bibliography{biblio} - -\end{document} diff --git a/Master/texmf-dist/doc/latex/msc/msc.pdf b/Master/texmf-dist/doc/latex/msc/msc.pdf new file mode 100644 index 00000000000..da4db8cccba Binary files /dev/null and b/Master/texmf-dist/doc/latex/msc/msc.pdf differ diff --git a/Master/texmf-dist/doc/latex/msc/msc.tex b/Master/texmf-dist/doc/latex/msc/msc.tex new file mode 100644 index 00000000000..10b32f11a9e --- /dev/null +++ b/Master/texmf-dist/doc/latex/msc/msc.tex @@ -0,0 +1,2299 @@ +% file: manual.tex +% Copyright 2008-2013 V. Bos, T. van Deursen, P. Kordy, and S. Mauw +% This file is part of the MSC Macro Package. +% +\documentclass[12pt,a4paper]{article} +\def\pgfautoxrefs{1} +\usepackage[version=latest]{pgf} +\usepackage{xparse} +% \usepackage{a4wide} +% \usepackage{url} +\usepackage{moreverb} +\usepackage{multicol} +\usepackage{msc} +\usepackage{showexpl} +\usepackage{xkeyval,calc,listings,tikz,fp} +\usepackage{hyperref} +\usepackage{ifluatex} +\usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry} +\usepackage{amsmath,amssymb} +\usepackage{xxcolor} +\usepackage{pifont} +\usepackage{makeidx} +\usepackage{compsci} +\usepackage{xstring} +% \usepackage{pgfmanual} +\newcommand{\PK}[1]{% +{\color{red}{\bf[PK]} #1}} + +% we allow a ragged right +\setlength{\rightskip}{0pt plus 0.05\linewidth minus 0pt} + +\input{manual-macros.tex} +% \hypersetup{hidelinks} +\hypersetup{% + colorlinks=true, % use true to enable colors below: + linkcolor=blue,%red, + filecolor=blue,%magenta, + urlcolor=blue,%cyan, + citecolor=blue, + pdfborder=0 0 0, +} + +\makeindex +\makeatletter +\def\convertto#1#2{\strip@pt\dimexpr #2*65536/\number\dimexpr 1#1}%\dimexpr require etex +\input{pgfmanual.code} +\pgfkeys{ + % list is tried to find a match. + /pdflinks/search key prefixes in={/msc/,/tikz/,/pgf/,/depgraph/}, + % +} +\newcommand{\msckey}[3]{ + \IfEndWith*{\mscget{#1}}{pt}{% + \IfStrEq*{#1}{label distance}{ + \def\tmp{\convertto{ex}{\mscget{#1}}ex} + }{ + \def\tmp{\convertto{cm}{\mscget{#1}}cm} + } + }{% + \edef\tmp{\mscget{#1}} + } + + \begin{key}{/msc/#1=#2 (initially \tmp)} + #3 + \end{key} +} +\newcommand{\mscstyle}[2]{ + \begin{stylekey}{/msc/#1} + #2 + \end{stylekey} +} + +% 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). +{\catcode`\|=\z@ \catcode`\\=12 |gdef|bslash{\}} +\makeatother +\title{ + A \LaTeX{} macro package for Message Sequence Charts\\{\large User Manual} +} + +\author{ + \begin{tabular}{c} + \begin{tabular}{ccc} + Victor Bos & & + Ton van Deursen\\ + & & \\ + Piotr Kordy& & + Sjouke Mauw + \end{tabular}\\ + \end{tabular} +} + +\date{\small Version A\mscversion, last update \today\\ + Describing \mscpack{} version \mscversion} + +\begin{document} + +\maketitle + +\begin{abstract} +\noindent +The \mscpack{} facilitates the \LaTeX\ user to easily include +Message Sequence Charts in his texts. This document describes the +design and use of the \mscpack. +\end{abstract} + +\tableofcontents +\section{New} +\label{new} +\paragraph{Version~2.00} is the result of a complete rewrite of the package. +The main difference is that the package is +now implemented in \tikzname\ instead of \verb+PSTricks+, making it +compatible with +\verb+pdfLaTex+ and \beamer. + +In addition the syntax has been slightly extended. It now supports the +specification of all options as a comma separated list in square +brackets, while remaining backward compatible. All lengths are now +stored using \pgfname\ keys. As a result it is possible to change +sizes of shapes individually. Support for colors is added. + +We are much indebted to Adrian Farmadin (Masaryk University, Czech +Republic) for initiating and contributing to this software rehaul. + + +\paragraph{Version~1.17} slightly modifies the handling of the +|offset| argument of the |\mess|, |\setstoptimer|, and +|\settimeout| commands. All commands with an |offset| +argument can now properly handle real numbers as +argument. Furthermore, the \verb+\topheaddist+, +\verb+\firstlevelheight+, and \verb+\instheadheight+ lengths are now +taken into account when computing the height of the instance and the +\verb+\gatesymbolradius+ length is now properly implemented. + +The |\condition*| macro is now extended to dynamically +resize a condition symbol that spans multiple instances. The +|\condition*| and |\action*| macros, introduced in the +previous release, no longer shrink to a size smaller than their +non-starred counterparts. The |\condition| and +|\action| have crossed-out counterparts |\ncondition| and +|\naction| respectively. + +A variation to the \verb+\stop+ command is implemented. Rather than +drawing a cross to denote that an instance has stopped, the +\verb+\stop*+ command draws an instance footer. + +Finally, the \verb+\create+ command no longer requires the +\verb+creator+ parameter to be specified. If it is not specified, no +arrow is drawn from the creator to the dynamically created instance. + + +\paragraph{Version~1.16} solves a bug that was due to a change in +syntax of the \verb+scalebox+ macro in the \verb+PSTricks+ package. + +The |\action| and |\condition| macros are extended with a +starred option. The starred version of the macros automatically +adjusts the size of the rectangle and hexagon based on the size of the +contents. + +\paragraph{Version~1.13} has a reimplementation of message commands in MSC +diagrams. The affected commands are: |\create|, |\found|, +|\lost|, |\mess|, and |\order|. The new implementation +provides more control over the placement of message labels. + +The command \verb+\selfmesslabelpos+ has been removed. + +The bounding box bug has been partly solved. Now, a white |\fbox| +is drawn around every (msc, mscdoc, hmsc) diagram. This makes it +possible for \texttt{dvips -E} to compute the correct bounding box for +the diagrams. Due to the |\fbox|, each diagram is extended with +0.3pt on each side (left, top, right, and bottom). This bugfix fails +if the background is not white. The xdvi program shows the white +|\fbox| in black with the result that diagrams have two visible +frames. This seems to be a bug of xdvi. + +The lines around comments (|\msccomment|, Section~\ref{comments}) +are changed from gray into black. The reason for this is that the gray +lines became invisible after converting the document to HTML. + +\section{Introduction} +\label{introduction} + +The \MSC{} language is a visual language for the description of the +interaction between different components of a system. +This language is standardized by the ITU (International +Telecommunication Union) in Recommendation Z.120~\cite{z120}. An +introductory text on \MSC{} can be found +in~\cite{RudolphGrabowskiGraubmann96}. \MSC{}s have a +wide application domain, ranging from requirements specification to +testing and documentation. +An example of a Message Sequence Chart is in Figure~\ref{quick}. + +In order to support easy drawing of \MSC{}s in \LaTeX\ documents, we have +developed the \mscpack. The current version of the \mscpack{} +supports the following \MSC{} constructs: \MSC{} frame, instances (both +single line width and double line width), messages (including +self-messages and messages to the environment), actions, singular and +combined timer events (set, timeout, reset, set-timeout, set-stop), +lost and found messages, generalized order, conditions, coregions, +activation regions, suspension regions, gates, instance creation, +instance stop, time measurements, references, and inline +expressions. In addition, there is support for \HMSC{}'s (high-level +\MSC{}s) and \MSCdoc{}s. + +In this manual we explain the design and the use of the \mscpack. For +a complete overview of all features, we refer to the reference +manual~\cite{BM02}, which is included in the distribution under the +name \verb+refman.ps+. Another way to learn how to use the \mscpack{} +is to have a look at the \LaTeX{} source code of the manual and the +source code of the reference manual. They are included in the +distribution under the names \verb+manual.tex+ and \verb+refman.tex+, +respectively. The \MSC{} constructs are simply introduced as +syntactic constructs. This paper is not meant to describe their use or +meaning. + +We list the backgrounds of the package and some design decisions in +Section~\ref{background}. +Section~\ref{install} contains notes on installing the +package. Section~\ref{quickstart} contains an example of using the +package. It allows the impatient reader to quickly start using the +package. The details of using the package are explained in +Section~\ref{use}. In Section~\ref{parameters} the parameters are +explained which determine detailed layout of the various symbols. +A large but meaningless example is given in +Section~\ref{example}. + + +\section{Background and motivation} +\label{background} +Several commercial and non-commercial tools are available, which +support drawing or generating Message Sequence Charts. However, these +tools are in general not freely available and often not flexible +enough to satisfy all user's wishes with respect to the layout and +graphical appearance of an \MSC{}. +Therefore, people often use general drawing tools, such as {\em xfig} +to draw \MSC{}s. However flexible this approach is, it takes quite some +effort to produce nice \MSC{} drawings in a tool which is not dedicated +to \MSC{}s. Furthermore, when drawing a number of \MSC{}s it requires some +preciseness in order to obtain a consistent set of \MSC{}s. + +For these reasons, we have started the design of a set of +\LaTeX\ macros which support the drawing of \MSC{}s. In this way, an \MSC{} can be +represented in \LaTeX\ in a textual format and compiled into +e.g.\ PostScript. + +We aimed at satisfying the following requirements and design +decisions. +\begin{itemize} +\item +The package should follow the ITU standard with respect to shape and +placement of the symbols. (The current version supports +the \MSC2000 standard.) +\item +Static and dynamic semantics are not considered. The user is allowed +to violate all semantical restrictions and draw inconsistent \MSC{}s. +The package only supports elementary syntactical requirements. +\item +The package should offer functionality at the right level of +abstraction. Rather than supplying coordinates of pixels, the +user should be able to express the placement of symbols in terms of +{\em levels}. +Nevertheless, the textual representation of \MSC{}s as defined by the ITU +standard has a level of abstraction which is too high for our purposes. +It lacks information about the actual positioning of the \MSC{} symbols, +while we think that in our package this should be under user control. +\item +There should be only minimal automatic restructuring and layout of the +\MSC{} (e.g.\ the relative positioning of two messages should be as +defined by the user, even if the messages are not causally ordered). +\item +The user can customize the appearance of the \MSC{}s by manipulating +an appropriate set of parameters. +\end{itemize} + +\section{Installation, copyright and system requirements} +\label{install} + +The \mscpack{} is still under development. The authors +appreciate any comments and suggestions for improvements. The most +recent version of the package can be downloaded from +\url{http://satoss.uni.lu/mscpackage/}. + + +The \mscpack{} has a \emph{LaTeX Project Public License} +(LPPL), see~\url{http://www.latex-project.org/lppl.txt}: +{\small +\verbatiminput{COPYRIGHT} +} As such, it is free of charge and can be freely +distributed. Furthermore, it is allowed to make modifications to the +package, provided that modified versions get different names. The +authors accept no liability with respect to the functioning of the +package. + +The \mscpack{} runs with \LaTeXe. It has been tested with \LaTeXe\ +version dated 1998/06/01 using \TeX\ version 3.14159. The following +additional packages are required: \textsf{tikz}, \textsf{calc}, +and \textsf{xstring}. These packages are in general +part of the standard \LaTeXe\ distribution. These additional packages +can be obtained from the {\em ctan} database for \LaTeX\, e.g.\ via +the following URL: \url{http://www.tex.ac.uk/}. The \textsf{tikz} +package is described shortly in~\cite{mertz2007graphics} or in the \pgfname +manual~\cite{tantau2022pgf}. +The generated output can be previewed with pdf/ps previewing software. +It may be needed to update all \LaTeX\ related software +to a more recent version in order to smoothly work with the \mscpack. + +The \mscpack{} can be installed easily. Just put the file +|msc.sty| in a directory which is searched by \LaTeX{} for style +files. The set of directories actually searched depends on the \TeX\ +installation, but often the {\em current directory} is included. UNIX +users may have to set the environment variable \texttt{\$TEXINPUTS} to +an appropriate value. For more details on this topic consult +documentation of your \TeX\ installation. + +%The following text is currently not applicable -sm +% +%A problem may occur when using more packages than the \MSC{} macro +%package in your \LaTeX\ document. This happens, e.g.\ when using the +%{\em epsfig} package. These problems are due to the combination of +%several packages which are required (but not provided) by the \MSC{} +%macro package. The solution is to change the order of the +%\verb+usepackage+ clauses. + +\section{Quick start} +\label{quickstart} +The \mscpack{} is easy to use. +Below is an example of the use of the package and +Figure~\ref{quick} shows the generated \MSC{}. +\begin{figure}[htbp] +\begin{center} +\begin{codeexample}[width=\linewidth-6.8cm] +\begin{msc}{Example} +\declinst{usr}{User}{} +\declinst{m1}{Machine 1}{control} +\declinst{m2}{Machine 2}{drill} + +\mess[label position=below] +{startm1}{usr}{m1} +\nextlevel +\mess{startm2}{m1}{m2} +\nextlevel +\mess{log}{m1}{envleft} +\nextlevel +\nextlevel +\mess{output}{m2}{usr}[2] +\mess{free}{m1}{usr} +\nextlevel +\end{msc} +\end{codeexample} +\end{center} +\caption{The generated \MSC{}} +\label{quick} +\end{figure} +The \mscpack{} is activated by the clause \verb+\usepackage{msc}+. This package +contains, among others, a definition of the environment |msc|. This +environment is used to draw \MSC{}s. The \MSC{} definition is surrounded by the +clauses |\begin{msc}{Example}| and |\end{msc}|. The name of the +\MSC{}, {\tt Example}, is displayed in the upper-left corner of the \MSC{}. + +The next four lines define the \emph{instances}: +|\declinst{m1}{Machine 1}{control}| defines an instance with +\meta{nickname} |m1| and a description consisting of two parts, +namely, |Machine 1| and |control|. The nickname is used in +all subsequent references to this instance. The first part of the +description is drawn above the rectangular instance head symbol, and +the second part of the description is drawn inside the instance head +symbol. + +The following lines contain the definitions of the messages. Every +message has a source and a destination instance. The clause +|\mess[label position=below]{startm1}{usr}{m1}| defines a message with name +|startm1|, which goes from instance |usr| to instance |m1|. +Between square brackets we can put optional list of options. Each option is +comma separated from another option. In this example we specify the placement of +the label to be below the message arrow. + +In order to control the vertical placement of the messages, the \MSC{} is +divided into levels. At every level, any number of messages may start. +The vertical position of the end point of a message is determined +by the optional fourth argument of the message definition, as in the +clause |\mess{output}{m2}{user}[2]|. +This argument is the vertical offset (in number of levels) between the +start point of the message (i.e.,\ the current level) and its end point. +If the value is 0 the message is drawn horizontally. A negative offset +means that the arrow has an upward slope. Equivalently we could specify this +value using option: |\mess[level shift=2]{output}{m2}{user}|. + +The clause |\nextlevel| is used to advance to the next level. + +\section{Use of the \mscpack} +\label{use} +\subsection{Options} +Each command supported by the \mscpack\ can be provided with a list of +options. A list of +options is surrounded by square brackets and options are separated +by a comma. In fact options are \pgfname\ keys and the parsing of options +is done internally by the \tikzname\ package. All keys defined by the +\mscpack\ are +prefixed by the |/msc| keyword. When a key is not fully specified (i.e.,\ it is +specified without the |/msc|, |/tikz| or some other prefix) the +package will search first for the keys in the |/msc| namespace and if no +key is found it will search the default |/tikz| name space. + +In the description below, optional arguments are marked in \opt{green}. +\subsection{The \MSC{} frame} +\label{mscframe} +The |msc| environment is used for making \MSC{} definitions. Thus, such a +definition looks as follows. +\begin{environment}{{msc}\opt{\oarg{options}}\marg{msc name}} +This declares the |msc| environment. The frame and the header of the +\MSC{} are drawn. +The argument \meta{msc name} is the name of the \MSC{}. +The header of an \MSC{} is formed from the keyword |msc|, followed +by the \meta{msc name}. + +The size of the \MSC{} frame is determined vertically by the number of levels +occurring in the \MSC{} (see Section~\ref{levels}) and horizontally by +the number of instances (see Section~\ref{instances}). +\msckey{title position}{\meta{position}}{ + Controls the position of the header of the MSC. Possible values of + \meta{position} are: + |left|, |right|, and |center|.} +\msckey{msc keyword}{\meta{keyword}}{ + Specifies the \meta{keyword} in the header.} +\msckey{title distance}{\meta{distance}}{ + Specifies the \meta{distance} between left/right side of the frame and the MSC + header.} +\msckey{title top distance}{\meta{distance}}{ + Specifies the \meta{distance} between top of the frame and the (top + of the) MSC header.} +\msckey{left environment distance}{\meta{distance}}{ + Specifies the \meta{distance} between the left-most instance and the + left side of the frame. +} +\msckey{right environment distance}{\meta{distance}}{ + Specifies the \meta{distance} between the right-most instance and + the right side of the frame. +} + \begin{key}{/msc/environment distance} + Sets the keys |right environment distance| and |left environment distance| to + the provided value. + \end{key} +\msckey{instance distance}{\meta{distance}}{ + Sets the \meta{distance} between the (vertical) instance lines. +} + +\begin{key}{/msc/draw frame=\meta{colour} (default , initially \mscget{draw frame})} + Sets the colour of the frame. If you do not want to draw a frame, set + \meta{colour} to |none|. When \meta{colour} is empty, then the last colour is used, + usually black. +\end{key} + +\begin{key}{/msc/draw grid=\meta{grid type} (default grid, initially \mscget{draw grid})} + Specifies if we want to draw the help grid in msc. Possible values for + \meta{grid type} are |grid|, + |color grid| and |none|. +\end{key} + +\end{environment} + +\subsection{Levels} +\label{levels} +An \MSC{} is vertically divided in {\em levels}. All events in an \MSC{} are +attached to a certain level, or stretch out over several levels. +Any number of events can be drawn at a certain level. +An event will always be drawn (or started) at the current level, unless a level +offset is specified (see e.g.\ the |\mess| command in +Section~\ref{messages}). The \meta{level offset} is a positive integer number, which +denotes at which level, relative to the current level, an event should +be drawn. +Drawing starts at level 0. +The following command is used to advance to the next level. +\begin{command}{\nextlevel\opt{\oarg{level offset}}} +The \meta{lever offset} is a positive integer value which denotes the number of +levels to advance. By default, the value of \meta{lever offset} is 1, which means +drawing continues at the next level. +\end{command} +The following keys influence the |\nextlevel| command: +\msckey{first level height}{\meta{distance}}{ + Specifies the \meta{distance} between the instance start symbol and the first level.} +\msckey{level height}{\meta{distance}}{ + Specifies the \meta{distance} between two consecutive levels.} +\msckey{last level height}{\meta{distance}}{ + Specifies the \meta{distance} between the last level and the instance end symbol.} + +Figure~\ref{parametersfig} on page~\pageref{parametersfig} shows all lengths of +the \mscpack. +\subsection{Instances} +\label{instances} +All instances have to be declared before they can be used. An instance +consists of an instance head symbol with an associated name, an +instance axis and an instance end symbol. Normal instances have a +single line axis. Fat instances have a double line axis. The order of +the instance declarations determines the order in which the instances +occur in the drawing. + +An instance is declared with the following command. + +\begin{command}{\declinst\opt{*}\marg{nickname}\marg{instance name above}\marg{instance name within}} +The starred version produces a fat instance. +The \meta{nickname} is used for referring to this instance in the rest of the +MSC definition. +The \meta{instance name above} is put above the instance head symbol. +The \meta{instance name within} is put inside the instance head symbol. +\MSC{} definition. +\end{command} +The keys associated with the command: +\msckey{head height}{\meta{height}} { + Specifes the minimum \meta{height} of the instance head symbol.} +\msckey{instance width}{\meta{width}}{ + Specifes the minimum \meta{width} of the instance head symbol.} +\msckey{head top distance}{\meta{distance}}{ + Specifes the \meta{distance} between top of the head symbols and frame.} +\msckey{foot height}{\meta{height}}{ + Specifes the \meta{height} of the instance foot symbol.} +\msckey{foot distance}{\meta{distance}}{ + Specifes the \meta{distance} between the instance foot symbol and the bottom of the \MSC{} frame.} +\msckey{environment distance}{\meta{distance}}{ + Specifies the \meta{distance} between the edge of the \MSC{} and the first/last instance axis.} +\msckey{instance width}{\meta{width}}{ + Specifies the \meta{width} of the instance head and foot symbols.} +\msckey{label distance}{\meta{distance}}{ + Specifies the \meta{distance} between the instance head symbol and the part of the + instance name drawn above the head symbol.} +\msckey{draw head}{\meta{colour}}{ + Sets the colour of the instance head. If you do not want to draw an instance head, set + \meta{colour} to |none|. When \meta{colour} is empty, then the last colour is used, + usually black. +} + +% The command \verb+\setfootcolor{color}+ sets the +% fill color of the footer symbol. Valid color values are, e.g., +% \texttt{black} (default), \texttt{white}, and \texttt{gray}. +The following \MSC{} shows the declaration of an \MSC{} with three +instances. The first and the last are normal instances (one line axis), +whereas the second is a fat instance (double line axis). The optional +parameter |values small|, indicates that the small drawing +style should be used (see Section~\ref{parameters}). +% \setmscvalues{small} +\begin{codeexample}[width=\linewidth-8.8cm] +\begin{msc}[small values]{instances} +\declinst{i}{above}{within} +\declinst*{j}{}{j} +\declinst{k}{k}{} +\end{msc} +\end{codeexample} + +\subsection{Messages} +\label{messages} +A message is denoted by an arrow from the sending instance to the +receiving instance. The instances are referred to by their nicknames. +A message is defined with the following command. +\begin{command}{\mess\opt{*}\opt{\oarg{options}}\marg{name}\marg{sender}\marg{receiver}\opt{\oarg{leveloffset}}} +% \begin{verbatim} +% \mess(*)[pos]{name}[labelpos]{sender}[placement]{receiver}[leveloffset] +% \end{verbatim} +The \meta{name} of the message may be any string. The \mscpack{} +processes the \meta{name} argument in LR-mode, +see~\cite[page~36]{Lam94}. This means that the string will consist of +one line. To generate multi-line message names, use the standard +\cmd{parbox} command, see the \emph{Tricks} section in the reference +manual~\cite{BM02}. By default, the name of a message label is drawn +above the center of the arrow, but the optional keys |label position|, +|side|, and |pos| influence the actual location, +as described below. The arrow starts at the current level at the +sending instance. The arrow ends at the current level plus the +level \meta{leveloffset}, at the receiving instance. \meta{leveloffset} can be +also modified by specifying keys |level shift| and |offset|. The +\meta{sender} and \meta{receiver} should be the nicknames of declared +instances. +Messages to or from the environment (i.e.,\ the left or the right side +of the \MSC{} frame) can be +specified by setting the sender or the receiver argument to one of the values +|envleft| or |envright|. (Note: Since instances and +environments are treated equally in the implementation, at every position +where the nickname of an instance is required, also +|envleft| and |envright| are allowed.) + +In case the sending and the receiving instance are the same, the +message is a \emph{self message}. A self message is drawn as a +polyline connecting the instance axis to itself. + +The starred version of the command, |\mess*|, produces the same +result as |\mess|, except that the arrow is drawn with a dashed +line. This can be used to draw a {\em method reply} (see~\cite{z120}). +\end{command} +The following keys influence the messages: +\msckey{level shift}{\meta{integer}}{ + For non-self message, \meta{integer} determines at which level message should arrive relative to the starting level + of the message. +} +\msckey{offset}{\meta{integer}}{ + For self message, \meta{integer} determines how many levels the message arrow should advance. +} +\msckey{side}{\meta{side}}{ + Determine the position of the arrow with respect to the instance axis. Valid values + for \meta{side} are |left| and |right|. In case of a non-self message the key is ignored. +} +\msckey{label position}{\meta{position}}{ + Determines the position of the label.In case of non-self message, valid values + for \meta{position} are |above|, |below|, |above~left|, |above~right|, + |below~left| and |below~right|. In case of self message valid values are |left| + and |right| and the default value is taken from the value of the key |side|. As + the implementation uses corresponding |/tikz| keys the |label~position=| part + can be skipped. +} +\msckey{pos}{\meta{real}}{ + Determines the relative distance of the message label to the beginning of the + message. Valid values for \meta{real} are real numbers in the closed interval $[0,1]$. + The key works in similar way as |/tikz/pos| key. +} +\msckey{self message width}{\meta{width}}{ + Controls the \meta{width} of the polyline used for drawing self-message. +% It also affects other commands such as |\order|, |\settimeout| or |\setstoptimer|. +} +\msckey{label distance}{\meta{distance}}{ + Specifies the \meta{distance} between the label of a message and the message arrow. +} +\msckey{arrow scale}{\meta{scale}}{ + The \meta{scale} specifies by which factor should the message arrow be scaled. Influences all + arrows drawn in |msc| environment. +} + +In Figure~\ref{fig:mscsomeExample} we see \MSC{} that shows an example of the use of messages. +In this sample \MSC{} and the following \MSC{}s in this section we will +not list the complete textual representations of the \MSC{}s. For brevity +we omit the environment call and the declarations of the instances. +Note the final |\nextlevel| command which is needed +to make the instance axis long enough to receive message +\verb+a+. + +Figure~\ref{fig:refpoints:B} shows different options that can be used to +position label. We use the keys |pos|, |label position| and |side| to place +the labels. Additionally we use |/tikz/anchor| key, which is an alternative way +to specify the placement of the label (see PGF Manual~\cite{tantau2022pgf}). + +\begin{figure}[htbp] +\begin{codeexample}[width=\linewidth-9.8cm] +\begin{msc}[small values,head top distance=0.8cm]{messages} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\mess{a}{j}{i}[3] +\mess{self}{i}{i}[1] +\nextlevel +\mess*{b}{j}{k} +\mess[b]{c}{k}{envright} +\nextlevel +\mess{d}{k}[.6]{i} +\end{msc} +\end{codeexample} +\caption{Example showing msc messages} +\label{fig:mscsomeExample} +\end{figure} +% +\begin{figure}[htbp] +\begin{codeexample}[width=\linewidth-9.8cm] +\begin{msc}[small values]{Label reference points} +\declinst{m0}{I0}{} +\declinst{m1}{I1}{} +\declinst{m2}{I2}{} +\nextlevel + +\mess[label position=above]{above}{m0}{m1} +\nextlevel +\mess[label position=below]{below}{m1}{m2} +\nextlevel[2] + +\mess[anchor=south,pos=0.1]{south}{m1}{m0} +\nextlevel +\mess[anchor=north]{north}{m2}{m1} +\nextlevel[2] + +\mess[label position=left]{left}{m0}{m0}[2] +\mess[side=right,pos=0.9]{right}{m2}{m2}[2] +\nextlevel[4] +\mess[label position=right]{right}{m0}{m0}[2] +\mess[left,side=right]{left}{m2}{m2}[2] +\nextlevel[6] + +\mess[anchor=east]{east}{m0}{m0}[-2] +\mess[anchor=west,side=right]{west}{m2}{m2}[-2] +\nextlevel[4] +\mess[right]{right}{m0}{m0}[-2] +\mess[side=right,left]{left}{m2}{m2}[-2] +\nextlevel[2] + +\mess[below left]{below left}{m0}{m1}[2] +\mess[above right]{above right}{m1}{m2}[2] +\nextlevel[6] + +\mess[anchor=south west]{SW}{m1}{m0}[-2] +\mess[anchor=north east,pos=0]{NE}{m2}{m1}[-2] +\nextlevel[2] +\end{msc} +\end{codeexample} +\caption{Different placing the message labels} +\label{fig:refpoints:B} +\end{figure} + +\subsection{Comments} +\label{comments} + +Comments are additional texts to clarify (events on) an instance. The +following command can be used to add comments to an \MSC{} diagram. +\begin{command}{\msccomment\opt{\oarg{options}}\marg{text}\marg{instance}} + +The \meta{instance} parameter defines the instance to which the +comment is attached. The text of the comment is specified by the +\meta{text} parameter and is processed in LR-mode. +The key |side| affect the horizontal position relative to its instance. +\end{command} +The following key affects the drawing of the comment: +\msckey{msccomment distance}{\meta{distance}}{ + Specifies the \meta{distance} at which the comment will be placed from the + \meta{instance} instance. +} + +The following diagram shows how to use comments. In this diagram we modify the +distance between the frame and the instances in order to fit the comments inside +the frame. +\begin{codeexample}[width=\linewidth-8.8cm] +\begin{msc}[small values, + left environment distance=2.6cm, + right environment distance=1.9cm]{comments} +\declinst{i}{}{i} +\declinst{j}{}{j} +\mess{a}{i}{j}[2] +\msccomment[msccomment distance=1.2cm]{start}{i} +\nextlevel[2] +\msccomment[side=right]{end}{j} +\nextlevel +\end{msc} +\end{codeexample} + + + +\subsection{Actions} +\label{actions} +An instance can perform an action, which is denoted by a +rectangle. There are two commands to draw actions: +\begin{command}{\action\opt{*}\opt{\oarg{options}}\marg{name}\marg{instance}} +The action is attached at the current level to the \meta{instance}. +The \meta{name} is centered inside the action symbol and is processed +in LR-mode. The height and width of the action symbol are adjusted so that +the \meta{name} fits inside a rectangle. + +The starred version of the command, |\action*|, produces the same +result as |\action|, except that the width of the action is not adjusted. + +The following keys determine the detailed drawing of the action +symbol: +\msckey{action width}{\meta{width}}{Specifies the \meta{width} of the action symbol.} +\msckey{action height}{\meta{hegiht}}{Specifies the \meta{height} of the action symbol.} +\end{command} +\begin{command}{\naction\opt{*}\opt{\oarg{options}}\marg{name}\marg{instance}} +The |\naction| command produces an action box with a diagonal +cross in it. It is otherwise identical to the |\action| command. +\end{command} + + +The following example shows that after an action often a multiple level +increment is needed to obtain nice pictures. +\begin{codeexample}[width=\linewidth-8.8cm] +\begin{msc}[small values, instance distance=1.6cm]{action} +\declinst{i}{}{i} +\declinst{j}{}{j} +\mess{a}{j}{i} +\nextlevel +\naction{doit}{i} +\nextlevel[2] +\action*{doitnow}{i} +\nextlevel[2] +\mess{b}{i}{j} +\end{msc} +\end{codeexample} + +\subsection{Timers} +\label{timers} +There are five commands to draw timer events. +\begin{command}{\settimer\opt{\oarg{options}}\marg{name}\marg{instance}}% +Setting of a timer is drawn as a line connecting the \meta{instance} +to the {\em hour glass} symbol. The \meta{name} is put near this +symbol. The key |side| is determines on which side of the instance axis the +timer is drawn. The key |self message width| determines the lenght of the arm +between the symbol and the instance axis. The key |label distance| determines +the distance between the name and the timer symbol. The key |arrow scale| +determines the scaling of the arrow. +{\em hour glass} symbol to the \meta{instance}. +\end{command} +\begin{command}{\timeout\opt{\oarg{options}}\marg{name}\marg{instance}} +A time-out is represented by an arrow from an +{\em hour glass} symbol to the \meta{instance}. +\end{command} +\begin{command}{\stoptimer\opt{\oarg{options}}\marg{name}\marg{instance}} +Stopping a timer is drawn as a line connecting the \meta{instance} with the timer stop +symbol (denoted by a cross). +\end{command} +\begin{command}{\settimeout\opt{\oarg{options}}\marg{name}\marg{instance}\opt{\oarg{offset}}} +The command |\settimeout| is a combination of the setting of a +timer and a time out. The \meta{offset} denotes the number of levels +between the two events. +\end{command} +\begin{command}{\setstoptimer\opt{\oarg{options}}\marg{name}\marg{instance}\opt{\oarg{offset}}} +Likewise, |\setstoptimer| is a combination +of the setting of a timer and stopping a timer. +\end{command} +\msckey{offset}{\meta{offset}}{ + The key holds the value of \meta{offset}. It denotes the number of levels + between the two events. +}% +\msckey{timer width}{\meta{width}}{ + The key determines the \meta{width} of the hour glass and the time out symbols. +} + +The various timer symbols are shown in the following example. + +\medskip +\begin{codeexample}[width=\linewidth-9.8cm] +\begin{msc}[small values]{timers} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\settimer{T,50}{j} +\setstoptimer[r]{V}{k}[6] +\nextlevel[2] +\timeout{T}{j} +\settimeout{U}{i} +\nextlevel[2] +\settimer[r]{T,20}{j} +\nextlevel[2] +\stoptimer[r]{T}{j} +\end{msc} +\end{codeexample} + +\subsection{Time measurements} +\label{measurements} +There are several commands to add time measurements to an \MSC{}. +\begin{command}{ +\mscmark\opt{\oarg{options}}\marg{name}\marg{instance} +} +This command attach an absolute time stamp to an event on an \meta{instance}. +The \meta{name} is the text attached to the mark symbol, which is a dashed +polyline. The position of the mark is determined by the keys |position| (above, +below) and |side| (left,right). +\end{command} +\msckey{position}{\meta{position}}{ + The key determines the position of the mark symbol relative to the marked + event. The allowed values for \meta{position} are |above|, |mid| and |below|. +} +\begin{command}{\measure\opt{*}\opt{\oarg{options}}\marg{name}\marg{instance1}\marg{instance2}\opt{\oarg{offset}}} + This command connects two events from \meta{instance1} and \meta{instance2}. + The first event is at the current level. The second event is \meta{offset} + levels lower than the first event. Not that instead giving optional argument + \meta{offset} we can specify the key |offset|. The \meta{name} is attached to + the measure symbol. The measure symbol can be placed ath the left or right of + \meta{instance1}. This is determined by the value of the key |side|. In the + starred version of the command arrow heads are at the outside of the measured + interval. +\end{command} +In case the two events are far apart, the measure may be split in two +parts. We use two commands to draw this parts: +\begin{command}{\measurestart\opt{*}\opt{\oarg{options}}\marg{name}\marg{instance}\marg{gate}} + Draws the first part of the measure. The points where these two parts should + be connected are drawn by a small cicle, to which the text \meta{gate} in + attached. + In the starred version of the command arrow heads are at the outside of the + measured interval. +\end{command} +\begin{command}{\measureend\opt{*}\opt{\oarg{options}}\marg{name}\marg{instance}\marg{gate}} + Draws the first part of the measure in similar way as |\measurestart| command. +\end{command} + + +Several keys can be used to control the detailed layout of the time measurement +symbols. The |label distance| key specify the distance between the label of a +measurement and the measurement symbol. +\msckey{measure distance}{\meta{distance}}{ +This key specifies at which \meta{distance} the measurement symbols are drawn from the +\meta{instance} line. +} +\msckey{measure symbol width}{\meta{width}}{ + Specifies the \meta{width} of the measurement triangle symbol. +} + +The following example illustrates marks and measurements in an \MSC{}.. +\begin{codeexample}[width=\linewidth-9.8cm] +\begin{msc}[small values]{Time measurements} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\mess{m1}{i}{j}[1] +\mscmark{t=0.0}{i} +\measure{0.6}{i}{j}[4] +\nextlevel +\mscmark[position=above,side=right]{t=0.3}{j} +\nextlevel[3] +\mess{m2}{j}{k} +\measurestart*[side=right]{0.2}{k}{g} +\nextlevel[6] +\mess{m3}{k}{i} +\mscmark[position=below,side=left]{t=1.0}{i} +\measureend*[side=right]{0.2}{k}{g} +\nextlevel +\end{msc} +\end{codeexample} + +\subsection{Lost and found messages} +\label{lostfound} +\begin{command}{\lost\opt{\oarg{options}}\marg{name}\marg{gate}\marg{instance}} +A lost message is denoted by an arrow starting at an instance and +ending at a filled circle. +The argument \meta{instance} determines the instance to which the +arrow is attached. The \meta{name} of the message is put above the +message arrow. The \meta{gate} is a text associated to the circle. +The keys |side|, |label position|, |pos|, |label distance| and +|self message width| +function in similar way as in the |\mess| command +(Section~\ref{messages}). That is, |side| controls the placement of the lost or +found message with respect to the instance axis. The |label position| and |pos| +controls the placement of the \meta{name} with respect to the message arrow. +The key |self message width| determines the length of the arrow and |label +distance| specifies the distance between the name and the arrow. +\end{command} +\begin{command}{\found\opt{\oarg{options}}\marg{name}\marg{gate}\marg{instance}} +A found message is denoted by an arrow starting at an open circle and ending at +an instance. Otherwise the command is identical to the |\lost| command. +\end{command} +\msckey{lost symbol radius}{\meta{radius}}{ + Determines the \meta{radius} of the circle for lost and found messages. +} + +The following example shows a found and a lost message. + +\begin{codeexample}[width=\linewidth-9.8cm] +\begin{msc}[small values]{lost and found} +\declinst{i}{}{i} +\declinst{j}{}{j} +\found{m}{g}{i} +\nextlevel +\mess{p}{i}{j} +\nextlevel +\lost[side=right]{n}{}{j} +\end{msc} +\end{codeexample} + + +\subsection{Conditions} +\label{conditions} +There are two commands to draw condition boxes: +\begin{command}{\condition\opt{*}\opt{\oarg{options}}\marg{text}\marg{instance list}} + A condition is denoted by a hexagon. It is used to express that the + system has entered a certain state. A condition relates to a number of + instances. All conditions which take part in the condition are covered + by the condition symbol. The other instances are drawn through the + condition symbol. + + The \meta{text} is placed in the center of the condition. The + \meta{instance list} expresses which instances take part in the + condition. It is a list of nicknames of instances, separated by + commas. Take care not to add extra white space around the nicknames, + since this is considered part of the nickname in \LaTeX. + The order in which the instances are listed is immaterial. + + The starred version of the command |\condition*|, produces the same + result as the command |\condition|, except that the width of the + condition symbol is not adjusted to fit the contents of the hexagon. +\end{command} +\begin{command}{\ncondition\opt{*}\opt{\oarg{options}}\marg{text}\marg{instance list}} +The |\ncondition| command produces a condition with a diagonal +cross in it. It is otherwise identical to the |\condition| command. +\end{command} + +There are several keys that controls the shape of the condition +symbol: +\msckey{condition height}{\meta{hegiht}}{ + Determines the \meta{height} of the condition symbol. +} +\msckey{condition overlap}{\meta{distance}}{ + The \meta{distance} determines the width of the part of the condition + symbol which extends over the rightmost/leftmost contained instance + axis. +} + +The following example contains some conditions. +\begin{codeexample}[width=\linewidth-10.6cm] +\begin{msc}[small values]{conditions} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\condition{some condition}{i,k} +\nextlevel[3] +\mess{m}{i}{j} +\action{a}{k} +\nextlevel +\condition{C}{i} +\ncondition{D}{j} +\nextlevel[2] +\condition{A, B, C}{i,j,k} +\nextlevel[2] +\end{msc} +\end{codeexample} + +\subsection{Generalized ordering} +\label{ordering} +A generalized order is treated much like a regular message (see +Section~\ref{messages}). There +are three differences: a generalized order is drawn with a +dotted line, it has no label, and the arrow head is in the middle of +the line. A generalized order is defined with the following command. +\begin{command}{\order\opt{\oarg{options}}\marg{sender}\marg{receiver}\opt{\oarg{level offset}}} +The \meta{sender} and \meta{receiver} are the nicknames of the +instances which are connected by the generalized ordering symbol. +At the \meta{receiver} instance, the generalized ordering symbol ends +at the current level plus the \meta{level offset}. The +\meta{level offset} is an optional integer value, with default 0. + +In case \meta{sender} and \meta{receiver} denote the same instance, +the order is a \emph{self order}. The placement of the order arrow of +a self order is controlled by the key |side|. It +can have values |left| (meaning that the ordering symbol is drawn +left of the instance axis) and |right| (meaning that the ordering +symbol is drawn right of the instance axis). By default it is drawn at +the left side of the instance. + +The position of the arrow is controlled with the |pos| key. The key |self +message width| specify the width of the polyline used for drawing orderings on a +single instance axis. The key |arrow scale| controls the size of the arrow. + +Orderings to or from the environment (i.e.,\ the left or the right side +of the \MSC{} frame) can be +specified by setting the sender or the receiver argument to the value +|envleft| or |envright|. +\end{command} + +An example of a generalized order is given in the following diagram. +\begin{codeexample}[width=\linewidth-9.6cm] +\begin{msc}[head top distance=0.8cm] + {generalized order} +\declinst{i}{}{i} +\declinst{j}{}{j} +\mess{m}{envleft}{i} +\order{i}{j}[1] +\nextlevel +\mess{k}{j}{envright} +\nextlevel +\end{msc} +\end{codeexample} + +\subsection{Instance regions} +\label{regions} +A part of the instance axis can be drawn in a different style. Such a +part is called an {\em instance region}. The following +regions are supported: +{\em coregion} (the instance axis is dashed, which means that the order of the +attached instances is immaterial), +{\em suspension region} (a small rectangle with dashed left and right +sides, which denotes that the instance is suspended), +{\em activation region} (a small filled rectangle, which denotes that +the instance has control). + +The following commands are used to draw an instance region. +\begin{command}{\regionstart\opt{\oarg{options}}\marg{type}\marg{instance name}} + After this command the instance axis of \meta{intstance name} is drawn in the + shape determined by \meta{type} starting from the current level. + The \meta{type} can have values |coregion|, |suspension|, and |activation|. +\end{command} +\begin{command}{\regionend\marg{instance name}} + After this command the instance axis for the \meta{instance name} is drawn in + the usual way. In other words it ends current region. +\end{command} +The following keys control the shape of on instance region: +\msckey{region width}{ + Determines the \meta{width} of the coregion start and end symbol and the \meta{width} of the activation and suspension rectangle. +} + +In the following example, several instance regions are demonstrated. +Note that the relative order of |\mess|, |\regionstart|, and +|\regionend| commands does not matter. Also notice that the +second activation region on~$i$ ends with a method reply +(which is produced by the command |\mess*|). + +\medskip + +\begin{codeexample}[width=\linewidth-9.6cm] +\begin{msc}[small values]{regions} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\regionstart{activation}{i} \nextlevel[3] +\regionend{i} +\mess{m}{i}{j} \nextlevel +\regionstart{coregion}{j} \nextlevel +\regionstart{suspension}{k} +\mess{p}{j}{k} \nextlevel +\regionstart{activation}{i} +\mess{q}{j}{i} \nextlevel +\regionend{j} \nextlevel[3] +\regionend{i} +\mess*{r}{i}{j} \nextlevel +\mess{s}{j}{k} +\regionend{k} \nextlevel +\end{msc} +\end{codeexample} + +\subsection{Instance creation and instance stop} +\label{createstop} +The \MSC{} language offers constructs for dynamic instance creation and +instance destruction. +An instance can dynamically create another instance by issuing a +create command. An instance creation is drawn as a dashed message +arrow. At the side of the arrow head, the instance head symbol for the +created instance is drawn. +An instance end symbol does not denote the end of the specified +process, but merely the end of its current description. Therefore, a +different symbol is needed which denotes that an instance stops before +the end of the \MSC{} in which it is contained. +The instance stop symbol is a cross. + +The following commands are used for instance creation and instance +stop. +\begin{command}{\dummyinst\opt{\oarg{options}}\marg{created instance}} + This command reserve space for on instance which will be created dynamically. + |\dummyinst| command is mixed with the declarations of normal instances (see + the |\declinst| command, Section~\ref{instances}). The argument \meta{created + instance} is the nickname of the instance that will be created later. +\end{command} +\begin{command}{\startinst\opt{\oarg{options}}\marg{instance name}% + \marg{text above}\marg{text inside}} + This command create an instance. The created instance must have been declared + first with the |\dummyinst| command. The name of the created instance consists + of two parts. The part called \meta{text above} is placed above the instance + head and the \meta{text inside} is centered within the instance head. +\end{command} +\begin{command}{\create\opt{\oarg{options}}\marg{name}\marg{creator}\marg{instance name}% + \marg{text above}\marg{text inside}} + This command is identical to |\startinst| command except it allows to specify + the creator of the instance. The command results in a horizontal message arrow + labelled with \meta{name}. The arrow starts at the current level at the + instance with the nickname \meta{creator} and ends at the current level at the + instance head of the instance with nickname \meta{instance name}. + As with normal messages, placement of the message label is controlled by the + keys |label position| and |pos|. +\end{command} +\begin{command}{\stop\opt*\opt{\oarg{options}}\marg{instance name}} + An instance is stopped with the |\stop| command. + The \meta{instance} is the nickname of the stopped instance. The + instance axis is not drawn any further below the level at which the + |\stop| command is issued. Also, the instance foot symbol is not + drawn. + + If the |\stop*| command is used, then the instance foot symbol is + drawn instead of the stop symbol. +\end{command} +\msckey{stop width}{\meta{width}}{ + The \meta{width} determines the size of the stop symbol. +} + + +Take care not to specify any events on an instance which has not yet +been created or which has already been stopped. However, it is possible +to create an instance after it has stopped, as showed in the next example. + +\begin{codeexample}[width=\linewidth-9.6cm] +\begin{msc}[small values]{dynamic instances} +\declinst{i}{}{j} +\dummyinst{j} +\declinst{k}{}{k} + +\mess{p}{i}{k} +\nextlevel[3] +\create[label position=below]{kick}{k}{j}{}{j} +\nextlevel[2] +\stop*{k} +\nextlevel +\mess{ok}{j}{i} +\nextlevel +\stop{j} +\nextlevel[2] +\startinst{k}{}{again} +\nextlevel[2] +\end{msc} +\end{codeexample} + +\subsection{\MSC{} references} +\label{references} +Within an \MSC{} a reference to other \MSC{}s can be included. Such a +reference is drawn as a rectangle with rounded corners, covering part +of the \MSC{}. The following commands are used to draw \MSC{} references. + +\begin{command}{\referencestart\opt{\oarg{options}}\marg{nickname} + \marg{text}\marg{left instance}\marg{right instance}} + The reference symbol starts at the level where the + |\referencestart| command is used, and ends at the level where + the corresponding |\referenceend| command occurs. These commands + correspond if they have the same \meta{nickname}. + The \meta{text} is + placed in the center of the reference symbol. The reference covers all + instances from \meta{leftinstance} to \meta{rightinstance}. + + The left and right edge of the reference symbol are + \meta{nickname}|left| and \meta{nickname}|right|, where \meta{nickname} is + the nickname of the \MSC{} reference as defined in the + |\referencestart| command. + These names can be used at every place where the nickname of an + instance is required, e.g.\ as the sender or receiver of a message. +\end{command} +\begin{command}{\referenceend\opt{\oarg{options}}\marg{nickname}} + This command end the reference \meta{nickname} that has been started with the + |\referencestart| command. +\end{command} +The following keys affect the drawing of reference symbol: +\msckey{left reference overlap}{\meta{distance}}{ + Determines the \meta{distance} between the left edge of the reference symbol and the + leftmost covered instance axis. +} +\msckey{right reference overlap}{\meta{distance}}{ + Determines the \meta{distance} between the right edge of the reference symbol and the + rightmost covered instance axis. +} + +The following example shows the usage of references: + +\begin{codeexample}[width=\linewidth-9.6cm] +\begin{msc}[small values]{references} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\mess{a}{j}{k} +\nextlevel +\referencestart{r}{a reference}{i}{j} +\nextlevel +\mess{b}{rright}{k} +\nextlevel[2] +\referenceend{r} +\nextlevel[2] +\referencestart{p}{another reference}{i}{k} +\nextlevel +\mess{c}{envright}{pright} +\nextlevel[4] +\referenceend{p} +\end{msc} +\end{codeexample} + +\subsection{Inline expressions} +\label{inlines} +An inline expression is a part of an \MSC{} on which an operation is +defined. A rectangle surrounds the part of the \MSC{} containing the +operands. The operands are separated by horizontal dashed lines. +The operator is placed in the upper left corner of the inline +expression symbol. +The following commands are used to draw inline expressions. + +\begin{command}{\inlinestart\opt{\oarg{options}}\marg{nickname}\marg{operator}\marg{left instance}\marg{right instance}} + Starts the inline expression at the current level. The inline expression + spans over the instances from \meta{left instance} to \meta{right instance}. + The \meta{operand} is placed in the upper left corner of the rectangle. +% + The left and right edge of the inline expression symbol are named + \meta{nickname}|left| and \meta{nickname}|right|, where \meta{nickname} is + the nickname of the inline expression as defined in the + |\inlinestart| command. + These names can be used at every place where the nickname of an + instance is required, e.g.\ as the sender or receiver of a message. +\end{command} +\begin{command}{\inlineseparator\opt{\oarg{options}}\marg{nickname}} + Draws a dashed line at the current level for the inline expression with + nickname \meta{nickname}. +\end{command} +\begin{command}{\inlineend\opt{*}\opt{\oarg{options}}\marg{nickname}} + Ends the inline expresion with the nickname \meta{nickname} at the current level. + The command |\inlineend*| does the same as the command + |\inlineend|, except that the bottom line of the rectangle is + This is used to indicate that the operand is optional. + dashed. +\end{command} + +\msckey{left inline overlap}{\meta{distance}}{ + Determines the \meta{distance} which is a distance between the left edge of the inline expression + symbol and the leftmost included instance axis. +} +\msckey{right inline overlap}{\meta{distance}}{ + Determines the \meta{distance} which is a distance between the right edge of the inline expression + symbol and the rightmost included instance axis. +} + +The following example shows how to draw inline expressions: + +\begin{codeexample}[width=\linewidth-9.6cm] +\begin{msc}[small values]{inline expressions} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\inlinestart{exp1}{par}{i}{k} \nextlevel +\mess{a}{k}{j} \nextlevel +\inlinestart[left inline overlap=0.6cm] + {exp2}{alt}{i}{j} \nextlevel[2] +\mess{b}{j}{i} \nextlevel +\inlineseparator{exp2} \nextlevel +\mess{c}{j}{i} \nextlevel +\inlineend{exp2} \nextlevel +\inlineseparator{exp1} \nextlevel +\mess{d}{j}{k} \nextlevel +\inlineend{exp1} \nextlevel +\inlinestart{exp3}{opt}{i}{j} \nextlevel +\mess{e}{envright}{exp3right} +\mess{e}{exp3right}{j} \nextlevel +\mess{f}{j}{i} \nextlevel +\inlineend*{exp3} +\end{msc} +\end{codeexample} +% +\subsection{Gates} +\label{gates} + +A gate determines a connection point for messages. + +The following command can be used to draw gates. + +\begin{command}{\gate\opt{*}\opt{\oarg{options}}\marg{gate name}\marg{instance name}} + The unstarred version produces a normal (invisible) gate. The starred + version produces a visible gate (a small dot). The gate is drawn at the + current level at the instance \meta{instance name} (which can also be the + left and right edge of e.g.\ an \MSC{} reference). The + \meta{gate name} is attached to the gate. The positioning of the \meta{gate + name} relative to the gate is determined by the keys |side| (|left| or + |right|) and |position| (|above|, |mid| or |below|). +\end{command} + +There are several keys to control the size and shape of the gate symbol: +\msckey{gate symbol radius}{\meta{radius}}{ + The \meta{radius} defines the radius of the gate symbol. +} + +The next example shows a number of gates. +\begin{codeexample}[width=\linewidth-9.6cm] +\begin{msc}[small values]{gates} +\declinst{i}{}{i} +\declinst{j}{}{j} +\declinst{k}{}{k} +\referencestart{r}{ref}{i}{j} +\nextlevel +\gate{$g$}{rright} +\mess{b}{rright}{envright} +\gate[r][c]{$h$}{envright} +\nextlevel[2] +\mess{c}{rright}{k} +\gate*[l][b]{$h'$}{rright} +\nextlevel[2] +\referenceend{r} +\end{msc} +\end{codeexample} + +\subsection{High-level \MSC{}s} +\label{hmsc} +A High-level \MSC{} (\HMSC{}) is a drawing which defines the relation between +a number of \MSC{}s. It is composed of a start symbol (an upside down +triangle), a number of end symbols (represented by triangles), a +number of \MSC{} references (these are rectangles with rounded corners), +a number of conditions (hexagons) and possibly several connection +points (circles). These symbols are connected by arrows. + +The following commands can be used to draw \HMSC{}s. +\begin{environment}{{hmsc}\opt{\oarg{options}}\marg{hmsc name}\opt{(\meta{llx},\meta{lly})(\meta{urx},\meta{ury})}} + In order to draw \HMSC{}s, a new environment is defined, which is called + |hmsc|. The command to begin this environment has several + arguments. + + The header of an \HMSC{} is + formed from the value of the key |hmsc keyword| (initially |hmsc|), followed by the + \meta{hmsc name}. The positioning of the header depends on the key + |title position|. The possible values are |left|, |right| and |center|. The + keys |title top distance| and |title distance| control the distances of the + header from the frame. + The size of the \HMSC{} frame is calculated automatically unless the optional + parameters (\meta{llx},\meta{lly}) and (\meta{urx},\meta{ury}) are specified. In + such case the frame is determined by the + coordinates of the lower-left corner,(\meta{llx},\meta{lly}) , and the + coordinates of the upper-right corner, (\meta{urx},\meta{ury}). +\msckey{hmsc keyword}{\meta{keyword}}% +{The \meta{keyword} will be a starting word in a header of \HMSC{}.} +\msckey{north hmsc margin}{\meta{distance}}% +{The \meta{distance} determines the north margin of hmsc environment} +\msckey{south hmsc margin}{\meta{distance}}% +{The \meta{distance} determines the south margin of hmsc environment} +\msckey{east hmsc margin}{\meta{distance}}% +{The \meta{distance} determines the east margin of hmsc environment} +\msckey{west hmsc margin}{\meta{distance}}% +{The \meta{distance} determines the west margin of hmsc environment} +\msckey{west hmsc margin}{\meta{distance}}% +{The \meta{distance} determines the west margin of hmsc environment} +\begin{stylekey}{/msc/hmsc margin=\meta{distance}} + Sets the |north hmsc margin|, |south hmsc margin|, |west hmsc margin|, + |east hmsc margin| to \meta{distance}. +\end{stylekey} +\end{environment} +In the \HMSC{} we can draw number of symbols. Each symbol is in fact a \tikz{} +node and \meta{options} can be used to specify for example the placement +relative to the other nodes. The following commands are used to draw the symbols: +\begin{command}{\hmscstartsymbol\opt{\oarg{options}}\marg{nicknamee}\opt{(\meta{x},\meta{y})}} + Draws an equilateral triangle pointed down representing the start symbol. The + \meta{nickname} can be used later as a reference to the drawn symbol. Optional + \meta{x} and \meta{y} specify the coordinates at which the symbol should be + drawn. +\end{command} +\begin{stylekey}{/msc/start symbol} + A style that is applied to draw a triangle node in + the |\hmscstartsymbol| command. +\end{stylekey} +\msckey{hmsc symbol width}{\meta{width}}{ + Sets the width of the triangle of the start and end symbol in hmsc to the \meta{width}. +} +\begin{command}{\hmscendsymbol\opt{\oarg{options}}\marg{nickname}\opt{(\meta{x},\meta{y})}} + The command in identical to |\hmscstartsymbol| command but draws an + equilateral triangle pointed up representing the start symbol. +\end{command} +\begin{stylekey}{/msc/end symbol} + A style that is applied to draw a triangle node in + the |\hmscendsymbol| command. +\end{stylekey} +\begin{command}{\hmscreference\opt{\oarg{options}}\marg{nickname}\marg{text}\opt{(\meta{x},\meta{y})}} + Draws a \meta{text} inside a frame with rounded corners. The \meta{nickname} + can be used later to connect it to other hmsc elements. +\end{command} +\begin{stylekey}{/msc/reference} + A style that is applied to draw a reference node in the |\hmscreference| command. +\end{stylekey} +\msckey{reference height}{\meta{height}}% +{ Sets the minimal height of the reference to \meta{height}.} +\msckey{reference width}{\meta{width}}% +{ Sets the minimal width of the reference to \meta{width}.} +\begin{command}{\hmsccondion\opt{\oarg{options}}\marg{nickname}\marg{text}\opt{(\meta{x},\meta{y})}} + Draws a \meta{text} inside a rectangular frame with diamond shaped sides. The \meta{nickname} + can be used later to connect it to other hmsc elements. +\end{command} +\msckey{hmsc condition height}{\meta{height}}% +{ Sets the minimal height of the condition to \meta{height}.} +\msckey{hmsc condition width}{\meta{width}}% +{ Sets the minimal width of the condition to \meta{width}.} +\begin{command}{\hmscconnection\opt{\oarg{options}}\marg{nickname}\opt{(\meta{x},\meta{y})}} + Draws a small circle symbolizing connection at coordinates + (\meta{x},\meta{y}). Later we can refer to the connection using \meta{nickname}. +\end{command} +\msckey{hmsc connection radius}{\meta{distance}}% +{ Sets the radius of the connection symbol to the \meta{distance}} + +The \HMSC{} grid is not drawn, but used to control the positioning of the +\HMSC{} symbols (|startsymbol|, |endsymbol|, |reference|, +|condition|, and |connection|). +The center of each symbol is drawn on the grid point +with coordinates (\meta{x},\meta{y}). Each symbol also has a \meta{nickname} +for later reference. + +\begin{verbatim} +\hmscreference{nickname}{text}(x,y) +\hmsccondition{nickname}{text}(x,y) +\hmscconnection{nickname}(x,y) +\arrow{from-nickname}[coord-list]{to-nickname} +\end{verbatim} + +\HMSC{} symbols can be connected by means of the \verb+arrow+ command. +This draws an arrow from the symbol with nickname \verb+from-nickname+ +to the symbol with nickname \verb+to-nickname+. The optional argument +\verb+coord-list+ can be used if the line connecting the source and +the destination should not be straight. The \verb+coord-list+ has +the following syntax: \verb+(x1,y1)(x2,y2)...(xk,yk)+. This means +that the connecting line goes through the points with coordinates +(x1,y1), (x2,y2), \ldots, (xk,yk). + +Arrows always leave the start symbol at the bottom. They enter the end symbol +at the top. +Arrows start and end either at the middle of the top or at the middle +of the bottom of a reference and condition symbol. The incoming +(outgoing) direction of the arrow determines whether it will start +(end) at the top or at the bottom. + +There are several parameters to control the size and shape of the +symbols (see Section~\ref{parameters}). These are +\verb+\hmscconditionheight+ (the height of the condition symbol), +\verb+\hmscconditionwidth+ (the width of the condition symbol, +excluding the left and right angular parts), +\verb+\hmscreferenceheight+ (the height of the reference symbol), +\verb+\hmscreference width+ (the width of the reference symbol), +\verb+\messarrowscale{size}+ (a command to set the size of the arrow +head of a connection line); +\verb+setconnectiontype(type)+ (set the shape of the polyline +connection the symbols; \verb+type+ can be \verb+straight+, +\verb+rounded+, and \verb+curved+), +\verb+\startsymbolwidth+ (the width of the start and end symbol), +\verb+\topnamedist+ (sets the distance between the top of the \HMSC{} frame +and the \HMSC{} header). + +An example of an \HMSC{} is in the following diagram. Notice that the +width and height of reference symbols are changed locally (i.e., +between \verb+{+ and \verb+}+ braces) just before the big +reference~\verb+b+ is defined. + +\medskip + +\noindent +\begin{minipage}[c]{0.375\linewidth} + +\begin{hmsc}{High level}(-3,0)(3,12) +\hmscstartsymbol{s}(0,10) +\hmscreference{a}{A}(0,9) +\hmscconnection{c}(0,7.5) +{ +\mscset{reference width=2cm} +\mscset{reference height=2\baselineskip} +% \setlength{\hmscreferencewidth}{2cm} +% \setlength{\hmscreferenceheight}{3\baselineskip} +\hmscreference{b}{\parbox{1.9cm} + {\centering + this is a big + hmsc reference} + }(0,6) +} +\hmsccondition{t}{Again}(1,4.25) +\hmsccondition{ok}{Ok}(0,3.5) +\hmsccondition{q}{\textit{Break}}(-2,3.5) +\hmscendsymbol{e1}(-2,2) +\hmscreference{do}{Do it!}(0,2) +\hmscendsymbol{e2}(0,1) + +\arrow{s}{a} +\arrow{a}{c} +\arrow{c}{b} +\arrow{c}[(-2,7.5)]{q} +\arrow{b}{q} +\arrow{q}{e1} +\arrow{b}{ok} +\arrow{ok}{do} +\arrow{do}{e2} +\arrow{b}{t} +\arrow{t}[(1,3.5)(2.5,3.5)(2.5,7.5)]{c} +\end{hmsc} +\end{minipage}\hfill +\begin{minipage}[c]{0.6\linewidth} +{\footnotesize +\begin{verbatim} +\begin{hmsc}{High level}(-3,0)(3,12) +\hmscstartsymbol{s}(0,10) +\hmscreference{a}{A}(0,9) +\hmscconnection{c}(0,7.5) +{\setlength{\hmscreferencewidth}{2cm} + \setlength{\hmscreferenceheight} + {3\baselineskip} + \hmscreference{b}{\parbox{1.9cm} + {\centering this is a big hmsc reference} + }(0,6)} +\hmsccondition{t}{Again}(1,4.5) +\hmsccondition{ok}{Ok}(0,3.5) +\hmsccondition{q}{\textit{Break}}(-2,3.5) +\hmscendsymbol{e1}(-2,2) +\hmscreference{do}{Do it!}(0,2) +\hmscendsymbol{e2}(0,1) +\arrow{s}{a} +\arrow{a}{c} +\arrow{c}{b} +\arrow{c}[(-2,7.5)]{q} +\arrow{b}{q} +\arrow{q}{e1} +\arrow{b}{ok} +\arrow{ok}{do} +\arrow{do}{e2} +\arrow{b}{t} +\arrow{t}[(1,3.5)(2.5,3.5)(2.5,7.5)]{c} +\end{hmsc} +\end{verbatim} +} +\end{minipage} + + +\subsection{\MSC{} documents} +\label{mscdoc} +An \MSCdoc{} is a drawing which contains various declarations +of objects used in the \MSC{} description. For drawing \MSCdoc{}s +he following commands are provided. + +\begin{verbatim} +\begin{mscdoc}[headerpos]{mscdocname}{text}(llx,lly)(urx,ury) +\end{mscdoc} +\reference{text}(x,y) +\separator{y} +\end{verbatim} + +As for \MSC{} and \HMSC{}, a new environment is defined, which is named +\verb+mscdoc+. The command to begin an \MSCdoc{} has several +arguments. The argument \verb+headerpos+ is optional. It controls +positioning of the header of the \MSCdoc{}. +This argument can have values +\verb+l+ (for a left aligned header), \verb+c+ (for a centered header) +and \verb+r+ (for a right aligned header). +The header of an \MSCdoc{} is formed from the keyword \verb+mscdocument+, +followed by the \verb+mscdocname+. +The \verb+text+ is placed left-aligned below the \MSCdoc{} header. +The size of the \MSCdoc{} frame is determined by +coordinates of the lower-left corner, \verb+(llx,lly)+, and the +coordinates of the upper-right corner, \verb+(urx,ury)+. + +The \MSCdoc{} grid is not drawn, but used to control the positioning of the +\MSC{} references. +The center of such a reference is drawn on the grid point +with coordinates \verb+{x,y}+. + +The \verb+separator+ command draws a dashed horizontal line. The \MSC{} +references above the separator are the exported, while the ones below +the separator are local. + +There are several parameters to control the size and shape of the +symbols (see Section~\ref{parameters}). +\verb+\mscdocreferenceheight+ (the height of the reference symbol), +\verb+\mscdocreferencewidth+ (the width of the reference symbol), +\verb+\topnamedist+ (sets the distance between the top of the \MSCdoc{} +frame and the \MSCdoc{} header). + +An example of an \MSCdoc{} is in the following diagram. Notice that +the size of references in an \MSCdoc{} had to be changed for the last +reference. + +\medskip + + +\begin{minipage}{0.4\linewidth} +\begin{mscdoc}{My declarations}% + (0,0)(6,8) +\reference{a}(1,6) +\reference{b}(3,6) +\reference{c}(1,4) +\reference{d}(3,4) +\separator{3} +\mscset{reference width=4.5cm} +\mscset{reference height=2\baselineskip} +\reference{% + \parbox{4cm}% + {\raggedright This is a + two-line reference}} + (3,1.5) +\end{mscdoc} +\end{minipage} +% +\begin{minipage}{0.5\linewidth} +{\small +\begin{verbatim} +\begin{mscdoc}{My declarations}% + (0,0)(6,8) +\reference{a}(1,6) +\reference{b}(3,6) +\reference{c}(1,4) +\reference{d}(3,4) +\separator{3} +\mscset{reference width=4.5cm} +\mscset{reference height=2\baselineskip} +\reference{% + \parbox{4cm}% + {\raggedright This is a + two-line reference}} + (3,1.5) +\end{mscdoc} +\end{verbatim} +} +\end{minipage} + + + +\section{Style parameters} +\label{parameters} +\definecolor{markColor}{rgb}{0.10,0.10,0.9} + +\makeatletter +\NewDocumentCommand{\measureMark}{% + s % arrows outside the measured distance + D<>{1.5pt} % offset of marks + O{.75cm} % offset of label + m % first point + m % second point + m % label + D<>{o} % () coordinates -> angle + % h -> horizontal, + % v -> vertical + % o or what ever -> oblique + O{} % options for tikzset + }{% + + {\tikzset{#8} + + \coordinate (@1) at #4 ; + \coordinate (@2) at #5 ; + + \if #7v % vertical + \coordinate (@0) at ($($#4!.5!#5$) + (#3,0)$) ; + \coordinate (@4) at (@0|-@1) ; + \coordinate (@5) at (@0|-@2) ; + \else + \if #7h % horizontal + \coordinate (@0) at ($($#4!.5!#5$) + (0,#3)$) ; + \coordinate (@4) at (@0-|@1) ; + \coordinate (@5) at (@0-|@2) ; + \else % cotation encoche + \ifnum\pdfstrcmp{\unexpanded\expandafter{\@car#7\@nil}}{(}=\z@ + \coordinate (@5) at ($#7!#3!#5$) ; + \coordinate (@4) at ($#7!#3!#4$) ; + \else % cotation oblique + \coordinate (@5) at ($#5!#3!90:#4$) ; + \coordinate (@4) at ($#4!#3!-90:#5$) ; + \fi\fi\fi + + \draw[dotted,very thin,shorten >= #2,shorten <= -2*#2] (@4) -- #4 ; + \draw[dotted,very thin,shorten >= #2,shorten <= -2*#2] (@5) -- #5 ; + + \IfBooleanTF #1 {% with star + \draw[measureMark arrow,-,draw=none] (@4) -- (@5) + node[measureMark node] {#6\strut}; + \draw[measureMark arrow,<-] (@4) -- ($(@4)!-2pt!(@5)$) ; + \draw[measureMark arrow,<-] (@5) -- ($(@5)!-2pt!(@4)$) ; + }{% without star + \ifnum\pdfstrcmp{\unexpanded\expandafter{\@car#7\@nil}}{(}=\z@ + \draw[measureMark arrow] (@5) to[bend right] + node[measureMark node] {#6\strut} (@4) ; + \else + \draw[measureMark arrow] (@4) -- (@5) + node[measureMark node] {#6\strut}; + \fi + }} + } +\makeatother + +By means of a collection of parameters, the graphical appearance of +an \MSC{} can be fine tuned to the user's taste. +The general parameters +are displayed in Figure~\ref{parametersfig} on page~\pageref{parametersfig}. +% +% %======================== +\begin{figure}[htb] + \begin{msc}[right environment distance=2.3cm]{Lengths} + \tikzset{% + measureMark node/.style={% + midway, + sloped, + fill=white, + text = markColor, + font=\footnotesize, + inner sep=1.5pt, + outer sep=2pt + }, + measureMark arrow/.style={% + <->, + >=latex, + very thin,dashed + }, + dimen/.style={<->,>=latex,thin,every rectangle node/.style={fill=white,midway,font=\sffamily}}, + symmetry/.style={dashed,thin}, + } + \declinst{m1}{aname}{iname} + \declinst{st}{}{} + \declinst{m2}{}{} + + \mess{msg1}{m1}{st} + \nextlevel + \mess{msg2}{m1}{st} + \nextlevel + \mess{self}{m1}{m1} + \coregionstart{m2} + \nextlevel[2] + \coregionend{m2} + \nextlevel + \lost[r]{x}{}{m2} + \stop{st} + \settimer{T}{m1} + \nextlevel + \inlinestart[left inline overlap=0.9cm,right inline overlap=0.5cm]{alt}{alt}{m1}{m1} + \nextlevel[2] + \inlineend{alt} + \action{a}{m2} + \nextlevel + \referencestart{ref}{\small reference}{m1}{m1} + \nextlevel + \referenceend{ref} + \nextlevel + \gate*{}{m1} + \nextlevel + \condition{cond1}{m1,m2} + \nextlevel[3] + \mess{msg3}{m2}{m1} + \makeatletter + \msc@endmsc[] + \makeatother + + \measureMark*[-2.5cm]{($(msc@env@nw)+(\mscget{title distance},0cm)$)}{($(msc@env@nw)+ + (\mscget{title distance},-\mscget{title top distance})$)}% + {title top distance}% + [measureMark node/.append style={above right=-36pt and -2pt,rotate=90}] + + \measureMark*[-0.8cm]{($(msc@env@nw)+(0cm,-\mscget{title top distance}-1em)$)}{($(msc@env@nw)+ + (\mscget{title distance},-\mscget{title top distance}-1em)$)}% + {title distance}[measureMark node/.append style={left=6pt}] + + \measureMark*[-1.1cm]{(msc@nodem1.north)}{($(msc@nodem1.north)+ (0cm,\mscget{label distance})$)}% + {label distance}[measureMark node/.append style={above left=6pt and 9pt,rotate=-90}] + + \measureMark*[-1.6cm]{($(msc@level2-|msc@nodem1)+(1.5cm,0)$)} + {($(msc@level2-|msc@nodem1)+ (1.5cm,\mscget{label distance})$)}% + {label distance}[measureMark node/.append style={above left=6pt and 9pt,rotate=-90}] + + \measureMark[0.0cm]{($(msc@env@nw)+(4cm,0)$)}{(msc@nodest.north)}% + {head top distance}[measureMark node/.append style={right=0pt,rotate=90}] + + \measureMark[0.2cm]{($(msc@env@nw)+(0,-3cm)$)}{(msc@nodem1.south)}% + {left environment distance}[measureMark node/.append style={above left=0pt and -7pt}] + + \measureMark[1.0cm]{($(msc@nodem1.south)+(-\mscget{self message + width},-2.4cm)$)}{($(msc@nodem1.south)+(0cm,-2.4cm)$)}% + {self message width}[measureMark node/.append style={left=8pt}] + + \measureMark*[0.21cm]{($(msc@nodem1.south)+(-\mscget{self message width}- + \mscget{timer width}/2,-2.9cm)$)} + {($(msc@nodem1.south)+(-\mscget{self message width}+\mscget{timer width}/2,-2.9cm)$)}% + {timer width}[measureMark node/.append style={left=7pt,yshift=1pt}] + + \measureMark[0.17cm]{($(msc@level8-|msc@nodem1)+(-0.9cm,-10pt)$)} + {($(msc@level8-|msc@nodem1)+(0,-10pt)$)}% + {left inline overlap}[measureMark node/.append style={left=12pt}] + + \measureMark[0.17cm]{($(msc@level8-|msc@nodem1)+(0.5cm,-2pt)$)} + {($(msc@level8-|msc@nodem1)+(0,-2pt)$)}% + {right inline overlap}[measureMark node/.append style={right=6pt}] + + \measureMark[0.0cm]{($(msc@level11-|msc@nodem1)+(-\mscget{left reference overlap},4pt)$)} + {($(msc@level11-|msc@nodem1)+(0,4pt)$)}% + {left reference overlap}[measureMark node/.append style={left=14pt}] + + \measureMark*[-0.2cm]{($(msc@level12-|msc@nodem1)+(0,\mscget{gate symbol radius})$)} + {($(msc@level12-|msc@nodem1)$)}% + {gate symbol radius}[measureMark node/.append style={left=1pt,rotate=90}] + + \measureMark[-0.3cm]{($(msc@level17-|msc@nodem1)+(-\mscget{instance width}/2,0pt)$)} + {($(msc@level17-|msc@nodem1)+(\mscget{instance width}/2,0pt)$)}% + {instance width}[measureMark node/.append style={below=0pt}] + + \measureMark[0.2cm]{(msc@level0-|msc@nodest)} + {(msc@level1-|msc@nodest)}% + {first level height}[measureMark node/.append style={align=left,right=0pt,rotate=90}] + + \measureMark[0.2cm]{(msc@level1-|msc@nodest)} + {(msc@level2-|msc@nodest)}% + {level height}[measureMark node/.append style={align=left,right=0pt,rotate=90}] + + \measureMark[0.2cm]{(msc@nodem2.north east)} + {(msc@nodem2.south east)}% + {head height}[measureMark node/.append style={align=left,right=0pt,rotate=90}] + + \measureMark[0.2cm]{($(msc@level3-|msc@nodem2)+(\mscget{region width}/2,0)$)} + {($(msc@level3-|msc@nodem2)+(-\mscget{region width}/2,0)$)}% + {region width}[measureMark node/.append style={align=left,right=5pt}] + + \measureMark*[0.2cm]{($(msc@level6-|msc@nodem2)+(\mscget{self message width},\mscget{lost symbol radius})$)} + {($(msc@level6-|msc@nodem2)+(\mscget{self message width},0pt)$)}% + {lost symbol radius}[measureMark node/.append style={align=left,right=0pt,rotate=90}] + + \measureMark[-0.2cm]{($(msc@level6-|msc@nodest)+(-\mscget{stop width}/2,-\mscget{stop width}/2)$)} + {($(msc@level6-|msc@nodest)+(\mscget{stop width}/2,-\mscget{stop width}/2)$)}% + {stop width}[measureMark node/.append style={align=left,right=7pt}] + + \measureMark[-0.2cm]{($(msc@level4-|msc@nodem1)$)} + {($(msc@level4-|msc@nodest)$)}% + {instance\\ distance}[measureMark node/.append style={align=left,fill=none,yshift=-1pt}] + + \measureMark[0.2cm]{($(msc@level9-|msc@nodem2)+(-\mscget{action width}/2,0)$)} + {($(msc@level9-|msc@nodem2)+(\mscget{action width}/2,0)$)}% + {action width}[measureMark node/.append style={align=left,above=-1pt,xshift=3pt}] + + \measureMark[0.2cm]{($(msc@level9-|msc@nodem2)+(\mscget{action width}/2,0)$)} + {($(msc@level9-|msc@nodem2)+(\mscget{action width}/2,-\mscget{action height})$)}% + {action height}[measureMark node/.append style={align=left,right=1pt,rotate=90}] + + \measureMark[0.5cm]{($(msc@level13-|msc@nodem2)+(\mscget{condition overlap},0)$)} + {($(msc@level13-|msc@nodem2)+(\mscget{condition overlap},-\mscget{condition height})$)}% + {condition height}[measureMark node/.append style={align=left,right=1pt,rotate=90}] + + \measureMark[0.2cm]{($(msc@level13-|msc@nodem2)+(\mscget{condition overlap},0)$)} + {($(msc@level13-|msc@nodem2)+(0,0pt)$)}% + {right condition overlap}[measureMark node/.append style={align=left,above=-1pt}] + + \measureMark<2pt>[0.2cm]{($(msc@level13-|msc@nodem2)+(\mscget{condition overlap},0)$)} + {($(msc@level13-|msc@nodem2)+(0,0pt)$)}% + {right condition overlap}[measureMark node/.append style={align=left,above=-1pt}] + + \measureMark<2pt>[0.2cm]{($(msc@level16-|msc@nodem2)+(0,0)$)} + {($(msc@level17-|msc@nodem2)+(0,0pt)$)}% + {last level height}[measureMark node/.append style={align=left,right=-2pt,rotate=90}] + + \measureMark*[0.2cm]{($(msc@level17-|msc@nodem2)+(\mscget{instance width}/2,0)$)} + {($(msc@level17-|msc@nodem2)+(\mscget{instance width}/2,-\mscget{foot height})$)}% + {foot height}[measureMark node/.append style={align=left,right=1pt,rotate=90}] + + \measureMark<0pt>[0.0cm]{($(msc@level17-|msc@nodem2)+(0.3cm,-\mscget{foot height})$)} + {($(msc@env@se-|msc@nodem2)+(0.3cm,0)$)}% + {foot distance}[measureMark node/.append style={align=left,left=-1pt,rotate=90}] + + \measureMark[0.2cm]{($(msc@env@se)+(0,7.5cm)$)}{(msc@nodem2.south)}% + {right\\ environment\\ distance}[measureMark node/.append style={align=left,right=33pt}] + + \mscset{draw frame=none,msc keyword={},msc/name={}} + \end{msc} + + \caption{User controllable parameters} + \label{parametersfig} +\end{figure} +% +% The value of a parameter can be changed using standard +% \LaTeX\ commands, e.g. +% \begin{verbatim} +% \setlength{\levelheight}{1cm} +% \end{verbatim} +% +% The following list describes all parameters. +% The default values for drawing \MSC{}s at large, normal and small size are +% included. See the command \verb+\setmscvalues{size}+ below for +% restoring the parameters to their original values. +% +% %======================== +% \begin{defs} +% +% \item[\cmd{actionheight}] +% Height of action symbols.\\ +% (\lnsvalue{0.75}{0.6}{0.5} cm.) +% +% \item[\cmd{actionwidth}] +% Width of action symbol.\\ +% (\lnsvalue{1.25}{1.25}{1.2} cm.) +% +% \item[\cmd{bottomfootdist}] +% Distance between bottom of foot symbol and frame.\\ +% (\lnsvalue{1.0}{0.7}{0.5} cm.) +% +% \item[\cmd{commentdist}] +% Distance between a comment and its instance.\\ +% (\lnsvalue{0.5}{0.5}{0.5} cm.) +% +% \item[\cmd{conditionheight}] +% Height of condition symbols.\\ +% (\lnsvalue{0.75}{0.6}{0.5} cm.) +% +% \item[\cmd{conditionoverlap}] +% Overlap of condition symbol.\\ +% (\lnsvalue{0.6}{0.5}{0.4} cm.) +% +% \item[\cmd{envinstdist}] +% Distance between environments and nearest instance line.\\ +% (\lnsvalue{2.5}{2.0}{1.2} cm.) +% +% \item[\cmd{firstlevelheight}] Height of level just below head +% symbols. Should not be changed inside the \MSC{} environment.\\ +% (\lnsvalue{0.75}{0.6}{0.4} cm.) +% +% \item[\cmd{gatesymbolradius}] Radius of the gate symbol.\\ +% (\lnsvalue{0.5}{0.5}{0.5} mm.) +% +% \item[\cmd{hmscconditionheight}] +% Height of \HMSC{} condition symbol.\\ +% (\lnsvalue{0.375}{0.3}{0.25} cm.) +% +% \item[\cmd{hmscconditionwidth}] +% Width of \HMSC{} condition symbol.\\ +% (\lnsvalue{1.0}{0.8}{0.7} cm.) +% +% \item[\cmd{hmscconnectionradius}] +% Radius of \HMSC{} connection symbol.\\ +% (\lnsvalue{0.06}{0.05}{0.04} cm.) +% +% \item[\cmd{hmscreferenceheight}] +% Height of \HMSC{} reference symbol.\\ +% (\lnsvalue{0.375}{0.3}{0.25} cm.) +% +% \item[\cmd{hmscreferencewidth}] +% Width of \HMSC{} reference symbol.\\ +% (\lnsvalue{1.0}{0.8}{0.7} cm.) +% +% \item[\cmd{hmscstartsymbolwidth}] +% Width of \HMSC{} start symbol.\\ +% (\lnsvalue{0.75}{0.6}{0.3} cm.) +% +% \item[\cmd{inlineoverlap}] +% Overlap of inline symbol.\\ +% (\lnsvalue{1.5}{1.0}{0.75} cm.) +% +% \item[\cmd{instbarwidth}] +% Default width of vertical instance bars (applies to fat instances only).\\ +% (\lnsvalue{0.0}{0.0}{0.0} cm.) +% +% \item[\cmd{instdist}] +% Distance between instance axes.\\ +% (\lnsvalue{3.0}{2.2}{1.5} cm.) +% +% \item[\cmd{instfootheight}] Height of foot symbols. Should not be +% changed inside the \MSC{} environment.\\ +% (\lnsvalue{0.25}{0.2}{0.15} cm.) +% +% \item[\cmd{instheadheight}] Height of head symbols. Should not be +% changed inside the \MSC{} environment.\\ +% (\lnsvalue{0.6}{0.55}{0.5} cm.) +% +% \item[\cmd{instwidth}] +% Width of header and foot symbols.\\ +% (\lnsvalue{1.75}{1.6}{1.2} cm.) +% +% \item[\cmd{labeldist}] +% Distance between labels and the symbols to which they belong (for instance, message labels and arrows).\\ +% (\lnsvalue{1.0}{1.0}{1.0} ex.) +% +% \item[\cmd{lastlevelheight}] Height of level just above foot +% symbols. Should not be changed inside the \MSC{} environment.\\ +% (\lnsvalue{0.5}{0.4}{0.3} cm.) +% +% \item[\cmd{leftnamedist}] Distance between left of the frame and +% (left of) \MSC, \HMSC, or \MSCdoc{} title.\\ +% (\lnsvalue{0.3}{0.2}{0.1} cm.) +% +% \item[\cmd{levelheight}] +% Height of a level.\\ +% (\lnsvalue{0.75}{0.5}{0.4} cm.) +% +% \item[\cmd{lostsymbolradius}] +% Radius of the lost and found symbols.\\ +% (\lnsvalue{0.15}{0.12}{0.08} cm.) +% +% \item[\cmd{markdist}] +% Horizontal distance from a mark to its instance.\\ +% (\lnsvalue{1.0}{1.0}{1.0} cm.) +% +% \item[\cmd{measuredist}] +% Horizontal distance from a measure to its (closest) instance.\\ +% (\lnsvalue{1.0}{1.0}{1.0} cm.) +% +% \item[\cmd{measuresymbolwidth}] +% Width of a measure symbol.\\ +% (\lnsvalue{0.75}{0.6}{0.4} cm.) +% +% \item[\cmd{mscdocreferenceheight}] +% Height of reference symbol in an \MSCdoc.\\ +% (\lnsvalue{0.375}{0.3}{0.25} cm.) +% +% \item[\cmd{mscdocreferencewidth}] +% Width of reference symbol in an \MSCdoc.\\ +% (\lnsvalue{1.0}{0.8}{0.7} cm.) +% +% \item[\cmd{referenceoverlap}] +% Overlap of reference symbol.\\ +% (\lnsvalue{1.5}{1.0}{0.75} cm.) +% +% \item[\cmd{regionbarwidth}] +% Width of region bars.\\ +% (\lnsvalue{0.5}{0.4}{0.2} cm.) +% +% \item[\cmd{selfmesswidth}] +% Length of horizontal arms of self messages.\\ +% (\lnsvalue{0.75}{0.6}{0.4} cm.) +% +% \item[\cmd{stopwidth}] +% Width of the stop symbol.\\ +% (\lnsvalue{0.6}{0.5}{0.3} cm.) +% +% \item[\cmd{timerwidth}] +% Width of the \emph{timer} symbols.\\ +% (\lnsvalue{0.4}{0.3}{0.2} cm.) +% +% \item[\cmd{topheaddist}] +% Distance between top of head symbols and frame.\\ +% (\lnsvalue{1.5}{1.3}{1.2} cm.) +% +% \item[\cmd{topnamedist}] Distance between top of the frame and +% (top of) \MSC, \HMSC, or \MSCdoc{} title.\\ +% (\lnsvalue{0.3}{0.2}{0.2} cm.) +% +% \end{defs} +% +% In addition there are several commands which allow the user to adjust +% the \MSC{} drawing to his own taste. +% +% \begin{defs} +% +% \item[\cmd{messarrowscale}\{\emph{scalefactor}\}] Sets the scale +% factor (a positive real number) of message arrow +% heads. (\lnsvalue{2}{1.5}{1.2}) +% +% \item[\cmd{setmscscale}\{\emph{scalefactor}\}] Sets the scale factor +% of the \MSC{} environment to \emph{scalefactor}. the scale factor is +% supposed to be a real number. Scaling is done when the \MSC{} +% environment ends (\verb|\end{msc}|). The default of \emph{scalefactor} +% is~1. A more consistent way for +% varying the size of the \MSC{} can be obtained by using the +% \verb+\setmesvalues+ command as described below. +% (default value 1.) +% +% \item[\cmd{psset}\{\texttt{linewidth=D}\}] This command sets the width +% of all lines in \MSC{}s, \HMSC{}s, and \MSCdoc{}s to length \verb+D+. If +% this command is issued outside the msc environment, then the value is +% set for the complete document. If it is used directly after the start +% of the msc environment it only holds for this \MSC{}.\\ +% (large/normal/small value 0.8/0.7/0.6 pt.) +% +% \item[\cmd{setfootcolor}\{\emph{color}\}] Sets the color of the foot +% symbols of \MSC{} instances. Possible values are \emph{black}, +% \emph{white}, \emph{gray}, or \emph{lightgray}. For more color values, +% see the documentation of the \LaTeXe{} \textsf{color} package. +% +% \end{defs} +% +% The following command can be used to set the above mentioned +% style parameters to suitable values. +% +% \begin{defs} +% \item[\cmd{setmscvalues}\{\emph{size}\}] Sets all parameters of the \mscpack{} to +% predefined values. Valid values for \emph{size} are: +% \verb|small|, \verb|normal|, and \verb|large|. +% (The default value of \verb+size+ is \verb+normal+. +% This can be used for drawings with at maximum six instances on a +% sheet of A4 paper. +% For sizes \verb+large+ and \verb+small+, a maximum of four and nine +% instances respectively fit on a sheet of A4 paper.) +% \end{defs} +% +% Caution has to be taken when changing the value of a parameter within +% the \MSC{} definition. The following parameters can be changed within an +% \MSC{} definition without unexpected side effects: +% +% \begin{flushleft} +% \verb+\actionheight+, +% \verb+\actionwidth+, +% \verb+\bottomfootdist+, +% \verb+\conditionheight+, +% \verb+\conditionoverlap+, +% \verb+\inlineoverlap+, +% \verb+\instfootheight+, +% \verb+\instwidth+ (however, this may cause different sizes of +% corresponding instance header and footer symbols), +% \verb+\labeldist+, +% \verb+\lastlevelheight+, +% \verb+\levelheight+, +% \verb+\lostsymbolradius+, +% \verb+\referenceoverlap+, +% \verb+\regionbarwidth+, +% \verb+\selfmesswidth+, +% \verb+\stopwidth+, +% \verb+\timerwidth+, and +% \verb+\topnamedist+. +% \end{flushleft} +% +% +% In addition to the parameters specific to the \mscpack, +% standard \LaTeX\ commands can be used to change the type style and +% other details. +% For example, if the command \verb+\sffamily+ is included directly after +% the start of the msc environment, the text in the \MSC{} +% is drawn using a {\sf sans serif} font. Likewise, the text size can be +% changed by inserting, e.g., the command \verb+\small+. +% The \verb+\raisebox+ and \verb+\parbox+ commands +% can also be used to position and format names. + + +\section{Example} +\label{example} +Figure~\ref{ex} on page~\pageref{ex} shows the \MSC{} defined in the +following \LaTeX\ fragment. + +{\small +\begin{verbatim} +\begin{msc}{Example} +\declinst{usr}{The user}{User} +\declinst{m1}{Control}{M1} +\dummyinst{m2} +\declinst{m3}{Another Machine}{M3} + +\create{start}{m1}{m2}{Processing}{M2} +\mess{msg 0}{envleft}{usr} +\mess{msg 1}{envright}{m2}[1] +\nextlevel + +\mess{msg 2}{usr}{m1} +\order{m1}{m2}[4] +\action{a}{m3} + +\nextlevel +\found{msg x}{}{usr} +\nextlevel + +\mess{msg 3}{usr}{m2}[-1] +\coregionstart{m1} +\settimeout{S}{m3}[2] +\nextlevel + + +\mess{msg 4}{m1}{usr} +\coregionstart{m2} +\settimer[r]{T}{m3} +\nextlevel + +\mess[r]{msg 5}{m2}{m2}[3] +\mess{msg 6}{usr}{usr}[2] +\nextlevel + +\mess{msg 7}{m2}{usr} +\timeout[r]{T}{m3} +\nextlevel + +\coregionend{m2} +\nextlevel + +\coregionend{m1} +\stoptimer[r]{T'}{m3} +\nextlevel + +\lost[r]{msg y}{Mach 1}{usr} +\mess{msg 8}{m1}{envright} +\nextlevel + +\condition{condition 1}{usr,m2} +\setstoptimer[r]{U}{m3} +\nextlevel[2] +\stop{usr} + +\end{msc} +\end{verbatim} +} + +\begin{figure}[htb] +\begin{center} +\begin{msc}{Example} +\declinst{usr}{The user}{User} +\declinst{m1}{Control}{M1} +\dummyinst{m2} +\declinst{m3}{Another Machine}{M3} + +\create{start}{m1}{m2}{Processing}{M2} +\mess{msg 0}{envleft}{usr} +\mess{msg 1}{envright}{m2}[1] +\nextlevel + +\mess{msg 2}{usr}{m1} +\order{m1}{m2}[4] +\action{a}{m3} + +\nextlevel +\found{msg x}{}{usr} +\nextlevel + +\mess{msg 3}{usr}{m2}[-1] +\coregionstart{m1} +\settimeout{S}{m3}[2] +\nextlevel + + +\mess{msg 4}{m1}{usr} +\coregionstart{m2} +\settimer[r]{T}{m3} +\nextlevel + +\mess[r]{msg 5}{m2}{m2}[3] +\mess{msg 6}{usr}{usr}[2] +\nextlevel + +\mess{msg 7}{m2}{usr} +\timeout[r]{T}{m3} +\nextlevel + +\coregionend{m2} +\nextlevel + +\coregionend{m1} +\stoptimer[r]{T'}{m3} +\nextlevel + +\lost[r]{msg y}{Mach 1}{usr} +\mess{msg 8}{m1}{envright} +\nextlevel + +\condition{condition 1}{usr,m2} +\setstoptimer[r]{U}{m3} +\nextlevel[2] +\stop{usr} + +\end{msc} + +\caption{A menagerie of \MSC{} symbols} +\label{ex} +\end{center} +\end{figure} + + +\section{Acknowledgments} +Thanks are due to the following people for providing us with useful +input: Cas Cremers, Hugo Jonker, Peter Peters, Sa\v{s}a Radomirovi\'c, +Michel Reniers, and Pim Vullers. + +\bibliographystyle{plain} +\bibliography{biblio} +\printindex + +\end{document} diff --git a/Master/texmf-dist/doc/latex/msc/refman.pdf b/Master/texmf-dist/doc/latex/msc/refman.pdf deleted file mode 100644 index 8423cc8ade6..00000000000 Binary files a/Master/texmf-dist/doc/latex/msc/refman.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/msc/refman.tex b/Master/texmf-dist/doc/latex/msc/refman.tex deleted file mode 100644 index 84d60381633..00000000000 --- a/Master/texmf-dist/doc/latex/msc/refman.tex +++ /dev/null @@ -1,1547 +0,0 @@ -% 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} - -- cgit v1.2.3