summaryrefslogtreecommitdiff
path: root/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex')
-rw-r--r--graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex94
1 files changed, 58 insertions, 36 deletions
diff --git a/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex b/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
index 45de64ab48..4186402412 100644
--- a/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
+++ b/graphics/pgf/contrib/circuitikz/doc/circuitikzmanual.tex
@@ -5,10 +5,10 @@
% !TeX spellcheck = en_US
% !TeX encoding = utf8
-% Copyright 2018-2020 by Romano Giannetti
-% Copyright 2015-2020 by Stefan Lindner
-% Copyright 2013-2020 by Stefan Erhardt
-% Copyright 2007-2020 by Massimo Redaelli
+% Copyright 2018-2021 by Romano Giannetti
+% Copyright 2015-2021 by Stefan Lindner
+% Copyright 2013-2021 by Stefan Erhardt
+% Copyright 2007-2021 by Massimo Redaelli
%
% This file may be distributed and/or modified
%
@@ -280,7 +280,8 @@ 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.
You can check the used version at your local installation using the macro \verb!\pgfcircversion{}!.
\begin{itemize}
- \item Due to a bug fix in \TikZ{} that revealed a problem in \Circuitikz, you \textbf{must} upgrade to v1.2.7 or newer if you use a \TikZ{} 3.1.8 or 3.1.8a (the change in \TikZ{} has been reverted later).
+ \item After 1.2.7 a big code reorganization (which by the way fixed some bug) has been made; no changes should be visible, but a fallback point at 1.2.7 has been added.
+ \item You \textbf{must} upgrade to v1.2.7 or newer if you use a \TikZ{} 3.1.8 or 3.1.8a (but better upgrade both packages to the current version).
\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[...]}).
@@ -307,13 +308,13 @@ You can check the used version at your local installation using the macro \verb!
If you have older projects that show compatibility problems, you have two options:
\begin{itemize}
\item you can use an older version locally using the git-version and picking the correct commit from the repository (branch gh-pages) or the main GitHub site directly;
- \item if you are using \LaTeX, the distribution has embedded several important old versions: \texttt{0.4}, \texttt{0.6}, \texttt{0.7}, \texttt{0.8.3}, \texttt{0.9.3}, \texttt{0.9.6}, \texttt{1.0} and \texttt{1.1.2}.
+ \item if you are using \LaTeX, the distribution has embedded several important old versions: \texttt{0.4}, \texttt{0.6}, \texttt{0.7}, \texttt{0.8.3}, \texttt{0.9.3}, \texttt{0.9.6}, \texttt{1.0}, \texttt{1.1.2} and \texttt{1.2.7}.
To switch to use them, you simply change your \verb|\usepackage| invocation like
\begin{lstlisting}
\usepackage[]{circuitikz-0.8.3} % or circuitikz-0.4, 0.6...
\end{lstlisting}
You have to take care of the options that may have changed between versions;
- \item if you are using \ConTeXt, only versions \texttt{0.8.3}, \texttt{0.9.3}, \texttt{0.9.6}, \texttt{1.0} and \texttt{1.1.2} are packaged; if can use it with
+ \item if you are using \ConTeXt, only versions \texttt{0.8.3}, \texttt{0.9.3}, \texttt{0.9.6}, \texttt{1.0}, \texttt{1.1.2} and \texttt{1.2.7} are packaged; if can use it with
\begin{lstlisting}
\usemodule[circuitikz-0.8.3]
\end{lstlisting}
@@ -1124,7 +1125,7 @@ The above diagram has been obtained with the code:
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).
-This behavior, although not optimal, was standard in \texttt{to} operation in plain \TikZ{} before version 3.1.18; 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}.
+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}.
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).
@@ -5804,14 +5805,28 @@ The position of annotations and labels can be adjusted with \verb|_| and \verb|
\end{circuitikz}
\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 from the option parser using an \verb|\mbox| command, or redefining the characters with a \TeX\ \verb|\def|:
+\textbf{Caveat:} when \TikZ{} processes the options, there will be problems if the label (or annotation, voltage, or current) contains one of the characters $=$ (equal) or $,$ (comma) --- because the parser search for those two characters to delimit the arguments, giving unexpected errors and wrong output.
+These two characters can be protected from the option parser using an extra set of braces.
\begin{LTXexample}[varwidth=true]
- \def\eq{=}
\begin{circuitikz}
% the following will fail:
- % \draw (0,0) to[R, l={$R=3}] (3,0);
+ % \draw (0,0) to[R, l=$R=3$]
+ \draw (0,0) to[R, l={$R=3$}] (3,0);
+ \draw (0,0) to[R={$R=3$}] (0,3);
+ \draw (3,3) to[R={$R,3$}] (3,0);
+ % this works, but it has wrong spacing
+ \draw (0,3) to[R, l=$R{=}3$] (3,3);
+ \end{circuitikz}
+\end{LTXexample}
+
+\textbf{(Even more) Caveat:} up to version \texttt{1.2.7}, due to the way in which \Circuitikz{} used to processes the options, even that was not sufficient, so you must protect that tokens even more, for example using an \verb|\mbox| command, or redefining the characters with a \TeX\ \verb|\def|:
+
+\begin{LTXexample}[varwidth=true]
+ \begin{circuitikz}
+ \def\eq{=}
+ % the following will fail up to 1.2.7:
+ % \draw (0,0) to[R, l={$R=3$}] (3,0);
\draw (0,0) to[R, l=\mbox{$R=3$}] (3,0);
\draw (0,0) to[R, l=$R\eq3$] (0,3);
\draw (3,3) to[R, l=\mbox{$R,3$}] (3,0);
@@ -5820,6 +5835,7 @@ These two characters must be protected from the option parser using an \verb|\mb
\end{circuitikz}
\end{LTXexample}
+
\noindent The default orientation of labels is controlled by the options \texttt{smartlabels}, \texttt{rotatelabels} and \texttt{straightlabels} (or the corresponding \texttt{label/align} keys). Here are examples to see the differences:
\begin{LTXexample}[varwidth=true]
\begin{circuitikz}
@@ -7552,9 +7568,11 @@ Just substitute every occurrence of the environment \verb!circuitikz! with \verb
\faqQ I cannot write \verb!to[R = $R_1=12V$]! nor \verb!to[ospst = open, 3s]!: I get errors.
-\faqA It is a limitation of the parser, joined with a suboptimal processing by \Circuitikz{} of the passing of the argument of keys.
+\faqA It is a limitation of the parser, joined with a suboptimal processing by \Circuitikz{} (up to \texttt{1.2.7}) of the passing of the argument of keys.
-Use for example \verb|\mbox{}| or define \verb|\def{\eq}{=}| and use \verb!to[R = $R_1\eq 12V$]!, or try to protect commas and equal signs like \verb!to[ospst = open{,} 3s]! or \verb|ospst=\mbox{open, 3s}| instead; see caveat in section~\ref{sec:labels-and-annotations}.
+You should protect commas and equal signs like in \verb!to[R = {$R_1=12V$}]! or \verb!to[ospst = {open, 3s}]!.
+
+In versions up to \texttt{1.2.7}, use for example \verb|\mbox{}| or define \verb|\def{\eq}{=}| and use \verb!to[R = $R_1\eq 12V$]!, or try to protect commas and equal signs like \verb!to[ospst = open{,} 3s]! or \verb|ospst=\mbox{open, 3s}| instead; see caveat in section~\ref{sec:labels-and-annotations}.
\subsection{Global scaling and rotating}\label{faqs:scale-and-rotate}
@@ -7581,15 +7599,16 @@ Use for example \verb|\mbox{}| or define \verb|\def{\eq}{=}| and use \verb!to[R
\textbf{Big fat warning}: this material is reserved to \TeX-hackers; do not delve into this if you have no familiarity with (at least) a bit of core \TeX{} programming and to the basic \TikZ{} layer. You have been warned.
-
\subsection{Suggested setup}
+Notice: the source code has been re-organized after release 1.2.7; if you are bound to use an older version check the corresponding manual.
+
The suggested way to start working on a new component is to use the utilities of the \Circuitikz{} manual for checking and testing your device. Basically, find (or download) the source code of the last version of \Circuitikz{} and find the file \texttt{ctikzmanutils.sty}; copy it in your directory and prepare a file like this:
-\begin{lstlisting}
+\begin{lstlisting}[keepspaces=true]
\documentclass[a4paper, titlepage]{article}
-\usepackage{a4wide} %smaller borders
-\usepackage[utf8]{inputenc}
+\usepackage{a4wide} %smaller borders
+\usepackage[utf8]{inputenc} %not needed since LaTeX 2019
\usepackage[T1]{fontenc}
\parindent=0pt
\parskip=4pt plus 6pt minus 2pt
@@ -7640,7 +7659,10 @@ From now on, you can add the new commands for the component between the \verb|\m
Let's define for example a path style component, like the one suggested by the user \texttt{@alex} on \href{https://tex.stackexchange.com/questions/484268/combined-spring-damper-in-circuitikz}{\TeX{} stackexchange site}. The component will be a mix of the \texttt{damper} and the \texttt{spring} components already present.
-The first step is to check if we can use the definition already existing for similar elements (for coherence of size) or if we need to define new ones; for this you have to check the file \texttt{pgfcirc.defines.tex}: we find
+The definitions of the components are in the files \texttt{pgfcirc\emph{something}.tex}; they are more or less distributed by the number of terminals, but there are exceptions (for example, switches are in \texttt{bipoles}, even if several of them are tripoles or more\dots \texttt{grep} is your friend here.
+
+To define the new component we will look into (in this case) \texttt{pgfcircbipoles.tex}; at the start of the block where the components are defined you can find the relevant definitions (sometime some of the definitions are in \texttt{pgfcirc.defines.tex}, for historical or dependencies reasons).
+The first step is to check if we can use the definition already existing for similar elements (for coherence of size) or if we need to define new ones; for this you have to check into the we find
\begin{lstlisting}
\ctikzset{bipoles/spring/height/.initial=.5}
@@ -7652,9 +7674,10 @@ The first step is to check if we can use the definition already existing for sim
We will use them; at this stage you can decide to add other parameters if you need them. (Notice, however, than although flexibility is good, these parameters should be described in the manual, otherwise they're as good as a fixed number in the code).
-To define the new component we will look into \texttt{pgfcircbipoles.tex} and we will copy, for example, the definition of the damper into our code, just changing the name:
-\begin{lstlisting}
+After that we will copy, for example, the definition of the damper into our code, just changing the name:
+
+\begin{lstlisting}[keepspaces=true]
%% mechanical resistor - damper
\pgfcircdeclarebipolescaled{mechanicals}
{} % extra anchors
@@ -7694,21 +7717,20 @@ To define the new component we will look into \texttt{pgfcircbipoles.tex} and we
}
\end{lstlisting}
-This command will define a shape that is named \texttt{viscoeshape}, with all the correct geographical anchors based on the depth, height and width defined in the parameters of \verb|\pgfcircdeclarebipolescaled|. Moreover, the element is assigned to the class \texttt{mechanicals} for styling.
+This \verb|\pgfcircdeclarebipolescaled| command will define a shape that is named \texttt{viscoeshape}, with all the correct geographical anchors based on the depth, height and width defined in the parameters: in this case we are reusing the ones of the \texttt{damper} shape. Moreover, the element is assigned to the class \texttt{mechanicals} for styling.
-To be coherent with the styling, you should use (when needed) the length \verb|\pgf@circ@scaled@Rlen| as the ``basic'' length for drawing, using the fill functions defined at the start of \texttt{pgfcirc.defines.tex} to fill and stroke --- so that the operation will follow the style parameters and, finally, use the macro \verb|\pgf@circ@setlinewidth| to set the line thickness /the first argument is the ``legacy'' class, if you do not want to assign one you can use the pseudo-legacy class \texttt{none}.
+To be coherent with the styling, you should use (when needed) the length \verb|\pgf@circ@scaled@Rlen| as the ``basic'' length for drawing, using the fill functions (they are defined at the start of the file \texttt{pgfcirc.defines.tex}) to fill and stroke --- so that the operation will follow the style parameters and, finally, use the macro \verb|\pgf@circ@setlinewidth| to set the line thickness: the first argument is the ``legacy'' class, if you do not want to assign one you can use the pseudo-legacy class \texttt{none}.
-The anchors for the bipole (which then set the lengths \verb|\pgf@circ@res@left|) are already scaled for your use. You can use these lenghts (which defines, normally, the geographical anchors of the element) to draw your shapes.
+The anchors for the bipole (which then set the lengths \verb|\pgf@circ@res@left|) are already scaled for your use. You can use these lengths (which defines, normally, the geographical anchors of the element) to draw your shapes.
-This is not sufficient for using the element in a \texttt{to[]} path command; you need to ``activate'' it with (this commands are normally in \texttt{pgfcircpath.tex}):
+This is not sufficient for using the element in a \texttt{to[]} path command; you need to ``activate'' it (the definition of the commands are normally in \texttt{pgfcircpath.tex}). In this case the component is simple --- look at the definitions if you need to do more complex things.
\begin{lstlisting}
-\def\pgf@circ@viscoe@path#1{\pgf@circ@bipole@path{viscoe}{#1}}
-\compattikzset{viscoe/.style = {\circuitikzbasekey,
- /tikz/to path=\pgf@circ@dviscoe@path, l=#1}}
+\pgfcirc@activate@bipole@simple{l}{viscoe}
\end{lstlisting}
-And now you can show it with:
+In the definition above, the \texttt{\{l\}} parameter means that using the component like \texttt{to[viscoe=A]} will be equivalent to \texttt{to[viscoe, l=A]}; you can use also \texttt{v} or \texttt{i} or \texttt{f} if your component needs it.
+Now you can show it with:
\begin{lstlisting}
\circuitdescbip*{viscoe}{Mechanical viscoelastic element}{}(left/135/0.2, right/45/0.2, center/-90/0.3)
@@ -7723,13 +7745,14 @@ And now you can show it with:
\end{LTXexample}
\end{lstlisting}
-Obviously, at first you you just have a component that is the same as the one you copied with another name. It is now just a matter of modifying it so that it has the desired shape; in the example above you can already see the new symbol after the changes.
+Obviously, at first you you just have a component that is the same as the one you copied with another name.
+It is now just a matter of modifying it so that it has the desired shape; in the example above you can already see the new symbol after the changes.
-When doing the drawing, the \verb|\pgfcircdeclarebipole| will setup the lengths \verb|\pgf@circ@res@right|
-and \verb|\pgf@circ@res@up| as the $x$-$y$ coordinates of the upper right corner, and
-\verb|\pgf@circ@res@left| and \verb|\pgf@circ@res@down| as the $x$-$y$ coordinates of the lower left corner of your shape. The \texttt{center} coordinate is usually at $(0pt, 0pt)$.
+When doing the drawing in the main argument of the \verb|\pgfcircdeclarebipole|, things will be setup so that the lengths \verb|\pgf@circ@res@right|
+and \verb|\pgf@circ@res@up| are the $x$-$y$ coordinates of the upper right corner, and
+\verb|\pgf@circ@res@left| and \verb|\pgf@circ@res@down| are the $x$-$y$ coordinates of the lower left corner of your shape. The \texttt{center} coordinate is usually at $(0pt, 0pt)$.
-Looking at the implementation of the \texttt{spring} element, a possible implementation is changing the lines between lines~12 and~16 with:
+Looking at the implementation of the \texttt{spring} element, one possibility is changing the lines between lines~12 and~16 with:
\begin{lstlisting}
% spring into the damper
@@ -7780,6 +7803,7 @@ If you think they are too tight or too loose you can use a (developer-only) key
Notice that by default the key \texttt{bipoles/\emph{mybipole}/voltage/additional shift} is not defined, so if you want to use it you must create it before (this is the meaning of the \texttt{.initial} here).
+Now you can save all the code between the \verb|\makeatletter| and \verb|\makeatother| in a file and \verb|\input{}| it for using your special component, or submit the component to the project (see below).
As a final note, notice that the \texttt{viscoe} element is already added to the standard package.
@@ -7820,8 +7844,6 @@ Once you have a satisfactory element, you should
The best way of contributing is forking the project, adding your component in the correct files, modifying the manual and creating a pull request for the developers to merge. Anyway, if this is a problem, just open an issue and someone (when they have time\dots) will answer.
-
-
\section{Examples}
Here a series of example, contributed by several people, is shown with their code.