summaryrefslogtreecommitdiff
path: root/graphics/circuit_macros/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-10-14 03:01:58 +0000
committerNorbert Preining <norbert@preining.info>2022-10-14 03:01:58 +0000
commit1c0d5e0721918b8ee790c9f1c11f1543e0403322 (patch)
tree945544ad8dae56580c1578e1d2c96c7fe0fc29eb /graphics/circuit_macros/doc
parentba720f8eaac74c537fb16f8556e4cf0ab4cd8235 (diff)
CTAN sync 202210140301
Diffstat (limited to 'graphics/circuit_macros/doc')
-rw-r--r--graphics/circuit_macros/doc/Circuit_macros.pdfbin1023203 -> 1025740 bytes
-rw-r--r--graphics/circuit_macros/doc/PconnMan.m42
-rw-r--r--graphics/circuit_macros/doc/Version.tex2
-rw-r--r--graphics/circuit_macros/doc/body.tex136
-rw-r--r--graphics/circuit_macros/doc/defines.tex78
5 files changed, 122 insertions, 96 deletions
diff --git a/graphics/circuit_macros/doc/Circuit_macros.pdf b/graphics/circuit_macros/doc/Circuit_macros.pdf
index 9c67589a6f..6e109a06de 100644
--- a/graphics/circuit_macros/doc/Circuit_macros.pdf
+++ b/graphics/circuit_macros/doc/Circuit_macros.pdf
Binary files differ
diff --git a/graphics/circuit_macros/doc/PconnMan.m4 b/graphics/circuit_macros/doc/PconnMan.m4
index 0933af6810..2543048d00 100644
--- a/graphics/circuit_macros/doc/PconnMan.m4
+++ b/graphics/circuit_macros/doc/PconnMan.m4
@@ -43,7 +43,7 @@ P2: [
`"\tt (L,GF)"' at last [].s below
C10: pconnex(,GC) with .w at last [].e + (0.2,0)
`"\tt (,GC)"' ht 11pt__ at last [].s below
- C10: pconnex(,GCF) with .w at last [].e + (0.2,0)
+ C12: pconnex(,GCF) with .w at last [].e + (0.2,0)
`"\tt (,GCF)"' ht 11pt__ at last [].s below
C4: pconnex(,P) with .w at last [].e + (0.2,0)
diff --git a/graphics/circuit_macros/doc/Version.tex b/graphics/circuit_macros/doc/Version.tex
index 45c581b3af..c0b5abb2fd 100644
--- a/graphics/circuit_macros/doc/Version.tex
+++ b/graphics/circuit_macros/doc/Version.tex
@@ -1 +1 @@
-Version 9.9
+Version 10.0
diff --git a/graphics/circuit_macros/doc/body.tex b/graphics/circuit_macros/doc/body.tex
index b984ec0435..dc0738769f 100644
--- a/graphics/circuit_macros/doc/body.tex
+++ b/graphics/circuit_macros/doc/body.tex
@@ -613,12 +613,12 @@ circle diameter (last circle.width * 1.2) with .sw at last circle.ne}
The planar objects can be filled with gray or colour.
For example, either
-{\tt box dashed fill\_({\sl number})}\quad or\quad
+{\tt box dashed fill\_({\sl expression})}\quad or\quad
{\tt box dashed outlined "{\sl color}" shaded "{\sl color}"}
\noindent
produces a dashed box. The first case has a gray fill determined by
-{\sl number}, with $0$ corresponding to black and $1$ to white;
+{\sl expression}, with $0$ corresponding to black and $1$ to white;
the second case allows color outline and fill, the color strings depending on
the postprocessor.
Postprocessor-compatible RGB color strings are produced by the macro
@@ -666,10 +666,11 @@ function).
\subsection{Compound objects\label{Compoundobjects:}}
A compound object is a group of statements enclosed in square
-brackets. Such an object is placed by default as if it were a box, but
+brackets. Such an object, often called a {\em block},
+is placed by default as if it were a box, but
it can also be placed by specifying the final position of a defined point.
A defined point is the center or compass corner of the bounding box
-of the compound object or one of its internal objects.
+of the object or one of its internal objects.
Consider the last line of the code fragment shown:
\noindent%
@@ -683,6 +684,7 @@ The two gate macros evaluate to compound objects containing {\tt Out},
{\tt In1}, and other locations. The final positions of all objects
inside the square brackets are determined in the last line by
specifying the position of {\tt In1} of gate {\tt And2}.
+The compound block has been given the name {\tt Ands.}
\subsection{Other language facilities\label{Otherlanguage:}}
@@ -754,8 +756,8 @@ operating-system commands, \pic macros, and external file inclusion.
\xection{Two-terminal circuit elements\label{Basictwo:}}
There is a fundamental difference between the two-terminal elements, each
of which is drawn along an invisible straight-line segment,
-and other elements, which are compound objects mentioned
-in \SR{Compoundobjects:}.
+and other elements, which are generally compound objects
+in {\tt[} {\tt]} blocks as mentioned in \SR{Compoundobjects:}.
% Specifying the straight-line segment requires four numbers, the coordinates
% of the start and end, or equivalent, but default values are used if
% not specified.
@@ -827,11 +829,12 @@ and the remaining source lines of the file are explained below:
be given a name, {\tt R1} in the example, so that positions
{\tt R1.start}, {\tt R1.centre}, and {\tt R1.end} are automatically
defined as shown.
-\item The element body is overlaid by a block, which can be
- used to place labels around the element. The block
- corresponds to an invisible rectangle with horizontal top and bottom lines,
- regardless of the direction in which the element is drawn. A
- dotted box has been drawn in the diagram to show the block boundaries.
+\item The element body is drawn in or overlaid by a block, which can be
+ used to place labels around the body.
+ The block corresponds to an invisible rectangle with horizontal top
+ and bottom lines, regardless of the direction in which the element
+ is drawn. A dotted box has been drawn in the diagram to show the
+ block boundaries.
\item The last sub-element, identical to the first in two-terminal
elements, is an invisible line that can be referenced later to
place labels or other elements.
@@ -1146,9 +1149,9 @@ quote, in which case the argument is copied literally.
The third argument specifies the separation from the element.
\subsection{Labels\label{Labels:}}
- Arbitrary labels
+ Arbitrary text labels
can be positioned by any \pic\ placement method including the
- representative basic examples shown:
+ basic examples shown:
{\tt "}{\sl text}{\tt" at {\sl position}}\NVL
{\tt "}{\sl text}{\tt" at {\sl position} above}\NVL
@@ -1158,20 +1161,22 @@ The third argument specifies the separation from the element.
In addition, special macros for labeling two-terminal elements are available:
\par
{\tt
- llabel(} {\sl arg1,arg2,arg3} {\tt )
+ llabel(} {\sl label,\ label,\ label,\ rel placement,\ block name} {\tt )
\hfill\break\hspace*{\parindent}%
- clabel(} {\sl arg1,arg2,arg3} {\tt )
+ clabel(} {\sl label,\ label,\ label,\ rel placement,\ block name} {\tt )
\hfill\break\hspace*{\parindent}%
- rlabel(} {\sl arg1,arg2,arg3} {\tt )
+ rlabel(} {\sl label,\ label,\ label,\ rel placement,\ block name} {\tt )
\hfill\break\hspace*{\parindent}%
- dlabel(} {\sl long,lat,arg1,arg2,arg3,}{\tt[X][A|B][L|R])}
-
-The first macro places the three arguments, which are treated as math-mode
-strings, on the left side of the element block {\em with respect to the
-current direction:} {\tt up, down, left, right.}
-The second places the arguments along the centre, and the third along the
-right side.
-A simple circuit example with labels is shown in \FR{Loop}.
+ dlabel(} {\sl long,\ lat,\ label,\ label,\ label,\ }{\tt[X][A|B][L|R])}
+
+The first macro places the first three arguments, which are treated
+as math-mode strings, on the left side of the last {\tt []} block (or
+the block named in the fifth argument if present) {\em with respect to
+the current direction:} {\tt up, down, left, right.} The second macro
+places the strings along the centre of the element, and the third along
+the right side. Labels beginning with {\tt sprintf} or a double quote
+are copied literally rather than assumed to be in math mode. A simple
+circuit example with labels is shown in \FR{Loop}.
\begin{figure}[h!t]
\vspace*{-\baselineskip}
\parbox{4in}{\small \verbatiminput{Loop.m4}}%
@@ -1180,6 +1185,10 @@ A simple circuit example with labels is shown in \FR{Loop}.
\caption{A loop containing labeled elements, with its source code.}
\label{Loop}
\end{figure}
+Most commonly, only
+the first three arguments are needed, and blank arguments are ignored.
+The fourth argument can be {\tt above,} {\tt below,} {\tt left,} or {\tt
+right} to supplement the default relative position.
The macro {\tt dlabel} performs these functions for an
obliquely drawn element, placing the three macro arguments at
{\tt vec\_(-long,lat),} {\tt vec\_(0,lat),} and {\tt vec\_(long,lat)}
@@ -1188,9 +1197,6 @@ In the fourth argument, an {\tt X} aligns the labels with respect to the line
joining the two terminals rather than the element body, and
{\tt A, B, L, R} use absolute {\tt above, below, left,} or {\tt right} alignment
respectively for the labels.
-Labels beginning
-with {\tt sprintf} or a double quote are copied literally rather than
-assumed to be in math mode.
\xection{Placing two-terminal elements\label{Placing:}}
The length and position of a two-terminal element
@@ -1517,6 +1523,7 @@ The fifth argument is a string of characters. {\tt P}
adds a power connection, {\tt R} exchanges the second and
third entries, and {\tt T} truncates the opamp point.
+\enlargethispage{\baselineskip}
Typeset text associated with circuit elements is not rotated by default,
as illustrated by the second and third opamps in \FR{Opamp}.
The {\tt opamp} labels can be rotated if necessary by
@@ -1826,9 +1833,13 @@ and {\sl E} is shown in \FR{ujt}.
\label{ujt}
\end{figure}
-A thyristor macro with predefined internal locations
+The 3 or 4-terminal thyristor macro with predefined internal locations
{\sl G} and {\sl T1,} {\sl T2,} or
- {\sl A,} {\sl K} is in \FR{thyristor}.
+ {\sl A,} {\sl K,} {\sl G,} and {\sl Ga}
+ as appropriate is in \FR{thyristor}.
+Except for the {\sl G} and {\sl Ga} terminals,
+a thyristor (the {\tt IEC} variant excluded)
+is much like a two-terminal element.
\begin{figure}[H]
\input thyristorMan
\vspace*{-1ex}
@@ -1840,10 +1851,9 @@ A thyristor macro with predefined internal locations
to the second argument to draw open arrowheads.}
\label{thyristor}
\end{figure}
-Except for the {\sl G} terminal, a thyristor (the {\tt IEC} variant excluded)
-is much like a two-terminal element. The wrapper macro
-{\tt scr({\sl linespec, chars, label})} and similar macros
-{\tt scs, sus,} and {\tt sbs}
+The wrapper macro
+{\tt thyristor\_t({\sl linespec, chars, label})} and similar macros
+{\tt scr, scs, sus,} and {\tt sbs}
place thyristors using {\sl linespec} as for a two-terminal element,
but require a third argument for the label for the compound block; thus,
@@ -3327,25 +3337,28 @@ distribution. The \latex drawing commands alone or with {\tt eepic}
or {\tt pict2e} extensions are suitable only for simple diagrams.
\xection{Developer's notes\label{Developersnotes:}}
-Years ago in the course of writing a book, I took a few days off to
-write a \pic-like interpreter (\dpic) to eliminate the tedious coordinate
-calculations required when drawing with \latex picture objects.
-The macros in this distribution and the interpreter are the result of that
-effort, drawings I have had to produce since, and suggestions received
-from others. The interpreter has been upgraded over time to generate
-\mfpic, \MetaPost~\cite{metapost}, raw \Postscript, \Postscript with {\tt
-psfrag} tags, raw PDF, \PSTricks, and Ti{\it k}Z PGF output, the latter
-two my preference because of their quality and flexibility, including
-facilities for colour and rotations, together with simple font selection.
-\Xfig{}-compatible output was introduced early on to allow the creation of
-diagrams both by programming and by interactive graphics. \SVG output
-was added relatively recently, and seems suitable for producing web
-diagrams directly and for further editing by the Inkscape interactive
-graphics editor. The latest addition is raw PDF output, which has very
-basic text capability and is most suitable for creating diagrams without
-labels, but on which sophisticated text can be overlaid if necessary.
-\Dpic can write the coordinates of selected locations to an external
-file to be used in overlaying text or other items on the diagram.
+In the course of writing a book in the late 1980s when there was little
+available for creating line diagrams in \latex, I wished to eliminate
+the tedious coordinate calculations required by the \latex
+picture objects that I was then using. The \pic\ language seemed to be a
+good fit for this purpose, and I took a few days off to write a \pic-like
+interpreter (\dpic). The macros in this distribution and the interpreter
+are the result of that effort, drawings I have had to produce since,
+and suggestions received from others. The interpreter has been upgraded
+over time to generate \mfpic, \MetaPost~\cite{metapost}, raw \Postscript,
+\Postscript with {\tt psfrag} tags, raw PDF, \PSTricks, and Ti{\it k}Z
+PGF output, the latter two my preference because of their quality and
+flexibility, including facilities for colour and rotations, together
+with simple font selection. \Xfig{}-compatible output was introduced
+early on to allow the creation of diagrams both by programming and by
+interactive graphics. \SVG output was added relatively recently, and
+seems suitable for producing web diagrams directly and for further editing
+by the Inkscape interactive graphics editor. The latest addition is raw
+PDF output, which has very basic text capability and is most suitable for
+creating diagrams without labels, but on which sophisticated text can
+be overlaid if necessary. \Dpic can write the coordinates of selected
+locations to an external file to be used in overlaying text or other
+items on the diagram.
The simple \pic\ language is but one of many available tools for creating
line graphics. Consequently, the main value of this distribution is
@@ -3363,21 +3376,22 @@ can be worth the effort.
Instead of using \pic macros, I preferred the equally simple but more
powerful \Mfour macro processor, and therefore \Mfour is required here,
-although \dpic now supports \pic-like macros. Free versions of \Mfour
+although \dpic now supports \pic macros. Free versions of \Mfour
are available for Unix and its descendents, Windows, and other operating
systems. Additionally, the simplicity of \Mfour and \pic enables the
writing of custom macros, which are mentioned from time to time in this
manual and included in some of the examples.
If starting over today would I not just use one of the other drawing
-packages available these days? It would depend on the context, but \pic
-remains a good choice for line drawings because it is easy to learn
-and read but powerful enough for coding the geometrical calculations
-required for precise component sizing and placement. It would be nice
-if arbitrary rotations and scaling were simpler and if a general path
-element with clipping were available as in \Postscript. However,
-all the power of \Postscript or \TPGF, for example, remains available,
-as arbitrary postprocessor code can be included with \pic code.
+packages available these days? It would depend on the context, but
+\pic remains a good choice for line drawings because it is easy to learn
+and read but powerful enough (that is, Turing-complete) for coding the
+geometrical calculations required for precise component sizing and
+placement. It would be nice if arbitrary rotations and scaling were
+simpler and if a general path element with clipping were available
+as in \Postscript. However, all the power of \Postscript or \TPGF,
+for example, remains available, as arbitrary postprocessor code can be
+included with \pic code.
The \dpic interpreter has several output-format options that may be
useful. The {\tt eepicemu} and {\tt pict2e} extensions of the
diff --git a/graphics/circuit_macros/doc/defines.tex b/graphics/circuit_macros/doc/defines.tex
index dfcee2f91d..7ac3cbaed4 100644
--- a/graphics/circuit_macros/doc/defines.tex
+++ b/graphics/circuit_macros/doc/defines.tex
@@ -251,6 +251,10 @@
\macrodef{below\_}{below_}{}
{gen}
{string position relative to current direction}
+\macrodef{Between\_}{Between_}{({\sl Pos1, Pos2,distance,}[R])}
+ {gen}
+ {Position {\sl distance} from {\sl Pos1} toward {\sl Pos2}. If
+ the fourth arg is {\tt R} then from {\sl Pos2} toward {\sl Pos1}.}
\macrodef{bi\_tr}{bi_tr}{(\linespec,L|R,P,E)}
{cct}
{left or right, N- or P-type bipolar transistor, without or with envelope
@@ -370,17 +374,18 @@
{gen}
{Upper (lower if arg5={\tt R}) intersection of circles at
{\sl Pos1} and {\sl Pos2}, radius {\sl rad1} and {\sl rad2}}
-\macrodef{clabel}{clabel}{({\sl label},{\sl label},{\sl label},{\sl arg4},%
- {\sl arg5})}
- {cct}
- {Triple label along the drawing axis of an element in the current
- direction \seesect{Labels:}. Labels are placed at the beginning,
- centre, or end of the last {\tt []} block (or a named {\tt []}
- block). The labels are treated as math, but copied literally if
- in double quotes or defined by sprintf. {\sl Arg4} can be {\tt
- above,} {\tt below,} {\tt left,} or {\tt right} to supplement the
- default position. {\sl Arg5} is the optional name of a {\tt []}
- block to be labelled and is {\tt last []} by default}
+\macrodef{clabel}{clabel}{({\sl label},{\sl label},{\sl label},[{\sl arg4}],%
+ [{\sl block name}])}
+ {cct}
+ {Triple label along the draing axis of the body of an element in the
+ current direction \seesect{Labels:}. Labels are placed at the
+ beginning, centre, and end of the last {\tt []} block (or a named
+ {\tt []} block). Each label is treated as math by default, but is
+ copied literally if it is in double quotes or defined by sprintf.
+ {\sl Arg4} can be {\tt above,} {\tt below,} {\tt left,} or {\tt
+ right} to supplement the default relative position. The fifth
+ argument is the optional name of the {\tt []} block to be labelled,
+ which is {\tt last []} by default}
\macrodef{cm\_\_}{cm__}{}
{gen}
{absolute centiimetres}
@@ -1158,17 +1163,18 @@ n|e|s|w,{\sl length})}
\macrodef{ljust\_}{ljust_}{}
{gen}
{ljust with respect to current direction}
-\macrodef{llabel}{llabel}{({\sl label},{\sl label},{\sl label},{\sl arg4},%
- {\sl arg5})}
- {cct}
- {Triple label on the left of an element with respect to the current
- direction \seesect{Labels:}. Labels are placed at the beginning,
- centre, or end of the last {\tt []} block (or a named {\tt []}
- block). The labels are treated as math, but copied literally if
- in double quotes or defined by sprintf. {\sl Arg4} can be {\tt
- above,} {\tt below,} {\tt left,} or {\tt right} to supplement the
- default position. {\sl Arg5} is the optional name of a {\tt []}
- block to be labelled and is {\tt last []} by default}
+\macrodef{llabel}{llabel}{({\sl label},{\sl label},{\sl label},[{\sl arg4}],%
+ [{\sl block name}])}
+ {cct}
+ {Triple label on the left of the body of an element with respect to the
+ current direction \seesect{Labels:}. Labels are placed at the
+ beginning, centre, and end of the last {\tt []} block (or a named
+ {\tt []} block). Each label is treated as math by default, but is
+ copied literally if it is in double quotes or defined by sprintf.
+ {\sl Arg4} can be {\tt above,} {\tt below,} {\tt left,} or {\tt
+ right} to supplement the default relative position. The fifth
+ argument is the optional name of the {\tt []} block to be labelled,
+ which is {\tt last []} by default}
\macrodef{loc\_}{loc_}{({\sl x}, {\sl y})}
{gen}
{location adjusted for current direction}
@@ -1640,17 +1646,18 @@ degrees})}
\macrodef{rjust\_}{rjust_}{}
{gen}
{right justify with respect to current direction}
-\macrodef{rlabel}{rlabel}{({\sl label},{\sl label},{\sl label},{\sl arg4},%
- {\sl arg5})}
- {cct}
- {Triple label on the right of an element with respect to the current
- direction \seesect{Labels:}. Labels are placed at the beginning,
- centre, or end of the last {\tt []} block (or a named {\tt []}
- block). The labels are treated as math, but copied literally if
- in double quotes or defined by sprintf. {\sl Arg4} can be {\tt
- above,} {\tt below,} {\tt left,} or {\tt right} to supplement the
- default position. {\sl Arg5} is the optional name of a {\tt []}
- block to be labelled and is {\tt last []} by default}
+\macrodef{rlabel}{rlabel}{({\sl label},{\sl label},{\sl label},[{\sl arg4}],%
+ [{\sl block name}])}
+ {cct}
+ {Triple label on the right of the body of an element with respect to the
+ current direction \seesect{Labels:}. Labels are placed at the
+ beginning, centre, and end of the last {\tt []} block (or a named
+ {\tt []} block). Each label is treated as math by default, but is
+ copied literally if it is in double quotes or defined by sprintf.
+ {\sl Arg4} can be {\tt above,} {\tt below,} {\tt left,} or {\tt
+ right} to supplement the default relative position. The fifth
+ argument is the optional name of the {\tt []} block to be labelled,
+ which is {\tt last []} by default}
\macrodef{rot3Dx}{rot3Dx}{({\sl radians,x,y,z})}
{3D} {rotates x,y,z about x axis}
\macrodef{rot3Dy}{rot3Dy}{({\sl radians,x,y,z})}
@@ -2414,6 +2421,11 @@ justification})}
centre,
R=right orientation, E=envelope
\seesect{Semiconductors:}}
+\macrodef{thyristor\_t}{thyristor_t}{({\sl linespec, chars, label})}
+ {cct}
+ {Wrapper to place a thyristor as a two-terminal element with
+ {\tt [ ]} block label given by the third argument
+ \seesect{Semiconductors:}}
\macrodef{tikznode}{tikznode}{({\sl \Tikz node name, position}) }
{pgf}
{insert \Tikz code to define a zero-size \Tikz node at {\sl location}