pgf-umlsd-manual.tex

% Manual of pgf-umlsd.sty, a convenient set of macros for drawing UML
% sequence diagrams.
% Written by Xu Yuan <xuyuan.cn@gmail.com> from
% Southeast University, China.
% This file is part of pgf-umlsd
% you may get it at http://code.google.com/p/pgf-umlsd/

\documentclass{article}
\usepackage[margin=12mm]{geometry}
\usepackage{hyperref}
\usepackage[underline=true,rounded corners=false]{pgf-umlsd}
\usetikzlibrary{calc}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{listings}
\usepackage{color}
\definecolor{listinggray}{gray}{0.92}
\lstset{ %
language=[LaTeX]TeX,
breaklines=true,
frame=single,
% frameround=tttt,
basicstyle=\footnotesize\ttfamily,
backgroundcolor=\color{listinggray},
keywordstyle=\color{blue}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\hypersetup{
  colorlinks=true,
  linkcolor=blue,
  anchorcolor=black,
  citecolor=olive,
  filecolor=magenta,
  menucolor=red,
  urlcolor=blue
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\demo}[2][1]{
  \begin{center}
  \begin{tabular}{cc}
    \begin{minipage}{.49\linewidth}
      \centering
      \resizebox{#1\linewidth}{!}{
        \input{demo/#2}
      }
    \end{minipage}
    &
    \begin{minipage}{.45\linewidth}
      \lstinputlisting{demo/#2}
    \end{minipage}
  \end{tabular}
  \end{center}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\example}[2][1]{
  \begin{center}  
    \resizebox{#1\linewidth}{!}{
      \input{demo/#2}
    }
  \end{center}
  \lstinputlisting{demo/#2}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 

\begin{document}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\title{Drawing UML Sequence Diagram by using \texttt{pgf-umlsd}}
\author{\href{mailto:xuyuan.cn@gmail.com}{Yuan Xu}}
\date{\today{}~(v0.7)}
\maketitle
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{abstract}
  \texttt{pgf-umlsd} is a LaTeX package for drawing UML Sequence
  Diagrams. As stated by its name, it is based on a very popular
  graphic package \texttt{PGF/TikZ}. This document presents the usage
  of \texttt{pgf-umlsd} and collects some UML sequence diagrams as
  examples. \texttt{pgf-umlsd} can be downloaded from
  \href{http://code.google.com/p/pgf-umlsd/}{http://code.google.com/p/pgf-umlsd/}.
\end{abstract}

\tableofcontents

\section{The Essentials}
\subsection{Basic graphics objects}
\subsubsection{empty diagram}
\demo{empty}

\subsubsection{thread}
\demo[0.3]{thread}

\subsubsection{instance}
\demo[0.3]{instance}

\subsubsection{distance between threads and instances}
\demo{distance}

\subsubsection{customization}
The package has two options for customization: \texttt{underline} and
\texttt{rounded corners}, further customization see the example below:

\demo{customize}


\subsection{Call}
\subsubsection{call}
\demo[0.6]{call}

\subsubsection{call self}
\demo[0.6]{callself}

\subsubsection{message call}
\demo[0.6]{messcall}

\subsubsection{nested call}
\demo[0.6]{nested-call}

\subsubsection{call from outside}
\demo[0.6]{call-from-outside}

\subsection{Message}
\demo[0.6]{message}

Sometimes however, it takes a considerable amount of time to reach the
receiver (relatively speaking of course) . For example, a message
across a network. Such a non-instantaneous message is drawn as a
slanted arrow.

\demo[0.6]{non-instantaneous-message}

\subsection{Block}
\demo[0.6]{block}

\section{Manually adjustment}
The idea of \texttt{pgf-umlsd} is users only have to write the logic
of diagram, the program generates figure automatically. However, the
package can not handle all the use case, it still needs to be adjusted
manually.

\subsection{Level}
If the text on the arrows is more than one line (large function name
for example) it will overlap other things. \texttt{postlevel} can be
used to make the time (level) later.

\demo[0.6]{postlevel}

In the situation of multi-threads, some events happen at the same
time. \texttt{prelevel} can make the call earlier.

\demo[0.6]{prelevel}

\subsection{Bias of thread line}
In the situation of multi-threads, the instance can be accessed at the
same time (e.g. two threads reading data at the same time). Currently,
we have to adjust the bias of thread line manually for this. Possible
parameters for \texttt{setthreadbias} are: \texttt{center},
\texttt{west} and \texttt{east}.

\demo[0.8]{threadbias}

\section{Examples}
\subsection{Single thread}
\example[0.8]{single-thread-example}

\subsection{Multi-threads}
\example[0.8]{multi-threads-example}

\subsection{Annotation}
\example[0.5]{sync-clock}

\subsection{Protocol Message Diagram}
\example[0.8]{protocol-message-diagram}

\subsection{Known Issue}
\texttt{pgf-umlsd} conflicts with tikz \texttt{backgrounds} library.

\section{Acknowledgements}
Many people contributed to \texttt{pgf-umlsd} by reporting problems,
suggesting various improvements or submitting code. Here is a list of
these people:
\href{mailto:nobel1984@gmail.com}{Nobel Huang},
\href{mailto:humbert@uni-wuppertal.de}{Dr. Ludger Humbert},
\href{mailto:MathStuf@gmail.com}{MathStuf},
\href{mailto:vlado.handziski@gmail.com}{Vlado Handziski},
\href{mailto:frankmorgner@gmail.com}{Frank Morgner},
\href{mailto:petrautzki@hs-coburg.de}{Dirk Petrautzki},
and \href{mailto:christianklos@gmx.net}{Christian Klos}.

\end{document}
%%% Local Variables: 
%%% mode: Tex-PDF
%%% TeX-master: t
%%% End: