circuitikz (30oct23)

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

1 files changed, 219 insertions, 14 deletions

diff --git a/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.tex b/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.tex
index 1982bca4525..32a8a8c532a 100644
--- a/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.tex
+++ b/Master/texmf-dist/doc/latex/circuitikz/circuitikzmanual.tex
@@ -7281,11 +7281,133 @@ The code that implemented the printing of the numbers (which in \texttt{muxdemux
     \foreach \myp in {1,...,\NB} \node[above, font=\tiny] at (\myn.bbpin \myp){\myp};
     \foreach \myp in {1,...,\NT} \node[below, font=\tiny] at (\myn.btpin \myp){\myp};
 }
+\end{circuitikz}
 \end{lstlisting}
 
-\subsubsection{Adding wedge or circular inversion markers}\label{sec:wedge-inversion}
+\subsubsection{Adding labels to the pins}\label{sec:muxdemux-labels}
+
+In \texttt{muxdemux}es, there is no automatic labelling of pins with numbers as in chips; there is no simple standard enumeration possible. But since \texttt{v1.6.5} it is possible to associate a name to the pins that will be printed with the shape; that names are called \emph{pin labels}.
+Pin labels are counter-rotated by default if the shape is rotated, as in chip pin numbers~(see \ref{sec:chip-rotation}), but you can avoid it with the key \texttt{rotated numbers} (the default is \texttt{straight numbers}).
+Additionally, you can set also \emph{border labels} on the four borders (more or less, see later); that are normally not counter-rotated \emph{unless} the result would be upside-down (or if you use \texttt{straight numbers}, of course), and clock and negation symbols.
+
+All of these labels and symbols are added by specifying them in a \texttt{muxdemux label=\{\dots\}} clause. Notice that the key specified there are not checked for validity; if you misspell any of that, it will be simply ignored.
+
+\paragraph{Inner pin labels} will be printed in the inside of the shape, with the font specified in the \verb|\ctikzset| key \texttt{muxdemux/inner label font} (default is \verb|\tiny| in \LaTeX, other engine can have it different --- better set it in case of doubt) and with a padding setting with the keys \texttt{muxdemux/inner label xsep} and  \texttt{muxdemux/inner label ysep} (respectively for horizontal and vertical shifts; default for both \texttt{2pt}). You can also use the key \texttt{muxdemux/inner label sep} to set both at the same time.
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}
+\tikzset{myICwl/.style={muxdemux,
+    muxdemux def={Lh=4, Rh=4, w=4,
+        NR=1, NL=2, NB=2, NT=2,},
+    muxdemux label={L1=left1, L2=left2,
+        R1=r1, B2=b2, T1=t1, T2=t2},
+    }
+}
+\draw (0, 0) node[myICwl]{chip} ++(3,0)
+    node[myICwl, rotate=-90]{chip};
+\draw (0, -3) node[myICwl]{chip} ++(3,0)
+    node[myICwl, rotate=-90,
+        rotated numbers]{chip};
+\end{circuitikz}
+\end{LTXexample}
+
+As you can see, the syntax is to add a \texttt{muxdemux label} to the specification; the labels are set using one of the letter \texttt{L}, \texttt{R}, \texttt{B}, and \texttt{T} for respectively left, right, bottom and top labels. You can define all the labels, none (which will give the default behavior of no-labels as it was before \texttt{v1.6.5}), or any number you wish.
+If you want some specific label rotated in a different way, you have to do it manually, as shown in the following example.
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}
+\tikzset{mux 4by2 wl/.style={muxdemux,
+    muxdemux def={Lh=6, NL=6, Rh=3, NB=2, w=3, NT=1},
+    draw only left pins={2-5},
+    muxdemux label={B1=$A_1$, B2=$A_0$, R1=OUT,
+        L2=$D_{00}$, L3=$D_{01}$, L4=$D_{10}$, L5=$D_{11}$,
+        T1=\rotatebox{90}{\texttt{Enable}}},
+    circuitikz/muxdemux/inner label ysep=4pt}}
+\node [mux 4by2 wl]{};
+\end{circuitikz}
+\end{LTXexample}
 
