Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2017 by Elmar Peise
4 % -----------------------------------------
5 %
6 % This package is distributed under the MIT license.
7 %
8 % \fi
9 %
10 % \iffalse
11 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
12 %<package>\ProvidesPackage{drawmatrix}[2017/06/05 v1.5.0 drawmatrix package]
13 %
14 %<*driver>
15 \documentclass{ltxdoc}
16 \usepackage{drawmatrix}
17 \usepackage{xspace}
18 \usepackage{tcolorbox}
19 \usepackage{lstautodedent}
20 \usepackage{makeidx}
21 \makeindex
22 \tcbuselibrary{documentation}
23 \lstset{autodedent=true, language=TeX}
24 \tcbset{
25 /tcb/docexample/.append style={sidebyside, righthand width=.2\textwidth},
26 docmulti/.style={after={}, height=\baselineskip, after skip=-.75em},
27 }
28 \tcbmakedocSubKey{docDmKey}{drawmatrix}
29 \EnableCrossrefs
30 \RecordChanges
31 \OnlyDescription
32 \begin{document}
33 \DocInput{drawmatrix.dtx}
34 \end{document}
35 %</driver>
36 % \fi
37 %
38 % \CheckSum{131}
39 %
40 % \CharacterTable
41 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
42 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
43 % Digits \0\1\2\3\4\5\6\7\8\9
44 % Exclamation \! Double quote \" Hash (number) \#
45 % Dollar \$ Percent \% Ampersand \&
46 % Acute accent \' Left paren \( Right paren \)
47 % Asterisk \* Plus \+ Comma \,
48 % Minus \- Point \. Solidus \/
49 % Colon \: Semicolon \; Less than \<
50 % Equals \= Greater than \> Question mark \?
51 % Commercial at \@ Left bracket \[ Backslash \\
52 % Right bracket \] Circumflex \^ Underscore \_
53 % Grave accent \` Left brace \{ Vertical bar \|
54 % Right brace \} Tilde \~}
55 %
56 % \changes{v1.0.0}{2014/02/23}{Initial Version}
57 % \changes{v1.0.1}{2014/09/08}{Bugfix: Collapsible bbox (label placement for
58 % vectors)}
59 % \changes{v1.0.2}{2015/03/20}{Bugfix: Bbox had a linewidth/2 offset}
60 % \changes{v1.0.3}{2015/11/18}{Introduced |diag| option}
61 % \changes{v1.1.0}{2015/11/26}{Separate lower and upper banding, externalization
62 % control, fixed matrix style collection, lots of simplifications, moved
63 % ``every'' keys to |/drawmatrix| path}
64 % \changes{v1.1.1}{2016/01/29}{Bugfix: Remove extra space after vectors}
65 % \changes{v1.2.0}{2016/08/25}{Added coordinate transformations}
66 % \changes{v1.3.0}{2016/11/12}{Added label base (shifted exponents)}
67 % \changes{v1.4.0}{2016/12/20}{Added exponenet shortcut}
68 % \changes{v1.5.0}{2017/05/05}{Moved code to keys, added hooks, updated
69 % documentation}
70 %
71 %
72 % \GetFileInfo{drawmatrix.sty}
73 %
74 % \title{The \textsf{drawmatrix} package}
75 % \author{Elmar Peise \\ \texttt{[email protected]}}
76 % \date{\filedate \ \fileversion}
77 %
78 % \newcommand\TikZ{Ti{\it k}Z\xspace}
79 %
80 % \maketitle
81 %
82 % \begin{abstract}
83 % \textsf{drawmatrix} provides macros to visually represent matrices. Various
84 % options allow to change the visualizations, e.g., drawing rectangular,
85 % triangular, or banded matrices.
86 % \end{abstract}
87 %
88 % \tableofcontents
89 %
90 % \input{userdoc}
91 %
92 % \section{Implementation}
93 %
94 % \DoNotIndex{
95 % \dm@bboxheight, \dm@bboxwidth, \dm@currname, \dm@currval, \dm@height,
96 % \dm@labelbase, \dm@labeltextouter, \dm@labeltext, \dm@lowerbandwidth,
97 % \dm@minsize, \dm@offsetheight, \dm@offsetwidth, \dm@upperbandwidth,
98 % \dm@width, \dm@zero, \RequirePackage, \begin, \def, \edef, \else, \end,
99 % \expandafter, \fi, \filldraw, \ifdrawmatrix@externalize, \ifmmode, \ifx,
100 % \let, \newcommand, \newif, \node, \path, \pgfkeys, \pgfkeysalso,
101 % \pgfkeyscurrentname, \pgfkeyscurrentvalue, \pgfkeysnovalue, \pgfkeysvaueof,
102 % \pgflinewidth, \pgfgetlastxy, \pgfmathsetlengthmacro, \pgfresetboundingbox,
103 % \pgfqkeys, \phantom, \tikz@library@external@loaded, \tikzset, \undefined,
104 % }
105 %
106 % This section describes the implementation details of the \textsf{drawmatrix}
107 % package.
108 %
109 % \subsection{Package: \TikZ}
110 %
111 % The \textsf{tikz} package is used for drawing.
112 % \begin{macrocode}
113 \RequirePackage{tikz}
114 % \end{macrocode}
115 %
116 % \subsection{If for externalization}
117 %
118 % \TeX{} |if| representing whether to explicitly disable \TikZ externalization.
119 % \begin{macrocode}
120 \newif\ifdrawmatrix@externalize
121 % \end{macrocode}
122 %
123 % \subsection{Key Declarations and Defaults}
124 %
125 % We rely on PGF keys as much as we can.
126 % \begin{macrocode}
127 \pgfkeys{
128 % \end{macrocode}
129 %
130 % Everything happens in the path |/drawmatrix|.
131 % \begin{macrocode}
132 drawmatrix/.is family,
133 drawmatrix/.cd,
134 % \end{macrocode}
135 %
136 % |picture| is the style for the |\tikzpicture| in which the matrix is drawn.
137 % |baseline| sets the baseline of the picture to a named coordinate of the
138 % matrix (default: base of the label).
139 % \begin{macrocode}
140 picture/.style={},
141 path/.style={},
142 baseline/.style={picture/.append style={baseline=(drawmatrix #1)}},
143 scale/.style={path/.append style={scale=#1}},
144 x/.style={path/.append style={x=#1}},
145 y/.style={path/.append style={y=#1}},
146 baseline=label.base,
147 % \end{macrocode}
148 %
149 % |bbox| is the style of the bounding box, to which |bbox style| appends keys.
150 % \begin{macrocode}
151 bbox/.style={},
152 bbox style/.style={bbox/.append style={#1}},
153 % \end{macrocode}
154 %
155 % |bbox height| and |bbox width| don't have default values. |bbox size| sets
156 % them both to the same value.
157 % \begin{macrocode}
158 bbox height/.initial,
159 bbox width/.initial,
160 bbox size/.style={bbox height=#1, bbox width=#1},
161 % \end{macrocode}
162 %
163 % |offset height| and |offset width| are |0| by default. |offset| sets them
164 % both to the same value.
165 % \begin{macrocode}
166 offset height/.initial=0,
167 offset width/.initial=0,
168 offset/.style={offset height=#1, offset width=#1},
169 % \end{macrocode}
170 %
171 % |width| and |height| are |1| (\TikZ unit) by default. |size| sets them both
172 % to the same value.
173 % \begin{macrocode}
174 height/.initial=1,
175 width/.initial=1,
176 size/.style={height=#1, width=#1},
177 % \end{macrocode}
178 %
179 % The |lower bandwidth| and |upper bandwidth| don't have default values.
180 % |bandwidth| sets them both to the same value.
181 % \begin{macrocode}
182 lower bandwidth/.initial,
183 upper bandwidth/.initial,
184 bandwidth/.style={lower bandwidth=#1, upper bandwidth=#1},
185 % \end{macrocode}
186 %
187 % |lower banded| and |upper banded| are shortcuts to set the corresponding
188 % bandwidths to the default value of |0.3| (\TikZ units). |banded| sets them
189 % both.
190 % \begin{macrocode}
191 lower banded/.style={lower bandwidth=.3},
192 upper banded/.style={upper bandwidth=.3},
193 banded/.style={lower banded, upper banded},
194 % \end{macrocode}
195 %
196 % |lower| and |upper| are implemented by setting the opposite bandwidth to
197 % |0|. |diag| sets them both.
198 % \begin{macrocode}
199 lower/.style={upper bandwidth=0},
200 upper/.style={lower bandwidth=0},
201 diag/.style={bandwidth=0},
202 % \end{macrocode}
203 %
204 % |label| is the style for the label with the text |label text|. |label pos|
205 % sets the label at a named coordinate of the matrix (default: center of the
206 % bounding box). |label anchor| sets the label's |anchor| (default: in the
207 % middle).
208 % \begin{macrocode}
209 label text/.initial,
210 label/.style={},
211 label pos/.style={label/.append style={at=(drawmatrix #1)}},
212 label pos=bbox.center,
213 label anchor/.style={label/.append style={anchor=#1}},
214 label anchor=mid,
215 % \end{macrocode}
216 %
217 % |label base| and |label base anchor| allow to ofset labels with exponents.
218 % \begin{macrocode}
219 label base/.initial,
220 label outer/.style={},
221 label base anchor/.style={label outer/.append style={
222 anchor=#1, at=(drawmatrix label.#1)
223 }},
224 label base anchor=base west,
225 % \end{macrocode}
226 %
227 % |exponent| is a shortcut to add an expontent to the label text without using
228 % the |label base|.
229 % \begin{macrocode}
230 exponent/.style={
231 label base/.expanded=\pgfkeysvalueof{/drawmatrix/label text},
232 label text/.append=^{#1}
233 },
234 % \end{macrocode}
235 %
236 % Unknown keys are collected in |/drawmatrix/drawmatrix|.
237 % \begin{macrocode}
238 drawmatrix/.style={},
239 .unknown/.code={%
240 \let\dm@currname\pgfkeyscurrentname%
241 \let\dm@currval\pgfkeyscurrentvalue%
242 \ifx#1\pgfkeysnovalue\pgfkeysalso{
243 drawmatrix/.append style/.expand once={\dm@currname}
244 }\else\pgfkeysalso{
245 drawmatrix/.append style/.expand twice={%
246 \expandafter\dm@currname\expandafter=\dm@currval%
247 }
248 }\fi%
249 },
250 % \end{macrocode}
251 %
252 % The default style for matrices: |every picture| applies to all
253 % |\tikzpicture|s the matrices are drawn in, |every bbox| applies to all
254 % bounding boxes, |every drawmatrix| applies to the matrices themselves, and
255 % |every label| applies to the labels.
256 % \begin{macrocode}
257 every picture/.style={},
258 every bbox/.style={
259 name=drawmatrix bbox,
260 inner sep=0
261 },
262 every drawmatrix/.style={
263 fill=white,
264 draw=gray
265 },
266 every label/.style={
267 name=drawmatrix label,
268 outer sep=0,
269 inner sep=0
270 },
271 every node/.style={
272 name=drawmatrix matrix,
273 outer sep=0,
274 inner sep=0,
275 anchor=north west,
276 at=(drawmatrix north west)
277 },
278 % \end{macrocode}
279 %
280 % |externalize| sets a \TeX{} if (default: |true| = behave as all pictures).
281 % \begin{macrocode}
282 externalize/.is if=drawmatrix@externalize,
283 externalize=true,
284 % \end{macrocode}
285 %
286 % \subsection{Hooks}
287 % Hooks for inserting code at various points of the render.
288 % \begin{macrocode}
289 pre code/.code={},
290 post setup code/.code={},
291 pre coordinate code/.code={},
292 post coordinate code/.code={},
293 pre draw code/.code={},
294 post draw code/.code={},
295 pre label code/.code={},
296 post label code/.code={},
297 post code/.code={},
298 % \end{macrocode}
299 %
300 % \subsection{Code Keys}
301 % The following keys contain the code that construct the drawmatrix.
302 %
303 % Prepare the label text and, if needed label outer text (for alignment). This
304 % needs to be outside the tikzpicture to properly detect math mode.
305 % \begin{macrocode}
306 setup label code/.code={
307 \ifmmode\edef\dm@labeltext{$\dm@labeltext$}\fi%
308 \expandafter\ifx\dm@labelbase\pgfkeysnovalue\else%
309 \let\dm@labeltextouter\dm@labeltext%
310 \edef\dm@labelbase{%
311 \ifmmode$\dm@labelbase$\else\dm@labelbase\fi%
312 }%
313 \def\dm@labeltext{\phantom{\dm@labelbase}}%
314 \fi%
315 },
316 % \end{macrocode}
317 %
318 % Disable externalization if |externalize=false|.
319 % \begin{macrocode}
320 externalization code/.code={
321 \ifdrawmatrix@externalize\else%
322 \ifx\tikz@library@external@loaded\undefined\else%
323 \tikzset{external/export=false}%
324 \fi%
325 \fi%
326 },
327 % \end{macrocode}
328 %
329 % Parse width, height, the minimum dimension and zero for comparison purposes.
330 % \begin{macrocode}
331 setup sizes code/.code={
332 \path[/drawmatrix/path] (\dm@width, \dm@height);
333 \pgfgetlastxy\dm@width\dm@height
334 \path[/drawmatrix/path] (\dm@offsetwidth, \dm@offsetheight);
335 \pgfgetlastxy\dm@offsetwidth\dm@offsetheight
336 \pgfmathsetlengthmacro\dm@minsize{min(\dm@width, \dm@height)}
337 \pgfmathsetlengthmacro\dm@zero{0.0}
338 % \end{macrocode}
339 %
340 % Prepare the band widths: First, if the matrix is not banded, the bandwidth is
341 % set to the smaller matrix dimension. Then, the band width is limited by this
342 % smaller dimension.
343 % \begin{macrocode}
344 \expandafter\ifx\dm@lowerbandwidth\pgfkeysnovalue
345 \def\dm@lowerbandwidth{\dm@minsize}
346 \else
347 \path[/drawmatrix/path] (\dm@lowerbandwidth, 0);
348 \pgfgetlastxy\dm@lowerbandwidth\dm@zero
349 \fi
350 \expandafter\ifx\dm@upperbandwidth\pgfkeysnovalue
351 \def\dm@upperbandwidth{\dm@minsize}
352 \else
353 \path[/drawmatrix/path] (0, \dm@upperbandwidth);
354 \pgfgetlastxy\dm@zero\dm@upperbandwidth
355 \fi
356 \pgfmathsetlengthmacro\dm@lowerbandwidth{
357 min(\dm@minsize, \dm@lowerbandwidth)
358 }
359 \pgfmathsetlengthmacro\dm@upperbandwidth{
360 min(\dm@minsize, \dm@upperbandwidth)
361 }
362 % \end{macrocode}
363 %
364 % Set the default bounding box size.
365 % \begin{macrocode}
366 \expandafter\ifx\dm@bboxheight\pgfkeysnovalue
367 \pgfmathsetlengthmacro\dm@bboxheight{
368 \dm@height + \dm@offsetheight
369 }
370 \else
371 \path[/drawmatrix/path] (0, \dm@bboxheight);
372 \pgfgetlastxy\dm@zero\dm@bboxheight
373 \fi
374 \expandafter\ifx\dm@bboxwidth\pgfkeysnovalue
375 \pgfmathsetlengthmacro\dm@bboxwidth{
376 \dm@width + \dm@offsetwidth
377 }
378 \else
379 \path[/drawmatrix/path] (\dm@bboxwidth, 0);
380 \pgfgetlastxy\dm@bboxwidth\dm@zero
381 \fi
382 },
383 % \end{macrocode}
384 %
385 % Reset the bounding box and begin with (drawing) the path for the bounding box.
386 % \begin{macrocode}
387 bbox code/.code={
388 \pgfresetboundingbox
389 \node[/drawmatrix/every bbox, /drawmatrix/bbox,
390 minimum height=\dm@bboxheight,
391 minimum width=\dm@bboxwidth] {};
392 },
393 % \end{macrocode}
394 %
395 % Whether needed or not, declare all matrix corners.
396 % \begin{macrocode}
397 coordinate code/.code={
398 \path (drawmatrix bbox.north west)
399 ++(\dm@offsetwidth, -\dm@offsetheight)
400 ++(.5\pgflinewidth, -.5\pgflinewidth)
401 coordinate (drawmatrix north west)
402 ++(\dm@width, 0)
403 +(-\dm@minsize + \dm@upperbandwidth, 0)
404 coordinate (drawmatrix north)
405 +(0, -\dm@minsize + \dm@upperbandwidth)
406 coordinate (drawmatrix east)
407 ++(0, -\dm@height)
408 coordinate (drawmatrix south east)
409 ++(-\dm@width, 0)
410 +(\dm@minsize - \dm@lowerbandwidth, 0)
411 coordinate (drawmatrix south)
412 +(0, \dm@minsize - \dm@lowerbandwidth)
413 coordinate (drawmatrix west);
414 },
415 % \end{macrocode}
416 %
417 % Add an invisible node the size of the matrix.
418 % \begin{macrocode}
419 node code/.code={
420 \node[/drawmatrix/every node,
421 minimum height=\dm@height,
422 minimum width=\dm@width] {};
423 },
424 % \end{macrocode}
425 %
426 % Now, draw only what is needed of the matrix. Otherwise path modifications
427 % (e.g., such as rounded corners) might not work.
428 % \begin{macrocode}
429 draw code/.code={
430 \filldraw[/drawmatrix/every drawmatrix, /drawmatrix/drawmatrix]
431 (drawmatrix north west)
432 \ifx\dm@upperbandwidth\dm@zero
433 \ifx\dm@width\dm@minsize\else -- (drawmatrix north) \fi
434 \ifx\dm@height\dm@minsize\else -- (drawmatrix east) \fi
435 \else
436 -- (drawmatrix north)
437 \ifx\dm@upperbandwidth\dm@minsize\else
438 -- (drawmatrix east)
439 \fi
440 \fi
441 -- (drawmatrix south east)
442 \ifx\dm@lowerbandwidth\dm@zero
443 \ifx\dm@width\dm@minsize\else -- (drawmatrix south) \fi
444 \ifx\dm@height\dm@minsize\else -- (drawmatrix west) \fi
445 \else
446 -- (drawmatrix south)
447 \ifx\dm@lowerbandwidth\dm@minsize\else
448 -- (drawmatrix west)
449 \fi
450 \fi
451 -- cycle;
452 },
453 % \end{macrocode}
454 %
455 % The label.
456 % \begin{macrocode}
457 label code/.code={
458 \node[/drawmatrix/every label, /drawmatrix/label]
459 {\dm@labeltext};
460 \expandafter\ifx\dm@labelbase\pgfkeysnovalue\else
461 \node[/drawmatrix/every label, /drawmatrix/label,
462 /drawmatrix/label outer] {\dm@labeltextouter};
463 \fi
464 }
465 }
466 % \end{macrocode}
467 %
468 % \subsection{User Macros}
469 %
470 % \refCom{drawmatrixset} as a simple shortcut like |\tikzset|.
471 % \begin{macrocode}
472 \newcommand\drawmatrixset[1]{\pgfqkeys{/drawmatrix}{#1}}
473 % \end{macrocode}
474 %
475 % Here we go, the main thing: \refCom{drawmatrix}. First, apply the options and
476 % extract the sizes from the PGF keys.
477 % \begin{macrocode}
478 \newcommand\drawmatrix[2][]{{%
479 \drawmatrixset{
480 label text={#2},
481 #1,
482 label text/.get=\dm@labeltext,
483 height/.get=\dm@height,
484 width/.get=\dm@width,
485 lower bandwidth/.get=\dm@lowerbandwidth,
486 upper bandwidth/.get=\dm@upperbandwidth,
487 offset height/.get=\dm@offsetheight,
488 offset width/.get=\dm@offsetwidth,
489 bbox height/.get=\dm@bboxheight,
490 bbox width/.get=\dm@bboxwidth,
491 label base/.get=\dm@labelbase,
492 pre code,
493 setup label code,
494 externalization code
495 }%
496 \begin{tikzpicture}[/drawmatrix/every picture, /drawmatrix/picture]
497 \drawmatrixset{
498 setup sizes code,
499 post setup code,
500 bbox code,
501 pre coordinate code,
502 coordinate code,
503 post coordinate code,
504 node code,
505 pre draw code,
506 draw code,
507 post draw code,
508 pre label code,
509 label code,
510 post label code
511 }
512 \end{tikzpicture}%
513 \drawmatrixset{post code}%
514 }}
515 % \end{macrocode}
516 %
517 % \Finale
518 % \printindex
519 % \PrintChanges
520 %
521 \endinput