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.tex480
1 files changed, 339 insertions, 141 deletions
diff --git a/graphics/circuit_macros/doc/body.tex b/graphics/circuit_macros/doc/body.tex
index 0acc9dc2ec..c7c7b2bc6b 100644
--- a/graphics/circuit_macros/doc/body.tex
+++ b/graphics/circuit_macros/doc/body.tex
@@ -35,6 +35,7 @@
\newcommand{\PR}[1]{\hyperref[#1]{page~\pageref*{#1}}}
\newcommand{\FR}[1]{\hyperref[#1]{Figure~\ref*{#1}}}
\newcommand{\FRS}[1]{\hyperref[#1]{Figures~\ref*{#1}}}
+\newcommand{\MR}[2]{\hyperref[#1]{#2}}
\newcommand{\REF}[1]{\hyperref[#1]{\ref*{#1}}}
\newcommand{\LQ}{\char96}
\newcommand{\RQ}{\char39}
@@ -72,7 +73,8 @@ 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
-combinations of them for particular drawings.
+combinations of them for particular drawings,
+a process for which \Mfour\ and \pic\ are well suited.
\xection{Using the macros\label{Using:}}
This section describes the basic process of adding circuit diagrams to
@@ -121,7 +123,7 @@ The contents of file {\tt quick.m4} and resulting diagram are shown in
% to show several ways for placing circuit elements,
%and to provide sufficient information for producing
and the production of basic labeled circuits.
-\begin{figure}[h!]
+\begin{figure}[ht]
\parbox{\textwidth}{\small\verbatiminput{quick.m4}}%
\hfill\llap{\raise-1.15in\hbox{\input quick }}%
% \hfill\llap{\raise-1.15in\hbox{\pdftooltip{\input quick }%
@@ -856,25 +858,26 @@ were added after the previously shown source:
\end{itemize}
\subsection{The two-terminal elements\label{Twoterminal:}}
-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
+Two-terminal elements are shown in
+\FRS{Resistors} to~\REF{Switches} and part of~\FR{Arresters}.
+Several are included more than once to illustrate
some of their arguments, which are listed in detail in \SR{defines}.
+
+\enlargethispage{\baselineskip}
\FR{Resistors} shows some resistors with typical variants.
-\begin{figure}[h!]
+The first macro argument specifies the
+\begin{figure}[H]
\input ResistorsMan
- \caption{Resistors dawn by the macro
+ \caption{Resistors drawn 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
-the invisible line segment along which the element is drawn.
+ \end{figure}
+\noindent%
+invisible line segment along which the element is drawn.
If the argument is blank,
the element is drawn from the current position in the current drawing
direction along a default length.
@@ -890,7 +893,6 @@ vertices per side.
The macro {\tt up\_} evaluates to {\tt up} but also resets the current
directional parameters to point up.
-\pagebreak
Capacitors are illustrated in \FR{Capacitors}.
See \SR{Composite:} for the {\tt variable} macro.
\begin{figure}[h!t]
@@ -935,7 +937,7 @@ to draw a single cycle of a sinusoid or approximate sinusoid.
\end{figure}
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
+ [n:][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:
\par
@@ -949,24 +951,16 @@ and for power-system diagrams, macros
and
{\tt Ysymbol(at {\sl position, keys,} U|D|L|R|{\sl degrees})},
-\pagebreak
-Diodes and fuses are shown in \FRS{Diodes} and \REF{Fuses}.
-\begin{figure}[h!]
+%Diodes and fuses are shown in \FRS{Diodes} and \REF{Fuses}.
+Diodes are shown in \FR{Diodes}.
+\begin{figure}[h!t]
\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])}.
+ \caption{The macro {\tt
+ diode(\linespec, 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}
-\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}
-\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
@@ -999,9 +993,39 @@ by 1.8, for example
{\tt resized(1.8,`diode',right\_ 0.4);}
{\tt resized(1.8,`reversed',`diode',right\_ 0.4)}
+Fuses are shown in \FR{Fuses}
+and switches with numerous controls in \FR{Switches}.
+\begin{figure}[h!t]
+ \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}
+
+%\enlargethispage{\baselineskip}%
+\begin{figure}[h!t]
+%\vspace*{-\baselineskip}
+ \input SwitchesMan
+ \caption{The
+ {\tt switch(\linespec,L|R,{\sl chars},L|B|D,{\sl attribs})}
+ 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 {\sl chars,text})} 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 bottom row.}
+ \label{Switches}
+ \end{figure}
+
+\pagebreak
\FR{Emarrows} contains radiation-effect arrows for embellishing two-terminal
and other macros.
-\begin{figure}[h!]
+\begin{figure}[h!t]
\input EmarrowsMan
\caption{Radiation arrows: {\tt em\_arrows({\sl type, angle, length})}}
\label{Emarrows}
@@ -1019,29 +1043,10 @@ 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!]
+\begin{figure}[ht]
\input ArrestersMan
\caption{Variations of the {\tt arrester({\sl linespec, chars,}
{\sl wid}[{\tt :}{\sl arrowhead ht}],
@@ -1278,7 +1283,6 @@ 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
@@ -1392,7 +1396,6 @@ 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},
@@ -1454,7 +1457,6 @@ have identical effect:
\par
ground(at (1.5,2)) }
-%\noindent
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,
@@ -1518,12 +1520,12 @@ The code in \FR{opampex} places an opamp with three connections.
\begin{figure}[h!b]
\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{opampex}
\end{figure}
+\pagebreak
\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.}
@@ -1638,18 +1640,17 @@ An {\tt I} in the first argument draws open circles for contacts.
\begin{figure}[ht]
% \ifpdf\vspace*{-\baselineskip}\else\vspace*{-0.5\baselineskip}\fi%
\input ContactMan
- \vspace{-1ex}
\caption{The {\tt contact({\sl chars})}
macro (default drawing direction right)
- can be used alone, in a set of ganged contacts, or in relays.}
+ can be used alone, in a set of ganged contacts, or in relays.}%
\label{Contact}
\end{figure}
+\pagebreak
The {\tt contacts({\sl poles, chars})} macro in \FR{Contacts}
draws multiple contacts.
-\begin{figure}[ht]
+\begin{figure}[h!t]
\input ContactsMan
- \vspace{-1ex}
\caption{The {\tt contacts({\sl poles, chars})}
macro (drawing direction right).}
\label{Contacts}
@@ -1659,7 +1660,6 @@ 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%
@@ -1682,8 +1682,8 @@ 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}[!ht]
+The first
+\begin{figure}[H]
\input JackMan
\vspace{-1ex}
\caption{The {\tt jack(U|D|L|R|{\sl degrees}, {\sl chars})}
@@ -1691,6 +1691,8 @@ The first argument of both macros establishes the drawing direction.
and their defined points.}
\label{Jack}
\end{figure}
+\noindent%
+argument of both macros establishes the drawing direction.
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.
@@ -1703,16 +1705,16 @@ The first argument of both macros establishes the drawing direction.
or {\tt S[M|B]} substrings add auxiliary contacts with
specified make or break points.
-A macro for drawing headers is in \FR{Headers},
-and some experimental connectors are shown in \FR{Conn} and \FR{Pconn}.
+A macro for drawing headers is in \FR{Headers}.
+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.
-\begin{figure}[h!b]
+\begin{figure}[h!t]
\input HeadersMan
\caption{Macro {\tt Header(1|2, {\sl rows, wid, ht, type})}.}
\label{Headers}
\end{figure}
-\begin{figure}[h!b]
+\begin{figure}[h!t]
\input ConnMan
\caption{Macros {\tt tstrip(R|L|U|D|{\sl degrees}, {\sl chars})},
{\tt ccoax(at} {\sl location}, {\tt M|F, {\sl diameter})},
@@ -1720,8 +1722,7 @@ for width and height.
{\tt tbox({\sl text, wid, ht}, <|>|<>,{\sl type})}. }
\label{Conn}
\end{figure}
-
-\begin{figure}[ht]
+\begin{figure}[h!t]
\input PconnMan
\caption{A small set of power connectors drawn by
{\tt pconnex(R|L|U|D|}{\sl degrees, chars}{\tt)}. Each connector has
@@ -1733,7 +1734,7 @@ 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!t]
- \ifpdf{\vspace*{-1ex}}\fi%
+% \ifpdf{\vspace*{-1ex}}\fi%
\input NPDTMan
\caption{Multipole double-throw switches drawn by
{\tt NPDT({\sl npoles}, [R])}.}
@@ -1821,9 +1822,7 @@ and {\sl E} is shown in \FR{ujt}.
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%
+\begin{figure}[H]
\input thyristorMan
\vspace*{-1ex}
\caption{The top two rows illustrate use of the
@@ -1834,10 +1833,11 @@ 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}
+Except for the {\sl G} terminal, a thyristor (the {\tt IEC} variant excluded)
is much like a two-terminal element. The wrapper macro
{\tt scr({\sl linespec, chars, label})} and similar macros
-{\tt scs, sus,} and {\tt sbs} place thyristors
-using {\sl linespec} as for a two-terminal element,
+{\tt scs, sus,} and {\tt sbs}
+place thyristors using {\sl linespec} as for a two-terminal element,
but require a third argument for the label for the compound block; thus,
{\tt scr(from A to B,{,}Q3); line right from Q3.G}
@@ -1851,6 +1851,7 @@ 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]
+\vspace*{-\baselineskip}
\input fetMan
\caption{JFET, insulated-gate enhancement and depletion MOSFETs,
simplified versions, graphene, and ferroelectric fets.
@@ -1879,15 +1880,15 @@ temporarily for compatibility.
This system allows considerable freedom in choosing or customizing components,
as illustrated in \FR{fet}.
+\enlargethispage{\baselineskip}
The number of possible semiconductor symbols is very
large, so these macros must be regarded as prototypes.
-Often an element is a minor modification of existing elements. For example,
-the {\tt thyristor(\linespec, {\sl chars})} macro illustrated in
-\FR{thyristor} is derived from the diode and bipolar transistor macros.
+Often an element is a minor modification of existing elements.
+The {\tt thyristor(\linespec, {\sl chars})} macro in
+\FR{thyristor} is derived from diode and bipolar transistor macros.
Another example is the {\tt tgate} macro shown in \FR{Tgate}, which
also shows a pass transistor.
-\begin{figure}[h!t]
-% \ifpdf\vspace*{-\baselineskip}\fi%
+\begin{figure}[H]
\input TgateMan
\caption{The {\tt tgate({\sl linespec,} [B][R|L])} element, derived from
a customized diode and {\tt ebox}, and the
@@ -1962,7 +1963,6 @@ 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
@@ -2140,6 +2140,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.
+\pagebreak
\FR{Multiplexer} shows a multiplexer block with variations, and
\FR{Demultiplexer} shows
the very similar demultiplexer.
@@ -2155,7 +2156,6 @@ 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}.
@@ -2235,6 +2235,182 @@ 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.
+\xection{Single-line diagrams\label{SingleLine:}}
+\input SLDsMan
+ Standard single-line diagrams for power distribution employ many of
+ the normal two-terminal elements along with others that are unique to
+ the context. This distribution contains a library of draft single-line
+ diagram (SLD) elements that can be loaded with the
+ command {\tt include(libSLD.m4)}.
+ The {\tt examples.pdf} and {\tt examplesSVG.html}
+ documents include samplers of some of their uses.
+
+ Writing macros for special elements is always an option but the SLD
+ macros allow considerable scope for customization. Diagram-wide
+ or block-scope changes are made by redefining
+ environmental variables, particularly
+ {\tt linethick,} for example, and {\tt linewidth} for scaling.
+ Element body sizes are altered using, for example,
+ {\tt define(`dimen\_',dimen\_*1.2)} as for the normal circuit elements.
+ To apply such a change to a single element, use
+ {\tt pushdef(`dimen\_',{\sl expr})} {\sl element statements}
+ {\tt popdef(`dimen\_').}
+The SLD library also includes a number of redefinable default
+style parameters, which are currently:
+\begin{verbatim}
+define(`sl_breakersize_',`dimen_*3/16') # breaker box size
+define(`sl_breakersep_',`dimen_/2') # breaker separation from body
+define(`sl_ttboxlen_',`dimen_*3/4') # inline box length
+define(`sl_ttboxwid_',`dimen_*3/4') # inline box width
+define(`sl_sboxlen_',`dimen_*2/3') # stem box length
+define(`sl_sboxwid_',`dimen_*2/3') # stem box wid
+define(`sl_diskdia_',`dimen_*2/3') # sl_disk diam
+define(`sl_chevronsiz_',`dimen_/4') # sl_drawout (chevron) size
+define(`sl_loadwid_',`dimen_*0.32') # load width
+define(`sl_loadlen_',`dimen_*0.45') # load length
+define(`sl_transcale_',1) # transformer body scale factor
+define(`sl_busthick_',linethick*2) # sl_bus line thickness
+define(`sl_busindent_',`min(dimen_/5,rp_len/5)') # bus end extension
+\end{verbatim}
+
+ The macros also allow for extensive customization of individual
+ elements using a key-value mechanism.
+ The greatest control of appearance is obtained by drawing all
+ elements individually; however,
+ provision is made for automatically attaching circuit breakers
+ and other symbols to elements.
+
+\subsection{Two-terminal SLD elements\label{TwoTermSLD:}}
+The two-terminal SLD elements are drawn along an invisible line segment
+that can be named as for normal two-terminal elements.
+There are four arguments for which defaults are provided as always.
+The transformers are shown in \FR{SLDTransformers} and other two-terminal
+elements in \FR{SLDTwoTerms}.
+\begin{figure}[h!t]
+ \SLDTransformers
+ \caption{The SLD draft transformers
+ drawn by {\tt sl\_transformer({\sl linespec, key-value pairs,
+ stem object, stem object, type {\tt S} circle object,
+ type {\tt S} circle object})},
+ drawing direction {\tt up\_}.}
+ \label{SLDTransformers}
+ \end{figure}
+
+The first argument is the linespec defining the direction and location
+of the element, e.g.,
+{\tt sl\_transformer(right\_ {\sl expr}).}
+\begin{figure}[h!t]
+ \SLDTwoTerms
+ \caption{SLD two-terminal elements, drawing direction {\tt right\_}.}
+ \label{SLDTwoTerms}
+ \end{figure}
+
+The second argument is a sequence of semicolon (;)-separated key-value
+pairs that customize the element body, depending on the case, e.g.,
+{\tt sl\_ttbox(,lgth={\sl expr}; wdth={\sl expr};
+ text="{\sl internal label}"; box=shaded~"yellow").}
+
+If the third argument is blank, then a plain input stem is drawn for the
+element.
+If it is a {\tt C} then a default closed
+breaker is inserted and an {\tt O} inserts a default open breaker,
+and similarly an {\tt X} or slash ({\tt/}) add these elements.
+If it or its prefix is {\tt S:} or {\tt S$n$:} where $n$ is an integer,
+then, instead of a breaker,
+an $n$-line slash symbol is drawn using the macro
+{\tt sl\_slash(at {\sl position, keys,} [$n$:]R|L|U|D|{\sl degrees}).}
+
+Otherwise, one or more of the extensive {\tt sl\_ttbox} body
+key-value pairs will insert a custom breaker as needed. These keys include:
+{\tt lgth={\sl expr},
+wdth={\sl expr},
+name={\sl Name},
+text="{\sl text}",
+box={\sl other box attributes, e.g., {\tt dashed, shaded,} $\ldots$}.}
+For the slash symbol, the {\tt sl\_slash} keys are valid.
+
+The fourth argument is like the third but controls a breaker or slash
+symbol in the output
+lead. The example, {\tt sl\_transformer(right\_ elen\_ from A,,C,C)}
+draws a transformer with closed breakers in the input and output leads.
+
+Exception are the {\tt sl\_drawout()} element which does not have breakers
+and the {\tt transformer()} element which has an extra two arguments for
+the frequently used {\tt S} variant.
+
+The body can be given a name with {\tt name={\sl Label};} in the
+second argument. The default two-terminal name is {\sl Body}
+except for the {\tt sl\_breaker} element which has default body name {\sl Br}
+and the {\tt sl\_slash} element which has default name {\sl SL}.
+Annotations can be added by writing {\tt "{\sl text}" at {\sl
+position}} as always, but there are other ways. One alternative is to
+use, for example, {\tt llabel({\sl text, text, text, position, name})}
+as usual. However, this macro positions text by default with respect
+to {\tt last []} which normally will be incorrect if breakers are
+automatically included with the element.
+In the latter case, enter the element body name as the fifth argument
+of {\tt llabel()}.
+For example, {\tt B: sl\_ttbox} creates an element of which
+the invisible centre line has name {\sl B} and the body has name {\sl Body,}
+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.
+
+\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.
+SLD generators are shown in \FR{SLDGenerators}, other
+one-terminal elements in \FR{SLDOneTerms}.
+\begin{figure}[h!t]
+ \SLDGenerators
+ \caption{SLD generators, drawing direction {\tt up\_}.}
+ \label{SLDGenerators}
+ \end{figure}
+\begin{figure}[h!t]
+ \SLDOneTerms
+ \caption{SLD one-terminal elements, drawing direction {\tt up\_}.}
+ \label{SLDOneTerms}
+ \end{figure}
+There are three arguments, as follows.
+
+The first argument is a linespec which defines the location and drawing
+direction of the element stem.
+The second argument is a sequence of semicolon-separated key-value pairs
+as necessary to customize and name the element head, of which the
+default name is {\sl Head}.
+The third argument controls the presence and type of the object in the stem
+as for the two-terminal element breakers. The default breaker name is {\sl Br}
+and the default slash name is {\sl SL.}
+
+A stem of zero length is allowed when only the element head is needed.
+Because a line segment of zero length has undefined direction, the
+first argument must be one of {\tt U, D, L, R} (for up, down, left, right)
+or a number to set the direction in degrees, optionally followed by
+{\tt at {\sl position}} to set the position ({\tt Here} by default).
+For example, {\tt sl\_box(45 at Here+(1,0))}.
+
+The macros {\tt sl\_busbar({\sl linespec, np, keys})} and
+{\tt sl\_ct({\sl keys}),}
+shown in \FR{SLDComposite},
+are composite; that is, they are {\tt [ ]} blocks with defined
+internal positions. For {\tt sl\_busbar}, these are
+{\sl Start, End,} and
+{\sl P1, P2, $\ldots$ Pnp} where {\sl np} is the value of the
+second argument.
+\begin{figure}[h!t]
+ \SLDComposite
+ \caption{The {\tt sl\_busbar()} and two variants of {\tt sl\_ct}.}
+ \label{SLDComposite}
+ \end{figure}
+
+For example, the line
+\par
+{\tt line right\_ 3cm\_\_; sl\_busbar(up\_ 4.5cm\_\_,5) with .P3 at Here}
+\vspace*{\parsep}
+\par
+\noindent%
+ draws a vertical busbar at the end of a horizontal line.
+
\xection{Element and diagram scaling\label{Scaling:}}
There are several issues related to scale changes. You may wish to use
@@ -2380,9 +2556,9 @@ Custom two-terminal elements can often be defined by writing a wrapper
for an existing element. For example, an enclosed thermal switch
can be defined as shown in \FR{Thermal}.
\begin{figure}[ht]
- \parbox{4.2in}{\tt define(`thermalsw',\hfill\break
+ \parbox{5in}{\tt define(`thermalsw',\hfill\break
\hbox{}\space`dswitch(`\$1',`\$2',WDdBTh)\hfill\break
- \hbox{}\space\space circle rad distance(M4T,last line.c)
+ \hbox{}\space\space circle rad distance(last [].T,last line.c)
at last line.c ') }%
\hfill\raise-0.15in\hbox{\input Thermal }
\caption{A custom thermal switch defined from the {\tt dswitch} macro.}
@@ -2404,7 +2580,6 @@ a subcircuit that is replicated several times to generate \FR{Tline}.
\end{figure}
\Example{3}
-%\par\noindent {\bf Example 3:}
\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
@@ -2618,40 +2793,69 @@ 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
+parameters are entered using keys. Two macros assist this process.
+The first is
-{\tt setkey\_({\sl string, key, default value, }[N])}
+{\tt pushkey\_({\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
+%The first argument is a sequence of terms of the form
+%{\tt {\sl key}={\sl value}}.
+%The terms are separated by semicolon (;) characters.
+For example in a macro, the line
-{\tt setkey\_( `\$2', wdth, dimen\_*2 )}
+{\tt pushkey\_( `\$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 would be required if
-{\tt m4wdth} were to be non-numeric.
+checks macro argument 2 for the substring {\tt wdth=}{\sl expression}
+and, if found, defines the macro {\tt m4wdth}, using {\tt pushdef()},
+to equal {\tt ({\sl expression})}; if the substring is not found, {\tt
+m4wdth} is given the default value {\tt (dimen\_*2).} The enclosing
+parentheses are omitted if the fourth argument of {\tt pushkey\_} is
+nonblank as would be required if {\tt m4wdth} were to be non-numeric.
+Argument 1 can contain several such substrings separated by semicolons.
In addition, the macro
-{\tt setkeys\_({\sl string, keysequence})}
+{\tt pushkeys\_({\sl string, keysequence})}
\noindent
-applies {\tt setkey\_()} multiple times to its {\sl keysequence}
+applies {\tt pushkey\_()} 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.
+Each term of the second argument consists of the rightmost three
+arguments of {\tt pushkey\_} separated by the colons (:) rather than commas.
+
+%For example, suppose that a macro contains the line
+%
+%{\tt pushkeys\_(`\$1', wdth:dimen\_/2; type::N)}
+%
+%\noindent
+%and is invoked as {\tt {\sl macro}(type=Basic;wdth=0.2, $\ldots$)}.
+%The first argument is scanned, resulting in
+%{\tt m4wdth} defined to be
+%{\tt (0.2)} and {\tt m4type} to be {\tt Basic}.
+
+The macros {\tt setkey\_()} and {\tt setkeys\_()} are similar to
+{\tt pushkey\_()} and {\tt pushkeys\_()} respectively but use the
+m4 {\tt define} command rather than {\tt pushdef}.
+
+For example, the macro
+{\tt sarrow({\sl linespec}, {\sl keys})}
+can generate the custom arrows shown below the three native arrows
+in \FR{arrowex}. The defined keys are
+ {\tt type=}; {\tt lgth=}; {\tt wdth=}; {\tt shaft=}; and {\tt head=}.
+Many variations of these arrowheads are possible.
+\begin{figure}[h!t]
+ \input arrowex
+ \caption{The three \dpic native arrows and others generated by
+ {\tt sarrow({\sl linespec}, {\sl keys})}.}
+ \label{arrowex}
+ \end{figure}
-For example, consider the elementary example of a custom box macro:
+As another example, consider the elementary example of a custom box macro:
\begin{verbatim}
define(`custombox',
-`setkeys_(`$1',wdth:boxwid:; hgt:boxht:; label::N; text::N)
+`pushkeys_(`$1',wdth:boxwid:; hgt:boxht:; label::N; text::N)
ifelse(m4label,,,m4label:) box wid m4wdth ht m4hgt "m4text" ')
\end{verbatim}
@@ -2666,21 +2870,6 @@ 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')}.
-%\iffalse
-As another example, the macro
-{\tt sarrow({\sl linespec}, {\sl keys})}
-can generate the custom arrows shown below the three native arrows
-in \FR{arrowex}. The defined keys are
- {\tt type=}; {\tt lgth=}; {\tt wdth=}; {\tt shaft=}; and {\tt head=}.
-Many variations of these arrowheads are possible.
-\begin{figure}[h!t]
- \input arrowex
- \caption{The three \dpic native arrows and others generated by
- {\tt sarrow({\sl linespec}, {\sl keys})}.}
- \label{arrowex}
- \end{figure}
-%\fi
-
\xection{Interaction with \latex\label{Interaction:}}
The sizes of typeset labels and other \tex boxes are generally unknown
@@ -2846,6 +3035,7 @@ the {\tt ifpstricks} macro in the second line of the diagram source) are
\hbox{}
+\pagebreak
Objects can be taylored to their attached text by invoking
\verb|\boxdims| and \verb|boxdim| explicitly.
The small source file in \FR{boxdims}, for example,
@@ -2931,10 +3121,13 @@ the rotation of text by \PSTricks postprocessing is illustrated by the file
which contains both horizontal text and text rotated $90^\circ$ along the
vertical line.
This rotation of text is also implemented by the macro
-{\tt rs\_box}, which is similar
+{\tt rs\_boxs([angle={\sl expr};] {\sl text}[,{\sl expr, expr $\ldots$}])},
+which is similar
to {\tt s\_box} but rotates its argument by~$90^\circ,$ a default angle
that can be changed by preceding invocation with
-\verb|define(`text_ang',|{\sl degrees}{\tt )}. The {\tt rs\_box} macro
+\verb|define(`text_ang',|{\sl degrees}{\tt )}
+or by starting the first argument with {\tt angle={\sl expr};}.
+The {\tt rs\_box} macro
requires either \PSTricks or \TPGF and, like {\tt s\_box}, it calculates the
size of the resulting text box but requires the diagram to be
processed twice.
@@ -3097,14 +3290,15 @@ 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:}}
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
+write a \pic-like interpreter (\dpic) to eliminate the tedious coordinate
+calculations required when drawing with \latex picture objects.
+The macros in this distribution and the interpreter are the result of that
+effort, drawings I have had to produce since, and suggestions received
+from others. The interpreter has been upgraded over time to generate
+\mfpic, \MetaPost~\cite{metapost}, raw \Postscript, \Postscript with {\tt
psfrag} tags, raw PDF, \PSTricks, and Ti{\it k}Z PGF output, the latter
two my preference because of their quality and flexibility, including
facilities for colour and rotations, together with simple font selection.
@@ -3118,26 +3312,27 @@ 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.
+The simple \pic\ language is but one of many available tools for creating
+line graphics. Consequently, the main value of this distribution is
+not necessarily 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 decades, and which now total 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 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, but the payoff
+can be worth the effort.
Instead of using \pic macros, I preferred the equally simple but more
powerful \Mfour macro processor, and therefore \Mfour is required here,
-although \dpic now supports \pic-like macros.
-% 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.
+although \dpic now supports \pic-like macros. Free versions of \Mfour
+are available for Unix and its descendents, Windows, and other operating
+systems. Additionally, the simplicity of \Mfour and \pic enables the
+writing of custom macros, which are mentioned from time to time in this
+manual and included in some of the examples.
If starting over today would I not just use one of the other drawing
packages available these days? It would depend on the context, but \pic
@@ -3175,6 +3370,7 @@ 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.
+\pagebreak
\xection{Bugs\label{Bugs:}}
This section provides hints and a list of common errors.
@@ -3195,7 +3391,7 @@ received.
\bflistitem}[2]{\phantomsection\pdfbookmark[subsection]{#1}{#2}{\bf #1: }}
\begin{enumerate}
-%\item {\bf Misconfiguration:}
+%\pagebreak
\item
\bflistitem{Misconfiguration}{misconfig}%
One of the configuration files
@@ -3479,6 +3675,7 @@ without sacrificing ease of use.
-B16000} enlarges the buffer size to 16000 bytes. However, this
error message could also result from a syntax error.
+\iffalse
\item
\bflistitem{\PSTricks anomaly}{anomaly}
If you are using \PSTricks and
@@ -3503,6 +3700,7 @@ without sacrificing ease of use.
to {\tt define(`M4PatchPSTricks',)}. Undo the change if you later update
\PSTricks.
\end{enumerate}
+\fi
\item
\bflistitem{m4 {\tt -I} error}{mfourerror}\label{Mfourerror:}