Files in this directory

Name	Date	Size		Description
CHANGES	2008-11-12	5 Kbyte	download
Copying	2008-11-12	456 bytes	download
Makefile	2008-11-12	1 Kbyte	download
README	2008-11-12	13 Kbyte	download	Shown below
boxdims.sty	2008-11-12	1 Kbyte	download
darrow.m4	2008-11-12	7 Kbyte	download
gpic.m4	2008-11-12	1 Kbyte	download
homelib.txt	2008-11-12	219 bytes	download
lib3D.m4	2008-11-12	8 Kbyte	download
libcct.m4	2008-11-12	82 Kbyte	download
libgen.m4	2008-11-12	35 Kbyte	download
liblog.m4	2008-11-12	23 Kbyte	download
mfpic.m4	2008-11-12	1 Kbyte	download
mpost.m4	2008-11-12	1 Kbyte	download
pgf.m4	2008-11-12	1 Kbyte	download
postscript.m4	2008-11-12	2 Kbyte	download
pstricks.m4	2008-11-12	1 Kbyte	download
xfig.m4	2008-11-12	1 Kbyte	download

---

Contents of the README file

Circuit_macros

* Circuit_macros Version 6.4, copyright (c) 2008 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 TeX, LaTeX, or similar documents.  Fundamental electric
  circuit elements and basic logic gates 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 are similar to those
  of TeX itself, which is macro-based and non-wysiwyg, with ordinary
  character input.

  The macros are to be processed by m4, and evaluate to drawing
  commands in the pic "little language," which is easy to read and
  learn. Pic is well suited to line drawings requiring parametric or
  conditional components, fine adjustment, significant geometric
  calculations, repetition, or recursion.  Arbitrary text for
  formatting by LaTeX can be placed at will in the diagram.  Free
  LaTeX-compatible interpreters for m4 and pic are readily available.
  An extensive set of examples is included, showing electric circuits,
  block diagrams, flow charts, signal-flow graphs, basic use of colour
  and fill, and other applications.

  Some alternatives to consider according to taste and the graphics to
  be drawn are: wysiwyg drawing programs (but the results may be
  difficult to parameterize or tune), packages using TeX or LaTeX
  macros (but harder to read, of limited power, or for specialized
  diagrams), Metafont (good for diagrams up to moderate size), MetaPost
  and other drawing languages (powerful but typically with limited
  output formats) and specialized CAD programs (but typically the
  graphics are not easily tuned or not of book quality).  Any of the
  several intermediate formats to which the pic code can be translated
  can also be considered as an alternative drawing language.

REQUIRED SOFTWARE:
Preferred setup:
  m4, dpic (see below), TeX or LaTeX, PSTricks, dvips
or
  m4, dpic, LaTeX or PDFLaTeX, TikZ-PGF

Alternative:
  m4, GNU pic (gpic), TeX or LaTeX, and a driver recognizing tpic specials
   (eg dvips)

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, Postscript

USAGE:
  A source file, for example cct.m4, is processed as shown:
    m4 <path>pstricks.m4 <path>libcct.m4 cct.m4 | dpic -p > cct.tex
  or
    m4 <path>libcct.m4 cct.m4 | gpic -t > cct.tex

  The file cct.tex is processed by LaTeX or, more typically, inserted
  into the source of a document to be processed by LaTeX, and the
  resulting dvi file is printed using dvips.

  In the case of PGF, the command is
    m4 <path>pgf.m4 <path>libcct.m4 cct.m4 | dpic -g > cct.tex
  and the document is processed either by LaTeX to produce postscript
  or PDFLaTeX to produce pdf.

  NOTE: One of the configuration files gpic.m4, pstricks.m4, pgf.m4,
  postscript.m4, mpost.m4, mfpic.m4, or xfig.m4 must be read by m4
  before any of the other files, depending on the required form of pic
  output.  By default, gpic.m4 is read if one of these is not loaded
  first, but this behaviour can be modified as described below in the
  installation instructions.

  The manual CMman.pdf describes this process in more detail and
  suggests simplified and alternative usages.

  For processing complex documents containing many diagrams or other
  components, a project-management tool such as "make" is convenient:
  http://www.gnu.org/manual/make/html_chapter/make_toc.html. Otherwise
  a scripting language can automate the production steps.  Processing
  can also be simplified by grouping several diagrams per source file
  as described in the manual.

INSTALLATION:
  0.  Decide where you will be installing the .m4 library files:
      $HOME/Circuit_macros or c:\localtexmf\Circuit_macros, for example.
      You can simply expand Circuit_macros.zip or Circuit_macros.tar.gz of
      the distribution to create these, but be sure to perform Step 1 below.

  1.  Change the definition of HOMELIB_ near the top of libcct.m4 and each
      .m4 file in the same directory to the absolute path of the
      installation directory.  You can edit each file, but to automate
      this step on a system with a "make" facility, simply edit the
      path in the file homelib.txt and type "make homelib".

  2.  This is optional.  If dpic with PSTricks will be your default
      processor then you can change the string "gpic.m4" to
      "pstricks.m4" in the statements defining the default processor
      near the top of the lib*.m4 files and darrow.m4.  Type "make psdefault"
      to do this automatically using the Makefile. Changing the default
      means that you need not explicitly name the configuration file
      <path>pstricks.m4 or equivalent in the command path as in the
      cct.m4 example above.  If you do not change the default but are
      invoking dpic, then remember to read the correct configuration
      file before the library files and diagram source file.

      Similarly, if dpic with TikZ PGF will be your default then you
      can change the default string "gpic.m4" to "pgf.m4" in the
      library files.  Typing "make pgfdefault" will do this automatically.

  3.  Copy libcct.m4 and the other .m4 files in the same directory
      to the installation directory if they aren't there already.

  4.  If you are going to use boxdims.sty (see Section 9 of the manual)
      copy it to where LaTeX will find it, typically in
      localtexmf/tex/latex/local/ or C:\localtexmf\tex\latex\local,
      and refresh the filename database.

TESTING:
  First-time users should read at least the Quick Start section of
  CMman.pdf.  To test your installation, go to the examples 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.

  No "make" facility?  You have to test by hand.  Copy a test file as
  above into test.m4.  Assuming you have dpic installed, type the following,
  where <path> is the full path to the installed library directory:
  m4 -B32000 <path>/pstricks.m4 <path>/libcct.m4 test.m4 > test.pic
  dpic -p test.pic > test.tex
  latex tst
  dvips tst -o tst.ps

SOURCES:
  M4 is widely available on Unix systems.  PC source and executables are
  also available.  A 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) at
  http://www.delorie.com/pub/djgpp/current/v2gnu/
  and on web archives.

  There are several sources of hints on m4 usage; two places to look are
  http://www.gnu.org/software/m4/manual/m4.html
  and http://www.seindal.dk/rene/gnu/. An academic discussion of the
  language can be found in
  http://www.cs.stir.ac.uk/~kjt/research/pdf/expl-m4.pdf.

  Gpic is part of the GNU groff distribution, for which the latest
  source is available from prep.ai.mit.edu in pub/gnu, but there are
  mirror sites that archive these sources, and others that distribute
  executables.

DPIC:
  Dpic is not included here you say?  If you want to try the LaTeX
  picture objects, mfpic, PSTricks, TikZ-PGF, MetaPost, xfig, or
  Postscript output provided by dpic, the current free source and
  Windows executable can be obtained from
  http://ece.uwaterloo.ca/~aplevich/dpic/

MANUALS:
  View or print CMman.pdf in the doc directory.

  The original pic manual can be obtained at
  http://www.cs.bell-labs.com/10thEdMan/pic.pdf.  A more extensive
  manual is found in the documentation that comes with GNU pic, which
  is typically installed as gpic.  A compressed postscript copy is in
  http://ece.uwaterloo.ca/~aplevich/dpic/ and a version can be found
  on the web at http://www.kohala.com/start/troff/gpic.raymond.ps

EXAMPLES:
  Read the manual CMman.pdf and view or print the file examples.ps in the
  examples directory.  For the possibly unstable development version, try 
  http://ece.uwaterloo.ca/~aplevich/Circuit_macros/

  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

  The sources for the diagrams in examples.ps are included in this
  distribution.  To reproduce these examples you may have to adjust the
  font selections for your machine.  The examples should not be taken
  to represent the best or the only way to draw the diagrams because
  there are often several ways to draw the same figure.

  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," (Third edition)
  Toronto:  Prentice Hall, Pearson Education Canada, Inc., 2008.  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://math.byu.edu/~grout/software/dokuwiki/format-plugin
  Another web-based pic application can be found at http://figr.org/

  A collection of pic resources and related material is available at
  http://www.kohala.com/start/troff/troff.html Some of the example pic
  macros found there need minor tuning to work under dpic.

  A pic tutorial on the web is found at
  http://www.onlamp.com/pub/a/onlamp/2007/06/21/in-praise-of-pic.html

  The use of the pic language and pic macros for drawing graphs is
  described at http://www.math.uiuc.edu/~west/gpic.html

  Other early pic preprocessors are described in the pic section of
  http://troff.org/papers.html

MetaPost examples:  Go to the examples/mpost directory.  Check the
  Makefile as described in the README file, type "make", and stand well back.

TikZ-PGF: Check the Makefile in the examples/pgf directory as described
  in the README file, and type "make" or "make examples.pdf".

PDFLaTeX: Check the Makefile in the examples/pdflatex directory as described
  in the README file, and type "make".  These examples use Metafont as an
  intermediate format and are made somewhat obselete by the above TikZ-PGF
  compatibility.

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.

Metafont:
  The file examples/mf/cct.mf is a Metafont source for some 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
  testfont.ps" in the mf directory.

Xfig:
  It can be very efficient to define and fine-tune elements in a
  programming language for later placement with interactive graphics.
  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 basic macro definitions and is included
  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.

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 recently
retired from full-time duties 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.ca

Small print: This listing is regenerated periodically so there is a small chance that the directory has changed from what is shown here; to be sure, check the FTP listing.