Debian Codegraph @

texmf-dist/source/latex/codeanatomy/codeanatomy.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: codeanatomy.dtx Copyright (C) 2019 Hong-Phuc Bui
4 %
5 % It may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in the file
9 %
10 % https://www.latex-project.org/lppl.txt
11 %
12 %
13 % -----------------------------------------------------------------------
14 %
15 % The development version of the bundle can be found at
16 %
17 % https://github.com/hpb-htw/codeanatomy
18 %
19 % for those people who are interested.
20 %
21 % -----------------------------------------------------------------------
22 % \fi
23 %
24 % \iffalse
25 %<package>\NeedsTeXFormat{LaTeX2e}[2018/12/01]
26 %<package>\ProvidesPackage{codeanatomy}[2025/10/16 v0.5-Beta draw Code Anatomy]
27 % \fi
28 %
29 % \iffalse
30 %<*driver>
31 \documentclass[full]{l3doc}
32
33 \usepackage{fontspec}
34 \usepackage{luaotfload}
35
36
37 \usepackage{biblatex}
38 \addbibresource{literatur.bib}
39 \newcommand{\slsh}{\textbackslash{}}
40 \newcommand{\TikZ}{Ti\textit{k}Z}
41 \newcommand{\fixedBug}[1]{\tikz[baseline=(X.base)]\node[cross out,draw] (X) {#1};}
42 \def\thinmargin{\list{}{\rightmargin-50pt\leftmargin-90pt}\item[]}
43 \let\endthinmargin=\endlist
44
45 \usepackage{listings}
46 \lstset {
47 basicstyle=\small\ttfamily
48 ,escapeinside={+}{+}
49 }
50
51 \usepackage{codeanatomy}
52 \EnableCrossrefs
53 \CodelineIndex
54 \RecordChanges
55
56 \begin{document}
57 \DocInput{\jobname.dtx}
58 \end{document}
59 %</driver>
60 % \fi
61 %
62 % \GetFileInfo{\jobname.sty}
63 % \DoNotIndex{\definecolor, \colorlet}
64 % \DoNotIndex{\NewDocumentCommand, \node}
65 % \DoNotIndex{\phantom}
66 % \DoNotIndex{\RequirePackage, \rule}
67 % \DoNotIndex{\small, \sffamily}
68 % \DoNotIndex{\textcolor, \tikzmarknode, \tikzset, \ttfamily}
69 % \DoNotIndex{\usetikzlibrary}
70 %
71 % \title{^^A
72 % \pkg{codeanatomy} -- Draw Code Anatomy^^A
73 % \thanks{This file describes \fileversion, ^^A
74 % last revised \filedate.}\\[1ex]^^A
75 % \normalsize{Reference}^^A
76 % }^^A
77 %
78 % \author{^^A
79 % Hồng-Phúc Bùi^^A
80 % \thanks{^^A
81 % E-mail:
82 % \href{mailto:Hồng-Phúc Bùi}
83 % {hong-phuc.bui (at) htwsaar dot de}^^A
84 % }^^A
85 % }
86 %
87 % \date{Released \filedate}
88 %
89 % \parindent0pt
90 %
91 % \maketitle
92 % \tableofcontents
93 %
94 % \section{Hints}
95 % Usage of this Package can be found in \texttt{codeanatomy.usage.pdf} and \texttt{codeanatomy.lstlisting.pdf}.
96 % This document show only generated reference of commands in this Package.
97 %
98
99 % ^^A %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
100 % \section{Implementation}
101 %
102 % \changes{v0.2-Alpha}
103 % {2019/07/10}
104 % {This package does not load \pkg{xcolor} anymore.
105 % It relies on \pkg{tikz}, that \pkg{tikz} loads \pkg{xcolor}
106 % in a way that \pkg{codeanatomy} can define RGB color}
107 %
108 %
109 % \subsection{Package Dependenies}
110 %
111 % \begin{macrocode}
112 \RequirePackage{expl3}
113 \RequirePackage{xparse}
114 \RequirePackage{tikz}
115 % \end{macrocode}
116 %
117 % Load necsessary \TikZ{} libraries.
118 % \begin{macrocode}
119 \usetikzlibrary{
120 tikzmark
121 ,fit
122 ,arrows.meta
123 ,bending
124 ,shapes
125 ,chains
126 ,backgrounds
127 ,scopes
128 ,decorations
129 ,decorations.pathmorphing
130 }
131 % \end{macrocode}
132 %
133 % \subsection{Setup styles}
134 % ^^A+++++++++++++++++++++
135 % \subsubsection{Colors}
136 % ^^A-------------------
137 % Define colors which are used in \pkg{codeanatomy}
138
139 % \DescribeMacro{annotationcolor}
140 % \tikz{\draw[fill=annotationcolor] circle(1ex); }
141 % \begin{macrocode}
142 \definecolor{annotationcolor}
143 {rgb}{0,0.50002,1} % Blue
144 % \end{macrocode}
145 %
146 % \DescribeMacro{bgcmdcolor}
147 % \tikz{\draw[fill=bgcmdcolor] circle(1ex); }
148 % \begin{macrocode}
149 \colorlet{bgcmdcolor}{gray} % Grey
150 % \end{macrocode}
151 %
152 % \subsubsection{\TikZ{} styles for code in a Code Anatomy}
153 % ^^A------------------------------------------------------
154 %
155 % \DescribeMacro{anatomy}
156 % \TikZ{} style for annotation labels: \\
157 % |\tikz{\node(code) [anatomy] at (0,0) {code line 1\\code line 2}; }|\\
158 % yields \tikz{\node(code) [anatomy] at (0,0) {code line 1\\code line 2}; }
159 % \begin{macrocode}
160 \tikzset{anatomy/.style={%
161 anchor=south west,%
162 inner sep=0,%
163 align=left,%
164 font=\ttfamily
165 }
166 }
167 % \end{macrocode}
168 %
169 %
170 %
171 % \DescribeMacro{code part}
172 % \TikZ{} style to mark a piece of code in an anatomy: \\
173 % |\tikz{\node(code) [code part] at (0,0) {let a = 12;};}|\\
174 % yields \tikz{\node(code) [code part] at (0,0) {let a = 12;};}
175 % \begin{macrocode}
176 \tikzset{code part/.style={%
177 rectangle,%
178 draw=annotationcolor,%
179 align=left,%
180 minimum height=1.175em,%
181 inner sep=1.75pt,%
182 outer sep=0.1pt,%
183 font=\ttfamily
184 }
185 }
186 % \end{macrocode}
187 %
188 %
189 % \DescribeMacro{ignored code part}
190 % \TikZ{} style to make a pice of code in an anatomy as not important in currently talking context
191 % |\tikz{\node(ignore code) [ignored code part] at (0,0) {/*some comment*/} }|
192 % yields \tikz{\node(ignore code) [ignored code part] at (0,0) {/*some comment*/} }
193 %
194 % \changes{v0.4-Beta}
195 % {2023/01/24}
196 % {Add new \TikZ{} Style \texttt{ignored code part}}%
197 %
198 % \begin{macrocode}
199 \tikzset{ignored code part/.style={%
200 code part,%
201 draw=none,color=bgcmdcolor,%
202 inner sep=0.75pt
203 }
204 }
205 % \end{macrocode}
206 %
207 %
208 %
209 %
210 % \DescribeMacro{fit extrem}
211 % \TikZ{} style to mark a piece of multiple line code in an anatomy:\\
212 % |\tikz{ \node(c)[fit extrem, fit={(0,0) (0.5,0.975) (1,0)}] {}; }|\\
213 % yields \tikz{ \node(c)[fit extrem, fit={(0,0) (0.5,0.975) (1,0)}] {}; }
214 % \begin{macrocode}
215 \tikzset{fit extrem/.style={%
216 rectangle,%
217 draw=annotationcolor,%
218 align=left,%
219 minimum height=1.175em,%
220 inner sep=1.75pt,%
221 outer sep=0.1pt,%
222 font=\ttfamily
223 }
224 }
225 % \end{macrocode}
226 %
227 %
228 %
229 %
230 % \DescribeMacro{annotation}
231 % \TikZ{} style of arrows from annotation labels to code parts:\\
232 % |\tikz{\draw[] (1,0) circle(3ex); \draw[->,annotation] (0,0) -- (1,0);}|\\
233 % yields
234 % \tikz{\draw[] (1,0) circle(3ex); \draw[->,annotation] (0,0) -- (1,0);}
235 %
236 % \changes{v0.4-Alpha}
237 % {2019/07/12}
238 % {Set \texttt{fill} to \texttt{annotationcolor} explicit for arrow style}
239 %
240 % \begin{macrocode}
241 \tikzset{annotation/.style={%
242 preaction={
243 draw=white,%
244 line width=3.5pt,%
245 arrows={-Triangle Cap[]},%
246 },%
247 draw=annotationcolor,%
248 arrows={-Latex[%
249 round,%
250 color=annotationcolor,
251 fill=annotationcolor
252 ]
253 },
254 shorten >=0.25pt
255 }
256 }
257 % \end{macrocode}
258 %
259 %
260 % \DescribeMacro{code annotation}
261 % \TikZ{} style for a annotation label \tikz{\node(a)[code annotation] at (0,0) {function name};}
262 % \begin{macrocode}
263 \tikzset{code annotation/.style={%
264 inner sep=2pt,%
265 text=annotationcolor,%
266 align=center,%
267 font=\sffamily\small
268 }
269 }
270 % \end{macrocode}
271 %
272 %
273 %
274 % \DescribeMacro{code grid debug}
275 % \TikZ{} style to draw debug grid on the background of anatomy
276 % \begin{macrocode}
277 \tikzset{code grid debug/.style={%
278 step=1.0,%
279 draw=gray!20,%
280 very thin,%
281 on background layer
282 }
283 }
284 % \end{macrocode}
285 %
286 %
287 % ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
288 %
289 %
290 % \subsection{Command used to set code and code anatomy}
291 % ^^A---------------------------------------------------
292 %
293 %
294 % \DescribeMacro{\codeBlock} \marg{code}
295 %
296 % Complete code listing of a Code Anatomy figure is typeset by this command.
297 % Whereas \marg{code} is the \emph{formatted} code listing.
298 % This command can be used if there are no other packages to typeset code listing in use.
299 % \begin{macrocode}
300 \NewDocumentCommand{\codeBlock}{m}%
301 {\node(code) [anatomy] at (0,0) {#1};}%
302 % \end{macrocode}
303 %
304 %
305 %
306 % \DescribeMacro{\cPart} \oarg{style} \marg{node name}\marg{piece of code}
307 %
308 % Assign a piece of typeset code --typical in one line-- to a \TikZ{} Node, so that it can
309 % be annotated.
310 % \begin{itemize}
311 % \item \oarg{style} a defined \TikZ{} style to be applied to this node, the style |code part|
312 % is applied to the node per default.
313 % \item \marg{node name} is a unique \TikZ{} node name in the |tikzpicture|
314 % \item \marg{piece of code} is a single code part to be marked.
315 % \end{itemize}
316 %
317 % \changes{v0.4-Beta}
318 % {2023/01/24}
319 % {Add option \oarg{style} to \texttt{cPart}}%
320 %
321 % \begin{macrocode}
322 \NewDocumentCommand\cPart{O{code part}mm}
323 {\tikzmarknode[#1]{#2}{#3}}
324 % \end{macrocode}
325 %
326 %
327 %
328 % \DescribeMacro{\iPart} \marg{node name}\marg{piece of code}
329 %
330 % Assign a piece of typeset code --typical in one line-- to a \TikZ{} Node, so that it can
331 % be annotated. It does not plot border around the pice of code as |\cPart| does.
332 % \begin{itemize}
333 % \item \oarg{style} a defined \TikZ{} style to be applied to this node, the style |ignored code part|
334 % is applied to the node per default.
335 % \item \marg{node name} is a unique \TikZ{} node name in the |tikzpicture|
336 % \item \marg{piece of code} is a single code part to be marked.
337 % \end{itemize}
338 %
339 % \changes{v0.4-Beta}
340 % {2023/01/24}
341 % {Add option \oarg{style} to \texttt{iPart}}
342 %
343 % \begin{macrocode}
344 \NewDocumentCommand{\iPart}{O{ignored code part}mm} %
345 {\tikzmarknode[#1]{#2}{#3}}
346 % \end{macrocode}
347 %
348 %
349 %
350 %
351 % \DescribeMacro{\mtPoint}\marg{node name}
352 %
353 % Marks a point as a \textbf{m}ost \textbf{t}op in a Code Block.
354 % \begin{macrocode}
355 \NewDocumentCommand{\mtPoint}{m}
356 {\tikzmarknode{#1}{\phantom{\rule[1.8ex]{0.1ex}{0.1ex}}}}
357 % \end{macrocode}
358 %
359 %
360 %
361 % \DescribeMacro{\hmtPoint}\marg{node name}
362 %
363 % Marks a point as a \textbf{h}eigher \textbf{m}ost \textbf{t}op point in a Code Block.
364 % \begin{macrocode}
365 \NewDocumentCommand{\hmtPoint}{m}
366 {\tikzmarknode{#1}{\phantom{\rule[2.5ex]{0.1ex}{0.1ex}}}}
367 % \end{macrocode}
368 %
369 %
370 %
371 % \DescribeMacro{\mbPoint}\marg{node name}
372 %
373 % Marks a point as a \textbf{d}eeper \textbf{m}ost \textbf{b}ottom point in a Code Block.
374 % \begin{macrocode}
375 \NewDocumentCommand{\mbPoint}{m}
376 {\tikzmarknode{#1}{\phantom{\rule[-0.55ex]{0.1ex}{0.1ex}}}}
377 % \end{macrocode}
378 %
379 %
380 %
381 % \DescribeMacro{\dmbPoint}\marg{node name}
382 %
383 % Marks a point as a \textbf{d}eeper \textbf{m}ost \textbf{b}ottom point in a Code Block.
384 % \begin{macrocode}
385 \NewDocumentCommand{\dmbPoint}{m}
386 {\tikzmarknode{#1}{\phantom{\rule[-2ex]{0.1ex}{0.1ex}}}}
387 % \end{macrocode}
388 %
389 %
390 % \DescribeMacro{\extremPoint}\marg{node name}\oarg{yshift}\oarg{xshift}\oarg{style}
391 %
392 % Create a \TikZ{} Node as reference point for later use in |\fitExtrem|.
393 %
394 % \begin{itemize}
395 % \item \marg{node name} is the \TikZ{} node name which is used in |\fitExtrem| to reference to this point
396 % \item \oarg{yshift} a length, default 0ex which places this markpoint on the base line,
397 % shift this mark point vertical, for positive value over base line, negative value under
398 % base line.
399 % \item \oarg{xshift} same as \oarg{yshift} but for horizontal direction.
400 % \item \oarg{style} is a \TikZ{} style (may be defined by user).
401 % \end{itemize}
402 %
403 % For example:
404 %
405 % |\begin{tikzpicture}[remember picture]|\\
406 % |\node(code) [anatomy] at (0,0) {|\\
407 % | \extremPoint{tl}[2ex]Line with some text\extremPoint{br}[-1ex]\\|\\
408 % | \extremPoint{tl2}other Line with some text\\|\\
409 % | some more line\extremPoint{br2}\\|\\
410 % |};|\\
411 % |\fitExtrem{box1}{(tl) (br)}|\\
412 % |\fitExtrem{box2}{(tl2) (br2)}|\\
413 % |\end{tikzpicture}|\\
414 %
415 % yields\\
416 %
417 % \begin{tikzpicture}[remember picture]
418 % \node(code) [anatomy] at (0,0) {
419 % \extremPoint{tl}[2ex]Line with some text\extremPoint{br}[-1ex]\\
420 % \extremPoint{tl2}other Line with some text\\
421 % some more line\extremPoint{br2}\\
422 % };
423 % \fitExtrem{box1}{(tl) (br)}
424 % \fitExtrem{box2}{(tl2) (br2)}
425 % \end{tikzpicture}
426 % \begin{macrocode}
427 \NewDocumentCommand{\extremPoint}{m O{0ex} O{0.1ex} O{} }
428 {\tikzmarknode[#4]{#1}{\phantom{\rule[#2]{#3}{0.1ex}}}}
429 % \end{macrocode}
430 %
431 %
432 %
433 %
434 % \DescribeMacro{\fitExtrem} \marg{node name}\marg{extrem points}
435 %
436 % Create a rectangle box over given extrem points defined by |\*Point{}|.
437 %
438 % \begin{itemize}
439 % \item \marg{node name} is a unique \TikZ{} node name in the current anatomy
440 % \item \marg{extrem points} is a list of \TikZ{} node name created by |\*Point|,
441 % each name is surrounded by |()|.
442 % \end{itemize}
443 %
444 % Example:
445 %
446 % |\begin{tikzpicture}[remember picture]|\\
447 % |\node(code) [anatomy] at (0,0) {|\\
448 % |\mtPoint{left}Line 1\\|\\
449 % |Long Line 2\extremPoint{right}\\|\\
450 % |Line 3\mbPoint{bottom}|\\
451 % |};|\\
452 % |\fitExtrem{box} { (left) (bottom) (right) }|\\
453 % |\end{tikzpicture}|\\
454 %
455 % yields\\
456 %
457 % \begin{tikzpicture}[remember picture]
458 % \node(code) [anatomy] at (0,0) {
459 % \mtPoint{left}Line 1\\
460 % Long Line 2\extremPoint{right}\\
461 % Line 3\mbPoint{bottom}
462 % };
463 % \fitExtrem{box} { (left) (bottom) (right) }
464 % \end{tikzpicture}
465 % \begin{macrocode}
466 \NewDocumentCommand{\fitExtrem}{mm}
467 {\node(#1)[fit extrem,fit={#2}]{};}
468 % \end{macrocode}
469 %
470 %
471 % \DescribeMacro{\bgcode} \marg{piece of code}
472 %
473 % Typeset a piece of code in color |bgcmdcolor|.
474 % For example
475 %
476 % |\tikz{\codeBlock{let a := 12\bgcode{;}}}|
477 %
478 % yields \tikz{\codeBlock{let a := 12\bgcode{;}}}
479 % \begin{macrocode}
480 \NewDocumentCommand{\bgcode}{m}{\textcolor{bgcmdcolor}{#1}}
481 % \end{macrocode}
482 %
483 %
484 % \DescribeMacro{\ptab}
485 % \DescribeMacro{\phspace}
486 % Produce a horizontal space of 4 small characters |h| respective 1 small character |h|\\
487 % for example: |\tikz{\codeBlock{a\ptab{}b}}| yields \tikz{\codeBlock{a\ptab{}b}}
488 % \begin{macrocode}
489 \NewDocumentCommand{\ptab}{}{\phantom{hhhh}}
490 \NewDocumentCommand{\phspace}{}{\phantom{h}}
491 % \end{macrocode}
492 %
493 %
494 %
495 % \DescribeMacro{\codeAnnotation}\marg{node name}\parg{coordinate}\marg{label text}
496 %
497 % Typeset Annotation labels for a code part.
498 % \begin{itemize}
499 % \item \marg{node name} is a unique \TikZ{} node name in the |tikzpicture|,
500 % \item \parg{coordinate} is the coordinate of the annotation label, surrounded by a |()|,
501 % \item \marg{label text} text content to be typeset.
502 % \end{itemize}
503 %
504 % For example:
505 %
506 % |\begin{tikzpicture}[remember picture]|\\
507 % |\codeBlock{a \cPart{a}{:=} 12 + 13}|\\
508 % |\codeAnnotation{codeLabel} (1,-0.5) {assignment}|\\
509 % |\draw[->,annotation] (codeLabel) -- (a);|\\
510 % |\end{tikzpicture}|\\
511 %
512 % yields\\ \medskip
513 %
514 % \begin{tikzpicture}[remember picture]
515 % \codeBlock{a \cPart{a}{:=} 12 + 13}
516 % \codeAnnotation{codeLabel} (1,-0.5) {assignment}
517 % \draw[->,annotation] (codeLabel) -- (a);
518 % \end{tikzpicture}
519 % \begin{macrocode}
520 \NewDocumentCommand{\codeAnnotation}{m r() m } %
521 { \node(#1)[code annotation] at (#2) {#3}; }
522 % \end{macrocode}
523 %
524 %
525 %
526 %
527 % ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
528 % \section{Known Bugs}
529 %
530 % \paragraph*{\fixedBug{Arrows color}}
531 % Arrows appear in some cases with mysterious color. I don't know why!
532 % For example:
533 %
534 % |\begin{tikzpicture}[remember picture]|\\
535 % |\node(code) [anatomy] at (0,0) {|\\
536 % |\hmtPoint{a}Short line\\|\\
537 % |code with some long text\extremPoint{b}[-0.5ex]|\\
538 % |};|\\
539 % |\fitExtrem{l}{(a) (b)}|\\
540 % |\codeAnnotation{n} (-2,0){here is|\\
541 % | a\extremPoint{point}[0.75ex][0.5ex]|\\
542 % | long line}|\\
543 % |\draw[->, annotation] (point) -- (l);|\\
544 % |\end{tikzpicture}|
545 %
546 % yields
547 %
548 % \begin{tikzpicture}[remember picture]
549 % \node(code) [anatomy] at (0,0) {
550 % \hmtPoint{a}Short line\\
551 % code with some long text\extremPoint{b}[-0.5ex]
552 % };
553 % \fitExtrem{l}{(a) (b)}
554 % \codeAnnotation{n} (-2,0){here is\\
555 % a\extremPoint{point}[0.75ex][0.5ex]\\
556 % long line}
557 % \draw[->, annotation] (point) -- (l);
558 % \end{tikzpicture}
559 %
560 %
561 % ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
562 % \PrintIndex
563 % \PrintChanges
564 %
565 \endinput
566