Category: Getting started

Getting started with M4 Circuit-Macros – Part III

In Part I, I discussed all of the programs (or stuff) that needs to be downloaded to get started. In Part II, I discussed how to install (the bare minimum) to get started. In this part, I will discuss how to “draw” (i.e. program) our first M4 Circuit Macro picture and to basically test if is successfully working together.

Copy and paste the following into your favorite editor and save as (say) ex0.m4cm. I usually save all my M4 Circuit Macro “pictures” with a *.m4cm extension, using *.m4 only for my M4 Circuit Macro include or “library” files. 

.PS

include(pstricks.m4)

scale=25.4

cct_init

dx = 12.5
dy = 12.5

O: (0,0)

Vs: source(up_ dy from O,S);            llabel(,\mathbf{V}_s,)
L:  inductor(right_ 2*dx,,3,,dimen_/5); llabel(,jX_s,)
Zl: ebox(down_ to (Here.x,O.y));        llabel(,\mathbf{Z}_l,)
    line to O
    dot
    ground
    
.PE

On Windows I prefer to use Notepad++ as it allows for easy implementation of customised syntax-highlighting, as well as the NppExec plugin to allow external scripts to be run from within Notepad++.

The next step is to run m4 on the ex0.m4cm file to generate pic output code at the command prompt,

$ m4 ex0.m4cm > ex0.pic

If m4 is able to find the pstricks.m4 file, it implies that the M4PATH was set up correctly. If not, the following error message will be displayed.

