summaryrefslogtreecommitdiff
path: root/graphics/pgf/contrib/codeanatomy/codeanatomy.usage.tex
blob: 5136905babb6b07503df8f56ec14e39660a47f17 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
\documentclass[full]{l3doc}  
\usepackage{fontspec}
\usepackage{biblatex}
\addbibresource{literatur.bib}
\newcommand{\slsh}{\textbackslash{}}
\newcommand{\TikZ}{Ti\textit{k}Z}
\def\thinmargin{\list{}{\rightmargin-50pt\leftmargin-90pt}\item[]}
\let\endthinmargin=\endlist

\usepackage{listings}
\lstset {
    basicstyle=\small\ttfamily
    ,escapeinside={+}{+}
}

\usepackage{codeanatomy}

\begin{document}

\GetFileInfo{codeanatomy.sty}
\DoNotIndex{}

\title{
  \pkg{codeanatomy} -- Draw Code Anatomy%
  \thanks{This file describes \fileversion,
    last revised \filedate.}\\[1ex]
  \normalsize{Usage}  
}

\author{
 Hồng-Phúc Bùi
 \thanks{
   E-mail:
   \href{mailto:Hồng-Phúc Bùi}
     {hong-phuc.bui (at) htwsaar dot de}
  }
}

\date{Released \filedate}

\AtEndDocument{
 \printbibliography
}

\maketitle
\tableofcontents

\begin{documentation}
\section{Introduction}
The idea of this Package is to typeset illustrations of pieces of code with 
annotations on each single parts of code (Code Anatomy). The origin of this idear is
code illustrations in the texbook~\autocite{sedgewick-wayne-2016}. This package 
just provides tool to draw those figures.

\section{Tutorial} 
In this tutorial we will draw an anatomy of a function like the
figure~\ref{fig:tut1-function} step by step.

\begin{figure} 
\begin{centering}  
\begin{tikzpicture}[remember picture]
\codeBlock{
\cPart{functionHead}{function \cPart{functionName}{gcd} \cPart{parameterList}{(p, q)}}\{ \\[2.5pt] %
\ptab{}\mtPoint{mostLeft}if (q === 0) \{\\
\ptab\ptab{}return p; \\
\ptab{}\} else \{\\
\ptab\ptab{}return gcd(q, p \% q);\extremPoint{mostRight}\\
\ptab{}\}\mbPoint{mostBottom}\\
\}
};

\node(functionBody)[draw,code part,fit=(mostLeft) (mostRight) (mostBottom)] {};

% Anotation labels
\codeAnnotation{functionHeadText}(-1,3)  {Function\\Head}
\codeAnnotation{functionBodyText}(-1,1.5){Function\\Body}
\codeAnnotation{functionNameText}(1,4)   {Function Name}
\codeAnnotation{parameterListText} (4,4) {Paramter List}

% Annotation labels to Code
\draw[->, annotation] (functionBodyText) -- (functionBody);
\draw[->, annotation] (functionHeadText) -- (functionHead);
\draw[->, annotation] (functionNameText) -- (functionName);
\draw[->, annotation] (parameterListText) -- (parameterList);
\end{tikzpicture}

\caption{Anatomy of a function\label{fig:tut1-function}}
\end{centering}
\end{figure}

\subsection{Package Usage}
To use this package, just insert |\usepackage{codeanatomy}| in your \LaTeX{} file.

\subsection{Create an anatomy environment}
Next step is to create a |tikzpicture| environment. All commands in this package must be placed in 
a |tikzpicture| environment with option |remember picture|.

\begin{thinmargin}
\begin{tikzpicture}[remember picture]
\codeBlock{
\textbackslash{}begin\{tikzpicture\}[\cPart{option}{remember picture}]\\
\cPart{debugGrid}{\{[on background layer]\textbackslash{}draw[code grid debug] (-0.5,-0.5) grid (6.5,4.5);\}}\\
\% ... \\
\textbackslash{}end\{tikzpicture\}
}

% Annotation labels
\codeAnnotation{optionText}    (5,2.5) {necsessary for\\later mark}
\codeAnnotation{debugGridText} (7,0)   {plot a thin grey grid on background\\usefull to determinate coordinate of annotation}

% Annotation labels to code
\draw[->, annotation] (optionText) -- (option);
\draw[->, annotation] (debugGridText) -- (debugGrid);
\end{tikzpicture}
\end{thinmargin}


\subsection{Typeset Code Listing in a TikZ-Node}
As next step we need to put the piece of code in the |tikzpicture| environment using 
the command |\codeBlock|. \medskip


