summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-12-28 23:26:11 +0000
committerKarl Berry <karl@freefriends.org>2018-12-28 23:26:11 +0000
commitb725313018cecaf42e1e195dccf34e44ae02b30e (patch)
treedfd21f2a9db07901d6485f7847a1bcca167544b0 /Master/texmf-dist/doc
parent5f5e3b734fe79b18115c591ba0d2b1a789e7678a (diff)
memorygraphs (27dec18)
git-svn-id: svn://tug.org/texlive/trunk@49518 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/memorygraphs/README.md30
-rw-r--r--Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.pdfbin0 -> 187894 bytes
-rw-r--r--Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.tex328
3 files changed, 358 insertions, 0 deletions
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 &copy; 2018&ndash;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
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/memorygraphs/memorygraphs.pdf
Binary files 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}