\section{Introduction}
This document describes a set of macros, written in the {\bf m4} macro
language\cite{KRm4}, for producing electric circuits and other diagrams
in \LaTeX\ documents.  The macros evaluate to drawing commands in {\bf
pic}, a drawing language\cite{KRpic} which is very simple to learn.
%of moderate power and extreme simplicity.  
The result is a system with the advantages and
disadvantages of \TeX\ itself, which is macro-based, non-wysiwyg, and
which uses ordinary character input.

A collection of basic components and conventions for their internal
structure are described.  For particular drawings it is often
convenient to create new macros, or combinations of them, using
consistent conventions, so macros such as these are only a starting
point.  The IEEE standard\cite{IEEEstd} has been followed.  The macros
described here make extensive use of the features of {\bf pic} and have
been designed, where possible, to be an extension of the language.

\section{Macro usage}
The diagram source file is preprocessed as illustrated in
Fig.\ \ref{Flowdiag+}.  The source, together with the pre-defined
macros, is first passed through {\bf m4}, and then through a {\bf
pic\/} interpreter which produces a {\tt .tex\/} file to be inserted
into the {\tt .tex\/} source using the \verb|\include| command.

\begin{figure}[htb]
   \input Flowdiag+
   \caption{Inclusion of figures and macros in the \LaTeX\ document}
   \label{Flowdiag+}
   \end{figure}

The file, {\tt cct.m4,} say, is processed as shown:
\begin{verbatim}
  m4 $HOME/lib/libcct.m4 cct.m4 > cct.pic
   \end{verbatim}\vspace{-2ex}
after which the {\tt .pic\/} file must be converted to a {\tt .tex\/} file
containing, for example, {\bf tpic\/} specials, \LaTeX\ graphics,
(or other graphics commands, such as for {\bf mfpic\/}\cite{mfpic}
or {\bf PSTricks}\cite{pstricks})
which \LaTeX\ will convert or include in a {\tt .dvi\/} file. The {\tt .dvi\/}
file is then to be viewed or printed by a driver capable of
interpreting any \verb|\special| commands inserted by the
{\bf pic\/} processor.  In the above example, {\tt \$HOME/lib\/} is the
directory in which files {\tt gpic.m4\/} and {\tt libcct.m4\/} have
been installed.

\section{The Pic processor}

The {\bf pic\/} language defines the following elementary graphics
objects:  {\tt line, box, arc, arrow, ellipse, circle, spline,} text
string, and blocks containing simpler objects.  In addition, local and
global variables, elementary mathematical functions, structured
objects, looping and branching, and elementary macro and file
facilities are available.  The graphics objects are drawn by absolute
location, or relative to previously-defined objects or locations.  At
all times a current location and drawing direction are defined.

To convert {\bf pic\/} to TeX input one can use\cite{gpic} {\bf gpic
-t\/} with a printer driver that understands {\bf tpic\/} specials,
typically\cite{dvips} {\bf dvips}.
Thus, for the previous example the command
\begin{verbatim}
   gpic -t cct.pic > cct.tex
   \end{verbatim}\vspace{-2ex}
creates a file for inclusion in the \LaTeX\ document.
{\bf Pic\/} processors contain basic macro facilities,
so some of the concepts applied here require only a {\bf pic\/} processor.

With judicious use of macros the features of both {\bf m4\/} and {\bf pic\/}
can be exploited.
(The fastidious might observe that there are 3 languages being
scrambled: {\bf m4\/}, {\bf pic}, and the {\bf tpic,} {\bf tex} or
other output, not to mention the meta-language of the macros, and that
this mixture might be a problem, but experience implies otherwise.)

A {\bf pic\/} manual\cite{KRpic}
can be obtained by emailing to {\tt netlib@research.att.com\/} with
the message body {\tt send 116 from research/cstr,} or by ftp as
\begin{verbatim}
ftp://netlib.att.com/netlib/att/cs/cstr/116.ps.Z.
\end{verbatim}

Further explanation is available, for example, from the {\bf gpic\/}
`man' page, part of the GNU {\bf groff\/} package.  For a discussion of
the use of ``little languages'' in document production, and of pic
in particular, see Chapter 9 of \cite{Bentley88}.

\section{Basic two-terminal elements}
All fundamental two-terminal element macros have been constructed
according to the conventions described below.

First, all drawing macros have default arguments, so that only arguments
different from default need be specified.  The arguments are given
in Sec.\ \ref{defines}.

Consider the resistor shown in Fig.\ \ref{BigResistor+},
which also serves as a useful example of {\bf pic\/} commands.

\begin{figure}[htb]
   \input BigResistor+
   \caption{Resistor (with label $R1$), showing the enclosing block}
   \label{BigResistor+}
   \end{figure}

The first line of a source file begins with {\tt .PS} with optional
further arguments, and the last line is normally {\tt .PE}.
The first part of the source for Fig.\ \ref{BigResistor+} is shown below:
{\small \input BigResistor+1.verb }

These lines and the remaining source lines are explained below:
\begin{enumerate}
\item The first line invokes an almost-empty macro which initializes
   local variables used by some circuit-element macros.  This macro can
   be customized to set line thicknesses, maximum page sizes, scale
   parameters, or other global quantities as desired.
\item By default, the size of two-terminal elements is a multiple of the
   {\bf pic\/} variable {\tt linewid,} which has initial value
   $0.5\,$in., so the value $2.0$ is assigned to this variable to make
   a suitably big diagram for this manual.  The body size of an element
   is determined by the macro {\tt dimen\_}, which evaluates by default
   to {\tt linewid,} and the default element length length is {\tt
   elen\_,} which is {\tt dimen\_*3/2\/} by default.  These dimensions
   can all be customized if necessary.  (For resistors, the length of the
   body is {\tt dimen\_/2,} and the width is {\tt dimen\_/6.})
\item The macro {\tt linethick\_} sets the thickness of subsequent
   lines (to 2.0pt in the example).
\item The sequence of drawing commands to which a two-terminal macro is
   expanded begins with the command {\tt `line invis $\cdots$'} where
   the part following {\tt `line invis'} is the first argument of the
   macro if it exists, otherwise this part specifies length {\tt
   elen\_\/} in the current direction. The invisible line is first
   drawn, and the element is drawn on top of the line.  The current
   direction is initially to the right, so in the example the resistor
   is drawn to the right. 
\item The element---rather the initially-drawn invisible line---can
   be given a name ({\tt R1\/} in the example, so that points
   {\tt R1.start} and {\tt R1.end} are defined as shown, also {\tt R1.center\/}
   is defined).  Pic place names begin with an upper-case letter, whereas
   variable names begin with a lower-case letter.
\item The element body is enclosed by a block, which later can be
   referenced for placing labels around the element.  The block
   corresponds to an invisible rectangle of which the top and bottom
   are horizontal, and the sides of which are vertical, regardless of
   the direction in which the element is drawn.  In the diagram a
   dotted box has been drawn to show the block boundaries.
   \item The last sub-element, identical to the first, in each two-terminal
   element is an invisible line that can also be referenced later to
   place labels or other elements.
  \end{enumerate}

To produce Fig.\ \ref{BigResistor+} the following embellishments were included
after the previously-shown source:
{\small \input BigResistor+2.verb }

These lines have the following explanation.
\begin{itemize}
\item The line thickness is set to the default thin value of 0.4pt, and
   the box displaying the element body block is drawn.  Notice how the
   width and height can be specified, and the box centre positioned at
   the centre of the block.
\item The next paragraph draws two objects, a spline with an arrowhead,
   and a string left justified at the end of the spline.  Other
   string-positioning modifiers than {\tt ljust\/} are {\tt rjust,}
   {\tt above,} and {\tt below.} Lines to be read by {\bf pic\/} can be
   continued by putting a backslash as the rightmost character.  Where
   meaningful, {\tt Pic\/} objects have pre-defined compass corners,
   including {\tt .s\/} in the example, others being {\tt .n,} {\tt
   .e,} {\tt .w,} {\tt .ne,} {\tt .nw,} {\tt .sw,} {\tt .se,} {\tt .c,}
   {\tt .start,} {\tt .end.}  Furthermore any position, such as
   {\tt R1.c\/} in the example, has an $x$-coordinate and $y$-coordinate
   usable in expressions as, for example, {\tt R1.c.x\/} and {\tt R1.c.y.}

\item The next paragraph draws the arrows and labels at the ends of the
   resistor.  Positions on the drawing can be defined in many ways, including
   referring to a corner of an object or object-name, or by adding
   paired arithmetic expressions to a position as illustrated.
\item The last paragraph invokes a macro for dimensioning diagrams.
   Lines can be broken before a macro argument because {\bf m4\/}
   ignores white space before arguments.
   \end{itemize}

\section{Macro arguments}
Fig.\ \ref{CctTable+} is a table of the 2-terminal elements included
with this package, all drawn with the current direction to the right,
which is the default pic drawing direction.  Some elements are included
more than once to illustrate their arguments.
\begin{figure}[htb]
   \input CctTable+
   \caption{2-terminal element macros, with some variations}
   \label{CctTable+}
   \end{figure}
In the {\bf m4} language, macro arguments are included within parentheses
which follow the macro name, without spaces between the name and the
opening parenthesis.
%Arguments are separated by commas, and white space
%(spaces, new lines, tabs) at the beginning of each argument is ignored.

The first argument of the two-terminal elements, if included, defines
the line direction and length along which the element is drawn.  Other
arguments of several macros are used to produce variants of the default
elements.
%In Fig.\ \ref{CctTable+}, no first arguemnts are given, since the
%default direction and length are pre-defined.  The expanded first
%argument is inserted as the specification of the invisible first
%line of the element.  
Thus, for example,

{\tt resistor(up\_ 1.25)}

\noindent%
draws a resistor 1.25 units long up from the current position.
The name {\tt up\_\/} is a macro that resets the current macro and {\tt pic\/}
directional parameters to point up.

Instead of defining a direction and distance as above, some variants of the
first argument are

{\tt up\_ 1.25 from\/} {\sl position}

{\tt to\/} {\sl position}

{\tt from\/} {\sl position} {\tt to\/} {\sl position}

{\tt with\/} {\sl corner\/} {\tt at\/} {\sl position}

\noindent%
where for a line, the {\sl corner\/} is one of {\tt .start\/}, {\tt
.end\/}, or {\tt .center\/}.

A position may be absolute, such as {\sl (expression, expression)},
or {\sl (position,position)}, where the latter takes the x-coordinate
from the first position, and the y-coordinate from the second.  Positions
can be named, thus

{\tt Node1: (0,0); Node2: (1,1); inductor from Node1 to Node2,}

\noindent%
or, for example,

{\tt Amp1: opamp with .In1 at Here; line up 0.5 from Amp1.Out}

\noindent%
where {\tt Amp1} becomes the name for a block containing
positions {\tt In1} and {\tt Out} predefined in the opamp macro.
Referring to {\tt Amp1\/} is the same as {\tt Amp1.center,} a compass
corner can be used, e.g.\ {\tt Amp1.n\/} for the top, and
{\tt Amp1.In1\/} is the named position within the block.

The name {\tt Here} is the default for the current drawing position.

Another possibility for defining positions is 

{\sl expression} {\tt of the way between} {\sl position}
 {\tt and} {\sl position}

\noindent%
which is abbreviated as

{\sl expression} {\tt <} {\sl position} {\tt ,} {\sl position} {\tt >}

\noindent%
but care has to be used in giving this construction to {\tt m4}, since
the comma may have to be put within quotes, {\tt `,'} to distinguish it
from the {\tt m4\/} argument-separator.

Positions can refer to previously-drawn elementary {\bf Pic\/} objects
within the current block, e.g.

{\tt resistor from 1st line.start to 3rd last [].s,}

\noindent%
and finally, positions can be calculated using variables, which must
begin with a lower-case letter, and of which the scope is the current
block.  Thus, for example,

{\tt
  theta = atan2(B.y-A.y,B.x-A.x)

  line to Here+(3*cos(theta),3*sin(theta)).
  }

A {\tt Pic\/} manual should be consulted for more examples, and for
other facilities, such as the branching facility,

{\tt if\/} {\sl expression\/} {\tt then \{\/} {\sl anything\/} 
  {\tt\} else \{\/} {\sl anything\/} {\tt\}},

\noindent%
the looping facility,

{\tt for\/} 
{\sl variable\/} {\tt =\/} {\sl expression\/} 
{\tt to\/} {\sl expression\/} 
{\tt by\/} {\sl expression\/} 
{\tt do \{\/} {\sl anything\/} {\tt\},} 

\noindent%
operating-system commands, string handling, and file inclusion.

\section{Branch-current arrows}
The macro
\begin{figure}[hbt]
   \input currents+
   \caption{Illustrating {\tt b\_current}}
   \label{currents+}
   \end{figure}
\begin{verbatim}
   b_current(label,position,direction)
   \end{verbatim}\vspace{-3ex}
draws an arrow on the last-drawn two-terminal element (i.e.\ line),
inward by default, outward if the third argument is non-blank.  The
first argument is an optional label, of which the default position is
the macro {\tt above\_,} which evaluates to above if the current
direction is right, or to ljust, below, rjust if the current direction
is respectively down, left, up.  A non-blank second argument specifies
another relative position, for example {\tt below\_,} which places the
label below with respect to the current direction, or an absolute
position, for example {\tt below,} or {\tt ljust,} with respect to the
arrowhead.

\section{Labels}
   Macros for labelling two-terminal elements are included:
\begin{verbatim}
   llabel(arg1,arg2,arg3)
   clabel(arg1,arg2,arg3)
   rlabel(arg1,arg2,arg3)
   dlabel(long,lat,arg1,arg2,arg3)
   \end{verbatim}\vspace{-2ex}
The first 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: up, down, left, right.}
The second places the arguments along the centre, and the third along the
right side.  Thus a simple circuit example with labels is
{\small \input Loop+.verb }
\noindent which produces Fig.\ \ref{Loop+}.
\begin{figure}[htb]
   \input Loop+
   \caption{A loop with labelled elements}
   \label{Loop+}
   \end{figure}