\begin{thinmargin}
\begin{tikzpicture}[remember picture]
\codeBlock{
\textbackslash{}begin\{tikzpicture\}[remember picture]\\
\{[on background layer]\textbackslash{}draw[code grid debug]\\
                       \ptab\ptab (-0.5,-0.5) grid (6.5,4.5);\}\\
\textbackslash{}codeBlock\{\% \\
\mtPoint{mostLeft}function gcd(p, q) \{ \\
\ptab{}if (q === 0) \{ \\
\ptab\ptab{}return p; \\
\ptab{}\} else \{ \\
\ptab\ptab{}return gcd(q, p\%q);\extremPoint{mostRight}\\
\ptab\} \\
\mbPoint{mostBottom}\}\\
\} \\
\textbackslash{}end\{tikzpicture\}
}

\node(codeBlockBody)[draw,code part,fit=(mostLeft) (mostRight) (mostBottom)] {};

\codeAnnotation{codeBlockBodyText} (7,2.5) {Anatomy of Code}
\draw[->, annotation] (codeBlockBodyText) -- (codeBlockBody);
\end{tikzpicture}
\end{thinmargin}

The result of the above code is shown in the figure~\ref{fig:function-compressed},
which is not what we really want. All extra whitespaces and newlines in the 
listing are removed, further more |{| and |}| are interpreted as \LaTeX{} tokens and are not 
displayed.

\begin{figure}[h]
\begin{centering}  
\begin{tikzpicture}[remember picture]
{[on background layer]\draw[code grid debug] (-0.5,-0.5) grid (6.5,4.5);}
\codeBlock{
function gcd(p, q) {
    if (q === 0) {
        return p;
    } else {
        return gcd(q, p\%q);
    }
}
}
\end{tikzpicture}
\caption{Unformated Code\label{fig:function-compressed}}  
\end{centering}
\end{figure}


We need to put |\ptab| and |\\| into code to keep whitespaces and newlines. The characters |{| and |}|
also need to be escaped by prefixing a |\| before them.

\begin{thinmargin}
\begin{tikzpicture}[remember picture]
\codeBlock{
\textbackslash{}begin\{tikzpicture\}[remember picture]\\
\{[on background layer]\textbackslash{}draw[code grid debug]\\
                       \ptab\ptab (-0.5,-0.5) grid (6.5,4.5);\}\\
\textbackslash{}codeBlock\{\%\\
function gcd(p, q) \slsh\{                          \cPart{sh1}{\slsh\slsh}\\
\cPart{ptab1}{\slsh{}ptab\{\}}if (q === 0) \slsh\{                 \cPart{sh2}{\slsh\slsh}\\
\cPart{ptab2}{\slsh{}ptab\slsh{}ptab\{\}}return p;                 \cPart{sh3}{\slsh\slsh}\\
\cPart{ptab3}{\slsh{}ptab}\slsh\} else \slsh\{                     \cPart{sh4}{\slsh\slsh}\\
\cPart{ptab4}{\slsh{}ptab\slsh{}ptab\{\}}return gcd(q, p\slsh\%q); \cPart{sh5}{\slsh\slsh}\\
\cPart{ptab5}{\slsh{}ptab}\slsh\}                                  \cPart{sh6}{\slsh\slsh}\\
\slsh\}                                             \cPart{sh7}{\slsh\slsh}\\
\} \\
\textbackslash{}end\{tikzpicture\}
}

% Annotation labels
\codeAnnotation{shText}    (9,2.5) {Double backslash}
\codeAnnotation{ptabText}  (-2,2.5) {\texttt{\slsh{}ptab} proceduces\\whitespaces}
% Annotation labels to code
\draw[->, annotation] (shText.20) to[out=90,in=0] (sh1.east);
\draw[->, annotation] (shText.80) to[out=95,in=0] (sh2.east);
\draw[->, annotation] (shText) -- (sh3);
\draw[->, annotation] (shText) -- (sh4);
\draw[->, annotation] (shText) -- (sh5);
\draw[->, annotation] (shText.270) to[out=260,in=0] (sh6);
\draw[->, annotation] (shText.340) to[out=260,in=0] (sh7);

\draw[->, annotation] (ptabText) -- (ptab1.west);
\draw[->, annotation] (ptabText) -- (ptab2.west);
\draw[->, annotation] (ptabText) -- (ptab3.west);
\draw[->, annotation] (ptabText) -- (ptab4.west);
\draw[->, annotation] (ptabText) -- (ptab5.west);
\end{tikzpicture}
\end{thinmargin}

The result (figure~\ref{fig:function-formated}) is much more like what we expect 
than the version before (figure~\ref{fig:function-compressed}).

