CTAN sync 202210140301

1 files changed, 75 insertions, 61 deletions

diff --git a/graphics/circuit_macros/doc/body.tex b/graphics/circuit_macros/doc/body.tex
index b984ec0435..dc0738769f 100644
--- a/graphics/circuit_macros/doc/body.tex
+++ b/graphics/circuit_macros/doc/body.tex
@@ -613,12 +613,12 @@ circle diameter (last circle.width * 1.2) with .sw at last circle.ne}
 The planar objects can be filled with gray or colour.
 For example, either
 
-{\tt box dashed fill\_({\sl number})}\quad or\quad
+{\tt box dashed fill\_({\sl expression})}\quad or\quad
  {\tt box dashed outlined "{\sl color}" shaded "{\sl color}"}
 
 \noindent
 produces a dashed box. The first case has a gray fill determined by
-{\sl number}, with $0$ corresponding to black and $1$ to white;
+{\sl expression}, with $0$ corresponding to black and $1$ to white;
 the second case allows color outline and fill, the color strings depending on
 the postprocessor.
 Postprocessor-compatible RGB color strings are produced by the macro
@@ -666,10 +666,11 @@ function).
 
 \subsection{Compound objects\label{Compoundobjects:}}
 A compound object is a group of statements enclosed in square
-brackets.  Such an object is placed by default as if it were a box, but
+brackets.  Such an object, often called a {\em block},
+is placed by default as if it were a box, but
 it can also be placed by specifying the final position of a defined point.
 A defined point is the center or compass corner of the bounding box
-of the compound object or one of its internal objects.
+of the object or one of its internal objects.
 Consider the last line of the code fragment shown:
 
 \noindent%
@@ -683,6 +684,7 @@ The two gate macros evaluate to compound objects containing {\tt Out},
 {\tt In1}, and other locations.  The final positions of all objects
 inside the square brackets are determined in the last line by
 specifying the position of {\tt In1} of gate {\tt And2}.
+The compound block has been given the name {\tt Ands.}
 
 \subsection{Other language facilities\label{Otherlanguage:}}
 
@@ -754,8 +756,8 @@ operating-system commands, \pic macros, and external file inclusion.
 \xection{Two-terminal circuit elements\label{Basictwo:}}
 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 compound objects mentioned
-in \SR{Compoundobjects:}.
+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.
@@ -827,11 +829,12 @@ and the remaining source lines of the file are explained below:
    be given a name, {\tt R1} in the example, so that positions
    {\tt R1.start}, {\tt R1.centre}, and {\tt R1.end} are automatically
    defined as shown.
-\item The element body is overlaid by a block, which can be
-   used to place labels around the element.  The block
-   corresponds to an invisible rectangle with horizontal top and bottom lines,
-   regardless of the direction in which the element is drawn.  A
-   dotted box has been drawn in the diagram to show the block boundaries.
+\item The element body is drawn in or overlaid by a block, which can be
+   used to place labels around the body.
+   The block corresponds to an invisible rectangle with horizontal top
+   and bottom lines, regardless of the direction in which the element
+   is drawn.  A dotted box has been drawn in the diagram to show the
+   block boundaries.
 \item The last sub-element, identical to the first in two-terminal
    elements, is an invisible line that can be referenced later to
    place labels or other elements.
@@ -1146,9 +1149,9 @@ quote, in which case the argument is copied literally.
 The third argument specifies the separation from the element.
 
 \subsection{Labels\label{Labels:}}
-   Arbitrary labels
+   Arbitrary text labels
    can be positioned by any \pic\ placement method including the
-   representative basic examples shown:
+   basic examples shown:
 
    {\tt "}{\sl text}{\tt" at {\sl position}}\NVL
    {\tt "}{\sl text}{\tt" at {\sl position} above}\NVL
@@ -1158,20 +1161,22 @@ The third argument specifies the separation from the element.
    In addition, special macros for labeling two-terminal elements are available:
 \par
 {\tt
-   llabel(} {\sl arg1,arg2,arg3} {\tt )
+   llabel(} {\sl label,\ label,\ label,\ rel placement,\ block name} {\tt )
       \hfill\break\hspace*{\parindent}%
-   clabel(} {\sl arg1,arg2,arg3} {\tt )
+   clabel(} {\sl label,\ label,\ label,\ rel placement,\ block name} {\tt )
       \hfill\break\hspace*{\parindent}%
-   rlabel(} {\sl arg1,arg2,arg3} {\tt )
+   rlabel(} {\sl label,\ label,\ label,\ rel placement,\ block name} {\tt )
       \hfill\break\hspace*{\parindent}%
-   dlabel(} {\sl long,lat,arg1,arg2,arg3,}{\tt[X][A|B][L|R])}
-
-The first macro places the three arguments, which are treated as math-mode
-strings, on the left side of the element block {\em with respect to the
-current direction:} {\tt up, down, left, right.}
-The second places the arguments along the centre, and the third along the
-right side.
-A simple circuit example with labels is shown in \FR{Loop}.
+   dlabel(} {\sl long,\ lat,\ label,\ label,\ label,\ }{\tt[X][A|B][L|R])}
+
+The first macro places the first three arguments, which are treated
+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}.
 \begin{figure}[h!t]
    \vspace*{-\baselineskip}
    \parbox{4in}{\small \verbatiminput{Loop.m4}}%