m4:ex0.m4cm:3: cannot open `pstricks.m4': No such file or directory

If m4 were enabled to find pstricks.m4, no message will be display and an ex0.pic file will be created, with all the m4 circuit-macros, e.g.

  • source
  • inductor
  • ebox
  • ground

expanded into pic code. The m4 macro processor only expands all the m4 macros that was defined, either in the file itself, or in the included *.m4 files, but does not check for any syntax errors in the code.

The next step is to run the dpic compiler on the pic code, to produce LaTeX output code. To generate LaTeX PSTricks output from the ex0.pic file, issue the following command at the command prompt,

$ dpic -p ex0.pic > ex0.tex

If the file was successfully compiled, no output message will be displayed and a ex0.tex file will be created. If there however was some problem with the syntax, an error message will be displayed, e.g.

*** dpic: line 138 ERROR: ; or end of line found.
 The following were expected:
 .x .y * /

if (say) the “to” in “line to O” in the ex0.m4cm code above, was omitted.

The next step is to include our newly created M4 Circuit Macro picture, i.e. ex0.tex into our main LaTeX document. For this example, copy and paste the following code into your favorite LaTeX editor, ands save as (say) Example_0.tex.

\documentclass[dvips]{article}

\usepackage{pstricks}
\usepackage{times}

\pagestyle{empty}

\begin{document}

\begin{figure}[hbt]
  \begin{center}
    \include{ex0}
    \caption{Our first M4 Circuit Macro picture.}
  \end{center}
\end{figure}

\end{document}

We can now use LaTeX to compile the above document to a DVI output,

$ latex -quiet Example_0.tex

The Yap viewer that comes with MikTeX can be used to view the Example_0.tex output file.

We can see that the text labels for the source, inductor and load impedance is not correctly displayed in Yap. But don’t fear, this is just an “optical illusion”. After converting the output to Postscript, the labels will be displayed correctly. This is done by issuing the following command at the command prompt,

$ dvips -q Example_0.dvi

This will generate an Example_0.ps file that can be viewed using the legacy GSView,

or we can covert it to PDF, by issuing

$ ps2pdf Example_0.ps

at the command line to create an Example_0.pdf file which can viewed in any PDF viewer, e.g. SumatraPDF.

Alternatively, we can also generate PGF/TikZ code from dpic, and use PdfLaTeX to create a PDF file directly from our LaTeX document. This will be shown on the next page.

Pages: Page 1, Page 2

Getting started with M4 Circuit Macros – Part II

In Part I, I discussed what all the programs (or stuff) is that is required to get started. As mentioned a LaTeX installation is paramount as we will be generating LaTeX code from our (m4) circuit-macros to be inserted in our LaTeX document.

Because (m4) circuit-macros also form part of the CTAN, I usually extract them to one of my TEXMF root directories according to the TDS structure, e.g. on Windows,

  • I copy the boxdims.sty LaTeX style file and all the *.m4 files in the Circuit_macros<version number>.zip to C:\Users\<my user name>\texmf\tex\latex\circuit_macros
  • and all the rest of the files to C:\Users\<my user name>\texmf\doc\latex\circuit_macros

This is my personal choice, however it is important that boxdims.sty is located in one of the TEXMF root directories. In MikTeX a TEXMF root directory can be add using MikTeX Console as follows:

Here, C:\User\petra\texmf, is my personal or custom or local TEXMF root directory. According to the TDS all LaTeX packages (i.e. class or style files) are situated in the C:\User\petra\texmf\latex directory, where as all the documentation is the C:\User\petra\texmf\doc directory. After a local TEXMF root directory was created, and new package where added, the package file name database (FNDB) needs to be updated,

Now that the (m4) circuit-macros have been “installed”, we need to “install” the m4 macro processor to expand these circuit-macros into pic code. We also need to “install” the (d)pic compiler to convert the pic code into LaTeX code. The following three files therefore needs to be copied somewhere in your PATH:

  • m4.exe
  • regex2.dll (required by m4.exe)
  • dpic.exe

Because I use m4 and dpic exclusively with LaTeX, I usually (on Windows) copy them into my MikTeX bin directory, i.e. C:\Program Files\MiKTeX 2.9\miktex\bin\x64 But this is personal preference, the only requirement is that they are in the path somewhere…

To check if m4 and dpic are indeed in the path, issue the following commands in a directory other than where these executable were copied to.

$ m4 --version

Should result is,

m4 (GNU M4) 1.4.17
Copyright (C) 2013 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later .
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Rene' Seindal.

And,

$ dpic --version

Should result in,

*** dpic version 2019.01.01
 Options:
     (none) LaTeX picture output
     -d PDF output
     -e Pict2e output
     -f Postscript output, psfrag strings
     -g PGF-TikZ output
     -h write this message and quit
     -m mfpic output
     -p PSTricks output
     -r Postscript output
     -s MetaPost output
     -t eepicemu output
     -v SVG output
     -x xfig output
     -z safe mode (disable sh, copy, and print to file)

The final part of the “installation” is to let the m4 macro processor know where our m4 circuit-macro “libraries” are located. This is done by creating an M4PATH variable point to the installation path of our m4 circuit-macros. This is done by clicking on the Environment Variables… button on the Advanced tab of System Properties in Windows.

And adding the new M4PATH variable.

In my case, M4PATH=C:\User\petra\texmf\latex\circuit_macros

By opening the command promp in Windows, one can check the M4PATH variable by issueing the following command,

$ set m4path

In my case, this should return,

M4PATH=C:\Users\petra\texmf\tex\latex\circuit_macros

In the next part (Part III), I will discuss how to “draw” (i.e. program) our first M4 Circuit Macro picture and basically test to see if everything is smoothly working together.

Getting started with M4 Circuit Macros – Part I

To get started with M4 Circuit Macros, a lot of different programs (or stuff) is required. On a Windows box, this could seem very daunting. On a Linux box it is slightly easier.

In Part I, I will only discuss all the stuff that needs to be download first. Part II will focus on where these stuff needs to placed to work together properly. Part III wil discuss how to test our installation and generate an M4 Circuit Macros picture from the command line. Again for a Windows user this may seem a bit daunting, but for a Linux user this should not be relative easy to follow. Part IV will discuss how these command line step can be simplified using the Python script, m4cm.py. Part V will discuss how the creation of an M4 Circuit Macros picture can simplified further using Notepad++ on Windows and Kile on Linux.

OK, so let’s start with all of the stuff that needs to be downloaded first.

  1. The most important is a LaTeX installation as the (d)pic compiler generates LaTeX code that needs to included into the main LaTeX and compiled to show the picture. On Windows I prefer MikTeX and on Linux, TexLive. I wouldn’t go into the details in Part II on how to install LaTeX, as this is beyond the scope of this Blog, but for MikTeX, have a look at the HOWTO links here. I have a complete installation, but missing packages can be installed on the fly.
  2. Preferable the latest version of (m4) circuit-macros from either
  3. Make sure the general-purpose macro processor m4, to expand the circuit-macros into (d)pic code, is installed. On a Linux box, it is usually installed by default. For a Window box, m4 can be downloaded from Sourceforge :
  4. The dpic compiler, to compile the (d)pic output generated by the macro processor m4 into LaTeX code, can be downloaded here,
  5. A nice editor that preferable allows for custom syntax highlighting in order to ease the “programming” of (m4) circuit-macros. On Windows, I prefer Notepad++ for (m4) circuit-macros, whilst using TeXstudio for my LaTeX documents (just because I still have not figured out how to do syntax highlighting for TeXstudio).
    On Linux I use Kile (which is basically “KatePart for LaTeX”) for both my LaTeX documents and my (m4) circuit-macros.
    Have a look in the Syntax Highlighting directory of my m4cmpy GitHub repository for custom syntax highlighting for both these editors, i.e. Notepad++ and KatePart/Kile.
  6. And finally on a PDF viewer that allows a PDF file to be altered while it is being viewed, e.g. Sumatra PDF on Windows or Okular on Linux.
    Adobe Acrobat unfortunately does not work as one has to close the file whilst compiling a new version.

In the next part (Part II), we will look at how to install some the above mentioned programs, or more correctly where to copy some of these files to, for a basic installation, just to get started and wet the appetite for more.

Design a site like this with WordPress.com
Get started