circuit-macros

git-svn-id: svn://tug.org/texlive/trunk@55089 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 72 insertions, 151 deletions

diff --git a/Master/texmf-dist/doc/latex/circuit-macros/README b/Master/texmf-dist/doc/latex/circuit-macros/README
index 3d31e4eb616..982ea2a097a 100644
--- a/Master/texmf-dist/doc/latex/circuit-macros/README
+++ b/Master/texmf-dist/doc/latex/circuit-macros/README
@@ -1,5 +1,5 @@
 
-* Circuit_macros Version 9.2, copyright (c) 2020 J. D. Aplevich under      *
+* Circuit_macros Version 9.3, 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 *
@@ -13,9 +13,9 @@
   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.
+  basic form are similar to those of TeX itself, which is macro-based
+  and non-WYSIWYG. Graphical interfaces are available for specific
+  operating systems.
 
   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
@@ -100,11 +100,7 @@ USAGE
   \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
+    m4 pstricks.m4 cct.m4 | dpic -p > cct.tex or 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.
@@ -114,99 +110,16 @@ USAGE
 
     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
+  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 of the basic process, three windows can be kept
+  open: one in which to edit the source, one to process the source and
+  produce postscript or pdf, and Okular or GSview 5.0, which updates
+  when clicked.
 
-  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
+INSTALLATION AND TESTING: See the INSTALL file.
 
 SOURCES AND MANUALS:
   View or print Circuit_macros.pdf in the doc directory.
@@ -223,7 +136,6 @@ SOURCES AND MANUALS:
   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.
@@ -232,10 +144,6 @@ SOURCES AND MANUALS:
   (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
@@ -259,15 +167,14 @@ DPIC:
   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.
+  of the pic language and of features unique to dpic.
 
-EXAMPLES AND INTEGRATION WITH OTHER TOOLS:
+EXAMPLES
   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
+  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.pdf in the
+  examples directory. For the curious, There are additional 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/
@@ -277,48 +184,71 @@ EXAMPLES AND INTEGRATION WITH OTHER TOOLS:
   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.
+INTEGRATION WITH OTHER TOOLS:
+  Installation and usage of the macros have evolved smewhat since the
+  beginning, so archived instructions on the net may be slightly more
+  complicated than currently necessary. Because I was producing books,
+  I simply added commands to the appropriate Makefiles. However, others
+  have developed tools that simplify workflow for their circumstances.
+  The following are representative but keep in mind that systems and
+  installations evolve ovr time:
+
+  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 python build-automation tool, m4cm, by Peter Jan Randewijk is at
+  https://m4cmpy.wordpress.com/
+  with very clear instructions about getting started with Circuit_macros at
+  https://m4cmpy.wordpress.com/2020/02/23/getting-started-with-m4-circuit-macros/
+
+  Fabrice Salvaire has a blog and a useful bash script 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 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 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
 
-  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 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.  There is
+  uncertainty about installation possibilities because of changes in
+  library dependencies.
 
   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.
+  LaTeX automation tools are discussed at, for example, 
+  http://tex.stackexchange.com/questions/64/tools-for-automating-document-compilation
 
   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
+VARIATIONS
+  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.
+
+  See eschpic on Github for IEC-style electrical drawings.
+
+  For an example of the use of dpic in a wiki (thanks to Jason Grout), see
+  http://jasongrout.org/software/dokuwiki/format-plugin
 
   Pic dates from the 1980s and was first developed as a preprocessor for
   the *roff family of Unix word processors.  Some additional libraries such
@@ -329,10 +259,11 @@ EXAMPLES AND INTEGRATION WITH OTHER TOOLS:
   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.
+  A collection of traditional 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.
@@ -398,16 +329,6 @@ LIBRARIES:
   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