circuitikz (7jul20)

git-svn-id: svn://tug.org/texlive/trunk@55771 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 435 insertions, 230 deletions

diff --git a/Master/texmf-dist/doc/latex/circuitikz/changelog.tex b/Master/texmf-dist/doc/latex/circuitikz/changelog.tex
index 80bc730a3e1..a9e9200ee12 100644
--- a/Master/texmf-dist/doc/latex/circuitikz/changelog.tex
+++ b/Master/texmf-dist/doc/latex/circuitikz/changelog.tex
@@ -5,6 +5,40 @@ full list of changes.
 
 \begin{itemize}
 \item
+  Version 1.2.1 (2020-07-06)
+
+  Several changes, both internal and user-visible. These are quite
+  risky, although they \emph{should} be backeard-compatible.
+
+  From the user point of view:
+
+  \begin{itemize}
+  \tightlist
+  \item
+    there is now a new style of voltages (``raised American'')
+  \item
+    a powerful mechanism for customize voltages, current and flows has
+    been added.
+  \end{itemize}
+
+  The internal changes are basically the re-implementation of the macros
+  that draw the path elements (\texttt{to{[}...{]}}), which have been
+  completely rewritten. Please be sure to read the possible
+  incompatibilities in the manual (section 1.9).
+
+  \begin{itemize}
+  \tightlist
+  \item
+    Added access to voltages, currents and flows anchors
+  \item
+    Added ``raised american'' voltage style
+  \item
+    Rewrite of the path generation macros
+  \item
+    Several small bugs fixed (no one ever used some
+    ``f\^{}\textgreater{}'' options\ldots{})
+  \end{itemize}
+\item
   Version 1.2.0 (2020-06-21)
 
   In this release, the big change is the rewriting of the voltages
diff --git a/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf b/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf
index 1547fdaa575..d4b9b8b7634 100644
--- a/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf
+++ b/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf
diff --git a/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.tex b/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.tex
index 9ecca9a39ad..300ee04f200 100644
--- a/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.tex
+++ b/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.tex
@@ -141,23 +141,23 @@
         \draw (C.pin 20) -- ++(0,-8) node[ground](GND){};
         \draw (C.pin 7) to[D, fill=blue] ++(0,-1) -- ++(0.5,0) to[R] ++(2,0)
             coordinate(a1) to[short, -*]
-            node[above left, blue]{Massimo A. Redaelli}
-            node[below left,]{\email{m.redaelli@gmail.com}}
+            node[above left, blue, pos=1]{Massimo A. Redaelli}
+            node[below left, pos=1]{\email{m.redaelli@gmail.com}}
             (a1-|GND);
             \draw (C.pin 5) to[D, fill=red] ++(0,-3)-- ++(0.5,0) to[R] ++(2,0)
             coordinate(a2) to[short, -*]
-            node[above left, blue]{Stefan Lindner}
-            node[below left,]{\email{stefan.lindner@fau.de}}
+            node[above left, blue, pos=1]{Stefan Lindner}
+            node[below left, pos=1]{\email{stefan.lindner@fau.de}}
             (a2-|GND);
             \draw (C.pin 3) to[D, fill=green] ++(0,-5)-- ++(0.5,0) to[R] ++(2,0)
             coordinate(a3) to[short, -*]
-            node[above left, blue]{Stefan Erhardt}
-            node[below left,]{\email{stefan.erhardt@fau.de}}
+            node[above left, blue, pos=1]{Stefan Erhardt}
+            node[below left, pos=1]{\email{stefan.erhardt@fau.de}}
             (a3-|GND);
             \draw (C.pin 1) to[D, fill=yellow] ++(0,-7)-- ++(0.5,0) to[R] ++(2,0)
             coordinate(a4) to[short, -*]
-            node[above left, blue]{Romano Giannetti}
-            node[below left,]{\email{romano.giannetti@gmail.com}}
+            node[above left, blue, pos=1]{Romano Giannetti}
+            node[below left, pos=1]{\email{romano.giannetti@gmail.com}}
             (a4-|GND);
     \end{circuitikz}
     \par\bigskip\vfill}
