From 55ae461252a599d6bc951065a37c16a8971fc560 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Thu, 15 Jul 2021 03:01:01 +0000
Subject: CTAN sync 202107150300

---
 .../contrib/circuitikz/doc/circuitikzmanual.tex    | 116 ++++++++++++++++++---
 1 file changed, 102 insertions(+), 14 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 10a4a9b483..d2d3ee394b 100644
--- a/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
+++ b/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
@@ -46,6 +46,7 @@
 	% pdflatex
 		\usepackage[T1]{fontenc}
 		\usepackage[utf8]{inputenc}
+        \usepackage{lmodern}
 		% \usepackage{babel}
 	\fi
 \fi
@@ -192,6 +193,7 @@ Correcting this will need a big rewrite of the path routines, and although the a
 
 This same issue create a lot of problem of compatibility between \Circuitikz{} and the new \texttt{pic} Ti\emph{k}Z feature, so basically don't put components into \texttt{pic}s.
 
+
 \subsection{Scale factors inaccuracies}\label{sec:usefpu}
 
 Sometimes, when using fractional scaling factors and big values for the coordinates, the basic layer inaccuracies from \TeX{} can bite you, producing results like the following one:
@@ -224,7 +226,9 @@ The \texttt{use fpu reciprocal} key seems to have no side effects, but given tha
 Here, we will provide a list of incompabilitys between different version of \Circuitikz. We will try to hold this list short, but sometimes it is easier to break with old syntax than including 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 at your local installation using the macro \verb!\pgfcircversion{}!.
 \begin{itemize}
-    \item \texttt{v1.4.0} introduce the rollback system for the package when using LaTeX; that (at least in principle) should be completely backeard-compatible.
+    \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 is 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).
+    \item There have been changes in (internal) parameters for capacitors in \texttt{v1.4.1}; now to change them you should use the style interface (see~\ref{sec:capacitors-styling}).
+    \item \Circuitikz{} \texttt{v1.4.0} introduce the rollback system for the package when using LaTeX; that (at least in principle) should be completely backward-compatible.
     \item The path construction in \texttt{v1.4.0} has been changed a bit (again). The change shouldn't break any circuit and correct a behavior that should have been fixed with the \texttt{v1.2.1} change (see below).
     \item Version 1.3.6 fixes several problems with the stacked labels; the most important change is that now the bracing of arguments is respected as in version 1.3.0 for the other labels. The special treatment in stacked labels (and only in stacked labels!) for the (still experimental\footnote{and, really, not advised\dots}) \texttt{siunitx} compact syntax \texttt{<...>} has been removed: it was completely buggy before, and silently ignored, now will throw an error.
     \item Version 1.3.3 fixes the direction of the arrows in tunable elements; before this version, they were more or less random, now the arrow goes from bottom left to top right. You have the option to go back to the old behavior with \texttt{\textbackslash ctikzset\{bipoles/fix tunable direction=false\}}. As a compensation for the fuss, now the arrows are configurable. To learn more, see the FAQ:~\ref{faq:tunable-arrow}.
@@ -542,10 +546,12 @@ In this snippet, notice that the only absolute coordinate is the first one; that
 with the same result.
 
 The second step is to position the op-amp. We can check the manual and see the component's description (section~\ref{sec:amplifiers}):
+
 \begin{groupdesc}
     \circuitdesc*{op amp}{Operational amplifier}{}( +/180/0.2, -/180/0.2, out/0/
 0.2, up/90/0.2, down/-90/0.2 )
 \end{groupdesc}
+
 where we notice the type of the component (it is a node-type component, so we have to use
 \texttt{node} to position it) and the available ``anchors'': points we can use to position the shape or to connect to. Not all the anchors are \emph{explicitly} printed in the description box; you should read further in the manual and you'll see a ``\emph{component} anchors'' (\ref{sec:amplifiers-anchors}) section with the relevant information.
 
@@ -655,7 +661,7 @@ And we can use it like in the following:
     \node [ocirc] at (OA1-in) {};
     \node [above] at (OA1-in) {$v_i$};
     \node [ocirc] at (OA2-out){};
-    \node [ocirc] at (OA1-in) {$v_o$};
+    \node [above] at (OA2-out) {$v_o$};
     \draw (OA1-out) -| (OA2-in);
 \end{circuitikz}
 \end{LTXexample}
