diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/codeanatomy/codeanatomy.usage.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/codeanatomy/codeanatomy.usage.tex | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/codeanatomy/codeanatomy.usage.tex b/Master/texmf-dist/doc/latex/codeanatomy/codeanatomy.usage.tex new file mode 100644 index 00000000000..5136905babb --- /dev/null +++ b/Master/texmf-dist/doc/latex/codeanatomy/codeanatomy.usage.tex @@ -0,0 +1,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} + |