diff options
author | Karl Berry <karl@freefriends.org> | 2023-12-14 20:58:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-12-14 20:58:57 +0000 |
commit | b61e86c4c7e0871158ff4bb872e46cce0939e3d2 (patch) | |
tree | bda990e0784f115b1902fd7eed60223b7dccc4c5 | |
parent | fc0be36b72419e3463372dbb555354010fcda735 (diff) |
messagepassing (14dec23)
git-svn-id: svn://tug.org/texlive/trunk@69123 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r-- | Master/texmf-dist/doc/latex/messagepassing/messagepassing.pdf | bin | 267669 -> 306130 bytes | |||
-rw-r--r-- | Master/texmf-dist/source/latex/messagepassing/messagepassing.dtx | 114 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/messagepassing/messagepassing.sty | 71 |
3 files changed, 113 insertions, 72 deletions
diff --git a/Master/texmf-dist/doc/latex/messagepassing/messagepassing.pdf b/Master/texmf-dist/doc/latex/messagepassing/messagepassing.pdf Binary files differindex 410b4d22cab..91e92d0409b 100644 --- a/Master/texmf-dist/doc/latex/messagepassing/messagepassing.pdf +++ b/Master/texmf-dist/doc/latex/messagepassing/messagepassing.pdf diff --git a/Master/texmf-dist/source/latex/messagepassing/messagepassing.dtx b/Master/texmf-dist/source/latex/messagepassing/messagepassing.dtx index 3811f558a5a..41b95184e88 100644 --- a/Master/texmf-dist/source/latex/messagepassing/messagepassing.dtx +++ b/Master/texmf-dist/source/latex/messagepassing/messagepassing.dtx @@ -14,7 +14,7 @@ % \iffalse %<package> \NeedsTeXFormat{LaTeX2e} -%<package> \ProvidesPackage{messagepassing}[2022/02/18 v1.0 A package to draw message passing diagrams] +%<package> \ProvidesPackage{messagepassing}[2023/12/13 v1.2 A package to draw message passing diagrams] %<package> \RequirePackage{tikz} %<package> \usetikzlibrary{quotes, calc, arrows.meta} %<package> \RequirePackage{xparse} @@ -60,6 +60,8 @@ % Right brace \} Tilde \~} % % +% \changes{v1.2}{2023/12/13}{Add optional display names in processes and message node options} +% \changes{v1.1}{2022/07/20}{Consistent spelling of "colour"} % \changes{v1.0}{2022/02/18}{Initial version for publication} % % \GetFileInfo{messagepassing.sty} @@ -117,7 +119,7 @@ % bottom, instead of from left to right. Doing so, almost all % labels\footnote{Annotations are not rotated, unless explicitly asked.} are % rotated as well. If, \emph{in addition}, \verb+annotatevertical+ is set, then -% annotations (including named of colouredboxes) are rotated as well. +% annotations (including names of colouredboxes) are rotated as well. % \subsection{Basic usage} % \subsubsection{Creating a diagram.} @@ -150,8 +152,12 @@ % \subparagraph{Creating a new process.} % Each process is characterised by its name. % \DescribeMacro{\newprocess} The simplest macro to create a new process is then -% |\newprocess| \marg{name}, where \marg{name} is the name of the process (resp. -% \(p\), \(q\), and \(r\) in Figure~\ref{mp:ex1}). +% |\newprocess| \marg{name} \oarg{display name}, where \marg{name} is the name +% of the process (resp. \(p\), \(q\), and \(r\) in Figure~\ref{mp:ex1}). If +% \oarg{display name} is provided, it is used as the name when rendering the +% figure, while \marg{name} is used internally to refer to the process. This +% allows you to use names that can not be used internally (e.g.\ with maths or +% things like that). % % In addition, we often draw a horizontal\footnote{By default, the line is vertical if % the option |vertical| is used.} line that represent the running process. @@ -160,21 +166,21 @@ % creates a line of length \emph{length} for process \emph{process}.}, we also % provide a simple macro that performs both actions: % \DescribeMacro{\newprocesswithlength} -% |\newprocesswithlength|\marg{name}\marg{length}. +% |\newprocesswithlength|\marg{name}\oarg{display name}\marg{length}. % % An other alternative is to name the state in which the process starts (in % Fig~\ref{mp:ex1}, we call those states \(si\) as \emph{state intervals}). % Again, this can be achieved using individual commands, but we also provide % \DescribeMacro{\newprocesswithstateinterval} -% |\newprocesswithstateinterval|\marg{name}\marg{state name}. +% |\newprocesswithstateinterval|\marg{name}\oarg{display name}\marg{state name}. % % Finally, an other way to create a process is to create a process that % (eventually) fails, which is represented by the process' line terminating % early with a cross. For that, we provide \DescribeMacro{\newprocesswithcrash} -% |\newprocesswithcrash|\marg{name}\marg{length}\marg{crash coordinate name}. -% The first two arguments are similar to |\newprocesswithlength|, and the latter -% one is used to provide a name for the coordinate where the crash occurs. This -% name can later be used to place nodes. +% |\newprocesswithcrash|\marg{name}\oarg{display name}\marg{length}\marg{crash coordinate name}. +% The first arguments are similar to |\newprocesswithlength|, and the last one +% is used to provide a name for the coordinate where the crash occurs. This name +% can later be used to place nodes. % % Of course, we can imagine other combinations (e.g. a process with a length and % a state interval). We do not provide individual commands for each combination, @@ -205,17 +211,22 @@ % according to their timestamp\footnote{Notice that nothing prevents sending % messages in the past, simply set a receiving time before the sending time.}. % +% For instance, in Figure~\ref{fig:ex_msg}, we use |\send{p}{1}{q}{2}|. +% % In addition, we can label the arrow with the message that is sent with % \DescribeMacro{\sendwithname} % |\sendwithname|\marg{sender}\marg{send time}\marg{receiver}\marg{receive -% time}\marg{label}. -% For instance, in Figure~\ref{fig:ex_msg}, we use |\send{p}{1}{q}{2}|. +% time}\marg{label}\oarg{label options}. The \marg{label} contains the label +% that should be displayed. The package provides default positioning options for +% the label, which should be acceptable for most cases. Those positioning +% options can be overridden by \oarg{label options}, which should be \TikZ node +% options. % % Finally, we sometimes distinguish \emph{out-of-band} messages, e.g. messages % that do not carry informations, but that are for instance used for metadata, % etc.. We provide the macro % \DescribeMacro{\sendoutofband}|\sendoutofband|\marg{sender}\marg{send time}\marg{receiver}\marg{receive -% time}\marg{label}, which behaves similarly to |\sendwithname|, but prints the +% time}\marg{label}\oarg{label options}, which behaves similarly to |\sendwithname|, but prints the % message in an other colour. % % \begin{figure} @@ -315,7 +326,7 @@ % A checkpoint can be added with % \DescribeMacro{\checkpoint}|\checkpoint|\marg{process}\marg{time}\marg{name}, % where \emph{process} is the name of the process which takes a checkpoint, -% \emph{time} is the the time at which the checkpoint is taken, and \emph{name} +% \emph{time} is the time at which the checkpoint is taken, and \emph{name} % is the name of the checkpoint, that is printed next to it, and can be used as % a coordinate. Notice that the name is printed in a math environment, as we % expect most checkpoints names to be indexed, e.g.\(c_1\), \(c_2\), etc. @@ -425,12 +436,12 @@ % Two parts of the package use colours: colouredboxes and out-of-band messages. By % default both are shades of red. We provide commands to change that if desired. % -% \DescribeMacro{\colouredboxcolor}|\colouredboxcolor|\marg{colour} changes the colour +% \DescribeMacro{\colouredboxcolour}|\colouredboxcolour|\marg{colour} changes the colour % used for colouredboxes. Notice that this sets both the background colour (which is % a light variant of the provided colour) and the text colour (which uses the % provided colour). % -% \DescribeMacro{\oobcolor}|\oobcolor|\marg{colour} changes the colour used for +% \DescribeMacro{\oobcolour}|\oobcolour|\marg{colour} changes the colour used for % out-of-band messages. % % \subsubsection{Coordinates} @@ -579,14 +590,14 @@ \newcommand{\mp@annotaterotation}{0} \fi -\newcommand{\mp@oobcolor}{red} -\newcommand{\oobcolor}[1]{ - \renewcommand\mp@oobcolor{#1} +\newcommand{\mp@oobcolour}{red} +\newcommand{\oobcolour}[1]{ + \renewcommand\mp@oobcolour{#1} } -\newcommand{\mp@colouredboxcolor}{red} -\newcommand{\colouredboxcolor}[1]{ - \renewcommand\mp@colouredboxcolor{#1} +\newcommand{\mp@colouredboxcolour}{red} +\newcommand{\colouredboxcolour}[1]{ + \renewcommand\mp@colouredboxcolour{#1} } \newif\iftimeline @@ -655,38 +666,42 @@ % % \begin{macrocode} %% #1: name -\newcommand{\newprocess}[1]{ +%% #2: display name +\NewDocumentCommand{\newprocess}{m o}{ \addtocounter{processnb}{1} \coordinate (#1) at (0, -\value{processnb}); - \draw (#1) node[anchor=\mp@processnameanchor] {$#1$}; + \draw (#1) node[anchor=\mp@processnameanchor] {\IfValueTF{#2}{#2}{$#1$}}; } % \end{macrocode} % % \begin{macrocode} %% #1: name -%% #2: width -\newcommand{\newprocesswithlength}[2]{ - \newprocess{#1} - \processlength{#1}{#2} +%% #2: display name +%% #3: width +\NewDocumentCommand{\newprocesswithlength}{m o m}{ + \newprocess{#1}[#2] + \processlength{#1}{#3} } % \end{macrocode} % % \begin{macrocode} %% #1: name -%% #2: state interval name -\newcommand{\newprocesswithstateinterval}[2]{ - \newprocess{#1} - \stateinterval{#1}{0}{#2} +%% #2: display name +%% #3: state interval name +\NewDocumentCommand{\newprocesswithstateinterval}{m o m}{ + \newprocess{#1}[#2] + \stateinterval{#1}{0}{#3} } % \end{macrocode} % % \begin{macrocode} %% #1: name -%% #2: width -%% #3: crash name -\newcommand{\newprocesswithcrash}[3]{ - \newprocess{#1}{#2} - \crash{#1}{#2}{#3} +%% #2: display name +%% #3: width +%% #4: crash name +\NewDocumentCommand{\newprocesswithcrash}{m o m m}{ + \newprocess{#1}[#2]{#3} + \crash{#1}{#3}{#4} } % \end{macrocode} % @@ -706,8 +721,13 @@ %% #3: receiver's name %% #4: receive date %% #5: message name -\newcommand{\sendwithname}[5]{ - \draw[->] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5}; +%% #6: message name display options +\NewDocumentCommand{\sendwithname}{m m m m m o}{ + \IfValueTF{#6}{ + \draw[->] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3, #6] {#5}; + }{ + \draw[->] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5}; + } } % \end{macrocode} % @@ -738,8 +758,9 @@ %% #4: receive date %% #5: state interval name %% #6: message name -\newcommand{\sendwithstateintervalandname}[6] { - \sendwithname{#1}{#2}{#3}{#4}{#6} +%% #7: message name display options +\NewDocumentCommand{\sendwithstateintervalandname}{m m m m m m o} { + \sendwithname{#1}{#2}{#3}{#4}{#6}[#7] \stateinterval{#3}{#4}{#5} } % \end{macrocode} @@ -750,8 +771,13 @@ %% #3: receiver's name %% #4: receive date %% #5: OoB message name -\newcommand{\sendoutofband}[5]{ - \draw[->, color=\mp@oobcolor] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5}; +%% #6: OoB message name display options +\NewDocumentCommand{\sendoutofband}{m m m m m o}{ + \IfValueTF{#6}{ + \draw[->, color=\mp@oobcolour] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3, #6] {#5}; + }{ + \draw[->, color=\mp@oobcolour] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5}; + } } % \end{macrocode} % @@ -826,7 +852,7 @@ %% #5: caption \newcommand{\colouredbox}[5]{ \begin{pgfonlayer}{background} - \fill[color=\mp@colouredboxcolor!20] ($(#1) + (#3, 0)$) rectangle ($(#2) + (#4, 0)$) node[midway, color = \mp@colouredboxcolor, rotate=\mp@annotaterotation]{#5}; + \fill[color=\mp@colouredboxcolour!20] ($(#1) + (#3, 0)$) rectangle ($(#2) + (#4, 0)$) node[midway, color = \mp@colouredboxcolour, rotate=\mp@annotaterotation]{#5}; \end{pgfonlayer} } % \end{macrocode} diff --git a/Master/texmf-dist/tex/latex/messagepassing/messagepassing.sty b/Master/texmf-dist/tex/latex/messagepassing/messagepassing.sty index f807ec06ca1..cb321808bd5 100644 --- a/Master/texmf-dist/tex/latex/messagepassing/messagepassing.sty +++ b/Master/texmf-dist/tex/latex/messagepassing/messagepassing.sty @@ -20,7 +20,7 @@ %% \NeedsTeXFormat{LaTeX2e} - \ProvidesPackage{messagepassing}[2022/02/18 v1.0 A package to draw message passing diagrams] + \ProvidesPackage{messagepassing}[2023/12/13 v1.2 A package to draw message passing diagrams] \RequirePackage{tikz} \usetikzlibrary{quotes, calc, arrows.meta} \RequirePackage{xparse} @@ -85,14 +85,14 @@ \newcommand{\mp@annotaterotation}{0} \fi -\newcommand{\mp@oobcolor}{red} -\newcommand{\oobcolor}[1]{ -\renewcommand\mp@oobcolor{#1} +\newcommand{\mp@oobcolour}{red} +\newcommand{\oobcolour}[1]{ +\renewcommand\mp@oobcolour{#1} } -\newcommand{\mp@colouredboxcolor}{red} -\newcommand{\colouredboxcolor}[1]{ -\renewcommand\mp@colouredboxcolor{#1} +\newcommand{\mp@colouredboxcolour}{red} +\newcommand{\colouredboxcolour}[1]{ +\renewcommand\mp@colouredboxcolour{#1} } \newif\iftimeline @@ -153,29 +153,33 @@ } \ExplSyntaxOff %% #1: name -\newcommand{\newprocess}[1]{ +%% #2: display name +\NewDocumentCommand{\newprocess}{m o}{ \addtocounter{processnb}{1} \coordinate (#1) at (0, -\value{processnb}); -\draw (#1) node[anchor=\mp@processnameanchor] {$#1$}; +\draw (#1) node[anchor=\mp@processnameanchor] {\IfValueTF{#2}{#2}{$#1$}}; } %% #1: name -%% #2: width -\newcommand{\newprocesswithlength}[2]{ -\newprocess{#1} -\processlength{#1}{#2} +%% #2: display name +%% #3: width +\NewDocumentCommand{\newprocesswithlength}{m o m}{ +\newprocess{#1}[#2] +\processlength{#1}{#3} } %% #1: name -%% #2: state interval name -\newcommand{\newprocesswithstateinterval}[2]{ -\newprocess{#1} -\stateinterval{#1}{0}{#2} +%% #2: display name +%% #3: state interval name +\NewDocumentCommand{\newprocesswithstateinterval}{m o m}{ +\newprocess{#1}[#2] +\stateinterval{#1}{0}{#3} } %% #1: name -%% #2: width -%% #3: crash name -\newcommand{\newprocesswithcrash}[3]{ -\newprocess{#1}{#2} -\crash{#1}{#2}{#3} +%% #2: display name +%% #3: width +%% #4: crash name +\NewDocumentCommand{\newprocesswithcrash}{m o m m}{ +\newprocess{#1}[#2]{#3} +\crash{#1}{#3}{#4} } %% #1: sender's name %% #2: send date @@ -189,9 +193,14 @@ %% #3: receiver's name %% #4: receive date %% #5: message name -\newcommand{\sendwithname}[5]{ +%% #6: message name display options +\NewDocumentCommand{\sendwithname}{m m m m m o}{ +\IfValueTF{#6}{ +\draw[->] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3, #6] {#5}; +}{ \draw[->] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5}; } +} %% #1: process name %% #2: process width \newcommand{\processlength}[2]{ @@ -212,8 +221,9 @@ %% #4: receive date %% #5: state interval name %% #6: message name -\newcommand{\sendwithstateintervalandname}[6] { -\sendwithname{#1}{#2}{#3}{#4}{#6} +%% #7: message name display options +\NewDocumentCommand{\sendwithstateintervalandname}{m m m m m m o} { +\sendwithname{#1}{#2}{#3}{#4}{#6}[#7] \stateinterval{#3}{#4}{#5} } %% #1: sender's name @@ -221,8 +231,13 @@ %% #3: receiver's name %% #4: receive date %% #5: OoB message name -\newcommand{\sendoutofband}[5]{ -\draw[->, color=\mp@oobcolor] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5}; +%% #6: OoB message name display options +\NewDocumentCommand{\sendoutofband}{m m m m m o}{ +\IfValueTF{#6}{ +\draw[->, color=\mp@oobcolour] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3, #6] {#5}; +}{ +\draw[->, color=\mp@oobcolour] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5}; +} } %% #1: process's name %% #2: state interval date @@ -276,7 +291,7 @@ %% #5: caption \newcommand{\colouredbox}[5]{ \begin{pgfonlayer}{background} -\fill[color=\mp@colouredboxcolor!20] ($(#1) + (#3, 0)$) rectangle ($(#2) + (#4, 0)$) node[midway, color = \mp@colouredboxcolor, rotate=\mp@annotaterotation]{#5}; +\fill[color=\mp@colouredboxcolour!20] ($(#1) + (#3, 0)$) rectangle ($(#2) + (#4, 0)$) node[midway, color = \mp@colouredboxcolour, rotate=\mp@annotaterotation]{#5}; \end{pgfonlayer} } %% #1: Timeline length |