\begin{figure}[h]
\begin{centering}
\begin{tikzpicture}[remember picture]
{[on background layer]\draw[code grid debug] (-0.5,-0.5) grid (6.5,4.5);}
\codeBlock{
function gcd(p, q) \{ \\
\ptab{}if (q === 0) \{ \\
\ptab\ptab{}return p; \\
\ptab\} else \{ \\
\ptab\ptab{}return gcd(q, p\%q); \\
\ptab\} \\
\} \\
}
\end{tikzpicture}    
\caption{Formated Function\label{fig:function-formated}}
\end{centering}
\end{figure}

\subsection{Mark Parts of Code}
Now we can mark interesting parts of code with a blue boxes created by |\cPart|. At some positions 
we can use |\\[<length>]| to add a little amount of vertical space, sothat the boxes do not touch 
each others. 

\begin{thinmargin}
\begin{tikzpicture}[remember picture]
{[on background layer]\draw[code grid debug] (-0.5,-0.5) grid (10.5,4.5);}\\  
\codeBlock{
\textbackslash{}begin\{tikzpicture\}[remember picture]\\
\{[on background layer]\textbackslash{}draw[code grid debug]\\
                       \ptab\ptab (-0.5,-0.5) grid (6.5,4.5);\}\\
\textbackslash{}codeBlock\{\%\\
\cPart{nestedCodePart}{\slsh{}cPart\{functionHead\}\{function\slsh{}cPart\{functionName\}\{gcd\} \slsh{}cPart\{paramList\}\{(p, q)\}\}} \slsh\{\\
  \slsh\slsh[2.5pt]\\
\slsh{}ptab\{\}\cPart{ep1}{\slsh{}mtPoint\{mostLeft\}}if (q === 0) \slsh\{                                                         \slsh\slsh\\
\slsh{}ptab                                               \slsh{}ptab\{\}return p;                                                               \slsh\slsh\\
\slsh{}ptab                                                   \slsh\} else \slsh\{                                                               \slsh\slsh\\
\slsh{}ptab                                               \slsh{}ptab\{\}return gcd(q, p\slsh\%q); \cPart{ep2}{\slsh{}extremPoint\{mostRight\}}  \slsh\slsh\\
\slsh{}ptab\cPart{ep3}{\slsh{}mbPoint\{mostBottom\}}\slsh\}                                                                     \slsh\slsh\\
\slsh\}                                                                                                                                          \slsh\slsh\\
\} \\ 
   \\
\cPart{fitExtemCmd}{\slsh{}fitExtrem\{functionBody\}\{(mostLeft) (mostRight) (mostBottom)\}}\\
\slsh{}end\{tikzpicture\}
}
 
\codeAnnotation{nestedCodePartText}(11,6){\texttt{cPart} can be nested}
\codeAnnotation{exText}            (15,3){\texttt{extremPoint}s\\are used to mark\\outer most points of\\a multiline code part}
\codeAnnotation{fitExtemCmdText}   (6,-1){\texttt{fitExtrem} draws a rectangle\\which covers all passed extrem points}

\draw[->, annotation] (nestedCodePartText) to[out=270,in=90] (nestedCodePart);
\draw[->, annotation] (exText) to[out=145,in=320] (ep1.south east);
\draw[->, annotation] (exText) to[out=190,in=300] (ep2.320);
\draw[->, annotation] (exText) to[out=220,in=350] (ep3.340);
\draw[->, annotation] (fitExtemCmdText) -- (fitExtemCmd);
\end{tikzpicture} 
\end{thinmargin}


\begin{figure}[ht]
\centering
\begin{tikzpicture}[remember picture]
{[on background layer]\draw[code grid debug]
    (-0.5,-0.5) grid (6.5,4.5);}
\codeBlock{%
\cPart{functionHead}{function\cPart{functionName}{gcd} \cPart{paramList}{(p, q)}} \{
\\[2.5pt]
\ptab{}\mtPoint{mostLeft} if (q === 0) \{ \\
\ptab\ptab{}return p; \\
\ptab\} else \{ \\  
\ptab\ptab{}return gcd(q, p\%q); \extremPoint{mostRight} \\  
\ptab\mbPoint{mostBottom}\} \\
\} \\
}
\fitExtrem{functionBody}{(mostLeft) (mostRight) (mostBottom)}
\end{tikzpicture}  
\caption{Function with marked parts\label{fig:function-parts}}
\end{figure}

\subsection{Create Annotation Labels}
We can use |\codeAnnotation| to create annotation labels for each parts of code. To draw an 
arrow from label to a code part we can use the \TikZ{}command\\
|\draw[->,annotation]| \parg{annotation label} |--| \parg{code part} |;|.\\
Whereas \parg{annotation label}s are the first argument of |\codeAnnotation|s and 
\parg{code part}s are the first argument of |\cPart|s.