The macro {\tt dlabel\/} performs the above 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)}
respectively relative to the centre of the element.
%first moving {\tt vec\_(-long,lat)} to place arg1 with respect to the
%current element centre and direction, then placing arg2 at {\tt vec\_(0,lat),}
%then arg3 at {\tt vec\_(long,lat)}.

\section{Diagram scaling}

The finished size of a diagram or of elements whithin it can be easily
adjusted.

First, the line, e.g.\ `.PS 4.5' scales the entire drawing to a width of
4.5in, no matter what absolute lengths are in the interior.

Second, resetting the pic variable `scale', e.g.\ `scale = 2.54'
divides all lengths by 2.54, as one would to use cm instead of inches.

Third, the two-terminal elements all have default length and body size 
which are multiples of the pic variable `linewid,'
so setting this variable resets default element dimensions.
The scope of a pic variable is within the current block, so a construct
such as
\begin{verbatim}
linewid = 0.75
   ... drawing commands
B: [linewid = 1.25
      ... drawing commands
      ]
   ... more drawing commands
   \end{verbatim}\vspace{-2ex}
changes the size of elements within block {\tt B.}
Alternatively, it is
permissible to redefine the default length {\tt elen\_} or default
body size paramenter {\tt dimen\_.}

Text strings do not scale at all unless adjusted separately.

\section{Other circuit elements}
Some basic elements are not two-terminal.  Fig.\ \ref{Misc+} shows a
ground with and without a stem, an operational amplifier, and a simple
transformer.  By convention, such elements are enclosed in a block, and
thus can be named and can contain named locations in the interior, such
as E, B, C for a bipolar transistor.  An invisible locating line can be
optionally specified by the first argument, as for the two-terminal
elements.  Instead of positioning by the first line, the enclosing
block may be positioned, thus,
  {\sl element}{\tt (}{\tt at\/} {\sl position}{\tt ),} or using its
compass corners, thus,
  {\sl element} {\tt with} {\sl corner} {\tt at} {\sl position,} or,
when the block contains a pre-defined location, using
  {\sl element} {\tt with} {\sl location} {\tt at} {\sl position.}
Macro arguments are given for each element in Sec.\ \ref{defines}.

The operational amplifier is enclosed in a block
containing the three pre-defined internal locations shown on the diagram,
{\tt In1,} {\tt In2,} and {\tt Out}, which can be referenced in later
commands, for example as `{\tt last [].Out}.'
The first argument defines the direction and length of the opamp, but the
position is determined either by pre-defined enclosing block of the opamp,
or by a construction such as `{\tt opamp with .In1 at Here}' which places
the internal position {\tt In1} at the specified location.
There are optional second and third arguments for which the defaults
are {\tt\$-\$\/} and {\tt \$+\$\/} respectively.

The transformer has pre-defined internal locations
{\tt P1,} {\tt P2,} {\tt S1,} and {\tt S2.}  The first argument
specifies the direction and distance from {\tt P1} to {\tt P2}, with
position determined by the enclosing block as for opamps.  The second
argument places the secondary side of the transformer to the left
or right of the drawing direction.
\begin{figure}[htb]
   \input Misc+
   \caption{Miscellaneous basic elements}
   \label{Misc+}
   \end{figure}

Fig.\ \ref{Bip+} shows the variations of bipolar transistor macro {\tt
bi\_tr,} which contains pre-defined internal locations {\sl E}, {\sl
B}, {\sl C}.  The first argument defines the distance and direction
from {\sl E} to {\sl C,} with location determined by the enclosing
block as for other elements, and the base placed to the left or right
of the 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.
\begin{figure}[htb]
   \input Bip+
   \caption{Bipolar transistor variants (current direction upward)}
   \label{Bip+}
   \end{figure}
Some FETs with pre-defined internal locations {\sl S,} {\sl D,} and {\sl G} are
also included, with the same arguments as {\tt bi\_tr,} as shown in
Fig.\ \ref{fet+}.  The number of possible semiconductor symbols is very
\begin{figure}[htb]
   \input fet+
   \caption{JFET, insulated-gate enhancement and depletion MOSFETS}
   \label{fet+}
   \end{figure}
large, so these macros must be regarded as prototypes.

Some other non-two-terminal macros are {\tt dot\/} which has an
optional argument `{\tt at\/} {\sl location}', the line-thickness
macros, the fill macro, and {\tt hop,} which is useful to show
non-touching cross-overs of conductors.