@@ -786,7 +792,10 @@ This is the final circuit, with the nodes still marked:
 }}
 \def\killdepth#1{{\raisebox{0pt}[\height][0pt]{#1}}}
 \def\coord(#1){coordinate(#1)}
-\def\coord(#1){coordinate(#1) node[circle, red, draw, inner sep=1pt,pin={[red, overlay, inner sep=0.5pt, font=\tiny, pin distance=0.1cm, pin edge={red, overlay,}]45:#1}](#1-node){}}
+\def\coord(#1){coordinate(#1) node[circle, red, draw, inner sep=1pt,
+    pin={[red, overlay, inner sep=0.5pt, font=\tiny, pin distance=0.1cm,
+    % we reset the arrow in pin edge to avoid carrying over the path one!
+    pin edge={red, overlay,-}]45:#1}](#1-node){}}
 \begin{circuitikz}[american, ]
     \draw (0,0) node[nmos,](Q1){\killdepth{Q1}};
     \draw (Q1.S) to[R, l2^=$R_S$ and \SI{5}{k\ohm}] ++(0,-3) node[vee](VEE){$V_{EE}=\SI{-10}{V}$}; %define VEE level
@@ -824,7 +833,10 @@ This is the final circuit, with the nodes still marked:
 }}
 \def\killdepth#1{{\raisebox{0pt}[\height][0pt]{#1}}}
 \def\coord(#1){coordinate(#1)}
-\def\coord(#1){coordinate(#1) node[circle, red, draw, inner sep=1pt,pin={[red, overlay, inner sep=0.5pt, font=\tiny, pin distance=0.1cm, pin edge={red, overlay,}]45:#1}](){}}
+\def\coord(#1){coordinate(#1) node[circle, red, draw, inner sep=1pt,
+    pin={[red, overlay, inner sep=0.5pt, font=\tiny, pin distance=0.1cm,
+    % we reset the arrow in pin edge to avoid carrying over the path one!
+    pin edge={red, overlay,-}]45:#1}](#1-node){}}
 \begin{circuitikz}[american, ]
     \draw (0,0) node[nmos,](Q1){\killdepth{Q1}};
     \draw (Q1.S) to[R, l2^=$R_S$ and \SI{5}{k\ohm}] ++(0,-3) node[vee](VEE){$V_{EE}=\SI{-10}{V}$}; %define VEE level
@@ -1240,18 +1252,23 @@ The above diagram has been obtained with the code:
 \showbordersfornode{capacitivesens}
 \end{lstlisting}
 
+\endgroup
+
 \subsubsection{Relative coordinates}\label{sec:path-relative-coordinates}
 
-As \href{https://github.com/circuitikz/circuitikz/issues/460}{noticed by user \texttt{septatrix}}, although relative coordinates after a component work as expected when using \texttt{++(x,y)}-style coordinates,
-that is not true for the \texttt{+(x,y)}-style coordinates (which are supposed to set a temporary relative coordinate and then going back to the starting point).
+As \href{https://github.com/circuitikz/circuitikz/issues/460}{noticed by user \texttt{septatrix}},
+although full relative coordinates after a component work as expected when using \texttt{++(x,y)}-style coordinates,
+often there are problems when using
+the \texttt{+(x,y)}-style coordinates (which are supposed to set a temporary relative coordinate and then going back to the starting point).
 
-This behavior, although not optimal, was standard in \texttt{to} operation in plain \TikZ{} before version 3.1.8; it was changed by Henri Menke in later versions. Notice that the change revealed a problem in \Circuitikz{} that should hopefully fixed in \texttt{v1.2.7}.
+These kind of coordinate have in practice little use for the building of circuits, so have been only (very) lightly tested; avoid them if you can --- the behavior will depend not only on the \Circuitikz{} version, but also on the \TikZ{} layer underneath.
+
+This behavior, although not optimal, was standard in \texttt{to} operation in plain \TikZ{} before version 3.1.8; it was changed by Henri Menke in later versions. Notice that the change revealed a problem in \Circuitikz{} that should hopefully fixed in \texttt{v1.4.1}; for more details see \href{https://github.com/circuitikz/circuitikz/issues/569}{this issue on GitHub}.
 
 You can see from the example below (notice the blue curve using a spline line). If all the vertical lines are at the left, the manual has been compiled with a new \Circuitikz{} and \TikZ. Otherwise, the red and/or blue curve will have the vertical line at the right (which in principle is wrong).
 
 In the last (green) example, you can see a workaround using local path and the key \texttt{current point is local} that will work for older (and do not create problem in newer) versions.
 
-
 \begin{LTXexample}[varwidth=true, pos=t]
 Plotted using Ti\emph{k}Z version \pgfversion{} and CircuiTi\emph{k}Z version \pgfcircversion{}.
 
@@ -1273,7 +1290,6 @@ Plotted using Ti\emph{k}Z version \pgfversion{} and CircuiTi\emph{k}Z version \p
 \end{tikzpicture}
 \end{LTXexample}
 
-\endgroup
 
 \subsubsection{Customization}
 \label{sec:components-size}
@@ -2081,7 +2097,8 @@ You can change that globally or locally, as ever. The tip specification is the o
     \footnotetext{suggested by \href{https://github.com/circuitikz/circuitikz/issues/515}{Mayeul Cantan}}
 \end{groupdesc}
 
-Ferroelectric capacitors are fillable because that could be used to show the state of the hysteresis of the component.
+Capacitors are fillable since \texttt{v1.4.1}; this is normally just a stylistic option but in the case of
+ferroelectric capacitors that could be used to show the state of the hysteresis of the component.
 
 \begin{LTXexample}[varwidth]
 \begin{tikzpicture}[]
@@ -2104,12 +2121,29 @@ There is also the (deprecated\footnote{Thanks to \href{https://tex.stackexchange
 
 For capacitive sensors, see section~\ref{sec:sensors-anchors}.
 
-\subsubsection{Capacitors customizations}
+\subsubsection{Capacitors customizations}\label{sec:capacitors-styling}
 
 You can change the scale of the capacitors by setting the key \texttt{capacitors/scale}  to something different from the default \texttt{1.0}. For thickness, you can use the same keys (applied to the \texttt{capacitors} class) as for resistors in~\ref{sec:resistor-thickness}.
 
 Variable capacitors arrow tips follow the settings  of resistors, see section~\ref{sec:tunablearrows}.
 
+The relative size of the capacitors is a bit of a mixed bag, because each one has historically different internal parameters that makes maintaining coherence quite difficult. In \texttt{v1.4.1} this has changed and now you can use styling options to change the way the capacitors look. The main parameter you can set is \texttt{capacitors/width} (default \texttt{0.2}), which controls the standard distance between plates. That will change all the components (notice that the \texttt{piezoelectric} component is twice the size of a standard capacitor).
+
+The \texttt{capacitors/height} key is available also to set the height of the capacitor; the default is \texttt{0.6} for most of the capacitors, but \texttt{0.5} for electrolytic ones and \texttt{0.7} for piezoelectric. When used, it will set all of them at the same value, which is a good thing.
+
+If you want that only a specific kind of capacitor has a different value for a key, you can always use a style which will have a local scope, as in the following example.
+
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+    \begin{tikzpicture}
+        \draw (0,1) to [C] ++(1,0) to [elko] ++(1,0);
+        \ctikzset{capacitors/width=0.15, capacitors/height=0.5}
+        \draw (0,0) to [C] ++(1,0) to [elko] ++(1,0);
+        \tikzset{big elko/.style={elko=#1, capacitors/width=0.3}}
+        \draw (0,-1) to [C] ++(1,0) to[big elko] ++(1,0);
+    \end{tikzpicture}
+\end{LTXexample}
+
+
 \subsubsection{Inductors}
 
 If the \texttt{cuteinductors} option is active (default behaviour), or the style \texttt{[cute inductors]} is used, the inductors are displayed as follows:
@@ -3028,6 +3062,34 @@ Moreover, you have the arrow tip \texttt{latexslim} which is an arrow similar to
 \end{circuitikz}
 \end{LTXexample}
 
+\subsubsection{Generic Tunable Arrows}
+
+The basic passive components (resistors, capacitors and inductors) come with a ``tunable version'' (see for example~\ref{sec:tunablearrows}) that conveys the information that their value is adjustable. For generic components you can obtain a similar effect with the extra macro \verb|\ctikztunablearrow|, introduced in version \texttt{1.4.1}. The macro should be called as:
+\begin{quote}
+    \ttfamily
+    \textbackslash ctikztunablearrow[\emph{extra options}]\{\emph{thickness}\}\{\emph{length}\}\{\emph{angle}\}\{\emph{name}\}
+\end{quote}
+where \emph{extra options} is an optional argument with generic \TikZ{} keys, \emph{thickness} is the relative thickness (referred to the current line width when the macro is invoked), \emph{length} is the length of the arrow with respect to the diagonal size of the component, \emph{angle} is the inclination with respect to the normal direction of the component\footnote{which is the left-to-right direction of the component when shown in the component box in this manual.}, and finally \emph{name} is the reference name of the bipole or node.
+
+The arrows are the ones set with the keys \texttt{tunable start arrow} and \texttt{tunable end arrow} (to maintain coherency across the circuit), but you can override them in the \emph{extra options} argument as shown in the following example.
+
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+\begin{circuitikz}
+    \draw (0,0) node[tlground]{} to[sV, name=A] ++(0,3)
+        node[op amp, anchor=+](B){};
+    \ctikztunablearrow{1}{1.2}{30}{A}
+    \ctikzset{tunable start arrow={Bar},
+        tunable end arrow={Stealth}}
+    \ctikztunablearrow[color=green,
+        {Latex[reversed]}-Circle]{1}{1.2}{90}{A}
+    \ctikztunablearrow[color=blue, densely dashed]{1}{1.2}{-30}{A}
+    \begin{scope}[transparency group, opacity=0.5]
+        \ctikztunablearrow[red, shorten <=3mm]{6}{0.8}{110}{B}
+    \end{scope}
+\end{circuitikz}
+\end{LTXexample}
+
+Notice also the need to force a transparency group if you want a semitransparent arrow.
 \subsection{Terminal shapes}\label{sec:terminals}
 
 These are the so-called ``bipole nodes'' shapes, or poles (see section~\ref{sec:bipole-nodes}). These nodes are always filled; the ``open'' versions (starting with an \texttt{o}) are by default filled with the color specified by the key \texttt{open nodes fill} (by default \texttt{white}), but you can override locally it with the \texttt{fill} parameter.
@@ -7430,7 +7492,7 @@ pin={[draw, blue, font=\tiny, align=left]#1:{#2 \\ dir: \ctikzgetdirection{#2#3}
 
 \subsection{Advanced voltages, currents and flows}\label{sec:vif-anchors}
 
-Since version \texttt{1.2.1}, it is possible to access the anchors of the ``ornaments'' --- voltage, current and flows, together with some additional information that makes it possible to personalize them.
+Since version \texttt{1.2.1}\footnote{some options have been added in \texttt{v1.4.1}}, it is possible to access the anchors of the ``ornaments'' --- voltage, current and flows, together with some additional information that makes it possible to personalize them.
 Normally, voltages and flow and currents are drawn into the path of the bipoles, so that it is not possible, for example, to change the line type or color of the arrows, or the type of arrows\footnote{in regular voltages, the arrows are not real \TikZ{} arrows, but the auxiliary arrow shapes of \Circuitikz{}}. Access to the anchors allows to do all this things, and more.
 
 For example, you can do something like this:
@@ -7461,6 +7523,30 @@ Or, for example, to have a different voltage style; normally you would define a
 \end{circuitikz}
 \end{LTXexample}
 
+Since \texttt{v1.4.1} you can also keep the voltage, current and flow labels and suppress the output of the symbols (arrows or plus/minus depending on the style) with the keys \texttt{no v symbols}, \texttt{no i symbols}, \texttt{no f symbols} (there are also the corresponding \texttt{v symbols}, \texttt{i symbols} and \texttt{f symbols} in case you want to switch the behavior off/on  globally). This for example simplify an often requested feature, like having all the current in one color and the voltages in another one, which is not possible natively because the arrows are part of the same path One possible implementation is the following one:
+
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+\newcommand{\iarronly}[1]{% name
+    \node [currarrow, color=red, anchor=center,
+    rotate=\ctikzgetdirection{#1-Iarrow}] at (#1-Ipos) {};
+}
+\newcommand{\varronly}[1]{% name
+    \draw [color=blue] (#1-Vfrom) .. controls (#1-Vcont1)
+        and (#1-Vcont2)..  (#1-Vto) node [currarrow,
+        sloped, anchor=tip, allow upside down,pos=1]{};
+}
+\begin{circuitikz}[]
+    \ctikzset{!vi/.style={no v symbols, no i symbols}}
+    \ctikzset{bipole voltage style/.style={color=blue},
+        bipole current style/.style={color=red}}
+    \draw (120:6) to[R, *-,  name=R, v^=$v_R$, !vi]
+        (120:3) to[short, i=$i_R$, name=SR, !vi] (0,0);
+    \draw (180:4) to[L, o-, l=$L$, name=L2, v=$v_L$, !vi]
+        (180:2) to[V, -*, name=V2, v_=$v_2$, !vi] (0:0);
+    \iarronly{SR}\varronly{R}\varronly{L2}\varronly{V2}
+\end{circuitikz}
+\end{LTXexample}
+
 \subsubsection{Activating the anchors}
 
 You will have access to the anchors for voltages, currents and flows when, in the bipole, you have both a \texttt{v}, \texttt{i}, \texttt{f} specification (one or more of them) \textbf{and} a \texttt{name} key, to give the bipole a name. Otherwise, the anchors and the associated functions are not defined.
@@ -7500,7 +7586,7 @@ The meaning of the anchors is the following:
 \item
     \texttt{Vlab} is where the text label for the voltage is normally positioned. The anchor used for such label is available using the auxiliary macro \verb|\ctikzgetanchor| (see below)
 \item
-    \texttt{Ipos} and \texttt{Fpos} are the position for the arrowhead or the small flow arrow (which is a \texttt{currarrow} or \texttt{flowarrow} node normally) is positioned, respectively. The label is then added to the correct side of it using the anchor available via \verb|\ctikzgetanchor|.\footnote{In this case, the exact position of the label is not available if you do not position the element, for this there is no \texttt{Flab} or \texttt{Ilab} coordinate; you have to use the \texttt{Fpos} and \texttt{Ipos} coordinate with the corresponding \texttt{Ilab} and \texttt{Flab} anchors.}
+    \texttt{Ipos} and \texttt{Fpos} are the position for the arrowhead or the small flow arrow (which is a \texttt{currarrow} or \texttt{flowarrow} node normally) is positioned, respectively. The label is then added to the correct side of it using the anchor available via \verb|\ctikzgetanchor| (see below,~\ref{sec:advances-aux-info}). In this case, the exact position of the label is not available if you do not position the element, for this there is no \texttt{Flab} or \texttt{Ilab} coordinate; you have to use the \texttt{Fpos} and \texttt{Ipos} coordinate with the corresponding \texttt{Ilab} and \texttt{Flab} anchors.
 \end{itemize}
 
 Changing the options of the elements, will change the anchors acoordingly:
@@ -7579,12 +7665,13 @@ Finally, as ever, generators are treated differently, but you have all your anch
     }
 \end{circuitikz}
 
-\subsubsection{Auxiliary information}
+\subsubsection{Auxiliary information}\label{sec:advances-aux-info}
 
 When the anchors are activated, there are additional macros that you can use:
 \begin{itemize}
     \item \texttt{\textbackslash ctikzgetanchor\{\emph{<name>}\}\{\emph{<anchor>}\}}: \emph{name} is the name of the bipole, and \emph{anchor} can be \texttt{Vlab}, \texttt{Fpos} or \texttt{Ipos}. This macro expands to the normal anchor position (something like \texttt{north}, \texttt{south west}). Notice that if you have not activated the corresponding anchor, the content of this macro is not specified. It could be equivalent to \verb|\relax| (basically, empty) or contains the anchor of a bipole with the same name from another drawing --- it's a global macro like the coordinates.
     \item \texttt{\textbackslash ctikzgetdirection\{\emph{<name>}\}}: a number which is the direction of the \emph{name}d bipole.
+    \item \texttt{\textbackslash ctikzgetdirection\{\emph{<name>}-Iarrow\}}: a number which is the direction of the current arrow requested for the \emph{name}d bipole; using \texttt{\emph{<name>}-Farrow} you get the same information for flow arrows.
 \end{itemize}
 
 For example, you could like the voltage label oriented with the bipole:
@@ -7633,6 +7720,7 @@ You can then define a kind of ``power flow'' style:
 \end{LTXexample}
 
 
+
 \subsubsection{Fixed voltage arrows: an example of advanced voltage usage}
 
 \begingroup % to contain example definitions
-- 
cgit v1.2.3