-Although you can add ``negation balls'' as seen for, for example, flip-flops (see section~\ref{sec:flip-flop-cust}), sometimes the European-style notation (also accepted by the IEEE standard) with the small wedge is preferred. The \texttt{wedgeinv} shape will nicely do. It'll scale with the \texttt{muxdemuxes} class, and the length and height can be changed with the keys \texttt{wedge inversion mark/width} (default \texttt{0.2}) and \texttt{height} (default \texttt{0.1}), with the same units that are used for the \texttt{external pins width} and similar keys.
+\paragraph{Outer pin labels} will be printed on the outside of the pin position --- in the case of left and right pins, either above (``up'', identified by \texttt{LU} and \texttt{RU} labels), or below (``down'', \texttt{LD} and \texttt{RD} labels); in the case of top and bottom pin, either at the left (\texttt{TL} and \texttt{BL}) or at the right (\texttt{TR} and \texttt{BR}). The font is specified in the key \texttt{muxdemux/outer label font} (default \verb|\tiny|) and the padding with the corresponding \texttt{muxdemux/outer label xsep} and  \texttt{muxdemux/outer label ysep} (default for both \texttt{2pt}), or \texttt{muxdemux/outer label sep} to set both at the same time.
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}
+\ctikzset{muxdemux/outer label
+    font={\tiny\ttfamily\color{blue}}}
+\tikzset{myICwl/.style={muxdemux,
+    muxdemux def={Lh=4, Rh=4, w=4,
+        NR=1, NL=2, NB=2, NT=2,},
+    muxdemux label={L1=left1, L2=left2,
+        R1=r1, B2=b2, T1=t1, T2=t2,
+        LU1=lu1, LU2=lu2, LD1=ld1, LD2=ld2,
+        BR1=br1, BL1=bl1, BR2=br2, BL2=bl2,
+        RU1=ru1, RD1=rd1,TR2=tr2, TL2=tl2,
+        TR1=tr1, TL1=tl1},}
+}
+\draw (0, 0) node[myICwl]{chip} ++(3,0)
+    node[myICwl, rotate=-90]{chip};
+\draw (0, -3) node[myICwl]{chip} ++(3,0)
+    node[myICwl, rotate=-90,
+        rotated numbers]{chip};
+\end{circuitikz}
+\end{LTXexample}
+
+\paragraph{Border labels} are drawn \emph{before} the other labels along the external border (to be exact: in north, south, east, and west position) of the component.
+You set them with the key \texttt{N}, \texttt{S}, \texttt{W}, and \texttt{E} for the outer position, and \texttt{Ni}, \texttt{Si}, \texttt{Wi}, and \texttt{Ei} for the inner ones.
+The font is specified in the key \texttt{muxdemux/border label font} (default \verb|\tiny|) and the padding with the corresponding \texttt{muxdemux/border label xsep} and  \texttt{muxdemux/border label ysep} (default for both \texttt{2pt}), or \texttt{muxdemux/border label sep} to set both at the same time.
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz}
+\ctikzset{muxdemux/outer label
+    font={\tiny\ttfamily\color{blue}}}
+\tikzset{myICwl/.style={muxdemux,
+    muxdemux def={Lh=4, Rh=4, w=4,
+        NR=1, NL=2, NB=0, NT=0,},
+    muxdemux label={L1=inA, L2=inB,
+        R1=OUT, RU1=3, LU1=1, LU2=2,
+        N=mychip},}
+}
+\draw (0, 0) node[myICwl]{} ++(3,0)
+    node[myICwl, rotate=180]{};
+\draw (0, -3) node[myICwl,
+    muxdemux label={N=another}]{};
+\end{circuitikz}
+\end{LTXexample}
+
+As you can see, you can locally change any label in a specific instance.
+
+\paragraph{Clock and negation symbols} are not exactly labels, but they can be added with the same mechanism. There are four symbols available:
+\begin{description}
+    \item [clock wedge:] activated by the key \texttt{c} followed by the position (for example, \texttt{cL2} will set the clock wedge on the second left pin); its size can be changed with the key \texttt{muxdemux/clock wedge size} (default \texttt{0.2}, relative to \texttt{muxdemux/base len});
+    \item [not ball:] activated  by the key \texttt{n} followed by the position (for example, \texttt{cR1} will set the negation circle on the first right pin); the type and shape of the ball will depend on the logic port negation in use (basically it will use a \texttt{circleinv} shape unless you are using european ports with the small \texttt{ocirc} negation symbol);
+    \item [wedge in:] a wedge negation \emph{entering} the component (with the point on the border), activated  by the key \texttt{wi} followed by the position;
+    \item [wedge out:] a wedge negation \emph{exiting} the component (with the base on the border), activated  by the key \texttt{wo} followed by the position.
+\end{description}
+The value of the key should be \texttt{0}  or \texttt{1} for clocks and not circles; zero means ``do not draw'' and is used to override a previously specified element. In the case of wedge-style not, the \texttt{-1} value flips the side of the triangle (see the following example).
+
+\begin{LTXexample}[varwidth=true]
+\begin{circuitikz} \ctikzset{muxdemux/outer label
+    font={\tiny\ttfamily\color{blue}}}
+\ctikzset{logic ports=ieee, multipoles/external pins width=0.3}
+\tikzset{myICwl/.style={muxdemux,
+    muxdemux def={Lh=4, Rh=4, w=4, NR=2, NL=2, NB=1, NT=0,},
+    muxdemux label={L1=inA, L2=inB, R1=OUT, RU1=3, LU1=1, LU2=2,
+        N=example, nL1=1, woR1=1, woR2=-1, wiB1=1, cL2=1},}
+}
+\draw (0, 0) node[myICwl]{};
+\draw (0, -3) node[myICwl,
+    muxdemux label={N=another, LU1={1\strut},
+        RU1={3\strut}, cL2=0}](A){};
+\draw[red, <-] (A-nL1.-135) -- ++(-135:0.3);
+\end{circuitikz}
+\end{LTXexample}
+
+As you can see, the label position is not affected (with the exception of the clock wedge, that displaces the inner label), so you have to manually take care of not having overruns; you can change the \texttt{xsep} or \texttt{ysep} or, as shown in the example, modify the heigh and depth of the affected labels.
+
+You have also to take care of the effect shown for the flip-flops in section~\ref{sec:flip-flop-cust}, to avoid overrun the not circles when connecting wires. The ``not'' elements are named after the instance as \texttt{\textsl{<nodename>}-\textsl{<activating key>}} to give access to the border (show also in the example, although in bit of forced way\dots look at the red arrow).
+
+\subsubsection{Manually adding wedges or circular inversion markers}\label{sec:wedge-inversion}
+
+If the standard ``internal'' negation symbols are not sufficiently configurable for your application, you can add them manually.
+To add the wedge symbol, the \texttt{wedgeinv} shape will nicely do. It'll scale with the \texttt{muxdemuxes} class, and the length and height can be changed with the keys \texttt{wedge inversion mark/width} (default \texttt{0.2}) and \texttt{height} (default \texttt{0.1}), with the same units that are used for the \texttt{external pins width} and similar keys.
 
 Similarly, there is also a \texttt{circleinv} shape, which is basically the same as the \texttt{notcirc} (see~\ref{sec:ieeestdports}) one, but that scales with the \texttt{muxdemuxes} class and that has the default anchor at its left, similarly to \texttt{wedgeinv}. This one will be filled if the class says so, contrary to the wedge-like shapes that are always open.
 
