Fabrice Popineau

SUPELEC –
metapost
Campus de Metz
2, rue E. Belin
F--57070 Metz
Practical METAPOST 1
[email protected]

abstract
In this article, I will explain how to pratically use metapost. This program is very different from
usual drawing programs, but it fits very well in a tex based typesetting system.

résumé
Ces quelques pages ont pour objectif de montrer comment utiliser pratiquement metapost. Ce
programme est très différent des logiciels classique de dessin, mais s’intègre extrêmement bien
dans la chaı̂ne de composition basée sur tex.

samenvatting
De volgende pagina’s laten zien hoe metapost praktisch kan worden gebruikt. Dit programma
verschilt sterk van de klassieke tekenprogramma’s, maar laat zich voortreffelijk combineren met
op tex gebaseerde tekstverwerkingssystemen.

Where can METAPOST be found?

Today, metapost can be found in all “complete” tex distributions:
tetex for Unix,
texlive CD-ROM for Unix and Windows,
miktex for Windows,
oztex, cmactex and if you want to use context under OS/X then you need
tetex.
In the following treatment, I base myself upon texlive 6 that runs under both Unix and
Windows. The example graphics are taken from the metafun Manual by Hans Hagen
(see further down).
The main program (mpost or mpost.exe) is accompanied by some auxiliary programs:
makempx: a control program that extracts the text parts of your .mp files and con-
verts the lower level commands to a file with .mpx extension. This extraction is
only done when the .mpx file is older than the .mp file. Once extraction is accom-
plished the following two programs take care of the conversion.
mpto: this program extracts the btex ... etex parts and the verbatimtex ...
etex parts from your .mp file and places them in a tex file.
dvitomp: converts .dvi files to .mpx files.
Further programs in a basic distribution include a set of so--called “macro” files to
construct diagrams and graphics based on circles and boxes (for an example see fig-
ure 1). Within the tex Directory Structure – TDS – look for these files under
/texmf/metapost, for documentation under /texmf/doc/metapost, and for many exam-
ples under /texmf/doc/guides/metapost-examples.
The complete set of sources, documentation, examples and further contributions
can be downloaded from the Comprehensive tex Archive Network – CTAN – to be
found on the Web under ftp://ftp.dante.de/pub/tex/graphics/metapost/. A recent

1. First published in Cahiers GUTenberg n o 41 — Novembre 2001. Authorized translation from the
French by Karel and Hanny Wesseling.

80 MAPS
 Practical metapost metapost

.3
.2
METAPOST metademo.1
metademo.mp
TeX
mpto
dvitomp
metademo.mpx

metademo.tex metademo.dvi metademo.ps

TEX dvips
Figure 1 Compilation process of a metapost file
CD-ROM copy of this archive, published by Lehmanns Fachbuchhandlung is regular-
ly distributed to members of tex users groups without charge, but can be ordered at
[email protected]

The basics of using METAPOST with LATEX

Let us start with the two needed source documents:
metademo.tex containing the latex document, and
metademo.mp with the metapost graphics composition.
The general structure of an example metapost file looks like:
0 prologues:=2 ;
color c[];
c1:=red; c2:=green+red; c3:=green; c4:=blue;

def star (expr size, n, pos, color) =

5 for a=0 step 360/n until 360 :
draw (origin -- (size/2,0))
rotatedaround (origin,a)
shifted pos withcolor color ;
endfor ;
10 enddef ;

for n = 1 upto 4:
beginfig(n) ;
pickup pencircle scaled 2mm ; star(2cm,n+n+3,origin,c[n]) ;
15 endfig ;
endfor ;

end

Compilation of this file with mpost produces a series of four postscript output files, each
containing one of the four declared figures (1) through (4) as shown below:
c:\>mpost metademo.mp
This is MetaPost, Version 0.641 (Web2c 7.3.3.1)
(metademo.mp [1] [2] [3] [4] )
4 output files written: metademo.1 .. metademo.4
Transcript written on metademo.log.
It is now time to include the figures just generated in your .tex document. This is simple
when you are using a recent latex version in which the graphicx package treats the files
output by metapost as if they were Postscript.

