From b725313018cecaf42e1e195dccf34e44ae02b30e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 28 Dec 2018 23:26:11 +0000 Subject: memorygraphs (27dec18) git-svn-id: svn://tug.org/texlive/trunk@49518 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/memorygraphs/README.md | 30 ++ .../doc/latex/memorygraphs/memorygraphs.pdf | Bin 0 -> 187894 bytes .../doc/latex/memorygraphs/memorygraphs.tex | 328 +++++++++++++++++++++ 3 files changed, 358 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/memorygraphs/README.md create mode 100644 Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.pdf create mode 100644 Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.tex (limited to 'Master/texmf-dist/doc/latex/memorygraphs') diff --git a/Master/texmf-dist/doc/latex/memorygraphs/README.md b/Master/texmf-dist/doc/latex/memorygraphs/README.md new file mode 100644 index 00000000000..dc9f95729e5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/memorygraphs/README.md @@ -0,0 +1,30 @@ +# memorygraphs +Ti*k*Z styles to typeset graphs of program memory + +This package is on [CTAN][]. + +Development happens on [GitLab][]. +You can download the latest version of the package and the +[latest documentation][doc] there. + +## Colophon + +Copyright © 2018–present [Camil Staps][camilstaps]. + +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 work has the LPPL maintenance status “maintained”. + +The Current Maintainer of this work is C. Staps. + +This work consists of the files `memorygraphs.sty` and the documentation in +`memorygraphs.tex` and `example-fibonacci.tex`. + +[CTAN]: http://www.ctan.org/pkg/memorygraphs +[GitLab]: https://gitlab.science.ru.nl/cstaps/memorygraphs +[doc]: https://gitlab.science.ru.nl/cstaps/memorygraphs/-/jobs/artifacts/master/raw/memorygraphs.pdf?job=doc +[camilstaps]: https://camilstaps.nl diff --git a/Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.pdf b/Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.pdf new file mode 100644 index 00000000000..f91701e82f2 Binary files /dev/null and b/Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.pdf differ diff --git a/Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.tex b/Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.tex new file mode 100644 index 00000000000..ca38b1686d3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.tex @@ -0,0 +1,328 @@ +%% memorygraphs.tex +%% Copyright 2018 C. Staps +% +% 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 work has the LPPL maintenance status “maintained”. +% +% The Current Maintainer of this work is C. Staps. +% +% This work consists of the files memorygraphs.sty and the documentation in +% memorygraphs.tex and example-fibonacci.tex. +\documentclass[a4paper]{article} + +\usepackage{geometry} +\usepackage[hidelinks]{hyperref} +\usepackage{csquotes} +\usepackage{cleveref} + +\usepackage[nonewpage]{imakeidx} +\makeindex[intoc] + +\usepackage{latexgit} +\usepackage{fancyvrb} +\usepackage{listings} +\usepackage{color} +\definecolor{codebg}{rgb}{0.8,0.8,1} +\lstset{backgroundcolor=\color{codebg}, + frame=single, + framerule=0pt, + basicstyle=\ttfamily\footnotesize, + columns=fullflexible} + +\usepackage{memorygraphs} + +\newcommand{\memorygraphs}{\textsf{memorygraphs}} +\newcommand{\TikZ}{Ti\textit{k}Z} + +\title{The \memorygraphs{} package} +\author{Camil Staps\thanks{info@camilstaps.nl}} +\date{\gitcommitdate[formatDate]} + +\newif\ifexamplehorizontal +\newenvironment{example}{% + \medskip% + \VerbatimOut{\jobname.tmp}} + {\endVerbatimOut% + \ifexamplehorizontal% + \noindent\begin{minipage}{\linewidth} + \centering + \input{\jobname.tmp} + \end{minipage} + \par\bigskip + \noindent\begin{minipage}{\linewidth} + \lstinputlisting{\jobname.tmp} + \end{minipage} + \else% + \hfill% + \noindent\begin{minipage}{.4\linewidth} + \centering + \input{\jobname.tmp} + \end{minipage}% + \noindent\begin{minipage}{.6\linewidth} + \lstinputlisting{\jobname.tmp} + \end{minipage} + \fi% + } + +\makeatletter +\definecolor{keyheading}{rgb}{0.75,0,0} +\newcommand{\keyheading}[2][\pgfutil@empty]{% + \index{#2@\texttt{#2} key}% + \edef\pgf@test{#1}% + \item\texttt{{\color{keyheading}{/tikz/#2}}\ifx\pgf@test\pgfutil@empty\else\,=\,#1\fi}\par} +\newenvironment{keydescription}[2][\pgfutil@empty]{% + \list{}{\leftmargin=2em\itemindent-\leftmargin} + \itemsep=0pt + \parskip=0pt + \topsep=0pt + \keyheading[#1]{#2} + }{\endlist} +\newenvironment{macrodescription}[2][\pgfutil@empty]{% + \index{#2@\texttt{\textbackslash{}#2}}% + \list{}{\leftmargin=2em\itemindent-\leftmargin} + \itemsep=0pt + \parskip=0pt + \topsep=0pt + \item\texttt{{\color{keyheading}{\textbackslash#2}}\,#1} + \par\parskip3pt + }{\endlist} +\newcommand{\marg}[1]{\texttt{\textbraceleft}$#1$\texttt{\textbraceright}} +\makeatother + +\newcommand{\opt}[1]{$\langle#1\rangle$} + +\begin{document} + +\maketitle + +\begin{center} +\input{example-fibonacci} +\end{center} + +\tableofcontents + +\section{Introduction} +This is the documentation of the \LaTeX{} package \memorygraphs{}. +It defines some \TikZ{} styles and adds anchors to existing styles that ease the declaration of \enquote{memory graphs}. +It is intended for graphs that represent the memory of a computer program during its execution. + +\section{Functionality} + +\begin{keydescription}{memory graph} +The \verb$memory graph$ style is to be used on \verb$tikzpicture$. +It sets a different node distance that the author finds suitable for this kind of graphs. + +\begin{example} +\begin{tikzpicture}[memory graph] + \node[draw] (x) {37}; + \node[draw,right=of x] {42}; +\end{tikzpicture} +\end{example} +\end{keydescription} + +\subsection{Nodes} +The following styles can be used to typeset memory blocks: + +\begin{keydescription}{block} +This is the most basic style to define a memory block. +By default, this shape is a rectangle with borders: + +\begin{example} +\begin{tikzpicture}[memory graph] + \node[block] {37}; +\end{tikzpicture} +\end{example} +\end{keydescription} + +\begin{keydescription}[\opt{n}]{arity} +The \verb$arity$ style can be used to create a node with arguments. +This implies \verb$block$: + +\begin{example} +\begin{tikzpicture}[memory graph] + \node[arity=2] {Cons}; +\end{tikzpicture} +\end{example} +\end{keydescription} + +\begin{macrodescription}[\marg{i}]{arg} +Because blocks with \verb$arity$ are multipart rectangles, + one can use \TikZ{}'s \verb$\nodepart$ to put contents in the arguments. +However, it can be confusing that \verb$\nodepart{two}$ refers to the \emph{first} argument, + so we redefine \verb$\arg$ in \verb$block$s to identify arguments of the memory block: + +\begin{example} +\begin{tikzpicture}[memory graph] + \node[arity=2] {Cons \arg{1} 37 \arg{2} \dots}; +\end{tikzpicture} +\end{example} + +Should one want to use math mode's \verb$\arg$ in a memory block, they can first rename it: + +\begin{example} +\let\matharg\arg +\begin{tikzpicture}[memory graph] + \node[block] {$\matharg(1)$}; +\end{tikzpicture} +\end{example} +\end{macrodescription} + +\subsection{Markings} +It is possible to mark the head of memory blocks using triangles in the north east and south east corners. + +\begin{keydescription}[\opt{style}]{block mark north east} +\keyheading[\opt{style}]{block mark north west} +\keyheading[\opt{style}]{block mark south east} +\keyheading[\opt{style}]{block mark south west} +With this key, triangular marks can be added to the corners of the head of a node: + +\begin{example} +\begin{tikzpicture}[memory graph] + \node[arity=2,block mark north east] {Cons}; +\end{tikzpicture} +\end{example} + +It is optional to add a style: + +\begin{example} +\begin{tikzpicture} + [memory graph,every node/.style={block}] + \node[block mark north east={fill,red}] at (1,1) {1}; + \node[block mark north west={blue}] at (0,1) {2}; + \node[block mark south west={fill,green}] at (0,0) {3}; + \node[block mark south east={brown}] at (1,0) {4}; +\end{tikzpicture} +\end{example} + +The key is long to avoid clashes with other packages, + and because it depends on the context what nodes should be marked for. +It is of course possible to define a shorthand in your own document. +One application is to mark nodes that are in head normal form (HNF), + for which one may define the key \verb$hnf$: + +\begin{example} +\tikzset{every block/.style={block mark south east}} +\tikzset{hnf/.style={block mark south east=fill}} +\begin{tikzpicture}[memory graph] + \node[arity=2,hnf] + {Cons \arg{1}$\dots$ \arg{2}$\dots$}; + \node[arity=2] at (0,-1) + {map \arg{1}$\dots$ \arg{2}$\dots$}; +\end{tikzpicture} +\end{example} + +The size of the rectangles is defined by \verb$\memorygraphs@marklength$, + which can of course be changed. +The default is \makeatletter\the\memorygraphs@marklength\makeatother. + +\begin{example} +\makeatletter +\memorygraphs@marklength=7pt +\makeatother +\begin{tikzpicture}[memory graph] + \node[arity=2,block mark north west=fill] + {Cons \arg{1}$\dots$ \arg{2}$\dots$}; +\end{tikzpicture} +\end{example} +\end{keydescription} + +\subsection{Anchors} +\index{anchors} +Because blocks with \verb$arity$ are multipart rectangles, + one can use anchors like \verb$two south$ to refer to the south of the second part of a node. +These are aliased as \texttt{arg $i$ south} (and similar for other anchors on multipart nodes), + where \verb$arg 1$ stands for \verb$two$. +The first block of a node is aliased as \verb$head$ instead of \verb$arg 0$, + so one can use \verb$head south$. +For \verb$head$, anchors for the corners (\verb$head north east$, etc.) are defined as well. + +The parts of multipart rectangles do not normally have a \verb$center$ anchor, but \memorygraphs{} defines these. +One can use both \verb$two center$ and \verb$arg 1 center$ to refer to the center of the first argument of a node. + +The additional anchors are shown below. +See the \TikZ{} manual for the predefined anchors. + +{\examplehorizontaltrue +\begin{example} +\Large +\begin{tikzpicture} + \node + [arity=2, + line width=.25cm,inner xsep=1.25cm,inner ysep=.75cm, + color=black!30,fill=yellow!30] + (v) {Head \arg{1} 1 \arg{2} 2}; + \foreach \anchor/\placement in + {head north/above,head south/below,head center/below, + head north east/below,head south east/above,head north west/left,head south west/left, + arg 1 north/above,arg 1 south/below,arg 1 center/below, + arg 2 north/above,arg 2 south/below,arg 2 center/below} + \draw[shift=(v.\anchor)] plot[mark=x] coordinates{(0,0)} + node[\placement] {\scriptsize\texttt{v.\anchor}}; +\end{tikzpicture} +\end{example} +} + +\subsection{References} + +\begin{keydescription}{ref} +This is a simple style for arrows with a circle at the start and slightly rounded corners: + +\begin{example} +\begin{tikzpicture}[memory graph] + \node[arity=2] (hd) {Cons}; + \node + [arity=2,below=of hd.arg 2 center,anchor=head north] + (tl) {Cons}; + \draw[ref] (hd.arg 2 center) + -- (tl.head north); + \draw[ref] (tl.arg 2 center) + |- ($(hd.head north)+(0,.4)$) + -- (hd.head north); +\end{tikzpicture} +\end{example} +\end{keydescription} + +\section{Examples} +\examplehorizontaltrue + +\begin{itemize} +\item +The linked list of Fibonacci numbers on the title page was generated with: + +\noindent\begin{minipage}{\linewidth} + \centering + \input{example-fibonacci.tex} +\end{minipage} +\par\bigskip +\noindent\begin{minipage}{\linewidth} + \lstinputlisting{example-fibonacci.tex} +\end{minipage} + +\item +A cyclical linked list, with unboxed integers: + +\begin{example} +\begin{tikzpicture}[memory graph] + \node[block,arity=2] (xs) {Cons \arg{1} 1}; + + \node[block,arity=2,right=of xs.arg 2 east] (xsb) {Cons \arg{1} 2}; + \draw[ref] (xs.arg 2 center) -- (xsb); + + \node[block,arity=2,right=of xsb.arg 2 east] (xsc) {Cons \arg{1} 3}; + \draw[ref] (xsb.arg 2 center) -- (xsc); + + \draw[ref] (xsc.arg 2 center) -- +(0,.6) -| (xs.head north); +\end{tikzpicture} +\end{example} +\end{itemize} + +\printindex + +\end{document} -- cgit v1.2.3