summaryrefslogtreecommitdiff
path: root/graphics/circuit_macros/doc/body.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/circuit_macros/doc/body.tex')
-rw-r--r--graphics/circuit_macros/doc/body.tex635
1 files changed, 381 insertions, 254 deletions
diff --git a/graphics/circuit_macros/doc/body.tex b/graphics/circuit_macros/doc/body.tex
index 0afb23e5be..0fd36ecb5c 100644
--- a/graphics/circuit_macros/doc/body.tex
+++ b/graphics/circuit_macros/doc/body.tex
@@ -48,15 +48,13 @@
%
\xection{Introduction\label{Introduction:}}
\begin{quotation}\noindent
-% Before every conference, I find Ph.D.s in on weekends running back
-% and forth from their offices to the printer.
It appears that people
who are unable to execute pretty pictures with pen and paper find it
gratifying to try with a computer~\cite{Landauer95}.
\end{quotation}
-This manual\footnote{%
-This document is best displayed with a reader that shows bookmarks.}
+This manual%
+\footnote{This document is best displayed with a reader that shows bookmarks.}
describes a method for drawing electric circuits and
other diagrams in \latex and web documents.
The diagrams are defined in the simple \pic drawing language~\cite{KRpic}
@@ -69,8 +67,8 @@ with ordinary text input. The book from which the above quotation
is taken correctly points out that the payoff can be in quality of
diagrams at the price of the time spent in learning how to draw them.
-A collection of basic components, most based on IEEE
-standards~\cite{IEEEstd},
+A collection of basic components, most based on IEC and IEEE
+standards~\cite{IECstd,IEEEstd},
and conventions for their internal
structure are described. Macros such as these are only a starting
point, since it is often convenient to customize elements or to package
@@ -204,8 +202,6 @@ produce {\sl file}{\tt.ps},
which can be printed or viewed using {\tt gsview}, for example.
For \TPGF,
Invoking PDFlatex on the source produces {\tt .pdf} output directly.
-%Whether or not the figure environment is used,
-%the essential line in all cases is \verb|\input quick|.
The essential line is \verb|\input quick| whether or not the figure
environment is used.
@@ -301,9 +297,34 @@ the commands for producing the {\tt .tex} file can be reduced
\verb%m4 quick.m4 | dpic -p > quick.tex%
+\enlargethispage{\baselineskip}
+\item
+You can put several diagrams into a single source file.
+Make each diagram the body of a \latex macro, as shown:
+
+\par
+\verb|\newcommand{\diaA}{%|\NVL
+\verb|.PS|\NVL
+{\sl drawing commands}\NVL
+\verb|.PE|\NVL
+\verb|\box\graph }% \box\graph not required for dpic|\NVL
+\verb|\newcommand{\diaB}{%|\NVL
+\verb|.PS|\NVL
+{\sl drawing commands}\NVL
+\verb|.PE|\NVL
+\verb|\box\graph }% \box\graph not required for dpic|\NVL
+Produce a {\tt .tex} file as usual,
+insert the {\tt .tex} into the \latex source, and
+invoke the macros \verb^\diaA^ and \verb^\diaB^ at the appropriate places.
+
\item
-It may be desirable to invoke \Mfour and \dpic automatically from the
-document file as shown:
+%Whether this and the next item rightly belong under the heading
+%``Simplifications'' might be debated. They appear most useful
+%when a project-management tool is employed.
+In some circumstances,
+it may be desirable to invoke \Mfour and \dpic automatically from the
+document. Define a macro \verb|\mtotex| as shown in the
+following example:
{\tt \verb^\documentclass{article}^ \brtt
\verb^\usepackage{tikz}^ \brtt
@@ -322,7 +343,7 @@ The first argument of \verb|\mtotex| is a {\tt p} for pstricks or
Sources \verb|FileA.m4| and \verb|FileB.m4| must contain any required
\verb|include| statements,
and the main document should be processed using
-the latex or pdflatex option \verb|-shell-escape|.
+the latex or pdflatex option \verb|--shell-escape|.
If the {\tt M4PATH} environment variable is not set then insert
{\tt -I }{\sl installdir} after {\tt m4} in the command definition,
where {\sl installdir} is the absolute path to the installation directory.
@@ -333,24 +354,24 @@ A derivative of this method that allows the insertion of
\pic code into a \Tikz picture is described in \SR{Tikzwithpic:}.
\item
-You can put several diagrams into a single source file.
-Make each diagram the body of a \latex macro, as shown:
+It might be convenient for the source of small diagrams to be part
+of the document source text. The {\tt filecontents} environment of current
+\LaTeX\ allows this; older versions can employ a now-obsolete package
+{\tt filecontents.sty}. The following example
+for processing by {\tt pdflatex} \verb|--shell-escape|
+first writes the \Mfour\ source
+to file {\tt sample.m4}, invokes \verb|\mtotex| on it, and reads in the result:
\par
-\verb|\newcommand{\diaA}{%|\NVL
-\verb|.PS|\NVL
-{\sl drawing commands}\NVL
-\verb|.PE|\NVL
-\verb|\box\graph }% \box\graph not required for dpic|\NVL
-\verb|\newcommand{\diaB}{%|\NVL
+\verb|\begin{filecontents}[overwrite,noheader,nosearch]{sample.m4}|\NVL
+\verb|include(pgf.m4)|\NVL
\verb|.PS|\NVL
-{\sl drawing commands}\NVL
+\verb|cct_init|\NVL
+{\sl drawing commands} $\ldots$\NVL
\verb|.PE|\NVL
-\verb|\box\graph }% \box\graph not required for dpic|\NVL
-Produce a {\tt .tex} file using \verb|\mtotex|
-or \Mfour and \dpic or \gpic,
-insert the {\tt .tex} into the \latex source, and
-invoke the macros \verb^\diaA^ and \verb^\diaB^ at the appropriate places.
+\verb|\end{filecontents}|\NVL
+\verb|\mtotex{g}{sample}|\NVL
+\verb|\input{sample.tex}|\NVL
\end{enumerate}
\subsection{Including the libraries\label{Libraries:}}
@@ -394,7 +415,7 @@ begin with the characters {\tt m4}.
\xection{\Pic essentials\label{Pic:}}
-\Pic source is a sequence of lines in a file.
+\Pic source is a sequence of lines in a text file.
The first line of a diagram begins with {\tt .PS} with optional following
arguments, and the last line is normally {\tt .PE}.
Lines outside of these pass through the \pic processor unchanged.
@@ -406,7 +427,9 @@ The visible objects can be divided conveniently into two classes, the
The object {\tt move} is linear but draws nothing. A compound object,
or {\tt block,} is planar and consists of a pair of square brackets enclosing
other objects, as described in \SR{Compoundobjects:}.
-Objects can be placed using absolute coordinates or relative to other objects.
+
+Objects can be placed using absolute coordinates or,
+as is often better, relative to other objects.
\Pic allows the definition of real-valued variables, which are alphameric
names beginning with lower-case letters, and computations using them.
@@ -829,18 +852,21 @@ were added after the previously shown source:
\end{itemize}
\subsection{The two-terminal elements\label{Twoterminal:}}
-The two-terminal elements are shown in \FRS{CctTable}
-% to~\REF{Diodes} and \FRS{Fuses}
-%to~\REF{Switches}.
-to~\REF{Arresters}.
+The two-terminal elements are shown in
+\FRS{Resistors}
+to~\REF{Switches} and part of~\FR{Arresters}.
Several elements are included more than once to illustrate
-some of their arguments, which are listed in \SR{defines}.
-\enlargethispage{\baselineskip}
+some of their arguments, which are listed in detail in \SR{defines}.
+\FR{Resistors} shows some resistors with typical variants.
\begin{figure}[h!]
- \input CctTableMan
-% \ifpdf\vspace*{-\baselineskip}\fi%
- \caption{Basic two-terminal elements, showing some variations.}
- \label{CctTable}
+ \input ResistorsMan
+ \caption{Resistors dawn by the macro
+ {\tt resistor({\sl linespec, n}|E, {\sl chars}, {\sl cycle wid})}.
+ The second argument is either an integer to specify number of cycles,
+ the letter {\tt E}, or blank. The third argument specifies the desired
+ variant.
+ The default {\tt ebox} element designates a resistor.}
+ \label{Resistors}
\end{figure}
The first macro argument specifies
@@ -849,13 +875,7 @@ If the argument is blank,
the element is drawn from the current position in the current drawing
direction along a default length.
The other arguments produce variants of the default elements.
-\begin{figure}[ht]
- \input AmpTableMan
- \caption{Amplifier, delay, and integrator.}
- \label{AmpTable}
- \end{figure}
-\pagebreak
Thus, for example,
\par
{\tt resistor(up\_ 1.25,7)}
@@ -866,60 +886,82 @@ vertices per side.
The macro {\tt up\_} evaluates to {\tt up} but also resets the current
directional parameters to point up.
-\begin{figure}[ht]
+\pagebreak
+Capacitors are illustrated in \FR{Capacitors}.
+See \SR{Composite:} for the {\tt variable} macro.
+\begin{figure}[h!t]
+ \input CapacitorsMan
+ \caption{The {\tt capacitor({\sl linespec, chars,} [R],{\sl height, width})}
+ macro, and an example application of the {\tt variable} macro.}
+ \label{Capacitors}
+ \end{figure}
+
+Basic inductors are illustrated in \FR{Inductors}.
+\begin{figure}[h!]
+ \input InductorsMan
+ \caption{Basic inductors created with the
+ {\tt inductor({\sl linespec,} W|L, {\sl cycles,} M|P|K, {\sl loop wid})}
+ macro, the {\tt ebox} macro for European-style inductors, and some
+ modifications (see also \SR{Composite:}).
+ When an embellished element is repeated several times,
+ writing a wrapper macro may be desirable.}
+ \label{Inductors}
+ \end{figure}
+
+Some more basic elements are in \FR{MoreTable}, and amplifiers in \FR{AmpTable}.
+\begin{figure}[h!t]
+ \input MoreTableMan
+ \caption{More two-terminal elements.}
+ \label{MoreTable}
+ \end{figure}
+\begin{figure}[h!t]
+ \input AmpTableMan
+ \caption{Amplifier, delay, and integrator.}
+ \label{AmpTable}
+ \end{figure}
+
+\FR{Sources} shows sources, many of which contain internal symbols,
+and of which the {\tt AC} and {\tt S} options illustrate the need
+to draw a single cycle of a sinusoid or approximate sinusoid.
+\begin{figure}[h!t]
\input SourcesMan
-% \ifpdf\vspace*{-0.5\baselineskip}\fi%
\caption{Sources and source-like elements.}
\label{Sources}
\end{figure}
-
-The {\tt AC} and {\tt S} options of the {\tt source} macro in \FR{Sources}
-illustrate the need
-to draw a single cycle of a sinusoid or approximate sinusoid.
As a convenience,
the macro {\tt ACsymbol(at {\sl position, length, height,}
[A]U|D|L|R|{\sl degrees})} is included as an interface to
the {\tt sinusoid} macro. For example to add the sumbol
-(\input{ACsymbol.tex}) to an ebox:
+``\input{ACsymbol.tex}'' to an ebox:
\par
{\tt ebox; $\lbrace$\ ACsymbol(at last [],{,},dimen\_/8) $\rbrace$}
\noindent
For direct current (\input{DCsymbol.tex}), there is also
-{\tt DCsymbol(at {\sl position, length, height,} U|D|L|R|{\sl degrees})}.
+{\tt DCsymbol(at {\sl position, length, height,} U|D|L|R|{\sl degrees})},
+and for power-system diagrams, macros
+{\tt Deltasymbol(at {\sl position, keys,} U|D|L|R|{\sl degrees})},
+and
+{\tt Ysymbol(at {\sl position, keys,} U|D|L|R|{\sl degrees})},
-\begin{figure}[ht]
+\pagebreak
+Diodes and fuses are shown in \FRS{Diodes} and \REF{Fuses}.
+\begin{figure}[h!]
\input DiodesMan
\caption{The macro
{\tt diode(\linespec,B|CR|D|L|LE[R]|P[R]|S|T|V|v|w|Z|{\sl chars},[R][E])}.
Appending {\tt K} to the second argument draws an open arrowhead.}
\label{Diodes}
\end{figure}
-
-\begin{figure}[t!]
+\begin{figure}[h!]
\input FusesMan
\caption{Variations of the macros
{\tt fuse(\linespec, A|dA|B|C|D|E|S|HB|HC|SB, {\sl wid}, {\sl ht})}
and {\tt cbreaker(\linespec,L|R,D|T|TS)}.}
\label{Fuses}
\end{figure}
-\begin{figure}[t!]
- \input SwitchesMan
- \caption{The
- {\tt switch(\linespec,L|R,{\sl chars},L|B|D)}
- macro is a wrapper for the macros
- {\tt lswitch(\linespec,[L|R],[O|C][D][K][A])},
- {\tt bswitch(\linespec,[L|R],[O|C])},
- and the many-optioned
- {\tt dswitch(\linespec,R,W[ud]B[K] {\sl chars})} shown.
- The switch is drawn in the current drawing direction.
- A second-argument {\tt R} produces a mirror
- image with respect to the drawing direction.
- The separately defined macros {\tt Proxim} and {\tt Magn}
- embellish switches in the second-last row.}
- \label{Switches}
- \end{figure}
+\enlargethispage{\baselineskip}%
Most of the two-terminal elements are oriented; that is, they have
a defined direction or polarity. Several element macros include an
argument that reverses polarity, but there is also a more general
@@ -931,10 +973,7 @@ The first argument of the macro
\par
\noindent
is the name of a two-terminal element in quotes, followed by the
-element arguments. The element is drawn with reversed direction.
-
-\pagebreak
-Thus,
+element arguments. The element is drawn with reversed direction; thus,
\par
{\tt diode(right\_ 0.4); reversed(`diode',right\_ 0.4)}
\par
@@ -955,31 +994,17 @@ by 1.8, for example
{\tt resized(1.8,`diode',right\_ 0.4);}
{\tt resized(1.8,`reversed',`diode',right\_ 0.4)}
-\pagebreak
-\FR{Arresters} shows a collection of surge-protection devices, or arresters,
-of which the {\tt E} and {\tt S} types may be either 2-terminal or as
-3-terminal (composite) elements described in \SR{Composite:}.
-\begin{figure}[ht]
- \input ArrestersMan
- \caption{Variations of the {\tt arrester({\sl linespec, chars,}
- {\sl wid}[{\tt :}{\sl arrowhead ht}], {\sl ht}[{\tt :}{\sl arrowhead wid})}
- macro. Putting {\tt D} in argument 2 for the {\tt S} or {\tt E}
- configuration creates a 3-terminal composite element
- with terminals {\sl A, B}, and {\sl G.}}
- \label{Arresters}
- \end{figure}
-
\FR{Emarrows} contains radiation-effect arrows for embellishing two-terminal
and other macros.
-The arrow stems are named {\sl A1}, {\sl A2},
-and each pair is drawn in a \verb|[]| block, with
-the names {\sl Head} and {\sl Tail} defined to
-aid placement near another device. The second argument specifies
-\begin{figure}[ht]
+\begin{figure}[h!]
\input EmarrowsMan
\caption{Radiation arrows: {\tt em\_arrows({\sl type, angle, length})}}
\label{Emarrows}
\end{figure}
+The arrow stems are named {\sl A1}, {\sl A2},
+and each pair is drawn in a \verb|[]| block, with
+the names {\sl Head} and {\sl Tail} defined to
+aid placement near another device. The second argument specifies
absolute angle in degrees (default 135 degrees).
The arrows are drawn relative to the diode direction by the {\tt LE}
option in \FR{Diodes}. For absolute arrow directions, one can
@@ -989,10 +1014,43 @@ at 45 degrees, for example:
{\tt define(`myLED',`diode(`\$1'); em\_arrows(N,45)
with .Tail at last [].ne')}
+\enlargethispage{\baselineskip}
+Switches with numerous controls are in \FR{Switches}.
+\begin{figure}[h!]
+ \input SwitchesMan
+ \caption{The
+ {\tt switch(\linespec,L|R,{\sl chars},L|B|D)}
+ macro is a wrapper for the macros
+ {\tt lswitch(\linespec,[L|R],[O|C][D][K][A])},
+ {\tt bswitch(\linespec,[L|R],[O|C])},
+ and the many-optioned
+ {\tt dswitch(\linespec,R,W[ud]B[K] {\sl chars})} shown.
+ The switch is drawn in the current drawing direction.
+ A second-argument {\tt R} produces a mirror
+ image with respect to the drawing direction.
+ The separately defined macros {\tt Proxim} and {\tt Magn}
+ embellish switches in the second-last row.}
+ \label{Switches}
+ \end{figure}
+
+\FR{Arresters} shows a collection of surge-protection devices, or arresters,
+of which the {\tt E} and {\tt S} types may be either 2-terminal or as
+3-terminal (composite) elements described in \SR{Composite:}.
+\begin{figure}[h!]
+ \input ArrestersMan
+ \caption{Variations of the {\tt arrester({\sl linespec, chars,}
+ {\sl wid}[{\tt :}{\sl arrowhead ht}],
+ {\sl ht}[{\tt :}{\sl arrowhead wid}])}
+ macro. Putting {\tt D} in argument 2 for the {\tt S} or {\tt E}
+ configuration creates a 3-terminal composite element
+ with terminals {\sl A, B}, and {\sl G.}}
+ \label{Arresters}
+ \end{figure}
+
\FR{Variable} shows some two-terminal elements with
arrows or lines overlaid to indicate variability using the macro
\par
-{\tt variable(`}{\sl element}{\tt',{\sl type},{\sl angle},{\sl length})},
+{\tt variable(`}{\sl element}{\tt',{\sl type},[+|-]{\sl angle},{\sl length})},
\noindent
where {\sl type} is one of {\tt A, P, L, N, NN} with {\tt C} or {\tt S}
@@ -1000,21 +1058,23 @@ optionally appended to indicate continuous or stepwise variation.
Alternatively, this macro
can be invoked similarly to the label macros in
\SR{Labels:} by specifying an empty first argument;
-thus, the following line draws the resistor in \FR{Variable}:
+thus, the following line draws the third resistor in \FR{Variable}:
\par
- {\tt resistor(down\_ dimen\_); variable(,uN)}
+ {\tt resistor(up\_ dimen\_); variable(,uN)}
\begin{figure}[ht]
\vspace*{-\baselineskip}
\input VariableMan
\caption{Illustrating
{\tt variable(`{\sl element}',%
-[A|P|L|[u]N]|[u]NN]][C|S],{\sl angle},{\sl length})}.
- For example,\break {\tt variable(`resistor(down\_ dimen\_)',A)} draws
- the leftmost resistor shown above, and {\tt variable(`resistor(down\_
- dimen\_)',uN)} draws the third resistor. The default angle is
- 45${}^{\circ}$, regardless of the direction of the element. The array
- on the right shows the effect of the second argument.}
+[A|P|L|[u]N]|[u]NN]][C|S],[+|-]{\sl angle},{\sl length})}.
+ For example, {\tt variable(`resistor(up\_ dimen\_)',A)} draws
+ the leftmost resistor shown above.
+ The default angle is 45${}^{\circ}$, regardless of the direction of
+ the element, but the angle preceded by a sign ($+$ or $-$) is taken
+ to be relative to the drawing direction of the element as for the
+ lower right capacitor in \FR{Capacitors}, for example. The array on
+ the right shows the effect of the second argument.}
\label{Variable}
\end{figure}
@@ -1026,8 +1086,16 @@ just been drawn. Many variations of this are possible:
\verb|arrow right arrowht from last line.start+(alpha,0) "$i_1$" above|
+\enlargethispage{\baselineskip}%
Macros have been defined to simplify labelling two-terminal
elements, as shown in \FR{currents}.
+\begin{figure}[ht]
+% \ifpdf\vspace*{-0.5\baselineskip}\fi%
+ \input currents
+ \caption{Illustrating {\tt b\_current, larrow,} and {\tt rarrow}.
+ The drawing direction is to the right.}
+ \label{currents}
+ \end{figure}
The macro
{\tt b\_current({\sl label,} above\_|below\_, In|O[ut], Start|E[nd],
@@ -1036,13 +1104,6 @@ The macro
\noindent
draws an arrow from the start of the last-drawn two-terminal element
{\sl frac} of the way toward the body.
-\begin{figure}[ht]
-% \ifpdf\vspace*{-0.5\baselineskip}\fi%
- \input currents
- \caption{Illustrating {\tt b\_current, larrow,} and {\tt rarrow}.
- The drawing direction is to the right.}
- \label{currents}
- \end{figure}
If the fourth argument is {\tt End}, the arrow is drawn from the end
toward the body.
@@ -1068,7 +1129,16 @@ quote, in which case the argument is copied literally. The third argument
specifies the separation from the element.
\subsection{Labels\label{Labels:}}
- Special macros for labeling two-terminal elements are included:
+ Arbitrary labels
+ can be positioned by any \pic\ placement method including the
+ representative basic examples shown:
+
+ {\tt "}{\sl text}{\tt" at {\sl position}}\NVL
+ {\tt "}{\sl text}{\tt" at {\sl position} above}\NVL
+ {\tt "}{\sl text}{\tt" wid {\sl width} ht {\sl height}
+ with .sw at {\sl position}}\NVL
+
+ In addition, special macros for labeling two-terminal elements are available:
\par
{\tt
llabel(} {\sl arg1,arg2,arg3} {\tt )
@@ -1085,6 +1155,14 @@ 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}.
+\begin{figure}[h!t]
+ \vspace*{-\baselineskip}
+ \parbox{4in}{\small \verbatiminput{Loop.m4}}%
+ \hfill\raise-0.5in\hbox{\input Loop }
+ \vspace*{-\baselineskip}
+ \caption{A loop containing labeled elements, with its source code.}
+ \label{Loop}
+ \end{figure}
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)}
@@ -1097,25 +1175,11 @@ Labels beginning
with {\tt sprintf} or a double quote are copied literally rather than
assumed to be in math mode.
- Arbitrary \latex including {\bsl\tt includegraphics,} for example,
- can also be placed on a diagram using
-
- {\tt "}{\sl \latex text}{\tt" wid {\sl width} ht {\sl height}
- at {\sl position}}
-
-\begin{figure}[ht]
- \vspace*{-\baselineskip}
- \parbox{4in}{\small \verbatiminput{Loop.m4}}%
- \hfill\raise-0.5in\hbox{\input Loop }
- \vspace*{-\baselineskip}
- \caption{A loop containing labeled elements, with its source code.}
- \label{Loop}
- \end{figure}
-
\xection{Placing two-terminal elements\label{Placing:}}
The length and position of a two-terminal element
-are defined by a straight-line segment and, possibly, a direction, so
-four numbers are required to place the element as in the following example:
+are defined by a straight-line segment, so
+four numbers or equivalent
+are required to place the element as in the following example:
\par
{\tt resistor(from (1,1) to (2,1))}.
@@ -1143,8 +1207,8 @@ To draw a resistor up $d$ units from the current position, for example:
{\tt resistor(up\_ d)}
\Pic stores the current drawing direction,
-the latter unfortunately limited to {\tt up, down, left, right,}
-which is assumed when necessary.
+which is unfortunately limited to {\tt up, down, left, right,}
+for reference when necessary.
The circuit macros need to know the current direction, so
whenever {\tt up, down, left, right} are used they should be written
respectively as the macros {\tt up\_, down\_, left\_, right\_} as in
@@ -1152,8 +1216,9 @@ the above example.
To allow drawing circuit objects in other than the standard four directions,
a transformation matrix
-is applied at the macro level to generate the required \pic code.
-Potentially, the matrix can be used for other transformations.
+is applied at the macro level to generate the required
+(but sometimes very elaborate) \pic code.
+Potentially, the matrix elements can be used for other transformations.
The macro
{\tt setdir\_({\sl direction, default direction})}
@@ -1178,7 +1243,7 @@ The macro {\tt eleminit\_} in the two-terminal elements invokes
to establish element length and direction.
As shown in \FR{Oblique},
-\begin{figure}[ht]
+\begin{figure}[h!t]
\vspace{-\baselineskip}
\parbox{4.5in}{\small \verbatiminput{Oblique.m4}}%
\hfill\raise-0.7in\llap{\hbox{\input Oblique }}%
@@ -1208,6 +1273,7 @@ as in {\tt `{`,'}',} as necessary.
Commas also may be avoided by writing
{\tt 0.5 between L and T} instead of {\tt 0.5<L,T>.}
+\pagebreak
\subsection{Series and parallel circuits\label{Seriesandparallel:}}
To draw elements in series, each element can be placed by specifying
@@ -1321,6 +1387,7 @@ to determine length and direction (but not position) of the block.
Nearly all elements drawn within blocks can be customized by adding an
extra argument, which is executed as the last item within the block.
+\pagebreak
The macro {\tt
potentiometer(\linespec,{\sl cycles},{\sl fractional pos},{\sl length},
@@ -1363,7 +1430,7 @@ drawn elements.
A few composite symbols derived from two-terminal elements
are shown in \FR{Composite}.
-\begin{figure}[h!b]
+\begin{figure}[ht]
\vspace*{-0.5ex}
% \vspace*{-\baselineskip}
\input Composite
@@ -1373,7 +1440,7 @@ are shown in \FR{Composite}.
\label{Composite}
\end{figure}
-\enlargethispage{\baselineskip}
+%\enlargethispage{\baselineskip}
The ground symbol is shown in \FR{Grounds}.
The first argument specifies position; for example, the two lines shown
have identical effect:
@@ -1442,14 +1509,14 @@ The {\tt opamp} labels can be rotated if necessary by
using postprocessor commands (for example \PSTricks \verb|\rput|)
as second and third arguments.
-The code in \FR{oax} places an opamp with three connections.
+The code in \FR{opampex} places an opamp with three connections.
\begin{figure}[h!b]
- \parbox{4in}{\small \verbatiminput{oaxbody.m4}}%
- \quad\raise-0.2in\hbox{\input oax }%
+ \parbox{4in}{\small \verbatiminput{opampexbody.m4}}%
+ \quad\raise-0.2in\hbox{\input opampex }%
% \vspace{-\baselineskip}
\caption{A code fragment invoking the
{\tt opamp(\linespec,-,+,{\sl size},[R][P])} macro.}
- \label{oax}
+ \label{opampex}
\end{figure}
\FR{Xform} shows variants of the transformer macro,
@@ -1587,8 +1654,8 @@ For drawing relays, the macro
{\tt relaycoil({\sl chars, wid, ht,} {\tt U|D|L|R|}{\sl degrees})}
shown in \FR{relaycoil} provides a choice of connection points and
actuator types.
-
\pagebreak
+
\begin{figure}[ht]
% \ifpdf\vspace*{-\baselineskip}\else\vspace*{-0.5\baselineskip}\fi%
\input relaycoilMan
@@ -1611,7 +1678,7 @@ terminals {\sl P$_i$, C$_i$, O$_i$.}
The {\tt jack} and {\tt plug} macros and their defined points are
illustrated in \FR{Jack}.
The first argument of both macros establishes the drawing direction.
-\begin{figure}[h!]
+\begin{figure}[!ht]
\input JackMan
\vspace{-1ex}
\caption{The {\tt jack(U|D|L|R|{\sl degrees}, {\sl chars})}
@@ -1635,27 +1702,22 @@ A macro for drawing headers is in \FR{Headers},
and some experimental connectors are shown in \FR{Conn} and \FR{Pconn}.
The {\tt tstrip} macro allows ``{\sl key}{\tt =}{\sl value}{\tt ;}'' arguments
for width and height.
-\begin{figure}[ht]
-% \ifpdf\vspace*{-0.5\baselineskip}\fi%
+\begin{figure}[h!b]
\input HeadersMan
-% \ifpdf{\vspace*{-0.5ex}}\fi%
\caption{Macro {\tt Header(1|2, {\sl rows, wid, ht, type})}.}
\label{Headers}
\end{figure}
-\begin{figure}[ht]
+\begin{figure}[h!b]
\input ConnMan
-% \ifpdf{\vspace*{-0.5ex}}\fi%
\caption{Macros {\tt tstrip(R|L|U|D|{\sl degrees}, {\sl chars})},
{\tt ccoax(at} {\sl location}, {\tt M|F, {\sl diameter})},
{\tt tconn(\linespec, >|>>|<|<<|O[F], {\sl wid})}, and
{\tt tbox({\sl text, wid, ht}, <|>|<>,{\sl type})}. }
\label{Conn}
-% \ifpdf{\vspace*{-1ex}}\fi%
\end{figure}
+
\begin{figure}[ht]
-% \ifpdf{\vspace*{-1ex}}\fi%
\input PconnMan
-% \ifpdf{\vspace*{-0.5ex}}\fi%
\caption{A small set of power connectors drawn by
{\tt pconnex(R|L|U|D|}{\sl degrees, chars}{\tt)}. Each connector has
an internal {\tt H}, {\tt N}, and where applicable, a {\tt G} shape.}
@@ -1665,7 +1727,7 @@ for width and height.
The double-throw switches shown in \FR{NPDT} are drawn in the
current drawing direction like the two-terminal elements, but are
composite elements that must be placed accordingly.
-\begin{figure}[h!b]
+\begin{figure}[h!t]
\ifpdf{\vspace*{-1ex}}\fi%
\input NPDTMan
\caption{Multipole double-throw switches drawn by
@@ -1678,7 +1740,7 @@ is shown in \FR{Windings}.
For simplicity, the complete spline
is first drawn and then blanked in appropriate places using the background
(core) color (\verb!lightgray! for example, default \verb!white!).
-\begin{figure}[h!b]
+\begin{figure}[h!t]
\vspace*{-\baselineskip}%
% \ifpdf\vspace*{-2\baselineskip}\else \vspace{-\baselineskip}\fi
\input WindingsMan
@@ -1690,6 +1752,7 @@ is first drawn and then blanked in appropriate places using the background
\label{Windings}
\end{figure}
+\pagebreak
\subsection{Semiconductors\label{Semiconductors:}}%
\FR{Bip} shows the variants of bipolar transistor macro
{\tt bi\_tr(\linespec,L|R,P,E)}
@@ -1697,9 +1760,7 @@ which contains predefined internal locations {\sl E},
{\sl B}, {\sl C}.
The first argument defines the distance and direction from {\sl E}
\begin{figure}[ht]
-% \ifpdf\vspace*{-0.5\baselineskip}\fi%
\input BipMan
-% \ifpdf\vspace*{-0.5\baselineskip}\fi%
\caption{Variants of bipolar transistor {\tt bi\_tr(\linespec,L|R,P,E)}
(current direction upward).}
\label{Bip}
@@ -1711,7 +1772,7 @@ current drawing direction according to the second argument. Setting the third
argument to {\tt P} creates a PNP device instead of NPN, and setting the
fourth to {\tt E} draws an envelope around the device.
\FR{Darlington} shows a composite macro with several optional internal elements.
-\begin{figure}[ht]
+\begin{figure}[h!t]
\input Darlington
\caption{Macro {\tt Darlington(L|R,[E][P][B1][E1|R1][E2|R2][D][Z])},
drawing direction {\tt up\_}.}
@@ -1720,8 +1781,7 @@ fourth to {\tt E} draws an envelope around the device.
The code fragment example in \FR{bitr} places a bipolar transistor,
connects a ground to the emitter, and connects a resistor to the collector.
-\begin{figure}[ht]
-%\vspace*{-\baselineskip}
+\begin{figure}[h!t]
\quad\quad\parbox{4in}{\small \verbatiminput{bitrbody.m4}}%
\quad\raise-0.4in\hbox{\input bitr }%
\vspace{-\baselineskip}
@@ -1734,8 +1794,7 @@ the macro {\tt bi\_trans(\linespec, L|R, {\sl chars}, E)}, which
draws the components of the transistor according to the characters in its
third argument. For example, multiple emitters and collectors can be
specified as shown in \FR{bitrans}.
-\begin{figure}[ht]
-%\vspace*{-0.5\baselineskip}
+\begin{figure}[h!t]
\input bi_trans
\caption{The {\tt bi\_trans(\linespec,L|R,{\sl chars},E)} macro.
The sub-elements are specified by the third argument. The substring
@@ -1744,21 +1803,21 @@ specified as shown in \FR{bitrans}.
\label{bitrans}
\end{figure}
-\pagebreak
A UJT macro with predefined internal locations {\sl B1,} {\sl B2,}
-and {\sl E} is shown in \FR{ujt},
-and a thyristor macro with predefined internal locations
- {\sl G} and {\sl T1,} {\sl T2,} or
- {\sl A,} {\sl K} is in \FR{thyristor}.
-Except for the {\sl G} terminal, a thyristor (the {\tt IEC} variant excluded)
-\begin{figure}[ht]
+and {\sl E} is shown in \FR{ujt}.
+\begin{figure}[h!t]
% \ifpdf\vspace*{-\baselineskip}\else\vspace*{-0.5\baselineskip}\fi%
\input ujtMan
% \ifpdf\vspace*{-0.5\baselineskip}\fi%
\caption{UJT devices, with current drawing direction {\tt up\_}. }
\label{ujt}
\end{figure}
-\begin{figure}[h!t]
+
+A thyristor macro with predefined internal locations
+ {\sl G} and {\sl T1,} {\sl T2,} or
+ {\sl A,} {\sl K} is in \FR{thyristor}.
+Except for the {\sl G} terminal, a thyristor (the {\tt IEC} variant excluded)
+\begin{figure}[h!b]
% \ifpdf\vspace*{-\baselineskip}\else\vspace*{-0.5\baselineskip}\fi%
\input thyristorMan
\vspace*{-1ex}
@@ -1770,7 +1829,7 @@ Except for the {\sl G} terminal, a thyristor (the {\tt IEC} variant excluded)
to the second argument to draw open arrowheads.}
\label{thyristor}
\end{figure}
-is much like an two-terminal element. The wrapper macro
+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} place thyristors
using {\sl linespec} as for a two-terminal element,
@@ -1782,18 +1841,17 @@ but require a third argument for the label for the compound block; thus,
draws the element from position {\sl A} to position {\sl B} with label
{\sl Q3}, and draws a line from {\sl G}.
+\enlargethispage{\baselineskip}
Some FETs with predefined internal locations {\sl S,} {\sl D,} and {\sl G} are
also included, with similar arguments to those of {\tt bi\_tr,} as shown in
\FR{fet}.
\begin{figure}[ht]
-% \ifpdf\vspace*{-\baselineskip}\fi%
\input fetMan
-% \ifpdf\vspace*{-\baselineskip}\fi%
\caption{JFET, insulated-gate enhancement and depletion MOSFETs,
- and simplified versions.
+ simplified versions, graphene, and ferroelectric fets.
These macros are wrappers that invoke the {\tt mosfet}
macro as shown in the middle and bottom rows.
- The two lower-right examples show custom devices, the first
+ The bottom-row examples show custom devices, the first
defined by omitting the substrate connection, and the second
defined using a wrapper macro.}
\label{fet}
@@ -1823,7 +1881,7 @@ the {\tt thyristor(\linespec, {\sl chars})} macro illustrated in
\FR{thyristor} is derived from the diode and bipolar transistor macros.
Another example is the {\tt tgate} macro shown in \FR{Tgate}, which
also shows a pass transistor.
-\begin{figure}[ht]
+\begin{figure}[h!t]
% \ifpdf\vspace*{-\baselineskip}\fi%
\input TgateMan
\caption{The {\tt tgate({\sl linespec,} [B][R|L])} element, derived from
@@ -1835,13 +1893,12 @@ also shows a pass transistor.
\label{Tgate}
\end{figure}
-\pagebreak
Some other non-two-terminal macros are {\tt dot}, which has an
optional argument ``{\tt at} {\sl location}'', the line-thickness
macros, the {\tt fill\_} macro, and {\tt crossover}, which is a useful if
archaic method to show non-touching conductor crossovers, as in
\FR{bistable}.
-\begin{figure}[ht]
+\begin{figure}[h!t]
\input bistableMan
% \vspace{-1ex}
\caption{Bipolar transistor circuit, illustrating {\tt crossover}
@@ -1873,6 +1930,8 @@ A macro is also provided for colored fills:
\noindent%
These macros depend heavily on the postprocessor and are intended only for
\PSTricks, \TPGF, \MetaPost, \SVG, and the Postscript or PDF output of \dpic.
+Basic \Pic\ objects are probably best colored and filled as discussed
+in \SR{Planarobjects:}.
\xection{Corners\label{Corners:}}%
If two straight lines meet at an angle then, depending on the postprocessor,
@@ -1898,6 +1957,7 @@ by half the line thickness (macro {\tt hlth}) as shown on the upper row
of the figure,
or a two-segment line can be overlaid at the corner to produce the same effect.
+\pagebreak
\xection{Looping\label{Looping:}}
Sequential actions can be performed using either the
\dpic command
@@ -1941,6 +2001,7 @@ which have one input {\tt In1} unless they are given a
first argument, which is treated as the line specification of a
two-terminal element.
\begin{figure}[h!]
+ \vspace*{-0.5\baselineskip}
\input LogicMan
\caption{Basic logic gates. The input and output locations of
a three-input NOR gate are shown. Inputs are negated by
@@ -1961,13 +2022,15 @@ regardless of gate orientation, as in \FR{FF}.
\caption{$SR$ flip-flop.}
\label{FF}
\end{figure}
-\begin{figure}[ht]
+Beyond a default number (6) of inputs, the
+gates are given wings as in \FR{exVIII}.
+\begin{figure}[h!t]
\input mplex
+ \vspace*{-0.5\baselineskip}
\caption{Eight-input multiplexer, showing a gate with wings.}
\label{exVIII}
\end{figure}
-Beyond a default number (6) of inputs, the
-gates are given wings as in \FR{exVIII}.
+
Negated inputs or outputs are marked by circles drawn using the
\verb|NOT_circle| macro. The name marks the point at the outer edge of the
circle and the circle itself has the same name prefixed by~{\tt N\_}.
@@ -2035,7 +2098,8 @@ If the first argument is non-blank however, then the buffer is drawn along
an invisible line like a two-terminal element, which is convenient sometimes
but requires internal locations of the block to be referenced using
{\tt last []}, as shown in \FR{Buffer}.
-\begin{figure}[ht]
+\begin{figure}[h!t]
+ \vspace*{-\baselineskip}
\input Buffer
\caption{The {\tt BUFFER\_gate} and {\tt BUFFER\_gen} macros.
The bottom two examples show how the gate can be drawn as a two-terminal
@@ -2071,7 +2135,6 @@ a label, use {\tt lg\_bartxt(}{\sl label}{\tt)}.
The {\sl pinopts} are {\tt [L|M|I|O][N][E]} as for the \verb|lg_pin| macro.
Optional argument 7 is the pin length in drawing units.
-\pagebreak
\FR{Multiplexer} shows a multiplexer block with variations, and
\FR{Demultiplexer} shows
the very similar demultiplexer.
@@ -2087,6 +2150,7 @@ the very similar demultiplexer.
[L][B|H|X][N[$n$]|S[$n$]][[N]OE],{\sl wid},{\sl ht})} macro.}
\label{Demultiplexer}
\end{figure}
+\pagebreak
Customized gates can be defined simply.
For example, the following code defines the custom flipflops in \FR{ShiftR}.
@@ -2104,7 +2168,6 @@ This definition makes use of macros \verb|L_unit| and
There are three pins on the right; the centre pin is null and
the bottom is null if the first macro argument is 1.
-\pagebreak
For hybrid applications, the \verb|dac| and \verb|adc| macros are
illustrated in \FR{Dac}.
The figure shows the default and predefined internal locations, the number
@@ -2175,7 +2238,8 @@ to change the size of a complete diagram while keeping the relative
proportions of objects within it. You may wish to change the sizes or
proportions of individual elements within a diagram. You must take
into account that line widths are scaled separately from drawn objects,
-and that the size of typeset text is independent of the \pic language.
+and that the size of typeset text is independent of the \pic language
+except when svg is being produced.
The scaling of circuit elements will be described first, then
the \pic scaling facilities.
@@ -2287,7 +2351,7 @@ If you develop a library of custom macros in the installation
directory then the statement {\tt include(}{\sl mylibrary}{\tt.m4)}
can bring its definitions into play.
-\enlargethispage{\baselineskip}
+%\enlargethispage{\baselineskip}
It may not be necessary to define your own macro if all that is needed is
a small addition to an existing element that is defined in an enclosing
\verb|[ ]| block. After the element arguments are expanded,
@@ -2326,7 +2390,7 @@ two macros are defined to simplify the repeated drawing
of a series resistor and series inductor, and the macro {\tt tsection} defines
a subcircuit that is replicated several times to generate \FR{Tline}.
{\small \verbatiminput{Tline.m4}}
-\begin{figure}[h!]
+\begin{figure}[h!t]
% \ifpdf\vspace*{-\baselineskip}\fi%
\input Tline
\caption{A lumped model of a transmission line, illustrating the
@@ -2336,10 +2400,17 @@ a subcircuit that is replicated several times to generate \FR{Tline}.
\Example{3}
%\par\noindent {\bf Example 3:}
-Composite elements containing several basic elements may be
-required. \FR{HybridPi} shows a circuit that can be drawn in
-any reference direction prespecified by {\tt Point\_({\sl degrees})},
-containing labels that always appear in their natural horizontal orientation.
+\FR{HybridPi} shows an element that is composed of several basic
+elements and that can be drawn in any direction prespecified by
+{\tt Point\_({\sl degrees})}. The labels always appear in their natural
+horizontal orientation.
+\begin{figure}[h!t]
+ \vspace*{-0.5ex}
+ \input HybridPi
+ \vspace*{-0.5ex}
+ \caption{A composite element containing several basic elements}
+ \label{HybridPi}
+ \end{figure}
Two flags in the argument determine the circuit orientation with respect to
the current drawing direction and whether a mirrored circuit is drawn.
The key to writing such a macro is to observe that the \pic language
@@ -2379,15 +2450,7 @@ define(`hybrid_PI_BJT',
`"$\mathrm{r_o}$"' at Ro.c+vec_(hunit/4,0)
`$2' ] ')
\end{verbatim}
-\begin{figure}[ht]
- \vspace*{-0.5ex}
- \input HybridPi
- \vspace*{-0.5ex}
- \caption{A composite element containing several basic elements}
- \label{HybridPi}
- \end{figure}
-%\enlargethispage{\baselineskip}
\Example{4}
A number of elements have arguments meant explicitly for customization.
\FR{Sinus} customizes the {\tt source} macro to show a cycle of a horizontal sinusoid with adjustable phase given by argument 2 in degrees,
@@ -2534,6 +2597,73 @@ placed by specifying the position of one of its defined points; by
default it will be placed as if it were a box.
\fi
+\subsection{Macro arguments\label{Marcroarguments:}}
+Macro parameters are defined
+by entering them into specific arguments, and if an argument is blank then
+a default parameter is used.
+For the resistor macro, for example:
+
+{\tt resistor( {\sl linespec, cycles, chars, cycle wid} );}
+
+\noindent
+an integer (3, say) in the second argument specifies the number of cycles.
+Arguments could be entered in a key--value style (for example,
+{\tt resistor(up\_ elen\_,style=N;cycles=8}) instead of by positional
+parameters, but it was decided early on
+to keep macro usage as close as possible to \pic\ conventions.
+
+More recently, a mixed style has been adopted by which some
+parameters are entered using keys. Two macros assist this process,
+of which the first is
+
+{\tt setkey\_({\sl string, key, default value, }[N])}
+
+The first argument
+is taken to be a sequence of semicolon (;)-separated terms of the form
+{\tt key={\sl value};}.
+Then for example in a macro, the line
+
+{\tt setkey\_( `\$2', wdth, dimen\_*2 )}
+
+\noindent
+checks argument 2 for a term {\tt wdth=}{\sl value} and defines
+the macro {\tt m4wdth} to evaluate to
+{\tt (dimen\_*2)} if not found,
+otherwise to {\tt ({\sl value}).}
+The enclosing parentheses are omitted if the
+third argument of {\tt setkey\_} is {\tt N,} as may be required if {\tt m4wdth}
+is non-numeric.
+
+In addition, the macro
+
+{\tt setkeys\_({\sl string, keysequence})}
+
+\noindent
+applies {\tt setkey\_()} multiple times to its {\sl keysequence}
+(second) argument.
+Each term of the second argument consists of the three
+arguments of {\tt setkey\_} separated by the colons (:) rather than commas.
+
+For example, consider the elementary example of a custom box macro:
+
+\begin{verbatim}
+define(`custombox',
+`setkeys_(`$1',wdth:boxwid:; hgt:boxht:; label::N; text::N)
+ ifelse(m4label,,,m4label:) box wid m4wdth ht m4hgt "m4text" ')
+\end{verbatim}
+
+Then {\tt custombox(wdth=2; label=B1; text=Hello)}
+first causes the macros {\tt m4wdth, m4hgt, m4label,} and {\tt m4text}
+to be created, with values {\tt (2), (boxht), B1,} and {\tt Hello}
+respectively, and {\tt custombox} evaluates to
+
+{\tt B1:\ box wid (2) ht (boxht) "Hello"}.
+
+The key prefix {\tt m4} of the automatically created parameter macros can be
+redefined if necessary, since it is given in the distribution by the line
+{\tt define(`key\_prefix',`m4')}.
+
+
\xection{Interaction with \latex\label{Interaction:}}
The sizes of typeset labels and other \tex boxes are generally unknown
prior to processing the diagram by \latex.
@@ -2553,12 +2683,13 @@ B: box
The \pic interpreter cannot know the size of the text to the left
and right of the box, and the diagram is generated using
-default text values. One solution to this problem is to measure the
+default text size values. One solution to this problem is to measure the
text sizes by hand and include them literally, thus:\hfill\break
\hbox{}\quad%
\verb|"Left text" wid 38.47pt__ ht 7pt__ at B.w rjust|\hfill\break
but this is tedious.
+%\enlargethispage{\baselineskip}
Often, a better solution is to process the diagram twice. The
diagram source is processed as usual by \Mfour and a \pic processor, and the
main document source is \latex{}ed to input the diagram and format the
@@ -2579,7 +2710,7 @@ This hackery is summarized below, with an example in \FR{stringdim}.
The argument of {\tt s\_box} need not be text exclusively; it can
be anything that produces a \TeX\ box, for example, \verb|\includegraphics|.
\end{itemize}
-\begin{figure}[ht]
+\begin{figure}[h!t]
\parbox{3.5in}{\small\tt.PS\\
gen\_init\\
sinclude(Circuit\_macros.dim)\\
@@ -2589,10 +2720,10 @@ This hackery is summarized below, with an example in \FR{stringdim}.
\hbox{}\quad s\_box(Right text: \$x\^{}{\%g}\$,2) at B.e ljust\\
.PE}%
\hfill\llap{\raise-0.25in\hbox{\input stringdims }}%
- \caption{The macro {\tt s\_box} sets string dimensions automatically
+ \caption{Macro {\tt s\_box} sets string dimensions automatically
when processed twice. If two or more arguments are
given to {\tt s\_box}, they
- are passed through {\tt sprintf}. The dots show the figure bounding box.}
+ are passed through {\tt sprintf}. The bounding box is shown.}
\label{stringdim}
\end{figure}
@@ -2669,7 +2800,6 @@ for the second time:
Here is a second small example. Suppose that the file {\tt tsbox.m4} contains
the following:
-\pagebreak
\begin{verbatim}
\documentclass{article}
\usepackage{boxdims,ifpstricks(pstricks,tikz)}
@@ -2690,7 +2820,7 @@ The file is processed twice as follows:
The first command line produces a file {\tt tsbox.pdf} with
incorrect bounding box. The second command reads the data in {\tt tsbox.dim}
to size the label correctly. The equivalent pstricks commands (note
-the {\tt ifpstricks} macro in the second source line) are
+the {\tt ifpstricks} macro in the second line of the diagram source) are
{\tt m4 pstricks.m4 tsbox.m4 | dpic -p > tsbox.tex; latex tsbox}
\par
@@ -2889,7 +3019,7 @@ formats, as shown in \FR{Workflow}.
One of the easiest methods
for producing web documents is to generate postscript as usual and to
convert the result to pdf format with Adobe Distiller or equivalent.
-\begin{figure}[h!b]
+\begin{figure}[h!t]
% \ifpdf\vspace*{-\baselineskip}\fi%
\input Workflow
% \ifpdf\vspace*{-\baselineskip}\fi%
@@ -2944,61 +3074,63 @@ that includes the diagram using
\verb|\includegraphics{|{\sl filename}\verb|.mps}|
as usual.
-The \dpic processor is capable of other output formats, as illustrated in
-\FR{Workflow} and in example files included with the distribution.
-The \latex drawing commands alone or with {\tt eepic} or {\tt pict2e}
-extensions are suitable only for simple diagrams.
+The \dpic processor can generate other output formats,
+as illustrated in \FR{Workflow} and in example files included with the
+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 automate the tedious
-coordinate calculations required by \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.
+write a \pic-like interpreter (\dpic) to automate the tedious coordinate
+calculations required by \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. \Dpic can write the coordinates of selected
-locations to an external file to be used in overlaying text or other
-items on the diagram.
-
-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 are available for Unix, Windows, and other
-operating systems.
+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 main value of this distribution is not intended to be in the use
+of a specific language but in the element data encoded in the macros,
+which have been developed with reference to standards and refined over
+more than two decades, and which now total thousands of lines. Some of
+the macros have become less readable as more options and flexibility
+have been added, and if starting over today, perhaps I would change
+some details. Compromises have been made in order to retain reasonable
+compatibility with the variety of postprocessors. No choice of tool
+is without compromise, and producing good graphics seems to be time
+consuming, no matter how it is done, especially for circuits or other
+diagrams that contain random detail.
+
+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.
+% One way of viewing macro
+% preprocessing is to suggest that \Mfour is to the \pic language as the C
+% preprocessor is to the C language.
+Free versions of \Mfour are available
+for Unix and its descendents, Windows, and other operating systems.
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
+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,
+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 main value of this distribution is not in the use of a specific
-language but in the element data encoded in the macros, which have been
-developed with reference to standards and refined over two decades.
-Some of them have become less readable as more options and flexibility
-have been added, and if starting over today, perhaps I would change
-some details. Compromises have been made in order to retain reasonable
-compatibility with the variety of postprocessors. No choice of tool
-is without compromise, and producing good graphics seems to be time
-consuming, no matter how it is done, especially for circuits
-or other diagrams that contain random detail.
-
The \dpic interpreter has several output-format options that may be
useful. The {\tt eepicemu} and {\tt pict2e} extensions of the
primitive \latex picture objects are supported. The \mfpic output
@@ -3021,7 +3153,6 @@ With raw \Postscript, \PDF, and \SVG output, the user is
responsible for ensuring that the correct fonts are provided and for
formatting the text.
-\pagebreak
Many thanks to the people who continue to send comments, questions,
and, occasionally, bug fixes. What began as a tool for my own use changed
into a hobby that has persisted, thanks to your help and advice.
@@ -3030,10 +3161,6 @@ into a hobby that has persisted, thanks to your help and advice.
This section provides hints and a list of common errors.
The distributed macros are not written for maximum robustness.
-Arguments could be entered in a key--value style (for example, {\tt
-resistor(up\_ elen\_,style=N;cycles=8}) instead of by positional
-parameters, but it was decided early on
-to keep macro usage as close as possible to \pic\ conventions.
Macro arguments could be tested for correctness and
explanatory error messages could be written as necessary, but that
would make the macros more difficult to read and to write. You will
@@ -3041,7 +3168,7 @@ have to read them when unexpected results are obtained or when you wish
to modify them.
Maintaining reasonable compatibility with both \gpic\ and \dpic
-and, especially, for different postprocessors, has
+and, especially, with different postprocessors, has
resulted in some macros becoming more complicated than is preferable.
Here are some hints, gleaned from experience and from comments I have
@@ -3087,7 +3214,7 @@ received.
\item
\bflistitem{Initialization}{initialization}
If the first element macro evaluated is not two-terminal or is within a
-\Pic block, then later macros evaluated outside the block may produce
+\Pic\ block, then later macros evaluated outside the block may produce
the error message
{\tt there is no variable `rp\_ang'}
@@ -3157,8 +3284,8 @@ If information is omitted, default values are used. Writing
{\tt source(up\_)}
-\noindent draws a source up a distance equal to the current
-{\tt lineht} value, which may cause confusion.
+\noindent draws a source from the current position up a distance equal
+to the current {\tt lineht} value, which may cause confusion.
Writing
{\tt source(0.5)}