Debian Codegraph @

texmf-dist/doc/latex/circuit-macros/README

raw
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