\section{Directions}
Aside from its block-structure capabilities, looping, and macros, {\bf pic\/}
has a very useful concept of the current point and current direction,
the latter unfortunately limited to {\tt up, down, left, right.}  Objects can
be drawn at absolute locations or placed relative to previously-drawn
objects.  These {\tt .m4\/} macros need to know the current direction so
whenever {\tt up, down, left, right\/} are used they should be written as
{\tt up\_, down\_, left\_, right\_\/} which are macros.

To draw circuit objects in other than the standard four directions,
the macros {\tt Point\_({\sl degrees}),} {\tt point\_({\sl
radians}),} and {\tt rpoint\_({\sl rel linespec})\/} re-define the
direction-cosine macros {\tt x\_, y\_\/} which are used within
element-drawing macros.  Thus `{\tt Point\_(-30); resistor}' draws a
resistor along a line with slope -30 degrees. `{\tt rpoint\_(to Z)}'
sets the current direction cosines to point to location Z.
Macro {\tt vec\_(x,y)} evaluates
to the position {\tt (x,y)\/} rotated by the argument of the previous
{\tt Point\_, point\_\/} or {\tt rpoint\_\/} command.  The macro {\tt
rvec\_(x,y)} evaluates to position {\tt Here + vec\_(x,y)} and is the
principal device used to define relative locations in the circuit
macros.  Thus, `{\tt line to rvec\_(x,0)}' draws a line of length
{\tt x\/} in the current direction.

Fig.\ \ref{Oblique+} shows a circuit drawn using the above
macros.  The source for the figure is below, and illustrates that some
hand-placement of labels using {\tt dlabel\/} may be useful when elements
are drawn other than horizontal or vertically.
\begin{figure}[htb]
   \input Oblique+
   \caption{Illustrating elements drawn at oblique angles}
   \label{Oblique+}
   \end{figure}
{\small \input Oblique+.verb }
The above source also illustrates that since {\bf m4\/} macro arguments
are separated by commas, any commas that are integral parts of the
arguments must be protected either by parentheses as in {\tt
inductor(from Cr to Cr+vec\_(elen\_,0))\/} or by multiple single
quotes, {\tt `{}`,'{}'.}

\section{Logic gates}
\begin{figure}[htb]
   \input NOR+
   \caption{Illustrating {\tt NOR\_gate(3)}}
   \label{NOR+}
   \end{figure}
Fig.\ \ref{NOR+} shows a 3-input NOR gate, with the enclosing block
and pre-defined internal locations {\tt Out,} {\tt In1}--{\tt In3}.
Gate macros have an optional argument, an integer from
$0$ to $N$ where $N$ can be up to approximately 5, defining locations
{\tt In1,} $\cdots$ {\tt In}$N.$  By default $N=2,$
except for macros {\tt NOT\_gate\/} and {\tt BUFFER\_gate\/} which
have one input {\tt In1\/}, unless they are given an argument, which
is treated as the line specification of a two-terminal element.
\begin{figure}[htb]
   \input Liblog+
   \caption{Basic logic gate library}
   \label{Liblog+}
   \end{figure}
Fig.\ \ref{Liblog+} shows these and the other basic logic gates included in
library {\tt liblog.m4}.
%in which the elements have been defined
% to the scale used in \cite{Johnstone92,Verwer92}.
These gates are typically not two-terminal elements and are normally
drawn horizontally or vertically (although arbitrary
directions may be set with e.g.\ {\tt Point\_({\sl degrees})}).
Each gate is contained in
a block of typical height {\tt 6*L\_unit\/} where {\tt L\_unit\/}
is a macro intended to establish line separation for an imaginary grid
on which the elements are superimposed.

The following
source produces the $SR$-flip-flop shown in Fig.\ \ref{FF+} to illustrate
change of direction.  Note that
when a gate is rotated, its input locations retain their positions
relative to the gate body.
{\small \input FF+.verb }
\begin{figure}[htb]
   \input FF+
   \caption{$SR$-flip-flop}
   \label{FF+}
   \end{figure}

A good strategy for drawing complex logic circuits might be summarized
as follows:
\begin{itemize}
\item Establish the absolute locations of gates and other major components
  (e.g.\ chips\/) relative to a grid of mesh size commensurate with
  {\tt L\_unit}, which is an absolute length.
\item Draw minor components or blocks relative to the major ones, using
   parametrized relative distances.
\item Draw connecting lines relative to the components and previously-drawn
   lines.
\item Write macros for repeated constructs.
\item Tune the diagram by making absolute locations relative, and by tuning
   the parameters.
   Some useful macros for this are the following, which are in units of
  {\tt L\_unit}:
   \begin{itemize}
   \item[] {\tt AND\_ht, AND\_wd\/}: the height and width of basic AND and
     OR gates
   \item[] {\tt BUF\_ht, BUF\_wd\/}: the height and width of basic buffers
   \item[] {\tt N\_diam\/}: the diameter of NOT circles
   \end{itemize}
   \end{itemize}
A useful exercise might be to reproduce the example of Fig.\ \ref{exVIII}.
\begin{figure}[htb]
   \input ex8
   \caption{Multi-function latch circuit}
   \label{exVIII}
   \end{figure}

\section{Developer's notes}
Because {\bf gpic\/} or its equivalent were not then available, several
years ago in the course of writing a book I took a few days off to
write a {\bf pic}-like interpreter {\bf (dpic)} that produced latex
picture objects.  More recently the interpreter has been upgraded to
generate {\bf mfpic\/} or {\bf PSTricks\/} commands, the latter my
preference because of the quality and flexibility of resulting
graphics, including facilities for colour and rotations.  Very
recently, Fig 3.1 output has been added.  I preferred the more-powerful
{\bf m4\/} macro processor to {\bf pic\/} macros, and therefore {\bf
m4}, which comes with many Unix systems and a free version of which is
available, is required here.  If starting over today would I not just
start with the {\bf gpic\/} source and change its back end?  Good
question.  Maybe.  Another question might be, why not use {\bf
PSTricks\/} (or {\bf mfpic}) alone?  Much can be done that way using
macros, but the {\bf pic\/} language is extremely simple to learn,
especially for backslashophobics like me.  The language has stood the
test of time, it has built-in looping and block-structure constructs
like
\begin{verbatim}
   drawing commands ...
   [drawing commands... 
      A:[... 
         B:box
        ]
   ] with .A.B.bottom at 2nd last ellipse.top
\end{verbatim}\vspace{-1ex}
that combine power with simplicity, and it allows the simple computation
of geometries using elementary functions.

{\bf Gpic\/} and {\bf dpic}
pass unaltered any line beginning with a \verb|\| character,
allowing TeX or PSTricks macros to be invoked, for example to set
parameters such as colour or fill values.

Using the {\bf mfpic\/} output of {\bf dpic\/} it is
possible to produce Metafont alphabets
of circuit elements or their sub-components, thereby
essentially removing dependence on device drivers, but with the
complication of treating every graphic sub-component as a \TeX\ box.

The {\bf xfig\/} output of {\bf dpic\/} allows elements to be defined
and fine-tuned, and then using the interactive graphics of {\bf xfig,}
quickly assembled into a circuit.  However, the elements should now have
all boundary points and points of connection on the grid points, or
at least the grid lines, of the drawing canvas.  Further refinement of
the elements might still be required.

Because the set of common circuit components and potential macros is
huge, an industrial-strength system developed from the one described
here would probably require a combination of all of the techniques
described, including the ability to dynamically define and build
character sets from macros.

\section{Bugs}
{\bf Initialization:}
If the first element macro evaluated is non-two-terminal or is within a
Pic block, then later macros evaluated outside the block may produce
the error message
\begin{verbatim}
   there is no variable `rp_ang' 
