1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
|
* Circuit_macros Version 9.2, copyright (c) 2020 J. D. Aplevich under *
* the LaTeX Project Public Licence in file Licence.txt. The files of *
* this distribution may be redistributed or modified provided that this *
* copyright notice is included and provided that modifications are clearly *
* marked to distinguish them from this distribution. There is no warranty *
* whatsoever for these files. *
This is a set of macros for drawing high-quality line diagrams to
include in LaTeX, web, or similar documents, with support for SVG
(including Inkscape) and other formats. Fundamental electric circuit
elements and basic logic gates based on IEEE and European standards are
included with several tools and examples of other types of diagrams.
Elements can be scaled or drawn in any orientation and are easy
to modify. The advantages and disadvantages of such a system in its
basic form are similar to those of TeX itself, which is macro-based and
non-WYSIWYG; however, graphical interfaces are available for specific
operating systems as mentioned below.
The macros are to be processed by an m4 macro processor, and evaluate to
drawing commands in the pic "little language," which is easy to read and
learn. The diagram is then automatically translated into TiKZ, PSTricks,
or other formats for processing by LaTeX or other applications. Pic
is well suited to line drawings requiring parametric or conditional
components, fine adjustment, geometric calculations, repetition, or
recursion. Arbitrary text for formatting by LaTeX can be included.
Free interpreters for m4 and pic are readily available.
Sources are available as a git repository at
https://gitlab.com/aplevich/Circuit_macros
REQUIRED SOFTWARE:
Preferred setup:
GNU m4, dpic (see below), LaTeX, PSTricks, dvips
or
m4, dpic, LaTeX or PDFLaTeX, TikZ-PGF
The GNU m4 macro processor is assumed, and a small number of macros
require GNU m4 features. Other versions of m4 will work with most macros.
The dpic interpreter can translate pic input into several forms,
typically a .tex file for processing by latex with pgf/Tikz or PSTicks.
Alternative:
m4, GNU pic (gpic), TeX or LaTeX, and a driver recognizing tpic specials
(eg dvips)
The GNU pic interpreter with option -t produces tpic special commands.
Also possible for some diagrams:
m4 and dpic with output in the following formats:
LaTeX graphics or LaTeX eepic (for simple diagrams), mfpic, xfig,
MetaPost, SVG, PDF, or Postscript.
USAGE
First-time users should read the Quick Start section of Circuit_macros.pdf.
The following describes the most common basic usage to produce tikz
or pstricks graphics for LaTeX; see below for integration with other
tools and production of other formats. You probably should try out
the basic usage before integrating the macros with sophisticated
system-dependent tools. When developing your own diagrams, refer to
the macro descriptions in the List of Macros section of Circuit_macros.pdf.
Suppose that a source file, cct.m4 say, has been created and the top
two lines are
.PS
cct_init
...
The file is processed by feeding a configuration file followed by the
diagram source to m4, and routing the output to dpic. If you have set
the M4PATH environment variable as described in the INSTAllATION
instructions, the command for Tikz processing is
m4 pgf.m4 cct.m4 | dpic -g > cct.tex
NOTE: The order in which the files are given to m4 is important.
A configuration file (pgf.m4 in this example) must ALWAYS appear first.
If you have not set the M4PATH environmental variable then the command is
m4 -I <path> pgf.m4 cct.m4 | dpic -g > cct.tex
where <path> is the absolute path to the directory containing the library
macros.
If the first line of cct.m4 is
include(pgf.m4)
and M4PATH is defined, then this command can be simplified to
m4 cct.m4 | dpic -g > cct.tex
In each case, the resulting file cct.tex is normally inserted into
a document to be processed by LaTeX. The -g option of dpic produces
Tikz-pgf graphics commands in cct.tex so the LaTeX document must have
\usepackage{tikz} in the preamble.
To produce postscript output, the LaTeX preamble must contain
\usepackage{pstricks}, pstricks.m4 is read instead of pgf.m4, and the dpic
option is -p, so the command is
m4 pstricks.m4 cct.m4 | dpic -p > cct.tex
or, if include(pstricks.m4) is the first line of cct.m4,
m4 cct.m4 | dpic -p > cct.tex
Read Section 2 of the manual to see how to process the diagram source
from within the main .tex source file.
To use the GNU gpic processor (called pic on some systems) instead of dpic,
the command is
m4 gpic.m4 cct.m4 | gpic -t > cct.tex
with the -I <path> option added if M4PATH has not been defined.
INSTALLATION:
1. Decide where you will be installing the .m4 library files. In
principle, they can go anywhere; for example, $HOME/Circuit_macros,
c:\localtexmf\Circuit_macros, /usr/local/share/Circuit_macros,
or ~/texmf/tex/latex/Circuit_macros. Copy the files from the
top-level directory of the distribution to the installation
directory, or simply expand the .tar.gz or .zip distribution file
and rename the result to create the installation directory, which
will then include the doc and examples subdirectories.
2. Copy boxdims.sty (see Section 9 of the manual) from the top
distribution directory to where LaTeX will find it; directory
~/texmf/tex/latex/boxdims for example, and refresh the LaTeX
filename database (the exact command depends on your LaTeX
distribution and may not be necessary).
3. Define the environment variable M4PATH to point to the installation
directory determined in Step 1. For the bash shell, for
example, add the following to your .bashrc file:
export M4PATH='.:~/texmf/tex/latex/Circuit_macros:'
but modify the path to the installation directory as necessary.
4. This is optional. For historical reasons, the default configuration file
as distributed is gpic.m4. You can change it to pgf.m4 or pstricks.m4
for use with dpic by editing the include command near the top of
libgen.m4. To do this automatically, go to the installation directory
and type
"make pgfdefault" to set the default processor to dpic with Tikz pgf
"make psdefault" to set the default processor to dpic with PSTricks
"make gpicdefault" to restore gpic as the default.
In case of difficulty, go to the examples directory, look at debug1.tex
and debug2.m4, and follow instructions.
WORKFLOW: The basic commands given above suffice for documents of moderate
size and complexity; otherwise, a "make" facility or equivalent should be
used or, for modest documents, diagram processing can be controlled from
within the tex document source as described in the manual. For near-immediate
viewing, three windows can be kept open: one in which to edit the source, one
to process the source and produce postscript or pdf, and GSview 5.0, which
updates when clicked. The Okular viewer also re-loads automatically.
Special-purpose editors and GUI-based project tools such as TeXnicCenter
can also be employed, or a scripting language can automate the steps as
done by Latexmk or several other similar tools; see, for example,
http://tex.stackexchange.com/questions/64/tools-for-automating-document-compilation
NOTE: One of the configuration files (gpic.m4, pstricks.m4, pgf.m4,
pdf.m4, postscript.m4, psfrag.m4, mpost.m4, mfpic.m4, svg.m4, or
xfig.m4) must be read by m4 before (or at the beginning of) the diagram
source file, depending on the required form of pic output. Otherwise,
libgen.m4 can be read first but it will invoke the default configuration
file, which is gpic.m4 in the distribution unless it has been changed
during installation.
TESTING:
To test your installation, go to the examples directory (or copy the
files Makefile, tst.tex, and any .m4 sources you might like to test
to a working directory) and create a test circuit in the
file test.m4. Copy ex01.m4, for example, or quick.m4 from the doc
directory into test.m4.
On a system with a "make" facility, first check the definitions at
the top of the Makefile, and then type "make tst1" to produce the
file tst.ps. If the source requires processing twice, type "make
tst" instead. To process one of the example .m4 files in the
examples directory, simply type "make name.ps" to process name.m4.
If these tests work to your satisfaction, try typing simply "make" to
produce examples.ps. To test .pdf files, go to the pgf directory,
copy name.m4 there, and type either "make name.ps" or "make name.pdf"
to test the file under pdflatex and TikZ PGF.
The .m4 files in the examples directory can serve as models for your
diagrams but keep in mind that some of them contain details that allow
the source to be used with a variety of postprocessors. Sticking to one
postprocessor such as tikz or PStricks allows for the simplest source.
You might also wish to browse some of the included files that are not
used to make examples.ps.
A few of the sources in the examples directory are copies of files
from the doc directory. They are duplicated to provide flexibility
of directory structure and independency of sources.
No "make" facility? You have to test by hand (but see below for
diagram production software). Copy a test file as above into
test.m4. Assuming you have dpic installed, type the following:
m4 -I <path> pstricks.m4 test.m4 > test.pic
dpic -p test.pic > test.tex
latex tst
dvips tst -o tst.ps
SOURCES AND MANUALS:
View or print Circuit_macros.pdf in the doc directory.
M4 is widely available on Unix systems. PC source and executables are
also available: http://gnuwin32.sourceforge.net/packages/m4.htm
A large set of Unix-like Windows tools, including m4, is available via
http://www.cygwin.com/
DJGPP versions are available as m4-NNb.zip (where NN is the current
release number) on web archives and at
http://www.delorie.com/djgpp/dl/ofc/dlfiles.cgi/current/v2gnu/
There are several sources of hints on m4 usage; some places to look are
http://gnuwin32.sourceforge.net/packages/m4.htm (m4 for Windows)
http://www.gnu.org/software/m4/manual/ (GNU m4 manual)
https://mbreen.com/m4.html (m4 by example)
https://www.seindal.dk/rene/gnu/ (development site)
The m4 (computer language) article in Wikipedia gives a concise overview.
An academic discussion of the language can be found in
http://www.cs.stir.ac.uk/~kjt/research/pdf/expl-m4.pdf.
The GNU Autoconf manual contains a chapter on M4 programming:
http://www.gnu.org/software/autoconf/manual/index.html
(Do not read this manual first). Autoconf uses quote characters [ and ]
instead of the default ` and ' which work well with the pic language.
A video "Drawing Circuit Diagrams with Circuits Macros" by James Green
showing how to use Circuit_macros with his setup is at
https://www.youtube.com/watch?time_continue=53&v=pFRIBvUJHS4
Gpic is part of the GNU groff distribution, for which the source
and documentation is available from http://ftp.gnu.org/gnu/groff/
but there are mirror sites as well. The original AT&T pic manual
can be obtained at http://doc.cat-v.org/unix/v10/10thEdMan/pic.pdf
A more extensive manual is found in the documentation that comes with
GNU pic, which is typically installed as gpic. A pdf copy is included
with the dpic distribution and a version can be found on the web at
http://www.kohala.com/start/troff/gpic.raymond.ps
DPIC:
Dpic is not included here you say? If you want to try the LaTeX
picture objects, mfpic, PSTricks, TikZ-PGF, MetaPost, xfig, SVG, PDF,
or Postscript output provided by dpic, there are at least three possibilities:
Some Linux distributions will install dpic automatically, the current
(free) C source and Windows executable can be obtaied from
http://ece.uwaterloo.ca/~aplevich/dpic/
and a git repository containing complete source is at
https://gitlab.com/aplevich/dpic
The source can be found in a number of repositories but many contain
older versions, see https://repology.org/project/dpic/badges
The best advice is to obtain the newest version.
The dpic distribution includes a manual dpic-doc.pdf containing a summary
of the pic language and descriptions of features unique to dpic.
EXAMPLES AND INTEGRATION WITH OTHER TOOLS:
A set of examples is included in this distribution, showing electric
circuits, block diagrams, flow charts, signal-flow graphs, basic use
of colour and fill, and other applications.
Read the manual Circuit_macros.pdf and view or print the file
examples.ps in the examples directory. There are a few other source
files in the examples directory that are not shown in examples.pdf.
For the possibly unstable development version of these macros, try
http://ece.uwaterloo.ca/~aplevich/Circuit_macros/
The examples directory Makefile automates the generation of .ps, .eps,
.png, and .pdf files for individual diagrams. Subdirectories of the
examples directory are for testing metafont, metapost, pgf, psfrag,
pdf, and xfig examples.
Installation and usage of the macros have evolved a little since the
beginning so archived instructions on the net may be slightly more
complicated than currently necessary. However, a number of people
have developed tools that simplify workflow for their circumstances,
which are beyond the scope of this distribution.
A set of examples and hints intended for his colleagues has been
produced by Alan Robert Clark at http://ytdp.ee.wits.ac.za/cct.html
A Python-based GUI called PyCirkuit is at
https://pypi.org/project/pycirkuit/ and
https://github.com/orestesmas/pycirkuit.
For an introduction, look at the FOSDEM video by Orestes Mas:
https://ftp.osuosl.org/pub/fosdem/2020/H.2215/pycirkuit.webm
A KDE interface created by Matteo Agostinelli can be found at
http://wwwu.uni-klu.ac.at/magostin/cirkuit.html. A git repository
of a newer version of cirkuit by Andrew G. for Linux is at
https://github.com/ag-ckt/cirkuit/tree/V0.5.0. Because of changes
in library dependencies, there is uncertainty about installation
possibilities.
A wiki offering examples and tips is at
http://swwiki.e-dschungel.de/circuit_macros
It is in German but Google translate works well on the page.
Variations:
See eschpic on Github for IEC-style electrical drawings.
Mac users:
A previewer app for Mac OS X written by Collin J. Delker is available at
http://www.collindelker.com/wp/2013/04/circuit_macros_previewer/
For an example of the use of dpic in a wiki (thanks to Jason Grout), see
http://jasongrout.org/software/dokuwiki/format-plugin
A Windows batch file for Circuit_macros is found at
http://someonehasdonethis.blogspot.ca/2012/12/a-solution-for-drawing-circuit-diagrams.html
The examples in the current distribution include some flowchart elements
in Flow.m4. For a pic-only version that does not require m4, look at
http://web.ing.puc.cl/~mtorrest/downloads.htm#TeX
Pic dates from the 1980s and was first developed as a preprocessor for
the *roff family of Unix word processors. Some additional libraries such
as chem (for chemical structures) and dformat (for data structures) are
still viable.
Pic macros for drawing graphs are described at
http://www.math.uiuc.edu/~west/gpic.html
After minor adaptation to dpic syntax, many of them can be simplified.
A collection of pic resources and related material is available at
http://www.kohala.com/start/troff/troff.html In particular, W. Richard
Stevens illustrated his books on Unix and TCP/IP using pic macros. Some
of the sources found there need minor tuning to work under dpic.
MetaPost examples: Go to the examples/mpost directory. Check the
Makefile as described in the README file, type "make", and stand well back.
Postscript with embedded psfrag strings:
Type "make" in the examples/psfrag directory to process examples
using dpic -f for creating .eps files with embedded psfrag strings.
Postscript, CorelDraw, Adobe Illustrator:
Circuits and other diagrams not requiring LaTeX-formatted text can be
processed through m4 and dpic -r to produce encapsulated Postscript
output. This output can also be imported into CorelDraw or Adobe
Illustrator. However, Postscript is not a word processor, so any
LaTeX formatting instructions in the source are not obeyed. These programs
also import svg output produced by dpic -v.
SVG output, Inkscape:
Dpic -v produces svg output. If the result is to be directly
inserted into html, then as for Postscript output, the diagram source
file has to be adapted to remove any LaTeX formatting. The configuration
file svg.m4 contains macros that can assist.
If SVG is the ultimate goal, then it may be advisable to use the tool
dvisvgm to convert dvi to svg. An alternative on some systems is to
produce pdf and then use pdf2svg, since the font selection and formatting
problems associated with direct production of svg are eliminated.
SVG is the native file format for the Inkscape graphics editor.
Therefore, elements defined by these macros can be output by dpic -v
in svg format for later manipulation by Inkscape. A basic palette
of circuit elements for importing into Inkscape is found in
examples/svg/paletteSVG.m4. In the svg subdirectory, type
"make paletteSVG.svg", read the resulting file into Inkscape, and then
ungroup the elements as desired. You would probably wish to add to or
customize these elements for extensive use.
Recent Inkscape versions can export graphics to eps or pdf format
and text to tex format, so that labels can be formatted by LaTeX and
overlaid on the graphics file. This process allows the use of Inkscape
to place and embellish circuit elements.
Metafont:
The file examples/mf/cct.mf is a Metafont source for a few variants of
the basic elements, produced using the mfpic output of dpic. It may
be of interest to persons who cannot otherwise implement the macros.
To see the elements (assuming a typical installation), type "make"
in the mf directory.
Xfig:
The file examples/xfig/xfiglib.fig contains circuit elements in xfig
3.2 format produced by dpic. The file is a prototype because many
more elements could be included. Logic gates often have many labels,
and xfig is not a word processor, so some fine tuning of labels is in
order. Translation between languages always involves a loss of
information and idiom, but Xfig can store diagrams in pic format, so
it is possible to alternate between xfig and dpic.
LIBRARIES:
The file libgen.m4 contains general-purpose macros and is read
automatically by other libraries. The file libcct.m4 defines basic
circuit elements. Binary logic-circuit elements are in liblog.m4.
Macros for drawing 3D projections are in lib3D.m4, and some macros
for drawing double-line arrows are in darrow.m4. The file dpictools.pic
contains pic macros and is read automatically by some of the examples.
MODIFICATIONS:
Macros such as these inevitably will be modified to suit individual
needs and taste. They continue to evolve in my own library as I use
them and as others send comments. No such collection can hope to
include all possible circuit-related symbols, so you will probably
find yourself writing your own macros or adapting some of these. Be
careful to rename modified macros to avoid confusion. The learning
curve compares well to other packages, but there is no trivially easy
way to produce high-quality graphics.
Feel free to contact me with comments or questions. I have retired
from full-time work but continue the hobby of maintaining these files.
I may now be able to spend more time on individual requests but I may
not reply instantly to email.
Dwight Aplevich
aplevich (AT) uwaterloo (DOT) ca
|