From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- graphics/pgf/contrib/codeanatomy/README.md | 64 +++ graphics/pgf/contrib/codeanatomy/codeanatomy.dtx | 532 ++++++++++++++++++ graphics/pgf/contrib/codeanatomy/codeanatomy.ins | 62 +++ .../contrib/codeanatomy/codeanatomy.lstlisting.pdf | Bin 0 -> 123921 bytes .../contrib/codeanatomy/codeanatomy.lstlisting.tex | 594 +++++++++++++++++++++ graphics/pgf/contrib/codeanatomy/codeanatomy.pdf | Bin 0 -> 97601 bytes .../pgf/contrib/codeanatomy/codeanatomy.usage.pdf | Bin 0 -> 82738 bytes .../pgf/contrib/codeanatomy/codeanatomy.usage.tex | 383 +++++++++++++ graphics/pgf/contrib/codeanatomy/literatur.bib | 8 + 9 files changed, 1643 insertions(+) create mode 100644 graphics/pgf/contrib/codeanatomy/README.md create mode 100644 graphics/pgf/contrib/codeanatomy/codeanatomy.dtx create mode 100644 graphics/pgf/contrib/codeanatomy/codeanatomy.ins create mode 100644 graphics/pgf/contrib/codeanatomy/codeanatomy.lstlisting.pdf create mode 100644 graphics/pgf/contrib/codeanatomy/codeanatomy.lstlisting.tex create mode 100644 graphics/pgf/contrib/codeanatomy/codeanatomy.pdf create mode 100644 graphics/pgf/contrib/codeanatomy/codeanatomy.usage.pdf create mode 100644 graphics/pgf/contrib/codeanatomy/codeanatomy.usage.tex create mode 100644 graphics/pgf/contrib/codeanatomy/literatur.bib (limited to 'graphics/pgf/contrib/codeanatomy') diff --git a/graphics/pgf/contrib/codeanatomy/README.md b/graphics/pgf/contrib/codeanatomy/README.md new file mode 100644 index 0000000000..32d85cfa5b --- /dev/null +++ b/graphics/pgf/contrib/codeanatomy/README.md @@ -0,0 +1,64 @@ +`codeanatomy` -- Draw Code Anatomy +================================== + +(C) 2019 Hồng-Phúc Bùi + +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 idea is +code illustrations in the texbook _Computer Science An Interdisciplinary Approach_ +from Robert Sedgewick and Kevin Wayne. + +This package just provides tools to draw those figures. + +Some illustrations can be found here: + +https://introcs.cs.princeton.edu/java/home/ + +for example the origin illustation of static method in java: + + + +Licence +------- + +This package may be distributed and/or modified under the conditions of the +LaTeX Project Public License (LPPL), either version 1.3c of this +License or any later version. The latest version +of this license is in the file https://www.latex-project.org/lppl.txt + +Build and Install (for Distributor) +----------------------------------- + +* To build the style file `codeanatomy.sty` just run **one** of + +``` +latex codeanatomy.ins +pdflatex codeanatomy.ins +xelatex codeanatomy.ins +lualatex codeanatomy.ins +``` + +then you can copy `codeanatomy.sty` to your local `texmf` tree, where latex can find it. + +* To create PDF Document manual you must use `lualatex` + +``` +lualatex codeanatomy.dtx +lualatex codeanatomy.usage.tex +lualatex codeanatomy.lstlisting.tex +``` + +(`lualatex` because of my name, really ego right! It needs unicode to be typeset correctly.) + +Development +----------- + +I try to use latex3 as much as posible. You can use + +``` +l3build doc +``` + +to create the style file and documentation files at once. You can also (like I also do) use `make` +to call repeatly tasks. + diff --git a/graphics/pgf/contrib/codeanatomy/codeanatomy.dtx b/graphics/pgf/contrib/codeanatomy/codeanatomy.dtx new file mode 100644 index 0000000000..4651dadeaa --- /dev/null +++ b/graphics/pgf/contrib/codeanatomy/codeanatomy.dtx @@ -0,0 +1,532 @@ +% \iffalse meta-comment +% +% File: codeanatomy.dtx Copyright (C) 2019 Hong-Phuc Bui +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file +% +% https://www.latex-project.org/lppl.txt +% +% +% ----------------------------------------------------------------------- +% +% The development version of the bundle can be found at +% +% https://github.com/hpb-htw/codeanatomy +% +% for those people who are interested. +% +% ----------------------------------------------------------------------- +% \fi +% +% \iffalse +%\NeedsTeXFormat{LaTeX2e}[2018/12/01] +%\ProvidesPackage{codeanatomy}[2019/07/12 v0.4-Alpha draw Code Anatomy] +% \fi +% +% \iffalse +%<*driver> +\documentclass[full]{l3doc} + +\usepackage{fontspec} +\usepackage{luaotfload} + + +\usepackage{biblatex} +\addbibresource{literatur.bib} +\newcommand{\slsh}{\textbackslash{}} +\newcommand{\TikZ}{Ti\textit{k}Z} +\newcommand{\fixedBug}[1]{\tikz[baseline=(X.base)]\node[cross out,draw] (X) {#1};} +\def\thinmargin{\list{}{\rightmargin-50pt\leftmargin-90pt}\item[]} +\let\endthinmargin=\endlist + +\usepackage{listings} +\lstset { + basicstyle=\small\ttfamily + ,escapeinside={+}{+} +} + +\usepackage{codeanatomy} +\EnableCrossrefs +\CodelineIndex +\RecordChanges + +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +% +% \fi +% +% \GetFileInfo{\jobname.sty} +% \DoNotIndex{\definecolor, \colorlet} +% \DoNotIndex{\NewDocumentCommand, \node} +% \DoNotIndex{\phantom} +% \DoNotIndex{\RequirePackage, \rule} +% \DoNotIndex{\small, \sffamily} +% \DoNotIndex{\textcolor, \tikzmarknode, \tikzset, \ttfamily} +% \DoNotIndex{\usetikzlibrary} +% +% \title{^^A +% \pkg{codeanatomy} -- Draw Code Anatomy^^A +% \thanks{This file describes \fileversion, ^^A +% last revised \filedate.}\\[1ex]^^A +% \normalsize{Reference}^^A +% }^^A +% +% \author{^^A +% Hồng-Phúc Bùi^^A +% \thanks{^^A +% E-mail: +% \href{mailto:Hồng-Phúc Bùi} +% {hong-phuc.bui (at) htwsaar dot de}^^A +% }^^A +% } +% +% \date{Released \filedate} +% +% \parindent0pt +% +% \maketitle +% \tableofcontents +% +% \section{Hints} +% Usage of this Package can be found in \texttt{codeanatomy.usage.pdf} and \texttt{codeanatomy.lstlisting.pdf}. +% This document show only generated reference of commands in this Package. +% + +% ^^A %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \section{Implementation} +% +% \changes{v0.2-Alpha} +% {2019/07/10} +% {This package does not load \pkg{xcolor} anymore. +% It relies on \pkg{tikz}, that \pkg{tikz} loads \pkg{xcolor} +% in a way that \pkg{codeanatomy} can define RGB color} +% +% +% \subsection{Package Dependenies} +% +% \begin{macrocode} +\RequirePackage{expl3} +\RequirePackage{xparse} +\RequirePackage{tikz} +% \end{macrocode} +% +% Load necsessary \TikZ{} libraries. +% \begin{macrocode} +\usetikzlibrary{ + tikzmark + ,fit + ,arrows.meta + ,bending + ,shapes + ,chains + ,backgrounds + ,scopes + ,decorations + ,decorations.pathmorphing +} +% \end{macrocode} +% +% \subsection{Setup styles} +% ^^A+++++++++++++++++++++ +% \subsubsection{Colors} +% ^^A------------------- +% Define colors which are used in \pkg{codeanatomy} + +% \DescribeMacro{annotationcolor} +% \tikz{\draw[fill=annotationcolor] circle(1ex); } +% \begin{macrocode} +\definecolor{annotationcolor} + {rgb}{0,0.50002,1} % Blue +% \end{macrocode} +% +% \DescribeMacro{bgcmdcolor} +% \tikz{\draw[fill=bgcmdcolor] circle(1ex); } +% \begin{macrocode} +\colorlet{bgcmdcolor}{gray} % Grey +% \end{macrocode} +% +% \subsubsection{\TikZ{} styles for code in a Code Anatomy} +% ^^A------------------------------------------------------ +% +% \DescribeMacro{anatomy} +% \TikZ{} style for annotation labels: \\ +% |\tikz{\node(code) [anatomy] at (0,0) {code line 1\\code line 2}; }|\\ +% yields \tikz{\node(code) [anatomy] at (0,0) {code line 1\\code line 2}; } +% \begin{macrocode} +\tikzset{anatomy/.style={% + anchor=south west,% + inner sep=0,% + align=left,% + font=\ttfamily + } +} +% \end{macrocode} +% +% +% +% \DescribeMacro{code part} +% \TikZ{} style to marce a piece of code in an anatomy: \\ +% |\tikz{\node(code) [code part] at (0,0) {let a = 12;};}|\\ +% yields \tikz{\node(code) [code part] at (0,0) {let a = 12;};} +% \begin{macrocode} +\tikzset{code part/.style={% + rectangle,% + draw=annotationcolor,% + align=left,% + minimum height=1.175em,% + inner sep=1.75pt,% + outer sep=0.1pt,% + font=\ttfamily + } +} +% \end{macrocode} +% +% +% +% \DescribeMacro{fit extrem} +% \TikZ{} style to mark a piece of multiple line code in an anatomy:\\ +% |\tikz{ \node(c)[fit extrem, fit={(0,0) (0.5,0.975) (1,0)}] {}; }|\\ +% yields \tikz{ \node(c)[fit extrem, fit={(0,0) (0.5,0.975) (1,0)}] {}; } +% \begin{macrocode} +\tikzset{fit extrem/.style={% + rectangle,% + draw=annotationcolor,% + align=left,% + minimum height=1.175em,% + inner sep=1.75pt,% + outer sep=0.1pt,% + font=\ttfamily + } +} +% \end{macrocode} +% +% +% +% +% \DescribeMacro{annotation} +% \TikZ{} style of arrows from annotation labels to code parts:\\ +% |\tikz{\draw[] (1,0) circle(3ex); \draw[->,annotation] (0,0) -- (1,0);}|\\ +% yields +% \tikz{\draw[] (1,0) circle(3ex); \draw[->,annotation] (0,0) -- (1,0);} +% +% \changes{v0.4-Alpha} +% {2019/07/12} +% {Set \texttt{fill} to \texttt{annotationcolor} explicit for arrow style} +% +% \begin{macrocode} +\tikzset{annotation/.style={% + preaction={ + draw=white,% + line width=3.5pt,% + arrows={-Triangle Cap[]},% + },% + draw=annotationcolor,% + arrows={-Latex[% + round,% + color=annotationcolor, + fill=annotationcolor + ] + }, + shorten >=0.25pt + } +} +% \end{macrocode} +% +% +% \DescribeMacro{code annotation} +% \TikZ{} style for a annotation label \tikz{\node(a)[code annotation] at (0,0) {function name};} +% \begin{macrocode} +\tikzset{code annotation/.style={% + inner sep=2pt,% + text=annotationcolor,% + align=center,% + font=\sffamily\small + } +} +% \end{macrocode} +% +% +% +% \DescribeMacro{code grid debug} +% \TikZ{} style to draw debug grid on the background of anatomy +% \begin{macrocode} +\tikzset{code grid debug/.style={% + step=1.0,% + draw=gray!20,% + very thin,% + on background layer + } +} +% \end{macrocode} +% +% +% ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% +% \subsection{Command used to set code and code anatomy} +% ^^A--------------------------------------------------- +% +% +% \DescribeMacro{\codeBlock} \marg{code} +% +% Complete code listing of a Code Anatomy figure is typeset by this command. +% Whereas \marg{code} is the \emph{formatted} code listing. +% This command can be used if there are no other packages to typeset code listing in use. +% \begin{macrocode} +\NewDocumentCommand{\codeBlock}{m}% + {\node(code) [anatomy] at (0,0) {#1};} +% \end{macrocode} +% +% +% +% \DescribeMacro{\cPart} \marg{node name}\marg{piece of code} +% +% Assign a piece of typeset code --typical in one line-- to a \TikZ{} Node, so that it can +% be annotated. +% \begin{itemize} +% \item \marg{node name} is a unique \TikZ{} node name in the |tikzpicture| +% \item \marg{piece of code} is a single code part to be marked. +% \end{itemize} +% \begin{macrocode} +\NewDocumentCommand{\cPart}{mm} % + {\tikzmarknode[code part]{#1}{#2}} +% \end{macrocode} +% +% +% +% \DescribeMacro{\iPart} \marg{node name}\marg{piece of code} +% +% Assign a piece of typeset code --typical in one line-- to a \TikZ{} Node, so that it can +% be annotated. It does not plot border around the pice of code as |\cPart| does. +% \begin{itemize} +% \item \marg{node name} is a unique \TikZ{} node name in the |tikzpicture| +% \item \marg{piece of code} is a single code part to be marked. +% \end{itemize} +% \begin{macrocode} +\NewDocumentCommand{\iPart}{mm} % + {\tikzmarknode[code part,draw=none,inner sep=0.75pt]{#1}{#2}} +% \end{macrocode} +% +% +% +% +% \DescribeMacro{\mtPoint}\marg{node name} +% +% Marks a point as a \textbf{m}ost \textbf{t}op in a Code Block. +% \begin{macrocode} +\NewDocumentCommand{\mtPoint}{m} + {\tikzmarknode{#1}{\phantom{\rule[1.8ex]{0.1ex}{0.1ex}}}} +% \end{macrocode} +% +% +% +% \DescribeMacro{\hmtPoint}\marg{node name} +% +% Marks a point as a \textbf{h}eigher \textbf{m}ost \textbf{t}op point in a Code Block. +% \begin{macrocode} +\NewDocumentCommand{\hmtPoint}{m} + {\tikzmarknode{#1}{\phantom{\rule[2.5ex]{0.1ex}{0.1ex}}}} +% \end{macrocode} +% +% +% +% \DescribeMacro{\mbPoint}\marg{node name} +% +% Marks a point as a \textbf{d}eeper \textbf{m}ost \textbf{b}ottom point in a Code Block. +% \begin{macrocode} +\NewDocumentCommand{\mbPoint}{m} + {\tikzmarknode{#1}{\phantom{\rule[-0.55ex]{0.1ex}{0.1ex}}}} +% \end{macrocode} +% +% +% +% \DescribeMacro{\dmbPoint}\marg{node name} +% +% Marks a point as a \textbf{d}eeper \textbf{m}ost \textbf{b}ottom point in a Code Block. +% \begin{macrocode} +\NewDocumentCommand{\dmbPoint}{m} + {\tikzmarknode{#1}{\phantom{\rule[-2ex]{0.1ex}{0.1ex}}}} +% \end{macrocode} +% +% +% \DescribeMacro{\extremPoint}\marg{node name}\oarg{yshift}\oarg{xshift}\oarg{style} +% +% Create a \TikZ{} Node as reference point for later use in |\fitExtrem|. +% +% \begin{itemize} +% \item \marg{node name} is the \TikZ{} node name which is used in |\fitExtrem| to reference to this point +% \item \oarg{yshift} a length, default 0ex which places this markpoint on the base line, +% shift this mark point vertical, for positive value over base line, negative value under +% base line. +% \item \oarg{xshift} same as \oarg{yshift} but for horizontal direction. +% \item \oarg{style} is a \TikZ{} style (may be defined by user). +% \end{itemize} +% +% For example: +% +% |\begin{tikzpicture}[remember picture]|\\ +% |\node(code) [anatomy] at (0,0) {|\\ +% | \extremPoint{tl}[2ex]Line with some text\extremPoint{br}[-1ex]\\|\\ +% | \extremPoint{tl2}other Line with some text\\|\\ +% | some more line\extremPoint{br2}\\|\\ +% |};|\\ +% |\fitExtrem{box1}{(tl) (br)}|\\ +% |\fitExtrem{box2}{(tl2) (br2)}|\\ +% |\end{tikzpicture}|\\ +% +% yields\\ +% +% \begin{tikzpicture}[remember picture] +% \node(code) [anatomy] at (0,0) { +% \extremPoint{tl}[2ex]Line with some text\extremPoint{br}[-1ex]\\ +% \extremPoint{tl2}other Line with some text\\ +% some more line\extremPoint{br2}\\ +% }; +% \fitExtrem{box1}{(tl) (br)} +% \fitExtrem{box2}{(tl2) (br2)} +% \end{tikzpicture} +% \begin{macrocode} +\NewDocumentCommand{\extremPoint}{m O{0ex} O{0.1ex} O{} } + {\tikzmarknode[#4]{#1}{\phantom{\rule[#2]{#3}{0.1ex}}}} +% \end{macrocode} +% +% +% +% +% \DescribeMacro{\fitExtrem} \marg{node name}\marg{extrem points} +% +% Create a rectangle box over given extrem points defined by |\*Point{}|. +% +% \begin{itemize} +% \item \marg{node name} is a unique \TikZ{} node name in the current anatomy +% \item \marg{extrem points} is a list of \TikZ{} node name created by |\*Point|, +% each name is surrounded by |()|. +% \end{itemize} +% +% Example: +% +% |\begin{tikzpicture}[remember picture]|\\ +% |\node(code) [anatomy] at (0,0) {|\\ +% |\mtPoint{left}Line 1\\|\\ +% |Long Line 2\extremPoint{right}\\|\\ +% |Line 3\mbPoint{bottom}|\\ +% |};|\\ +% |\fitExtrem{box} { (left) (bottom) (right) }|\\ +% |\end{tikzpicture}|\\ +% +% yields\\ +% +% \begin{tikzpicture}[remember picture] +% \node(code) [anatomy] at (0,0) { +% \mtPoint{left}Line 1\\ +% Long Line 2\extremPoint{right}\\ +% Line 3\mbPoint{bottom} +% }; +% \fitExtrem{box} { (left) (bottom) (right) } +% \end{tikzpicture} +% \begin{macrocode} +\NewDocumentCommand{\fitExtrem}{mm} + {\node(#1)[fit extrem,fit={#2}]{};} +% \end{macrocode} +% +% +% \DescribeMacro{\bgcode} \marg{piece of code} +% +% Typeset a piece of code in color |bgcmdcolor|. +% For example +% +% |\tikz{\codeBlock{let a := 12\bgcode{;}}}| +% +% yields \tikz{\codeBlock{let a := 12\bgcode{;}}} +% \begin{macrocode} +\NewDocumentCommand{\bgcode}{m}{\textcolor{bgcmdcolor}{#1}} +% \end{macrocode} +% +% +% \DescribeMacro{\ptab} +% \DescribeMacro{\phspace} +% Produce a horizontal space of 4 small characters |h| respective 1 small character |h|\\ +% for example: |\tikz{\codeBlock{a\ptab{}b}}| yields \tikz{\codeBlock{a\ptab{}b}} +% \begin{macrocode} +\NewDocumentCommand{\ptab}{}{\phantom{hhhh}} +\NewDocumentCommand{\phspace}{}{\phantom{h}} +% \end{macrocode} +% +% +% +% \DescribeMacro{\codeAnnotation}\marg{node name}\parg{coordinate}\marg{label text} +% +% Typeset Annotation labels for a code part. +% \begin{itemize} +% \item \marg{node name} is a unique \TikZ{} node name in the |tikzpicture|, +% \item \parg{coordinate} is the coordinate of the annotation label, surrounded by a |()|, +% \item \marg{label text} text content to be typeset. +% \end{itemize} +% +% For example: +% +% |\begin{tikzpicture}[remember picture]|\\ +% |\codeBlock{a \cPart{a}{:=} 12 + 13}|\\ +% |\codeAnnotation{codeLabel} (1,-0.5) {assignment}|\\ +% |\draw[->,annotation] (codeLabel) -- (a);|\\ +% |\end{tikzpicture}|\\ +% +% yields\\ \medskip +% +% \begin{tikzpicture}[remember picture] +% \codeBlock{a \cPart{a}{:=} 12 + 13} +% \codeAnnotation{codeLabel} (1,-0.5) {assignment} +% \draw[->,annotation] (codeLabel) -- (a); +% \end{tikzpicture} +% \begin{macrocode} +\NewDocumentCommand{\codeAnnotation}{m r() m } % + { \node(#1)[code annotation] at (#2) {#3}; } +% \end{macrocode} +% +% +% +% +% ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \section{Known Bugs} +% +% \paragraph*{\fixedBug{Arrows color}} +% Arrows appear in some cases with mysterious color. I don't know why! +% For example: +% +% |\begin{tikzpicture}[remember picture]|\\ +% |\node(code) [anatomy] at (0,0) {|\\ +% |\hmtPoint{a}Short line\\|\\ +% |code with some long text\extremPoint{b}[-0.5ex]|\\ +% |};|\\ +% |\fitExtrem{l}{(a) (b)}|\\ +% |\codeAnnotation{n} (-2,0){here is|\\ +% | a\extremPoint{point}[0.75ex][0.5ex]|\\ +% | long line}|\\ +% |\draw[->, annotation] (point) -- (l);|\\ +% |\end{tikzpicture}| +% +% yields +% +% \begin{tikzpicture}[remember picture] +% \node(code) [anatomy] at (0,0) { +% \hmtPoint{a}Short line\\ +% code with some long text\extremPoint{b}[-0.5ex] +% }; +% \fitExtrem{l}{(a) (b)} +% \codeAnnotation{n} (-2,0){here is\\ +% a\extremPoint{point}[0.75ex][0.5ex]\\ +% long line} +% \draw[->, annotation] (point) -- (l); +% \end{tikzpicture} +% +% +% ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \PrintIndex +% \PrintChanges +% +\endinput + diff --git a/graphics/pgf/contrib/codeanatomy/codeanatomy.ins b/graphics/pgf/contrib/codeanatomy/codeanatomy.ins new file mode 100644 index 0000000000..6a04a9d154 --- /dev/null +++ b/graphics/pgf/contrib/codeanatomy/codeanatomy.ins @@ -0,0 +1,62 @@ +\iffalse meta-comment + +File: codeanatomy.ins Copyright (C) 2019 by Me + +It may be distributed and/or modified under the conditions of the +LaTeX Project Public License (LPPL), either version 1.3c of this +license or (at your option) any later version. The latest version +of this license is in the file + + https://www.latex-project.org/lppl.txt + + +The released version of this bundle is available from CTAN. + +----------------------------------------------------------------------- + +The development version of the bundle can be found at + + https://github.com/(TODO) + +for those people who are interested. + +----------------------------------------------------------------------- + +\fi + +\input l3docstrip.tex +\askforoverwritefalse +\usedir{tex/latex/codeanatomy} +% stop DocStrip adding rather wordy text +\preamble +\endpreamble +\postamble +Copyright (C) 2008-2019 by + ME + +It may be distributed and/or modified under the conditions of +the LaTeX Project Public License (LPPL), either version 1.3c of +this license or (at your option) any later version. The latest +version of this license is in the file: + + https://www.latex-project.org/lppl.txt + + +This work consists of the files codeanatomy.dtx, + codeanatomy.ins, + and the derived files codeanatomy.pdf, + codeanatomy.sty. + +\endpostamble + +\keepsilent + +\generate {% + \file{codeanatomy.sty} {% + \from{codeanatomy.dtx}{package} + } +} + +\endbatchfile + + diff --git a/graphics/pgf/contrib/codeanatomy/codeanatomy.lstlisting.pdf b/graphics/pgf/contrib/codeanatomy/codeanatomy.lstlisting.pdf new file mode 100644 index 0000000000..4279660c8c Binary files /dev/null and b/graphics/pgf/contrib/codeanatomy/codeanatomy.lstlisting.pdf differ diff --git a/graphics/pgf/contrib/codeanatomy/codeanatomy.lstlisting.tex b/graphics/pgf/contrib/codeanatomy/codeanatomy.lstlisting.tex new file mode 100644 index 0000000000..b8956cea22 --- /dev/null +++ b/graphics/pgf/contrib/codeanatomy/codeanatomy.lstlisting.tex @@ -0,0 +1,594 @@ +\documentclass[full]{l3doc} + +\usepackage{fontspec} +\usepackage[backend=biber]{biblatex} +\addbibresource{literatur.bib} + +\usepackage{codeanatomy} + +\usepackage{listings} +\lstset { + basicstyle=\small\ttfamily% + ,language=% + ,escapeinside={!}{!}% + ,resetmargins=true% + ,columns=flexible% + ,literate={-}{-}1% + ,keepspaces=true +} + +\def\thinmargin{\list{}{\rightmargin-30pt\leftmargin-70pt}\item[]} +\let\endthinmargin=\endlist + +\usepackage{filecontents} + +% others shortcuts +\newcommand{\slsh}{\textbackslash{}} +\newcommand{\TikZ}{Ti\textit{k}Z} +\newcommand{\inputlisting}[1]{% +\lstinputlisting[% + basicstyle=\footnotesize\ttfamily% + ,xleftmargin=-70pt% + ,resetmargins=true% + ,firstline=5% + ,language=% + ,columns=flexible% + ,escapeinside={}{}% + ]{#1}% +} + +\usepackage{hyperref} + +\GetFileInfo{codeanatomy.sty} +\DoNotIndex{} + +\title{ + \pkg{codeanatomy} -- Draw Code Anatomy% + \thanks{This file describes \fileversion, + last revised \filedate.}\\\vspace*{2ex} + \normalsize{Usage with \pkg{listings}} +} + +\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 +} + +\begin{document} + +\maketitle +\tableofcontents + +\section{General Usage in Conjuntion with Package \pkg{listings}} +\subsection{Setup Package \pkg{listings}} +The most important setup for the package \pkg{listings} is the delimiter to escape \LaTeX{} +commands in Listing. With this escape delimiter we can mark a piece of code as with |\cPart|. +In this example we use |!| and |!| as delimiter. Code between |!| and |!| is evaluated as +\LaTeX{}-code. + +\lstset { + escapeinside={+}{+} +} +\begin{thinmargin} +\begin{tikzpicture}[remember picture] +% {[on background layer]\draw[code grid debug] (-3.5,-0.5) grid (5.5,4.5);} +\node(code) [anatomy] at (0,0){% +\begin{lstlisting} +\usepackage{codeanatomy} +\usepackage{listings} +\lstset { + basicstyle=\small\ttfamily + ,escapeinside=+\cPart{delimiter}{\{!\}\{!\}}+ +} +\end{lstlisting} +}; +\codeAnnotation{delimiterText} (4,-0.5) {Setup \texttt{!} and \texttt{!}\\as delimiter} + +\draw[->, annotation] (delimiterText) -- (delimiter); +\end{tikzpicture} +\end{thinmargin} + + +Delimiter can also be reset in |document|-Environment, typical just before a new \verb:\begin{lstlisting}: +environment so each anatomy can have different delimiter. The fact is, in this document I use |+| and |+| for +the above listing, so that I can typeset |!| in this listing. + +\subsection{Typeset Code} +The command |\codeBlock| does not work if the environment |lstlisting| is passed to its argument. So instead of +|\codeBlock| we must use the \TikZ{} command |\node|: + +\begin{thinmargin} +\begin{tikzpicture}[remember picture] +\node(code) [anatomy] at (0,0) { +\begin{lstlisting} +\begin{tikzpicture}[remember picture] ++\cPart{tikzNode}{\slsh{}node(code) [anatomy] at (0,0)}+ { ++\cPart{listingBegin}{\texttt{\slsh{}begin\{lstlisting\}}}\vspace{1.5pt}+ ++\mtPoint{mostLeft}+function gcd(p,q) { + if (q === 0) { + return q; + }else{ + let r = p % q; + return gcd(q, r);+\extremPoint{mostRight}+ + } +}+\mbPoint{mostBottom}+ ++\cPart{listingEnd}{\texttt{\slsh{}end\{lstlisting\}}}+ +}+\cPart{semiColon}{;}+ +\end{tikzpicture} +\end{lstlisting} +}; + +\fitExtrem{listingContent}{(mostLeft) (mostRight) (mostBottom)} + +% Annotations +\codeAnnotation{tikzNodeText} (-2, 5.5) {use \texttt{\slsh{}node}\\instead of\\\texttt{\slsh{}codeBlock}} +\codeAnnotation{listingText} (-2, 3) {typeset code\\in\\\texttt{lstlisting}\\environment} +\codeAnnotation{listingContentText} (6.5, 3) {whitespaces\\in code\\are kept} +\codeAnnotation{semiColonText} (6.5, 0.6) {don't forget\\semicolon} + +% Arrows from labels to code parts +\draw[->,annotation] (tikzNodeText) -- (tikzNode.west); +\draw[->,annotation] (listingText) -- (listingBegin.west); +\draw[->,annotation] (listingText) -- (listingEnd.west); +\draw[->,annotation] (listingContentText) -- (listingContent); +\draw[->,annotation] (semiColonText) -- (semiColon); +\end{tikzpicture} +\end{thinmargin} + +Figure~\ref{fig:full-formatted-code} shows result of the above code. + +\begin{figure}[ht] +\centering +\begin{tikzpicture}[remember picture] +\node(code) [anatomy] at (0,0) { +\begin{lstlisting} +function gcd(p,q) { + if (q === 0) { + return q; + }else{ + let r = p % q; + return gcd(q, r) + } +} +\end{lstlisting} +}; +\end{tikzpicture} +\caption{Code Listing is formatted\label{fig:full-formatted-code}} +\end{figure} + +\subsection{Mark Code} +% -------------------- + +The command |\cPart| can be used to mark single-line code parts. For +multiple-line code parts once can use |\extremPoint| to mark the outer most +points of code parts and |\fitExtrem| to cover exterm points of a code part. +These commmands must be put in delimiter, here |!| and |!|. + +\begin{thinmargin} +\begin{tikzpicture}[remember picture] +\node(code) [anatomy] at (0,0) { +\begin{lstlisting} +\begin{tikzpicture}[remember picture] +\node(code) [anatomy] at (0,0) { ++\texttt{\slsh{}begin\{lstlisting\}}+ +!\cPart{fnHead}{function \cPart{fnName}{gcd}\cPart{paramList}{(p,q)}}! { + +\cPart{ep1}{!\slsh{}mtPoint\{mostLeft\}!}+if (q === 0) { + return q; + }else{ + +\cPart{cp}{!\slsh{}cPart\{localVar\}\{let r\}!}+ = p % q; + return gcd(q, r);+\cPart{ep2}{!\slsh{}extremPoint\{mostRight\}!}+ + }+\cPart{ep3}{!\slsh{}mbPoint\{mostBottom\}!}+ +} ++\texttt{\slsh{}end\{lstlisting\}}+ +}; +\fitExtrem{fnBody}{(mostLeft) (mostRight) (mostBottom)} +\end{tikzpicture} +\end{lstlisting} +}; +% Annotations +\codeAnnotation{epText} (11,2.5) {\texttt{extremPoint}-s mark\\outer most\\of the function body} +\codeAnnotation{cpText} (-2,3) {\texttt{cPart} marks a\\single line\\code part} +% Arrows +\draw[->,annotation] (epText) -- (ep1.south east); +\draw[->,annotation] (epText) -- (ep2.east); +\draw[->,annotation] (epText) -- (ep3.south east); +\draw[->,annotation] (cpText) -- (cp); +\end{tikzpicture} +\end{thinmargin} + +Figure~\ref{fig:listing-code-parts} shows the result of the above code. + +\begin{figure}[ht] +\centering +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[remember picture] +\node(code) [anatomy] at (0,0) { +\begin{lstlisting} +!\cPart{fnHead}{function \cPart{fnName}{gcd}\cPart{paramList}{(p,q)}}! { + !\mtPoint{mostLeft}!if (q === 0) { + return q; + }else{ + !\cPart{localVar}{let r}! = p % q; + return gcd(q, r);!\extremPoint{mostRight}! + }!\mbPoint{mostBottom}! +} +\end{lstlisting} +}; +\fitExtrem{fnBody}{(mostLeft) (mostRight) (mostBottom)} +\end{tikzpicture} +\caption{Code Listing with mark of code parts\label{fig:listing-code-parts}} +\end{figure} + +\subsection{Add Annotations to Listing} +% ------------------------------------- +This step is the same as the description in the main document of package \pkg{codeanatomy}. +Readers can typeset annotations to the above listing like an exercise. + + + + + + +\section{Some examples} +% ==================== +% Reset to standard + +Most of examples in this section are redrawn from the textbook~\autocite{sedgewick-wayne-2016}. + +\subsection{Anatomy of a Java Program~\autocite[5]{sedgewick-wayne-2016}} +% ----------------------------------- + +\begin{filecontents}{java-program.tex} +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[remember picture] +\node(code) [anatomy] at (0,0){% +\begin{lstlisting} +public !\iPart{class}{class}! !\cPart{className}{HelloWorld}! +{ + !\mtPoint{mainLeft}!public static void main(String[] argv) + { + !\hmtPoint{left}\iPart{assign}{ + \bgcode{// Prints "Hello World" in the terminal window}} + \extremPoint{fnR} \extremPoint{mR}! + !\iPart{fnCall}{System.out.print( "Hello World");}\dmbPoint{mostBottom}! + }!\mbPoint{mainBottom}! +} +\end{lstlisting} +}; + +\fitExtrem{classBody}{(mainLeft) (mR) (mainBottom)} +\fitExtrem{functionBody}{(left) (fnR) (mostBottom)} + + +\codeAnnotation{fileNameText} (1.5,5) {text file named \texttt{HelloWorld.java}} +\codeAnnotation{classNameText} (3.5,4.25) {name} +\codeAnnotation{classBodyText} (6.5,3.6) {\texttt{main()} method} +\codeAnnotation{functionBodyText} (2.5,-0.5) {body} +\codeAnnotation{statement} (8,0) {statements} + +\draw[->,annotation] (fileNameText) -- (class); +\draw[->,annotation] (classNameText) -- (className); +\draw[->,annotation] (classBodyText.south west) -- (classBody); +\draw[->,annotation] (functionBodyText) -- (functionBody); +\draw[->,annotation] (statement) -- (assign.353); +\draw[->,annotation] (statement) -- (fnCall.350); +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} +\inputlisting{java-program.tex} +\end{thinmargin} + +\input{java-program.tex} + +\subsection{Anatomy of an expression~\autocite[17]{sedgewick-wayne-2016}} +% ----------------------------------- + +\begin{filecontents}{java-expression.tex} +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[remember picture] +\codeBlock{\cPart{op1}{4} \cPart{op}{*} \cPart{op2}{( x - 3 )} } + +\codeAnnotation{operand} (1,1.5) {operands\\(and expression)} +\codeAnnotation{operator} (0.7,-1) {operator} + +\draw[->,annotation] (operand) -- (op1.north); +\draw[->,annotation] (operand) -- (op2.north); +\draw[->,annotation] (operator) -- (op.south); +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} + \inputlisting{java-expression.tex} +\end{thinmargin} + +\input{java-expression.tex} + +\subsection{Using a primitive Data Type~\autocite[17]{sedgewick-wayne-2016}} +% ------------------------------------- + +\begin{filecontents}{using-a-primitive-data-type.tex} +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[ + remember picture % + ,code annotation/.append style = { % customize style of annotation text + font=\sffamily\footnotesize + } +] +{[on background layer]\draw[code grid debug] (-2.5,-0.5) grid (2.5,2.5);} +\node(code) [anatomy] at (0,0){% +\begin{lstlisting} +!\cPart{d}{int a, b;}! +!\iPart{v}{a}! = !\cPart{l}{1234}!; +!\iPart{a}{b = 99}!; +!\cPart{i}{int c = a + b}!; +\end{lstlisting} +}; +% Annotations +\codeAnnotation{declareText} ( 1,2.75 ) {declaration statement} +\codeAnnotation{literalText} ( 2.5,1.45) {literal} +\codeAnnotation{varText} (-1.5,1.75 ) {variable name} +\codeAnnotation{assignText} (-1.5,0.75 ) {assignment\\statement} +\codeAnnotation{initText} (-1.5,-0.75) {inline initialization\\statement} +% Arrows +\draw[->,annotation] (declareText) -- (d); +\draw[->,annotation] (literalText) -- (l); +\draw[->,annotation] (varText.south east) -- (v); +\draw[->,annotation] (assignText) -- (a); +\draw[->,annotation] (initText) -- (i.south west); +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} + \inputlisting{using-a-primitive-data-type.tex} +\end{thinmargin} + +\input{using-a-primitive-data-type.tex} + +\subsection{Anatomy of a method signature~\autocite[30]{sedgewick-wayne-2016}} +% --------------------------------------- + +\begin{filecontents}{anatomy-of-a-method-signature.tex} +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[remember picture] +\node(code) [anatomy] at (0,0) { +\begin{lstlisting} +public class !\iPart{l}{Math}! + .... + !\cPart{s}{\bgcode{static} \iPart{r}{double} \iPart{n}{sqrt}(\iPart{a}{double} a)}! + .... +\end{lstlisting} +}; +% Annotation +\codeAnnotation{lText} (3,2.5) {library name} +\codeAnnotation{sText} (-1,1) {signature} +\codeAnnotation{nText} (4.5,1.5) {method name} +\codeAnnotation{rText} (2.0,-0.51) {return type} +\codeAnnotation{aText} (4.5,-0.51) {argument type} +% Arrows +\draw[->, annotation] (lText) -- (l); +\draw[->, annotation] (nText) -- (n); +\draw[->, annotation] (sText) -- (s); +\draw[->, annotation] (rText) -- (r); +\draw[->, annotation] (aText) -- (a); +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} + \inputlisting{anatomy-of-a-method-signature.tex} +\end{thinmargin} + +\input{anatomy-of-a-method-signature.tex} + +\subsection{Using a library method~\autocite[30]{sedgewick-wayne-2016}} +% -------------------------------- + +\begin{filecontents}{using-a-library-method.tex} +\begin{tikzpicture}[remember picture] +\codeBlock{% +\iPart{r}{double} d = \iPart{l}{Math}.\iPart{m}{sqrt}(\iPart{a}{b*b - 4.0*a*c)}; +} +% Annotation +\codeAnnotation{lText} (2, 1.125) {library name} +\codeAnnotation{mText} (4.5, 1.125) {method name} +\codeAnnotation{rText} (2,-0.7) {return type} +\codeAnnotation{aText} (4,-0.7) {argument} +% Arrows +\draw[->,annotation] (lText) -- (l); +\draw[->,annotation] (mText) -- (m); +\draw[->,annotation] (rText.north west) -- (r); +\draw[->,annotation] (aText.north east) -- (a); +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} + \inputlisting{using-a-library-method.tex} +\end{thinmargin} + +\input{using-a-library-method.tex} + +\subsection{Anatomy of an \texttt{if} statement~\autocite[51]{sedgewick-wayne-2016}} +% --------------------------------------------- + +\begin{filecontents}{anatomy-of-an-if-statement.tex} +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[remember picture] +% {[on background layer]\draw[code grid debug] (-2.5,-0.5) grid (2.5,2.5);} +\node(code) [anatomy] at (0,0) {% +\begin{lstlisting} +if (!\cPart{e}{x > y}!) +{ + int t = x;!\mtPoint{tr}! + x = y; + !\mbPoint{bl}! y = t;!\extremPoint{br}! +} +\end{lstlisting} +}; + +\fitExtrem{b}{(tr) (bl) (br)} +% Annotation +\codeAnnotation{eText} (1,3.5) {boolean\\expression} +\codeAnnotation{bText} (-1,1.125) {sequence\\of \extremPoint{bPoint}[0.75ex]\\statements} +% Arrow +\draw[->,annotation] (eText) -- (e); +\draw[->,annotation] (bPoint) -- (b); +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} + \inputlisting{anatomy-of-an-if-statement.tex} +\end{thinmargin} + +\input{anatomy-of-an-if-statement.tex} + +\subsection{Anatomy of a \texttt{while} loop~\autocite[54]{sedgewick-wayne-2016}} +% ------------------------------------------ + +\begin{filecontents}{anatomy-of-a-while-loop.tex} +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[remember picture] +% {[on background layer]\draw[code grid debug] (-2.5,-0.5) grid (2.5,2.5);} +\node(code) [anatomy] at (0,0) { +\begin{lstlisting} +!\cPart{i}{\bgcode{int power = 1;}}\phantom{\rule[-2ex]{0.1ex}{0.1ex}}! +while ( !\cPart{c}{power <= n/2}! ) +!\cPart{po}{\{}! + !\cPart{b}{power = 2*power;}! +!\cPart{pc}{\}}! +\end{lstlisting} +}; + +% Annotation +\codeAnnotation{iText} (-1,3.25) {initialization is a\\separate statement} +\codeAnnotation{cText} (3.5,3) {loop-\\continuation\\condition} +\codeAnnotation{pText} (-1.5,0.5) {braces are\\optional\\when body\\is a single\\statement} +\codeAnnotation{bText} (2.125,-0.5) {body} +% Arrows +\draw[->,annotation] (iText) -- (i.north west); +\draw[->,annotation] (cText) -- (c); +\draw[->,annotation] (bText) -- (b); +\draw[->,annotation] (pText) -- (po); +\draw[->,annotation] (pText) -- (pc); +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} + \inputlisting{anatomy-of-a-while-loop.tex} +\end{thinmargin} + +{\sffamily test font if while do} + +\input{anatomy-of-a-while-loop.tex} + +\subsection{Anatomy of a \texttt{for} loop~\autocite[59]{sedgewick-wayne-2016}} +% ---------------------------------------- + +\begin{filecontents}{anatomy-of-a-for-loop.tex} +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[ + remember picture + ,code annotation/.append style={% + font=\sffamily\itshape\scriptsize + } +] + % {[on background layer]\draw[code grid debug] (-2.5,-0.5) grid (5.5,3.5);} +\node(code) [anatomy] at (0,0){% +\begin{lstlisting} +!\iPart{init}{\bgcode{int power = 1;}}! +for ( !\cPart{i}{int i = 0}!; !\cPart{c}{i <= n}!; !\cPart{u}{i++}! ) +{ + !\mtPoint{left}!System.out.println(i + " " + power);!\mtPoint{right}! + power *= 2;!\mbPoint{bottom}! +} +\end{lstlisting} +}; +\fitExtrem{b}{(left) (right) (bottom)} +% Annotations +\codeAnnotation{initText} (-1.5,2.7) {initialize another\\ + variable in a \extremPoint{initPoint}[0.75ex]\\ + separate\\statement} +\codeAnnotation{iText} (1,3.5) {declare and initialize\\ + a loop control variable} +\codeAnnotation{cText} (3.5,3) {loop-\\continuation\\condition} +\codeAnnotation{uText} (6,3) {increment} +\codeAnnotation{bText} (3.5,-0.25) {body} +% arrows on the background +{[on background layer] +\draw[->,annotation] (initPoint) -- (init.north west); +\draw[->,annotation] (iText) -- (i); +\draw[->,annotation] (cText) -- (c); +\draw[->,annotation] (uText) -- (u); +\draw[->,annotation] (bText) -- (b); +} +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} + \inputlisting{anatomy-of-a-for-loop.tex} +\end{thinmargin} + +\input{anatomy-of-a-for-loop.tex} + +\subsection{Anatomy of a static method~\autocite[196]{sedgewick-wayne-2016}} +% ---------------------------------------- +\begin{filecontents}{anatomy-of-a-static-method.tex} +\lstset{escapeinside={!}{!}} +\begin{tikzpicture}[remember picture] + %{[on background layer]\draw[code grid debug] (-2.5,-0.5) grid (8.5,3.5);} +\node(code) [anatomy] at (0,0) {% +\begin{lstlisting} +!\cPart{s}{public static \cPart{rt}{double} \cPart{fn}{harmonic}(\cPart{al}{\iPart{at}{int} \iPart{pv}{n}})}! +{ + !\hmtPoint{left}\cPart{lv}{double sum}! = 0.0; + for (int i = 0; i <= n; ++i)!\extremPoint{right}! + { + sum += 1.0/i; + } + !\cPart{rs}{return sum;}\dmbPoint{bottom}! +} +\end{lstlisting} +}; + +\fitExtrem{b}{(left) (right) (bottom)} + +% Annotation +\codeAnnotation{sText} (-0.7,5) {signature} +\codeAnnotation{rtText} (2,5) {return\\type} +\codeAnnotation{fnText} ( 4,5) {method\\name} +\codeAnnotation{alText} ( 6,5) {argument\\list} +\codeAnnotation{atText} (6.5,1.75) {argument\\type} +\codeAnnotation{pvText} (7.5,2.70) {parameter\\variable} +\codeAnnotation{lvText} (-0.7,2.5) {local\\variable} +\codeAnnotation{bText} (-0.7,1.5) {method\\body} +\codeAnnotation{rsText} (3,-0.4) {return statement} +% Arrows +\draw[->,annotation] (sText) -- (s.north west); +\draw[->,annotation] (rtText) -- (rt); +\draw[->,annotation] (fnText) -- (fn); +\draw[->,annotation] (alText) -- (al); +\draw[->,annotation] (atText) -- (at); +\draw[->,annotation] (pvText) -- (pv); +\draw[->,annotation] (lvText) -- (lv.west); +\draw[->,annotation] (bText) -- (b); +\draw[->,annotation] (rsText) -- (rs); +\end{tikzpicture} +\end{filecontents} + +\begin{thinmargin} + \inputlisting{anatomy-of-a-static-method.tex} +\end{thinmargin} + +\input{anatomy-of-a-static-method.tex} + +\end{document} + diff --git a/graphics/pgf/contrib/codeanatomy/codeanatomy.pdf b/graphics/pgf/contrib/codeanatomy/codeanatomy.pdf new file mode 100644 index 0000000000..3348439ed5 Binary files /dev/null and b/graphics/pgf/contrib/codeanatomy/codeanatomy.pdf differ diff --git a/graphics/pgf/contrib/codeanatomy/codeanatomy.usage.pdf b/graphics/pgf/contrib/codeanatomy/codeanatomy.usage.pdf new file mode 100644 index 0000000000..5057ad4a54 Binary files /dev/null and b/graphics/pgf/contrib/codeanatomy/codeanatomy.usage.pdf differ diff --git a/graphics/pgf/contrib/codeanatomy/codeanatomy.usage.tex b/graphics/pgf/contrib/codeanatomy/codeanatomy.usage.tex new file mode 100644 index 0000000000..5136905bab --- /dev/null +++ b/graphics/pgf/contrib/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 |\\[]| 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} + diff --git a/graphics/pgf/contrib/codeanatomy/literatur.bib b/graphics/pgf/contrib/codeanatomy/literatur.bib new file mode 100644 index 0000000000..27824d42ac --- /dev/null +++ b/graphics/pgf/contrib/codeanatomy/literatur.bib @@ -0,0 +1,8 @@ +@BOOK{sedgewick-wayne-2016, + place={Boston}, + title={Computer Science}, + subtitle={An Interdisciplinary Approach}, + publisher={Addison-Wesley}, + author={Sedgewick, Robert and Wayne, Kevin}, + year={2016} +} \ No newline at end of file -- cgit v1.2.3