@@ -273,13 +273,21 @@ Nevertheless,  \href{https://tex.stackexchange.com/a/529159/38080}{Schrödinger'
 \end{circuitikz}
 \end{LTXexample}
 
-They \texttt{use fpu reciprocal} key seems to have no side effects, but given that it is patching an internal interface of \TikZ{} it can break any time, so it is advisable to use it only if and when needed.
+The \texttt{use fpu reciprocal} key seems to have no side effects, but given that it is patching an internal interface of \TikZ{} it can break any time, so it is advisable to use it only if and when needed.
 
 
 \subsection{Incompabilities between version}
 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.
 You can check the used version at your local installation using the macro \verb!\pgfcircversion{}!.
 \begin{itemize}
+    \item After v1.2.1: \textbf{Important:} the routine that implement the \texttt{to[...]} component positioning has been rewritten. That should enhance the line joins in path, and it's safer, but it can potentially change behavior.
+
+        One of the changes is that the previous routine did the wrong thing if you used \texttt{(node) to[...]} (you should use an anchor or a coordinate, not a node there --- like \texttt{(node.anchor) to[...]}).
+
+        The other one was that in the structure \texttt{... to[...] node[pos=\emph{something}]  (coord)} the value of \texttt{pos} was completely wrong (even if you don't use \texttt{pos} explicitly, remeber it's \texttt{pos=0.5} by default).
+
+        Additionally, the old code disrupted the \TikZ{} path-fill mechanism, so that you could get away with using the \texttt{fill} option on paths and having just the components to be filled, not the path. That was incorrect, although sometime it was handy.
+
     \item After v1.2.0: voltage arrows, symbols and label positions are calculated with a rewritten routine. There should be little change, \emph{unless} you touched internal values\dots
     \item After v1.1.3: during the 1.1.0 --- 1.1.2 version, the inverted Schmitt buffer in IEEE style ports was called \texttt{inv schmitt} (with an additional space). The correct name is \texttt{invschmitt port} (the same as the legacy american port).
     \item After v1.1.2: the position of \texttt{american} voltages for the \texttt{open} bipoles (you can revert to old behavior, see section~\ref{sec:sub-voltage-position}).
@@ -315,7 +323,12 @@ The easiest way to contact the authors is via the official Github repository: \u
 \subsection{Package options}
 \label{sec:package-options}
 
-\noindent Circuit people are very opinionated about their symbols. In order to meet the individual gusto you can set a bunch of package options. The standard options are what the authors like, for example you get this:
+Circuit people are very opinionated about their symbols. In order to meet the individual gusto you can set a bunch of package options.
+
+There are arguably way too much 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.
+
+The standard options are what the authors like, for example you get this:
+
 \begin{LTXexample}[varwidth=true]
     \begin{circuitikz}
         \draw (0,0) to[R=2<\ohm>, i=?, v=84<\volt>] (2,0) --
@@ -5347,9 +5360,9 @@ Long names/styles for the bipoles can be used:
 
 \subsection{Labels and Annotations}
 \label{sec:labels-and-annotations}
-Since Version 0.7, beside the original label (l) option, there is a new option to place a second label, called annotation (a) at each bipole. Up to now this is a beta-test and there can be problems. For example, up to now this option is not compatible with the concurrent use of voltage labels.
+Since Version 0.7, beside the original label (\texttt{l})  option, there is a new option to place a second label, called annotation (\texttt{a}) at each bipole.
 
-The position of (a) and (l) labels can be adjusted with \_ and \^, respectively.
+The position of annotations and labels can be adjusted with \verb|_|  and \verb|^|.
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
@@ -5364,7 +5377,7 @@ The position of (a) and (l) labels can be adjusted with \_ and \^, respectively.
 \end{LTXexample}
 
 \textbf{Caveat:} notice that the way in which \texttt{circuitikz} processes the options, there will be problems if the label (or annotation, voltage, or current) contains one of the characters $=$ (equal) or $,$ (comma), giving unexpected errors and wrong output.
-These two characters must be protected to the option parser using an \verb|\mbox| command, or redefining the characters with a \TeX\ \verb|\def|:
+These two characters must be protected from the option parser using an \verb|\mbox| command, or redefining the characters with a \TeX\ \verb|\def|:
 
 \begin{LTXexample}[varwidth=true]
     \def\eq{=}
@@ -5513,9 +5526,54 @@ as shown in the following examples.
 
 This manual has been typeset with the option \texttt{\chosenvoltoption}.
 
+\subsubsection{Common properties of voltages and currents}
+\label{sec:common-vif-pos}
+
+Currents, voltages and flows (see later) are positioned along, or across, the part of the wires that connect the inner component to the rest of the circuit. So, changing the length of the connection (the coordinates that embrace the \texttt{to[...]} command) will change the position of the components.
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}
+    \draw (-1,1) to[R, v=$v$, i=$i$, f>^=$f$] (1,1);
+    \draw (-2,0) to[R, v=$v$, i=$i$, f>^=$f$] (2,0);
+\end{circuitikz}
+\end{LTXexample}
+
+However, you can override the properties \texttt{voltage/distance from node} (default \texttt{0.5}: how distant from the initial and final points of the path the arrow starts and ends or the plus and minus symbols are drawn) and \texttt{voltage/bump b} (how high the bump of the arrow is --- how curved it is, default \texttt{1.5}), and also \texttt{voltage/european label distance} (how distant from the normal position the voltage label will be, default \texttt{1.4}) on a per-component basis, in order to fine-tune the voltages:
+
+\begin{LTXexample}[varwidth=true]
+\tikz \draw (0,0) to[R, v=1<\volt>] (2,0); \par
+\ctikzset{voltage/distance from node=.1}
+\ctikzset{voltage/bump b=2.5}
+\tikz \draw (0,0) to[R, v=1<\volt>] (2,0);
+\end{LTXexample}
+
+The same concept as \texttt{distance from node} applies to the key \texttt{current/distance} for the position of the current's arrow:
+
+\begin{LTXexample}[varwidth=true]
+\tikz \draw (0,0) to[C, i=$\imath$] (2,0); \par
+\ctikzset{current/distance = .2}
+\tikz \draw (0,0) to[C, i=$\imath$] (2,0);
+\end{LTXexample}
+
+You can change globally these parameters by defining a component-specific key; you have to use the internal name of the component (in the component list, is the \texttt{nodename} without the terminal ``\texttt{shape}'' part):
+
+\begin{LTXexample}[varwidth=true]
+\tikz \draw (0,0) to[R, v=1<\volt>] (1.5,0)
+       to[C, v=2<\volt>] (3,0); \par
+\ctikzset{bipoles/capacitor/voltage/distance from node/.initial=.7}
+\tikz \draw (0,0) to[R, v=1<\volt>] (1.5,0)
+       to[C, v=2<\volt>] (3,0); \par
+\end{LTXexample}
+
+Note the \texttt{.initial}; you have to create such key the first time you use it. These kind of adjustments are not guaranteed to work in future upgrades, though; if you have to create a key you are somehow touching the internal structure of the package; it's much safer to create a style.
+
+One common request is to change the style of the arrows (both head and line) of these elements. Voltages, currents and flows are part of the same path of the component, so this is not possible in simple way; you have to drawn your own with \TikZ{} commands using the facilities explained in section~\ref{sec:vif-anchors}.
+
 \subsection{Currents}\label{sec:currents}
 
-Inline (along the wire) currents are selected with \verb|i_>|, \verb|i^<|, \verb|i>_|, \verb|i>^|, and various simplification; the default position and direction is obtained with the key \verb|i=...|.
+Inline (along the wire) currents are selected with \verb|i_>|, \verb|i^<|, \verb|i>_|, \verb|i>^|, and various combination; the default position and direction is obtained with the simple key \verb|i=...|.
+
+Basically, \verb|^| and \verb|_| control if the label is above or below the line (above and below \textbf{do} depend on the direction of the component path), and \verb|<| and \verb|>| the direction of the arrow; swapping them (from for example from \verb|i^>| to \verb|i>^|) will switch the side of the component where the symbol is drawn. See the following examples:
 
 
 \begin{LTXexample}[varwidth=true]
@@ -5566,31 +5624,16 @@ Inline (along the wire) currents are selected with \verb|i_>|, \verb|i^<|, \verb
 \end{circuitikz}
 \end{LTXexample}
 
