Author: Peter Jan Randewijk

Getting started with M4 Circuit-Macros – Part IV

In this section we will see how the m4cm.py script can be used to automate the creation of loose standing EPS, PDF, PNG and JPG pictures. In order to use this script however, some additional programs, over and above those installed in Part I, is required.

  1. The first is obviously the Python interpreter, or more specifically the Python 3 interpreter. This can be downloaded from the official Python website here, https://www.python.org/downloads/
  2. The second program required is Ghostscript. The Python script uses it to obtain the bounding box of the dvips generated Postscript (.PS) picture, in order to convert it into an Encapsulated Postscript (.EPS) picture. Ghostcript can be downloaded here, https://www.ghostscript.com/download/gsdnld.html
  3. The third program required is ImageMagick. The Python script will use it to convert the Encapsulated Postscript (.EPS) picture into a Joint Photographic Experts Group (.JPG) or Portable Network Graphics (.PNG) format if the “-j” or “-n” option respectively is selected with the m4cm script. ImageMagick can be downloaded here, https://imagemagick.org/script/download.php

Some help with the script can be obtained by running the script with either “-h” or “–help”, e.g.

$ m4cm -h

usage: M4CM [-h] [-a [APPEND_CHARS]] [-b L B R T] [-d] [-e] [-g] [-j] [-n]
[-o [OUTPUT_DIR]] [-p] [-q] [-Q] [-r [PNG_RESOLUTION]]
[-t [LATEX_TEMPLATE_FILE]] [-v] [M4CM_FILE [M4CM_FILE …]]

Instead of "M4CM_FILE", it is also possible to use "*.m4cm" to compile all the ".m4cm" files in the current folder

positional arguments:  M4CM_FILE M4CM File to be compiled

optional arguments:
  -h, --help show this help message and exit
  -a [APPEND_CHARS], --append [APPEND_CHARS]
     Character/String to append to the end of the output file(s)
  -b L B R T, --boundingbox_offset L B R T the BoundingBox Offset: left
     offset point value, top offset point value, right offset point value,
     bottom offset point values, the default is: 1 1 1 1, i.e. 1pt in each 
     direction
  -d, --delete_eps delete EPS file after converting to PNG or PDF
  -e, --eps convert to EPS format [default option]
  -g, --ghostscript use GhostScript to convert to PNG format
  -j, --jpg convert to JPG format
  -n, --png convert to PNG format
  -o [OUTPUT_DIR], --output_dir [OUTPUT_DIR] the Output Directory for the  
     EPS/PDF/PNG/JPG output files
  -p, --pdf convert to PDF format
  -q, --quiet run quietly, but print progress
  -Q, --super_quiet run quietly with no output
  -r [PNG_RESOLUTION], --resolution [PNG_RESOLUTION] PNG or JPG resolution 
     (or density)
  -t [LATEX_TEMPLATE_FILE], --template [LATEX_TEMPLATE_FILE]
     LaTeX template file to be used [default="default.ltx"]
  -v, --version show program's version number and exit

In order to create standalone PDF/JPG/PNG figures for M4 Circuit Macros

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.

“convert:not authorized” errors with ImageMagick

If you get the following error when trying to compile to a JPG or PNG file, on a Linux machine,


convert: not authorized `<file_name>.eps' @ error/constitute.c/ReadImage/428.
convert: no images defined `<file_name>.png' @ error/convert.c/ConvertImageCommand/3275.
Error executing: convert -density 600 <file_name>.eps file_name>.png

It is probable due to added securing options that was introduced in version 6+ of the convert utility from ImageMagick that the m4cm.py script uses to convert from EPS to either PNG or JPG. For more information, refer to this post on StackOverflow. The simple solution is to find the policy.xml file which is usually located in /etc/ImageMagick<-version_number> directory, and change the following line of code,

  <policy domain="coder" rights="write" pattern="PS" />

to

  <policy domain="coder" rights="read|write" pattern="PS" />
Design a site like this with WordPress.com
Get started