| 1 |
|
| 2 |
* Circuit_macros Version 11.0, copyright (c) 2026 J. D. Aplevich under * |
| 3 |
* the LaTeX Project Public Licence in file Licence.txt. The files of * |
| 4 |
* this distribution may be redistributed or modified provided that this * |
| 5 |
* copyright notice is included and provided that modifications are clearly * |
| 6 |
* marked to distinguish them from this distribution. There is no warranty * |
| 7 |
* whatsoever for these files. * |
| 8 |
|
| 9 |
This is a set of macros for drawing high-quality line diagrams to |
| 10 |
include in LaTeX, web, or similar documents, with support for svg |
| 11 |
(including Inkscape) and other formats. Fundamental electric circuit |
| 12 |
elements and basic logic gates based on IEEE and European standards are |
| 13 |
included with several tools and examples of other types of diagrams. |
| 14 |
Elements can be scaled or drawn in any orientation and are easy |
| 15 |
to modify. The advantages and disadvantages of such a system in its |
| 16 |
basic form are similar to those of TeX itself, which is macro-based |
| 17 |
and non-WYSIWYG. Graphical interfaces are available for specific |
| 18 |
operating systems. |
| 19 |
|
| 20 |
The macros are to be processed by an m4 macro processor, and evaluate |
| 21 |
to drawing commands in the pic "little language," which is easy to |
| 22 |
read and learn. The diagram is then automatically translated into |
| 23 |
TiKZ, PSTricks, or other formats for processing by LaTeX or other |
| 24 |
applications. Pic is well suited to line drawings requiring parametric |
| 25 |
or conditional components, fine adjustment, geometric calculations |
| 26 |
(it is Turing complete), repetition, or recursion. Arbitrary text |
| 27 |
for formatting by LaTeX can be included. Free interpreters for m4 |
| 28 |
and pic are readily available. |
| 29 |
|
| 30 |
Sources are available as a git repository at |
| 31 |
https://gitlab.com/aplevich/Circuit_macros |
| 32 |
|
| 33 |
REQUIRED SOFTWARE: |
| 34 |
Preferred setup: |
| 35 |
m4, dpic, LaTeX or PDFLaTeX, TikZ-PGF |
| 36 |
or |
| 37 |
GNU m4, dpic, LaTeX, PSTricks, dvips |
| 38 |
|
| 39 |
The GNU m4 macro processor is assumed. Other versions of m4 will work |
| 40 |
with most macros. |
| 41 |
|
| 42 |
The dpic interpreter can translate pic input into several forms, |
| 43 |
typically a .tex file for processing by latex with pgf/Tikz or PSTicks |
| 44 |
but also several stand-alone formats including SVG. |
| 45 |
|
| 46 |
Alternative: |
| 47 |
m4, GNU pic (gpic), TeX or LaTeX, and a driver recognizing tpic specials |
| 48 |
(eg dvips) |
| 49 |
|
| 50 |
The GNU pic interpreter with option -t produces tpic special commands. |
| 51 |
|
| 52 |
Also possible for some diagrams: |
| 53 |
m4 and dpic with output in the following formats: |
| 54 |
LaTeX graphics or LaTeX eepic (for simple diagrams), mfpic, xfig, |
| 55 |
MetaPost, svg, pdf, or Postscript. |
| 56 |
|
| 57 |
USAGE |
| 58 |
First-time users should read the Quick Start section of Circuit_macros.pdf. |
| 59 |
|
| 60 |
The following describes the most common basic usage to produce tikz |
| 61 |
or pstricks graphics for LaTeX; see below for integration with other |
| 62 |
tools and production of other formats. You probably should try out |
| 63 |
the basic usage before integrating the macros with sophisticated |
| 64 |
system-dependent tools. When developing your own diagrams, refer to the |
| 65 |
macro descriptions in the List of Macros section of Circuit_macros.pdf. |
| 66 |
|
| 67 |
Suppose that a source file, cct.m4 say, has been created and the top |
| 68 |
two lines are |
| 69 |
.PS |
| 70 |
cct_init |
| 71 |
... |
| 72 |
|
| 73 |
The file is processed by feeding a configuration file followed by the |
| 74 |
diagram source to m4, and routing the output to dpic. If you have set |
| 75 |
the M4PATH environment variable as described in the INSTAllATION |
| 76 |
instructions, the command for Tikz processing is |
| 77 |
|
| 78 |
m4 pgf.m4 cct.m4 | dpic -g > cct.tex |
| 79 |
|
| 80 |
NOTE: The order in which the files are given to m4 is important. |
| 81 |
A configuration file (pgf.m4 in this example) must ALWAYS appear first. |
| 82 |
|
| 83 |
If you have not set the M4PATH environmental variable then the command is |
| 84 |
|
| 85 |
m4 -I <path> pgf.m4 cct.m4 | dpic -g > cct.tex |
| 86 |
|
| 87 |
where <path> is the absolute path to the directory containing the library |
| 88 |
macros. |
| 89 |
|
| 90 |
If the first line of cct.m4 is |
| 91 |
include(pgf.m4) |
| 92 |
and M4PATH is defined, then this command can be simplified to |
| 93 |
|
| 94 |
m4 cct.m4 | dpic -g > cct.tex |
| 95 |
|
| 96 |
In each case, the resulting file cct.tex is normally inserted into |
| 97 |
a document to be processed by LaTeX. The -g option of dpic produces |
| 98 |
Tikz-pgf graphics commands in cct.tex so the LaTeX document must have |
| 99 |
\usepackage{tikz} in the preamble. |
| 100 |
|
| 101 |
To produce postscript output, the LaTeX preamble must contain |
| 102 |
\usepackage{pstricks}, pstricks.m4 is read instead of pgf.m4, and the dpic |
| 103 |
option is -p, so the command is |
| 104 |
|
| 105 |
m4 pstricks.m4 cct.m4 | dpic -p > cct.tex or m4 cct.m4 | dpic -p > cct.tex |
| 106 |
|
| 107 |
Read Section 2 of the manual to see how to process the diagram source |
| 108 |
from within the main .tex source file. |
| 109 |
|
| 110 |
To use the GNU gpic processor (called pic on some systems) instead of dpic, |
| 111 |
the command is |
| 112 |
|
| 113 |
m4 gpic.m4 cct.m4 | gpic -t > cct.tex |
| 114 |
|
| 115 |
The basic commands given above suffice for documents of moderate size |
| 116 |
and complexity; otherwise, a "make" facility or equivalent should be |
| 117 |
used or, for modest documents, diagram processing can be controlled |
| 118 |
from within the tex document source as described in the manual. For |
| 119 |
near-immediate viewing of the results, three windows can be kept open: |
| 120 |
one in which to edit the source, one to process the source and produce |
| 121 |
postscript or pdf, and a viewer such as gv, GSview 5.0, or Okular, for |
| 122 |
example. A window displaying the manual is also useful when you are |
| 123 |
composing a significant diagram. |
| 124 |
|
| 125 |
INSTALLATION AND TESTING: See the INSTALL file. |
| 126 |
|
| 127 |
SOURCES AND MANUALS: |
| 128 |
View or print Circuit_macros.pdf in the doc directory. |
| 129 |
|
| 130 |
M4 is widely available on Unix systems. PC source and executables are |
| 131 |
also available: http://gnuwin32.sourceforge.net/packages/m4.htm |
| 132 |
A large set of Unix-like Windows tools, including m4, is available via |
| 133 |
http://www.cygwin.com/ |
| 134 |
DJGPP versions are available as m4-NNb.zip (where NN is the current |
| 135 |
release number) on web archives and at |
| 136 |
http://www.delorie.com/djgpp/dl/ofc/dlfiles.cgi/current/v2gnu/ |
| 137 |
|
| 138 |
There are several sources of hints on m4 usage; some places to look are |
| 139 |
http://gnuwin32.sourceforge.net/packages/m4.htm (m4 for Windows) |
| 140 |
http://www.gnu.org/software/m4/manual/ (GNU m4 manual) |
| 141 |
https://mbreen.com/m4.html (m4 by example) |
| 142 |
The m4 (computer language) article in Wikipedia gives a concise overview. |
| 143 |
An academic discussion of the language can be found in |
| 144 |
http://www.cs.stir.ac.uk/~kjt/research/pdf/expl-m4.pdf. |
| 145 |
The GNU Autoconf manual contains a chapter on M4 programming: |
| 146 |
http://www.gnu.org/software/autoconf/manual/index.html |
| 147 |
(Do not read this manual first). Autoconf uses quote characters [ and ] |
| 148 |
instead of the default ` and ' which work well with the pic language. |
| 149 |
|
| 150 |
DPIC: |
| 151 |
Several Linux distributions will install dpic by command but the version |
| 152 |
may not be the latest. A git repository containing complete source is at |
| 153 |
https://gitlab.com/aplevich/dpic |
| 154 |
and source plus a Windows executable can be obtained from |
| 155 |
http://ece.uwaterloo.ca/~aplevich/dpic/ |
| 156 |
The best advice is to obtain the newest version. |
| 157 |
|
| 158 |
The dpic distribution includes dpic-doc.pdf, a manual containing a summary |
| 159 |
of the pic language and a detailed description of features unique to dpic. |
| 160 |
|
| 161 |
GPIC: |
| 162 |
Gpic is part of the GNU groff distribution, for which the source |
| 163 |
and documentation is available from http://ftp.gnu.org/gnu/groff/ |
| 164 |
but there are mirror sites as well. A more extensive manual is found |
| 165 |
in the documentation that comes with GNU pic, which is typically |
| 166 |
installed as gpic. A pdf copy is included with the dpic distribution. |
| 167 |
The original AT&T pic manual can be found at |
| 168 |
http://doc.cat-v.org/unix/v10/10thEdMan/pic.pdf |
| 169 |
|
| 170 |
SVG output, Inkscape: |
| 171 |
Dpic -v produces svg output. If the result is to be directly inserted |
| 172 |
into html, then as for Postscript output, the diagram source file has |
| 173 |
to be adapted to remove any LaTeX formatting. The configuration file |
| 174 |
svg.m4 contains macros that can assist. At the expense of an extra |
| 175 |
postprocessing step, sophisticated text formatting and font selection |
| 176 |
can be retained by first producing pdf output and then converting to |
| 177 |
svg using, say, dvisvgm (https://www.ctan.org/pkg/dvisvgm) or pdf2svg |
| 178 |
(https://github.com/dawbarton/pdf2svg). |
| 179 |
|
| 180 |
SVG is the native file format for the Inkscape graphics editor. |
| 181 |
Therefore, elements defined by these macros can be output by dpic -v in |
| 182 |
svg format for later manipulation by Inkscape. A basic palette of |
| 183 |
circuit elements for Inkscape is found in examples/dpv/palettePDV.m4. |
| 184 |
In the examples/dpv subdirectory, type "make paletteDPV.svg", read |
| 185 |
the resulting file into Inkscape, and then ungroup the elements as |
| 186 |
desired. You would probably wish to add to or customize these elements |
| 187 |
for extensive use. |
| 188 |
|
| 189 |
EXAMPLES |
| 190 |
Numerous examples are included in this distribution, showing electric |
| 191 |
circuits, block diagrams, flow charts, signal-flow graphs, basic use |
| 192 |
of colour and fill, and other applications. Some of the examples |
| 193 |
test the boundaries of the domain of application of dpic with m4 |
| 194 |
macros. Read the manual Circuit_macros.pdf and view examples.pdf in the |
| 195 |
examples directory or make and view the html file in the examples/dpv |
| 196 |
directory. Yet more examples are in the examples/extras directory. |
| 197 |
Try http://ece.uwaterloo.ca/~aplevich/Circuit_macros/ for the possibly |
| 198 |
unstable development version of these macros. |
| 199 |
|
| 200 |
The examples directory Makefile automates the generation of .ps, .eps, |
| 201 |
.png, and .pdf files for individual diagrams. Subdirectories of the |
| 202 |
examples directory are for testing metafont, metapost, pgf, psfrag, |
| 203 |
and xfig examples. |
| 204 |
|
| 205 |
WORKFLOW: |
| 206 |
Installation and usage of the macros have evolved somewhat since the |
| 207 |
beginning, so archived instructions on the net may be slightly more |
| 208 |
complicated than currently necessary. |
| 209 |
|
| 210 |
I use a very simple workflow most of the time: three open windows; |
| 211 |
one to edit the diagram source, one to run LaTeX and produce pdf or |
| 212 |
postscript, and a document viewer window. The lines |
| 213 |
:set mps+=`:' |
| 214 |
:set mps+=<:> |
| 215 |
were added to my default .vimrc file to highlight matched pairs of |
| 216 |
brackets, braces, parentheses, and, expecially for m4 programming, |
| 217 |
single quotes. |
| 218 |
|
| 219 |
INTEGRATION WITH OTHER TOOLS: |
| 220 |
To automate document production, I simply added commands to |
| 221 |
the appropriate Makefiles. However, others have developed tools |
| 222 |
that simplify workflow for their circumstances. The following are |
| 223 |
representative but keep in mind that systems and installations evolve |
| 224 |
over time: |
| 225 |
|
| 226 |
A Python-based GUI called PyCirkuit is at |
| 227 |
https://pypi.org/project/pycirkuit/ and |
| 228 |
https://github.com/orestesmas/pycirkuit. For an introduction, look at |
| 229 |
the FOSDEM video by Orestes Mas: |
| 230 |
https://archive.fosdem.org/2020/schedule/event/pycirkuit/ |
| 231 |
|
| 232 |
A python build-automation tool, m4cm, by Peter Jan Randewijk is at |
| 233 |
https://m4cmpy.wordpress.com/ and very clear instructions about getting |
| 234 |
started with Circuit_macros are at |
| 235 |
https://m4cmpy.wordpress.com/2020/02/23/getting-started-with-m4-circuit-macros/ |
| 236 |
|
| 237 |
Fabrice Salvaire has a blog and a useful bash script at |
| 238 |
https://www.fabrice-salvaire.fr/en/blog/electronic-circuit-diagrams/ |
| 239 |
|
| 240 |
A set of examples and hints intended for his colleagues has been |
| 241 |
produced by Alan Robert Clark at http://ytdp.ee.wits.ac.za/cct.html |
| 242 |
|
| 243 |
Peter Fabo and colleagues are writing an open-source book |
| 244 |
that introduces Circuit_macros as well as useful libraries and |
| 245 |
customizations: |
| 246 |
https://github.com/lab-411/Technicka_Grafika |
| 247 |
The rendered version is available at |
| 248 |
https://lab-411.github.io/Technicka_Grafika/_build/html/index.html |
| 249 |
It is in the Slovak language but Google Translate works well with it. |
| 250 |
|
| 251 |
Examples and hints for logic circuits are at: |
| 252 |
https://aprikose.sumomo.ne.jp/madchemiker/ |
| 253 |
Invoke this site using Google translate if you do not read Japanese. |
| 254 |
|
| 255 |
A video "Drawing Circuit Diagrams with Circuits Macros" by James Green |
| 256 |
showing how to use Circuit_macros with his setup is at |
| 257 |
https://www.youtube.com/watch?time_continue=53&v=pFRIBvUJHS4 |
| 258 |
|
| 259 |
A recent elementary introduction to Circuit_macros is at |
| 260 |
https://www.root.cz/clanky/publikovanie-elektrickych-schem-a-diagramov-pomocou-circuit-macros/ |
| 261 |
It is in Czech but Google translate works well. |
| 262 |
|
| 263 |
LaTeX automation tools are discussed at, for example, |
| 264 |
http://tex.stackexchange.com/questions/64/tools-for-automating-document-compilation |
| 265 |
|
| 266 |
A Windows batch file for Circuit_macros is found at |
| 267 |
http://someonehasdonethis.blogspot.ca/2012/12/a-solution-for-drawing-circuit-diagrams.html |
| 268 |
|
| 269 |
The eschpic package on Github contains macro definitions targeted at |
| 270 |
IEC-style electrical drawings for industrial and automation purposes: |
| 271 |
https://github.com/xwhatsit/eschpic |
| 272 |
|
| 273 |
Mac users: |
| 274 |
Descriptions of Mac installations have been published from time to time; |
| 275 |
for example: |
| 276 |
https://www.yumpu.com/en/document/view/34946319/using-circuitmacros-in-mac-os-x-automation-and-robotics- |
| 277 |
|
| 278 |
VARIATIONS |
| 279 |
Macros such as these will be modified inevitably to suit individual |
| 280 |
needs and taste. They continue to evolve in my own library as I |
| 281 |
use them and as others send comments. No such collection can hope to |
| 282 |
include all possible circuit-related symbols, so you will probably find |
| 283 |
yourself writing your own macros or adapting some of these. The example |
| 284 |
files might be a good place to start. Be careful to rename modified |
| 285 |
macros to avoid confusion. The learning curve compares well to other |
| 286 |
packages, but there is no trivially easy way to produce high-quality |
| 287 |
graphics. (If "a picture is worth a thousand words," ask yourself |
| 288 |
how long it would take to write, revise, and perfect a thousand words.) |
| 289 |
|
| 290 |
The pic language dates from the 1980s and was first developed |
| 291 |
as a preprocessor for the *roff family of Unix wordprocessors. |
| 292 |
Some additional libraries such as chem (for chemical structures) |
| 293 |
and dformat (for data structures) are still viable. |
| 294 |
|
| 295 |
A collection of traditional pic resources and related material is |
| 296 |
available at http://www.kohala.com/start/troff/troff.html In particular, |
| 297 |
W. Richard Stevens illustrated his books on Unix and TCP/IP using |
| 298 |
pic macros. Some of the sources found there need minor tuning to work |
| 299 |
under dpic. |
| 300 |
|
| 301 |
MetaPost examples: Go to the examples/mpost directory. Check the |
| 302 |
Makefile as described in the README file, type "make", and stand |
| 303 |
well back. |
| 304 |
|
| 305 |
Postscript with embedded psfrag strings: |
| 306 |
Type "make" in the examples/psfrag directory to process examples |
| 307 |
using dpic -f for creating .eps files with embedded psfrag strings. |
| 308 |
|
| 309 |
Postscript, CorelDraw, Adobe Illustrator: |
| 310 |
Circuits and other diagrams not requiring LaTeX-formatted text can be |
| 311 |
processed through m4 and dpic -r to produce encapsulated Postscript |
| 312 |
output. This output can also be imported into CorelDraw or Adobe |
| 313 |
Illustrator. However, Postscript is not a word processor, so any LaTeX |
| 314 |
formatting instructions in the source are not obeyed. These programs |
| 315 |
also import svg output produced by dpic -v. |
| 316 |
|
| 317 |
Metafont: |
| 318 |
The file examples/mf/cct.mf is a Metafont source for a few variants of |
| 319 |
the basic elements, produced using the mfpic output of dpic. It may |
| 320 |
be of interest to persons who cannot otherwise implement the macros. |
| 321 |
To see the elements (assuming a typical installation), type "make" |
| 322 |
in the mf directory. |
| 323 |
|
| 324 |
Xfig: |
| 325 |
The file examples/xfig/xfiglib.fig contains circuit elements in xfig |
| 326 |
3.2 format produced by dpic. The file is a prototype because many |
| 327 |
more elements could be included. Logic gates often have many labels, |
| 328 |
and xfig is not a word processor, so some fine tuning of labels is in |
| 329 |
order. Translation between languages always involves a loss of |
| 330 |
information and idiom, but Xfig can store diagrams in pic format, so |
| 331 |
it is possible to alternate between xfig and dpic. |
| 332 |
|
| 333 |
LIBRARIES: |
| 334 |
The file libgen.m4 contains general-purpose macros and is read |
| 335 |
automatically by other libraries and the macro gen_init. The file |
| 336 |
libcct.m4 defines basic circuit elements. Binary logic-circuit |
| 337 |
elements are in liblog.m4 and additional single-line elements are |
| 338 |
in libSLD.m4. Macros for drawing 3D projections are in lib3D.m4, and |
| 339 |
some macros for drawing double-line arrows are in darrow.m4. The file |
| 340 |
dpictools.pic contains dpic macros and is read automatically by some |
| 341 |
of the examples. |
| 342 |
|
| 343 |
Feel free to contact me with comments or questions. I have retired from |
| 344 |
full-time professorship but continue the hobby of maintaining these files. |
| 345 |
I may now be able to spend more time on individual requests but I may |
| 346 |
not reply instantly to email. |
| 347 |
|
| 348 |
|
| 349 |
Dwight Aplevich |
| 350 |
aplevich (AT) uwaterloo (DOT) ca |