% \iffalse meta-comment
%
% Copyright (C) 2011 by Enrico Gregorio
% <Enrico dot Gregorio at univr dot it>
% -------------------------------------------------------
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3c of this license or (at your option) any
% later version. The latest version of this license is in
% http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions
% of LaTeX version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Enrico Gregorio.
%
% This work consists of the files
% gmp.dtx
% gmp.ins
% and the derived file gmp.sty.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{gmp.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[2008/04/05]
%<package>\ProvidesPackage{gmp}
%<*package>
[2011/03/10 v1.0 Integrate MetaPost with LaTeX (EG)]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage[shellescape,tex]{gmp}
\usepackage{url,float,microtype}
\usepackage{metalogo,mflogo,color}
\floatstyle{ruled}
\restylefloat{figure}
\restylefloat{table}
% \newenvironment{averbatim}{\verbatim}{\endverbatim}
\newenvironment{annotation}
{\par\addvspace{\medskipamount}\footnotesize}
{\par\addvspace{\medskipamount}}
\newcommand{\cmdname}[1]{\texttt{\char`\\#1}}
\renewcommand{\meta}[1]{$\langle$\textnormal{\itshape#1\/}$\rangle$}
\renewcommand{\marg}[1]{\texttt{\char`\{#1\char`\}}}
\renewcommand{\oarg}[1]{\texttt{[#1]}}
\newcommand{\scratchcount}[1]{%
\begin{mpost}
n:=#1;
height := 3/5\mpdim{\baselineskip} ;
span := 1/3 * height ;
drift := 1/10 * height ;
pickup pencircle scaled (1/12 * height) ;
def d = (uniformdeviate drift) enddef ;
for i := 1 upto n :
draw
if (i mod 5)=0 : ((-d-4.5span,d)--(+d-0.5span,height-d))
else : ((-d,+d)--(+d,height-d)) fi
shifted (span*i,d-drift) ;
endfor;
picture cp ;
cp := currentpicture ; % for readability
setbounds currentpicture to
(llcorner cp shifted (0,-ypart llcorner cp) --
lrcorner cp shifted (0,-ypart lrcorner cp) --
urcorner cp -- ulcorner cp -- cycle) ;
\end{mpost}}
\makeatletter
\newenvironment{scratchenum}{\begin{enumerate}%
\@namedef{label\@enumctr}{\scratchcount{\arabic{\@enumctr}}}%
}{\end{enumerate}}
\makeatother
\newcommand\VCEN[1]{$\vcenter{\hbox{#1}}$}
\newcommand\lista[2][black]{%
\VCEN{%
\begin{mpost}[
%mpcommands={n:=#3;color fuzzy_color ; fuzzy_color:=#1 ;},
mpmem=metafun]
n:=#2 ; color fuzzy_color ; fuzzy_color:=#1 ;
height := 5pt ;
span := 1/3 * height ;
drift := 1/10 * height ;
hsize := .7\mpdim{\linewidth} ;
vstep := 10pt ;
xmax := hsize div 5span ;
pickup pencircle scaled (1/12 * height) ;
def d = (uniformdeviate drift) enddef ;
for i := 1 upto n :
xpos := ((i-1) mod (5*xmax))*span ;
ypos := ((i-1) div (5*xmax))*vstep ;
draw
if (i mod 5)=0 : ((-d-4.5span,d)--(+d-0.5span,height-d))
else : ((-d,+d)--(+d,height-d)) fi
shifted (xpos,-ypos+d-drift) withcolor fuzzy_color ;
endfor;
picture cp ;
cp := currentpicture ; % for readability
if (ypart ulcorner cp - ypart llcorner cp) <= vstep :
setbounds currentpicture to
(llcorner cp shifted (0,-ypart llcorner cp) --
lrcorner cp shifted (0,-ypart lrcorner cp) --
urcorner cp -- ulcorner cp -- cycle) ;
fi
\end{mpost}}%
}
\newsavebox{\tacochapterbox}
\newcommand{\tacochapterhead}[1]{%
\sbox\tacochapterbox{\Large\bfseries #1}%
{\ooalign{%
\MPclipOne{\mpdim{\wd\tacochapterbox+6pc}}
{\mpdim{\ht\tacochapterbox+3pc}}
{8}
{(.7,.7,.7)}
{red}
\cr
\hfill\raisebox{\dimexpr.5\ht\tacochapterbox+1.5pc\relax}
{\box\tacochapterbox}\hfill}}}
\def\MPclipOne#1#2#3#4#5{\begin{mpost}
w := #1; width := 100; wfactor := w/width;
h := #2; height := 100; hfactor := h/height;
color lightred; lightred := (.90,.50,.50);
color lightgray; lightgray := (.95,.95,.95);
color gray; gray := (.50,.50,.50);
def random_delta (expr d) =
d-(uniformdeviate 2d)
enddef;
z1 = (0,height);
z2 = (0,0);
z3 = (width,0);
z4 = (width,height);
z5 = (width+random_delta(.2width),height+random_delta(.2height));
z6 = (.5width+random_delta(.1width),height+random_delta(.1height));
pickup pencircle
xscaled (#3/wfactor)
yscaled (#3/(2*hfactor))
rotated 30;
draw z5..z1..z2..z3..z4..z6 withcolor #4;
pickup pencircle
xscaled (#3/wfactor)
yscaled (#3/hfactor);
draw z1 withcolor #5;
draw z2 withcolor #5;
draw z3 withcolor #5;
draw z4 withcolor #5;
draw z5 withcolor #5;
draw z6 withcolor #5;
newwidth := (xpart (urcorner currentpicture)) -
(xpart (llcorner currentpicture));
newheight := (ypart (urcorner currentpicture)) -
(ypart (llcorner currentpicture));
currentpicture := currentpicture
xscaled (w/newwidth) yscaled (h/newheight);
\end{mpost}}
\newcommand{\squares}[2][black]{%
\begin{mpost}
boolean timetofillbox;
sfactor:=.95;
path p,q; u:=\mpdim{#2\textwidth}/2;
p := (u,u) -- (-u,u) -- (-u,-u) -- (u,-u) -- cycle;
theta := 0; dtheta := .005;
forever:
theta := theta+dtheta;
q := p scaled sfactor rotated theta;
exitif ypart(point 0 of q) > u;
endfor;
fill p withrgbcolor #1; timetofillbox:=false;
for i:=1 upto 51:
p := p scaled sfactor rotated theta;
if timetofillbox:
fill p withrgbcolor #1; timetofillbox:=false;
else:
fill p withrgbcolor white-#1; timetofillbox:=true;
fi
endfor
\end{mpost}}
\urldef\messageurl\url
{http://groups.google.com/group/comp.text.tex/browse_frm/thread/516fb024bb83bcda}
\setcounter{secnumdepth}{1}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
\DocInput{gmp.dtx}
\PrintChanges
\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{698}
%
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
% Digits \0\1\2\3\4\5\6\7\8\9
% Exclamation \! Double quote \" Hash (number) \#
% Dollar \$ Percent \% Ampersand \&
% Acute accent \' Left paren \( Right paren \)
% Asterisk \* Plus \+ Comma \,
% Minus \- Point \. Solidus \/
% Colon \: Semicolon \; Less than \<
% Equals \= Greater than \> Question mark \?
% Commercial at \@ Left bracket \[ Backslash \\
% Right bracket \] Circumflex \^ Underscore \_
% Grave accent \` Left brace \{ Vertical bar \|
% Right brace \} Tilde \~}
%
%
% \changes{v1.0}{2011/03/10}{Initial version}
%
% \GetFileInfo{gmp.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment,\!,\",\%,\',\:,\;,\=,\?}
% \DoNotIndex{\@gobbletwo,\@ifundefined,\@makeother,\@nameuse,\@ne}
% \DoNotIndex{\@onlypreamble,\@temp,\^,\`,\|,\~,\active,\advance,\@nil}
% \DoNotIndex{\begin,\begingroup,\bgroup,\catcode,\chardef,\closeout}
% \DoNotIndex{\color,\count@,\csname,\def,\define@key,\dimexpr,\@gobble}
% \DoNotIndex{\do,\documentclass,\edef,\egroup,\else,\empty,\end,}
% \DoNotIndex{\endcsname,\endgroup,\endinput,\expandafter,\fbox,\fi}
% \DoNotIndex{\gdef,\global,\ifdefined,\IfFileExists,\ifnum,\ifx}
% \DoNotIndex{\immediate,\jobname,\label,\lccode,\let,\long,\loop}
% \DoNotIndex{\lowercase,\m@ne,\message,\MessageBreak,\newcounter}
% \DoNotIndex{\newif,\newlinechar,\newtoks,\noexpand,\number}
% \DoNotIndex{\PackageError,\PackageWarning,\PackageWarningNoLine}
% \DoNotIndex{\par,\refstepcounter,\relax,\repeat,\RequirePackage}
% \DoNotIndex{\space,\string,\the,\toks@,\usepackage,\x,\xdef,\z@}
%
%
% \title{The \textsf{gmp} package\thanks{This document
% corresponds to \textsf{gmp}~\fileversion, dated \filedate.}}
% \author{Enrico Gregorio \\ \texttt{enrico DOT gregorio AT univr DOT it}}
%
% \maketitle
%
% \begin{center}
% \tacochapterhead{Introduction}
% \end{center}
%
% Con\TeX{}t is far more superior to \LaTeX{} in its integration of
% \MP{}. On the other hand, few people are going to do the big jump
% towards Con\TeX{}t, especially if they have to use maths in their
% documents.
%
% Nonetheless, sometimes a better integration between \LaTeX{} and
% \MP{} would be welcome. One great package is \textsf{mfpic}, but
% its philosophy is different: it defines a set of \TeX{} macros which
% are afterwards interpreted as \MP{}. It suffers a bit from its
% \MF{} origin: the user has to pass the dimensions of the created
% figure in advance, while \MP{} is able to figure them out by itself.
%
% A very recent package does similar things as \textsf{gmp}, Vafa
% Khalighi's \mbox{\textsf{mpgraphics}}, from which I learned to add
% the \texttt{runs} and \texttt{clean} keys. However also Vafa's
% package can't pass parameters to the \MP{} pictures at run time.
% I~have to thank Vafa Khalighi because his \textsf{mpgraphics}
% package helped me to straighten some roughness from the preliminary
% version of this package. Another package is oriented to this
% purpose, \textsf{emp} by Thorsten Ohl, but it has not been updated
% since 1997.
%
% What I wanted was a package which could do \emph{automatically} the
% compilation of \MP{} output and, moreover, could pass parameters to
% \MP{}. Wouldn't it be nice being able to define a graphic object in
% terms of the current text width? Or of the current baseline skip?
% Or of some user defined parameter? A ``reusable'' object which can
% change depending on current conditions? This package is an answer;
% it runs under \LaTeX{}, \textsc{pdf}\LaTeX{} and
% \XeLaTeX{}.\footnote{It runs even under Lua\LaTeX{}, I'd say, but in
% this case it doesn't exploit the possibility of a direct call to the
% \MP{} library.}
%
% This has some consequences; for example, \MP{} labels will usually go
% inside
%\begin{verbatim}
%\btex ... etex
%\end{verbatim}
% instead of the normal \verb|btex ... etex|. Later examples will show
% this is an enrichment, rather than a limitation.
%
% \begin{mpost}[name=swelled]
% breadth=.667\mpdim{\linewidth};
% height=2pt;
% x1=0;
% x2=x6=.333x4;x5=x3=.667x4;
% x4=breadth;
% y1=y4=height/2;
% y2=y3=height;
% y5=y6=0;
% fill z1--z2--z3--z4--z5--z6--cycle;
% \end{mpost}
%
% Consider a swelled rule: we want its width to be two thirds of the
% line width. But, of course, we should not simply scale it when the
% line width changes. Here is an example; the swelled rule for the
% current line width:
% \begin{center}
% \usempost{swelled}
% \end{center}
% We follow it with a scaled version corresponding to half line width
% (on the left) and a true swelled rule constructed for a halved line
% width:
% \begin{center}
% % \scalebox{.5}[1]{\usempost{swelled}}\qquad
% \usempost[scale=.5]{swelled}\qquad
% \begin{mpost}
% breadth=.667\mpdim{\linewidth}/2;
% height=2pt;
% x1=0;
% x2=x6=.333x4;x5=x3=.667x4;
% x4=breadth;
% y1=y4=height/2;
% y2=y3=height;
% y5=y6=0;
% fill z1--z2--z3--z4--z5--z6--cycle;
% \end{mpost}
% \end{center}
%
% The difference is clear, but I must admit to have cheated: in this
% case it would be sufficient to scale the swelled rule only in the
% horizontal direction. However, scaling is not always the correct
% answer, since it affects all rule widths and character sizes, for
% example. You can see the input for the swelled rule in
% Figure~\ref{swelled-code}, taken from~Peter~\cite{peter2005}.
%
% \begin{figure}
% \centering
% \bigskip
% \usempost{swelled}\\*[3ex]
% \begin{minipage}{.5\linewidth}
%\begin{verbatim}
%\begin{mpost}[name=swelled]
%breadth=.667\mpdim{\linewidth};
%height=2pt;
%x1=0;
%x2=x6=.333x4;x5=x3=.667x4;
%x4=breadth;
%y1=y4=height/2;
%y2=y3=height;
%y5=y6=0;
%fill z1--z2--z3--z4--
% z5--z6--cycle;
%\end{mpost}
%\end{verbatim}
% \end{minipage}\\*[3ex]
% \usempost{swelled}
%
% \bigskip
% \caption{The code for the swelled rule}\label{swelled-code}
% \end{figure}
%
% The command \cmdname{mpdim} takes as an argument a length (rigid or
% rubber) and transforms it into a dimension understood by \MP{}
% (i.e., it strips off possible `plus' and `minus' specifications). To
% \MP{} eyes, it is an `unnamed variable' like `\texttt{whatever}',
% except that it has the value of the dimension given as argument; see
% the description in Section~\ref{commands}
%
% What I did was to define a \MP{} input for the swelled rule, to
% assign it a name and to use it when needed. For example, the above
% verbatim environment surrounded by swelled rules has been written as
% in Figure~\ref{averb}.
%
% \begin{figure}
% \centering\catcode`!=\active \def!{}
% \begin{minipage}{.5\linewidth}
%\begin{verbatim}
%\begin{center}
%\usempost{swelled}\\*[3ex]
%\begin{minipage}{.5\linewidth}
%\begin!{verbatim}
%\begin{mpost}[name=swelled]
%breadth=.667\mpdim{\linewidth};
%...
%\end{mpost}
%\end!{verbatim}
%\end{minipage}\\*[3ex]
%\usempost{swelled}
%\end{center}
%\end{verbatim}
% \end{minipage}
% \caption{The input for the nice verbatim}\label{averb}
% \end{figure}
%
% A recent message on \texttt{comp.text.tex}\footnote{\messageurl}
% asked how to realize in \LaTeX{} chapter headers like the ones in
% the manual ``Con\TeX{}t, an
% excursion''\footnote{\texttt{http://www.pragma-ade.nl/general/manuals/mp-cb-en.pdf}}
% and Taco Hoekwater kindly provided the code that's used. Here I
% propose a macro that solves the problem, once it's integrated in a
% chapter style for \textsf{memoir} or \textsf{titlesec}; the \MP{}
% code is found in table~\ref{taco} and the result is shown here
% \begin{center}
% \bigskip
% \tacochapterhead{How to draw graphics}
% \bigskip
% \end{center}
% Now you can return to the first page and see that the title for the
% introduction was typeset inside a similar drawing, but of different
% size. The \MP{} code is exactly the same as Taco's, except for the
% call of \texttt{mpost} instead of \cmdname{startMPgraphic} and
% \cmdname{endMPgraphic}. The \LaTeX{} code used is
%\begin{verbatim}
%\newsavebox{\tacochapterbox}
%\newcommand{\tacochapterhead}[1]{%
% \sbox\tacochapterbox{\Large\bfseries #1}%
% {\ooalign{%
% \MPclipOne{\mpdim{\wd\tacochapterbox+6pc}} % width
% {\mpdim{\ht\tacochapterbox+3pc}} % height
% {8} % thickness of the curve
% {(.7,.7,.7)} % color of the curve
% {red} % color of the spots
% \cr\hfill\raisebox{\dimexpr.5\ht\tacochapterbox+1.5pc\relax}
% {\box\tacochapterbox}\hfill}}}
%
%\tacochapterhead{How to draw graphics}
%\end{verbatim}
% Use a high level package such as \textsf{titlesec} in order to draw
% fancy ornaments around the chapter title; an example might be
%\begin{verbatim}
%\newcommand{\chapformat}[1]{\tacochapterhead{\thechapter.\ #1}}
%\titleformat{name=\chapter}[block]
% {\large\bfseries\filcenter}{}{0pt}{\chapformat}
%\titleformat{name=\chapter,numberless}[block]
% {\large\bfseries\filcenter}{}{0pt}{\tacochapterhead}
%\end{verbatim}
% which takes care also of numberless chapter headings.
%
% \begin{table}
% \caption{\MP{} code for a fancy chapter heading}\label{taco}
%\begin{verbatim}
%%macro arguments:
%%#1 = desired width
%%#2 = desired height
%%#3 = pen thickness (relative)
%%#4 = line color
%%#5 = dot color
%\def\MPclipOne#1#2#3#4#5%
% {\begin{mpost}
% w := #1; width := 100; wfactor := w/width;
% h := #2; height := 100; hfactor := h/height;
% color lightred; lightred := (.90,.50,.50);
% color lightgray; lightgray := (.95,.95,.95);
% color gray; gray := (.50,.50,.50);
% def random_delta (expr d) =
% d-(uniformdeviate 2d)
% enddef;
% z1 = (0,height);
% z2 = (0,0);
% z3 = (width,0);
% z4 = (width,height);
% z5 = (width+random_delta(.2width),height+random_delta(.2height));
% z6 = (.5width+random_delta(.1width),height+random_delta(.1height));
% pickup pencircle
% xscaled (#3/wfactor)
% yscaled (#3/(2*hfactor))
% rotated 30;
% draw z5..z1..z2..z3..z4..z6 withcolor #4;
% pickup pencircle
% xscaled (#3/wfactor)
% yscaled (#3/hfactor);
% draw z1 withcolor #5;
% draw z2 withcolor #5;
% draw z3 withcolor #5;
% draw z4 withcolor #5;
% draw z5 withcolor #5;
% draw z6 withcolor #5;
% newwidth := (xpart (urcorner currentpicture)) -
% (xpart (llcorner currentpicture));
% newheight := (ypart (urcorner currentpicture)) -
% (ypart (llcorner currentpicture));
% currentpicture := currentpicture
% xscaled (w/newwidth) yscaled (h/newheight);
% \end{mpost}}
%\end{verbatim}
% \end{table}
%
% Another useless application comes from the Metafun manual, by Hans
% Hagen~\cite{hagen-metafun}: a representation of a counter using
% vertical bars with a diagonal one after four of them, just like when
% counting on a piece of scratch paper. We can borrow the \MP{} input
% from Hans, and define the command you find in table~\ref{scratch}.
%
% \begin{table}
% \caption{The \texttt{\string\scratchcount} macro}\label{scratch}
%\begin{verbatim}
%\newcommand{\scratchcount}[1]{%
% \begin{mpost}
% n:=#1;
% height := 3/5\mpdim{\baselineskip} ;
% span := 1/3 * height ;
% drift := 1/10 * height ;
% pickup pencircle scaled (1/12 * height) ;
% def d = (uniformdeviate drift) enddef ;
% for i := 1 upto n :
% draw
% if (i mod 5)=0 : ((-d-4.5span,d)--(+d-0.5span,height-d))
% else : ((-d,+d)--(+d,height-d)) fi
% shifted (span*i,d-drift) ;
% endfor;
% picture cp ;
% cp := currentpicture ; %for readability
% setbounds currentpicture to
% (llcorner cp shifted (0,-ypart llcorner cp) --
% lrcorner cp shifted (0,-ypart lrcorner cp) --
% urcorner cp -- ulcorner cp -- cycle) ;
% \end{mpost}}
%\makeatletter
%\newenvironment{scratchenum}{\begin{enumerate}
% \@namedef{label\@enumctr}{\scratchcount{\arabic{\@enumctr}}}%
% }{\end{enumerate}}
%\makeatother
%\end{verbatim}
% \end{table}
%
% Now we have a new environment and we can use it at every nesting
% level:
% \begin{enumerate}
% \item A first item, to remember that \MP{} is a big fun, for the
% following reasons:
% \begin{scratchenum}
% \item it has a syntax very similar to \MF;
% \item it outputs very good PostScript;
% \item there are many people using it;
% \item it is very simple to use;
% \item it integrates easily with \LaTeX;
% \item some other reason just to arrive to six.
% \end{scratchenum}
% \item A second item, to remember that \LaTeX{} users can benefit from
% the use of \MP{}.
% \end{enumerate}
% The input for this nested enumeration was
%\begin{verbatim}
%\begin{enumerate}
% \item A first ...
% \begin{scratchenum}
% \item it has ...
% ...
% \end{scratchenum}
% \item A second ...
%\end{enumerate}
%\end{verbatim}
%
% Of course, if we need to use the \texttt{scratchenum} only at the
% first level of nesting, a definition such as
%\begin{verbatim}
%\newenvironment{scratchenum}
% {\begin{enumerate}
% \renewcommand{labelenumi}{\scratchcount{\arabic{enumi}}}%
% }
% {\end{enumerate}}
%\end{verbatim}
% would have sufficed. We give as argument to \cmdname{scratchcount}
% the representation of the counter as an arabic number; \MP{} does
% all the necessary calculations.
%
% \begin{figure}
% \centering
%\begin{verbatim}
%\newcommand\lista[2][black]{%
%\VCEN{\begin{mpost}[mpmem=metafun]
%n:=#2 ; color fuzzy_color ; fuzzy_color:=#1 ;
%
%height := 5pt ;
%span := 1/3 * height ;
%drift := 1/10 * height ;
%hsize := .7\mpdim{\linewidth} ;
%vstep := 10pt ;
%xmax := hsize div 5span ;
%
%pickup pencircle scaled (1/12 * height) ;
%def d = (uniformdeviate drift) enddef ;
%for i := 1 upto n :
% xpos := ((i-1) mod (5*xmax))*span ;
% ypos := ((i-1) div (5*xmax))*vstep ;
% draw
% if (i mod 5)=0 : ((-d-4.5span,d)--(+d-0.5span,height-d))
% else : ((-d,+d)--(+d,height-d)) fi
% shifted (xpos,-ypos+d-drift) withcolor fuzzy_color ;
%endfor;
%
%picture cp ;
%cp := currentpicture ; % for readability
%if (ypart ulcorner cp - ypart llcorner cp) <= vstep :
%setbounds currentpicture to
% (llcorner cp shifted (0,-ypart llcorner cp) --
% lrcorner cp shifted (0,-ypart lrcorner cp) --
% urcorner cp -- ulcorner cp -- cycle) ;
%fi
%\end{mpost}}}
%\end{verbatim}
% \caption{Expanded definition for the scratch numbers; the
% \protect\cmdname{VCEN} macro is for centering the object.}\label{expan}
% \end{figure}
%
% We can expand on this theme, to represent greater numbers. You can
% see it in Figure~\ref{expan}. After this, an input like
%\begin{verbatim}
%\begin{tabular}{llr}
%\multicolumn{2}{c}{\textbf{La lista}}\\\hline\\
%Italia & \lista[red]{640} & 640\\\\
%Alemagna & \lista{231} & 231\\\\
%Francia & \lista[red]{100}& 100\\\\
%Turchia & \lista{91}& 91\\\\
%Spagna & \lista[red]{1003} & 1003\\\\\hline
%\end{tabular}
%\end{verbatim}
% gives what you can see in figure~\ref{lalista}, but if we put it
% inside a \texttt{minipage}, we can render the same list in other
% ways, automatically. You see it in Figure~\ref{liste}.
%
% \begin{figure}
% \caption{La lista}\label{lalista}
% \centering
% \medskip
% \begin{tabular}{llr}
% Italia & \lista[red]{640} & 640\\\\
% Alemagna & \lista{231} & 231\\\\
% Francia & \lista[red]{100}& 100\\\\
% Turchia & \lista{91}& 91\\\\
% Spagna & \lista[red]{1003} & 1003\\
% \end{tabular}
%
% \medskip
% \end{figure}
%
% \begin{figure}
% \centering
% \scalebox{.7}{%
% \begin{minipage}{.5\linewidth}
% \begin{tabular}{ll}
% \multicolumn{2}{c}{\textbf{La lista}}\\\hline\\
% IT & \lista[red]{640}\\\\
% DE & \lista{231}\\\\
% FR & \lista[red]{100}\\\\
% TR & \lista{91}\\\\
% ES & \lista[red]{1003}\\\\\hline
% \end{tabular}
% \end{minipage}
% \quad
% \begin{minipage}{.4\linewidth}
% \begin{tabular}{ll}
% \multicolumn{2}{c}{\textbf{La lista}}\\\hline\\
% IT & \lista[red]{640}\\\\
% DE & \lista{231}\\\\
% FR & \lista[red]{100}\\\\
% TR & \lista{91}\\\\
% ES & \lista[red]{1003}\\\\\hline
% \end{tabular}
% \end{minipage}}
% \caption[]{The tables have been reduced at 70\%. On the right the
% table has been put in a \texttt{minipage}
% of size \texttt{.5\cmdname{linewidth}}; on the left the size was
% \texttt{.4\cmdname{linewidth}}}\label{liste}
% \end{figure}
%
% Note how we can pass to the \MP{} input some parameters, a
% dimension as before, and a color specification.
%
% It is not necessary to put \texttt{mpost} environments inside a
% definition, as we have already seen. We can assign a name to the
% object and use it as many times as we like, even subject to
% transformations with the same syntax as \cmdname{includegraphics}. The
% following example is from the \MP{} package \textsf{drv}, which
% requires a double run of \MP{}:
%\begin{verbatim}
%\begin{mpost}[runs=2,mpsettings={input drv;},name=der1]
%jgm 0 "A\vdash B";
%jgm 1 "B\vdash C";
%jgm 2 "A\vdash C";
%nfr 0 () ("f", 1);
%nfr 1 () ("g", 1);
%nfr 2 (0, 1) ("\circ", 1);
%draw drv_tree;
%\end{mpost}
%\usempost{der1}\quad
%\usempost[angle=90]{der1}
%\end{verbatim}
% \begin{center}
% \begin{mpost}[runs=2,mpxprogram=latex,
% mpsettings={input drv;},name=der1,use]
% jgm 0 "A\vdash B";
% jgm 1 "B\vdash C";
% jgm 2 "A\vdash C";
% nfr 0 () ("f", 1);
% nfr 1 () ("g", 1);
% nfr 2 (0, 1) ("\circ", 1);
% draw drv_tree;
% \end{mpost}\quad
% \usempost[angle=90]{der1}
% \end{center}
%
% If a \MP{} object is not assigned a name it is immediately used and,
% obviously, it cannot be used any more. Well, this is not strictly
% true: every object has a number corresponding to an \textsc{mps} file
% named \meta{filename}\texttt{+mp}\meta{number}\texttt{.mps} and it
% would be possible to include it in the usual way. Here
% \meta{filename} is the name of the root \LaTeX{} file. However, the
% \meta{number} is not fixed, since insertion of other objects before a
% certain one will change its assigned number.
%
% There are three ways for typesetting a document using \textsf{gmp},
% which correspond to the following package options:
% \begin{description}
% \item[\texttt{shellescape}] exploits the `shell escape' feature
% present in most \TeX{} distributions: every \texttt{mpost} environment
% calls a run of \MP{}, setting the object immediately (you have to call
% the typesetting engine with the necessary command line option, see
% later);
%
% \item[\texttt{noshellescape}] defers the \MP{} runs to the end of
% the \LaTeX{} run, the user has to launch them by hand---in this case a
% very simple shell script is written for doing all the business;
%
% \item[\texttt{nowrite}] inhibits writing \MP{} files and disables
% running \MP{}: when the document is finished and no more modifications
% to the \MP{} objects are needed, we can set this option and read the
% \textsc{mps} files already compiled in previous runs.
% \end{description}
%
% The `shell escape' feature is very handy, but someone may feel uneasy
% with it. For security reasons, \TeX{} distributions usually disable
% it by default and it must be explicitly requested by calling
% \begin{flushleft}
% \texttt{latex -shell-escape} \meta{filename}\\
% \texttt{pdflatex -shell-escape} \meta{filename}\\
% \texttt{xelatex -shell-escape} \meta{filename}
% \end{flushleft}
% depending on what engine you are using; see your system's
% documentation for the actual call: for \TeX~Live the command line
% option \texttt{-shell-escape}, while for MiK\TeX{} it's
% \texttt{-enable-write18}.
%
% In case some \MP{} graphics doesn't compile properly, it's better to
% switch to \texttt{noshellescape} and launch the shell script after a
% new \LaTeX{} run: from a terminal window say
% \texttt{sh~\meta{filename}+mp.sh}, where \meta{filename} stands for
% your main document's name. This will run \MP{} in `error stop mode',
% so that you'll probably get a clue about what is going wrong.
%
% If one uses \XeLaTeX{}, all \textsc{mps} files will be converted to
% \textsc{pdf} via \texttt{epstopdf}.
%
%
% \section{The name of the package and its workings}
%
% I wanted a successor of \textsf{emp}, but \textsf{fmp} was out of the
% question: this is a package for including functional \MP{} in
% \LaTeX. So I chose \textsf{gmp}.
%
% Here is a brief description of how the package works. A \MP{}
% object is defined through a \texttt{mpost} environment
% (see~Section~\ref{envoptions}). When such an environment is found,
% an external \MP{} file is written and processed (either immediately
% or after the \LaTeX{} run, at the user's choice). After processing,
% a file called \meta{filename}\texttt{+mp}\meta{number}\texttt{.mps}
% is produced, which is then included in the \LaTeX{} output with
% \cmdname{includegraphics}, but without user's intervention. If the
% object is assigned a name, it can be included as many times as
% desired.
%
% The \textsf{gmp} package depends on \textsf{xkeyval},
% \textsf{ifxetex}, \textsf{ifpdf} and, of course,
% \textsf{graphicx}. If you have to pass options to this one, load it
% before \textsf{gmp}.
%
%
% \section{File names}
%
% This package \emph{doesn't} support file names containing
% spaces. Quoting D.~E.~Knuth, if you're upset about this, you shouldn't
% be: spaces in file names might be supported, but every system has its
% idiosyncrasies and quotes around the name aren't always the correct
% answer. Avoiding strange characters in file names is the best strategy
% for being compatible with most platforms.
%
%
% \section{To do}
%
% Find out a way to coerce creation of all auxiliary files in a
% subdirectory of the current directory, in order not to fill it with
% junk, besides what's really necessary.
%
%
% \section{The package options}\label{options}
%
% We have seen some of the package options, but now I will present them
% more formally. Some of them will be grouped together; the first one
% of the group is the default.
%
% \subsection{\texttt{tex} and \texttt{latex}}
%
% \MP{} is able to use either Plain \TeX{} or \LaTeX{} for typesetting
% the `labels'. If you are using ten point type and the usual Computer
% Modern fonts or no label at all, it is not necessary to set this
% option (the default is \texttt{tex}). On the other hand, if you are
% using different fonts or different type sizes, then \texttt{latex} is
% necessary. The package creates a crude preamble keeping the type size
% of your document; insertion of any other package or of a different
% class must be explicitly done with the commands \cmdname{usempxclass}
% and \cmdname{usempxpackage} which have the same syntax as
% \cmdname{documentclass} and \cmdname{usepackage}. See
% Section~\ref{commands} for a description of the commands; their names
% should remember that they are used for an `extension' of \MP{}, namely
% the preprocessor that typesets the labels making them into \MP{}
% pictures. However the option can be overridden for any picture, see
% later on.
%
% \subsection{\texttt{noshellescape} and \texttt{shellescape}}
%
% The \texttt{shellescape} option uses the \verb|\write18| feature found
% in many \TeX{} distributions (all the up-to-date ones based on
% \textsf{Web2C} such as \TeX~Live, and MiK\TeX{}). Its purpose is to
% stop momentarily the \TeX{} compilation for executing the \MP{} run
% after a \texttt{mpost} environment has been found. \LaTeX{} or
% \textsc{pdf}\LaTeX{} have to be called with the \texttt{-shell-escape}
% command line option or \texttt{-enable-write18} on MiK\TeX.
%
% With \texttt{noshellescape} all shell commands are collected in a
% batch file and \LaTeX{} will remember users to execute it at the end
% of the run. On the subsequent \LaTeX{} run, all objects should be in
% place.
%
% When a compiled \MP{} object is not found at the proper place, a box
% like the one in the%
% \marginpar[\hfill\csname gmp@box\endcsname]{\csname gmp@box\endcsname}%
% margin is printed. The same will happen in presence of compilation
% errors, precisely when the proper \textsc{mps} file is not found.
%
% When using the \texttt{noshellescape} option, it may happen that
% after a compilation the objects are misplaced, for example if some
% new object has been added; running \MP{} on the created files and
% another \LaTeX{} run should fix this. The default option is
% \texttt{noshellescape}.
%
%
% \subsection{\texttt{write} and \texttt{nowrite}}
%
% The \texttt{nowrite} option is useful when all \MP{} objects are
% present in the document, they are in their final form and all of
% them have been processed. By setting the \texttt{nowrite} option,
% no writing of \MP{} files and no compilation take place, speeding up
% the process. I would have called this option \texttt{final} and its
% contrary \texttt{draft}, but this usage conflicts with the workings
% of \textsf{graphicx}. The default option is \texttt{write}, so it's
% not necessary to specify it.
%
%
% \subsection{\texttt{envname}}
%
% You can change the name of the environment for the \MP{} objects;
% the default is \texttt{mpost}. If you don't like it or you want this
% name for your favorite environment, you can say
% \begin{flushleft}
% \texttt{envname=}\meta{string}
% \end{flushleft}
% and \meta{string} will be used for introducing \MP{} objects. This
% key must be specified only as a package option, not in the argument
% of \cmdname{gmpoptions}.\footnote{Actually it can be in
% \cmdname{gmpoptions}, but there it has no effect.}
%
%
% \subsection{\texttt{extension}}
%
% If the root \LaTeX{} file is called \texttt{file}, then the compiled
% \textsc{mps} files will be named
% \texttt{file+mp}\meta{number}\texttt{.mps}. The string \texttt{+mp} is
% the \emph{mp-extension}, which can be modified by saying
% \begin{flushleft}
% \texttt{extension=}\meta{string}
% \end{flushleft}
% in the options to \textsf{gmp}; the \meta{string} should consist only
% of printable ASCII characters with no special meaning to \TeX{}. So,
% with a main file called \texttt{paper.tex}, the created files will be
% named \texttt{paper+mp0001.mp} and so on; with
%\begin{verbatim}
%\gmpoptions{extension=--mp--}
%\end{verbatim}
% the names will be \texttt{paper--mp--0001.mp} and so on. \emph{Don't
% use a slash} in the mp-extension! Leave this option to the default
% value, unless you happen to have files whose name contains the string
% \texttt{+mp}.
%
%
% \subsection{\texttt{everymp}}
%
% Here you can set whatever you want to be present in all \MP{}
% objects, for example input files. Any set of \MP{} statements
% can be given in braces, for example
%\begin{verbatim}
%everymp={input boxes;}
%\end{verbatim}
% Since these are \MP{} statements, don't forget the trailing
% semicolon. If you have a long list of \MP{} macros that should be
% loaded for each picture, it's better to save them in a file and input
% this one with the \texttt{everymp} key. When your document uses font
% packages, you may need to say
%\begin{verbatim}
%everymp={prologues=3;}
%\end{verbatim}
% so that your \textsc{mps} files will contain correct references to
% the fonts; this is automatically done when the typesetting engine is
% \XeLaTeX{}.
%
% \subsection{\texttt{clean=none\string|aux\string|mp}}
%
% After the compilation, there will be many auxiliary files around. The
% essential ones are only those necessary for the picture inclusion,
% namely the \textsc{mps} or \textsc{pdf} final results. With
% \texttt{clean=none} nothing will be removed, with \texttt{clean=aux}
% the files with extension \texttt{.log}, \texttt{.mpx} and
% \texttt{.mpo} created during the \MP{} runs will be deleted. Also the
% \texttt{.mp} files will be deleted with \texttt{clean=mp}; this option
% will erase also the \texttt{.mps} files when \XeLaTeX{} is used.
%
% Some strange files will remain, particularly when there's some error
% during one of the \MP{} runs; this is why I chose not to delete them.
% It's best to use \texttt{clean=none}, which is the default, at the
% beginning, changing to \texttt{clean=aux} when everything seems to be
% alright and \texttt{clean=mp} for the last check before setting
% \texttt{nowrite}.
%
% In case you are worried about what files will be deleted, run with the
% \texttt{noshellescape} options and have a look at the shell script
% that's created: it will show at its end the remove commands that will
% be run. Or just don't set anything, so that \texttt{clean=none} will
% be in force.
%
%
% \subsection{\texttt{rmcommand}}
%
% The default command for cleaning the directory is \texttt{rm~-f}. Of
% course this is system dependent and those on
% Windows$^{\scriptscriptstyle\mathrm{TM}}$ systems might want to set
% \texttt{rmcommand=del}.
%
% \subsection{\texttt{postrmcommand}}
% The value of the key \texttt{postrmcommand} is usually empty; you can
% obtain a `safe removing' by setting something like
%\begin{verbatim}
%\gmpoptions{rmcommand=mv,postrmcommand=junk}
%\end{verbatim}
% This will be translated into commands such as
%\begin{verbatim}
%mv filename+mp*.log junk
%\end{verbatim}
% so if you have a subdirectory called \texttt{junk} all the auxiliary
% files will be moved into it, instead of being deleted.
%
%
% \section{Commands}\label{commands}
%
%
% \subsection{\cmdname{gmpoptions}\marg{\meta{options}}}
%
% All package options can be given either as an optional argument to
% \cmdname{usepackage} or as an argument to \cmdname{gmpoptions}. This
% command can be given multiple times, with cumulative effect, but only
% in the preamble. However the \texttt{envname} option has no effect
% here.
%
%
% \subsection{\cmdname{usempxclass}%
% \oarg{\meta{options}}%
% \marg{\meta{class}}}
%
% This has the same syntax as \cmdname{documentclass}. Its purpose is
% to declare the class used for the runs of \TeX{} or \LaTeX{} for
% preparing the \texttt{mpx} files which \MP{} needs to draw the text
% labels. It should be not necessary to change it from the default
% (which is \texttt{article}). But if you are using a non standard
% class with a non standard type size (i.e., not 10, 11 or 12 point
% size), then you \emph{will need} to declare a class, otherwise your
% labels will be typeset in 10~point type. Of course this has no effect
% for \MP{} objects where the \TeX{} format to be used is Plain~\TeX{}.
%
%
% \subsection{\cmdname{usempxpackage}%
% \oarg{\meta{options}}%
% \marg{\meta{package\textup(s\textup)}}}
%
% Same syntax as \cmdname{usepackage}. It can be given multiple times
% and its effects are cumulative. Thus, if your main text font is
% Palatino, you have to give
%\begin{verbatim}
%\usepackage{palatino}
%\usempxpackage{palatino}
%\end{verbatim}
% I chose not to modify the standard \cmdname{usepackage} command
% because some packages make no sense inside \MP{} objects and it
% would be useless and time consuming to load them. Just think to the
% \textsf{pgf} package, for example: while a user may very well employ
% this one alongside with \textsf{gmp}, it would be very questionable to
% load \textsf{pgf} during a \LaTeX{} run to compile a \MP{} graphic
% object, albeit not forbidden.
%
% If your labels in \MP{} pictures use special characters (the accented
% ones, for instance), you \emph{must} load the \textsf{inputenc} package
% \emph{with the same option} as your main file:
%\begin{verbatim}
%...
%\usepackage[latin1]{inputenc}
%...
%\usepackage{gmp}
%\gmpoptions{...}
%\usempxpackage[latin1]{inputenc}
%...
%\end{verbatim}
% You can use any encoding with (\textsc{pdf})\LaTeX{}; set the
% \texttt{utf8} or \texttt{utf8x} option when your main document is
% typeset with \XeLaTeX{}.
%
% Both \cmdname{usempxpackage} and \cmdname{usempxclass} respect the
% usual scoping rules, so you can modify the class or the packages used
% for a particular \MP{} object by enclosing the commands in a group,
% for example in an environment such as \texttt{figure}. But no, not in
% the \texttt{mpost} environment itself, sorry.
%
%
% \subsection{\cmdname{resetmpxpackages}}
%
% This command resets to empty the list of packages to be loaded,
% obeying to the normal scoping rules.
%
%
% \subsection{\cmdname{mpxcommands}\marg{\meta{commands}}}
%
% With this command you can add \LaTeX{} commands to be executed for
% every run of \MP{}, when typesetting labels; for instance, your
% favorite definitions. Also the effect of this command is cumulative.
% Pay attention that this works only if the program used for compiling
% the \texttt{mpost} figures is \LaTeX{}. Like the commands for
% choosing the class and the packages, this one obeys the scoping rules.
%
% \subsection{\cmdname{resetmpxcommands}}
%
% This command resets the list of commands to empty, obeying to the
% normal scoping rules.
%
%
% \subsection{\cmdname{mpdim}\marg{\meta{dimen parameter}}}
%
% This command takes as argument a length, i.e., a \LaTeX{} parameter or
% a command defined by \cmdname{newlength} or operations on lengths.
% Its output is the length in points; if the length is a rubber one, the
% `plus' and `minus' parts are ignored. You can even use as argument an
% explicit length such as `\texttt{2cm}', although this would be
% overkill. However, you can give as argument some calculation with
% \cmdname{dimexpr} syntax, such as
%\begin{verbatim}
%\mpdim{2ex+\baselineskip}
%\mpdim{3em-1pt}
%\end{verbatim}
% which might be useful, because the \texttt{ex} and \texttt{em} units
% change with the current font size. Don't add \cmdname{relax}, it's
% automatically provided.
%
% \begin{annotation}
% \TeX{}nical note. The command \cmdname{mpdim} works without making
% assignments, so that it is fully expandable at the moment of the
% \cmdname{write} to the \MP{} external file. It uses internally
% \cmdname{the} and \cmdname{dimexpr}. When the \cmdname{write} takes
% place, the command is expanded and the output is
% \begin{flushleft}
% \ttfamily
% begingroup \meta{thedimen} endgroup
% \end{flushleft}
% where \meta{thedimen} is the value of the \meta{dimen} given as
% argument. Therefore the construction
% \cmdname{mpdim}\marg{\meta{dimen}} behaves like a number as far as
% \MP{} is concerned; for Metapost, dimensions are simply numbers and
% the units are just multipliers.
% \end{annotation}
%
%
% \subsection{\cmdname{usempost}}
%
% This command takes as its argument a string already assigned as a name
% to a \MP{} object. Its effect is to place the graphic object where
% the command appears. The complete syntax is
% \begin{flushleft}
% \cmdname{usempost}\oarg{\meta{options}}\marg{\meta{string}}
% \end{flushleft}
% where \meta{string} is the name of an already introduced and named
% \MP{} object and \meta{options} are any options that make sense for
% the \cmdname{includegraphics} command provided by the
% \textsf{graphicx} package.
%
%
% \section{Environments}
%
% The package provides two environments, whose default names are
% \texttt{mpost} and \texttt{mpost*}. The name, however, can be changed
% in the package options, as we have already seen. In the descriptions
% below I'll use the default name.
%
% Commands in the body of the \texttt{mpost} environment \emph{are}
% interpreted and expanded and this is the main feature offered by this
% package.
%
% The main difference between \texttt{mpost} and \texttt{mpost*} is that
% in the second one there is no expansion at all: every \MP{} statement
% in the environment's body is written out as it is for subsequent
% processing. Therefore \texttt{mpost*} behaves like \texttt{emp} or
% \texttt{mpgraphics} of the respective packages, but the difference is
% that it \emph{can} go in the argument to a command. This behavior
% costs us something: \LaTeX{} environments in \MP{} labels \emph{must}
% be enclosed in a pair of braces in the same \texttt{btex...etex}
% construction. So don't say
% \begin{flushleft}\color{red}
%\begin{verbatim}
%btex ... $\begin{array}{c}a\\b\end{array}$ ... etex
%\end{verbatim}
% \end{flushleft}
% but rather
%\begin{verbatim}
%btex ... {$\begin{array}{c}a\\b\end{array}$} ... etex
%\end{verbatim}
% See later on for details. The same holds for the \texttt{mpost}
% environment, with one more little catch, see page~\pageref{btex}.
%
% There is no |\inputmpost| command: if you really need it, just
% define
%\begin{verbatim}
%\newcommand{\inputmpost}[2][1]{\begin{mpost}[#1]input #2;\end{mpost}}
%\end{verbatim}
% The \MP{} file you input this way should contain just statements
% that would go in a normal \texttt{mpost} environment.
%
%
% \section{Options to the environments}\label{envoptions}
%
% Actually, the name of the two environments provided by this package
% can be chosen by the user on a per document basis with the package
% option \texttt{envname}. I will use the default name in the
% description. The syntax is
% \begin{flushleft}
% \cmdname{begin}\marg{mpost}\oarg{\meta{options}}\\
% \meta{\MP{} statements}\\
% \cmdname{end}\marg{mpost}\\[3ex]
% \verb|\begin{mpost*}[|\meta{options}\verb|]|\\
% \meta{\MP{} statements}\\
% \verb|\end{mpost*}|
% \end{flushleft}
%
% The \meta{options} are in the form \meta{key}\texttt{=}\meta{value}.
% They influence only the current environment and are the same for the
% two varieties (\texttt{mpost} and \texttt{mpost*}).
%
%
% \subsection{\texttt{name}}
%
% With \texttt{name=}\meta{string} you assign the object a name for
% subsequent multiple use with \cmdname{usempost}\marg{\meta{string}}.
% For example, if the object is some symbol to be employed many times,
% you can say
%\begin{verbatim}
%\begin{mpost}[name=mysymbol]
%...
%\end{mpost}
%\newcommand{\mynicesymbol}{%
% \usempost[height=.7\ht\strutbox]{mysymbol}}
%\end{verbatim}
% In this case you cannot pass arguments to the \texttt{mpost}
% environment: the object is \emph{frozen} apart from modifications with
% the optional argument to \cmdname{usempost}. In this case the symbol
% we have built with \MP{} will change size according to the current
% font size, but only by scaling.
%
% The \meta{string} used as a name should consist only of ASCII
% printable characters; no accented letters, please, just like for
% \LaTeX{} labels (those for \cmdname{label}). If you specify this key,
% then the object will not appear unless you specify also \texttt{use},
% see below. The proper place for named environments is usually the
% preamble.
%
% \begin{annotation}
% Suppose you have to write the symbol for a square wave in different
% sizes; instead of using only one \textsc{mps} graphic file and scaling
% it you may want to define a couple of them. Say, for instance, that
% you need it also in section titles, which are typeset in
% \cmdname{Large} size and bold face and that the symbol's height is the
% same as a lowercase letter. You can get the two versions which are
% automatically chosen among with the following code:
%\begin{verbatim}
%\makeatletter
%\newcommand{\sqwave}{\usempost{sqwave\f@size\f@series}}
%\newcommand{\sqwavebody}{%
% u:=\mpdim{1ex};
% pickup pencircle scaled \mpdim{.05em};
% draw (0,0)--(2/3u,0)--(2/3u,u)--(u,u)--(u,0)--(5/3u,0);}
%{\normalsize
%\begin{mpost}[name=sqwave\f@size\f@series]\sqwavebody\end{mpost}
%}
%{\Large\bfseries
%\begin{mpost}[name=sqwave\f@size\f@series]\sqwavebody\end{mpost}
%}
%\makeatother
%\end{verbatim}
% Then simply say \cmdname{sqwave} when you need the symbol. If you
% change the type size of your document, you'll get the proper symbol's
% height. If it turns out that you need the symbol also in other
% contexts, just add other \texttt{mpost} named environments along the
% same lines.
%
% We pass the \texttt{mpost} environment two dimensions that depends on
% the context: the symbol's height will be the x-height of the current
% font, the pen's width will scale according to the em size, which is
% bigger for bold face fonts. The picture will be chosen according to
% the current value of \cmdname{f@size} (the current type size) and
% \cmdname{f@series}, which contains the font series indicator (`m' for
% medium fonts and `bx' for bold face fonts, usually). The auxiliary
% macro \cmdname{sqwavebody} contains the body of the \texttt{mpost}
% environment, so there's even no need to copy it many times.
% \end{annotation}
%
%
% \subsection{\texttt{use}}
% This is a boolean option, the default is \texttt{true} unless the
% \texttt{name} option is present. When it is set to \texttt{true},
% the object is inserted in the place where the environment appears. In
% order to set it to \texttt{true}, it is sufficient to say \texttt{use}
% instead of \texttt{use=true}.
%
% \subsection{\texttt{mpmem}}
% You can choose a different format for \MP{} compilation instead of
% the default Plain. For example you can use Hans Hagen's Metafun
% package by passing the option
% \begin{flushleft}
% \texttt{mpmem=metafun}
% \end{flushleft}
%
% \subsection{\texttt{mpxprogram}}
%
% With this option, you can override the global option chosen when
% \textsf{gmp} was loaded, or with \cmdname{gmpoptions}; with
% \texttt{mpxprogram=tex} you invoke Plain \TeX{}, with
% \texttt{mpxprogram=latex} you invoke \LaTeX{} with the preamble
% defined by default or in the options to \textsf{gmp}. There are
% presently no other choices. Use \texttt{mpxprogram=latex} (or set the
% package option \texttt{latex}) whenever you have \MP{} labels.
%
%
% \subsection{\texttt{mpxcommands}}
%
% You can pass some commands to be executed when compiling \MP{} with
% \LaTeX{} with \texttt{mpxcommands=}\meta{commands}. For instance, you
% can say
%\begin{verbatim}
%mpxcommands={\newcommand{\C}{\mathbf{C}}}
%\end{verbatim}
% if your labels contain a \cmdname{C} command for typesetting the set
% of complex numbers in bold face type or some other useful commands.
% You may also say
%\begin{verbatim}
%mpxcommands={\input{mymacros}}
%\end{verbatim}
% and put all needed definitions inside \texttt{mymacros.tex}. Remember
% that inside \verb|\btex...etex| constructions (see
% Section~\ref{body}), \MP{} does \emph{not} know any of your personal
% commands, since the typesetting is made during a distinct run of
% \LaTeX{}. The \LaTeX{} commands are not interpreted during the write
% to the auxiliary file, they will be during \MP{} compilation.
%
% \subsection{\texttt{mpsettings}}
%
% The value for this key is a list of \MP{} statements to be executed
% \emph{before} \texttt{beginfig}, usually for inputting \MP{}
% packages. For example, if a \MP{} object is drawn with the
% \textsf{boxes} package, then it is necessary to say
%\begin{verbatim}
%mpsettings={input boxes;}
%\end{verbatim}
% because this package must be loaded before saying \texttt{beginfig}.
% Of course such a statement can be included also with the
% \texttt{everymp} global key. Don't forget the trailing semicolon.
% \LaTeX{} commands are interpreted just as in the \texttt{mpost}
% environment, so it's possible to use, for example, \cmdname{mpdim}.
%
% \subsection{\texttt{runs}}
%
% The \textsf{drv} package for \MP{} requires each source file to be
% run twice; in this case set the option \texttt{runs=2}. For this
% specific package it's necessary to use also the \texttt{latex}
% option and also, of course, \texttt{mpsettings={input drv;}} in
% order to load the \MP{} package. The default value is~$1$.
%
%
% \section{The body of the \texttt{mpost} and \texttt{mpost*}
% environments}\label{body}
%
% The body of the \texttt{mpost} and \texttt{mpost*} environments
% consists of \MP{} statements with the exception of
% \texttt{beginfig(\meta{number});}, \texttt{endfig;} and
% \texttt{end}\footnote{Actually, you \emph{can} put such statements;
% but don't blame me if your computer starts choking or insulting
% you.}.
%
% The \MP{} input that will be processed consists of
% \begin{flushleft}
% \meta{\TeX{} preamble}\\
% \meta{\MP{} preamble}\\
% \texttt{beginfig(\meta{number});}\\
% \meta{body of the environment}\\
% \texttt{endfig;end}\\
% \meta{\TeX{} postamble}
% \end{flushleft}
% The \meta{body of the environment} is precisely the contents of the
% \texttt{mpost} environment you supply. The \meta{number} is assigned
% automatically and is actually irrelevant.
%
% The \meta{\TeX{} preamble} is empty if the compiler for the
% \texttt{mpx} files is \TeX{}; it is the \LaTeX{} preamble formed as
% seen before in case the compiler is \LaTeX{}. In the latter case, the
% \meta{\TeX{} postamble} is just
%\begin{verbatim}
%verbatimtex \end{document} etex
%\end{verbatim}
% otherwise it is empty (the \MP{} interpreter knows to add
% \verb|\end| at the end of its produced \texttt{mpx} file, if
% necessary). Of course the \meta{\TeX{} preamble} is complemented by
% the declarations you supply with the previously described commands.
% Similarly, the \meta{\MP{} preamble} is usually almost empty, but
% you may add something with the methods described earlier; actually the
% only statement always added to the preamble is
%\begin{verbatim}
%outputtemplate:= "%j.mps";
%\end{verbatim}
% in order to give the resulting file a suitable name for automatic
% inclusion in the \LaTeX{} document. Don't issue such a statement
% yourself.
%
% In the \meta{body of the environment} you can put \TeX{} or \LaTeX{}
% commands as usual for \MP{} code inside \texttt{btex \meta{\TeX{}
% material} etex}; in a \texttt{mpost} environment, however,
% \LaTeX{} commands may be embedded in the normal \MP{} statements,
% we'll call them \emph{naked}.
%
%
% \subsection{Naked \TeX{} commands in the body of
% \texttt{mpost}}
%
% The \emph{naked} commands will be expanded in the normal way, it's up
% to you to ensure that their expansion is valid \MP{} code. Don't
% use dimension parameters by themselves: for example, the command
% \cmdname{linewidth} is \emph{unexpandable}, so \MP{} will interpret
% it as the variable \texttt{linewidth}, which probably would be
% unknown.
%
% Suppose you want that your \MP{} graphic objects have a uniform aspect
% throughout the document, but you haven't decided yet what will be the
% final background color for a series of pictures. All you need is to
% use something like
%\begin{verbatim}
%fill p withrgbcolor \backgroundcolor;
%\end{verbatim}
% and to give in the document's preamble a definition such as
%\begin{verbatim}
%\newcommand*{\backgroundcolor}{(.124,.048,.129)}
%\end{verbatim}
% and your backgrounds will be the same in all the pictures. Of course
% there are other methods to get this result: one might say also
%\begin{verbatim}
%\gmpoptions{everymp={rgbcolor mybgcolor;
% mybgcolor:=(.124,.048,.129)}}
%\end{verbatim}
% or write a definition file to be read via \texttt{everymp}; but I
% believe that the \emph{naked command} method is preferable from the
% point of view of a \LaTeX{} user: it requires less maintenance and is
% more direct.
%
% In order to pass length parameters to \MP{}, the \cmdname{mpdim}
% command is useful. If you know that the parameter is a fixed length
% (such as \cmdname{linewidth}), you can use also \cmdname{the} before
% the name of the length parameter. Beware however that most parameters
% in \LaTeX{} are defined through \cmdname{newlength} and so they are
% \emph{rubber} length, possibly having `plus' or `minus' components
% which would confuse \MP{}. Using \cmdname{mpdim} is safer.
% Moreover, \cmdname{mpdim} accepts its argument in the usual braced
% form.
%
% Pay attention that the expansion of \cmdname{mpdim} is not only the
% length in points, but something more complicated. Don't use it
% outside \texttt{mpost} environments.
%
% Any command whose expansion is just a string of characters can be used
% naked in a \texttt{mpost} environment; \MP{} will see the string of
% letters and it's under your responsibility that this string is
% meaningful in the context it's found. For example, after
%\begin{verbatim}
%\newcommand{\xxx}[1]{#1cm}
%\end{verbatim}
% has been given in the \LaTeX{} root file, \cmdname{xxx}\marg{2} can be
% written in a \texttt{mpost} environment, where \MP{} expects a
% numeric value; for instance,
%\begin{verbatim}
%a:=\xxx{2};
%\end{verbatim}
% would set the variable `\texttt{a}' to the value `\texttt{56.6929}',
% which are indeed two centimeters, since \MP{} works internally in
% `big~points'. Pay attention that
%\begin{verbatim}
%a:=2\xxx{2};
%\end{verbatim}
% would set the variable `\texttt{a}' to the value `\texttt{623.62192}'
% which corresponds to 22~centimeters and not to `\texttt{113.3858}'
% (i.e., 4~centimeters). The correct way to set `\texttt{a}' to
% 4~centimeters would be \verb|a:=2*\xxx{2};|.
%
%
% \subsection{Commands inside
% \texttt{[verbatim\string|btex]...etex}}\label{btex}
%
% This is an important point where the \MP{} input in a
% \texttt{mpost} environment deviates slightly from the normal
% one. Suppose that you have to write a label inside \MP{} in the
% form
%\begin{verbatim}
%btex \textit{label} etex
%\end{verbatim}
% because you want it in italics. We have a problem here, because the
% command \cmdname{textit} passes through a \cmdname{write}, so that it
% is expanded to something that is not what the \MP{} interpreter
% likes to see; precisely, the expansion might be something like
%\begin{verbatim}
%\protect \relax \protect \edef n{it}\protect\xdef
%\OT1/cmr/m/n/10 {\OT1/cmr/m/n/10 }\OT1/cmr/m/n/10
%\size@update \enc@update
%\end{verbatim}
% (all on one line). This will confuse the postprocessors that typeset
% the labels (that currently are integrated into \MP{}), either if we
% are using \LaTeX{} or, even worse, Plain \TeX{}.
%
% The solution is to write \cmdname{verbatimtex} and \cmdname{btex}
% instead of \texttt{verbatimtex} and \texttt{btex}. The leading
% backslash would be legal also in standard \MP{}, anyway.
% Everything inside
%\begin{verbatim}
%\verbatimtex ... etex
%\btex ... etex
%\end{verbatim}
% is passed as is to the compiler for producing the \texttt{mpx} files
% needed by \MP{}. So the correct way to pass the label is
%\begin{verbatim}
%\btex \textit{label} etex
%\end{verbatim}
% when post-processing with \LaTeX{} and
%\begin{verbatim}
%\btex \it label etex
%\end{verbatim}
% when post-processing with Plain \TeX{}. Though using \texttt{btex}
% without a backslash has its uses, remember that eight bit characters
% \emph{must} go inside \verb|\btex...etex| or protected by
% \cmdname{unexpanded} (unless you're using \XeLaTeX{}). So, never say
% \begin{flushleft}\color{red}
% \verb|btex Cuv�� 1982 etex|
% \end{flushleft}
% but choose among the following alternatives:
%\begin{verbatim}
%\btex Cuv�� 1982 etex
%btex \unexpanded{Cuv��} 1982 etex
%btex Cuv\unexpanded{��} 1982 etex
%\end{verbatim}
%
% \begin{annotation}
% \TeX{}nical note. When I started developing this package, the
% choice to write verbatim the \MP{} input was ruled out almost
% immediately, since I wanted to pass parameters from \LaTeX{} to
% \MP{}. The verbatim method is used by \textsf{emp}, which makes
% available only two parameters given as arguments to the \texttt{emp}
% environment; for example |\begin{emp}(23,45)| puts at the user's
% disposal the two \MP{} variables `\texttt{w}' and `\texttt{h}' with
% values $23$~times and $45$~times the usual \LaTeX{} parameter
% \cmdname{unitlength}. Passing to \MP{} the \cmdname{linewidth} is
% pretty complicated, since it requires to divide the
% \cmdname{linewidth} by the unit length. Moreover, only two
% parameters are too few.
%
% Therefore I chose to write the \MP{} files expanding commands. This
% works since \MP{} instructions have no backslashes in them and the
% command \cmdname{mpdim} used for passing parameters from the current
% document is especially tailored in order that its expansion is
% accepted by \MP{}. With the obvious exception of things inside
% \texttt{btex...etex}. The solution exploits the
% \cmdname{unexpanded} command made available by the modern \TeX{}
% engines.
%
% The construction \verb|\btex...etex| is equivalent to write
%\begin{verbatim}
%btex \unexpanded{...} etex
%\end{verbatim}
% and what is written to the \MP{} file is precisely
%\begin{verbatim}
%btex ... etex
%\end{verbatim}
% with no expansion of commands.
% \end{annotation}
%
% There is another catch: for \TeX{}nical reasons, environments in
% \verb|\btex...etex| parts cannot be used without protection. This
% is because the \MP{} input is gathered as an argument delimited by
% \cmdname{end}. The solution is to put the inner environments inside
% braces. An example, taken from Hoenig~\cite[p.~416]{hoenig}, is
% found in figure~\ref{hoenigsun}, where the input is just like
% Hoenig's except for a minor correction (\texttt{3.5u} in the
% original should be \texttt{4.5u}) and having put everything inside
% \verb|\btex...etex| in braces (and writing \cmdname{btex} instead of
% \texttt{btex}, of course).
%
% \begin{figure}
% \caption{An example from Alan Hoenig's book}\label{hoenigsun}
%\begin{verbatim}
%\begin{mpost}[mpxprogram=latex,mpsettings={input boxes;}]
%u:=1pc; path p[]; p0=(-6u,0) -- (6u,0);
%p1=(0,-4u)--(0,4u);
%p2=(0,-4.5u)--(0,4.5u); p2:=p2 rotated -45;
%circleit mech(\btex
%{\fontsize{8}{10}\selectfont
%$\begin{array}{c}
%\sigma_{ij,j}=0\\
%\sigma_{ij}=c_{ijk\ell}\epsilon_{k\ell}\\
%\epsilon_{ij}=\frac{1}{2}(u_{i,j}+u_{j,i})
%\end{array}$}
%etex);
%mech.dx=mech.dy; mech.c=origin;
%pickup pencircle scaled 1pt;
%draw p0; draw p1; draw p2; draw p2 rotated 90;
%pickup pencircle scaled u; unfilldraw bpath.mech;
%pickup pencircle scaled 1pt; drawboxed(mech);
%\end{mpost}
%\end{verbatim}
%
% \centering
% \begin{mpost}[mpxprogram=latex,mpsettings={input boxes;}]
% u:=1pc; path p[]; p0=(-6u,0) -- (6u,0);
% p1=(0,-4u)--(0,4u);
% p2=(0,-4.5u)--(0,4.5u); p2:=p2 rotated -45;
% circleit mech(\btex
% \fontsize{8}{10}\selectfont
% $\array{c}
% \sigma_{ij,j}=0\\
% \sigma_{ij}=c_{ijk\ell}\epsilon_{k\ell}\\
% \epsilon_{ij}=\frac{1}{2}(u_{i,j}+u_{j,i})
% \endarray$
% etex);
% mech.dx=mech.dy; mech.c=origin;
% pickup pencircle scaled 1pt;
% draw p0; draw p1; draw p2; draw p2 rotated 90;
% pickup pencircle scaled u; unfilldraw bpath.mech;
% pickup pencircle scaled 1pt; drawboxed(mech);
% \end{mpost}
% \end{figure}
%
% Another way to cope with this would be to write simply \cmdname{array}
% instead of \cmdname{begin}\marg{array} and \cmdname{endarray} instead
% of \cmdname{end}\marg{array}, which is how the \texttt{mpost}
% environment for this example has actually been written.
%
%
% \section{Definitions using the \texttt{mpost} environment}
%
% Some examples have already been presented, but it's best to
% underline again that the environment can go inside the replacement
% text of a definition; don't use \cmdname{mpost} and
% \cmdname{endmpost}, though, just |\begin{mpost}| and
% |\end{mpost}|. Commands defined this way are \emph{fragile}: don't
% use them in moving arguments. As an example, we can use a variation
% on a drawing from~\cite{hoenig}:
%\begin{verbatim}
%\newcommand{\squares}[2][black]{%
% \begin{mpost}
% boolean timetofillbox;
% sfactor:=.95;
% path p,q; u:=\mpdim{#2\textwidth}/2;
% p := (u,u) -- (-u,u) -- (-u,-u) -- (u,-u) -- cycle;
% theta := 0; dtheta := .005;
% forever:
% theta := theta+dtheta;
% q := p scaled sfactor rotated theta;
% exitif ypart(point 0 of q) > u;
% endfor;
% fill p withrgbcolor #1; timetofillbox:=false;
% for i:=1 upto 51:
% p := p scaled sfactor rotated theta;
% if timetofillbox:
% fill p withrgbcolor #1; timetofillbox:=false;
% else:
% fill p withrgbcolor white-#1; timetofillbox:=true;
% fi
% endfor
% \end{mpost}}
%\end{verbatim}
% The optional argument is an \textsc{rgb} color, either with a
% predefined name such as \texttt{black} (default) or a triple such as
% \texttt{(.165,.325,.553)}; the second argument is the size of the
% square, expressed as a fraction of \cmdname{textwidth}, for example
% \texttt{0.8}. In figure~\ref{squares} you get three variations input
% as
%\begin{verbatim}
%\begin{minipage}{\textwidth}
%\centering\offinterlineskip
%\squares{.4}\squares[(.165,.325,.553)]{.4}\\
%\squares[(.835,.685,.447)]{.8}
%\end{minipage}
%\end{verbatim}
% that also show how \textsf{gmp} uses the hi-res bounding box provided
% by \MP{}.
%
% \begin{figure}
% \medskip
% \begin{minipage}{\textwidth}
% \centering\offinterlineskip
% \squares{.4}\squares[(.165,.325,.553)]{.4}\\
% \squares[(.835,.685,.447)]{.8}
% \end{minipage}
% \medskip
% \caption{Squares taken from Hoenig's book}\label{squares}
% \end{figure}
%
%
% \section{The \texttt{mpost*} environment}
%
% No command in the body of the \texttt{mpost*} environment will be
% interpreted in any special way, so don't use them except than
% encapsulated into \texttt{btex...etex}. Here there's no need to write
% \cmdname{btex}, but it doesn't hurt either. It's however necessary to
% hide inside braces the \LaTeX{} command \cmdname{end} like for the
% sibling environment \texttt{mpost}. It's possible to pass variables to
% the picture from the \LaTeX{} context by exploiting the option
% \texttt{mpsettings}: for example, with a prologue such as
%\begin{verbatim}
%\begin{mpost*}[mpsettings{u:=\mpdim{\unitlength}}]
%\end{verbatim}
% you'll be able to use in the \MP{} code the variable $u$ which will be
% set to the current \cmdname{unitlength} (don't say \texttt{save u;} in
% the \MP{} code, of course).
%
% The \texttt{mpost*} environment \emph{can} go inside the argument
% to a command.
%
%
% \section{\XeLaTeX{} and \textsf{gmp}}
%
% The present package is compatible with \XeLaTeX{}; in this case it
% performs also a conversion to \textsc{pdf} of the \textsc{mps} file
% for inclusion. There are some limitations, though: it's impossible to
% typeset labels to pictures with system fonts, as it would be in the
% main document. Indeed \MP{} can't use \XeTeX{} for typesetting the
% labels, only \LaTeX{}; this limitation is in \MP{}, we hope that in
% the future it will be removed. If your main font is Linux Libertine,
% for instance, you can typeset labels by saying
%\begin{verbatim}
%\usempxpackage[utf8]{inputenc}
%\usempxpackage{libertine}
%\end{verbatim}
% (possibly passing some option to the latter package). Many fonts that
% you can use with \XeLaTeX{} can also be used in \LaTeX{}, of course
% without access to the full character set.
%
%
% \section{Examples}
%
% Let's try some weird input with foreign characters.
%\begin{verbatim}
%\usepackage[latin1]{inputenc}
%...
%\usempxpackage[latin1]{inputenc}
%...
%\begin{center}
%\begin{mpost}[mpxprogram=latex]
%label(\btex ��� etex, origin);
%draw fullcircle xscaled 1.5cm yscaled 2\mpdim\baselineskip;
%\end{mpost}
%\end{center}
%\end{verbatim}
% \begin{center}
% \usempxpackage[latin1]{inputenc}
% \begin{mpost}[mpxprogram=latex]
% label(\btex ��� etex, origin);
% draw fullcircle xscaled 1.5cm yscaled 2\mpdim\baselineskip;
% \end{mpost}
% \end{center}
% Always use the same option to \textsf{inputenc} as your main
% file or, if you are working with \XeLaTeX{},
%\begin{verbatim}
%\usempxpackage[utf8]{inputenc}
%\end{verbatim}
% in your document's preamble. Also \texttt{utf8x} is acceptable, of
% course, in this case.
%
% Let's see instead a case where expansion in a \texttt{btex...etex}
% construction is needed: we want to enclose numbers, colored in white,
% inside an elliptical gray background. The vertical axis of the
% ellipse should be as high as the baseline skip and it should be a
% circle if the number has only one digit; the additional problem is
% that the number can be given as the representation of some counter
% (for example \texttt{enumi}, a possible application is evident).
%\begin{verbatim}
%\newcounter{mycount}
%\newlength{\mylen}
%\newcommand{\circleit}[2][]{\settowidth{\mylen}{#2}%
% \begin{mpost}[mpxprogram=latex]
% fill fullcircle
% xscaled max(\mpdim{\mylen+6pt},\mpdim{\baselineskip})
% yscaled \mpdim{\baselineskip}
% withcolor .4white;
% draw thelabel(btex \unexpanded{#1}#2 etex, origin)
% withcolor white;
% \end{mpost}}
%
%\circleit{\themycount}\quad
%\setcounter{mycount}{3}\circleit{\themycount}\quad
%\setcounter{mycount}{12}\circleit{\themycount}\quad
%\renewcommand{\themycount}{\roman{mycount}}%
%\circleit{\themycount}\quad
%\circleit{44}\quad
%\renewcommand{\themycount}{\arabic{mycount}}%
%\circleit[\sffamily]{\themycount}
%\end{verbatim}
% \begin{center}
% \newcounter{mycount}
% \newlength{\mylen}
% \newcommand{\circleit}[2][]{\settowidth{\mylen}{#2}%
% \begin{mpost}[mpxprogram=latex]
% fill fullcircle
% xscaled max(\mpdim{\mylen+6pt},\mpdim{\baselineskip})
% yscaled \mpdim{\baselineskip}
% withcolor .4white;
% draw thelabel(btex \unexpanded{#1}#2 etex, origin)
% withcolor white;
% \end{mpost}}
% \circleit{\themycount}\quad
% \setcounter{mycount}{3}\circleit{\themycount}\quad
% \setcounter{mycount}{12}\circleit{\themycount}\quad
% \renewcommand{\themycount}{\roman{mycount}}%
% \circleit{\themycount}\quad
% \circleit{44}\quad
% \renewcommand{\themycount}{\arabic{mycount}}%
% \circleit[\sffamily]{\themycount}
% \end{center}
%
% In this case we \emph{want} that what is inside \texttt{btex...etex}
% is expanded, in case it is \cmdname{themycount}. Of course we have to
% be sure that the expansion of the command consists only of
% characters. So, for example,
%\begin{verbatim}
%\renewcommand{\themycount}{\textsf{\arabic{mycount}}}
%\end{verbatim}
% would not work for the last example. This is the reason for having
% defined an optional argument to \cmdname{circleit}. The trick of
% using this argument in \cmdname{unexpanded} keeps every program happy
% and the label is typeset correctly. More fun for the \TeX{}ackers!
%
%
% \section{Conversion from \textsf{emp}}
%
% It's quite easy to convert old files that use \textsf{emp} without
% changing too much; a typical \texttt{emp} environment is
%\begin{verbatim}
%\begin{emp}[xyz](15,30)
%...;
%\end{emp}
%\end{verbatim}
% where the dots stand for \MP{} statements and \texttt{xyz} is the name
% for subsequent use. This may be transformed into
%\begin{verbatim}
%\begin{mpost}[name=xyz,use]
%w:=\mpdim{15\unitlength};
%h:=\mpdim{30\unitlength};
%...;
%\end{mpost}
%\end{verbatim}
% An \texttt{empgraph} environment such as
%\begin{verbatim}
%\begin{empgraph}[xyz](15,30)
%...;
%\end{empgraph}
%\end{verbatim}
% must be transformed into
%\begin{verbatim}
%\begin{mpost}[name=xyz,use](15,30)
%w:=\mpdim{15\unitlength};
%h:=\mpdim{30\unitlength};
%draw begingraph(w,h);
%...;
%endgraph;
%\end{mpost}
%\end{verbatim}
% Remember to change all \texttt{btex} into \texttt{\string\btex} and
% the auxiliary commands into the similar ones of \textsf{gmp}: it
% should be almost straightforward. If people ask for it, I might add a
% compatibility layer for \textsf{emp}.
%
% Alternatively, the first case might be treated as
%\begin{verbatim}
%\begin{mpost*}[name=xyz,
% mpsettings={w:=\mpdim{15\unitlength};
% h:=\mpdim{30\unitlength};}]
%...;
%\end{mpost*}
%\end{verbatim}
% You might prefer this strategy if you have many \texttt{btex...etex}
% pairs. Look out for \cmdname{end} commands, though: if not properly
% braced, they will confuse the processing of the environment's content.
%
% \StopEventually{
% \begin{thebibliography}{1}
%
% \bibitem{hagen-metafun}%
% Hans Hagen, Metafun,
% \url{http://www.pragma-ade.nl/general/manuals/metafun-p.pdf}
%
% \bibitem{hoenig}%
% Alan Hoenig, \emph{\TeX{} unbound}, Oxford University Press, Oxford
% and New York, 1998.
%
% \bibitem{peter2005}%
% Steve Peter, ``\cmdname{starttext}, Swelled Rules and \MP{}'', The
% Prac\TeX{} Journal, n.~4 (2005).
%
% \end{thebibliography}
% }
%
% \section{Implementation}
%
% Before doing anything, we check that the engine knows about
% |\unexpanded| and |\dimexpr|; otherwise we say good-bye.
% \begin{macrocode}
\@ifundefined{eTeXversion}{%
\PackageError{gmp}{This package requires a e-TeX extensions}
{The gmp package requires a modern TeX engine, please upgrade}%
\endinput}{}
% \end{macrocode}
% We need \textsf{xkeyval} for its key-value interface. Then we define
% some conditional for later usage and the package options.
% \begin{macrocode}
\RequirePackage{xkeyval}[2005/01/30]
\newif\ifgmp@latex % true if always using latex for mpx
\newif\ifgmp@locallatex % true if using latex for mpx for a
% single figure
\newif\ifgmp@nogen % true if we are not generating the mps files
\newif\ifgmp@nowrite % true if we are not writing the mp files
\newif\ifgmp@warn % true if we are issuing the final message
\DeclareOptionX<ggmp>{tex}{\def\gmp@mpxprogram{tex}%
\gmp@latexfalse\gmp@locallatexfalse}
\DeclareOptionX<ggmp>{latex}{\def\gmp@mpxprogram{latex}%
\gmp@latextrue\gmp@locallatextrue}
\DeclareOptionX<ggmp>{noshellescape}{\gmp@nogentrue}
\DeclareOptionX<ggmp>{shellescape}{\gmp@nogenfalse}
\DeclareOptionX<ggmp>{nowrite}{\gmp@nowritetrue}
\DeclareOptionX<ggmp>{write}{\gmp@nowritefalse}
\DeclareOptionX<ggmp>{envname}{\def\gmp@envname{#1}}
\DeclareOptionX<ggmp>{extension}{\def\gmp@ext{#1}}
\def\gmp@preoptions{}
\DeclareOptionX<ggmp>{everymp}{\edef\gmp@preoptions{\gmp@preoptions^^J#1}}
\DeclareOptionX<ggmp>{clean}{\def\gmp@clean{#1}}
\DeclareOptionX<ggmp>{rmcommand}{\def\gmp@remove{#1}}
\DeclareOptionX<ggmp>{postrmcommand}{\def\gmp@postremove{#1}}
\def\gmp@jobname{\jobname}
% \end{macrocode}
% Now we set the default options: the mpx program is \TeX{}; we write
% out the auxiliary files and do not assume shell-escape; no cleaning
% after compilation of the \MP{} files; default environment names are
% \texttt{mpost} and \texttt{mpost*}; default mp-extension is
% \texttt{+mp}. Then we read the package options.
% \begin{macrocode}
\ExecuteOptionsX<ggmp>{tex,noshellescape,write,clean=none}
\ExecuteOptionsX<ggmp>{envname=mpost,extension=+mp,
rmcommand=rm -f,postrmcommand={}}
\ProcessOptionsX<ggmp>\relax
% \end{macrocode}
% We need some auxiliary packages, they'll probably be loaded anyway,
% with the exception of \textsf{environ} that's employed for the
% \texttt{mpost*} environment, but has no known incompatibility.
% \begin{macrocode}
\RequirePackage{graphicx}
\RequirePackage{ifpdf}
\RequirePackage{ifxetex}
\RequirePackage{environ}
% \end{macrocode}
% With \XeLaTeX{} we need to run epstopdf; we don't support
% Lua\LaTeX{}, because looking at shell-escape is useless, at the
% moment, even via Heiko Oberdiek's \textsf{pdftexcmds} (at least for
% the time being).
% \begin{macrocode}
\ifxetex
\let\gmp@shellescape\shellescape
\def\gmp@preoptions{prologues:=3;^^J}
\else
\ifdefined\pdfshellescape % (pdf)latex
\let\gmp@shellescape\pdfshellescape
\else % lualatex
\chardef\gmp@shellescape=\z@
\gmp@nogentrue
\fi
\fi
% \end{macrocode}
% We define some warning messages; in some cases the message enables
% or disables other messages.
% \begin{macrocode}
\def\gmp@msgdisallowed{\PackageWarningNoLine{gmp}{Compilation and
writing of MetaPost files has been\MessageBreak disallowed by the
`nowrite' option}\gdef\gmp@nemessage{}}
\def\gmp@msgnonexistent{\PackageWarning{gmp}{Non existent MetaPost
file requested}\ifgmp@warn\else\global\gmp@warntrue\fi}
\def\gmp@msgrequestx{\PackageWarningNoLine{gmp}{The MetaPost file you
requested does not exist,\MessageBreak perhaps by a compilation
error}}
\def\gmp@msgremember{\PackageWarningNoLine{gmp}{Remember to run `sh
\gmp@jobname\gmp@ext.sh' and rerun (pdf)LaTeX}}
% \end{macrocode}
% The following lines are to avoid spurious messages, opening and
% writing of files if the user has not activated the shell escape
% feature but has given the shell-escape option.
% \begin{macrocode}
\def\gmp@msgensure{%
\PackageWarningNoLine{gmp}{Ensure that you have enabled the shell
escape feature, or\MessageBreak you can be in trouble. The
available MetaPost generated\MessageBreak files will be used
anyway. Use option `nowrite' if they\MessageBreak are already
in final form}%
\let\gmp@message\@gobble
\let\gmp@writexviii\@gobble
\def\gmp@openout##1##2\@nil{}%
\let\gmp@write\@gobbletwo
\let\gmp@closeout\@gobble}
% \end{macrocode}
% Now we define some abbreviations for primitive actions, so that we
% are able to change their meaning at will.
% \begin{macrocode}
\let\gmp@message\message
\def\gmp@writexviii{\immediate\write18 }
\def\gmp@openout#1#2\@nil{\immediate\openout#1#2}
\def\gmp@write{\immediate\write}
\def\gmp@closeout{\immediate\closeout}
% \end{macrocode}
% \begin{macro}{\gmp@command}
% Here we define the main internal macro, |\gmp@command|, which has
% different definitions depending on the package options. If the
% \texttt{nowrite} option is valid, there's even no need for it;
% otherwise it must behave differently: if we are doing immediate
% compilation via shell-escape it must act by emitting
% |\gmp@writexviii|, otherwise it must write the command in the batch
% file to be run after the \LaTeX{} run. In the latter case we also
% open an output stream and write a prologue on it.
% \begin{macrocode}
\def\gmp@setupmacros{%
\ifgmp@nowrite
\let\gmp@nemessage\gmp@msgdisallowed
\else
\ifgmp@nogen
\let\gmp@nemessage\gmp@msgnonexistent
\def\gmp@command{%
mpost \ifx\gmp@mpmem\empty\else\space\gmp@mpmem\space\fi}%
\newwrite\gmp@shellout
\immediate\openout\gmp@shellout=\gmp@jobname\gmp@ext.sh%
\immediate\write\gmp@shellout{\string##!/bin/sh}%
\def\gmp@shellcommand##1{\immediate\write\gmp@shellout{##1}}%
\AtEndDocument{\ifgmp@warn\gmp@msgremember\gmp@warnfalse\fi}%
\else
\let\gmp@nemessage\gmp@msgrequestx
\ifnum\gmp@shellescape=\@ne
\def\gmp@command{%
mpost -interaction=nonstopmode %
\ifx\gmp@mpmem\empty\else\space\gmp@mpmem\space\fi}%
\def\gmp@shellcommand##1{%
\gmp@message{^^J(gmp) Doing external command^^J(gmp) \string"}%
\gmp@writexviii{echo ##1'\string"'}\gmp@writexviii{##1}%
}%
\else
\gmp@msgensure\let\gmp@shellcommand\@gobble
\fi
\fi
\fi
}
\gmp@setupmacros
% \end{macrocode}
% \end{macro}
% \begin{macro}{\gmpoptions}
% Next we define |\gmpoptions| which can be used to set package
% options in a more friendly way. However we disallow it outside the
% preamble, because otherwise the status of the macros would not be
% predictable.
% \begin{macrocode}
\def\gmpoptions#1{\setkeys{ggmp}{#1}\gmp@setupmacros}
\@onlypreamble\gmpoptions
% \end{macrocode}
% \end{macro}
% We next define a standard \LaTeX{} preamble for mpx.
% \begin{macrocode}
\def\gmp@latexpreamble{%^^J%
\gmp@percent\string&latex^^J%
\string\documentclass[1\@ptsize pt]{article}^^J%
\ifx\empty\gmp@packages\else\the\gmp@packages^^J\fi%
\ifx\empty\gmp@commands\else\the\gmp@commands^^J\fi%
\string\begin{document}^^J}
% \end{macrocode}
% \begin{macro}{\usempxclass}\begin{macro}{\usempxpackage}
% If one wants a non standard \LaTeX{} class, the command
% |\usempxclass|, with the same syntax as |\documentclass|, is
% provided. Similarly for |\usempxpackage|; |\resetmpxpackages| clears
% out the loading of packages.
% \begin{macrocode}
\newcommand\usempxclass[2][]{%
\def\gmp@latexpreamble{^^J%
\gmp@percent\string&latex^^J%
\string\documentclass[#1]{#2}^^J%
\ifx\empty\gmp@packages\else\the\gmp@packages^^J\fi%
\ifx\empty\gmp@commands\else\the\gmp@commands^^J\fi%
\string\begin{document}^^J}}
\newtoks\gmp@packages
\newcommand\usempxpackage[2][]{%
\gmp@packages=\expandafter{\the\gmp@packages^^J%
\usepackage[#1]{#2}}}
\newcommand\resetmpxpackages{\gmp@packages={}}
% \end{macrocode}
% \end{macro}\end{macro}
% \begin{macro}{\mpxcommands}
% With |\mpxcommands| one can insert definitions to be used for \MP{}
% label composition: these are seen only if \LaTeX{} is used for
% mpx. There's also |\resetmpxcommands| in case of need.
% \begin{macrocode}
\newtoks\gmp@commands
\newcommand\mpxcommands[1]{%
\gmp@commands=\expandafter{\the\gmp@commands^^J%
#1}}
\newcommand\resetmpxcommands{\gmp@commands={}}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\mpdim}
% The |\mpdim| macro is used in the \texttt{mpost} environment or in
% the value of the key \texttt{mpsettings} for passing length
% depending on current conditions. We exploit |\dimexpr| that strips
% out possible `elastic' components and allows for doing
% calculations. The result is written out surrounded by
% \texttt{begingroup} and \texttt{endgroup} that make the number
% obtained look like a variable at \MP's eyes.
% \begin{macrocode}
\def\mpdim#1{ begingroup \the\dimexpr#1\relax\space endgroup }
% \end{macrocode}
% \end{macro}
% Now we start the hard task of writing out the auxiliary files. So we
% define an output stream and a counter that keeps track of the figure
% names; in order to know the total number of the pictures, at
% end-of-document we define an internal label which is currently
% unused, though.
% \begin{macrocode}
\newwrite\gmp@out
\newcounter{gmp@count}
\AtEndDocument{%
\refstepcounter{gmp@count}%
\label{gmp@finallabel}%
}
% \end{macrocode}
% \begin{environment}{mpost}
% The \texttt{mpost} environment (but the name can be set at package
% loading) must read the `local options' given as an optional argument
% as the usual list of key-value statements. First of all it must step
% the \MP{} figure counter and set a label for it for subsequent
% calling of the graphics, then we grab the option given to the
% environment.
% \begin{macrocode}
\newenvironment{\gmp@envname}[1][]
{\@bsphack
\global\gmp@usefalse
\refstepcounter{gmp@count}\label{gmp@label@\thegmp@count}%
\bgroup
\edef\gmp@number{\thegmp@count}%
\gmp@grab{#1}}
{\@esphack}
% \end{macrocode}
% \end{environment}
% \begin{environment}{mpost*}
% The \texttt{mpost*} environment writes out its contents without
% \TeX{} macro expansion; we simply use \texttt{mpost}: so we gather
% the optional argument into a scratch token register, collect the
% body of the environment and pass it to the |\gmp@writeunex| macro
% which calls |\begin{mpost}| (possibly with the name chosen by the
% user), to which are passed the options. The first |\unexpanded| is
% removed by |\edef|, the second one by the writing process.
% \begin{macrocode}
\def\gmp@writeunex#1{\begingroup
\edef\x{\endgroup\noexpand\begin{\gmp@envname}[\the\toks@]%
\unexpanded{\unexpanded{#1}}\noexpand\end{\gmp@envname}}\x}
\newenvironment{\gmp@envname*}[1][]
{\toks@{#1}\Collect@Body\gmp@writeunex}{}
% \end{macrocode}
% \end{environment}
% Here we define the key-value interface for the options to the
% environments, with some auxiliary macros and conditionals;
% |\gmp@fourdigits| is used for the output file names, we think that
% more than $9999$ pictures are difficult to be present for a single
% file; but this will not limit at all the user's possibilities.
% \begin{macrocode}
\def\gmp@fourdigits#1{%
\ifnum#1<10 0\fi
\ifnum#1<100 0\fi
\ifnum#1<1000 0\fi\number #1}
\def\gmp@not@a@name@{@not@a@name@}
\def\gmp@choosetex{\gmp@locallatexfalse}
\def\gmp@chooselatex{\gmp@locallatextrue}
\def\gmp@doiflatex#1{\ifgmp@latex#1\else\ifgmp@locallatex#1\fi\fi}
\def\gmp@mpmem{}
\newif\ifgmp@use
\define@key{gmp}{name}[@not@a@name@]{%
\def\gmp@thisname{#1}%
\expandafter\xdef\csname gmp@fig#1\endcsname
{\gmp@fourdigits{\gmp@number}}}
\define@key{gmp}{use}[true]{\global\csname gmp@use#1\endcsname}
\define@key{gmp}{mpmem}{\def\gmp@mpmem{-mem #1}}
\define@key{gmp}{mpsettings}{\edef\gmp@preoptions{\gmp@preoptions^^J#1}}
\define@key{gmp}{mpxcommands}{%
\gmp@commands=\expandafter{\the\gmp@commands^^J#1}}
\define@key{gmp}{mpxprogram}{%
\def\gmp@mpxprogram{#1}%
\csname gmp@choose#1\endcsname}
\define@key{gmp}{runs}{\chardef\gmp@runs=#1\relax}
% \end{macrocode}
% \begin{macro}{\gmp@grab}
% The |\gmp@grab| macro sets the value of the keys; the \texttt{name}
% must be initially empty and the number of runs should be~$1$. The
% conditional |\if@gmpuse| is set to false at the beginning of the
% environment, and to true when \texttt{use} is given or when there's
% no name. Finally the macro calls |\gmp@innermpost|.
% \begin{macrocode}
\def\gmp@grab#1{%
\setkeys{gmp}{name}%
\setkeys{gmp}{runs=1}%
\setkeys{gmp}{#1}%
\ifx\gmp@thisname\gmp@not@a@name@
\global\gmp@usetrue
\fi
\gmp@setup\gmp@innermpost}
% \end{macrocode}
% \end{macro}
% Before defining the macro responsible for the task of writing out
% the \MP{} files, we do some housekeeping.
%
% We ensure that the character we need are written correctly in the
% \MP{} files; so we define a `printing' percent sign and change the
% category code of characters that might be made active by
% \textsf{babel} or other packages. The semicolon is made active: it
% will output a semicolon followed by a new line character; in the
% environment |\par| means `go to a new line', so that empty lines in
% a \texttt{mpost} environment will cause a new line in the output
% file. However this doesn't work currently for \texttt{mpost}
% environments given as arguments to other commands; since the normal
% buffer size is around $50\,000$, this should not be a problem.
% \begin{macrocode}
\begingroup\@makeother\%\def\x{\endgroup\def\gmp@percent{%}}\x
\def\gmp@activesc{\catcode`\;=\active
\begingroup\lccode`\~=`\;
\lowercase{\endgroup\edef~}{\string;^^J}}
\def\gmp@otherchars{\do\!\do\=\do\:\do\"\do\?\do\'\do\`\do\|}
% \end{macrocode}
% \begin{macro}{\gmp@setup}
% The following macro |\gmp@setup| starts writing the output files,
% after setting category codes and something else; it doesn't write
% anything if the option \texttt{nowrite} is in force, otherwise
% writes a prologue and all needed preliminaries, up to
% \texttt{beginfig(}\meta{number}\texttt{)}; this number is actually
% irrelevant, because we use \texttt{outputtemplate}, but it should
% correspond to the number appearing in the name of the output file.
% \begin{macrocode}
\def\gmp@setup{%
\let\do\@makeother\gmp@otherchars\newlinechar=`\^^J
\gmp@activesc
\def\par{^^J}%
\ifgmp@nowrite\else
\edef\@temp{\gmp@jobname\gmp@ext\gmp@fourdigits{\gmp@number}.mp}%
\expandafter\gmp@openout\expandafter\gmp@out\@temp\@nil
\gmp@write\gmp@out{%
\gmp@percent\gmp@percent\space
Do not edit, this file has been generated^^J%
\gmp@percent\gmp@percent\space
automatically by \jobname.tex via gmp.sty^^J^^J%
\gmp@doiflatex{verbatimtex\gmp@latexpreamble etex;^^J}%
\ifx\empty\gmp@preoptions\else\gmp@preoptions^^J\fi%
outputtemplate:= "\gmp@percent j.mps";^^J%
beginfig(\gmp@number);%^^J%
}%
\fi}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\gmp@innermpost}
% This is the central macro which collects the body of the
% environment; we chose to use |\end| as delimiter so that the
% environment can be used inside other arguments or definitions; maybe
% it's not the best way to do this, but other than requiring
% protection of |\end| commands inside the environment seems to have
% no side effects. The environment's content is written out to the
% \MP{} file, followed by \texttt{endfig;} and \texttt{end}; if
% \LaTeX{} is used for the labels, also the closing statements are
% added (though they are not strictly necessary). Then
% |\gmp@shellcommand| is performed one or more times according to the
% value of \texttt{runs}. It will run \MP{} stopping \LaTeX{}
% momentarily or write the command to the shell script, according to
% the current package options. In the case of \XeLaTeX{} it will also
% call or write for a run of \textsf{epstopdf}. Finally, it executes
% |\end{mpost}| and uses the object if it has been requested to do,
% that is, if |\ifgmp@use| is true.
% \begin{macrocode}
\long\def\gmp@innermpost#1\end#2{%
\ifgmp@nowrite\else
\gmp@write\gmp@out{%
#1^^Jendfig;^^Jend.%
\gmp@doiflatex{^^Jverbatimtex^^J\string\end{document}^^Jetex}}%
\gmp@closeout\gmp@out
\count@=\gmp@runs
\loop\ifnum\count@>\z@
\gmp@shellcommand{\gmp@command\space
-tex=\gmp@mpxprogram\space\gmp@jobname\gmp@ext
\gmp@fourdigits{\gmp@number}}%
\advance\count@\m@ne
\repeat
\ifxetex
\gmp@shellcommand{epstopdf --hires \gmp@jobname\gmp@ext
\gmp@fourdigits{\gmp@number}.mps}%
\fi
\fi
\egroup
\end{#2}\ifgmp@use
\gmp@usempost{\thegmp@count}\fi}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\usempost}
% The macros for using the compiled pictures are almost straightforward:
% the files will have extension \texttt{.mps} for \LaTeX{} or
% \textsc{pdf}\LaTeX{} and \texttt{.pdf} for \XeLaTeX{}. We check that
% they exist and load them or issue a warning.
% \begin{macrocode}
\ifxetex
\def\gmp@usempost#1{%
\edef\gmp@thempsfile{\gmp@jobname\gmp@ext\gmp@fourdigits{#1}}%
\IfFileExists{\gmp@thempsfile.pdf}%
{\includegraphics{\gmp@thempsfile.pdf}}%
{\gmp@nemessage\gmp@box}}
\newcommand\usempost[2][]{%
\IfFileExists{\gmp@jobname\gmp@ext\csname gmp@fig#2\endcsname.pdf}%
{\includegraphics[#1]
{\gmp@jobname\gmp@ext\csname gmp@fig#2\endcsname.pdf}}%
{\gmp@nemessage\gmp@box}}
\else
\def\gmp@usempost#1{%
\edef\gmp@thempsfile{\gmp@jobname\gmp@ext\gmp@fourdigits{#1}}%
\IfFileExists{\gmp@thempsfile.mps}%
{\includegraphics[hiresbb]{\gmp@thempsfile.mps}}%
{\gmp@nemessage\gmp@box}}
\newcommand\usempost[2][]{%
\IfFileExists{\gmp@jobname\gmp@ext\csname gmp@fig#2\endcsname.mps}%
{\includegraphics[hiresbb,#1]
{\gmp@jobname\gmp@ext\csname gmp@fig#2\endcsname.mps}}%
{\gmp@nemessage\gmp@box}}
\fi
\def\gmp@box{\fbox{\@ifundefined{color}{}{\color{red}}MP}}
% \end{macrocode}
% \end{macro}
% Now we clean up our directory from the auxiliary files, at the
% user's request, of course. The \texttt{clean} keyword may be
% specified in the package options or in |\gmpoptions| to have a value
% among |none|, |aux|, or |mp|.
%
% At end document we look at the value of this key and do what's
% desired by the user. If the value is not recognized we issue a
% warning and act as if |clean=none| had been given; otherwise we
% execute the requested command or write them in the batch script.
% \begin{macrocode}
\AtEndDocument{%
\@ifundefined{gmp@doclean@\gmp@clean}
{\expandafter\gmp@badcleaning\expandafter{\gmp@clean}}
{\@nameuse{gmp@doclean@\gmp@clean}}}
\def\gmp@badcleaning#1{\PackageWarningNoLine{gmp}{%
Wrong cleaning option `clean=#1'; `clean=none' used}}
\def\gmp@doclean@none{}
\def\gmp@doclean@aux{%
\gmp@shellcommand{\gmp@remove\space
\jobname\gmp@ext*.log\space\gmp@postremove}%
\gmp@shellcommand{\gmp@remove\space
\jobname\gmp@ext*.mpx\space\gmp@postremove}%
\gmp@shellcommand{\gmp@remove\space
\jobname\gmp@ext*.mpo\space\gmp@postremove}%
}
\def\gmp@doclean@mp{%
\gmp@shellcommand{\gmp@remove\space
\jobname\gmp@ext*.log\space\gmp@postremove}%
\gmp@shellcommand{\gmp@remove\space
\jobname\gmp@ext*.mpx\space\gmp@postremove}%
\gmp@shellcommand{\gmp@remove\space
\jobname\gmp@ext*.mpo\space\gmp@postremove}%
\gmp@shellcommand{\gmp@remove\space
\jobname\gmp@ext*.mp\space\gmp@postremove}%
\ifxetex
\gmp@shellcommand{\gmp@remove\space
\jobname\gmp@ext*.mps\space\gmp@postremove}%
\fi}
% \end{macrocode}
% \begin{macro}{\verbatimtex}\begin{macro}{\btex}
% Final definition for not expanding macros in the \MP{} labels.
% \begin{macrocode}
\long\def\verbatimtex#1etex{verbatimtex \unexpanded{#1} etex}
\long\def\btex#1etex{btex \unexpanded{#1} etex}
% \end{macrocode}
% \end{macro}\end{macro}
% \Finale
\endinput
% Local Variables:
% mode: doctex
% coding: latin-1
% End: