diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/circuit-macros/README')
-rw-r--r-- | Master/texmf-dist/doc/latex/circuit-macros/README | 415 |
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 |