summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/circuit-macros/README
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/circuit-macros/README')
-rw-r--r--Master/texmf-dist/doc/latex/circuit-macros/README415
1 files changed, 415 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/circuit-macros/README b/Master/texmf-dist/doc/latex/circuit-macros/README
new file mode 100644
index 00000000000..c20ea3d4a3c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/circuit-macros/README
@@ -0,0 +1,415 @@
+
+* Circuit_macros Version 9.0, copyright (c) 2019 J. D. Aplevich under *
+* the LaTeX Project Public License. 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.
+
+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.
+
+ 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 wish to browse some of the files that are not
+ included to produce examples.ps.
+
+ 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 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.ps.
+ 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. The following may
+ be of interest:
+
+ Fabrice Salvaire provides a brief introduction at
+ https://www.fabrice-salvaire.fr/en/blog/electronic-circuit-diagrams/
+
+ 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 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
+
+ The GUI front end PyCirkuit at https://github.com/orestesmas/pycirkuit
+ is Python-based and inspired by Cirkuit.
+
+ 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.
+
+ 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 more examples in the context of a textbook, have a look at
+ Aplevich, J.D., "The Essentials of Linear State-Space Systems," New
+ York: John Wiley & Sons Inc., 2000. In Canada, look at Andrews,
+ G.C., Aplevich, J.D., Fraser, and R.A., MacGregor, C.G.,
+ "Introduction to Professional Engineering in Canada," (fifth edition)
+ Toronto: Pearson Education Canada, Inc., 2018. Some samples from these
+ books can be found at
+ http://ece.uwaterloo.ca/~aplevich/
+
+ 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.
+
+TikZ-PGF: Check the Makefile in the examples/pgf directory as described
+ in the README file, and type "make" or "make examples.pdf".
+
+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