summaryrefslogtreecommitdiff
path: root/graphics/circuit_macros/doc/body.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-01-02 03:04:28 +0000
committerNorbert Preining <norbert@preining.info>2024-01-02 03:04:28 +0000
commit6b10e9901a24325e837f0fdc2cbce8f43f18ccff (patch)
tree3c9f999691258a32058bf6b3e8353eadeda85f9b /graphics/circuit_macros/doc/body.tex
parent094e5f512c4ea5981db967dd89c47363a603529b (diff)
CTAN sync 202401020304
Diffstat (limited to 'graphics/circuit_macros/doc/body.tex')
-rw-r--r--graphics/circuit_macros/doc/body.tex441
1 files changed, 235 insertions, 206 deletions
diff --git a/graphics/circuit_macros/doc/body.tex b/graphics/circuit_macros/doc/body.tex
index 296ba4e295..b6b9ca0dde 100644
--- a/graphics/circuit_macros/doc/body.tex
+++ b/graphics/circuit_macros/doc/body.tex
@@ -59,7 +59,7 @@ This manual%
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}
-augmented with \Mfour macros~\cite{KRm4}, and are
+augmented with \Mfour macros~\cite{KRm4,GnuM4}, and are
processed by \Mfour and a \pic processor to
convert them to \TPGF, \PSTricks, other \latex-compatible code, \SVG,
or other formats.
@@ -84,9 +84,9 @@ systems, project management software with graphical interfaces can
automate the process, but the steps can also be performed by a script,
makefile, or by hand for simple documents as described in~\SR{Quickstart:}.
-The diagram source file is preprocessed as illustrated in
+The diagram source file is processed as illustrated in
\FR{Flowdiag}. A configuration file is read by \Mfour,
-followed by the diagram source.
+followed by the diagram source and library macros.
The result is passed through a
\pic interpreter to produce {\tt .tex} output that can be inserted
into a {\tt .tex} document using the \verb|\input| command.
@@ -114,7 +114,7 @@ that understands \tpic specials, typically {\bq dvips}~\cite{dvips}.
The \dpic processor extends the pic language in small but important ways;
consequently, some of the macros and examples in this distribution work fully
only with \dpic.
-\Pic processors contain basic macro facilities, so some of the
+\Pic processors provide basic macro facilities, so some of the
concepts applied here do not require \Mfour.
\subsection{Quick start\label{Quickstart:}}
@@ -132,8 +132,9 @@ labeled circuits.
There are several ways of drawing the same picture; for example,
nodes (such as {\tt Origin}) can be defined and circuit branches
drawn between them; or absolute coordinates can be used (e.g.,
- {\tt source(up\_ from (0,0) to (0,0.75))} ). Element sizes and styles
- can be varied as described in later sections.\label{quick}}%
+ {\tt source(up\_ from (0,0) to (0,0.75))} ). Element sizes
+ can be varied and non-two-terminal elements included (\FR{QTrans})
+ as described in later sections.\label{quick}}%
\end{figure}
\subsubsection{\protect{Using \Mfour}%
@@ -156,34 +157,33 @@ containing the library files.
Now there are at least two basic possibilities as follows,
but be sure to read \SR{Simplifications:} for simplified use.
-\subsubsection{\protect{Processing with \dpic and \PSTricks or \TPGF}%
+\subsubsection{\protect{Processing with \dpic and \TPGF or \PSTricks}%
\label{Processingwithpstricks:}}
-If you are using \dpic with \PSTricks,
-put \verb|\usepackage{pstricks}| in the main \latex source file header and
-type the following commands or put them into a script:
+If you are using \dpic with \TPGF,
+put \verb|\usepackage{tikz}| in the main \latex source file header and
+type the following commands or put them into a script or makefile:
{\vspace*\parsep\tt
- m4 pstricks.m4 quick.m4 > quick.pic
+ m4 pgf.m4 quick.m4 > quick.pic
\brtt
- dpic -p quick.pic > quick.tex
+ dpic -g quick.pic > quick.tex
\vspace*\parsep}
-
\noindent
-To produce \TPGF code,
-the \latex header should contain \verb|\usepackage{tikz}|.
-The commands are modified to read \verb|pgf.m4|
-and invoke the {\tt-g} option of \dpic as follows:
+To produce \PSTricks code,
+the \latex header should contain \verb|\usepackage{pstricks}|.
+The commands are modified to read \verb|pstricks.m4|
+and invoke the {\tt-p} option of \dpic as follows:
{\vspace*\parsep\tt
% {\tt
- m4 pgf.m4 quick.m4 > quick.pic
+ m4 pstricks.m4 quick.m4 > quick.pic
\brtt
- dpic -g quick.pic > quick.tex
+ dpic -p quick.pic > quick.tex
\vspace*\parsep}
\enlargethispage{\baselineskip}
-A configuration file ({\tt pstricks.m4} and {\tt pgf.m4} in the
+A configuration file ({\tt pgf.m4} and {\tt pstricks.m4} in the
above examples) is {\em always} the first file to be given to \Mfour.
Put the following or its equivalent in the document body:
\begin{verbatim}
@@ -194,16 +194,16 @@ Put the following or its equivalent in the document body:
\label{Symbolic_label}
\end{figure}
\end{verbatim}
-Then for \PSTricks,
+Then for \TPGF,
+Invoking PDFlatex on the source produces {\tt .pdf} output directly.
+For \PSTricks,
the commands ``{\tt latex} {\sl file}{\tt;} {\tt dvips} {\sl file}''
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.
The essential line is \verb|\input quick| whether or not the {\tt figure}
environment is used.
-The effect of the \Mfour command above is shown in \FR{ConfigA}.
+The effect of the second \Mfour command above is shown in \FR{ConfigA}.
\begin{figure}[H]
% \vspace*{-\baselineskip}
\input ConfigA
@@ -313,7 +313,7 @@ document. Define a macro \verb|\mtotex| as shown in the
following example:
{\tt \verb^\documentclass{article}^ \brtt
-\verb^\usepackage{tikz}^ \brtt
+\verb^\usepackage{tikz} % or \usepackage{pstricks}^ \brtt
\verb^\newcommand\mtotex[2]{\immediate\write18{m4 ^%-I^ {\sl installdir}
\verb^#2.m4 | dpic -#1 > #2.tex}}%^\break
\verb^\begin{document}^ \brtt
@@ -365,19 +365,18 @@ The configuration files for \dpic are as follows,
depending on the output format (see \SR{Alternative:}):
{\tt pstricks.m4, pgf.m4, mfpic.m4, mpost.m4, postscript.m4, psfrag.m4, svg.m4,
gpic.m4,} or {\tt xfig.m4}.
-The file {\tt psfrag.m4} simply defines the macro {\tt psfrag\_} and
-then reads {\tt postscript.m4}.
-For \gpic, the configuration file is {\tt gpic.m4}.
+%The file {\tt psfrag.m4} simply defines the macro {\tt psfrag\_} and
+%then reads {\tt postscript.m4}.
The usual case for producing circuit diagrams is to read
-{\tt pstricks.m4} or {\tt pgf.m4} first when \dpic is the postprocessor or
+ {\tt pgf.m4} or {\tt pstricks.m4}
+ first when \dpic is the postprocessor or
to set one of these as the default configuration file.
+For \gpic, the configuration file is {\tt gpic.m4}.
+\pagebreak
At the top of each diagram source, put one or more initialization
commands; that is,
-
-{\tt cct\_init, log\_init, sfg\_init, darrow\_init, threeD\_init}
-
-\noindent
+{\tt cct\_init, log\_init, sfg\_init, darrow\_init, threeD\_init,}
or, for diagrams not requiring specialized macros, {\tt gen\_init}.
As shown in \FRS{ConfigA} and~\REF{ConfigB},
each initialization command reads in the appropriate macro
@@ -385,10 +384,21 @@ library if it hasn't already been read;
for example, {\tt cct\_init} tests whether {\tt libcct.m4} has been
read and includes it if necessary.
-A few of the distributed example files contain other experimental macros
+The distribution includes a collection of \pic utilities in the file
+{\tt dpictools.pic,} which is loaded automatically by macros that
+invoke the {\tt NeedDpicTools} macro.
+
+The file libSLD.m4 contains macros for drawing single-line
+power distribution diagrams. The line
+{\tt include(libSLD.m4)} loads the macros.
+A few of the distributed example files contain other macros
that can be pasted into diagram source files; see
{\tt Flow.m4} or {\tt Buttons.m4}, for example.
+Also included in the distribution is a generous set of examples
+to show capabilities of the macros and to act as a source of code
+if you wish to produce similar diagrams.
+
The libraries contain hints and explanations that might help in debugging
or if you wish to modify any of the macros. Macros are generally named
using the obvious circuit element names so that programming becomes something
@@ -426,7 +436,7 @@ beginning with an upper-case letter.
The classic \pic manual~\cite{KRpic} is still a good introduction to \pic, but
a more complete manual~\cite{Raymond95} can be found in the GNU \groff\
package, and both are available on the web~\cite{KRpic,Raymond95}. Reading
-either will give you competence with \pic in an hour or two. Explicit mention
+either will give you basic competence with \pic in an hour. Explicit mention
of {\tt *roff} string and font constructs in these manuals should be replaced by
their equivalents in the \latex context.
%A man-page language summary is
@@ -754,12 +764,9 @@ A list of the library macros and their arguments is in
\SR{defines}. The arguments have default values, so that only
those that differ from defaults need be specified.
-\FR{BigResistor}, which shows a resistor, also serves as
+\FR{BigResistor} shows a resistor and serves as
an example of \pic commands.
-%Consider the resistor shown in \FR{BigResistor},
-%which also serves as an example of \pic commands.
The first part of the source file for this figure is
-%as follows:
on the left:
\begin{figure}[H]
@@ -773,9 +780,9 @@ on the left:
The lines of \FR{BigResistor}
and the remaining source lines of the file are explained below:
\begin{itemize}
-\item The first line invokes the macro {\tt cct\_init} that
+\item The first line after {\tt .PS} invokes the macro {\tt cct\_init} that
loads the library {\tt libcct.m4}
- and initializes local variables needed by some circuit-element macros.
+ and initializes local variables needed by circuit-element macros.
\item
The sizes of circuit elements are proportional to the \pic environmental
@@ -784,8 +791,8 @@ and the remaining source lines of the file are explained below:
a macro that evaluates to {\tt linewid} unless redefined, and the default
element length is {\tt elen\_}, which evaluates to
{\tt dimen\_*3/2} unless redefined.
- Setting {\tt linewid} to 2.0 as in the example means that the default element
- length becomes 3.0\,in.
+ Setting {\tt linewid} to $2.0$ as in the example means that the
+ default element length becomes $2.0 \times 3/2 = 3.0$\,in.
For resistors, the default length of the body is {\tt dimen\_/2,} and the
width is {\tt dimen\_/6.} All of these values can be customized.
Element scaling and the use of SI units is discussed further in
@@ -837,7 +844,7 @@ were added after the previously shown source:
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
+ 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.}
@@ -850,6 +857,46 @@ Two-terminal elements are shown in
Several are included more than once to illustrate
some of their arguments, which are listed in detail in \SR{defines}.
+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
+mechanism, as follows.
+
+The first argument of the macro
+\par
+{\tt reversed(`}{\sl macro name}{\tt',}{\sl macro arguments}{\tt )}
+\par
+\noindent
+is the name of a two-terminal element in quotes, followed by the
+element arguments. The element is drawn with reversed direction; thus,
+\par
+{\tt diode(right\_ 0.4); reversed(`diode',right\_ 0.4)}
+\par
+\noindent
+draws two diodes to the right, but the second one points left.
+
+%\pagebreak
+Similarly, the macro
+\par
+{\tt resized(}{\sl factor},`{\sl macro name}',{\sl macro arguments}{\tt )}
+\par
+\noindent
+will resize the body of an element by temporarily multiplying
+the {\tt dimen\_} macro by {\sl factor} but
+\Mfour\ primitives can be employed instead as follows:
+\par
+{\tt pushdef(`dimen\_',dimen\_*({\sl factor})),%
+{\sl macro name}({\sl arguments}) popdef(`dimen\_')}
+\par
+\noindent
+More general resizing should be
+done by redefining {\tt dimen\_} globally as described in \SR{Circuitscaling:}.
+%These two macros can be nested; the following scales the above example
+%by 1.8, for example
+%\par
+%{\tt resized(1.8,`diode',right\_ 0.4);}
+%{\tt resized(1.8,`reversed',`diode',right\_ 0.4)}
+
\enlargethispage{\baselineskip}
\FR{Resistors} shows some resistors with typical variants.
The first macro argument specifies the
@@ -922,12 +969,30 @@ More basic elements are in \FR{MoreTable}, and amplifiers in \FR{AmpTable}.
\label{AmpTable}
\end{figure}
+%\enlargethispage{\baselineskip}
+Diodes are shown in \FR{Diodes}.
+\begin{figure}[H]
+ \input DiodesMan
+ \caption{The macro {\tt
+ diode(\linespec, B|b|CR|D|L|LE[R]|P[R]|S|T|U|V|v|w|Z|{\sl chars}, [R][E])}.
+ Appending {\tt K} to the second argument draws an open arrowhead.}
+ \label{Diodes}
+ \end{figure}
+The arrows are drawn relative to the diode direction by the {\tt LE}
+option. For absolute arrow directions, one can
+define a wrapper (see \SR{Writing:}) for the {\tt diode} macro to draw arrows
+at 45 degrees, for example:
+\par
+{\tt define(`myLED',`diode(`\$1'); em\_arrows(N,45)
+ with .Tail at last [].ne')}
+
\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]
+\begin{figure}[hbt]
\input SourcesMan
- \caption{Sources and source-like elements.}
+ \caption{Sources and source-like elements. An argument of each
+ element allows customization such as shading.}
\label{Sources}
\end{figure}
As a convenience,
@@ -946,26 +1011,21 @@ and for power-system diagrams, macros
and
{\tt Ysymbol(at {\sl position, keys,} U|D|L|R|{\sl degrees})},
-\enlargethispage{\baselineskip}
-Diodes are shown in \FR{Diodes}.
-\begin{figure}[H]
- \input DiodesMan
- \caption{The macro {\tt
- diode(\linespec, B|b|CR|D|L|LE[R]|P[R]|S|T|U|V|v|w|Z|{\sl chars}, [R][E])}.
- Appending {\tt K} to the second argument draws an open arrowhead.}
- \label{Diodes}
+Fuses, breakers, and jumpers are in \FR{Fuses},
+and switches with numerous controls in \FR{Switches}.
+%Switches with numerous controls are in \FR{Switches},
+%and fuses, breakers, and jumpers in \FR{Fuses}.
+\begin{figure}[hbt]
+ \input FusesMan
+ \caption{Variations of the macros
+ {\tt fuse(\linespec, A|dA|B|C|D|E|S|HB|HC|SB, {\sl wid}, {\sl ht},
+ {\sl attributes}),}
+ {\tt cbreaker(\linespec,L|R,D|T|TS),}
+ and
+ {\tt jumper(\linespec,{\sl chars}|{\sl keys}).}}
+ \label{Fuses}
\end{figure}
-The arrows are drawn relative to the diode direction by the {\tt LE}
-option. For absolute arrow directions, one can
-define a wrapper (see \SR{Writing:}) for the {\tt diode} macro to draw arrows
-at 45 degrees, for example:
-\par
-{\tt define(`myLED',`diode(`\$1'); em\_arrows(N,45)
- with .Tail at last [].ne')}
-
-Switches with numerous controls are in \FR{Switches},
-and fuses, breakers, and jumpers in \FR{Fuses}.
-\begin{figure}[H]
+\begin{figure}[hbt]
\input SwitchesMan
\caption{The
{\tt switch(\linespec,L|R,{\sl chars},L|B|D,{\sl attribs})}
@@ -973,7 +1033,7 @@ and fuses, breakers, and jumpers in \FR{Fuses}.
{\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 {\sl chars,text})} shown.
+ {\tt dswitch(\linespec,R,W[ud]B {\sl chars,attributes})} 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.
@@ -981,55 +1041,8 @@ and fuses, breakers, and jumpers in \FR{Fuses}.
embellish switches in the bottom row.}
\label{Switches}
\end{figure}
-\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}),}
- {\tt cbreaker(\linespec,L|R,D|T|TS),}
- and
- {\tt jumper(\linespec,{\sl chars}|{\sl keys}).}}
- \label{Fuses}
- \end{figure}
-
-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
-mechanism, as follows.
-
-The first argument of the macro
-\par
-{\tt reversed(`}{\sl macro name}{\tt',}{\sl macro arguments}{\tt )}
-\par
-\noindent
-is the name of a two-terminal element in quotes, followed by the
-element arguments. The element is drawn with reversed direction; thus,
-\par
-{\tt diode(right\_ 0.4); reversed(`diode',right\_ 0.4)}
-\par
-\noindent
-draws two diodes to the right, but the second one points left.
-
-Similarly, the macro
-\par
-{\tt resized(}{\sl factor},`{\sl macro name}',{\sl macro arguments}{\tt )}
-\par
-\noindent
-will resize the body of an element by temporarily multiplying
-the {\tt dimen\_} macro by {\sl factor} but
-\Mfour\ primitives can be employed instead as follows:
-\par
-{\tt pushdef(`dimen\_',dimen\_*({\sl factor})),%
-{\sl macro name}({\sl arguments}) popdef(`dimen\_')}
-\par
-\noindent
-More general resizing should be
-done by redefining {\tt dimen\_} globally as described in \SR{Circuitscaling:}.
-%These two macros can be nested; the following scales the above example
-%by 1.8, for example
-%\par
-%{\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:}.
@@ -1044,6 +1057,7 @@ of which the {\tt E} and {\tt S} types may be either 2-terminal or as
\label{Arresters}
\end{figure}
+\enlargethispage{\baselineskip}
\FR{Variable} shows some two-terminal elements with
arrows or lines overlaid to indicate variability using the macro
\par
@@ -1075,7 +1089,6 @@ thus, the following line draws the third resistor in \FR{Variable}:
\label{Variable}
\end{figure}
-\pagebreak
\FR{Emarrows} contains radiation-effect arrows for embellishing two-terminal
and other macros.
\begin{figure}[H]
@@ -1165,9 +1178,10 @@ as math-mode strings, on the left side of the last {\tt []} block (or
the block named in the fifth argument if present) {\em with respect to
the current direction:} {\tt up, down, left, right.} The second macro
places the strings along the centre of the element, and the third along
-the right side. Labels beginning with {\tt sprintf} or a double quote
-are copied literally rather than assumed to be in math mode. A simple
-circuit example with labels is shown in \FR{Loop}.
+the right side. The fourth applies a displacement {\sl long, lat} with
+respect to the drawing direction. Labels beginning with {\tt sprintf}
+or a double quote are copied literally rather than assumed to be in
+math mode. A simple circuit example with labels is shown in \FR{Loop}.
\begin{figure}[H]
\vspace*{-\baselineskip}
\parbox{4in}{\small \verbatiminput{Loop.m4}}%
@@ -1197,7 +1211,6 @@ are required to place the element as in the following example:
\par
{\tt resistor(from (1,1) to (2,1))}.
-\noindent
However, \pic has a very useful concept of the current point (explicitly
named {\tt Here}); thus,
\par
@@ -1257,7 +1270,7 @@ The macro {\tt eleminit\_} in the two-terminal elements invokes
to establish element length and direction.
As shown in \FR{Oblique},
-\begin{figure}[H]
+\begin{figure}[hbt]
\vspace{-\baselineskip}
\parbox{4.5in}{\small \verbatiminput{Oblique.m4}}%
\hfill\raise-0.7in\llap{\hbox{\input Oblique }}%
@@ -1388,9 +1401,12 @@ not change the drawing direction.
\xection{Composite circuit elements\label{Composite:}}
Many basic elements are not two-terminal. These elements are usually enclosed in
a \verb|[ ]| \pic block, and contain named interior locations and components.
-The block must be placed by using its compass corners, thus:
+Nearly all elements drawn within blocks can be customized by adding an
+extra argument, which is executed as the last item within the block.
+By default, a block is placed as if it were a box; otherwise,
+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:
+or, when the block contains predefined locations, 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.
@@ -1398,25 +1414,22 @@ A few macros are positioned with the first argument;
the {\tt ground} macro, for example:
{\tt ground(}{\tt at} {\sl position}{\tt ).}
-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.
+\enlargethispage{\baselineskip}
+\FR{QTrans} illustrates the adaptation of file {\tt quick.m4} to
+include a transformer, a composite element described in detail below,
+followed by code for the figure.
\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.}
+% \parbox{4in}{\small \verbatiminput{QTrans.m4}}%
+% \hspace*{-0.45in}\raise-0.15in\hbox{\input QTrans }
+% \vspace*{-\baselineskip}
+ \input Qtrans
+ \caption{The file {\tt quick.m4} modified to include a composite
+ element, the transformer, which is positioned by placing an
+ internal point.}
+% transformer, of which the length and orientation of connectors
+% is given by the first argument, and which is positioned in this
+% example by placing the internal position {\sl P1.}}
\label{QTrans}
\end{figure}
@@ -1443,6 +1456,11 @@ puts dots at opposite ends.
\label{Xform}
\end{figure}
+The code for \FR{QTrans} is reproduced in the following.
+Label {\sl Vs} has been added for later reference.
+The transformer is positioned by placing internal position {\sl P1.}
+\verbatiminput{QTrans.m4}
+
The macro {\tt
potentiometer(\linespec,{\sl cycles},{\sl fractional pos},{\sl length},
$\ldots$)},
@@ -1457,6 +1475,7 @@ direction.
\label{Potentiometers}
\end{figure}
+\pagebreak
The macro {\tt
addtaps([{\sl arrowhd} | type={\sl arrowhd};name={\sl Name}],
{\sl fraction, length, fraction, length,}
@@ -1482,7 +1501,6 @@ 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]
@@ -1495,15 +1513,17 @@ 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:
-\par
-{\tt move to (1.5,2); ground
-\par
-ground(at (1.5,2)) }
-
+The first argument specifies position; for example,
+{\tt ground(at (1.5,2))} has the same effect as
+{\tt move to (1.5,2); ground.}
+%The first argument specifies position; for example, the two lines shown
+%have identical effect:
+%\par
+%{\tt move to (1.5,2); ground
+%\par
+%ground(at (1.5,2)) }
The second argument truncates
the stem, and the third defines the symbol type.
The fourth argument specifies the angle at which the symbol is drawn,
@@ -1532,8 +1552,8 @@ shown in \FR{Antennas} are similar to those of {\tt ground}.
\label{Antennas}
\end{figure}
-\FR{Opamp} illustrates the macro
-{\tt opamp({\sl\linespec, - label, + label, size, chars})\label{OPAMP}}.
+\FR{Opamp} illustrates the macro {\tt
+ opamp({\sl\linespec, - label, + label, size, chars, attributes})\label{OPAMP}}.
\begin{figure}[H]
\input OpampMan
\caption{Operational amplifiers. The {\tt P} option adds
@@ -1577,12 +1597,13 @@ with predefined internal locations as shown.
\begin{figure}[H]
\input AudioMan
\caption{Audio components:
- {\tt speaker(U|D|L|R|{\sl degrees},{\sl size},{\sl type}),
+ {\tt speaker(U|D|L|R|{\sl degrees},{\sl size},{\sl type},{\sl attributes}),
bell, microphone, buzzer,
earphone}, with their internally named positions and components.}
\label{Audio}
\end{figure}
-The first argument specifies the device orientation.
+The first argument specifies the device orientation. The fourth can add
+fill or line attributes.
Thus,
\par
{\tt S: speaker(U) with .In2 at Here}
@@ -1591,7 +1612,7 @@ Thus,
places an upward-facing speaker with input {\sl In2} at the
current location.
-
+\pagebreak
The {\tt nport({\sl box specs {\tt[;} other commands{\tt]},
nw, nn, ne, ns, space ratio, pin lgth, style})}
macro is shown in \FR{Nport}.
@@ -1602,7 +1623,6 @@ 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,
@@ -1651,6 +1671,7 @@ The above example and the related gyrator macro are illustrated in
\label{NLG}
\end{figure}
+\pagebreak
\FR{Contact} shows the macro {\tt contact({\sl chars})},
which contains predefined locations {\sl P, C, O}
for the armature and normally closed and normally
@@ -1665,7 +1686,6 @@ An {\tt I} in the first argument draws open circles for contacts.
\label{Contact}
\end{figure}
-\pagebreak
The {\tt contacts({\sl poles, chars})} macro in \FR{Contacts}
draws multiple contacts.
\begin{figure}[H]
@@ -1686,13 +1706,14 @@ actuator types.
\label{relaycoil}
\end{figure}
+\pagebreak
The {\tt relay} macro in \FR{Relay}
defines coil terminals {\sl V1, V2} and contact
terminals {\sl P$_i$, C$_i$, O$_i$.}
\begin{figure}[H]
\input RelayMan
\vspace{-1ex}
- \caption{The {\tt relay({\sl poles, chars})}
+ \caption{The {\tt relay({\sl poles, chars, attributes})}
macro (drawing direction right).}
\label{Relay}
\end{figure}
@@ -1707,7 +1728,6 @@ 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.
@@ -1720,6 +1740,7 @@ The first argument of both macros establishes the drawing direction.
\label{Jack}
\end{figure}
\noindent%
+\enlargethispage{\baselineskip}
The second argument is a string of characters defining drawn components.
An {\tt R} in the string specifies a
right orientation with respect to the drawing direction.
@@ -1741,8 +1762,11 @@ A macro for drawing headers is in \FR{Headers}.
\end{figure}
Some 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.
+The {\tt tstrip} macro allows keys
+ {\tt wid={\sl{}value};}
+ {\tt ht={\sl{}value};} and
+ {\tt box={\sl{}attributes};}
+ in argument 3 for width, height, and e.g., fill, color, or dashed.
\begin{figure}[H]
\input ConnMan
\caption{Macros {\tt tstrip(R|L|U|D|{\sl degrees}, {\sl chars})},
@@ -1765,7 +1789,7 @@ 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]
- \vspace*{-\baselineskip}%
+% \vspace*{-\baselineskip}%
\input WindingsMan
\caption{The {\tt winding(L|R, diam, pitch, turns, core wid, core color)}
macro draws a coil with axis along the current drawing direction.
@@ -1774,6 +1798,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)}
@@ -1794,7 +1819,6 @@ 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
@@ -1828,6 +1852,7 @@ 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]
@@ -1868,6 +1893,7 @@ 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}.
+\pagebreak
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}.
@@ -1919,6 +1945,7 @@ 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
@@ -1983,6 +2010,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
@@ -2016,16 +2044,19 @@ which evaluates {\sl actions} and increments counter {\tt m4Lx}
for each instance of {\sl variable} set to {\sl value1, value2, $\ldots$}
\xection{Logic gates\label{Logicgates:}}
-\FR{Logic} shows the basic logic gates included in
-library {\tt liblog.m4}.
-The first argument of the gate macros can be an integer $N$ from $0$ to $16,$
-specifying the number of input
-locations {\tt In1,} $\ldots$ {\tt In}$N,$ as illustrated for
-the NOR gate in the figure.
-By default, $N=2$ except for macros {\tt NOT\_gate} and {\tt BUFFER\_gate},
-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.
+Library {\tt liblog.m4} contains a selection of basic and advanced logic
+gates and structures. The default size and style parameters defined
+near the top of the file can be globally redefined or temporarily set
+locally. Individual gates also have arguments that allow adjustment of
+size, and fill, for example.
+
+\FR{Logic} shows the basic logic gates. The first argument of the gate
+macros can be an integer $N$ from $0$ to $16,$ specifying the number
+of input locations {\tt In1,} $\ldots$ {\tt In}$N,$ as illustrated
+for the NOR gate in the figure. By default, $N=2$ except for macros
+{\tt NOT\_gate} and {\tt BUFFER\_gate}, 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
@@ -2049,6 +2080,7 @@ 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]
@@ -2376,7 +2408,6 @@ which executes the given actions successively with
\label{sampleIC}}%
\end{figure}
-%\pagebreak
\xection{Single-line diagrams\label{SingleLine:}}
\input SLDsMan
Standard single-line diagrams for power distribution employ many of
@@ -2733,7 +2764,7 @@ can be defined as shown in \FR{Thermal}.
\label{Thermal}
\end{figure}
-\enlargethispage{\baselineskip}
+\pagebreak
\Example{2}
In the following,
two macros are defined to simplify the repeated drawing
@@ -2800,7 +2831,6 @@ define(`hybrid_PI_BJT',
`$2' ] ')
\end{verbatim}
-\pagebreak
\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,
@@ -2822,6 +2852,7 @@ $3,$4,$5)')
\label{Sinus}
\end{figure}
+\pagebreak
\Example{5}
Repeated subcircuits might appear only
as the subcircuit and its mirror image, for example, so the
@@ -3398,8 +3429,8 @@ invoked in the outermost scope of a pic diagram, and the
\xection{Web documents, {\ttfamily pdf}, and alternative output formats%
\label{Alternative:}}
-Circuit diagrams contain graphics and symbols, and the issues related to
-web publishing are similar to those for other mathematical documents.
+The issues related to web publishing are similar to those for other
+documents containing both graphics and text.
Here the important factor is that \gpic\ {\tt -t} generates output
containing \tpic \verb|\special| commands, which must be converted
to the desired output, whereas \dpic can generate several alternative
@@ -3465,30 +3496,30 @@ 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.
-\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
-the tedious coordinate calculations required by the \latex
-picture objects that I was then using. The \pic\ language seemed to be a
-good fit for this purpose, and I took a few days off to write a \pic-like
-interpreter (\dpic). The macros in this distribution and the interpreter
-are the result of that effort, drawings I have had to produce since,
-and suggestions received from others. The interpreter has been upgraded
-over time to generate \mfpic, \MetaPost~\cite{metapost,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.
+available for creating line diagrams in \latex, I wished to eliminate the
+tedious coordinate calculations required by the \latex picture objects
+that I was then using. The \pic\ language seemed to be a good fit for
+this purpose, and I took a few days off to write a \pic-like interpreter
+(\dpic). The macros in this distribution and the interpreter are
+the result of that effort, drawings I have had to produce since, and
+suggestions received from others. The emphasis throughout has been to
+produce a few types of diagrams well rather than attempting to satisfy
+the needs of everyone.
+
+\Dpic has been upgraded 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.
The simple \pic\ language is but one of many available tools for creating
line graphics. Consequently, the main value of this distribution
@@ -3536,13 +3567,12 @@ Similarly, the SVG output can be read directly by the Inkscape graphics
editor, but SVG can also be used directly for web pages.
\Dpic will also generate low-level \MetaPost or \Postscript code, so
that diagrams defined using \pic can be manipulated and combined with
-others. The \Postscript output can be imported into
-CorelDraw
-%\Textregistered
-and Adobe Illustrator
-%\Textregistered
-for further processing.
-With raw \Postscript, \PDF, and \SVG output, the user is
+others.
+I learned to great benefit that the \Postscript output can be imported into
+CorelDraw and Adobe Illustrator for further processing,
+so that detailed diagram components produced by pic program can be combined
+with effects best acheived using a wysiwyg drawing program.
+With raw \Postscript, \PDF, and \SVG output however, the user is
responsible for ensuring that the correct fonts are provided and for
formatting the text.
@@ -3899,7 +3929,6 @@ 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