Debian Codegraph @

texmf-dist/doc/latex/circuitikz/ctikzmanutils.sty

raw
1 % Copyright 2018-2026 by Romano Giannetti
2 % Copyright 2015-2026 by Stefan Lindner
3 % Copyright 2013-2026 by Stefan Erhardt
4 % Copyright 2007-2026 by Massimo Redaelli
5 %
6 % This file may be distributed and/or modified
7 %
8 % 1. under the LaTeX Project Public License and/or
9 % 2. under the GNU Public License.
10 %
11 % See the files gpl-3.0_license.txt and lppl-1-3c_license.txt for more details.
12
13 \NeedsTeXFormat{LaTeX2e}
14 \ProvidesPackage{ctikzmanutils}[2026/02/15 utilities for formatting the circuitikz manual]
15 \RequirePackage{ifthen}
16 \RequirePackage{iftex}
17 \RequirePackage{etoolbox}% easier lwarp support
18 \RequirePackage{listings}
19 \RequirePackage{ragged2e}
20 \RequirePackage{textcomp}
21 \RequirePackage{booktabs}
22 \renewcommand{\arraystretch}{1.2}
23 \RequirePackage{a4wide} % smaller borders
24 \RequirePackage{titling}
25 \RequirePackage{titlesec}
26 % clear page on section break
27 \newcommand{\sectionbreak}{\clearpage}
28 \setcounter{secnumdepth}{4}
29 \setcounter{tocdepth}{4}
30 % for some example we need them...
31 \usetikzlibrary{calc, fit, decorations, decorations.pathmorphing, tikzmark}
32 \RequirePackage{upgreek}
33
34 %
35 % Example definitions using `enverb`
36 %
37 \RequirePackage{enverb,varwidth}
38 \newcommand*\ctikz@ex@lstopts{} % collect options meant for lstlisting
39 \newcommand*\ctikz@ex@codeOutside{} % collect code to execute after the env
40 \newdimen\ctikz@ex@width % width available to the code
41 \newsavebox\ctikz@ex@box % temporary box register
42 % handle the 'store' key.
43 % #1: the name of the storage
44 % saves the contents currently in \enverbBody to the named storage.
45 \newcommand*\ctikz@ex@dostore[1]
46 {%
47 \@ifundefined{ctikz@ex@storage@#1}%
48 {\global\expandafter\let\csname ctikz@ex@storage@#1\endcsname\@empty}%
49 {}%
50 \expandafter\gappto\csname ctikz@ex@storage@#1\expandafter\endcsname
51 \expandafter{\enverbBody}%
52 }
53 % handle the 'restore' key.
54 % #1: the name of the storage
55 % prepends \enverbBody with the contents of the named storage.
56 \newcommand*\ctikz@ex@dorestore[1]
57 {%
58 \@ifundefined{ctikz@ex@storage@#1}
59 {\PackageError{ctikz}{Unknown storage #1}{}}%
60 {%
61 \epreto\enverbBody
62 {%
63 \unexpanded\expandafter\expandafter\expandafter
64 {\csname ctikz@ex@storage@#1\endcsname}%
65 }%
66 }%
67 }
68 \ekvdefinekeys{ctikz/examples}
69 {
70 % pos=<t|b|l>
71 % where to output the results
72 % t: on top of the code
73 % b: below the code
74 % l: left of the code
75 choice-store pos = \ctikz@ex@pos{t,b,l}
76 ,initial pos = l
77 % hsep=<dimen>
78 % how much separation to put between the results and the code for pos=l
79 ,dimen hsep = \ctikz@ex@hsep
80 ,initial hsep = 1.5\columnsep
81 % vsep=<dimen>
82 % how much separation to put between the results and the code for pos=t/b
83 ,dimen vsep = \ctikz@ex@vsep
84 ,initial vsep = \bigskipamount
85 % aboveskip=<dimen>
86 % how much space to put above the environment
87 ,dimen aboveskip = \ctikz@ex@aboveskip
88 ,initial aboveskip = \medskipamount
89 % belowskip=<dimen>
90 % how much space to put below the environment
91 ,dimen belowskip = \ctikz@ex@belowskip
92 ,initial belowskip = \medskipamount
93 % width=<dimen> (late evaluation)
94 % the width of the results box for box=varwidth/minipage, if this is 0pt
95 % the default values will be
96 % pos=l: 0.5\linewidth
97 % pos=t/b: \linewidth
98 ,store width = \ctikz@ex@reswd
99 ,initial width = 0pt
100 % box=<hbox|varwidth|minipage|default>
101 % the type of box put around the results box (not visually but how to
102 % determine the width)
103 % hbox: simply use a \hbox (so natural width, no \par, no vertical
104 % material)
105 % varwidth: Use a `varwidth` environment around it
106 % minipage: Use a `minipage` environment around it
107 % default: the used boxing mechanism depends on pos:
108 % pos=l: hbox
109 % pos=t/b: minipage
110 ,choice-store box = \ctikz@ex@boxtype
111 {hbox=h, varwidth=v, minipage=m, default=d}
112 ,initial box = default
113 % varwidth=[<t|true|f|false>]
114 % backwards compatibility, sets box=varwidth without a value or with
115 % true/t, sets box=default with false/f.
116 ,nmeta varwidth = box=varwidth
117 ,choice varwidth =
118 {
119 true=\ekvmorekv{box=varwidth}, t=\ekvmorekv{box=varwidth},
120 false=\ekvmorekv{box=default}, f=\ekvmorekv{box=default}
121 }
122 % only code=[<true|false>]
123 % true/-NoValue-: there'll be no results box
124 % false: revert the setting
125 ,boolTF only code = \ctikz@ex@onlycodeTF
126 % exec outside=[<true|false>]
127 % true/-NoValue-: the code will be executed outside the environment (using
128 % the generic env/<env>/after hook).
129 % false: revert this setting
130 % This will also call 'only code' with the same value!
131 ,boolTF exec outside = \ctikz@ex@execOutsideTF
132 ,also meta exec outside = {only code={#1}}
133 ,also nmeta exec outside = only code
134 % store=<name>
135 % if used the code will be stored in a named storage for later use (see
136 % 'restore'). Multiple environments using the same storage name will
137 % result in the code being appended to the existing stored code in this
138 % storage.
139 ,dataT store = \ctikz@ex@store
140 % restore=<name>
141 % restore the code of the named storage, meaning it'll be prepended to the
142 % code of this environment for the results box (but not for the listing!)
143 ,dataT restore = \ctikz@ex@restore
144 % clear storage=<name>
145 % forget the contents of the named storage (handled on the spot, so a key
146 % combination `store=foo, clear storage=foo` would first clear `foo` and
147 % then store the environment contents into `foo` after the environment was
148 % processed.
149 ,code clear storage =
150 \global\expandafter\let\csname ctikz@ex@storage@#1\endcsname\ctikz@undef
151 % dollar=[<true|false>]
152 % Whether to fix the dollar category code while code is executed. We set
153 % the boolean globally but if used it's turned to false again in the
154 % after-block. Will only take effect during lwarp's HTML creation.
155 ,gboolTF dollar = \ctikz@ex@dollarTF
156 % collect unknown keys for lstlisting
157 ,unknown code = \appto\ctikz@ex@lstopts{,#1={#2}}
158 ,unknown noval = \appto\ctikz@ex@lstopts{,#1}
159 }
160 % wrap enverbExecute to handle 'dollar=true'
161 \newcommand*\ctikz@ex@execute
162 {%
163 \ctikz@ex@dollarTF{\pushdollarcat}{}%
164 \enverbExecute
165 \ctikz@ex@dollarTF{\popdollarcat}{}%
166 }
167 % handle the boxing inside the results box
168 % #1: default box type if 'box=default'
169 % This will call \ctikz@ex@fbox with the argument based on the current
170 % box-setting.
171 \newcommand*\ctikz@ex@handleboxtype[1] % #1 = default case
172 {%
173 \if\ctikz@ex@boxtype d%
174 \def\ctikz@ex@boxtype{#1}%
175 \fi
176 \if\ctikz@ex@boxtype h%
177 \ctikz@ex@fbox{\ctikz@ex@execute}%
178 \else\if\ctikz@ex@boxtype v%
179 \ctikz@ex@fbox
180 {\begin{varwidth}{\dimeval\ctikz@ex@reswd}\ctikz@ex@execute\end{varwidth}}%
181 \else\if\ctikz@ex@boxtype m%
182 \ctikz@ex@fbox
183 {\begin{minipage}{\dimeval\ctikz@ex@reswd}\ctikz@ex@execute\end{minipage}}%
184 \else
185 \PackageError{ctikz}{Unknown example box type \ctikz@ex@boxtype}{}%
186 \fi\fi\fi
187 }
188 % print the result of the collected code
189 % Control will first be given to \ctikz@ex@handleboxtype which will call
190 % \ctikz@ex@fbox eventually. But first we need to set a suitable default width
191 % for 'width=0pt' (or anything that evaluates to 0pt inside \dimexpr).
192 \newcommand*\ctikz@ex@printresult
193 {%
194 \if\ctikz@ex@pos l%
195 \ifdim\dimeval\ctikz@ex@reswd=\z@
196 \def\ctikz@ex@reswd{.5\linewidth}%
197 \fi
198 \ctikz@ex@handleboxtype{h}%
199 \else
200 \ifdim\dimeval\ctikz@ex@reswd=\z@
201 \def\ctikz@ex@reswd{\linewidth}%
202 \fi
203 \ctikz@ex@handleboxtype{m}%
204 \fi
205 }
206 % output a vcentered framed box for the results
207 % additionally the output (together with the framed box) will be in the box
208 % register \ctikz@ex@box
209 % #1: the contents to box up (should be \enverbExecute nested in a suitable box
210 % construct based on the 'box' key).
211 \newcommand*\ctikz@ex@fbox[1]
212 {%
213 \sbox\ctikz@ex@box
214 {%
215 % fboxsep=6pt, fboxrule=0.8pt -> 13.6pt less for linewidth
216 \advance\linewidth-13.6pt
217 \ctikz@ex@restore\ctikz@ex@dorestore
218 \ignorespaces#1\unskip
219 }%
220 \sbox\ctikz@ex@box
221 {%
222 \fboxsep=6pt
223 \fboxrule=0.8pt
224 \rlap{\fcolorbox{cyan}{white}{\phantom{\usebox\ctikz@ex@box}}}%
225 \kern\fboxrule
226 \kern\fboxsep
227 \usebox\ctikz@ex@box
228 }%
229 $\vcenter{\copy\ctikz@ex@box}$% vcenter matches minipage [c]
230 }
231 % output a vcentered code listing if pos=l, otherwise output a code listing
232 \newcommand*\ctikz@ex@printcode
233 {%
234 \ctikz@ex@onlycodeTF{\@firstofone}%
235 {%
236 \if\ctikz@ex@pos l% only box up the code if necessary
237 \expandafter\@secondoftwo
238 \fi
239 \@secondoftwo{\parbox[c]{\ctikz@ex@width}}%
240 }%
241 {%
242 \ExpandArgs{ne}\enverbListing{lstlisting}%
243 {[%
244 style=expl-code
245 ,aboveskip=6pt% we don't want skips but need to compensate listings
246 ,belowskip=0pt%
247 \unexpanded\expandafter{\ctikz@ex@lstopts}%
248 ]}%
249 }%
250 }
251 % \begin{ctikzExample}[<settings>]
252 % the front level environment. <settings> can be any keys as described inside
253 % \ekvdefinekeys{ctikz/examples}. The following paragraph will be indented if
254 % there's a blank line between \end{ctikzExample} and the first line of the
255 % paragraph (as with lists in LaTeX).
256 \newenvironment{ctikzExample}
257 {\enverb{key-set=ctikz/examples, oarg-not-enverb, more-ignore=0}}
258 {%
259 \par
260 \vskip\ctikz@ex@aboveskip
261 \noindent
262 \ctikz@ex@width=\linewidth
263 \ctikz@ex@onlycodeTF
264 {}%
265 {%
266 \if\ctikz@ex@pos b
267 \else
268 \ctikz@ex@printresult
269 \if\ctikz@ex@pos t
270 \par
271 \vskip\ctikz@ex@vsep
272 \noindent
273 \else
274 \hfill
275 \advance\ctikz@ex@width-\wd\ctikz@ex@box
276 \advance\ctikz@ex@width-\ctikz@ex@hsep
277 \fi
278 \fi
279 }%
280 \ctikz@ex@printcode
281 \ctikz@ex@onlycodeTF
282 {}%
283 {%
284 \if\ctikz@ex@pos b
285 \par
286 \vskip\ctikz@ex@vsep
287 \noindent
288 \ctikz@ex@printresult
289 \fi
290 }%
291 \par
292 \vskip\ctikz@ex@belowskip
293 \ctikz@ex@store\ctikz@ex@dostore
294 \ctikz@ex@execOutsideTF
295 {\global\let\ctikz@ex@codeOutside\enverbBody}%
296 {}%
297 \@endparenv
298 }
299 % handling of the 'exec outside' key. If there are contents inside
300 % \ctikz@ex@codeOutside the key was used and we should rerun an \enverbExecute
301 % (which only works on \enverbBody contents, so we restore those outside of the
302 % environment).
303 \AddToHook{env/ctikzExample/after}
304 {%
305 \ifx\ctikz@ex@codeOutside\@empty
306 \else
307 \let\enverbBody\ctikz@ex@codeOutside
308 \global\let\ctikz@ex@codeOutside\@empty
309 \ctikz@ex@execute
310 \fi
311 \ctikz@ex@dollarTF{\global\let\ctikz@ex@dollarTF\@secondoftwo}{}%
312 }
313 %
314 % --- Style for the code part ---
315 % cyan block, no numbers
316 %
317 \lstdefinestyle{expl-code}{
318 language=[LaTeX]TeX,
319 basicstyle=\small\ttfamily,
320 columns=fullflexible,
321 keepspaces=true,
322 breaklines=true,
323 showstringspaces=false,
324 tabsize=3,
325 numbers=none,
326 frame=single, % using none make framesep=0 which is ugly
327 framerule=0pt,% no frame but keep separation
328 framesep=4pt,
329 backgroundcolor=\color{cyan!10},
330 xleftmargin=0.5em,
331 aboveskip=\bigskipamount,
332 belowskip=\bigskipamount,
333 }
334 \lstset{style=expl-code}
335
336 % in lwarp's warpingprint-false case we need to temporarily change the category
337 % code of $ to be mathshift again. These macros will do that in that case
338 % (they're redefined in `ctikz-lwarp-late.tex`).
339 \newcommand*\pushdollarcat{}
340 \newcommand*\popdollarcat{}
341
342 \newcommand{\email}[1]{\href{mailto:#1}{#1}}
343 \long\def\comment#1{}
344
345 \RequirePackage{framed}
346 \RequirePackage{xtab}
347 \RequirePackage{hyperref}
348 \hypersetup{
349 pdftitle={CircuiTikZ \pgfcircversion\ - manual}, % title
350 pdfauthor={Massimo Redaelli, Stefan Lindner, Stefan Erhardt, Romano Giannetti}, % authors
351 pdfsubject={CircuiTikZ manual}, % subject of the document
352 pdfkeywords={}, % list of keywords
353 colorlinks=true, % false: boxed links; true: colored links
354 linkcolor=blue, % color of internal links
355 citecolor=blue, % color of links to bibliography
356 filecolor=blue, % color of file links
357 urlcolor=blue % color of external links
358 }
359
360 % There are a lot of boxes in the document; let's try to give TeX
361 % a bit of leverage... do not use parindent (which looks strange between examples)
362 % and add stretch between paragraph, to avoid a lot of sections and subsections
363 % starting at the end of the page.
364 \parindent=0pt
365 \parskip=4pt plus 6pt minus 2pt
366 %
367 % names
368 %
369 \def\TikZ{Ti\emph{k}Z}
370 \def\Circuitikz{Circui\TikZ}
371 \def\ConTeXt{Con\TeX t}
372 %
373 % Start of special macros for component descriptions
374 %
375 % draw the shape without affecting anything
376 \newcommand{\drawphantomshape}[1] {%
377 {\tikz [overlay, color=blue] \path (0,0) node[#1]{};}
378 }
379 %% New circuit description macros
380 \newcommand{\twopartbox}[2]{%
381 \leavevmode\null\par\noindent\fbox{\parbox[c]{0.32\linewidth}{#1}\hfill
382 \parbox[c]{0.66\linewidth}{\RaggedRight\hbadness=9500 #2}\par\noindent}%
383 }
384 % filling color for filled-enabled component
385 \colorlet{fillcol}{cyan!30!white}
386 % find the class for the element. Thanks to Symbol 1
387 % https://tex.stackexchange.com/a/501389/38080
388 \def\checkclass#1{%
389 \csname pgf@sh@ma@#1\endcsname
390 \ifdefined\ctikzclass
391 Class: \texttt{\ctikzclass}.%
392 \else
393 No class.%
394 \fi
395 }
396 % description of a node component:
397 % optional star for fillable
398 % optional: scale of the component in the entry
399 % mandatory shape name, description, node text:
400 % optional between (): anchor specification list
401 % optional between []: internal nodes specification list
402 \NewDocumentCommand{\circuitdesc}{s O{1} m m m d() d[]}
403 {
404 \twopartbox{%
405 \begin{circuitikz}[]
406 \IfBooleanTF{#1}{%
407 \draw (0,0) node[#3,scale=#2, fill=fillcol](N){#5};
408 }{
409 % if it's non-fillable, red should not go through
410 \draw (0,0) node[#3,scale=#2,
411 % fill=red
412 ](N){#5};
413 }
414 \IfValueT{#6}{%
415 \foreach \n/\a/\d in {#6} \path(N.\n) \showcoord(\n)<\a:\d>;
416 }
417 \IfValueT{#7}{%
418 \foreach \n/\a/\d in {#7} \path(N-\n) \showcoordb(N-\n)<\a:\d>;
419 }
420 \end{circuitikz}%
421 }{\sloppy
422 {#4, type: node\IfBooleanT{#1}{, fillable}%
423 } (\texttt{node[\detokenize{#3}]\IfValueT{#7}{(N)}\{\detokenize{#5}\}}). \index{#3}%
424 \checkclass{N}%
425 }%
426 }
427 % description of a path-style bipole component:
428 % optional: main name, if different from above
429 % mandatory component name
430 % optional between <>: shapename, if note "nodeshape"
431 % mandatory description, comma separated alias
432 % optional between (): anchor specification list
433 % optional between []: internal nodes specification list
434 % 1 2 3 4 5 6 7 8
435 \NewDocumentCommand{\circuitdescbip}{s o m d<> m m d() d[]}
436 {%
437 \index{#3}%
438 \foreach \i in {#6} {\index{\i|seealso{#3}} }%
439 \twopartbox{%
440 \begin{circuitikz}
441 \IfBooleanTF{#1}{%
442 \draw (0,0) to[#3, name=B, fill=fillcol] (2,0);
443 }{
444 % if it's non-fillable, red should not go through
445 \draw (0,0) to[#3, name=B,
446 %fill=red
447 ] (2,0);
448 }
449 \IfValueT{#7}{%
450 \foreach \n/\a/\d in {#7} \path(B.\n) \showcoord(\n)<\a:\d>;
451 }
452 \IfValueT{#8}{%
453 \foreach \n/\a/\d in {#8} \path(B-\n) \showcoordb(B-\n)<\a:\d>;
454 }
455 \end{circuitikz}%
456 }{\sloppy
457 \texttt{\textbf{#3}}: #5, \texttt{type: path-style\IfBooleanT{#1}{, fillable}%
458 \IfValueT{#8}{, \texttt{name=B}}%
459 \IfValueTF{#4}{, nodename: #4.}{%
460 \IfValueTF{#2}{, nodename: #2shape.%\drawphantomshape{#2shape}%
461 }{, nodename: #3shape.%\drawphantomshape{#3shape}%
462 }}%
463 }
464 \ifthenelse{\equal{#6}{}}{ }{ Aliases: \texttt{#6}. }\checkclass{B}%
465 }%
466 }
467 % command to add the content to the index
468 \NewDocumentCommand{\IndexKey}{O{#2} m}{%
469 \index{\detokenize{#1}|textit}\texttt{#2}%
470 }
471
472 %new environment for grouping descriptions
473 \newenvironment{groupdesc}{\medskip\begingroup}{\endgroup\par\medskip\par\noindent}
474
475 % command to show anchors: (name)<angle>
476 % usage in path: \path (anchor) \coord(anchor)<60>
477 \makeatletter % we use the internal circuitikz base length
478 \def\showcoord(#1)<#2:#3>{%
479 node[circle, red, draw, inner sep=1pt,pin={%
480 [red, inner sep=0.5pt, font=\small,
481 pin distance=#3\pgf@circ@Rlen, pin edge={red, }%
482 ]#2:#1}](#1){}}
483 \def\showcoordb(#1)<#2:#3>{%
484 node[circle, blue, draw, inner sep=1pt,pin={%
485 [blue, inner sep=0.5pt, font=\small,
486 pin distance=#3\pgf@circ@Rlen, pin edge={blue, }%
487 ]#2:#1}](#1){}}
488 \def\showcoordwc[#1](#2)<#3:#4>{%
489 node[circle, #1, draw, inner sep=1pt,pin={%
490 [#1, inner sep=0.5pt, font=\small,
491 pin distance=#4\pgf@circ@Rlen, pin edge={#1, }%
492 ]#3:#2}](#2){}}
493 \makeatother
494 % show anchors of a node component:
495 % optional: options of the circuitikz environment
496 % mandatory node spec, node text
497 % optional between (): anchor specification list
498 \NewDocumentCommand{\showanchors}{O{} m m d()}
499 {
500 \begin{circuitikz}[#1]
501 \draw (0,0) node[#2](N){#3};
502 \IfValueT{#4}{%
503 \foreach \n/\a/\d in {#4} \path(N.\n) \showcoord(\n)<\a:\d>;
504 }
505 \end{circuitikz}%
506 }
507
508
509 \newcommand{\geolrcoord}[2][]{\showanchors[#1]{#2}{text}(north/90/0.4, north east/45/0.4, east/0/0.4,
510 south east/-45/0.4,
511 south/-90/0.4, south west/-135/0.4, west/180/0.4, north west/135/0.4,
512 left/160/0.4, right/30/0.4, center/-120/0.3
513 )
514 }
515
516 \newcommand{\geocoord}[2][]{\showanchors[#1]{#2}{text}(north/90/0.4, north east/45/0.4, east/0/0.4,
517 south east/-45/0.4,
518 south/-90/0.4, south west/-135/0.4, west/180/0.4, north west/135/0.4,
519 center/-120/0.3
520 )
521 }