@@ -1180,6 +1185,10 @@ A simple circuit example with labels is shown in \FR{Loop}.
    \caption{A loop containing labeled elements, with its source code.}
    \label{Loop}
    \end{figure}
+Most commonly, only
+the first three arguments are needed, and blank arguments are ignored.
+The fourth argument can be {\tt above,} {\tt below,} {\tt left,} or {\tt
+right} to supplement the default relative position.
 The macro {\tt dlabel} performs these functions for an
 obliquely drawn element, placing the three macro arguments at
 {\tt vec\_(-long,lat),} {\tt vec\_(0,lat),} and {\tt vec\_(long,lat)}
@@ -1188,9 +1197,6 @@ In the fourth argument, an {\tt X} aligns the labels with respect to the line
 joining the two terminals rather than the element body, and
 {\tt A, B, L, R} use absolute {\tt above, below, left,} or {\tt right} alignment
 respectively for the labels.
-Labels beginning
-with {\tt sprintf} or a double quote are copied literally rather than
-assumed to be in math mode.
 
 \xection{Placing two-terminal elements\label{Placing:}}
 The length and position of a two-terminal element
@@ -1517,6 +1523,7 @@ The fifth argument is a string of characters.  {\tt P}
 adds a power connection, {\tt R} exchanges the second and
 third entries, and {\tt T} truncates the opamp point.
 
+\enlargethispage{\baselineskip}
 Typeset text associated with circuit elements is not rotated by default,
 as illustrated by the second and third opamps in \FR{Opamp}.
 The {\tt opamp} labels can be rotated if necessary by 
@@ -1826,9 +1833,13 @@ and {\sl E} is shown in \FR{ujt}.
    \label{ujt}
    \end{figure}
 
-A thyristor macro with predefined internal locations
+The 3 or 4-terminal thyristor macro with predefined internal locations
  {\sl G} and {\sl T1,} {\sl T2,} or
- {\sl A,} {\sl K} is in \FR{thyristor}.
+ {\sl A,} {\sl K,} {\sl G,} and {\sl Ga} 
+ as appropriate is in \FR{thyristor}.
+Except for the {\sl G} and {\sl Ga} terminals,
+a thyristor (the {\tt IEC} variant excluded)
+is much like a two-terminal element.
 \begin{figure}[H]
    \input thyristorMan
    \vspace*{-1ex}
@@ -1840,10 +1851,9 @@ A thyristor macro with predefined internal locations
     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}
+The wrapper macro
+{\tt thyristor\_t({\sl linespec, chars, label})} and similar macros
+{\tt scr, 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,
 
@@ -3327,25 +3337,28 @@ distribution.  The \latex drawing commands alone or with {\tt eepic}
 or {\tt pict2e} extensions are suitable only for simple diagrams.
 
 \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
-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.
-\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.
+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}, 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 is
@@ -3363,21 +3376,22 @@ 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.  Free versions of \Mfour
+although \dpic  now supports \pic 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
-remains a good choice for line drawings because it is easy to learn
-and read but powerful enough for coding the geometrical calculations
-required for precise component sizing and placement. It would be nice
-if arbitrary rotations and scaling were simpler and if a general path
-element with clipping were available as in \Postscript.  However,
-all the power of \Postscript or \TPGF, for example, remains available,
-as arbitrary postprocessor code can be included with \pic code.
+packages available these days?  It would depend on the context, but
+\pic remains a good choice for line drawings because it is easy to learn
+and read but powerful enough (that is, Turing-complete) for coding the
+geometrical calculations required for precise component sizing and
+placement. It would be nice if arbitrary rotations and scaling were
+simpler and if a general path element with clipping were available
+as in \Postscript.  However, all the power of \Postscript or \TPGF,
+for example, remains available, as arbitrary postprocessor code can be
+included with \pic code.
 
 The \dpic interpreter has several output-format options that may be
 useful.  The {\tt eepicemu} and {\tt pict2e} extensions of the