Najaar 2002 81
metapost Fabrice Popineau

For older versions you might consider renaming the files such that the file exten-
sion becomes .eps. For example, rename metademo.1 to metadem1.eps. These files
can then be handled without problems. Perhaps a better solution is to add a line
\DeclareGraphicsRule with parameters as shown in the latex document below. This
line specifies to latex that files included with the \includegraphics command that have
an extension that is not recognized should be treated as postscript files.
0 \documentclass[a4paper,11pt]{article}
\usepackage{graphicx}

\begin{document}

5 Some ‘‘stars’’ taken from the MetaFun manual:\\[4mm]

\includegraphics[width=1.5cm]{metademo.1} \hfill
\includegraphics[width=1.5cm]{metademo.2} \hfill
\includegraphics[width=1.5cm]{metademo.3} \hfill
10 \includegraphics[width=1.5cm]{metademo.4}

\end{document}

Now compile this file and pass it to dvips to obtain a postscript file which looks like the
starry result below.

In its default configuration, metapost does not create encapsulated, i.e. self contained,
postscript but as long as you compile to DVI and use dvips exclusively to obtain a
postscript output file, there is no problem. But if you want to use the postscript generat-
ed by metapost with other applications such as Adobe Illustrator for example, you must
include in your .mp file a prologue variable which is given the value 2, as we saw in the
metapost program above, as follows:
prologues := 2 ;
This variable is 0 by default. A positive value forces metapost to generate encapsu-
lated postscript. Use a value of 1 for troff, 2 for dvips. With a prologue value of
2, metapost will look for the file psfonts.map, the font map file that is usually read by
dvips. These mappings, however, are not included in the metapost output file. Thus,
they have to be supplied together with the output, unless they already are resident in the
target application. The immediate drawback of this approach is that you face problems as
soon as non--ASCII character codes are used. The code vectors assumed by dvips will
simply be ignored by other applications.

METAPOST and PDF

metapost maintains a particular relationship to pdf, even though it generates code that
could be a priori incompatible with pdf. Fortunately, the range of instructions that meta-
post uses is a sufficiently small subset of postscript that it is more or less “accidentally”
compatible with the pdf operators.

82 MAPS
Practical metapost metapost

The context system 2 contains a module supp-pdf that permits the direct conversion
by tex of eps files produced by metapost into pdf instructions. The advantage of this
module is that it is independent of context and can be used in other environments, for
example latex. When used in conjunction with pdftex, the graphicx package recog-
nizes .mps files containing metapost instructions and charges supp-pdf with the conver-
sion of such graphics.
However, metapost produces graphic output files with extensions .1, .2 and so on, so
we have to tell the graphicx package that such files are actually .mpsfiles. Therefore we
always add an IF statement as follows:
\usepackage{ifpdf}
...
\ifpdf
\DeclareGraphicsRule{*}{mps}{*}{*}
\else
% Recent LaTeX versions don’t require the next line
% \DeclareGraphicsRule{*}{eps}{*}{*}
\fi
Thus we see that metapost vector graphics files are compatible with postscript as well
as pdf output. The same source files serve two output formats, and there is no need to
keep and maintain two file versions, one for each output type.
context has an equally easy utility to achieve this called mptopdf. It is a Perl script
accompanied by a reduced format file mptopdf.efmt that automatically includes the nec-
essary commands when compiling metapost files through texexec, the context work
bench of many uses.
context also offers a new format for metapost called MetaFun which loads its pro-
prietary macros on top of those of metapost. They include flashy effects such as the one
demonstrated below (figure 2): a graded background to a line of text, going from red to
yellow and back to red again.
Circular shade background
Figure 2 MetaFun’s
shady background.

Integration of METAPOST graphics in your source document

