summaryrefslogtreecommitdiff
path: root/graphics/circuit_macros/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-07-29 03:01:04 +0000
committerNorbert Preining <norbert@preining.info>2022-07-29 03:01:04 +0000
commitda2dc471ec5bb2620f0ef5a4a700b236d1a8af06 (patch)
treed928b5b5abe4df9287ffda090d15e777c78bd783 /graphics/circuit_macros/doc
parent5937dac9360bdf40d1b0baf9d7384b109fb5b7a7 (diff)
CTAN sync 202207290301
Diffstat (limited to 'graphics/circuit_macros/doc')
-rw-r--r--graphics/circuit_macros/doc/Circuit_macros.pdfbin1020598 -> 1023203 bytes
-rw-r--r--graphics/circuit_macros/doc/DiodesMan.m46
-rw-r--r--graphics/circuit_macros/doc/Version.tex2
-rw-r--r--graphics/circuit_macros/doc/body.tex93
-rw-r--r--graphics/circuit_macros/doc/defines.tex32
5 files changed, 91 insertions, 42 deletions
diff --git a/graphics/circuit_macros/doc/Circuit_macros.pdf b/graphics/circuit_macros/doc/Circuit_macros.pdf
index 9dd8ad8377..9c67589a6f 100644
--- a/graphics/circuit_macros/doc/Circuit_macros.pdf
+++ b/graphics/circuit_macros/doc/Circuit_macros.pdf
Binary files differ
diff --git a/graphics/circuit_macros/doc/DiodesMan.m4 b/graphics/circuit_macros/doc/DiodesMan.m4
index fb433235e1..33789fa5c7 100644
--- a/graphics/circuit_macros/doc/DiodesMan.m4
+++ b/graphics/circuit_macros/doc/DiodesMan.m4
@@ -1,5 +1,5 @@
.PS
-# Diodes.m4
+# DiodesMan.m4
cct_init
movewid = 2pt__
@@ -16,6 +16,8 @@ movewid = 2pt__
move down 0.2; right_
{diode(,B) ; move ; "`{\tt diode(,B)}'" ljust}
move down 0.2; right_
+ {diode(,b) ; move ; "`{\tt diode(,b)}'" ljust}
+ move down 0.2; right_
{diode(,G) ; move ; "`{\tt diode(,G)}'" ljust}
move down 0.2; right_
{diode(,D) ; move ; "`{\tt diode(,D)}'" ljust}
@@ -39,7 +41,7 @@ movewid = 2pt__
{diode(,MK) ; move ; "`{\tt diode(,MK)}'" ljust}
}
- move right_ 2.0
+ move down_ sourcerad_ right_ 2.0
{ {diode(,Z,RE) ; move ; "`{\tt diode(,Z,RE)}'" ljust}
move down 0.30; right_
{diode(,U) ; move ; "`{\tt diode(,U)}'" ljust}
diff --git a/graphics/circuit_macros/doc/Version.tex b/graphics/circuit_macros/doc/Version.tex
index 91db3d8a25..45c581b3af 100644
--- a/graphics/circuit_macros/doc/Version.tex
+++ b/graphics/circuit_macros/doc/Version.tex
@@ -1 +1 @@
-Version 9.8
+Version 9.9
diff --git a/graphics/circuit_macros/doc/body.tex b/graphics/circuit_macros/doc/body.tex
index c7c7b2bc6b..b984ec0435 100644
--- a/graphics/circuit_macros/doc/body.tex
+++ b/graphics/circuit_macros/doc/body.tex
@@ -956,7 +956,7 @@ 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|U|V|v|w|Z|{\sl chars}, [R][E])}.
+ 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}
@@ -984,14 +984,21 @@ Similarly, the macro
{\tt resized(}{\sl factor},`{\sl macro name}',{\sl macro arguments}{\tt )}
\par
\noindent
-can be used to resize the body of an element by temporarily multiplying
-the {\tt dimen\_} macro by {\sl factor}. More general resizing should be
-done by redefining {\tt dimen\_} as described in \SR{Circuitscaling:}.
-These two macros can be nested; the following scales the above example
-by 1.8, for example
+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 resized(1.8,`diode',right\_ 0.4);}
-{\tt resized(1.8,`reversed',`diode',right\_ 0.4)}
+{\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)}
Fuses are shown in \FR{Fuses}
and switches with numerous controls in \FR{Switches}.
@@ -1919,7 +1926,7 @@ using the macro
\par
\noindent
where the {\sl r, g, b} values are in the range 0 to 1
-(integers from 0 to 255 for \SVG) to specify the rgb color.
+to specify the rgb color.
This macro is a wrapper for the following, which may be more convenient
if many elements are to be given the same color:
@@ -2245,18 +2252,18 @@ which executes the given actions successively with
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
+ The SLD macros allow considerable scope for
+ customization using key-value pairs to set internal parameters.
+ In addition, diagram-wide or block-scope changes are made as usual
+ 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}
+ To apply such a change to a single element or a group of them,
+ 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:
+style parameters, which are currently as follows:
\begin{verbatim}
define(`sl_breakersize_',`dimen_*3/16') # breaker box size
define(`sl_breakersep_',`dimen_/2') # breaker separation from body
@@ -2270,14 +2277,15 @@ 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
+define(`sl_busindent_',`min(dimen_/5,rp_len/5)') # busbar end indent
\end{verbatim}
- The macros also allow for extensive customization of individual
- elements using a key-value mechanism.
+%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
+ (which occur often)
and other symbols to elements.
\subsection{Two-terminal SLD elements\label{TwoTermSLD:}}
@@ -2320,6 +2328,13 @@ 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}).}
+The separation of the optional attached breaker or other stem elements from
+the body is controlled by the {\tt sl\_breakersep\_} global
+parameter. Adding {\tt sep={\sl expr}} to the body keys
+adjusts separations for an element; otherwise, adding
+this key to argument 3 or 4 adjusts the separation of
+the corresponding attached object.
+
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},
@@ -2380,7 +2395,9 @@ 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.}
+and the default slash name is {\sl SL,} and the separation from the head
+is specified using global {\tt sl\_breakersep\_} or the local
+{\tt sep={\sl expr}} parameters as for the two-terminal elements.
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
@@ -2448,7 +2465,18 @@ or the body-size parameter {\tt dimen\_.} For example, adding the line
\noindent%
after the {\tt cct\_init} line of {\tt quick.m4} produces slightly
-larger body sizes for all circuit elements. For logic elements, the
+larger body sizes for all circuit elements.
+
+For more localized resizing, use, for example,
+\par
+{\tt pushdef(`dimen\_',{\sl expression}) {\sl drawing commands}
+ popdef(`dimen\_')}
+\par
+\noindent
+(but ensure that the drawing commands have no net effect on the {\tt dimen\_}
+stack).
+
+For logic elements, the
equivalent to the {\tt dimen\_} macro is {\tt L\_unit}, which has
default value {\tt (linewid/10)}.
@@ -2570,6 +2598,7 @@ In the following,
two macros are defined to simplify the repeated drawing
of a series resistor and series inductor, and the macro {\tt tsection} defines
a subcircuit that is replicated several times to generate \FR{Tline}.
+\pagebreak
{\small \verbatiminput{Tline.m4}}
\begin{figure}[h!t]
% \ifpdf\vspace*{-\baselineskip}\fi%
@@ -3035,7 +3064,6 @@ 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,
@@ -3121,17 +3149,24 @@ 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\_boxs([angle={\sl expr};] {\sl text}[,{\sl expr, expr $\ldots$}])},
+{\tt rs\_boxs([angle={\sl degrees};] {\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 )}
-or by starting the first argument with {\tt angle={\sl expr};}.
+or by starting the first argument with {\tt angle={\sl degrees};}
+where {\sl degrees} is a decimal number (not an expression).
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.
+The macro {\tt r\_text({\sl degrees, text,} at {\sl position})}
+works under \PSTricks, \TPGF, and \SVG, the last requiring
+processing twice. The {\sl degrees} argument is a decimal constant
+(not an expression) and the text is a simple string without quotes.
+The text box is not calculated.
+
Another common requirement is the filling of arbitrary shapes, as
illustrated by the following lines within a {\tt .m4} file:
@@ -3192,6 +3227,7 @@ The lines
\noindent\verb|\end{scope}%|
\vspace{\parsep}
+\pagebreak
This is accomplished, for example, by adapting the {\tt \bsl{}mtotex}
macro of \SR{Simplifications:} as follows:
@@ -3290,7 +3326,6 @@ 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 eliminate the tedious coordinate
@@ -3321,7 +3356,7 @@ 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.
+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.
@@ -3370,10 +3405,13 @@ 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.
+First of all, be aware that old versions of \LaTeX, \dpic, and these
+macros are not always compatible. Updating an installation to current
+versions is often the way to eliminate mysterious error messages.
+
The distributed macros are not written for maximum robustness.
Macro arguments could be tested for correctness and
explanatory error messages could be written as necessary, but that
@@ -3391,7 +3429,6 @@ received.
\bflistitem}[2]{\phantomsection\pdfbookmark[subsection]{#1}{#2}{\bf #1: }}
\begin{enumerate}
-%\pagebreak
\item
\bflistitem{Misconfiguration}{misconfig}%
One of the configuration files
diff --git a/graphics/circuit_macros/doc/defines.tex b/graphics/circuit_macros/doc/defines.tex
index eb7d914fb2..dfcee2f91d 100644
--- a/graphics/circuit_macros/doc/defines.tex
+++ b/graphics/circuit_macros/doc/defines.tex
@@ -598,11 +598,12 @@
{macro for dimensioning diagrams;
{\sl arrowhead=}{\tt -> | <-}}
\macrodef{diode}{diode}{(\linespec,%
-B|CR|D|G|L|LE[R]|P[R]|S|Sh|T|U|V|v|w|Z|chars,%
+B|b|CR|D|G|L|LE[R]|P[R]|S|Sh|T|U|V|v|w|Z|chars,%
[R][E])}
{cct}
{diode:
{\tt B}=bi-directional,
+ {\tt b}=bi-directional with outlined zener crossbar,
{\tt CR}=current regulator,
{\tt D}=diac,
{\tt G}=Gunn,
@@ -1531,7 +1532,8 @@ elementspec}\char39,%
\macrodef{pushkeys\_}{pushkeys_}{({\sl string, key sequence})}
{gen}
{Multiple key-value definitions. Arg 2 is a semicolon-separated
- sequence of terms of the form {\tt {\sl key}:{\sl default value}:[N]}.
+ sequence of terms of the form {\tt {\sl key}:{\sl default value}:[N]}
+ which must contain no semicolons and the default values contain no colons.
Macro {\tt pushkey\_} is applied to each of the terms in order.
\seesect{Macroarguments:}}
\Letter{R}%
@@ -1603,14 +1605,13 @@ degrees})}
\macrodef{rgbdraw}{rgbdraw}{({\sl color triple}, {\sl drawing commands})}
{gen}
{color drawing for PSTricks, pgf, MetaPost, SVG postprocessors;
- (color entries are 0 to 1 except for SVG entries which are 0 to 255),
+ (color entries are 0 to 1),
see {\tt setrgb} \seesect{Semiconductors:}. Exceptionally, the color
of SVG arrows other than the default black has to be defined using the
{\tt outlined }{\sl string} and {\tt shaded }{\sl string} constructs.}
\macrodef{rgbfill}{rgbfill}{({\sl color triple}, {\sl closed path})}
{gen}
- {fill with arbitrary color (color entries are 0 to 1 except
- SVG entries which are 0 to 255); see {\tt
+ {fill with arbitrary color (color entries are 0 to 1); see {\tt
setrgb}\seesect{Semiconductors:}}
\macrodef{rgbstring}{rgbstring}{({\sl color triple or color name})}
{gen}
@@ -1629,9 +1630,12 @@ degrees})}
{Draw a right-angle symbol at {\sl Pos2}, of size
given by arg4. Arg5 =
line attributes, e.g., {\tt outlined "gray"}}
-\macrodef{r\_text}{s_text}{({\sl text},{\sl degrees})}
+\macrodef{r\_text}{r_text}{({\sl degrees},{\sl text},at {\sl position})}
{gen}
- {Rotate text by arg2 degrees (PSTricks, PGF, or SVG only).
+ {Rotate text by arg1 degrees (provides a single command for
+ PSTricks, PGF, or SVG only) placed at position in arg3.
+ The first argument is a decimal constant (not an expression) and
+ the text is a simple string without quotes.
\seesect{Interaction:}, \seesect{Pstricks:}}
\macrodef{rjust\_}{rjust_}{}
{gen}
@@ -1687,11 +1691,14 @@ degrees})}
\macrodef{rrot\_}{rrot_}{({\sl x, y, angle})}
{gen}
{\tt Here + vrot\_({\sl x, y, cos(angle), sin(angle))}}
-\macrodef{rs\_box}{rs_box}{([angle={\sl expr};]
+\macrodef{rs\_box}{rs_box}{([angle={\sl degrees};]
{\sl text},{\sl expr1},$\cdots$)}
{gen}
{like {\tt s\_box} but the text is rotated by {\tt text\_ang}
- (default 90) degrees. Two or more args are passed to {\tt sprintf()}.
+ (default 90) degrees, unless
+ the first argument begins with {\tt angle={\sl decimal number};},
+ in which case the number defines the rotation angle.
+ Two or more args are passed to {\tt sprintf()}.
If the first argument begins with {\tt angle={\sl expr};} then
the specified angle is used.
The examples {\tt define(`text\_ang',45); rs\_box(Hello World)} and
@@ -1800,8 +1807,7 @@ $\ldots$)}
name}])}
{gen}
{define colour for lines and text, optionally named (default
- {\tt lcspec});
- svg values are integers from 0 to 255\seesect{Semiconductors:}}
+ {\tt lcspec}); \seesect{Semiconductors:}}
\macrodef{setkey\_}{setkey_}{({\sl string, key, default,}[N])}
{gen}
{Key-value definition, like {\tt pushkey\_()} but the resulting
@@ -1976,6 +1982,7 @@ justification})}
{\tt scale={\sl expr} (default 1.0)};
{\tt grnd={\sl expr} attached ground at given angle
(type {\tt S} or {\tt N}))};
+ {\tt sep={\sl{}expr}};
{\tt stemlgth={\sl{}expr}};
{\tt wdth={\sl{}expr}};
{\tt direct=U|D|L|R|{\sl degrees}} (drawing direction).
@@ -1985,6 +1992,9 @@ justification})}
The {\tt L} (default) variant also defines internal labels
Internal labels {\sl L} and {\sl C} are included.
+ Key {\tt sep} is the type-{\tt S} separation from the head to the centre
+ of the slash symbol.
+
Key {\tt scale} allows scaling (default scale 1.0) but, with \dpic,
the {\tt scaled} directive can also be used.
\seesect{SingleLine:}}