@@ -7310,6 +7432,52 @@ Similarly, there is also a \texttt{circleinv} shape, which is basically the same
 \end{tikzpicture}
 \end{LTXexample}
 
+\subsubsection{Adding a background drawing to the muxdemux}
+
+In a similar way to the oscilloscope waveform, you can add a drawing to the \texttt{muxdemux} component, provided you use basic-level \texttt{pgf} commands. You have to define a \texttt{.code} key named \texttt{bgpicture} in the \texttt{muxdemux def} definitions, as in the following example. The coordinate system is changed so that the horizontal axis of the shape is mapped between \SI{-1}{\cm} and \SI{+1}{\cm} and the origin at the center; the vertical extent will then depend on the form factor of the \texttt{muxdemux}: for example, the vertical coordinate of the top left border will be $\SI{1}{\cm}\cdot{\mathtt{Lh}/\mathtt{w}}$.
+
+\begin{LTXexample}[varwidth=true, basicstyle=\scriptsize\ttfamily, keepspaces=true]
+\begin{circuitikz}
+\ctikzset{muxdemux/outer label font={\tiny\ttfamily\color{blue}}}
+\tikzset{myICwl/.style={muxdemux,
+    muxdemux def={Lh=4, Rh=4, w=3, NR=1, NL=2, NB=0, NT=0,
+    bgpicture/.code={%
+        \pgfsetcolor{gray!50}\pgfsetlinewidth{1mm}
+        \pgfpathmoveto{\pgfpoint{-1cm}{1cm*4/3}} \pgfpathlineto{\pgfpointorigin}
+        \pgfpathmoveto{\pgfpoint{-1cm}{-1cm*4/3}}\pgfpathlineto{\pgfpointorigin}
+        \pgfpathmoveto{\pgfpoint{1cm}{0cm}}      \pgfpathlineto{\pgfpointorigin}
+        \pgfpathcircle{\pgfpointorigin}{0.5cm}
+        \pgfusepath{draw}
+        },
+    },
+    muxdemux label={RU1=3, LU1=1, LU2=2, N=flux, Ni=converter},}
+}
+\draw (0, 0) node[myICwl]{}{};
+\end{circuitikz}
+\end{LTXexample}
+
+You can even embed images:
+
+\begin{LTXexample}[varwidth=true, basicstyle=\scriptsize\ttfamily]
+\begin{circuitikz}
+\ctikzset{muxdemux/outer label font={\tiny\ttfamily\color{blue}}}
+\tikzset{myICwl/.style={muxdemux,
+    muxdemux def={Lh=4, Rh=4, w=3, NR=1, NL=2, NB=0, NT=0,
+    bgpicture/.code={%
+            \pgfdeclareimage[width=1.5cm]{myimg}{example-image-a}
+            \pgftext{\pgfuseimage{myimg}}
+        },
+    },
+    muxdemux label={RU1=3, LU1=1, LU2=2, N=embedding, Ni=images},}
+}
+\draw (0, 0) node[myICwl]{}{};
+\end{circuitikz}
+\end{LTXexample}
+
+
+For more complex things, consider using a normal macro that draws on the background layer and that use the geographical coordinates of the node to locate it.
+
+
 \subsubsection{Mux-Demux special usage}
 
 You can use these shapes  to draw a lot of symbols that are unavailable; using a bit of \LaTeX{} command trickery you can use them quite naturally too\dots. Examples with personalized amplifier shapes are listed in section~\ref{sec:muxdemux-amplis}.