With \write18, which is part of the Web2C system, it has become possible, finally, to
include metapost graphics transparently in your tex document, i.e. that graphics com-
pilation is automatically launched by tex at the time of the compilation of the main
document. But note: for security reasons the \write18 command is disabled by default.
To make it operational you must call tex with the option -shell_escape, or you could
modify your texmf.cnf file. Look for:
% Enable system commands via \write18{...}?
shell_escape = t
context is the first provider of an environment to fully exploit the possibilities of meta-
post graphics integration in the body of a source document. See how it is done in practice
by reading the code below which produces the effect shown in figure 2 above:

2. context, whose principal author is Hans Hagen, is a complete text composition system more
modern and more ambitious than latex. For more information on context look at the NTG Web
site www.ntg.nl/context/

Najaar 2002 83
metapost Fabrice Popineau

0 \definecolor[a][yellow]
\definecolor[c][darkred]

\startuniqueMPgraphic{CircularShade}
path p ;
5 p := unitsquare xscaled \overlaywidth
yscaled \overlayheight ;
circular_shade(p,0,\MPcolor{a},\MPcolor{c}) ;
\stopuniqueMPgraphic

10 \defineoverlay[circular shade]
[\uniqueMPgraphic{CircularShade}]
\framed[background=circular shade,frame=off]
{\bf Circular shade background}

A powerful aspect of context is that it offers extensive possibilities of information ex-

change between tex and metapost since tex may pass parameters to metapost because
its macros are expanded in time before the metapost file is generated. And using its
driver modules, context can create graphics perfectly encapsulated in typeset text com-
posed by tex or vice versa, as shown above with the shading example. This requires,
of course, several compilation passes: the first generates the graphic definition file, the
second composes the ensemble of text and graphics; between the runs metapost is called.
When write18 is enabled, only one pass is needed.
This pleasant property of context of the fusion of figures and text in one single doc-
ument has also been ported lately to latex thanks to the emp package which stands for
Embedded MetaPost. This package can be used to produce effects similar to the example
above, as demonstrated with the listing below, and the result shown in figure 3:
0 \documentclass[a4paper,11pt]{article}
\usepackage{palatino}
\usepackage{mflogo,graphicx,emp,ifpdf}

\ifpdf
5 \DeclareGraphicsRule{*}{mps}{*}{}
\fi

\begin{document}

10 % Commands included in the Metapost file:

\empaddtoTeX{%
\usepackage{palatino}
}

15 % Start of metapost figures

\begin{empfile}
% General definitions:
\begin{empcmds}
color yellow ; yellow := red + green ;
20 \input mp-spec ; % or \input metafun ;
\end{empcmds}
% First Metapost figure:
\begin{empdef}[fig1](5cm,5cm)
draw fullsquare withcolor .625red ;
25 draw fullsquare rotated 45 withcolor .625red ;
picture cp ; cp := currentpicture ;
def copy = addto currentpicture also cp enddef ;
copy scaled .9 withcolor .625white ;

84 MAPS
 Practical metapost metapost

copy scaled .7 withcolor .625yellow ;

30 copy scaled .6 withcolor .625white ;
copy scaled .4 withcolor .625red ;
copy scaled .3 withcolor .625white ;
fill fullcircle scaled .2 withcolor .625yellow ;
currentpicture := currentpicture scaled 50 ;
35 \end{empdef}
% (more figure can follow)
\end{empfile}
% On-the-fly metapost compilation:
\immediate\write18{mpost -tex=latex \jobname}

Example of a \MP\ figure included in the body of a \LaTeX\ document.

\begin{figure}[ht]
\begin{center}
\empuse{fig1}
45 \caption{A \MP{} graphic embedded in a \LaTeX\ document}
\end{center}
\end{figure}

\end{document}

Figure 3 A metapost graphic

embedded in a Latex document.

Unfortunately, and unlike in context, the emp package does not allow the exchange of
parameters between tex and metapost.

Conclusion
I hope that with this publication I have eliminated most of the practical difficulties that
one may meet initially when attempting to use metapost. I also hope to have induced
you to undergo the joys of geometry graphics. Bonne chance. Good luck.

Najaar 2002 85