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.tex291
1 files changed, 216 insertions, 75 deletions
diff --git a/graphics/circuit_macros/doc/body.tex b/graphics/circuit_macros/doc/body.tex
index f89fe710fe..e229888d91 100644
--- a/graphics/circuit_macros/doc/body.tex
+++ b/graphics/circuit_macros/doc/body.tex
@@ -118,10 +118,12 @@ only with \dpic.
concepts applied here do not require \Mfour.
\subsection{Quick start\label{Quickstart:}}
-Read this section to understand basic usage of \Mfour and macros.
-The contents of file {\tt quick.m4} and resulting diagram are shown in
-\FR{quick} to illustrate the language
-and the production of basic labeled circuits.
+Read this section to understand basic usage of \Mfour and macros,
+and look at the {\tt examples.pdf} file for cases
+that might be similar to yours.
+The contents of file {\tt quick.m4} and resulting diagram are shown
+in \FR{quick} to illustrate the language and the production of basic
+labeled circuits.
\begin{figure}[ht]
\parbox{\textwidth}{\small\verbatiminput{quick.m4}}%
\hfill\llap{\raise-1.15in\hbox{\input quick }}%
@@ -741,10 +743,8 @@ operating-system commands, \pic macros, and external file inclusion.
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 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.
+in {\tt[} {\tt]} blocks as described in \SR{Compoundobjects:}
+and \SR{Composite:}.
The two-terminal element macros follow a
set of conventions described in this section, and other elements will
be described in \SR{Composite:}.
@@ -1391,15 +1391,57 @@ The block must be placed by using its compass corners, thus:
{\sl element} {\tt with} {\sl corner} {\tt at} {\sl position}
or, when the block contains a predefined location, thus:
{\sl element} {\tt with} {\sl location} {\tt at} {\sl position}.
+In some cases, an invisible line can be specified by the first argument
+to determine length and direction (but not position) of the block.
A few macros are positioned with the first argument;
the {\tt ground} macro, for example:
{\tt ground(}{\tt at} {\sl position}{\tt ).}
-In some cases, an invisible line can be specified by the first argument
-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.
+As a preliminary example,
+\FR{QTrans} shows the file {\tt quick.m4} adapted to include a
+transformer,
+% a composite element with predefined interior locations
+%{\sl P1,} {\sl P2,} {\sl S1,} {\sl S2} and others. The {\tt transformer} macro
+which is described in more detail below.
+\begin{figure}[H]
+% \vspace*{-\baselineskip}
+ \parbox{4in}{\small \verbatiminput{QTrans.m4}}%
+ \hspace*{-0.45in}\raise-0.15in\hbox{\input QTrans }
+ \vspace*{-\baselineskip}
+ \caption{The file {\tt quick.m4} has been modified to include a
+ transformer, of which the length and orientation of connectors
+ is given by the first argument, and which is placed by reference
+ to internal position {\sl P1.} Label {\sl Vs} has
+ been added for convenient reference.}
+ \label{QTrans}
+ \end{figure}
+
+\FR{Xform} shows variants of the transformer macro,
+which has predefined internal locations
+{\sl P1,} {\sl P2,} {\sl S1,} {\sl S2,} {\sl TP,} and {\sl TS.}
+The first argument specifies the direction and distance from {\sl P1}
+to {\sl P2} but not the position of the transformer, which is determined
+by the enclosing block as normal for a composite element. The second
+argument places the secondary side of the transformer to the left or
+right of the drawing direction. The optional third and fifth arguments
+specify the number of primary and secondary arcs respectively. If the
+fourth argument string contains an {\tt A}, the iron core is omitted;
+if a {\tt P}, the core is dashed (powder); and if it contains a {\tt W},
+wide windings are drawn. A {\tt D1} puts phase dots at the {\sl P1,
+S1} end, {\tt D2} at the {\sl P2, S2} ends, and {\tt D12} or {\tt D21}
+puts dots at opposite ends.
+\begin{figure}[H]
+ \input XformMan
+ \caption{The {\tt transformer(\linespec,L|R,{\sl np},%
+[A|P][W|L][D1|D2|D12|D21],{\sl ns})}
+ macro (drawing direction {\tt down}), showing predefined terminal
+ and centre-tap points.}
+ \label{Xform}
+ \end{figure}
+
The macro {\tt
potentiometer(\linespec,{\sl cycles},{\sl fractional pos},{\sl length},
$\ldots$)},
@@ -1439,6 +1481,7 @@ These two macros require the two-terminal element to be drawn either up,
down, to the left, or to the right; they are not designed for obliquely
drawn elements.
+\pagebreak
A few composite symbols derived from two-terminal elements
are shown in \FR{Composite}.
\begin{figure}[H]
@@ -1528,30 +1571,6 @@ The code in \FR{opampex} places an opamp with three connections.
\label{opampex}
\end{figure}
-\FR{Xform} shows variants of the transformer macro,
-which has predefined internal locations
-{\sl P1,} {\sl P2,} {\sl S1,} {\sl S2,} {\sl TP,} and {\sl TS.}
-\begin{figure}[H]
- \input XformMan
- \caption{The {\tt transformer(\linespec,L|R,{\sl np},%
-[A|P][W|L][D1|D2|D12|D21],{\sl ns})}
- macro (drawing direction {\tt down}), showing predefined terminal
- and centre-tap points.}
- \label{Xform}
- \end{figure}
-The first argument
-specifies the direction and distance from {\sl P1} to {\sl 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. The optional third and fifth arguments
-specify the number of primary and secondary arcs respectively.
-If the fourth argument string contains an {\tt A}, the iron core
-is omitted;
-if a {\tt P}, the core is dashed (powder);
-and if it contains a {\tt W}, wide windings are drawn.
-A {\tt D1} puts phase dots at the {\sl P1, S1} end, {\tt D2} at the
-{\sl P2, S2} ends, and {\tt D12} or {\tt D21} puts dots at opposite ends.
-
\FR{Audio} shows some audio devices, defined in {\tt []} blocks,
with predefined internal locations as shown.
\begin{figure}[H]
@@ -1582,6 +1601,7 @@ macro is shown in \FR{Nport}.
The {\tt nterm} macro draws single pins instead of pin pairs.}
\label{Nport}
\end{figure}
+\pagebreak
The macro begins with the line
\verb|define(`nport',`[Box: box `$1'|,
so the first argument is a box specification such as size, fill,
@@ -1644,7 +1664,7 @@ An {\tt I} in the first argument draws open circles for contacts.
\label{Contact}
\end{figure}
-\enlargethispage{\baselineskip}
+\pagebreak
The {\tt contacts({\sl poles, chars})} macro in \FR{Contacts}
draws multiple contacts.
\begin{figure}[H]
@@ -1686,6 +1706,7 @@ composite elements that must be placed accordingly.
\label{NPDT}
\end{figure}
+\pagebreak
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.
@@ -1752,7 +1773,6 @@ 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)}
@@ -1773,6 +1793,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.
+\pagebreak
\FR{Darlington} shows a composite macro with several optional internal elements.
\begin{figure}[H]
\input Darlington
@@ -1806,7 +1827,6 @@ 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}.
\begin{figure}[H]
@@ -1834,6 +1854,7 @@ is much like a two-terminal element.
to the second argument to draw open arrowheads.}
\label{thyristor}
\end{figure}
+\enlargethispage{\baselineskip}
The wrapper macro
{\tt thyristor\_t({\sl linespec, chars, label})} and similar macros
{\tt scr, scs, sus,} and {\tt sbs}
@@ -1985,10 +2006,11 @@ index takes on values 1, 3, 5, $\ldots$.
Repetitive actions can also be performed with the {\tt libgen} macro
-{\tt Loopover\_(`{\sl variable}', {\sl actions}, {\sl value1},
+{\tt foreach\_(`{\sl variable}', {\sl actions}, {\sl value1},
{\sl value2}, $\ldots$)}
\noindent
+(an alias for the older macro {\tt Loopover\_}),
which evaluates {\sl actions} and increments counter {\tt m4Lx}
for each instance of {\sl variable} set to {\sl value1, value2, $\ldots$}
@@ -2026,7 +2048,6 @@ regardless of gate orientation, as in \FR{FF}.
\label{FF}
\end{figure}
-\pagebreak
Beyond a default number (6) of inputs, the
gates are given wings as in \FR{exVIII}.
\begin{figure}[H]
@@ -2062,7 +2083,7 @@ argument character sequence of any gate negates the inputs, and including
\verb|B| in the second argument invokes the
general macro {\tt BOX\_gate([P|N]...,[P|N],{\sl horiz size},{\sl
vert size},{\sl label})}, which draws box gates. Thus, {\tt
-BOX\_gate(PNP,N,,8,\char92 geq 1)} creates a gate of default width,
+BOX\_gate(PNP,N,{},8,\char92 geq 1)} creates a gate of default width,
eight {\tt L\_unit}s height, negated output, three inputs with the
second negated, and internal label ``$\geq1$''.
If the fifth argument begins with {\tt sprintf} or a double quote then
@@ -2140,7 +2161,7 @@ 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.
-
+\enlargethispage{\baselineskip}
\FR{Multiplexer} shows a multiplexer block with variations, and
\FR{Demultiplexer} shows
the very similar demultiplexer.
@@ -2187,6 +2208,125 @@ of which can be specified as macro arguments.
In addition to the logic gates described here, some experimental
IC chip diagrams are included with the distributed example files.
+\subsection{Automatic structures\label{Automatic:}}
+In some common but special cases, logic circuits having a predefined
+structure can be drawn automatically, thereby saving much
+repetitive code. Boolean functions
+expressed as a product of sums or a sum of products are examples, and
+result in two-layer diagrams. Consider for example, the function
+\[
+ f(a,b,c,d) = abcd + \hbox{\tt\char126}ba + c + b\hbox{\tt\char126}a
+ \]
+which is the sum (that is, ``or'') of four terms which are products
+(that is, ``and'') of one or more single-character variables or their
+negation indicated by a preceding tilde. This and similar functions can
+be drawn in two-layer form, as follows. Define the circuit using function
+notation with the logic-gate functions {\tt And, Or, Not, Buffer, Xor,
+Nand, Nor,} and {\tt Nxor.} Variables can also be negated using tilde
+notation as shown above. An \Mfour\ macro implementing a stack can
+parse the defining function and draw the corresponding structure,
+as shown in \FR{Autologix} for the above example.
+\begin{figure}[H]
+ \vspace*{-\baselineskip}
+ \input AutologixMan
+ \caption{The circuit drawn by
+ {\tt Autologix(Or(And(a,b,c,d),And(Not(b),a),c,And(d,Not(a))))}.}
+ \label{Autologix}
+ \end{figure}
+Such an implementation is the macro
+
+{\tt Autologix({\sl function-spec}; {\sl function-spec}; $\ldots$,
+ [M[irror]] [N[occonect]] [L[eftinputs]]\\
+ {}\hspace*{20bp} [R][V] [;offset={\sl value}])}
+
+\noindent
+where {\sl function-spec} is of the form
+{\tt{\sl function}({\sl args}) [@ {\sl location-attribute}]},
+e.g.,
+
+{\tt HalfAdder: Autologix(Xor(x,y);And(x,y),LVR)}.
+
+This macro draws one or more trees of gates with the output or outputs
+(treeroots) to the right (on the left if the {\tt M[irror]} option is used).
+The predefined functions are given above
+and may be nested; e.g., {\tt Or(And(x,{\char126}y),And({\char126}x,y)).}
+The output is contained in a {\tt [ ]} block, which can be positioned normally.
+Function notation does not model internal connections such as
+feedback, however, but internal nodes can be accessed and connections added.
+
+The resulting block has outputs labeled {\sl Out1, Out2, $\ldots$}
+corresponding to the functions in the first argument, and inputs
+labeled {\sl In{\tt<}var{\tt>}} for each variable {\sl {\tt<}var{\tt>}} in the
+defining expressions, (with NOT gates for variables preceded by {\tt\char126}).
+
+The exact appearance of a tree depends on the order in which
+terms and variables appear in the expressions. Gates can be placed
+relative to previously drawn objects using the {\tt @ {\sl location}} construct;
+e.g., {\tt @with .nw at last [].sw+(0,-dimen\_)}.
+
+The macro has option {\tt R} for reversing the drawn order of the inputs
+{\tt N} for omitting input connections,
+and {\tt V} to reverse the order in which variables are scanned.
+There is also a
+limited capability {\tt L} for drawing inputs on the left; their vertical
+placement can be adjusted by adding {\tt ;offset={\sl var}}.
+
+
+To assist in manually adding connections to the resulting structure,
+the internal gate inputs and outputs are defined and numbered
+{\sl In1, In2, $\ldots$} and {\sl Out1, Out2, $\ldots$}. These labels
+are listed at the end of the output of {\tt Autologix}. Inputs
+are shown for an example in in \FR{Alogix}.
+\begin{figure}[H]
+% \vspace*{-\baselineskip}
+ \input AlogixMan
+ \caption{The {\tt Autologix({\sl expression; expression;$\ldots$, options})}
+ macro automatically draws Boolean expressions in function
+ notation. The function tree is drawn, then a row or column of inputs,
+ then the connections. A default result is on the left, and a tree
+ of gates without input connections but with internal input labels
+ shown is at the upper right.}
+ \label{Alogix}
+ \end{figure}
+
+The given expressions
+need not be in canonical two-layer form and, with minor effort, custom
+gates beyond those mentioned above can be defined and included.
+Here is how to include an arbitrary circuit (an SR-flipflop, for example)
+that is not one of the standard gates.
+First, define the circuit with a name ending
+in {\tt \_gate}. Put its inputs named {\sl In1, In2, $\ldots$}
+on the left and the output {\sl Out} on the right:
+\begin{verbatim}
+define(`SR_gate',`[ u = 2*L_unit
+ S: NOR_gate
+ line right_ 2*u from S.Out
+ Out: Here
+ R: NOR_gate at S+(0,-5*u)
+ TS: S.In2-(u,0)
+ TR: (TS,R.In1)
+ dot(at S.Out+(u,0))
+ line down u*3/2 then to TR+(0,u) then to TR then to R.In1
+ line from R.Out right u then up u*3/2 then to TS+(0,-u) \
+ then to TS then to S.In2
+ In1: S.In1
+ In2: R.In2 ]')
+\end{verbatim}
+
+Now define the function by which the circuit
+will be invoked using the built-in {\tt \_AutoGate} and the circuit name
+omitting {\tt \_gate}:
+\begin{verbatim}
+ define(`SRff',`_AutoGate(SR,$@)')
+\end{verbatim}
+That is all. The result, with a NAND and an AND gate, is shown in \FR{SRff}:
+\begin{figure}[H]
+% \vspace*{-\baselineskip}
+ \input SRffMan
+ \caption{The {\tt SRff} example.}
+ \label{SRff}
+ \end{figure}
+
\xection{Integrated circuits\label{ICs:}}
Developing a definitive library of integrated circuits is problematic
because context may determine how they should be drawn. Logical clarity
@@ -2206,33 +2346,36 @@ To draw the left-side pins, for example, one can write
\end{verbatim}
\noindent
and so on.
+Each pin can also be given a \pic\ name, some text
+to indicate function, and a number but,
+to reduce the tedium of adding the pins by hand, a list
+can be given to
+{\tt foreach\_(\char96{}variable\char39,
+\char96{}{\sl actions}\char39,
+{\sl value1, value2, $\ldots$})}
+which executes the given actions successively with
+ {\sl variable} = {\sl value1}, {\sl value2} $\ldots$ and the
+ counter {\tt m4Lx} set to 1, 2, $\ldots$ . The remaining left-side
+ and the right-side pins in the figure have been specified using this
+ macro.
+%as in \FR{sampleIC}.
\begin{figure}[H]
\parbox{\textwidth}{\small\verbatiminput{sampleIC.m4}}%
\hfill\llap{\raise-0.15in\hbox{\input sampleIC }}%
\vspace*{-\baselineskip}%
\caption{ An imaginary 16-pin integrated circuit and its code.
- Pin variations defined by the first {\tt Loopover\_}
+ Pin variations defined individually and by the first {\tt foreach\_}
are shown on the left; and text, pic labels, and pin
numbers are defined on the right.
The third and successive arguments of the second
- {\tt Loopover\_}
+ {\tt foreach\_}
are {\tt ;}-separated pin number, text, and pin type. The
semicolons are changed to commas by the {\tt patsubst} \Mfour\ macro
and the {\tt Upin} macro gives the resulting arguments to {\tt lg\_pin}.
\label{sampleIC}}%
\end{figure}
-Each pin can also be given a \pic\ name, some text
-to indicate function, and a number.
-
-To reduce the tedium of adding the pins by hand, a list
-can be given to the
-{\tt Loopover\_(\char96{}variable\char39,
-\char96{}{\sl actions}\char39,
-{\sl value1, value2, $\ldots$})}
-which executes the given actions successively with
- {\sl variable} = {\sl value1}, {\sl value2} $\ldots$ and the
- counter {\tt m4Lx} set to 1, 2, $\ldots$ as in the diagram.
+%\pagebreak
\xection{Single-line diagrams\label{SingleLine:}}
\input SLDsMan
Standard single-line diagrams for power distribution employ many of
@@ -2363,7 +2506,6 @@ and can be labelled like a normal two-terminal element. If, however,
breakers are included using {\tt B: tt\_box(,{,},C,C)} then write, for example,
{\tt llabel(,Box 15,{,},Body)} to place the label correctly.
-\pagebreak
\subsection{One-terminal and composite SLD elements\label{OneTermSLD:}}
The one-terminal elements have two components: a stem with optional
breaker or slash symbol, and a head.
@@ -2558,7 +2700,6 @@ 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}
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,
@@ -2577,7 +2718,6 @@ to defer macro expansion. Macro arguments are referenced inside a
macro by number; thus {\tt \$1} refers to the first argument.
A few examples will be given.
-\pagebreak
\Example{1}
Custom two-terminal elements can often be defined by writing a wrapper
for an existing element. For example, an enclosed thermal switch
@@ -2592,6 +2732,7 @@ can be defined as shown in \FR{Thermal}.
\label{Thermal}
\end{figure}
+\enlargethispage{\baselineskip}
\Example{2}
In the following,
two macros are defined to simplify the repeated drawing
@@ -2606,7 +2747,6 @@ a subcircuit that is replicated several times to generate \FR{Tline}.
\label{Tline}
\end{figure}
-\pagebreak
\Example{3}
\FR{HybridPi} shows an element that is composed of several basic
elements and that can be drawn in any direction prespecified by
@@ -3324,7 +3464,7 @@ 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.
-\enlargethispage{\baselineskip}
+\pagebreak
\xection{Developer's notes\label{Developersnotes:}}
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
@@ -3334,20 +3474,20 @@ 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.
+over time to generate \mfpic, \MetaPost~\cite{metapost,drawingwithmetapost},
+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
@@ -3358,8 +3498,8 @@ thousands of lines. The learning curve of \pic\ compares well with
other possibilities, but 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 to preserve the compatability of some of the older macros.
-Compromises have also been made to retain reasonable compatibility with
+been made to preserve the compatability of some of the older macros
+and also to retain reasonable compatibility with
the various postprocessors. No choice of tool is without compromise,
and producing good graphics seems to be time consuming, no matter how
it is done, but the payoff can be worth the effort.
@@ -3758,6 +3898,7 @@ without sacrificing ease of use.
\end{enumerate}
+\pagebreak
\xection{List of macros\label{Listofmacros:}}
\label{defines}
The following table lists macros in the libraries, configuration