@@ -7331,21 +7499,19 @@ As an additional example, this was used before the introduction of the \texttt{d
 \end{circuitikz}
 \end{LTXexample}
 
-Finally, you can play with them to create chips that have generic numbers of pins on the four sides, as in the following example (asked on \href{https://tex.stackexchange.com/q/596320/38080}{TeX.Stackexchange}):
+Finally, you can play with them to create chips that have generic numbers of pins on the four sides, as in the following example (asked on \href{https://tex.stackexchange.com/q/596320/38080}{TeX.Stackexchange}; notice however that this example has been made \emph{before} the option for labels existed; it could be quite streamlined now, as shown later):
 
-\begin{LTXexample}[varwidth=true]
-\begin{tikzpicture}[scale=0.8, transform shape]
+\begin{LTXexample}[varwidth=true, basicstyle=\scriptsize\ttfamily]
+\begin{tikzpicture}[scale=0.7, transform shape]
     \tikzset{ic555/.style={muxdemux,
-            muxdemux def={Lh=10, NL=5, Rh=10, NR=5,
-            NB=2, w=6, NT=2, square pins=1},
+            muxdemux def={Lh=10, NL=5, Rh=10, NR=5, NB=2, w=6, NT=2,
+            square pins=1},
         no input leads, external pins width=0.4,
         circuitikz/muxdemuxes/fill=blue!10}
     }
-    \node [ic555, font=\small\ttfamily,align=center](A)
-        at (0,0) {555\\Astable};
+    \node [ic555, font=\small\ttfamily,align=center](A) at (0,0) {555\\Astable};
     % left pins
-    \foreach \rawpin/\npin/\label in
-        {2/7/Discharge, 4/2/Trigger, 5/6/Threshold} {
+    \foreach \rawpin/\npin/\label in {2/7/Discharge, 4/2/Trigger, 5/6/Threshold}{
         \draw (A.lpin \rawpin) -- (A.blpin \rawpin)
             node[midway, blue, font=\small, above]{\npin}
             node[right, font=\small]{\label};
@@ -7360,12 +7526,32 @@ Finally, you can play with them to create chips that have generic numbers of pin
         \draw (A.bpin \rawpin) -- (A.bbpin \rawpin)
             node[midway, blue, font=\small, left]{\npin};
     }
-    % finally, left
+    % finally, right
     \draw (A.rpin 3) -- (A.brpin 3)
         node[midway, blue, font=\small, above]{3};
 \end{tikzpicture}
 \end{LTXexample}
 
+In a version of \Circuitikz{} better or equal to \texttt{v1.6.5}, you can do this:
+
+\begin{LTXexample}[varwidth=true, basicstyle=\scriptsize\ttfamily]
+\begin{tikzpicture}[scale=0.7, transform shape]
+\ctikzset{muxdemux/inner label font=\small}
+\ctikzset{muxdemux/outer label font={\small\color{blue}}}
+    \tikzset{ic555/.style={muxdemux,
+        muxdemux def={Lh=10, NL=5, Rh=10, NR=1, NB=2, w=6, NT=2},
+        muxdemux label={L2=Discharge, L4=Trigger, L5=Threshold,
+        T1=VCC, B2=GND,
+        LU2=7, LU4=2, LU5=6, TL1=8, TL2=4, RU1=3, BL1=5, BL2=1},
+        external pins width=0.4,
+        draw only left pins={2,4,5},
+        circuitikz/muxdemuxes/fill=blue!10}
+    }
+    \node [ic555, font=\small\ttfamily,align=center](A)
+        at (0,0) {555\\Astable};
+\end{tikzpicture}
+\end{LTXexample}
+
 
 \subsection{Chips (integrated circuits)}\label{sec:chips}
 
@@ -7471,7 +7657,7 @@ with the \texttt{bpin \textit{n}} anchors for the suppressed pins.
     \end{circuitikz}
 \end{LTXexample}
 
-\subsubsection{Chips anchors}
+\subsubsection{Chip anchors}
 
 Chips have anchors on pins and global anchors for the main shape.
 The pin anchors to be used to connect wires to the chip are called \texttt{pin 1}, \texttt{pin 2} , \dots, with just one space between \texttt{pin} and the number.
@@ -7506,7 +7692,7 @@ Additionally, you have geometrical anchors on the chip ``box'', see the followin
     \end{circuitikz}
 \end{quote}
 
-\subsubsection{Chips rotation}
+\subsubsection{Chip rotation}\label{sec:chip-rotation}
 
 You can rotate chips, and normally the pin numbers are kept straight (option \texttt{straight numbers}, which is the default), but you can rotate them if you like with \texttt{rotated numbers}.
 Notice that the main label has to be (counter-) rotated manually in this case.
@@ -8478,6 +8664,25 @@ Negative values do work as expected:
 \end{circuitikz}
 \end{LTXexample}
 
+Unfortunately\footnote{see \href{https://github.com/circuitikz/circuitikz/issues/747}{this bug report}.} the amount of shift given by \texttt{voltage shift} is not always the same between sources and passive bipoles, especially if the sizes of the component is very different from the default. Although this qualifies as a bug, and should be fixed in a more comprehensive way, a workaround is available with the key \texttt{voltage shift sources adjust} (default: \texttt{\ctikzvalof{voltage shift sources adjust}}). A smaller value is better for smaller components, as you can see in the example below.
+
+\begin{LTXexample}[varwidth=true, basicstyle=\small\ttfamily]
+\newcommand{\example}[2][]{\draw[#1] (#2)
+        to [V_=$U$] ++(0, -1) (#2) ++(2,0)
+        to [R,v=$U_R$] ++(0,-1);
+    }
+\ctikzset{resistors/scale=0.55,inductors/scale=0.55,
+    capacitors/scale=0.6,sources/scale=.8}
+\begin{circuitikz}[circuitikz/voltage=straight,
+    voltage dir=EF]
+    \example{0,4}
+    \ctikzset{voltage shift=2}
+    \example[color=red]{0,2}
+    \ctikzset{voltage shift sources adjust=0.2}
+    \example[color=blue]{0,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 from the lines of the symbols, default \texttt{1.4}) for the latter.
 
 \begin{LTXexample}[varwidth=true]