\begin{thinmargin}
\begin{tikzpicture}[remember picture]
\codeBlock{
\textbackslash{}begin\{tikzpicture\}[remember picture]\\
\{[on background layer]\textbackslash{}draw[code grid debug]\\
                       \ptab\ptab (-0.5,-0.5) grid (6.5,4.5);\}\\
\textbackslash{}codeBlock\{\%\\
\slsh{}cPart\{functionHead\}                                \{function \slsh{}cPart\{functionName\}\{gcd\} \slsh{}cPart\{paramList\}\{(p, q)\}\} \slsh\{\\
  \slsh\slsh[2.5pt]\\
\slsh{}ptab\{\}\slsh{}mtPoint\{mostLeft\}          if (q === 0) \slsh\{                                                                                \slsh\slsh\\
\slsh{}ptab\slsh{}ptab\{\}                                           return p;                                                                                       \slsh\slsh\\
\slsh{}ptab\slsh                                                 \} else \slsh\{                                                                                     \slsh\slsh\\
\slsh{}ptab\slsh{}ptab\{\}                                           return gcd(q, p\slsh\%q);       \slsh{}extremPoint\{mostRight\}                                 \slsh\slsh\\
\slsh{}ptab\slsh{}mbPoint\{mostBottom\}\slsh\}                                                                                                      \slsh\slsh\\
\slsh\}                                             \\
\} \\ 
   \\
\slsh{}fitExtrem\{functionBody\}\{(mostLeft) (mostRight) (mostBottom)\}\\ 
\\
\% Annotations \\
\slsh{}codeAnnotation\{functionHeadText\}(-1,3)\{Function\slsh\slsh{}head\} \\
\slsh{}codeAnnotation\{functionBodyText\}(-1,1)\{Function\slsh\slsh{}body\} \\
\slsh{}codeAnnotation\{functionNameText\}( 1,4)\{Function\slsh\slsh{}name\} \\
\slsh{}codeAnnotation\{paramListText\}   ( 3,4)\{Parameter\slsh\slsh{}list\} \\
\\
\% Annotation labels to code parts\\
\slsh{}draw[->,annotation] (functionHeadText) -- (functionHead);\\
\slsh{}draw[->,annotation] (functionBodyText) -- (functionBody);\\
\slsh{}draw[->,annotation] (functionNameText) -- (functionName);\\
\slsh{}draw[->,annotation] (paramListText) -- (paramList);\\
\slsh{}end\{tikzpicture\}
}

\end{tikzpicture} 
\end{thinmargin}

Instead of operator |--| we can use operator |to| \oarg{\TikZ{} options} to draw a path from 
\parg{annotation label} to \parg{code part}. Finally we can remove the command 
|\draw[code grid debug]...| at the begin of the |tikzpicture|.
The final result is shown in the figure~\ref{fig:function-final}, which is almost the same
as figure~\ref{fig:tut1-function}.

\begin{figure}[ht]
\centering 
\begin{tikzpicture}[remember picture]
\codeBlock{%
\cPart{functionHead} {function \cPart{functionName}{gcd} \cPart{paramList}{(p, q)}} \{
\\[2.5pt]
\ptab{}\mtPoint{mostLeft}if (q === 0) \{ \\
\ptab\ptab{} return p; \\
\ptab\} else \{ \\
\ptab\ptab{} return gcd(q, p\%q);\extremPoint{mostRight} \\
\ptab\mbPoint{mostBottom}\} \\
\}
}
\fitExtrem{functionBody}{(mostLeft) (mostRight) (mostBottom)}
% Annotations
\codeAnnotation{functionHeadText}(-1,3){Function\\head}
\codeAnnotation{functionBodyText}(-1,1){Function\\body}
\codeAnnotation{functionNameText}( 1,4){Function\\name}
\codeAnnotation{paramListText} ( 3,4){Parameter\\list}
% Annotation labels to code parts
\draw[->,annotation] (functionHeadText)  -- (functionHead);
\draw[->,annotation] (functionBodyText)  -- (functionBody);
\draw[->,annotation] (functionNameText)  -- (functionName);
\draw[->,annotation] (paramListText) --  (paramList);
\end{tikzpicture}
     
\caption{Function with Annotation Labels\label{fig:function-final}}
\end{figure}

\section{Usage in conjuntion with \pkg{listings}}

As we see in the previous section, the command |\codeBlock| cannot typeset whitespaces correctly as we 
expect. A way to typeset code listing is using the package \pkg{listings}. See \texttt{codeanatomy.lstlisting.pdf}


\section{Customize style}
TODO

\end{documentation}
\end{document}