From e14ce2a2aedfdc10d3e64b5b632a0b5aef10a618 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Sun, 14 May 2023 03:00:45 +0000
Subject: CTAN sync 202305140300

---
 .../contrib/circuitikz/doc/circuitikzmanual.tex    | 94 +++++++++++++++++-----
 1 file changed, 75 insertions(+), 19 deletions(-)

(limited to 'graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex')

diff --git a/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex b/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
index 12c967afc9..983f759a43 100644
--- a/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
+++ b/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
@@ -140,7 +140,8 @@ This package is author-maintained. Permission is granted to copy, distribute and
 	\bottomrule
 \end{tabular}
 \end{table}
-\footnotetext{\ConTeXt\ support was added mostly thanks to Mojca Miklavec and Aditya Mahajan.}
+\footnotetext{\ConTeXt\ support was added mostly thanks to Mojca Miklavec and Aditya Mahajan.\textbf{Please notice} that since \ConTeXt{} switched to the new \texttt{lmtx} engine (March 2023), there can be problems to compile \TikZ{} which some version; in May 2023 the problem has been fixed. Please check \href{https://github.com/circuitikz/circuitikz/issues/706}{this issue} for details.}
+
 
 \noindent \TikZ\ will be automatically loaded; additionally, the \TikZ{} libraries \texttt{calc}, \texttt{arrows.meta}, \texttt{bending}, and \texttt{fpu} are loaded (the last one is used only on demand).
 
@@ -173,11 +174,10 @@ instead of \texttt{circuitikz}. This is also advantageous for ``future resilienc
     \item \texttt{siunitx}, if using \texttt{siunitx} option (better \texttt{v2} or newer).
 \end{itemize}
 
-A similar approach for \ConTeXt\ is available, with the file \texttt{t-circuitikzgit.tex}.
+A similar approach for \ConTeXt\ is available, with the file \texttt{t-circuitikzgit.tex}; the compatibility in this case is not guaranteed, but provided on a \emph{best effort} base.
 
 This manual has been typeset with \Circuitikz{} \pgfcircversion{} (\pgfcircversiondate) on \TikZ{} \pgfversion{} (\pgfversiondate).
 
-
 \subsection{Incompatible packages}\label{sec:incompatible-packages}
 
 \TikZ's own \texttt{circuit} library, which was based on \Circuitikz, (re?)defines several styles used by this library. In order to have them work together you can use the \texttt{compatibility} package option, which basically prefixes the names of all \Circuitikz\ \texttt{to[]} styles with an asterisk.
@@ -246,9 +246,10 @@ The \texttt{use fpu reciprocal} key seems to have no side effects, but given tha
 
 
 \subsection{Incompabilities between versions}\label{sec:incompatible-changes}
-Here, we will provide a list of incompabilities between different versions of \Circuitikz. We will try to hold this list short, but sometimes it is easier to break with old syntax than include a lot of switches and compatibility layers. In general, changes that would invalidate a circuit (changes of polarity of components and so on) are almost always protected by a flag; the same is not true for purely aesthetic changes.
+Here, we will provide a list of incompatibilities between different versions of \Circuitikz. We will try to hold this list short, but sometimes it is easier to break with old syntax than include a lot of switches and compatibility layers. In general, changes that would invalidate a circuit (changes of polarity of components and so on) are almost always protected by a flag; the same is not true for purely aesthetic changes.
 If unsure, you can check the version in your local installation by using the macro \verb!\pgfcircversion{}!.
 \begin{itemize}
+    \item Since version \texttt{1.6.2} \texttt{siunitx}  will \textbf{not}  work anymore with \ConTeXt{} (it was a very poor simulation layer, anyway); it has been disabled in upstream \ConTeXt, in favor of \href{https://www.pragma-ade.nl/general/manuals/units-mkiv.pdf}{its own \texttt{units} module}.
     \item Version \texttt{1.6.0} has a big rewrite of the block's code. In principle the changes are backward-compatible, but there were several bugs (wrong anchors, errors with rotations, and so on) that have been fixed in the process.
     \item Since \texttt{v1.5.1}\footnote{Do not use \texttt{v1.5.0}, it's buggy.} color management (see section~\ref{sec:colors}) and the details of how the shapes are drawn and protected by the external drawing options has changed. There should be no substantial changes to the circuits, though.
     \item The \TikZ{} fix for \texttt{to[...] +(x,y)} behavior (see~\ref{sec:path-relative-coordinates}) uncovered a bug in the positioning of the labels in \Circuitikz{} that had been present since \texttt{v0.8}. So you \textbf{must} upgrade to \texttt{v1.4.1} or better if you have \TikZ{} newer than \texttt{3.1.8} (and you want/need to use the \texttt{+(x,y)} syntax).
@@ -320,7 +321,7 @@ The easiest way to contact the authors is via the official GitHub repository: \u
 
 Circuit people are very opinionated about their symbols. In order to satisfy the individual taste you can set a bunch of package options.
 
-There are arguably way too many options in \Circuitikz, as you can see in the following list. Since version \texttt{1.0}, it is recommended to just use the basic ones --- voltage directions (you \textbf{should} specify one of them), \texttt{siunitx}, the global style (\texttt{american} or \texttt{european}) and use styles (see~\ref{sec:styling}) for the remaining options.
+There are arguably way too many options in \Circuitikz, as you can see in the following list. Since version \texttt{1.0}, it is recommended to just use the basic ones --- voltage directions (you \textbf{should} specify one of them), \texttt{siunitx} (only for \LaTeX{}), the global style (\texttt{american} or \texttt{european}) and use styles (see~\ref{sec:styling}) for the remaining options.
 
 The standard options are set by historical reason, and reflect the preferences of the author that introduced them. For example you get this:
 
@@ -374,7 +375,7 @@ Feel free to load the package with your own cultural options:
         \item \texttt{europeangfsurgearrester}: uses rectangular gas filled surge arresters, as per european standards;
         \item \texttt{european}: equivalent to \texttt{europeancurrents}, \texttt{europeanvoltages}, \texttt{europeanresistors}, \texttt{europeaninductors}, \texttt{europeanports}, \texttt{europeangfsurgearrester};
         \item \texttt{american}: equivalent to \texttt{americancurrents}, \texttt{americanvoltages}, \texttt{americanresistors}, \texttt{americaninductors}, \texttt{americanports}, \texttt{americangfsurgearrester};
-        \item \texttt{siunitx}: integrates with \texttt{SIunitx} package. If labels, currents or voltages are of the form \verb!#1<#2>! then what is shown is actually \verb!\SI{#1}{#2}!;
+        \item \texttt{siunitx}: integrates with \texttt{SIunitx} package. If labels, currents or voltages are of the form \verb!#1<#2>! then what is shown is actually \verb!\SI{#1}{#2}! (not supported in \ConTeXt; it has been disabled in upstream \ConTeXt, in favor of \href{https://www.pragma-ade.nl/general/manuals/units-mkiv.pdf}{its own \texttt{units} module});
         \item \texttt{nosiunitx}: labels are not interpreted as above;
         \item \texttt{fulldiode}: the various diodes are drawn \emph{and} filled by default, i.e. when using styles such as \texttt{diode}, \texttt{D}, \texttt{sD}, \ldots Other diode styles can always be forced with e.g. \texttt{Do}, \texttt{D-},  \ldots
         \item \texttt{strokediode}: the various diodes are drawn \emph{and} stroke by default, i.e. when using styles such as \texttt{diode}, \texttt{D}, \texttt{sD}, \ldots Other diode styles can always be forced with e.g. \texttt{Do}, \texttt{D*},  \ldots
@@ -401,10 +402,9 @@ Feel free to load the package with your own cultural options:
                 \item \texttt{EFvoltages} (meaning Electric Field voltages): the arrow is in the direction of the electric field, like in \texttt{nooldvoltagedirection}, but batteries are fixed;
             \end{itemize}
             If none of these option are given, the package will default to \texttt{nooldvoltagedirection}. The behavior is also selectable circuit by circuit with the \texttt{voltage dir} style.
-        \item \texttt{betterproportions}\footnote{May change in the future!}: nicer proportions of transistors in comparision to resistors;
+        \item \texttt{betterproportions}\footnote{May change in the future!}: nicer proportions of transistors in comparision to resistors; notice that this option is superseded by styles and it's kept just for compatibility, do not use it in new projects;
     \end{itemize}
 
-
     The old options in the singular (like \texttt{american voltage}) are still available for compatibility, but are discouraged.
 
     \medskip
@@ -416,7 +416,7 @@ Feel free to load the package with your own cultural options:
 
     \medskip
 
-    In \ConTeXt\ the options are similarly specified: \texttt{current= european|american}, \texttt{voltage= european|american},  \texttt{resistor= american|european},  \texttt{inductor= cute|american|european}, \texttt{logic= american|european}, \texttt{siunitx= true|false}, \texttt{arrowmos= false|true}.
+    In \ConTeXt\ the options are similarly specified: \texttt{current= european|american}, \texttt{voltage= european|american},  \texttt{resistor= american|european},  \texttt{inductor= cute|american|european}, \texttt{logic= american|european}, \texttt{arrowmos= false|true}.
 
 } %\stop the \sloppy processing
 
@@ -3238,8 +3238,37 @@ For a more powerful (and elegant) way you can use the crossing nodes:
 
 Notice that the \texttt{plain crossing} and the \texttt{jump crossing} have a small gap in the straight wire, to enhance the effect of crossing (as a kind of shadow).
 
+\subsubsection{Crossing customization}
+
 The size of the crossing elements can be changed with the key \texttt{bipoles/crossing/size} (default 0.2).
 
+While the horizontal line will be drawn with the current path values, you can change the style of the vertical line\footnote{Suggested by \href{https://github.com/circuitikz/circuitikz/issues/704}{user lkjell on GitHub}, implemented in \texttt{v1.6.2}.} in a similar way to the one used for transistor's bodydiodes, by setting keys with the \verb!\ctikzset! command under the \texttt{crossing vertical} hierarchy. The available keys are:
+
+\begin{center}
+    \begin{tabular}{>{\ttfamily}l>{\ttfamily}lp{0.5\linewidth}}
+        \toprule
+     parameter &  default & description  \\
+     \midrule
+     relative thickness & 1.0 & multiply the default thickness (which is the same of the \texttt{choke} component).\\
+     color & default & stroke color: \texttt{default} is the same as the component. \\
+     dash & default & dash pattern: \texttt{default} means not to change the setting for the component; \texttt{none} means unbroken line; every other input is a dash pattern.\footnotemark \\
+        \bottomrule
+    \end{tabular}
+    \footnotetext{Follows the syntax of the pattern sequence \texttt{\textbackslash pgfsetdash} --- see \TikZ{} manual for details; phase is always zero. Basically you pass pairs of dash-length -- blank-length dimensions, see the examples.}
+\end{center}
+
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+    \begin{circuitikz}[every node/.append style={scale=2}]
+        \draw (0,2) node[jump crossing](A){};
+        \begin{scope}
+            \ctikzset{crossing vertical/.cd, color=red, dash={{2pt}{1pt}}}
+            \draw (0,1) node[jump crossing](B){};
+        \end{scope}
+        \ctikzset{crossing vertical/dash=none}
+        \draw[densely dotted, blue] (0,0) node[plain crossing](B){};
+    \end{circuitikz}
+\end{LTXexample}
+
 \subsection{Arrows}\label{sec:arrows}
 
 These are pseudo-arrows used in lot of places in the packages (for transistors, flows, currents, and so on). The first three arrows are magnified by a factor~3 in the boxes below; for the \texttt{trarrow}, the anchor \texttt{tip} is exactly on the tip and \texttt{btip} is slightly receded.
@@ -4224,7 +4253,7 @@ The position of the circle on collector and emitter by default is the one shown
      \midrule
      relative thickness & 1.0 & multiply the class thickness \\
      color & default & stroke color: \texttt{default} is the same as the component \\
-     dash & none & dash pattern: none means unbroken line\footnotemark \\
+     dash & default & dash pattern: none means solid line, default means keep the global pattern\footnotemark \\
      partial borders & none & draw only part of the circle border: none means draw all \\
      partial border dash & \{\{2pt\}\{2pt\}\} & dash pattern used in partial borders \\
         \bottomrule
@@ -4302,7 +4331,7 @@ The dashed line pattern can be changed by setting the key \texttt{transistor cir
 
 \subsubsection{Transistor bodydiode customization}\label{sec:trans-bodydiode-custom}
 
-You can change the style of the bodydiode\footnote{Suggested by \href{https://tex.stackexchange.com/questions/653348/drawing-mosfet-bodydiode-dashed}{user Alex Ghilas on TeX.SX}, implemented in \texttt{v1.5.4}.} in a similar way to the one used for circles (albeit with less options), by setting keys with the \verb!\ctikzset! command (or, like in the following example, directly in the node instantiation) under the \texttt{transistor bodydiode} hierarchy. The available keys are:
+You can change the style of the bodydiode\footnote{Suggested by \href{https://tex.stackexchange.com/questions/653348/drawing-mosfet-bodydiode-dashed}{user Alex Ghilas on TeX.SX}, implemented in \texttt{v1.5.4}; \texttt{scale} suggested by \href{https://github.com/circuitikz/circuitikz/issues/703}{user \texttt{@sputeanus} on GitHub} and added in version \texttt{1.6.2}.} in a similar way to the one used for circles (albeit with less options), by setting keys with the \verb!\ctikzset! command (or, like in the following example, directly in the node instantiation) under the \texttt{transistor bodydiode} hierarchy. The available keys are:
 
 \begin{center}
     \begin{tabular}{>{\ttfamily}l>{\ttfamily}lp{0.5\linewidth}}
@@ -4311,13 +4340,14 @@ You can change the style of the bodydiode\footnote{Suggested by \href{https://te
      \midrule
      relative thickness & 1.0 & multiply the class thickness \\
      color & default & stroke color: \texttt{default} is the same as the component \\
-     dash & default & dash pattern: \texttt{default} means not to change the setting for the component; \texttt{none} means unbroken line; every other input is a dash pattern.\footnotemark \\
+     dash & default & dash pattern: \texttt{default} means not to change the setting for the component; \texttt{none} means unbroken line; every other input is a dash pattern\footnotemark \\
+     scale & 0.3 & scale of the diode, with respect to the basic (not scaled) diode dimension.\\
         \bottomrule
     \end{tabular}
     \footnotetext{Follows the syntax of the pattern sequence \texttt{\textbackslash pgfsetdash} --- see \TikZ{} manual for details; phase is always zero. Basically you pass pairs of dash-length -- blank-length dimensions, see the examples.}
 \end{center}
 
-The following is a quite extensive example. Obviously, a good strategy in this case is to define styles for the options.
+The following is a quite extensive example. Obviously, a good strategy in this case is to define styles for the options, or, better, set the option in your style file or in the preamble (for coherency).
 
 \begin{LTXexample}[varwidth=true, pos=t, basicstyle=\small\ttfamily]
 \begin{tikzpicture}[red solid thin bodydiode/.style={bodydiode,
@@ -4327,12 +4357,14 @@ The following is a quite extensive example. Obviously, a good strategy in this c
     \draw (0,0) node (mosfet1) [nigfete,anchor=D,bodydiode] {$Q_1$};
     \draw[densely dashed]  (3,0) node (mosfet1) [nigfete,anchor=D,bodydiode] {$Q_2$};
     \draw (6,0) node (mosfet1) [nigfete,anchor=D,bodydiode,
-        circuitikz/transistor bodydiode/color=gray] {$Q_3$};
+        circuitikz/transistor bodydiode/color=gray,
+        circuitikz/transistor bodydiode/scale=0.2] {$Q_3$};
     \draw (0,-2) node (mosfet1) [nigfete,anchor=D,bodydiode,
         circuitikz/transistor bodydiode/dash={{2pt}{1pt}}]  {$Q_4$};
     \draw[densely dashed]  (3,-2) node (mosfet1) [nigfete,anchor=D,
         red solid thin bodydiode] {$Q_5$};
-    \ctikzset{transistor bodydiode/relative thickness=.5}% from now on, in scope
+    \ctikzset{transistor bodydiode/relative thickness=.5,
+        transistor bodydiode/scale=0.6}% from now on, in scope
     \draw[densely dotted] (6,-2) node (mosfet1) [nigfete,anchor=D,bodydiode,
           circuitikz/transistor bodydiode/dash=none] {$Q_6$};
     \path (7,0); %% adjust bounding box (node text is outside it!)
@@ -5071,6 +5103,29 @@ Transformers also inherit the \texttt{inductors/scale} (see~\ref{sec:tweak-l}) a
 
 Transformers core line distance is specified by the parameter \texttt{quadpoles/transformer core/core width} (default \texttt{0.05}) and the thickness of the lines follows the choke one; in other words, you can set it changing \texttt{bipoles/cutechoke/cthick}.
 
+You can change the style of the core lines\footnote{Suggested by \href{https://github.com/circuitikz/circuitikz/issues/702}{user myzinsky on GitHub}, implemented in \texttt{v1.6.2}.} in a similar way to the one used for transistor's bodydiodes, by setting keys with the \verb!\ctikzset! command under the \texttt{transformer core} hierarchy. The available keys are:
+
+\begin{center}
+    \begin{tabular}{>{\ttfamily}l>{\ttfamily}lp{0.5\linewidth}}
+        \toprule
+     parameter &  default & description  \\
+     \midrule
+     relative thickness & 1.0 & multiply the default thickness (which is the same of the \texttt{choke} component).\\
+     color & default & stroke color: \texttt{default} is the same as the component. \\
+     dash & default & dash pattern: \texttt{default} means not to change the setting for the component; \texttt{none} means unbroken line; every other input is a dash pattern.\footnotemark \\
+        \bottomrule
+    \end{tabular}
+    \footnotetext{Follows the syntax of the pattern sequence \texttt{\textbackslash pgfsetdash} --- see \TikZ{} manual for details; phase is always zero. Basically you pass pairs of dash-length -- blank-length dimensions, see the examples.}
+\end{center}
+
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+\begin{circuitikz}[]
+    \draw (0,0) node[transformer core](A){};
+    \ctikzset{transformer core/.cd, relative thickness=2, color=red, dash={{4pt}{2pt}}}
+    \draw (2,0) node[transformer core](B){};
+\end{circuitikz}
+\end{LTXexample}
+
 Another very useful parameter is \texttt{quadpoles/*/inner} (default \texttt{0.4}) that determine which part of the component is the ``vertical'' one. So, setting that parameter to 1 will eliminate the horizontal part of the component (obviously, to maintain the general aspect ratio you need to change the width also):
 
 
@@ -6738,13 +6793,14 @@ to obtain:
 \verb|\ctikztextnot{}| is a small utility macro to set a overbar to a text, like \ctikztextnot{RST} (created by \verb|\ctikztextnot{RST}|).
 
 
-By default, the following flip-flops are defined:
+By default, the following flip-flops are defined, as well as a support shape for the clock wedge:
 \begin{groupdesc}
     \circuitdesc*{latch}{D-type latch}{}
     \circuitdesc*{flipflop SR}{flip-flop SR}{}
     \circuitdesc*{flipflop D}{Edge-triggered synchronous flip-flop D}{}
     \circuitdesc*{flipflop T}{Edge-triggered synchronous flip-flop T}{}
     \circuitdesc*{flipflop JK}{Edge-triggered synchronous flip-flop JK}{}
+    \circuitdesc{clockwedge}{clock wedge shape}{text}(center/180/0.6, nw/90/0.2, sw/-90/0.2, right/45/0.5)
 \end{groupdesc}
 
 If you prefer that the negated output is labelled \texttt{Q} and a dot indicating negation is shown, you can add the \texttt{dot on notQ} key:
@@ -7475,7 +7531,7 @@ You can add ``decorations'' to the path-style components; there are basically fi
 \end{LTXexample}
 
 
-Long names/styles for the bipoles can be used, of course, and there is a special syntax (that works only in simple cases --- use it with caution!) if you load the package with the `siunitx` options:
+Long names/styles for the bipoles can be used, of course, and there is a special syntax (that works only in simple cases, and olny with \LaTeX{} --- use it with caution!) if you load the package with the `siunitx` options:
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}\draw
@@ -7603,7 +7659,7 @@ Notice that you \textbf{can't use} the compact \texttt{<...>} notation for \text
 
 Since \texttt{v1.3.6} you have the same possibility with the \texttt{annotation} (just use \texttt{a2=...}, \verb|a2_=...|, \texttt{a2 valign} and so on. Notice that the default position for stacked annotation is \texttt{v2 halign=l}.
 
-The \texttt{l2} and \texttt{a2} will only work in LaTeX because they use a \texttt{tabular} environment in their implementation. For plain TeX and ConTeXt you have to use \texttt{l} and \texttt{a} and build the stack of labels externally.
+The \texttt{l2} and \texttt{a2} will only work in LaTeX because they use a \texttt{tabular} environment in their implementation. For plain TeX and \ConTeXt{} you have to use \texttt{l} and \texttt{a} and build the stack of labels externally.
 
 %
 % This is hacky --- better not to publish it for now
@@ -8801,7 +8857,7 @@ Another possibility is to have the arrow length based on the length of the compo
 
 \subsection{Integration with {\ttfamily siunitx}}
 
-If the option {\ttfamily siunitx} is active\footnote{This option is still experimental --- personally (Romano) I would advise using the normal \texttt{\textbackslash SI\{\}\{\}} syntax.}  (and \emph{not} in \ConTeXt), then the following are equivalent:
+If the option {\ttfamily siunitx} is active\footnote{This option is still experimental --- personally (Romano) I would advise using the normal \texttt{\textbackslash SI\{\}\{\}} syntax, or the \texttt{\textbackslash qty\{\}\{\}} one for \texttt{siunitx} \texttt{v3} and newer.}, then the following are equivalent (this will \textbf{not} work in \ConTeXt{}, it has been disabled in upstream \ConTeXt, in favor of \href{https://www.pragma-ade.nl/general/manuals/units-mkiv.pdf}{its own \texttt{units} module}):
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
-- 
cgit v1.2.3