\end{verbatim}
because {\tt rp\_ang\/} is not defined in the outer-most scope of the
diagram.  To cure this problem, put the line
\begin{verbatim}
   cct_init 
\end{verbatim}
immediately after the .PS line, or prior to the first block.  It is
entirely permissible to modify {\tt cct\_init\/} to include commonly-used
diagram initializations, such as the {\tt thicklines\_\/} statement, and
to invoke cct\_init at the beginning of every diagram.
For completeness, macros {\tt gen\_init,} {\tt log\_init,} {\tt darrow\_init}
are also provided for cases where the circuit library is not included.

{\bf Commas:}
Remember that macro arguments are separated by commas, so commas which are
part of an argument must be protected by parentheses or quotes.  Thus,
\begin{verbatim}
   shadebox(box with .n at w,h)
\end{verbatim}
produces an error, whereas
\begin{verbatim}
   shadebox(box with .n at w`,'h)
\end{verbatim}
and
\begin{verbatim}
   shadebox(box with .n at (w,h))
\end{verbatim}
do not.

{\bf Names:}  Using the name of a macro as part of
a comment or string is a simple and common error.
Thus,
\begin{verbatim}
   arrow right "$\dot x$" above
\end{verbatim}\vspace{-1ex}
produces an error message because {\tt dot\/} is a macro name.   Macro
expansion can be avoided by adding quotes, as follows:
\begin{verbatim}
   arrow right `"$\dot x$"' above
\end{verbatim}\vspace{-1ex}

To avoid name conflicts, all library macros intended only for internal use
have names that begin with {\tt m4.}

A good rule is to process diagrams in separate files, and to use the TeX
\verb|\input| command to include the result.
If extensive use of strings
that conflict with macro names is required, then another solution is
to replace the strings by macros which are expanded by \LaTeX\ , for example
the diagram
\begin{verbatim}
.PS
   box "\stringA"
.PE
\end{verbatim}\vspace{-1ex}
with the LaTeX macro
\begin{verbatim}
  \newcommand{\stringA}{%
   Circuit containing planar inductor and capacitor}
\end{verbatim}\vspace{-1ex}

{\bf Current direction:} Some macros, particularly those for labels, do
unexpected things if care is not taken to pre-set the current direction
using macros {\tt right\_,} {\tt left\_,} {\tt up\_,} {\tt down\_,}
or {\tt rpoint\_($\cdot$).}
Thus for two-terminal macros it is good practice to write, e.g.

{\tt resistor(up\_ from A to B); rlabel(,R\_1)}

\noindent%
rather than 

{\tt resistor(from A to B); rlabel(,R\_1),}

\noindent%
which produce different results if the last-defined drawing direction is not
up.  It might be possible to change the label macros to avoid this problem
without sacrificing ease of use.

\section{List of macros}
\label{defines}
The following table lists the macros in libraries
darrow.m4, libcct.m4, liblog.m4, libgen.m4, and files gpic.m4, mfpic.m4,
and pstricks.m4.

Internal macros defined within the libraries begin with the characters
m4, and are not listed here.

The libraries use the following {\bf pic\/} variables:
\begin{verbatim}
   m4dll
   m4dlw
   m4i
   m4j
   m4t1
   m4t2
   m4tmp
   rp_ang
   rp_ht
   rp_len
   rp_wid.
\end{verbatim}

The library in which each macro is found is shown, and a brief description.
\input defines
\endinput