-Also:
+Also notice that the direction of the path is important:
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
+   \draw (2,1) to[R, i<=$i_1$] (0,1);
    \draw (0,0) to[R, i<=$i_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[R, i>=$i_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
-
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[R, i^=$i_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
-
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[R, i_=$i_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+Default directions can change if the component is active or passive,\footnote{This, in hindsight, has been a bad feature --- and I'm partly responsible for it. But removing it would create \emph{too small} variations in circuits, so it stays.} following the chosen global voltage direction strategy (see section~\ref{curr-and-volt}).
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
@@ -5599,8 +5642,8 @@ Also:
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[V<=10V, i_=$i_1$] (2,0);
+\begin{circuitikz}[voltage dir=EF]
+   \draw (0,0) to[V=10V, i_=$i_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
@@ -5616,22 +5659,27 @@ Also:
 \end{circuitikz}
 \end{LTXexample}
 
+Current generators with the direct label (the one obtained by, for example, \texttt{I = something}) will treat it as a current:
+
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american]
-   \draw (0,0) to[dcisource=1A, i_=$i_1$] (2,0);
+\begin{circuitikz}
+   \draw (0,0) to[I=$a_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
+If you use the option \texttt{americancurrent} or using the style \texttt{[american currents]}
+you can changhe the style of current generators.
+
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american]
-   \draw (0,0) to[dcisource=1A,invert, i_=$i_1$] (2,0);
+\begin{circuitikz}[american currents]
+   \draw (0,0) to[I=$a_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
+
 \subsection{Flows}\label{flows}
-As an alternative for the current arrows, you can also use the following flows. They can also be used to indicate thermal or power flows. The syntax is pretty the same as for currents.
 
-\textit{This is a new beta feature since version 0.8.3; therefore, please provide bug reports or hints to optimize this feature regarding placement and appearance! This means that the appearance may change in the future!}
+As an alternative for the current arrows, you can also use the following ``flows''. They can also be used to indicate thermal or power flows. The syntax is pretty the same as for currents.
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
@@ -5676,9 +5724,13 @@ As an alternative for the current arrows, you can also use the following flows.
 \end{LTXexample}
 
 \subsection{Voltages}
-See introduction note at Currents and Voltages (chapter \ref{curr-and-volt}, page \pageref{curr-and-volt}) for the direction of the voltage and currents.
+See the introduction at Currents and Voltages (section~\ref{curr-and-volt}, page \pageref{curr-and-volt}) for the default direction of the voltage and currents.
+
+Voltages come in four different styles: European (with curved or straight arrows) and American (with signs that can stay near the wire or raised at the label level).
+
+Direction and position of the symbols are controlled in the same way as for the currents (see section~\ref{sec:currents}) with the \verb|_^<>| symbols.
 
-\subsubsection{European style} The default, with arrows. Use option \texttt{europeanvoltage} or style \verb![european voltages]!, or setting (even locally) \texttt{voltage=european}.
+\subsubsection{European style} The default, with curved arrows. Use option \texttt{europeanvoltage} or style \verb![european voltages]!, or setting (even locally) \texttt{voltage=european}.
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}[european voltages]
@@ -5704,49 +5756,71 @@ See introduction note at Currents and Voltages (chapter \ref{curr-and-volt}, pag
 \end{circuitikz}
 \end{LTXexample}
 
+The default direction for active elements can change, depending on the global \texttt{voltage dir} setting, so be careful.
+
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
-   \draw (0,0) to[V=10V, i_=$i_1$] (2,0);
+   \draw (0,0) to[I=1A, v_=$u_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
-   \draw (0,0) to[V<=10V, i_=$i_1$] (2,0);
+   \draw (0,0) to[I<=1A, v_=$u_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
-   \draw (0,0) to[I=1A, v_=$u_1$] (2,0);
+   \draw (0,0) to[I=$~$,l=1A, v_=$u_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
-   \draw (0,0) to[I<=1A, v_=$u_1$] (2,0);
+   \draw (0,0) to[I,l=1A, v_=$u_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
+Moreover, for historical reasons, voltage generators have differently looking arrows (they are straight even in curved European style).
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
-   \draw (0,0) to[I=$~$,l=1A, v_=$u_1$] (2,0);
+   \draw (0,0) to[battery,l_=1V, v=$u_1$, i=$i_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
-   \draw (0,0) to[I,l=1A, v_=$u_1$] (2,0);
+   \draw (0,0) to[V=10V, i_=$i_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
+You can change this last thing by forcing ``off'' the status of ``voltage generator''  of the component; but now the normal (passive) rule will apply, so, again, be careful.
+
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}
-   \draw (0,0) to[battery,l_=1V, v=$u_1$, i=$i_1$] (2,0);
+   \draw (0,0) to[battery, bipole/is voltage=false,
+                 v>=$u_1$,] (2,0);
+\end{circuitikz}
+\end{LTXexample}
+
+As for the currents, the direct label of voltage sources is passed as a voltage:
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}
+   \draw (0,0) to[cV=$k\cdot a_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
-\subsubsection{Straight European style} Using straight arrows. Use option \texttt{straightvoltages} or style \verb![straight voltages]!, or setting (even locally) \texttt{voltage=straight}. Notice that this is an only lightly tested option, so use with care.
+The following results from using the option \texttt{americanvoltage} or the style \texttt{[american voltages]}.
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}[american voltages]
+   \draw (0,0) to[V=$a_1$] (2,0);
+\end{circuitikz}
+\end{LTXexample}
+
+\subsubsection{Straight European style} Using straight arrows. Use option \texttt{straightvoltages} or style \verb![straight voltages]!, or setting (even locally) \texttt{voltage=straight}.
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}[straight voltages]
@@ -5772,89 +5846,115 @@ See introduction note at Currents and Voltages (chapter \ref{curr-and-volt}, pag
 \end{circuitikz}
 \end{LTXexample}
 
+Again, voltage generators are treated differently:
+
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}[straight voltages]
-   \draw (0,0) to[V=10V, i_=$i_1$] (2,0);
+   \draw (0,0) to[V=10V, i_=$i_1$] (3,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}[straight voltages]
-   \draw (0,0) to[V<=10V, i_=$i_1$] (2,0);
+   \draw (0,0) to[I, v=10V, i_=$i_1$] (3,0);
 \end{circuitikz}
 \end{LTXexample}
 
+And you can override that with \texttt{bipole/is voltage} keeping into account that the default direction will be the one of passive components:
+
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}[straight voltages]
-   \draw (0,0) to[I=1A, v_=$u_1$] (2,0);
+   \draw (0,0) to[V=10V, bipole/is voltage=false,
+                 i_=$i_1$] (3,0);
 \end{circuitikz}
 \end{LTXexample}
 
+\subsubsection{American style}
+Use option \texttt{americanvoltage} or set \verb![american voltages]! or use the option \texttt{voltage=american}.
+
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[straight voltages]
-   \draw (0,0) to[I<=1A, v_=$u_1$] (2,0);
+\begin{circuitikz}[american voltages]
+   \draw (0,0) to[R, v^>=$v_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[straight voltages]
-   \draw (0,0) to[I=$~$,l=1A, v_=$u_1$] (2,0);
+\begin{circuitikz}[american voltages]
+   \draw (0,0) to[R, v^<=$v_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[straight voltages]
-   \draw (0,0) to[I,l=1A, v_=$u_1$] (2,0);
+\begin{circuitikz}[american voltages]
+   \draw (0,0) to[R, v_>=$v_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[straight voltages]
-   \draw (0,0) to[battery,l_=1V, v=$u_1$, i=$i_1$] (2,0);
+\begin{circuitikz}[american voltages]
+   \draw (0,0) to[R, v_<=$v_1$] (2,0);
+\end{circuitikz}
+\end{LTXexample}
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}[american]
+   \draw (0,0) to[I=1A, v_=$u_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}[american]
+   \draw (0,0) to[I<=1A, v_=$i_1$] (2,0);
+\end{circuitikz}
+\end{LTXexample}
 
-\subsubsection{American style}
-Use option \texttt{americanvoltage} or set \verb![american voltages]! or use the option \texttt{voltage=american}.
+
+\subsubsection{Raised American style}
+
+Since version \texttt{1.2.1}, ``raised'' American voltages are available; to use them, set the style \verb![raised voltages]! or use the option \texttt{voltage=raised}.
+This is a version of the American-style voltage where the signs are raised to the level of the label.
+The label is centered between the two signs, and the position of the signs is calculated supposing that the label itself will be pretty simple; if you have very big labels you will need to adjust the position with \texttt{voltage shift} and/or the \texttt{voltage/distance from node} properties (see section~\ref{sec:common-vif-pos}).
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
+\begin{circuitikz}[raised voltages]
    \draw (0,0) to[R, v^>=$v_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
+\begin{circuitikz}[raised voltages]
    \draw (0,0) to[R, v^<=$v_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
+\begin{circuitikz}[raised voltages]
    \draw (0,0) to[R, v_>=$v_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
+\begin{circuitikz}[raised voltages]
    \draw (0,0) to[R, v_<=$v_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}[american]
+   \ctikzset{voltage=raised}
    \draw (0,0) to[I=1A, v_=$u_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
 \begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american]
+\begin{circuitikz}[raised voltages]
    \draw (0,0) to[I<=1A, v_=$i_1$] (2,0);
 \end{circuitikz}
 \end{LTXexample}
 
-\subsubsection{Voltage position}\label{sec:sub-voltage-position} It is possible to move away the arrows and the plus or minus signs with the key \texttt{voltages shift} (default value is \texttt{0}, which gives the standard position):
+\subsubsection{Voltage position}\label{sec:sub-voltage-position}
+
+It is possible to move the arrows and the plus or minus signs away form the component with the key \texttt{voltages shift} (default value is \texttt{0}, which gives the standard position):
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}[]
@@ -5862,7 +5962,7 @@ Use option \texttt{americanvoltage} or set \verb![american voltages]! or use the
    \draw (0,-1) to[R, v=$v_1$, i=$i_1$,
       voltage shift=0.5] (2,-1);
    \draw (0,-2) to[R, v=$v_1$, i=$i_1$,
-      voltage shift=1.0, ] (2,-2);
+      voltage shift=1.0] (2,-2);
 \end{circuitikz}
 \end{LTXexample}
 
@@ -5872,12 +5972,24 @@ Use option \texttt{americanvoltage} or set \verb![american voltages]! or use the
 \end{circuitikz}
 \end{LTXexample}
 
+Negative values do work as expected:
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}[raised voltages]
+   \draw (0,1.5) to[R, v^=$v_1$, i=$i_1$] ++(2,0);
+   \draw (0,0) to[R, v^=$v_1$, i=$i_1$,
+        voltage shift=-1.0] ++(2,0);
+\end{circuitikz}
+\end{LTXexample}
+
 You can fine-tune the position of the \texttt{+} and \texttt{-} symbols and the label in independent way using \texttt{voltage/shift} (default \texttt{0.0} for the former and \texttt{voltage/american label distance} (the distance of the label form the lines of the symbols, default \texttt{1.4}) for the latter.
 
 \begin{LTXexample}[varwidth=true]
 \begin{circuitikz}[american voltages]
-    \ctikzset{voltage/american label distance=0.2, voltage/shift=2}
-    \draw (0,0) to[R, v=$v_1$, i=$i_1$] (2,0);
+    \draw (0,1) to[R, v=$v_1$, i=$i_1$] ++(2,0);
+    % normally 1.4, make it tighter
+    \ctikzset{voltage/american label distance=0.5}
+    \draw (0,0) to[R, v=$v_1$, i=$i_1$] ++(2,0);
 \end{circuitikz}
 \end{LTXexample}
 
@@ -5949,32 +6061,6 @@ This could be especially useful if you define a style, to use like this:
 \end{LTXexample}
 
 
-\subsection{Global properties of voltages and currents}
-
-\begin{LTXexample}[varwidth=true]
-\tikz \draw (0,0) to[R, v=1<\volt>] (2,0); \par
-\ctikzset{voltage/distance from node=.1}
-\tikz \draw (0,0) to[R, v=1<\volt>] (2,0);
-\end{LTXexample}
-
-\begin{LTXexample}[varwidth=true]
-\tikz \draw (0,0) to[C, i=$\imath$] (2,0); \par
-\ctikzset{current/distance = .2}
-\tikz \draw (0,0) to[C, i=$\imath$] (2,0);
-\end{LTXexample}
-
-However, you can override the properties \texttt{voltage/distance from node} (how distant from the initial and final points of the path the arrow starts and ends, default \texttt{0.5}) and \texttt{voltage/bump b} (how high the bump of the arrow is --- how curved it is, default \texttt{1.5}), and also \texttt{voltage/european label distance} (how distant from the ``bump''  the voltage label will be, default \texttt{1.4}) on a per-component basis, in order to fine-tune the voltages:
-
-
-\begin{LTXexample}[varwidth=true]
-\tikz \draw (0,0) to[R, v=1<\volt>] (1.5,0)
-       to[C, v=2<\volt>] (3,0); \par
-\ctikzset{bipoles/capacitor/voltage/distance from node/.initial=.7}
-\tikz \draw (0,0) to[R, v=1<\volt>] (1.5,0)
-       to[C, v=2<\volt>] (3,0); \par
-\end{LTXexample}
-
-Note the \texttt{.initial}; you have to create such key the first time you use it.
 
 \subsection{Changing the style of labels and text ornaments}
 
@@ -5987,7 +6073,7 @@ For example, you can make all annotations small by using:
 \ctikzset{bipole annotation style/.style={font=\small}}
 \end{lstlisting}
 
-And the change (override) the setting in one specific bipole using:
+And/or change (override) the setting in one specific bipole using:
 
 \begin{lstlisting}[numbers=none]
 ...to[bipole annotation style={color=red}, R, a={Red note}]...
@@ -6017,141 +6103,231 @@ The available styles and commands are \texttt{bipole label style}, \texttt{bipol
 \end{circuitikz}
 \end{LTXexample}
 
-\subsection{Labels in special components}
-
-For some components label, current and voltage behave as one would expect:
+\subsection{Accessing labels text nodes}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[I=$a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+Since 0.9.5, you can access all the labels nodes\footnote{The access to \texttt{label}s and \texttt{annotation}s was present before, but not documented.} using special node names. So, if you use \texttt{name} to give a name to the bipole node, you can access also the following nodes: \texttt{namelabel} (notice: no space nor any other symbol between \texttt{name} and \texttt{label}!), \texttt{nameannotation}, \texttt{namevoltage}, \texttt{namecurrent} and \texttt{nameflow}. Notice that the node names are available only if the bipole has an anchor or an annotation, of course.
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[I, i=$a_1$] (2,0);
+\begin{LTXexample}[varwidth=true,
+            pos=t, basicstyle=\small\ttfamily
+    ]
+\newcommand{\marknode}[2][45]{%
+    \node[circle, draw, red, inner sep=1pt,
+    pin={[red, font=\tiny]#1:#2}] at (#2.center) {};
+}
+\begin{circuitikz}[ american]
+    \draw (0,0) to [R=L1, a=A1, name=L1] ++(3,0)
+    to [R, l2_=L2 and 2L, a^=A2, name=L2] ++(3,0);
+    \marknode{L1} \marknode{L1label} \marknode[0]{L1annotation}
+    \marknode{L2} \marknode[0]{L2label} \marknode{L2annotation}
+    \draw[blue] (L2label.south west) rectangle (L2label.north east);
+    \draw (6.1,0) to [R=R1, v=V1, i=I1, f>^=F1, name=R1] ++(3,0)
+    to [R, v<=V2, i^=I2, f>^=F2, name=R2] ++(3,0);
+    \marknode[0]{R1voltage} \marknode[0]{R2voltage} \marknode[90]{R1current}
+    \marknode[90]{R2current} \marknode{R1flow} \marknode{R2flow}
 \end{circuitikz}
 \end{LTXexample}
 
+\subsection{Advanced voltages, currents and flows}\label{sec:vif-anchors}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[cI=$k\cdot a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+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.
+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:
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[sI=$a_1$] (2,0);
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+\begin{circuitikz}[]
+    \draw (0,1) to[R, v=$v$] ++(3,0);
+    \draw (0,0) to[R, v, name=R, voltage/bump b=3] ++(3,0);
+    \draw [thin, red, -{Stealth[width=8pt]}, ]
+    (R-Vfrom) .. controls (R-Vcont1) and (R-Vcont2).. (R-Vto)
+    node [black, pos=0.5, fill=white]{v};
 \end{circuitikz}
 \end{LTXexample}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[csI=$k\cdot a_1$] (2,0);
+Or, for example, to have a different voltage style; normally you would define a macro:
+
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+\begin{circuitikz}[voltage shift=0.5]
+    \def\eurVPM#1#2{% node, label
+        \draw [thin, -{Stealth[width=8pt]}, shorten >=5pt,
+        shorten <=5pt] (#1-Vfrom) node[font=\tiny]{$-$}
+        .. controls (#1-Vcont1) and (#1-Vcont2)..
+        (#1-Vto) node[font=\tiny]{$+$}
+        node[pos=0.5,anchor=\ctikzgetanchor{#1}{Vlab}]{#2};}
+    \draw (0,0) to[R=R1, name=R1, v, i=$i$] ++(3,0)
+        to[R, l_=R2, v^, name=R2] ++(0,-3);
+    \eurVPM{R1}{$v_1$} \eurVPM{R2}{$v_2$}
 \end{circuitikz}
 \end{LTXexample}
 
-The following results from using the option \texttt{americancurrent} or using the style \texttt{[american currents]}.
+\subsubsection{Activating the anchors}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american currents]
-   \draw (0,0) to[I=$a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+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.
+To suppress the normal output of the \texttt{v}, \texttt{i}, \texttt{f} keys, you can use such keys without any argument, like in the previous example; notice that the \verb|_| and \verb|^| modifiers work as expected.
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american currents]
-   \draw (0,0) to[I, i=$a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+The following line of resistors has been drawn with the following commands; it is used to show the name of the available anchors.
 
+\begin{lstlisting}
+    \draw (0,0) to[R=R1, v=$v$, name=R1] ++(4,0)
+        to[R, l_=R2, i=$i$, name=R2] ++(4,0)
+        to[R=R3, f=$f$, name=R3] ++(4,0);
+\end{lstlisting}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american currents]
-   \draw (0,0) to[cI=$k\cdot a_1$] (2,0);
+\begin{circuitikz}[]
+    \draw (0,0) to[R=R1, v=$v$, name=R1] ++(4,0) to[R, l_=R2, i=$i$, name=R2] ++(4,0) to[R=R3, f=$f$, name=R3] ++(4,0);
+    \path
+    (R1-Vto) \showcoord(R1-Vto)<-135:0.2>
+    (R1-Vfrom) \showcoord(R1-Vfrom)<-45:0.2>
+    (R1-Vcont1) \showcoord(R1-Vcont1)<-45:0.2>
+    (R1-Vcont2) \showcoord(R1-Vcont2)<-135:0.2>
+    (R1-Vlab) \showcoord(R1-Vlab)<-90:0.5>
+    (R2-Ito) \showcoord(R2-Ito)<45:0.3>
+    (R2-Ifrom) \showcoord(R2-Ifrom)<135:0.3>
+    (R2-Ipos) \showcoord(R2-Ipos)<-90:0.3>
+    (R3-Fto) \showcoord(R3-Fto)<45:0.3>
+    (R3-Ffrom) \showcoord(R3-Ffrom)<135:0.3>
+    (R3-Fpos) \showcoord(R3-Fpos)<-90:0.4>
+    ;
 \end{circuitikz}
-\end{LTXexample}
 
+The meaning of the anchors is the following:
+\begin{itemize}
+\item
+    \texttt{Vfrom} and \texttt{Vto} are the main points where the voltage information is given: start and end point of the arrow, or position of the $+$ or $-$ sign. This is the same for the \texttt{Ffrom} or \texttt{Fto} anchors for flows; for inline currents, the corresponding \texttt{Ifrom} and \texttt{Ito} mark the wire segment where the arrowhead is positioned (at the specified \texttt{current/distance} fraction. The direction of the arrow is available using the auxiliary macro \verb|\ctikzgetdirection| (see below).
+\item
+    \texttt{Vcont1} and \texttt{Vcont2} are the control points for the curved arrow (see the examples above); in the case of straight arrows or american-style voltages, they are set at the midpoint between \texttt{Vfrom} and \texttt{Vto}.
+\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.}
+\end{itemize}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american currents]
-   \draw (0,0) to[sI=$a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+Changing the options of the elements, will change the anchors acoordingly:
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american currents]
-   \draw (0,0) to[csI=$k\cdot a_1$] (2,0);
+\begin{lstlisting}
+    \ctikzset{current/distance=0.2}
+    \draw (0,0) to[R=R1, v>=$v$, name=R1] ++(4,0)
+        to[R, l_=R2, i<_=$i$, name=R2] ++(4,0)
+        to[R, l_=R3, f<_=$f$, name=R3] ++(4,0);
+\end{lstlisting}
+
+\begin{circuitikz}[]
+    \ctikzset{current/distance=0.2}
+    \draw (0,0) to[R=R1, v>=$v$, name=R1] ++(4,0) to[R, l_=R2, i<_=$i$, name=R2] ++(4,0) to[R, l_=R3, f<_=$f$, name=R3] ++(4,0);
+    \path
+    (R1-Vto) \showcoord(R1-Vto)<-45:0.2>
+    (R1-Vfrom) \showcoord(R1-Vfrom)<-135:0.2>
+    (R1-Vcont1) \showcoord(R1-Vcont1)<-135:0.2>
+    (R1-Vcont2) \showcoord(R1-Vcont2)<-45:0.2>
+    (R1-Vlab) \showcoord(R1-Vlab)<-90:0.5>
+    (R2-Ito) \showcoord(R2-Ito)<135:0.3>
+    (R2-Ifrom) \showcoord(R2-Ifrom)<45:0.3>
+    (R2-Ipos) \showcoord(R2-Ipos)<90:0.3>
+    (R3-Fto) \showcoord(R3-Fto)<90:0.4>
+    (R3-Ffrom) \showcoord(R3-Ffrom)<80:0.4>
+    (R3-Fpos) \showcoord(R3-Fpos)<-90:0.4>
+    ;
 \end{circuitikz}
-\end{LTXexample}
 
-The same holds for voltage sources:
+Obviously, the anchors follow the voltage style you choose:
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[V=$a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+\begin{lstlisting}
+    \draw (0,0) to[R=R1, v=$v$, name=R1, voltage=straight] ++(4,0)
+        to[R=R2, v=$v$, name=R2, voltage=american] ++(4,0)
+        to[R=R3, v=$v$, name=R3, voltage=raised] ++(4,0);
+\end{lstlisting}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[V, v=$a_1$] (2,0);
+\begin{circuitikz}[]
+    \ctikzset{current/distance=0.2}
+    \draw (0,0) to[R=R1, v=$v$, name=R1, voltage=straight] ++(4,0)
+        to[R=R2, v=$v$, name=R2, voltage=american] ++(4,0)
+        to[R=R3, v=$v$, name=R3, voltage=raised] ++(4,0);
+    \foreach \i in {1, 2, 3} {
+        \path
+        (R\i-Vto) \showcoord(R\i-Vto)<-90:0.4>
+        (R\i-Vfrom) \showcoord(R\i-Vfrom)<-90:0.4>
+        (R\i-Vcont1) \showcoord(R\i-Vcont1)<135:0.6>
+        (R\i-Vcont2) \showcoord(R\i-Vcont2)<45:0.6>
+        (R\i-Vlab) \showcoord(R\i-Vlab)<-90:0.6>
+        ;
+    }
 \end{circuitikz}
-\end{LTXexample}
 
+Notice the postion of the control points, as well as the fact that the anchor available with \verb|\ctikzgetanchor| is applied to \texttt{Vfrom} and \texttt{Vto} symbols, too.
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[cV=$k\cdot a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+Finally, as ever, generators are treated differently, but you have all your anchors too.
 
+\begin{lstlisting}
+    \ctikzset{american}
+    \draw (0,0) to[V=$v$, name=G1, voltage=european] ++(4,0)
+        to[V=$v$, v=$v$, name=G2, voltage=american] ++(4,0)
+        to[battery2, v=$v$, name=G3, voltage=raised] ++(4,0);
+\end{lstlisting}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[sV=$a_1$] (2,0);
+\begin{circuitikz}[]
+    \ctikzset{american}
+    \draw (0,0) to[V=$v$, name=G1, voltage=european] ++(4,0)
+        to[V=$v$, v=$v$, name=G2, voltage=american] ++(4,0)
+        to[battery2, v=$v$, name=G3, voltage=raised] ++(4,0);
+    \foreach \i in {1, 2, 3} {
+        \path
+        (G\i-Vto) \showcoord(G\i-Vto)<-60:0.1>
+        (G\i-Vfrom) \showcoord(G\i-Vfrom)<-120:0.1>
+        (G\i-Vlab) \showcoord(G\i-Vlab)<90:0.3>
+        ;
+    }
 \end{circuitikz}
-\end{LTXexample}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}
-   \draw (0,0) to[csV=$k\cdot a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+\subsubsection{Auxiliary information}
 
-The following results from using the option \texttt{americanvoltage} or the style \texttt{[american voltages]}.
+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.
+\end{itemize}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
-   \draw (0,0) to[V=$a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+For example, you could like the voltage label oriented with the bipole:
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
-   \draw (0,0) to[V, v=$a_1$] (2,0);
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+\begin{circuitikz}[]
+    \def\myvv#1#2{%
+    \draw [thin, blue, ->,]
+    (#1-Vfrom) .. controls (#1-Vcont1) and (#1-Vcont2).. (#1-Vto)
+    node [pos=0.5, below,
+    rotate=\ctikzgetdirection{#1}] at (#1-Vlab) {#2}; }
+    \draw (0,0) to[R, v, name=A] ++(3,0);
+    \draw (0,0) to[R, v, name=B] ++(3,3);
+    \myvv{A}{$v_A$}\myvv{B}{$v_B$}
 \end{circuitikz}
 \end{LTXexample}
 
+Or you could use the anchor to substitute the flow with a fancy one and still position automatically the label; suppose you have the following definition in your preamble (see \TikZ{} manual, ``Path decorations''):
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
-   \draw (0,0) to[cV=$k v_e$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
-
+\begin{lstlisting}
+% requires \usetikzlibrary{decorations, decorations.pathmorphing}
+\tikzset{%
+lray/.style={decorate, decoration={
+    snake, amplitude=2pt,pre length=1pt,post length=2pt, segment length=5pt,},
+    -Triangle,
+}}
+\end{lstlisting}
+\tikzset{%
+lray/.style={decorate, decoration={
+    snake, amplitude=2pt,pre length=1pt,post length=2pt, segment length=5pt, },
+    -Triangle,
+}}
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
-   \draw (0,0) to[sV=$a_1$] (2,0);
-\end{circuitikz}
-\end{LTXexample}
+You can then define a kind of ``power flow'' style:
 
-\begin{LTXexample}[varwidth=true]
-\begin{circuitikz}[american voltages]
-   \draw (0,0) to[csV=$k v_e$] (2,0);
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+\begin{circuitikz}[]
+    \newcommand\myff[3][blue]{% [opt: color] node label
+        \draw [lray, #1, ] (#2-Ffrom) -- (#2-Fto)
+        node [anchor=\ctikzgetanchor{#2}{Flab}, inner sep=4pt]
+        at (#2-Fpos) {#3};}
+    \draw (0,1) to[R, f, name=A] ++(3,0);
+    \draw (0,0) to[R, f_<, name=B] ++(3,0);
+    \myff{A}{$P_A$}\myff[red]{B}{$P_B$}
 \end{circuitikz}
 \end{LTXexample}
 
@@ -6195,30 +6371,6 @@ If the option {\ttfamily siunitx} is active (and \emph{not} in \ConTeXt), then t
 \end{circuitikz}
 \end{LTXexample}
 
-\subsection{Accessing labels text nodes}
-
-Since 0.9.5, you can access all the labels nodes\footnote{The access to \texttt{label}s and \texttt{annotation}s was present before, but not documented.} using special node names. So, if you use \texttt{name} to give a name to the bipole node, you can access also the following nodes: \texttt{namelabel} (notice: no space nor any other symbol between \texttt{name} and \texttt{label}!), \texttt{nameannotation}, \texttt{namevoltage}, \texttt{namecurrent} and \texttt{nameflow}.
-
-\begin{LTXexample}[varwidth=true,
-            pos=t, basicstyle=\small\ttfamily
-    ]
-\newcommand{\marknode}[2][45]{%
-    \node[circle, draw, red, inner sep=1pt,
-    pin={[red, font=\tiny]#1:#2}] at (#2.center) {};
-}
-\begin{circuitikz}[ american]
-    \draw (0,0) to [R=L1, a=A1, name=L1] ++(3,0)
-    to [R, l2_=L2 and 2L, a^=A2, name=L2] ++(3,0);
-    \marknode{L1} \marknode{L1label} \marknode[0]{L1annotation}
-    \marknode{L2} \marknode[0]{L2label} \marknode{L2annotation}
-    \draw[blue] (L2label.south west) rectangle (L2label.north east);
-    \draw (6.1,0) to [R=R1, v=V1, i=I1, f>^=F1, name=R1] ++(3,0)
-    to [R, v<=V2, i^=I2, f>^=F2, name=R2] ++(3,0);
-    \marknode[0]{R1voltage} \marknode[0]{R2voltage} \marknode[90]{R1current}
-    \marknode[90]{R2current} \marknode{R1flow} \marknode{R2flow}
-\end{circuitikz}
-\end{LTXexample}
-
 
 \section{Using bipoles in circuits}
 
@@ -6354,7 +6506,7 @@ There are several predefined shorthand as the above; in the following pages you
 \end{circuitikz}
 \end{LTXexample}
 
-\subsubsection{Transparent poles}
+\subsubsection{Transparent poles}\label{sec:transparent-poles}
 
 ``Open-poles'' terminals (\texttt{ocirc}, \texttt{odiamondpole}, and \texttt{osquarepole}) are normally filled with the background color at full opacity. This is because, for simplicity of operation, the nodes are placed \emph{after} the wires are drawn and have to ``white-out'' the underlying lines.
 
@@ -6363,14 +6515,16 @@ Anyway, \emph{if you know what you are doing}, you can change it with the key \t
 \begin{LTXexample}[pos=t, basicstyle=\small\ttfamily]
 \begin{circuitikz}[scale=3, transform shape]
     \fill[cyan] (0,0) rectangle (4.1,-0.6);
-    \tikzset{halfwhite/.style={fill opacity=0.5, fill=white, open poles opacity=0.5}}
+    \tikzset{open poles opacity=0.5}
     % automatic positioning  when opacity is not 1.0 creates artifacts
-    \draw[halfwhite] (0,0) to[generic, -o] ++(2,0) --++(0,-0.5);
+    % note that opacity must go on the draw command for path-style components
+    \draw[fill opacity=0.5] (0,0) to[generic, fill=white, -o] ++(2,0) --++(0,-0.5);
     % you have to use manual positioning
-    \draw[halfwhite] (2.2,0) -- ++(0.5,0) node[ocirc, anchor=180]{};
-    \draw[halfwhite] (3,0) node[ocirc](B){}  (B.0) --++(0.5,0) (B.-90) --++(0,-0.5);
+    \draw (2.2,0) -- ++(0.5,0) node[ocirc, anchor=180, fill opacity=0.5]{};
+    \draw (3,0) node[ocirc, fill opacity=0.5](B){}  (B.0) --++(0.5,0) (B.-90) --++(0,-0.5);
     % maybe really useful only for terminals going out of the circuit...
-    \draw (3.6,0) -- ++(0.2,0) node[ocirc, halfwhite, anchor=180]{};
+    % notice that in node commands you can specify the opacity directly
+    \draw (3.6,0) -- ++(0.2,0) node[ocirc, fill=white, fill opacity=0.5, anchor=180]{};
 \end{circuitikz}
 \end{LTXexample}
 
@@ -6457,9 +6611,17 @@ To correct the line ending, there are support shapes to fill the missing rectang
 	\end{tikzpicture}
 \end{LTXexample}
 
-
 \section{Colors}
 
+Color support in \Circuitikz{} is quite limited. You will have no problem if:
+\begin{enumerate}
+    \item You stick to use styles (see~\ref{sec:styling-fillcolor}) for filling your components, or using a direct \texttt{fill=...} option directly;
+    \item when coloring whole circuits, use the option \texttt{color=...} in your global picture options or in the \verb|\draw| command (not just the color name as a shorthand);
+    \item forget about transparency.
+\end{enumerate}
+
+Nevertheless, if you really need to do strange things with colors you can read on; you can do almost everything but there are several glitches to take into account.
+
 \subsection{Shape colors}
 
 The color of the components is stored in the key \verb!\circuitikzbasekey/color!. Circui\TikZ\ tries to follow the color set in \TikZ, although sometimes it fails. If you change color in the picture, please do not use just the color name as a style, like \verb![red]!, but rather assign the style \verb![color=red]!.
@@ -6583,20 +6745,23 @@ A workaround is shown in port \texttt{3}:
 ;\end{circuitikz}
 \end{LTXexample}
 
-Notice also that the connection point are always filled, although the color \emph{tries} to follow the color of the filling of the component:
+Notice also that the connection point are always filled, although the color \emph{tries} to follow the color of the filling of the component (but look at section~\ref{sec:transparent-poles}). Moreover, if you want to pass fill transparency down to path-style components, you \emph{have} to put it into the options of the \verb|\draw| command.
 
 \begin{LTXexample}[varwidth=true, pos=t]
 \begin{circuitikz}
     \fill[cyan] (0,3.0) rectangle (7,7);
-    \draw [fill=yellow, ] (4,4) to [D,o-o] ++(0,2) to[D*, fill=yellow] ++(2,0)
-    to[D*] ++(0,-2)  to[D, fill=red, o-o] ++(-2,0);
-    \draw (1,4) node[ocirc]{} -- ++(1,0) node[ocirc]{};
-    \draw (1,4.5) to[short, o-o] ++(1,0) to[short, -o] ++(1,0);
-    \draw[fill=yellow] (1,5) to[short, o-o] ++(1,0) to[short, -o] ++(1,0);
+    \draw [fill opacity=0.5] (1,6.5) to[generic, fill=white,o-o] ++(2,0);
     \draw (1,5.5) to[short, fill=red, o-o] ++(1,0) to[short, -o] ++(1,0);
+    \draw[fill=yellow] (1,5) to[short, o-o] ++(1,0) to[short, -o] ++(1,0);
+    \draw (1,4.5) to[short, o-o] ++(1,0) to[short, -o] ++(1,0);
+    \draw (1,4) node[ocirc]{} -- ++(1,0) node[ocirc]{};
+    \draw [thick, color=green!50!black] (4,4) to [D,o-o,fill=yellow] ++(0,2) to[D*, fill=yellow]
+        ++(2,0) to[D*,fill=yellow] ++(0,-2)  to[D, fill=red, o-o] ++(-2,0);
 \end{circuitikz}
 \end{LTXexample}
 
+As you can see, the ``black'' components (as \texttt{D*}) follow the color of the line, not the fill.
+
 \section{FAQ}
 
 \noindent Q: When using \verb!\tikzexternalize! I get the following error:
@@ -7197,3 +7362,4 @@ Here a series of example, contributed by several people, is shown with their cod
 \printindex
 
 \end{document}
+% vim: set fdm=marker fmr=%<<<,%>>>:
diff --git a/Master/texmf-dist/doc/latex/circuitikz/ctikzmanutils.sty b/Master/texmf-dist/doc/latex/circuitikz/ctikzmanutils.sty
index 38bf7716fcd..f402c9fa73b 100644
--- a/Master/texmf-dist/doc/latex/circuitikz/ctikzmanutils.sty
+++ b/Master/texmf-dist/doc/latex/circuitikz/ctikzmanutils.sty
@@ -17,7 +17,7 @@
 \RequirePackage{showexpl}
 \RequirePackage{ragged2e}
 % for some example we need them...
-\usetikzlibrary{calc,fit}
+\usetikzlibrary{calc,fit, decorations, decorations.pathmorphing}
 \RequirePackage{upgreek}
 %
 % The following trick is used to silence showexpl a bit, so that the
@@ -135,6 +135,11 @@
         [blue, inner sep=0.5pt, font=\small,
         pin distance=#3\pgf@circ@Rlen, pin edge={blue, }%
     ]#2:#1}](#1){}}
+    \def\showcoordwc[#1](#2)<#3:#4>{%
+    node[circle, #1, draw, inner sep=1pt,pin={%
+        [#1, inner sep=0.5pt, font=\small,
+        pin distance=#4\pgf@circ@Rlen, pin edge={#1, }%
+    ]#3:#2}](#2){}}
 \makeatother
 % show anchors of a node component:
 % optional: options of the circuitikz environment