summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/mpostinl
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/mpostinl
Initial commit
Diffstat (limited to 'macros/latex/contrib/mpostinl')
-rw-r--r--macros/latex/contrib/mpostinl/README.txt39
-rw-r--r--macros/latex/contrib/mpostinl/mpostinl.dtx3037
-rw-r--r--macros/latex/contrib/mpostinl/mpostinl.ins39
-rw-r--r--macros/latex/contrib/mpostinl/mpostinl.pdfbin0 -> 339538 bytes
4 files changed, 3115 insertions, 0 deletions
diff --git a/macros/latex/contrib/mpostinl/README.txt b/macros/latex/contrib/mpostinl/README.txt
new file mode 100644
index 0000000000..952507a8cc
--- /dev/null
+++ b/macros/latex/contrib/mpostinl/README.txt
@@ -0,0 +1,39 @@
+mpostinl v1.5
+Copyright 2010-2018 Niklas Beisert
+
+mpostinl is a LaTeX2e package
+which enables the embedding of metapost figures
+within a LaTeX document.
+The package automatically collects the embedded
+definitions and figures in a .mp file,
+adds an appropriate LaTeX document structure,
+and compiles it to .mps files.
+It also allows for various configuration options
+to manage the generation of files and compilation.
+
+The package consists of the files
+
+ README.txt readme file
+ mpostinl.ins installation file
+ mpostinl.dtx source file
+ mpostinl.sty package file
+ mpinlsmp.tex sample latex file
+ mpostinl.pdf manual
+
+The distribution consists of the files
+README.txt, mpostinl.ins and mpostinl.dtx.
+
+Run "(pdf)latex mpostinl.dtx" to compile the manual mpostinl.pdf.
+
+Run "latex mpostinl.ins" to create the package mpostinl.sty
+and the sample mpinlsamp.tex.
+Copy the file mpostinl.sty to an appropriate directory of your LaTeX
+distribution, e.g. texmf-root/tex/latex/mpostinl.
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+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.
diff --git a/macros/latex/contrib/mpostinl/mpostinl.dtx b/macros/latex/contrib/mpostinl/mpostinl.dtx
new file mode 100644
index 0000000000..1039b113bc
--- /dev/null
+++ b/macros/latex/contrib/mpostinl/mpostinl.dtx
@@ -0,0 +1,3037 @@
+% \iffalse
+%
+% mpostinl.dtx Copyright (C) 2010-2018 Niklas Beisert
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% 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 Niklas Beisert.
+%
+% This work consists of the files mpostinl.dtx and mpostinl.ins
+% and the derived files mpostinl.sty and mpinlsmp.tex
+%
+%<package|sample>\NeedsTeXFormat{LaTeX2e}[1996/12/01]
+%<package>\ProvidesPackage{mpostinl}[2018/12/30 v1.5 metapost inline figures]
+%<sample>\ProvidesFile{mpinlsmp.tex}[2018/12/30 v1.5 sample for mpostinl]
+%<*driver>
+%\ProvidesFile{mpostinl.drv}[2018/12/30 v1.5 mpostinl reference manual file]
+\PassOptionsToClass{10pt,a4paper}{article}
+\documentclass{ltxdoc}
+
+\usepackage[margin=35mm]{geometry}
+\usepackage{hyperref}
+\usepackage{hyperxmp}
+\usepackage[usenames]{color}
+\usepackage{amsmath,amsfonts}
+\usepackage{mflogo}
+\usepackage[utf8]{inputenc}
+
+\hypersetup{colorlinks=true}
+\hypersetup{pdfstartview=FitH}
+\hypersetup{pdfpagemode=UseNone}
+\hypersetup{pdfsource={}}
+\hypersetup{pdflang={en-UK}}
+\hypersetup{pdfcopyright={Copyright 2010-2018 Niklas Beisert.
+ This work may be distributed and/or modified under the
+ conditions of the LaTeX Project Public License, either version 1.3
+ of this license or (at your option) any later version.}}
+\hypersetup{pdflicenseurl={http://www.latex-project.org/lppl.txt}}
+\hypersetup{pdfcontactaddress={ETH Zurich, ITP, HIT K,
+ Wolfgang-Pauli-Strasse 27}}
+\hypersetup{pdfcontactpostcode={8093}}
+\hypersetup{pdfcontactcity={Zurich}}
+\hypersetup{pdfcontactcountry={Switzerland}}
+\hypersetup{pdfcontactemail={nbeisert@itp.phys.ethz.ch}}
+\hypersetup{pdfcontacturl={http://people.phys.ethz.ch/\xmptilde nbeisert/}}
+
+\newcommand{\secref}[1]{\hyperref[#1]{section \ref*{#1}}}
+
+\parskip1ex
+\parindent0pt
+\let\olditemize\itemize
+\def\itemize{\olditemize\parskip0pt}
+
+\begin{document}
+
+\title{The \textsf{mpostinl} Package}
+\hypersetup{pdftitle={The mpostinl Package}}
+\author{Niklas Beisert\\[2ex]
+ Institut f\"ur Theoretische Physik\\
+ Eidgen\"ossische Technische Hochschule Z\"urich\\
+ Wolfgang-Pauli-Strasse 27, 8093 Z\"urich, Switzerland\\[1ex]
+ \href{mailto:nbeisert@itp.phys.ethz.ch}
+ {\texttt{nbeisert@itp.phys.ethz.ch}}}
+\hypersetup{pdfauthor={Niklas Beisert}}
+\hypersetup{pdfsubject={Manual for the LaTeX2e Package mpostinl}}
+\date{30 December 2018, \textsf{v1.5}}
+\maketitle
+
+\begin{abstract}\noindent
+\textsf{mpostinl} is a \LaTeXe{} package
+which enables the embedding of \MP{} figures
+within a \LaTeX{} document.
+The package automatically collects the embedded
+definitions and figures in a |.mp| file,
+adds an appropriate \LaTeX{} document structure,
+and compiles it to |.mps| files.
+It also allows for various configuration options
+to manage the generation of files and compilation.
+\end{abstract}
+
+\begingroup
+\parskip0ex
+\tableofcontents
+\endgroup
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Introduction}
+
+\MP{} is a versatile tool
+to generate vector graphics files
+from a plain text source for inclusion
+in \LaTeX{} documents which allows to typeset labels
+in native \LaTeX{} code and fonts.
+The \MP{} compiler |mpost| typically compiles a
+metapost source file (extension |.mp|) to
+a set of metapost figure files (extension |.mps|)
+which are encapsulated postscript files (|.eps|)
+with a somewhat reduced scope.
+The figure files can be included in a \LaTeX{}
+document by |\includegraphics|,
+and modern \TeX{} distributions are typically able to handle
+the required conversions on the fly.
+
+While many steps in the compilation process are automated,
+some management is left to the user:
+\begin{itemize}
+\item
+Link the figures in the metapost source
+with the \LaTeX{} source by choosing an
+appropriate figure filename (or numeric identifier).
+\item
+When a figure is changed,
+the metapost source file must be compiled
+to update the figure files,
+and afterwards the \LaTeX{} source must be compiled
+to introduce the changes into the output document.
+\item
+Keep any changes aligned between \LaTeX{}
+and metapost source files.
+\item
+Set up a proper \LaTeX{} document structure
+to compile labels via \LaTeX{}.
+\item
+Distribute source and figures as separate files.
+\end{itemize}
+%
+The current \LaTeX{} package \textsf{mpostinl}
+helps in the management of metapost figures
+by embedding them into the \LaTeX{} source:
+%
+\begin{itemize}
+\item
+Figures are displayed at the location of their definition
+within the \LaTeX{} source
+to facilitate alignment between text and figures.
+\item
+A metapost source file with \LaTeX{} structure
+for the labels is generated.
+\item
+Figure files are compiled automatically
+from within the \LaTeX{} compiler.
+\end{itemize}
+%
+For example, a simple figure consisting
+of a circle might be represented as:
+%
+\begin{verbatim}
+ \begin{mpostfig}
+ draw fullcircle scaled 1cm;
+ \end{mpostfig}
+\end{verbatim}
+%
+The package also offers several options and customisations
+to streamline its use in several situations:
+%
+\begin{itemize}
+\item
+Figures can be assigned labels or filenames for later usage.
+\item
+There are several options and mechanisms to
+minimise the need for multiple compiler passes
+to generate the desired output.
+\item
+The package can handle several metapost files in a row
+with common definitions or include files.
+\item
+The font generation, \LaTeX{} structure
+and generated filenames can be customised.
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Related CTAN Packages}
+
+There are at least four other \LaTeX{} packages
+which offer a similar functionality:
+%
+\begin{itemize}
+\item
+The package \href{http://www.ctan.org/pkg/emp}{\textsf{emp}}
+provides similar basic functionality to compose a metapost file,
+but it does not automatically compile it.
+Analogously to the |picture| environment
+the size for every figure must be specified explicitly.
+\item
+The package \href{http://ci.uofl.edu/tom/software/LaTeX/}{\textsf{mpfig}}
+by Tomasz Cholewo (not available on CTAN)
+provides very basic functionality to compose a metapost file.
+\item
+The package \href{http://www.ctan.org/pkg/mpgraphics}{\textsf{mpgraphics}}
+provides similar functionality to compose and compile a metapost file.
+It processes all figures immediately and does not offer labels
+for recycling figures.
+\item
+The package \href{http://www.ctan.org/pkg/gmp}{\textsf{gmp}}
+provides similar functionality to compose and compile a metapost file.
+It processes all figures immediately and allows to inject \LaTeX{}
+definitions into the metapost code at the price of
+modifying the metapost syntax slightly.
+\end{itemize}
+%
+The philosophy of the present package is to generate a
+single metapost file containing all figures
+as in a traditional metapost setup
+which can be compiled in one pass.
+The aim is to provide a metapost setup which works
+with as little configuration as possible,
+but which offers several configuration options to
+customise the management in the desired way.
+The package offers most of the functionality of the above packages,
+but (presently) misses out on some more advanced features,
+see \secref{sec:suggestions}.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Usage}
+
+This manual assumes familiarity
+with the \MP{} figure description language.
+The \MP{} manual is a recommended introduction
+and an excellent reference.
+
+To use the package \textsf{mpostinl} add the command
+\begin{center}
+|\usepackage{mpostinl}|
+\end{center}
+to the preamble of your \LaTeX{} document.
+If not yet present,
+the package \textsf{graphicx} will be loaded automatically.
+Metapost figures and definitions are to be specified using
+the environments |mpostfig| and |mpostdef|, respectively,
+as described in \secref{sec:figuresdefinitions}.
+
+The package collects the figure files
+contained in the \LaTeX{} source,
+writes them to a metapost file,
+and compiles them at the end of the \LaTeX{} document.
+This means that the figures (or their updates)
+will normally \emph{not} be available
+in the first \LaTeX{} run and a secondary run is required
+for the correct output,
+see \secref{sec:immediate} for strategies
+to avoid a second pass.
+
+You should make sure that \LaTeX{} allows
+calling of external programs.
+If this feature is not enabled by default,
+it is achieved by calling |latex|
+with the command line option |-shell-escape|
+(or |-shell-restricted| if |mpost|
+is in the list of permissible commands):
+\begin{center}
+|latex -shell-escape |\textit{source}
+\end{center}
+In the MiK\TeX{} distribution the appropriate
+command line option is |-enable-write18|.
+In a \LaTeX{} front end this option may
+be configurable in the preferences.
+If the shell escape is not available,
+the generated metapost file(s) \textit{filename}
+(typically the same as the \LaTeX{} source \textit{source})
+must be compiled manually:
+\begin{center}
+|mpost -tex=latex |\textit{filename}
+\end{center}
+
+Some extended configuration options and situations are described in
+the following sections:
+package options are listed in \secref{sec:packageoptions};
+some options for writing and compiling are discussed
+in \secref{sec:compiling};
+the generation of multiple metapost files
+is described in \secref{sec:multiplefiles};
+finally, some issues regarding other \LaTeX{} packages
+are discussed in \secref{sec:interactions}.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Figures and Definitions}
+\label{sec:figuresdefinitions}
+
+\DescribeEnv{mpostfig}
+The main functionality provided
+by the package is the |mpostfig| environment:
+\begin{center}
+\begin{tabular}{l}
+|\||begin{mpostfig}[|\textit{opts}|]|\\
+| |\textit{metapost code}\\
+|\||end{mpostfig}|
+\end{tabular}
+\end{center}
+%
+The above block is translated
+to the following code in the metapost file:
+%
+\begin{center}
+\begin{tabular}{l}
+|filenametemplate:="|\textit{filename}|";|\\
+|beginfig(|\textit{number}|)|\\
+| |\textit{metapost code}\\
+|endfig;|
+\end{tabular}
+\end{center}
+%
+The optional argument \textit{opts} of the |mpostfig| environment
+is a comma-separated list of options:
+%
+\begin{itemize}
+\item |show|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Show the figure in place.
+If neither |file| nor |label| are specified,
+this option is forced to |true|.
+
+\item |file=|\textit{filename} --
+Filename for the figure.
+
+\item |label=|\textit{label} --
+Label for later use by the command |\mpostuse{|\textit{label}|}|.
+
+\item |opt=|\textit{opt} --
+Options to be passed on to |\includegraphics[|\textit{opt}|]|.
+
+\item |now|[|=true|$\vert$|false|]
+(no value implies |true|, overrides global setting |nowall|) --
+Compile figure immediately. Requires global option |now| to work.
+
+\item |twice|[|=true|$\vert$|false|]
+(no value implies |true|, overrides global setting |twice|) --
+Compile this figure twice.
+
+\end{itemize}
+%
+Please note the following restrictions
+due to the implementation via the package \textsf{verbatim}:
+%
+\begin{itemize}
+\item
+The closing statement |\||end{mpostfig}| must be on a line on its own.
+Any amount of leading whitespace is allowed,
+and trailing characters are ignored.
+
+\item
+The opening statement |\||begin{mpostfig}| has to find out
+whether an optional argument is provided
+by scanning into the block of metapost content.
+If none is given, all the code already scanned needs to be
+(re)interpreted as metapost content.
+In special circumstances this may cause problems.
+It should then help to use an empty optional argument:
+|\||begin{mpostfig}[]|.
+
+\item
+Lines starting with a single `|%|'
+are ignored and do not appear in the metapost file.
+Double `|%%|'
+or leading spaces preserve comments in the metapost file.
+
+\item
+The environment |mpostfig|
+cannot be used within macro arguments or particular other environments.
+If you want to display a figure in these situations,
+you should declare the figure with a label and
+display it via the command |\mpostuse| (see below).
+
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\DescribeMacro{\mpostuse}
+Figures which have been previously declared
+with a label \textit{label}
+can be recycled any number of times with the command:
+\begin{center}
+|\mpostuse[|\textit{opts}|]{|\textit{label}|}|
+\end{center}
+The options are passed on to
+|\includegraphics[|\textit{opt}|]{|\textit{filename}|}|.
+Note that |\mpostuse| accepts the overlay specification
+from the \textsf{beamer} package
+\begin{center}
+|\mpostuse<|\textit{overlay}|>[|\textit{opts}|]{|\textit{label}|}|
+\end{center}
+and passes it on to |\includegraphics|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\DescribeMacro{\mpostgetname}
+Furthermore, the filename of a figure can be obtained by
+calling |\mpostgetname{|\textit{label}|}|.
+The filename is returned in the macro |\mpostfigurename|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\DescribeEnv{mpostdef}
+Plain metapost code which is not part of a figure
+(definitions, assignments)
+can be specified by the |mpostdef| environment:
+%
+\begin{center}
+\begin{tabular}{l}
+|\||begin{mpostdef}[|\textit{opts}|]|\\
+| |\textit{code}\\
+|\||end{mpostdef}|
+\end{tabular}
+\end{center}
+%
+Note that the same restrictions as for |mpostfig| (see above)
+apply to |mpostdef|.
+The optional argument \textit{opts}
+is a comma-separated list of options:
+%
+\begin{itemize}
+\item |global|[|=true|$\vert$|false|]
+(no value implies |true|, overrides global setting |globaldef|) --
+In a setup with multiple metapost files, the block \textit{code}
+is applied to all files, not just the current file.
+
+\item |tex|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+The block \textit{code} represents \TeX{} or \LaTeX{} definitions
+rather than \MP{} code,
+which will be enclosed in the metapost file by |verbatimtex| and |etex|.
+This feature is superseded by the environment |mposttex| described below.
+The |tex| option is deprecated, and provided for backward compatibility only.
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\DescribeEnv{mposttex}
+\TeX{} or \LaTeX{} definitions for use in metapost labels
+can be specified by the |mposttex| environment:
+%
+\begin{center}
+\begin{tabular}{l}
+|\||begin{mposttex}[|\textit{opts}|]|\\
+| |\textit{code}\\
+|\||end{mposttex}|
+\end{tabular}
+\end{center}
+%
+The code will be enclosed in the metapost file by |verbatimtex| and |etex|.
+Note that the same restrictions as for |mpostfig| (see above)
+apply to |mposttex|.
+The optional argument \textit{opts}
+is a comma-separated list of options:
+%
+\begin{itemize}
+\item |global|[|=true|$\vert$|false|]
+(no value implies |true|, overrides global setting |globaldef|) --
+In a setup with multiple metapost files, the block \textit{code}
+is applied to all files, not just the current file.
+
+\item |dual|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+The definitions within the block \textit{code}
+will be available to both metapost figures and subsequent \LaTeX{} code.
+
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Package Options}
+\label{sec:packageoptions}
+
+\DescribeMacro{\mpostsetup}
+Options can be passed to the package by:
+\begin{center}
+\begin{tabular}{rl}
+&|\usepackage[|\textit{opts}|]{mpostinl}|
+\\
+or&|\PassOptionsToPackage{|\textit{opts}|}{mpostinl}|
+\\
+or&|\mpostsetup{|\textit{opts}|}|
+\end{tabular}
+\end{center}
+%
+|\PassOptionsToPackage| must be used before |\usepackage|;
+|\mpostsetup| must be used afterwards (for selected options).
+\textit{opts} is a comma-separated list of options.
+Below we provide a complete list of available options
+while some of the more relevant options are discussed
+in detail in the following sections:
+%
+\begin{itemize}
+\item |draft|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Enable/disable |draft| mode by declaring |draft:=1|
+at the top of the metapost file.
+
+\item |final| --
+Same as |draft=false|.
+
+\item |write|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |true|) --
+Enable/disable writing to metapost file.
+
+\item |compile|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |true|) --
+Enable/disable automatic compilation of metapost file.
+Requires shell escapes to work properly.
+
+\item |twice|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Enable/disable secondary metapost compilation.
+Some metapost files may require this to produce the intended output.
+
+\item |clean|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |true|) --
+Enable/disable cleaning of figure files prior to compilation.
+A dummy figure will be shown in case metapost cannot generate a figure.
+
+\item |checksum|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Enable/disable update detection.
+Compiles figures only if the metapost code has changed.
+
+\item |fonts|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Enable/disable embedding of fonts in metapost figures
+by setting |prologues:=3| thus making them proper
+encapsulated postscript files.
+This option may be required if figure files are
+used outside a \TeX{} environment,
+e.g.\ if the files are to be viewed or processed by |.eps| tools.
+Has no effect if |prologues| option is specified.
+
+\item |prologues=|\textit{value} --
+Declares |prologues:=|\textit{value} at the top of the metapost file.
+Set \textit{value} to empty to disable the |prologues| statement.
+
+\item |lineno|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Enable/disable line number indicators in the metapost file.
+All blocks in the metapost file will start with the line number
+where this block can be found in the \LaTeX{} source file.
+To view the source file name
+you should load the package \textsf{currfile}.
+
+\item |labelnames|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Use the figure label instead of a consecutive number
+to construct the name for figure files.
+The benefit of this mode is that the label will usually stay fixed
+while the number may change when adding or removing figures.
+The drawback is that the \LaTeX{} internal labels will appear as
+part of the filenames cluttering the directory slightly more.
+Moreover, one has to make sure that the figure labels
+are valid filenames in your operating system,
+i.e.\ use special characters with care,
+better only use alphanumeric characters,
+and bear in mind that some operating systems do
+not distinguish upper- and lowercase letters.
+
+\item |latex|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |true|) --
+Switch between \TeX{} (|false|) and \LaTeX{} (|true|)
+processing of labels.
+In \LaTeX{} mode a basic \LaTeX{} document structure is
+provided by the metapost file.
+
+\item |compiler=|\textit{compiler} --
+Set the compiler program for labels to \textit{compiler}
+(command line option |-tex=|\textit{compiler} for \MP).
+The default is |tex| (in \TeX{} mode)
+or |latex| (in \LaTeX{} mode).
+Set \textit{compiler} to empty to specify no compiler.
+
+\item |format=|\textit{tag} --
+Write format tag |%&|%
+\textit{tag} to specify the compiler program for labels.
+The default is |tex| (in \TeX{} mode)
+or |latex| (in \LaTeX{} mode).
+Set \textit{tag} to empty to write no format tag.
+
+\item |class=|\textit{class}
+(initially set to |article|) --
+Set the document class to be used in \LaTeX{} mode.
+
+\item |classopt=|\textit{options} --
+Set the options for the |\documentclass| statement in \LaTeX{} mode,
+e.g.\ |12pt| or |11pt|.
+No options are specified initially resulting in the |10pt| font set.
+
+\item |mem=|\textit{mem} --
+Set the metapost format file to \textit{mem}.
+
+\item |command=|\textit{command} --
+Use \textit{command} to process the generated file(s).
+By default the \MP{} program |mpost| is invoked
+to compile the generated metapost files
+(with appropriate command line options).
+
+\item |now|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Activate/deactivate immediate mode.
+In immediate mode, figures can be processed immediately
+so that a secondary \LaTeX{} pass is not required to
+display the figure correctly.
+Note that this option merely enables recording
+of all the required definitions
+so that immediate processing will be possible,
+but it does not activate immediate processing per se.
+
+\item |nowall|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Enable/disable immediate processing for all figures by default.
+This option will call the \MP{} compiler for every figure.
+While convenient, it requires heavier processing.
+
+\item |nowkeep|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Enable/disable immediate generation
+of figures by individual metapost files.
+If this mode is enabled,
+the filename for immediate processing
+of the figure \textit{filename}|.mps|
+will be \textit{filename}|.mp|.
+Otherwise the metapost code is stored in a temporary file and
+is overwritten by any subsequent immediate processing.
+
+\item |globaldef|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|) --
+Enable/disable the |global| option
+for the |mpostdef| and |mposttex| environments by default.
+This option can be used to specify a global block of definitions
+by enclosing it with appropriate |\mpostsetup| statements.
+
+\item |template=|\textit{template}
+(initially set to |\mpostfilename-#1.mps|) --
+Set the template for figure filenames
+for which it is not given explicitly.
+The parameter |#1| carries the number (or label) to be used.
+Moreover, the macro |\mpostfilename|
+carries the current metapost file.
+
+\item |extension=|\textit{ext}
+(initially set to |mps|) --
+Set the default extension for figure filenames.
+
+\item |numberwithin=|\textit{counter} --
+Declares the figure counter
+to be a child of \textit{counter}.
+In other words, the figure counter
+is reset when \textit{counter} is increased,
+and the figure number will be composed
+as \textit{counter}|-|\textit{figure}.
+Using this option with a top-level counter
+such as |section| or |chapter|
+stabilises the figure numbering
+by making changes to the sequence have
+effects only within the present section or chapter.
+
+\item |beamer|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |true|) --
+Enable/disable processing of overlay parameters |<|\ldots|>|
+by |\mpostuse| defined by the \textsf{beamer} package.
+
+\item |warnunused|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |true|) --
+Enable/disable warnings for unused figure labels.
+
+\end{itemize}
+%
+Admittedly, some of these options are hardly necessary
+as they will have little impact on output
+or performance in ordinary situations.
+They are provided for completeness,
+to make the package work in more exotic situations,
+and/or to satisfy some personal taste regarding
+how things should be managed.
+
+\DescribeMacro{\mpostplaceholder}
+\DescribeMacro{\mpostdisplaylabel}
+Finally, the package allows to customise the placeholder
+which is displayed when a figure file is not (yet) present
+after the first \LaTeX{} pass (or in case of some compile error)
+or a figure label does not exist.
+In these situations the following macro is called:
+\begin{center}
+|\mpostplaceholder[|\textit{type}|]{|\textit{name}|}|
+\end{center}
+\textit{type} is either `|file|' or `|label|'
+and \textit{name} is the missing filename or label.
+By default this command displays a 1''$\times$0.6'' box
+containing the missing filename or label.
+This behaviour can be customised by overwriting the macro.
+It makes sense to display the filename or label through
+|\mpostdisplaylabel| which can handle some special characters
+such as an underscore.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Writing and Compiling Options}
+\label{sec:compiling}
+
+The following discusses some package options regarding the writing
+and compiling of metapost files in more detail.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Label Typesetting Options.}
+
+Metapost figure files may or may not include the \MF{} fonts
+which are used by the figure labels.
+When the generated metapost figures
+are only used within a \LaTeX{} document
+in a standard \TeX{} distribution, it is not necessary to
+include the required fonts as they are automatically
+supplied by the \LaTeX{} compiler.
+This omission reduces the size of the figure files
+(but apparently it has no impact
+on the size of the compiled \LaTeX{} document
+in modern \TeX{} distributions).
+However, the postscript structure
+of such figure files is incomplete,
+and therefore the labels typically appear distorted
+in external viewing or processing tools.
+If the figure files are to be viewed,
+processed or passed on to
+a publisher, it makes sense to include the required fonts.
+The latter is achieved by enabling the package option |fonts|.
+In this context, one can also set the default figure file
+extension to |eps| by means of the package option |extension|.
+
+By default, the package provides a \LaTeX{} document structure
+for processing labels by \LaTeX{}.
+The default document class is |article| without options.
+An alternative class and options can be specified
+by the package options |class| and |classopt|.
+Further packages or macros should be declared as usual
+by specifying them in a |mposttex| enviroment.
+If no \LaTeX{} structure is desired,
+set the package option |latex| to |false|.
+If the typesetting requires an advanced compiler
+beyond |latex| or |tex|, it should be
+specified by the package option |compiler|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Compiling Options.}
+
+When the figure files are in a final form
+it may make sense to disable the compiling
+or even the writing of the metapost file(s)
+by setting the package options |compile|
+or |write| to |false|.
+In particular, this may be desirable
+if the \LaTeX{} source is uploaded to a repository
+or passed on to a publisher.
+
+The package can check whether the generated files
+change with respect to the previous \LaTeX{} pass,
+and only modified files are compiled thereupon.
+This check can be enabled by setting the option
+|checksum| to |true|.
+Note that under some conditions
+(in particular, if the previous \LaTeX{} pass
+produced compile errors),
+figures may not get compiled even though the source changed.
+In that case you can trigger compilation
+by deleting the generated metapost source or figures
+or by introducing further changes to the metapost code.
+By default all files are compiled.
+
+When the metapost file compiles with errors,
+one can inspect the generated metapost file.
+To this end it may be helpful to know which
+part of the \LaTeX{} source file is responsible
+for which part of the metapost file.
+The package option |lineno| activates
+prepending every block in the metapost file
+by the corresponding location in the \LaTeX{} source.
+If the \LaTeX{} source is distributed over several files,
+the source filename can also be provided
+if the package \textsf{currfile} is loaded.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Filename Options.}
+
+By default the names of figure files take the form
+%
+\begin{center}
+\textit{filename}|-|\textit{specifier}|.|\textit{ext}
+\end{center}
+where \textit{filename} is the name of the metapost file,
+\textit{specifier} is an integer number which enumerates the figures
+and \textit{ext} is `|mps|'.
+There are several options to customise the scheme:
+%
+\begin{itemize}
+\item
+The figure option |file| allows to explicitly specify
+the desired filename.
+
+\item
+The package option |numberwithin=|\textit{section} can be used to
+associate the counting with a top-level section counter
+(such as `|section|' or `|chapter|').
+Then \textit{specifier} takes the form
+\textit{section}|-|\textit{number},
+where \textit{number} is an integer that enumerates the figures
+within the present \textit{section}.
+
+\item
+The package option |labelnames| lets \textit{specifier}
+be the figure label. This option should be used with care,
+as the operating system does not necessarily allow
+or distinguish all characters which are available for \TeX{} macros.
+
+\item
+The extension \textit{ext} can be customised
+by the package option |extension|.
+
+\item
+The package option |template|
+allows to customise the above template.
+In composing the template,
+the argument |#1| carries the \textit{specifier}
+and |\mpostfilename| carries the name
+of the present metapost file.
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Multiple Files}
+\label{sec:multiplefiles}
+
+By default the package \textsf{mpostinl} writes out a single file
+\textit{source}|.mp| if the \LaTeX{} source is called \textit{source}|.tex|.
+However, the package can also be configured
+to write out several metapost files.
+This feature can be used to declare one metapost file
+for each top-level section of a large \LaTeX{} document
+(e.g.\ section or chapter).
+Alternatively, one could define
+different metapost files for figures of different kinds
+(e.g.\ technical drawings, diagrams, graphs, charts).
+Note that these could well use different
+sets of metapost macros and variables.
+
+This feature can make sense
+if the metapost source or generated figures
+are to be passed on to someone else (e.g.\ publisher)
+in order to help clarify the placement of figures.
+It may also be useful if selected sections
+of the document are generated
+individually by means of |\includeonly|,
+in which case only the relevant metapost file
+is generated and compiled.
+
+The contents of each metapost file should be enclosed
+by |\mpostfile| and |\mpostdone|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\DescribeMacro{\mpostfile}
+A new metapost file is started by the command:
+\begin{center}
+|\mpostfile[|\textit{opts}|]{|\textit{filename}|}|
+\end{center}
+%
+\textit{filename} is the filename without |.mp| extension.
+\textit{opt} is a comma-separated list of options:
+the only available option is |include|[|=true|$\vert$|false|]
+(no value implies |true|, initially set to |false|)
+which declares whether the file is an include file.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\DescribeMacro{\mpostdone}
+The present metapost file is completed by the command
+|\mpostdone| which also compiles the contained figures.
+Note that this command is called automatically
+at the end of the \LaTeX{} document.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Global Definitions.}
+
+Definitions in |mpostdef| and |mposttex| environments apply to the
+present metapost file only. However, definitions can also be
+specified for all metapost files
+by means of the option |global|:
+\begin{center}
+|\||begin{mpostdef}[global]|
+\end{center}
+These definitions are stored internally and will be written
+to all subsequent metapost files.
+
+To declare several consecutive (or all)
+blocks of definitions as global,
+one can use the package option |globaldef|.
+To that end, enclose the blocks by
+|\mpostsetup{globaldef=true}| and |\mpostsetup{globaldef=false}|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Include Files.}
+
+Alternatively, global definitions can be saved to an include file.
+This may make sense if there is a large amount of definitions
+which should not be written to each and every metapost file.
+An include file is declared by
+|\mpostfile[include]{|\textit{filename}|}|
+and will be used by all subsequent main metapost files.
+Include files are equivalent to global definitions,
+but they cannot contain \TeX{} definitions.
+Moreover they must not contain figures.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Immediate Processing}
+\label{sec:immediate}
+
+By default, the metapost file is compiled
+at the end of the \LaTeX{} document.
+Therefore all new figures and any changes to existing figures
+are not reflected in the compiled \LaTeX{} document
+after the first pass.
+A second \LaTeX{} pass is needed to generate the desired output.
+Moreover, any change to the sequence of figures
+(figures inserted, deleted or moved)
+can only be seen after the second pass;
+the first pass shows the old sequence.
+
+In the following we present some strategies to minimise or avoid
+this issue.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Collecting Figures at the Top.}
+
+One option is to declare all figures
+with labels near the top of the document,
+and close the metapost file by the command |\mpostdone|.
+The compiled figures are immediately available afterwards.
+A side effect is that metapost
+and \LaTeX{} source is necessarily separated
+(which may be considered a benefit
+or a drawback depending on philosophy).
+Note that in a setup with multiple metapost files,
+the figures can be defined at the top of each section
+thereby allowing some association between figures and manuscript.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Stable Filenames.}
+
+A change of figure sequence can have irritating effects
+because some figures are displayed
+in the wrong place in the first pass.
+Even though a second pass resolves this issue,
+the first pass may have upset the page composition
+so that some labels containing page numbers can be messed up
+in the second pass thus requiring a third pass.
+There are some methods to reduce this effect:
+\begin{itemize}
+\item
+Provide a filename for each figure by the option |file|.
+
+\item
+Automatically align the figure filenames with the labels by
+the package option |labelnames|.
+
+\item
+Use the package option |numberwithin| with the counter
+of the top-level section.
+Changes of the figure order will then
+be contained within each section.
+
+\item
+Use one metapost file for each top-level section.
+Changes of the figure order will then
+be contained within each metapost file.
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Immediate Processing.}
+
+The above strategies are workarounds, but the package also provides
+a mechanism to compile individual figures or all figures at once.
+The drawback is that one metapost file with all relevant definitions
+needs to be generated and compiled for each figure.
+This may have some negative impact on performance
+for very large documents with excessively many figures,
+if many such documents are to be generated in a row,
+if the computer is slow or busy otherwise,
+or if the laptop battery is low on a long journey
+(or eventually if the user is old-fashioned or paranoid).
+
+The mechanism is enabled by the package option |now|.
+While composing or editing individual figures,
+one can specify the figure option |now|,
+and remove it when the figure is final.
+Alternatively one can activate immediate processing for all figures
+with the package option |nowall| (together with |now|).
+Ordinarily, a temporary file is used for the metapost source
+for immediate processing.
+If the metapost sources for individual figures are needed,
+the package option |nowkeep| stores the metapost source
+for every generated figure \textit{filename}|.mps|
+in the file \textit{filename}|.mp|.
+When the figures are in a final state,
+all immediate processing can be disabled by turning off the package
+option |now|.
+
+Note that changing some variables within the figure blocks
+can have undesired effects for immediate processing:
+In immediate processing only the present figure is included
+in the metapost file,
+otherwise the metapost file contains the sequence of all figures.
+Therefore, a change or (re)definition of a variable within
+a figure block will not be visible to all subsequent figures
+in immediate mode!
+To avoid such situations:
+%
+\begin{itemize}
+\item
+Do not (re)define variables within a figure block.
+Use a definition block before the figure instead.
+\item
+Provide an initial value for all used variables
+which could change within other figures.
+\item
+For internal variables (such as the size |ahlength| of an arrow head)
+you can |save| the initial value before
+the first redefinition within a figure block.
+Alternatively you can prepend the first change to the variable
+by |interim|.
+Note that you can declare variables as internal
+by means of |newinternal|.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Interaction with Other Packages}
+\label{sec:interactions}
+
+The following lists some potential issues in
+the interaction with other \LaTeX{} packages:
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Package \textsf{inputenc}.}
+This package should not interfere with the input encoding
+selected via the package \textsf{inputenc}, e.g.\ |utf8| encoding.
+Extended characters are passed on
+unchanged by the |mpostfig| environment.
+If you declare an input encoding for your \LaTeX{} source by:
+\begin{center}
+|\usepackage[|\textit{enc}|]{inputenc}|
+\end{center}
+you should select the \emph{same} input encoding for the labels
+in the metapost figures by means of:
+\begin{center}
+\begin{tabular}{l}
+|\||begin{mposttex}|\\
+|\usepackage[|\textit{enc}|]{inputenc}|\\
+|\||end{mposttex}|
+\end{tabular}
+\end{center}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Package \textsf{beamer}.}
+
+The package \textsf{beamer} is a popular package for
+preparing slideshow presentations.
+In particular, slides can be presented in several steps
+by means on an overlay mechanism.
+To that end the |frame| environment
+saves the enclosed block and processes it in several passes.
+Therefore, the environments |mpostfig|, |mpostdef| and |mposttex|
+must not be used within the |frame| environment.
+Instead, figures should be declared outside the |frame| environment
+and can be displayed by |\mpostuse| within the |frame| environment.
+Note that |\mpostuse| accepts the overlay parameter |<|\ldots|>|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Package \textsf{graphbox}.}
+
+Figures are eventually displayed by the |\includegraphics| command
+which aligns the graphics with the bottom of the current line.
+To achieve different alignments or placements takes some efforts.
+The package \textsf{graphbox} extends the optional
+arguments of |\includegraphics| to customise the alignment conveniently.
+Since graphics arguments are passed on directly to |\includegraphics|
+the \textsf{graphbox} package can be used without restrictions.
+For instance, to align a figure vertically with the centre of the line,
+you may use |\||begin{mpostfig}[opt={align}]|
+or |\mpostuse[align]{|\textit{label}|}|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Package \textsf{latexmp}.}
+
+The \MP{} package \textsf{latexmp} writes its own \LaTeX{} structure
+to the metapost file.
+Therefore \textsf{mpostinl} must not write the \LaTeX{} structure,
+but still use the |latex| compiler.
+Furthermore \textsf{latexmp} needs two \MP{} passes.
+The required options are:
+\begin{center}
+|\mpostsetup{latex=false,format,compiler=latex,twice}|
+\end{center}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{Script \textsf{mplatex}.}
+
+The \MP{} processing script \textsf{mplatex} expects the default metapost
+file naming convention (\textit{filename}|.|\textit{nn})
+and no |prologues| statement.
+Moreover, it provides the \LaTeX{} structure.
+The required options are:
+%
+\begin{center}
+\begin{tabular}{l}
+|\mpostsetup{latex=false,format,prologues}|\\
+|\mpostsetup{template={\mpostfilename.#1}}|\\
+|\mpostsetup{command={mplatex |\textit{opt}|}}|
+\end{tabular}
+\end{center}
+%
+In \textit{opt} you can specify command line options for |mplatex|,
+e.g.\ to include \LaTeX{} packages.
+Make sure to enable full access to external programs,
+and that |mplatex| is in the path (or specify its location explicitly).
+Note that the file naming convention (\textit{filename}|.|\textit{nn})
+does not seem to work with pdf\LaTeX{}.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Information}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Copyright}
+
+Copyright \copyright{} 2010--2018 Niklas Beisert
+
+This work may be distributed and/or modified under the
+conditions of the \LaTeX{} Project Public License, either version 1.3
+of this license or (at your option) any later version.
+The latest version of this license is in
+ \url{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 Niklas Beisert.
+
+This work consists of the files |README.txt|, |mpostinl.ins| and |mpostinl.dtx|
+as well as the derived files |mpostinl.sty|, |mpinlsmp.tex| and |mpostinl.pdf|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Files and Installation}
+
+The package consists of the files:
+%
+\begin{center}
+\begin{tabular}{ll}
+ |README.txt| & readme file \\
+ |mpostinl.ins| & installation file \\
+ |mpostinl.dtx| & source file \\
+ |mpostinl.sty| & package file \\
+ |mpinlsmp.tex| & sample file \\
+ |mpostinl.pdf| & manual
+\end{tabular}
+\end{center}
+%
+The distribution consists of the files
+|README.txt|, |mpostinl.ins| and |mpostinl.dtx|.
+%
+\begin{itemize}
+\item
+Run (pdf)\LaTeX{} on |mpostinl.dtx|
+to compile the manual |mpostinl.pdf| (this file).
+\item
+Run \LaTeX{} on |mpostinl.ins| to create the package |mpostinl.sty|
+and the sample |mpinlsmp.tex|.
+Copy the file |mpostinl.sty| to an appropriate directory of your \LaTeX{}
+distribution, e.g.\ \textit{texmf-root}|/tex/latex/mpostinl|.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Required Packages and Software}
+
+The package relies on other packages and software:
+\begin{itemize}
+\item
+This package relies on some functionality of the package \textsf{verbatim}
+to read verbatim code from the \LaTeX{} source without expansion of macros.
+Compatibility with the \textsf{verbatim} package
+has been tested with v1.5q (2014/10/28).
+\item
+This package uses the package \textsf{graphicx}
+from the \textsf{graphics} bundle to include graphics files.
+Compatibility with the \textsf{graphicx} package
+has been tested with v1.0g (2014/10/28).
+\item
+This package uses the package \textsf{keyval}
+from the \textsf{graphics} bundle
+to process the options for the package, environments and macros.
+Compatibility with the \textsf{keyval} package
+has been tested with v1.15 (2014/10/28).
+\item
+This package uses the command |\currfilename|
+provided by the package \textsf{currfile} (if available and loaded)
+to indicate the \LaTeX{} source file in the generated metapost file.
+Compatibility with the \textsf{currfile} package
+has been tested with v0.7c (2015/04/23).
+\item
+The package assumes a \TeX{} installation with \MP{}
+configured appropriately.
+Recent \textsf{texlive} and MiK\TeX{} distributions should work well.
+Compatibility with the \textsf{texlive} distribution
+has been tested with the 2016 issue containing
+pdf\TeX{} version 3.14159265-2.6-1.40.17
+and \MP{} version 1.9991.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Feature Suggestions}
+\label{sec:suggestions}
+
+The following is a list of features which may be useful for future
+versions of this package:
+%
+\begin{itemize}
+\item
+A method to expand \LaTeX{} macros to the metapost code
+to match the corresponding feature of package \textsf{gmp}:
+One difficulty is that direct insertion of \LaTeX{} macros
+requires a substantially different implementation of the
+block scanning method
+because the method supplied by \textsf{verbatim} does not work.
+Furthermore, some escape mechanism is required
+either to expand selected \LaTeX{} macros
+or to prevent their expansion (within |btex| \ldots\ |etex| blocks).
+% encapsulate via | |
+% extra env
+\item
+A simpler approach to the above feature would be to implement a
+command or option to prepend some metapost statements
+to a given metapost block where \LaTeX{} macros are expanded.
+This may work well for passing very few macros to metapost variables.
+However, one would have to decide how aggressively
+macros are to be expanded.
+\item
+Write generated files to a subdirectory
+or remove files not needed after processing.
+However, both appear to be somewhat in contrast
+to the usual \TeX{} philosophy.
+%\item
+%improve detection of changed figure files?
+%allow to declare extra include files for update detection
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Revision History}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.5:} 2018/12/30
+
+\begin{itemize}
+\item
+new environment |mposttex| for \TeX{} or \LaTeX{} definitions
+to replace option |tex| of |mpostdef|;
+can be used in |dual| mode
+\item
+allow underscore, caret and ampersand in figure labels and filenames
+\item
+improve handling of optional arguments and special situations
+when scanning metapost blocks
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.4:} 2018/03/01
+
+\begin{itemize}
+\item
+|\mpostuse| now accepts overlay options |<|\ldots|>|
+of the \textsf{beamer} package;
+new option |beamer| to control the feature
+\item
+issue warnings for unused labels;
+new option |warnunused| to control the feature
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.3:} 2018/02/09
+
+\begin{itemize}
+\item
+new |clean| option to initialise figure files
+with dummy figures to show \MP{} compiler errors
+\item
+|checksum| behaviour improved
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.21:} 2018/01/17
+
+\begin{itemize}
+\item
+remark on leading empty lines added
+\item
+manual rearranged
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.2:} 2018/01/05
+
+\begin{itemize}
+\item
+new option |checksum| to compile only modified files
+(requires the pdf\TeX{} engine, otherwise disabled)
+\item
+warn if some figures may not be up to date
+\item
+bugfix for example if \textsf{graphbox} is not available
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.12:} 2017/06/24
+
+\begin{itemize}
+\item
+bugfix for blank |mpostfig| display
+due to changes in the basic
+\LaTeX{} or \textsf{graphicx} system
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.11:} 2017/04/01
+
+\begin{itemize}
+\item
+implementation of |fonts| option repaired
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.1:} 2017/02/27
+
+\begin{itemize}
+\item
+improved compatibility with package \textsf{latexmp}
+and script \textsf{mplatex}
+(thanks to Walter Entenmann for encouragement and testing)
+\item
+options improved to fine-tune structures written to metapost files
+and to specify compiler programs
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.0:} 2017/01/04
+
+\begin{itemize}
+\item
+manual and install package
+\item
+first version published on CTAN
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v0.7--0.9:} 2016/11/15 -- 2017/01/04
+
+\begin{itemize}
+\item
+package options
+\item
+metapost environments simplified and renamed
+\item
+immediate and multiple file processing
+\item
+customisation options
+\item
+internal buffer processing
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v0.6--0.63:} 2015/07/11 -- 2016/10/03
+
+\begin{itemize}
+\item
+minor improvements
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v0.5:} 2010/11/01
+
+\begin{itemize}
+\item
+basic functionality
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\appendix
+
+\settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
+
+ \DocInput{mpostinl.dtx}
+
+\end{document}
+%</driver>
+% \fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \section{Sample File}
+%\iffalse
+%<*sample>
+%\fi
+%
+% In this section we provide a \LaTeX{} example how to use
+% some of the \textsf{mpostinl} features.
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \subsection{Preamble}
+%
+% Standard document class:
+% \begin{macrocode}
+\documentclass[12pt,a4paper]{article}
+% \end{macrocode}
+
+% Adjust the paragraph shape:
+% \begin{macrocode}
+\parindent0pt
+\parskip6pt
+% \end{macrocode}
+
+% Include the \textsf{mpostinl} package,
+% include \MF{} fonts in the metapost figures:
+% \begin{macrocode}
+\usepackage[fonts=true]{mpostinl}
+% \end{macrocode}
+
+% We will test labels in UTF-8, so include package \textsf{inputenc}:
+% \begin{macrocode}
+\usepackage[utf8]{inputenc}
+% \end{macrocode}
+
+% Include packages \textsf{currfile} and \textsf{graphbox} if available,
+% declare dummy option |align| for |\includegraphics|
+% if \textsf{graphbox} is not available:
+% \begin{macrocode}
+%% optional: add filename to position labels in metapost code
+\IfFileExists{currfile.sty}{\usepackage{currfile}}{}
+%% optional: tools to align graphics
+\makeatletter\define@key{Gin}{align}[]{}\makeatother
+\IfFileExists{graphbox.sty}{\usepackage{graphbox}}{}
+% \end{macrocode}
+
+% Enable immediate mode and line number indicators,
+% prepare some \textsf{mpostinl} options for testing:
+% \begin{macrocode}
+%% some sample package options:
+%% \mpostsetup{write=false}
+%% \mpostsetup{compile=false}
+\mpostsetup{checksum}
+\mpostsetup{now}
+%% \mpostsetup{nowall}
+\mpostsetup{lineno}
+%% \mpostsetup{latex=false}
+%% \mpostsetup{classopt={12pt}}
+% \end{macrocode}
+
+% Include the package \textsf{inputenc}
+% for preparing \LaTeX{} labels within the metapost figures;
+% as we will be generating several metapost files later on,
+% make sure this statement in included in all of them:
+% \begin{macrocode}
+%% declare packages to be used for processing labels:
+\begin{mposttex}[global]
+\usepackage[utf8]{inputenc}
+\end{mposttex}
+% \end{macrocode}
+
+% Define an internal variable |unit| and initialise to 1cm;
+% as we will be generating several metapost files later on,
+% make sure this statement in included in all of them:
+% \begin{macrocode}
+%% specify global definitions:
+\begin{mpostdef}[global]
+newinternal unit;
+unit:=1cm;
+\end{mpostdef}
+% \end{macrocode}
+
+% Begin document body:
+% \begin{macrocode}
+\begin{document}
+% \end{macrocode}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \subsection{Basic Functionality}
+%
+% We start by demonstrating the basic functionality of the package:
+%
+% \begin{macrocode}
+\section{Basic Functionality}
+% \end{macrocode}
+
+% First, draw a circle of diameter 1cm and write a `1' in the centre:
+% \begin{macrocode}
+a plain circle:\\
+\begin{mpostfig}
+draw fullcircle scaled unit;
+label(btex 1 etex, (0,0));
+\end{mpostfig}
+% \end{macrocode}
+
+% Use the options for |\includegraphics|.
+% Draw another circle containing a `2' and scale it by factor $1.5$.
+% Also vertically align to the centre (if \textsf{graphbox} is available):
+% \begin{macrocode}
+scaled (and aligned to centre if available):\\
+X
+\begin{mpostfig}[opt={scale=1.5,align}]
+draw fullcircle scaled unit;
+label(btex 2 etex, (0,0));
+\end{mpostfig}
+X
+% \end{macrocode}
+
+% Declare a figure with label |fig|, do not show:
+% \begin{macrocode}
+declare figure with label (no display).
+\begin{mpostfig}[label={fig}]
+draw fullcircle scaled unit;
+label(btex 3 etex, (0,0));
+\end{mpostfig}
+% \end{macrocode}
+
+% Display the figure:
+% \begin{macrocode}
+display:\\
+\mpostuse{fig}
+% \end{macrocode}
+
+% Display the figure with options for |\includegraphics|:
+% \begin{macrocode}
+display with options:\\
+\mpostuse[scale=1.5,align]{fig}
+% \end{macrocode}
+
+% Display the figure within a box:
+% \begin{macrocode}
+display in a box:\\
+\fbox{\mpostuse{fig}}
+% \end{macrocode}
+
+% Display the figure at the centre of a line:
+% \begin{macrocode}
+centred display:
+\begin{center}
+\mpostuse[scale=1.5]{fig}
+\end{center}
+% \end{macrocode}
+
+% Display the figure within an equation:
+% \begin{macrocode}
+display in equation (align if possible):
+\begin{equation}
+\mpostuse[scale=1.5,align]{fig}
+\end{equation}
+% \end{macrocode}
+
+% Show the filename of the figure:
+% \begin{macrocode}
+filename: \mpostgetname{fig}
+\texttt{\mpostfigurename}
+% \end{macrocode}
+
+% Declare a figure with filename, label and show it,
+% then display filename:
+% \begin{macrocode}
+figure with filename:\\
+\begin{mpostfig}[file={\jobname-name.mps},label={name},show]
+draw fullcircle scaled unit;
+label(btex 4 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{name}
+\texttt{\mpostfigurename}
+% \end{macrocode}
+
+% Display the file via |\includegraphics|.
+% As the figure may not exist (in the first pass)
+% check for existence first to avoid a compile error:
+% \begin{macrocode}
+display by \verb+\includegraphics+ (if file exists):\\
+\IfFileExists{\jobname-name.mps}{\includegraphics{\jobname-name.mps}}{}
+% \end{macrocode}
+
+% Show a figure which does not exist,
+% triggers a warning and displays a box:
+% \begin{macrocode}
+label does not exist:\\
+\mpostuse{not_exist}
+% \end{macrocode}
+
+% Display a figure with a label containing special characters in UTF-8.
+% Note that the internal variable |unit| is changed locally (|interim|)
+% so that subsequent figures will see the old value:
+% \begin{macrocode}
+utf-8 test:\\
+\begin{mpostfig}
+interim unit:=1.5cm;
+draw fullcircle scaled unit;
+label(btex àáâãäåæ etex, (0,0));
+\end{mpostfig}
+% \end{macrocode}
+
+% Write a totally empty figure
+% \begin{macrocode}
+empty figure:\\
+\begin{mpostfig}
+\end{mpostfig}
+% \end{macrocode}
+
+% Write a figure with an empty line
+% \begin{macrocode}
+empty figure:\\
+\begin{mpostfig}
+
+\end{mpostfig}
+% \end{macrocode}
+
+% Make a dual definition
+% \begin{macrocode}
+\begin{mposttex}[dual]
+\def\mymacro{hello!}
+\end{mposttex}
+% \end{macrocode}
+% and test it
+% \begin{macrocode}
+dual definition `\mymacro':\\
+\begin{mpostfig}
+draw unitsquare shifted (-0.5,-0.5) xscaled 3 scaled unit;
+label(btex \mymacro etex, (0,0));
+\end{mpostfig}
+% \end{macrocode}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \subsection{Immediate Processing}
+%
+% Next, we demonstrate immediate processing
+% (make sure to enable the package option |now|):
+%
+% \begin{macrocode}
+\section{Immediate Processing}
+% \end{macrocode}
+
+% Declare a figure for immediate processing.
+% You may change the size |unit| and the figure will be
+% adjusted after the first \LaTeX{} pass:
+% \begin{macrocode}
+immediate processing per figure:\\
+\begin{mpostfig}[now]
+interim unit:=1.5cm;
+draw fullcircle scaled unit;
+label(btex 5 etex, (0,0));
+\end{mpostfig}
+% \end{macrocode}
+
+% One can also enable immediate processing for all subsequent figures.
+% Furthermore, store the metapost source in individual files:
+% \begin{macrocode}
+turn on immediate processing for all figures and keep sources.
+\mpostsetup{nowall,nowkeep}
+% \end{macrocode}
+
+% Now declare a figure with individual metapost source,
+% display via |\includegraphics|,
+% and confirm that source exists:
+% \begin{macrocode}
+generate file \texttt{\jobname-now.mps}:
+\begin{mpostfig}[file={\jobname-now.mps}]
+draw fullcircle scaled unit;
+label(btex 6 etex, (0,0));
+\end{mpostfig}
+\\
+display by \verb+\includegraphics+:\\
+\includegraphics{\jobname-now.mps}
+\\
+source \texttt{\jobname-now.mp}
+\IfFileExists{\jobname-now.mp}{exists}{does not exist}.
+% \end{macrocode}
+
+% Reset immediate processing options for further examples
+% (normally not necessary):
+% \begin{macrocode}
+turn off immediate processing and discard sources.
+\mpostsetup{nowall=false,nowkeep=false}
+% \end{macrocode}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \subsection{Filename Composition}
+%
+% Now, we demonstrate how to adjust the composition of figure filenames:
+%
+% \begin{macrocode}
+\section{Filename Composition}
+% \end{macrocode}
+
+% Use the figure label instead of a figure counter:
+% \begin{macrocode}
+by label:\\
+\mpostsetup{labelnames=true}
+\begin{mpostfig}[label={circle},show]
+draw fullcircle scaled unit;
+label(btex 7 etex, (0,0));
+\end{mpostfig}
+\mpostsetup{labelnames=false}
+\\
+filename: \mpostgetname{circle}
+\texttt{\mpostfigurename}
+% \end{macrocode}
+
+% Change extension to |.eps|:
+% \begin{macrocode}
+change extension:
+\mpostsetup{extension=eps}
+\begin{mpostfig}[label={ext}]
+draw fullcircle scaled unit;
+label(btex 8 etex, (0,0));
+\end{mpostfig}
+\mpostsetup{extension=mps}
+\\
+filename: \mpostgetname{ext}
+\texttt{\mpostfigurename}
+% \end{macrocode}
+
+% Change template altogether:
+% \begin{macrocode}
+change template:\\
+\mpostsetup{template=\mpostfilename-figure-#1.mps}
+\begin{mpostfig}[label={template},show]
+draw fullcircle scaled unit;
+label(btex 9 etex, (0,0));
+\end{mpostfig}
+\mpostsetup{template=\mpostfilename-#1.mps}
+\\
+filename: \mpostgetname{template}
+\texttt{\mpostfigurename}
+% \end{macrocode}
+
+% Demonstrate numbering within a section (here: |subsection|)
+% \begin{macrocode}
+\mpostsetup{numberwithin=subsection}
+% \end{macrocode}
+
+% One figure in the first section:
+% \begin{macrocode}
+\subsection{Section 1}
+
+\begin{mpostfig}[show,label={sec1}]
+draw fullcircle scaled unit;
+label(btex 10 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{sec1}
+\texttt{\mpostfigurename}
+% \end{macrocode}
+
+% Two figures in the second section:
+% \begin{macrocode}
+\subsection{Section 2}
+
+\begin{mpostfig}[show,label={sec2}]
+draw fullcircle scaled unit;
+label(btex 11 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{sec2}
+\texttt{\mpostfigurename}
+
+\begin{mpostfig}[show,label={sec3}]
+draw fullcircle scaled unit;
+label(btex 12 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{sec3}
+\texttt{\mpostfigurename}
+% \end{macrocode}
+
+% One figure in the third section:
+% \begin{macrocode}
+\subsection{Section 3}
+
+\begin{mpostfig}[show,label={sec4}]
+draw fullcircle scaled unit;
+label(btex 13 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{sec4}
+\texttt{\mpostfigurename}
+% \end{macrocode}
+
+% Reset numbering for further examples
+% (normally not necessary, setting cannot be undone completely):
+% \begin{macrocode}
+\makeatletter
+\def\thempi@count{\arabic{mpi@count}}
+\makeatother
+% \end{macrocode}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \subsection{Multiple Files}
+%
+% Finally, demonstrate the generation and usage of several metapost files:
+%
+% \begin{macrocode}
+\section{Multiple Files}
+% \end{macrocode}
+
+% First, close the old metapost file to get to a clean state:
+% \begin{macrocode}
+\mpostdone
+% \end{macrocode}
+
+% Make a definition which will apply to all metapost files.
+% |global| option can be activated
+% for a block of definitions (here only one):
+% \begin{macrocode}
+\mpostsetup{globaldef=true}
+
+\begin{mpostdef}
+unit:=0.8cm;
+\end{mpostdef}
+
+\mpostsetup{globaldef=false}
+% \end{macrocode}
+
+% Alternatively, we can define an include file
+% to be included by all main metapost files.
+% This has the same effect as a global definition,
+% but is intended for long definitions:
+% \begin{macrocode}
+\mpostfile[include]{\jobname-inc}
+
+\begin{mpostdef}
+def drawcircle =
+draw fullcircle scaled unit
+enddef;
+\end{mpostdef}
+
+\mpostdone
+% \end{macrocode}
+
+% The first file contains one figure:
+% \begin{macrocode}
+\subsection*{Section 1}
+\mpostfile{\jobname-sec1}
+
+\begin{mpostfig}[show,label={sec5}]
+drawcircle;
+label(btex 14 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{sec5}
+\texttt{\mpostfigurename}
+
+\mpostdone
+% \end{macrocode}
+
+% The second file contains a local redefinition of |unit|
+% and two figures:
+% \begin{macrocode}
+\subsection*{Section 2}
+\mpostfile{\jobname-sec2}
+
+\begin{mpostfig}[show,label={sec6}]
+drawcircle;
+label(btex 15 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{sec6}
+\texttt{\mpostfigurename}
+
+\begin{mpostdef}
+unit:=1.5cm;
+\end{mpostdef}
+
+\begin{mpostfig}[show,label={sec7}]
+drawcircle;
+label(btex 16 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{sec7}
+\texttt{\mpostfigurename}
+
+\mpostdone
+% \end{macrocode}
+
+% The third file contains one figure. Note that the redefinition
+% of the second file does not apply here:
+% \begin{macrocode}
+\subsection*{Section 3}
+\mpostfile{\jobname-sec3}
+
+\begin{mpostfig}[show,label={sec8}]
+drawcircle;
+label(btex 17 etex, (0,0));
+\end{mpostfig}
+\\
+filename: \mpostgetname{sec8}
+\texttt{\mpostfigurename}
+
+\mpostdone
+% \end{macrocode}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% End of document body:
+% \begin{macrocode}
+\end{document}
+% \end{macrocode}
+%\iffalse
+%</sample>
+%\fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \section{Implementation}
+%\iffalse
+%<*package>
+%\fi
+%
+% In this section we describe the package |mpostinl.sty|.
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Required Packages.}
+%
+% The package loads the packages
+% \textsf{verbatim}, \textsf{graphicx} and \textsf{keyval}
+% if not yet present.
+% \textsf{verbatim} is used for reading verbatim metapost code.
+% \textsf{graphicx} is used for including graphics files.
+% \textsf{keyval} is used for extended options processing.
+% \begin{macrocode}
+\RequirePackage{verbatim}
+\RequirePackage{graphicx}
+\RequirePackage{keyval}
+% \end{macrocode}
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Package Options.}
+%
+% \macro{\mpostfilename}
+% \macro{\mpi@nowname}
+% \macro{\mpi@extension}
+% \macro{\mpi@template}
+% |\mpostfilename| stores the metapost filename,
+% |\mpi@nowname| stores the filename for immediate processing,
+% and |\mpi@template| is the template to generate the figure filenames:
+% \begin{macrocode}
+\def\mpostfilename{\jobname}
+\def\mpi@nowname{\jobname-tmp}
+\def\mpi@extension{mps}
+\def\mpi@template#1{\mpostfilename-#1%
+ \ifx\mpi@extension\mpi@empty\else.\fi\mpi@extension}
+% \end{macrocode}
+
+% \macro{mpi@count}
+% Declare a counter for figure filenames:
+% \begin{macrocode}
+\newcounter{mpi@count}
+\def\thempi@count{\arabic{mpi@count}}
+% \end{macrocode}
+
+% The package has some boolean \textsf{keyval} options
+% which can be set to |true| or |false|.
+% \begin{macrocode}
+\newif\ifmpi@draft\mpi@draftfalse
+\newif\ifmpi@latex\mpi@latextrue
+\newif\ifmpi@fonts\mpi@fontsfalse
+\newif\ifmpi@write\mpi@writetrue
+\newif\ifmpi@compile\mpi@compiletrue
+\newif\ifmpi@twice\mpi@twicefalse
+\newif\ifmpi@clean\mpi@cleantrue
+\newif\ifmpi@checksum\mpi@checksumfalse
+\newif\ifmpi@lineno\mpi@linenofalse
+\newif\ifmpi@labelnames\mpi@labelnamesfalse
+\newif\ifmpi@nowactive\mpi@nowactivefalse
+\newif\ifmpi@now\mpi@nowfalse
+\newif\ifmpi@nowkeep\mpi@nowkeepfalse
+\newif\ifmpi@include\mpi@includefalse
+\newif\ifmpi@defglobal\mpi@defglobalfalse
+\newif\ifmpi@texdual\mpi@texdualfalse
+\newif\ifmpi@warnunused\mpi@warnunusedtrue
+\newif\ifmpi@beamer\mpi@beamertrue
+% \end{macrocode}
+
+% \macro{\mpi@mpostmem}
+% \macro{\mpi@mpostcompiler}
+% \macro{\mpi@latexclass}
+% \macro{\mpi@latexoptions}
+% \macro{\mpi@documentclass}
+% These definitions store the options for processing labels via
+% \TeX{} or \LaTeX{}:
+% \begin{macrocode}
+\def\mpi@mpostmem{}
+\def\mpi@mpostcompiler{}
+\def\mpi@latexclass{article}
+\def\mpi@latexoptions{}
+\def\mpi@documentclass{\@backslashchar documentclass%
+ \mpi@latexoptions{\mpi@latexclass}}
+% \end{macrocode}
+
+% \macro{\mpi@warncompile}
+% Warn and disable compiling if |\write18| is unavailable:
+% \begin{macrocode}
+\def\mpi@warncompile{\ifmpi@compile\ifeof18%
+ \PackageWarning{mpostinl}{write18 disabled, %
+ manual metapost compiling required}{}%
+ \global\mpi@compilefalse\fi\fi}
+% \end{macrocode}
+
+% Process package options:
+% \begin{macrocode}
+\def\mpi@group{mpi@}
+\DeclareOption{final}{\mpi@draftfalse}
+\define@key{\mpi@group}{draft}[true]{\csname mpi@draft#1\endcsname}
+\define@key{\mpi@group}{write}[true]{\csname mpi@write#1\endcsname}
+\define@key{\mpi@group}{latex}[true]{\csname mpi@latex#1\endcsname}
+\define@key{\mpi@group}{compile}[true]{\csname mpi@compile#1\endcsname}
+\define@key{\mpi@group}{twice}[true]{\csname mpi@twice#1\endcsname}
+\define@key{\mpi@group}{clean}[true]{\csname mpi@clean#1\endcsname}
+\define@key{\mpi@group}{checksum}[true]{\csname mpi@checksum#1\endcsname}
+\define@key{\mpi@group}{fonts}[true]{\csname mpi@fonts#1\endcsname}
+\define@key{\mpi@group}{prologues}[]{\def\mpi@prologues{#1}}
+\define@key{\mpi@group}{lineno}[true]{\csname mpi@lineno#1\endcsname}
+\define@key{\mpi@group}{labelnames}[true]{\csname mpi@labelnames#1\endcsname}
+\define@key{\mpi@group}{compiler}[]{\def\mpi@texcompiler{#1}}
+\define@key{\mpi@group}{format}[]{\def\mpi@texformat{#1}}
+\define@key{\mpi@group}{mem}[]{\def\mpi@mpostmem{#1}}
+\define@key{\mpi@group}{command}[]{\def\mpi@mpostcompiler{#1}}
+\define@key{\mpi@group}{class}{\def\mpi@latexclass{#1}}
+\define@key{\mpi@group}{classopt}[]{\def\mpi@latexoptions{[#1]}}
+\define@key{\mpi@group}{beamer}[true]{\csname mpi@beamer#1\endcsname}
+\define@key{\mpi@group}{warnunused}[true]{\csname mpi@warnunused#1\endcsname}
+\define@key{\mpi@group}{now}[true]{\csname mpi@nowactive#1\endcsname}
+\define@key{\mpi@group}{nowall}[true]{\csname mpi@now#1\endcsname}
+\define@key{\mpi@group}{nowkeep}[true]{\csname mpi@nowkeep#1\endcsname}
+\define@key{\mpi@group}{globaldef}[true]{\csname mpi@defglobal#1\endcsname}
+\define@key{\mpi@group}{extension}[]{\def\mpi@extension{#1}}
+\define@key{\mpi@group}{template}{\def\mpi@template##1{#1}}
+\define@key{\mpi@group}{numberwithin}{%
+ \@addtoreset{mpi@count}{#1}%
+ \def\thempi@count{\arabic{#1}-\arabic{mpi@count}}%
+}
+% \end{macrocode}
+
+% Pass undeclared options on to \textsf{keyval} processing:
+% \begin{macrocode}
+\DeclareOption*{\expandafter\setkeys\expandafter\mpi@group%
+ \expandafter{\CurrentOption}}
+% \end{macrocode}
+
+% Process package options,
+% warn if |\write18| mechanism is not available,
+% and disable checksum if |\pdfmdfivesum| is not available:
+% \begin{macrocode}
+\ProcessOptions
+\mpi@warncompile
+\ifdefined\pdfmdfivesum\else\mpi@checksumfalse\fi
+% \end{macrocode}
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Internal Commands and Definitions.}
+%
+% \macro{\mpi@empty}
+% Define an empty macro for comparison via |\ifx|:
+% \begin{macrocode}
+\def\mpi@empty{}
+% \end{macrocode}
+
+% \macro{\mpi@unusedlist}
+% Initialise a list of unused figure labels:
+% \begin{macrocode}
+\def\mpi@unusedlist{}
+% \end{macrocode}
+
+
+% \macro{\mpi@dblquotchar}
+% Define a bare double quotation character for writing to the file:
+% \begin{macrocode}
+\begingroup\catcode`\"=12\relax\gdef\mpi@dblquotchar{"}\endgroup
+% \end{macrocode}
+
+% \macro{\ifmpi@infile}
+% \macro{\ifmpi@inbody}
+% |\ifmpi@infile| indicates whether a file is open,
+% |\ifmpi@inbody| indicates whether the content section has started:
+% \begin{macrocode}
+\newif\ifmpi@infile\mpi@infilefalse
+\newif\ifmpi@inbody\mpi@inbodyfalse
+% \end{macrocode}
+
+% \macro{\ifmpi@inclmod}
+% \macro{\ifmpi@filemod}
+% |\ifmpi@inclmod| indicates whether an include file has been modified,
+% |\ifmpi@filemod| indicates whether the current file is modified:
+% \begin{macrocode}
+\newif\ifmpi@inclmod\mpi@inclmodfalse
+\newif\ifmpi@filemod
+% \end{macrocode}
+
+% \macro{\ifmpi@warnmod}
+% \macro{\ifmpi@showinfile}
+% |\ifmpi@warnmod| indicates whether a rerun warning is to be issued,
+% |\ifmpi@showinfile| indicates whether a figure has been displayed
+% while a file is being composed:
+% \begin{macrocode}
+\newif\ifmpi@warnmod\mpi@warnmodfalse
+\newif\ifmpi@showinfile
+% \end{macrocode}
+
+% \macro{\mpi@out}
+% \macro{\mpi@outnow}
+% File handles for the metapost file (|\mpi@out|)
+% and for immediate output (|\mpi@outnow|):
+% \begin{macrocode}
+\newwrite\mpi@out
+\newwrite\mpi@outnow
+% \end{macrocode}
+
+% \macro{\mpi@writebuf}
+% Write to the file:
+% \begin{macrocode}
+\def\mpi@writebuf{\ifmpi@write\immediate\write\mpi@out{\the\mpi@buf}\fi}
+% \end{macrocode}
+
+% \macro{\mpi@writenow}
+% Write to the immediate buffer:
+% \begin{macrocode}
+\def\mpi@writenow{\ifmpi@nowactive\mpi@addtoexp\mpi@nowbuf{\the\mpi@buf^^J}\fi}
+% \end{macrocode}
+
+% \macro{\mpi@buf}
+% \macro{\mpi@defbuf}
+% \macro{\mpi@nowbuf}
+% Declare three token buffers to store the current block (|\mpi@buf|),
+% global definitions (|\mpi@defbuf|)
+% and the definitions for immediate processing (|\mpi@nowbuf|):
+% \begin{macrocode}
+\newtoks\mpi@buf
+\newtoks\mpi@defbuf
+\newtoks\mpi@nowbuf
+\newtoks\mpi@verbbuf
+\mpi@defbuf={}
+% \end{macrocode}
+
+% \macro{\mpi@addto}
+% \macro{\mpi@addtoexp}
+% |\mpi@addto| adds the second argument to a global token buffer
+% without expansion.
+% |\mpi@addtoexp| first expands the second argument (once)
+% and adds it to the token buffer:
+% \begin{macrocode}
+\def\mpi@addto#1#2{\global#1=\expandafter{\the#1#2}}
+\def\mpi@addtoexp#1#2{\expandafter\mpi@addto\expandafter#1\expandafter{#2}}
+% \end{macrocode}
+
+% \macro{\mpi@clearbuf}
+% \macro{\mpi@addbufexp}
+% \macro{\mpi@addbufbuf}
+% \macro{\mpi@addbuf}
+% |\mpi@clearbuf| clears the current block buffer.
+% |\mpi@addbufexp| expands the first token
+% and adds to the current block buffer.
+% |\mpi@addbufbuf| adds a buffer to the current block buffer.
+% |\mpi@addbuf| adds to the current block buffer via |\protected@edef|:
+% \begin{macrocode}
+\def\mpi@clearbuf{\global\mpi@buf={}}
+\def\mpi@addbufexp#1{\mpi@addtoexp\mpi@buf{#1^^J}}
+\def\mpi@addbufbuf#1{\mpi@addtoexp\mpi@buf{\the#1}}
+\def\mpi@addbuf#1{{\protected@edef\mpi@tmp{#1}\mpi@addbufexp\mpi@tmp}}
+% \end{macrocode}
+
+% \macro{\mpi@stripext}
+% Strip |.mps| or |.eps| ending of a figure filename,
+% return result in |\mpi@stripped|:
+% \begin{macrocode}
+\def\mpi@stripext#1{\edef\mpi@tmp{#1}\expandafter%
+ \mpi@stripstart\expandafter{\mpi@tmp}}
+\def\mpi@ifeq#1#2#3#4{\def\mpi@tmpa{#1}\def\mpi@tmpb{#2}%
+ \ifx\mpi@tmpa\mpi@tmpb#3\else#4\fi}
+\def\mpi@stripstart#1{\mpi@stripfor{\@gobble}#1.\@@.}
+\def\mpi@stripfor#1#2.#3.{%
+ \begingroup%
+ \mpi@ifeq{#3}{\@@}{%
+ \def\mpi@tmp{\def\mpi@stripped{#1.#2}}%
+ \mpi@ifeq{#1}{\@gobble}{}{%
+ \mpi@ifeq{#2}{eps}{\def\mpi@tmp{\def\mpi@stripped{#1}}}{}%
+ \mpi@ifeq{#2}{mps}{\def\mpi@tmp{\def\mpi@stripped{#1}}}{}%
+ \ifx\mpi@extension\mpi@empty\else%
+ \expandafter\mpi@ifeq\expandafter{\mpi@extension}{#2}%
+ {\def\mpi@tmp{\def\mpi@stripped{#1}}}{}%
+ \fi%
+ }%
+ }{\def\mpi@tmp{\mpi@stripfor{#1.#2}#3.}}%
+ \expandafter\endgroup\mpi@tmp%
+}
+% \end{macrocode}
+
+% \macro{\mpi@warnmod}
+% Warn if some figure has been displayed while a file has been written
+% (potentially the displayed figure is old):
+% \begin{macrocode}
+\newcommand{\mpi@warnmod}{%
+ \ifmpi@checksum\ifmpi@warnmod%
+ \PackageWarning{mpostinl}{figure(s) may have changed. %
+ Rerun to update figures}{}%
+ \fi\fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@warnunused}
+% This macro processes the list of all figure labels
+% and issues a warning for every unused ones:
+% \begin{macrocode}
+\def\mpi@warnunused#1{%
+ \begingroup\def\mpi@tmp{#1}\ifx\mpi@tmp\mpi@empty\else%
+ \ifcsname mpi@lu@#1\endcsname\else
+ \PackageWarning{mpostinl}{figure label `#1' not used}{}%
+ \fi%
+ \def\mpi@tmp{\mpi@warnunused}%
+ \fi\expandafter\endgroup\mpi@tmp%
+}
+% \end{macrocode}
+% Run |\mpi@warnunused| at the end of the document:
+% \begin{macrocode}
+\AtEndDocument{\expandafter\mpi@warnunused\mpi@unusedlist{}}
+% \end{macrocode}
+
+% \macro{\mpostdisplaylabel}
+% Rescan a string potentially containing the special characters
+% underscore (`|_|'), caret (`|^|') and ampersand (`|&|'):
+% \begin{macrocode}
+\newcommand{\mpostdisplaylabel}[1]{{%
+ \catcode`\_=11\catcode`\^=11\catcode`\&=11%
+ \edef\mpi@tmp{#1}\expandafter\scantokens\expandafter{\mpi@tmp}}}
+% \end{macrocode}
+
+% \macro{\mpostplaceholder}
+% Display a placeholder for non-existing files or labels;
+% this function may be overwritten by the user for customisation purposes
+% (optional argument contains either `|file|' or `|label|'):
+% \begin{macrocode}
+\newcommand{\mpostplaceholder}[2][]{\parbox[c]{1in}{%
+ \hrule\vrule\hfill%
+ \parbox[c]{0pt}{\rule{0cm}{0.6in}}%
+ \makebox[0pt][c]{\scriptsize\tt\mpostdisplaylabel{#2}}%
+ \hfill\vrule\hrule}}
+% \end{macrocode}
+
+% \macro{\mpi@graphics}
+% Display a figure;
+% if the file does not exist (yet) issue a warning and display a placeholder,
+% otherwise expand filename properly and pass on to |\includegraphics|:
+% \begin{macrocode}
+\newcommand{\mpi@graphics}[2][]{%
+ \IfFileExists{#2}%
+ {\edef\mpi@tmp{#2}\includegraphics[#1]{\mpi@tmp}}%
+ {\typeout{graphics file `#2' missing}\mpostplaceholder[file]{#2}}%
+}
+% \end{macrocode}
+
+% \macro{\mpi@verbatim}
+% Start reading the block from the source file
+% using the \textsf{verbatim} package;
+% add each line to the buffer:
+% \begin{macrocode}
+\newcommand{\mpi@verbatim}{%
+ \begingroup%
+ \@bsphack%
+ \let\do\@makeother\dospecials%
+ \catcode`\^^M\active%
+ \global\mpi@verbbuf={}%
+ \def\verbatim@processline{\mpi@addtoexp\mpi@verbbuf{\the\verbatim@line^^J}}%
+ \verbatim@start%
+}
+% \end{macrocode}
+
+% \macro{\mpi@endverbatim}
+% End reading the block from the source file:
+% \begin{macrocode}
+\newcommand{\mpi@endverbatim}{%
+ \@esphack%
+ \endgroup%
+}
+% \end{macrocode}
+
+% \macro{\mpi@scanblock}
+% Read one optional argument and pass on
+% to an environment which reads a block from the source file.
+% Handle special cases of an initial empty line
+% or a completely empty block.
+% Pass prefetched tokens as second argument:
+% \begin{macrocode}
+\def\mpi@scanblock#1{%
+ \@ifnextchar\par{\mpi@scanblock@par{#1}}{\mpi@scanblock@sel{#1}}}
+\long\def\mpi@scanblock@par#1\par{\mpi@scanblock@sel{#1}[]}
+\def\mpi@scanblock@sel#1{\@ifnextchar[{\mpi@scanblock@opt{#1}}%
+ {\@ifnextchar\end{\mpi@scanblock@end{#1}}{\mpi@scanblock@noopt{#1}}}}
+\def\mpi@scanblock@end#1\end#2{%
+ \def\mpi@tmp{#2}\ifx\mpi@tmp\@currenvir%
+ \def\mpi@verbatim{\global\mpi@verbbuf={}}\def\mpi@endverbatim{}%
+ \fi%
+ #1{}{\scantokens{\end{#2}}}}
+\def\mpi@scanblock@noopt#1#2{#1{}{\scantokens#2}}
+\def\mpi@scanblock@opt#1[#2]{#1{#2}{}}
+% \end{macrocode}
+
+% \macro{\mpi@putlineno}
+% Write current position in source file to buffer;
+% write line number and source file name
+% (if available via package \textsf{currfile}):
+% \begin{macrocode}
+\newcommand{\mpi@putlineno}{%
+ \ifmpi@lineno%
+ \mpi@addbuf{\@percentchar---------------------------------------}%
+ \mpi@addbuf{\@percentchar%
+ \ifx\currfilename\@undefined\else\currfilename\space\fi%
+ l.\the\inputlineno}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@beginfig}
+% Write beginning of figure block to buffer;
+% write filename and |beginfig| statement:
+% \begin{macrocode}
+\newcommand{\mpi@beginfig}[1]{%
+ \mpi@addbuf{filenametemplate \mpi@dblquotchar#1\mpi@dblquotchar;}%
+ \mpi@addbuf{beginfig(\arabic{mpi@count})}%
+}
+% \end{macrocode}
+
+% \macro{\mpi@endfig}
+% Write end of figure block to buffer;
+% write |endfig| statement:
+% \begin{macrocode}
+\newcommand{\mpi@endfig}{%
+ \mpi@addbuf{endfig;}%
+}
+% \end{macrocode}
+
+% \macro{\mpi@declaredoc}
+% Write |\documentclass| statement in \LaTeX{} mode to buffer:
+% \begin{macrocode}
+\newcommand{\mpi@declaredoc}{%
+ \ifmpi@latex%
+ \mpi@addbuf{verbatimtex}%
+ \mpi@addbuf{\mpi@documentclass}%
+ \mpi@addbuf{etex}%
+ \mpi@addbuf{}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@begindoc}
+% Write beginning of content section to buffer;
+% write |\||begin{document}| statement in \LaTeX{} mode:
+% \begin{macrocode}
+\newcommand{\mpi@begindoc}{%
+ \ifmpi@latex%
+ \mpi@putlineno%
+ \mpi@addbuf{verbatimtex}%
+ \mpi@addbuf{\@backslashchar begin{document}}%
+ \mpi@addbuf{etex}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@enddoc}
+% Write end of content section to buffer;
+% write |\||end{document}| statement in \LaTeX{} mode:
+% \begin{macrocode}
+\newcommand{\mpi@enddoc}{%
+ \ifmpi@latex%
+ \mpi@putlineno%
+ \mpi@addbuf{verbatimtex}%
+ \mpi@addbuf{\@backslashchar end{document}}%
+ \mpi@addbuf{etex}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@declareformat}
+% Write \TeX{} format specifier to buffer:
+% \begin{macrocode}
+\newcommand{\mpi@declareformat}{%
+ \let\mpi@tmp\mpi@texformat%
+ \ifx\mpi@tmp\@undefined\def\mpi@tmp{\ifmpi@latex latex\else tex\fi}\fi%
+ \ifx\mpi@tmp\mpi@empty\else%
+ \mpi@addbuf{verbatimtex}%
+ \mpi@addbuf{\@percentchar &\mpi@tmp}%
+ \mpi@addbuf{etex}%
+ \mpi@addbuf{}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@composehead}
+% Write file header to buffer;
+% declare font inclusion and draft mode,
+% write \TeX{} format specifier and \LaTeX{} header:
+% \begin{macrocode}
+\newcommand{\mpi@composehead}{%
+ \mpi@putlineno%
+ \let\mpi@tmp\mpi@prologues%
+ \ifx\mpi@tmp\@undefined\def\mpi@tmp{\ifmpi@fonts 3\else 2\fi}\fi%
+ \ifx\mpi@tmp\mpi@empty\else%
+ \mpi@addbuf{prologues:=\mpi@tmp;}%
+ \fi%
+ \ifmpi@draft\mpi@addbuf{draft:=1;}\fi%
+ \mpi@addbuf{}%
+ \mpi@declareformat%
+ \mpi@declaredoc%
+}
+% \end{macrocode}
+
+% \macro{\mpi@beginfile}
+% Write beginning of file to buffer;
+% write generated file comment and header:
+% \begin{macrocode}
+\newcommand{\mpi@beginfile}{%
+ \ifx\mpi@mpostmem\mpi@empty\else%
+ \mpi@addbuf{\@percentchar &\mpi@mpostmem}%
+ \fi%
+ \mpi@addbuf{\@percentchar generated from file `\jobname' by mpostinl.sty}%
+ \ifmpi@include\else%
+ \mpi@composehead%
+ \mpi@addbufbuf{\mpi@defbuf}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@endfile}
+% Write end of file to buffer;
+% write |end| statement:
+% \begin{macrocode}
+\newcommand{\mpi@endfile}{%
+ \mpi@putlineno%
+ \ifmpi@include\else%
+ \mpi@addbuf{end}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@getchecksum}
+% Compute the MD5 checksum for a metapost file and store in macro:
+% \begin{macrocode}
+\newcommand{\mpi@getchecksum}[3]{%
+ \IfFileExists{#3}{#1\edef#2{\pdfmdfivesum file{#3}}}{#1\let#2=\@undefined}%
+}
+% \end{macrocode}
+
+% \macro{\mpi@startfile}
+% Start a new file if not already open:
+% \begin{macrocode}
+\newcommand{\mpi@startfile}{%
+ \ifmpi@infile\else%
+% \end{macrocode}
+% Prevent reopening and overwriting the previous file:
+% \begin{macrocode}
+ \ifx\mpostfilename\mpi@empty%
+ \PackageError{mpostinl}{no filename provided to write to}{}%
+ \fi%
+% \end{macrocode}
+% Compute checksum of old file:
+% \begin{macrocode}
+ \ifmpi@checksum\ifmpi@inclmod\else%
+ \mpi@getchecksum{\global}{\mpi@checksum@before}{\mpostfilename.mp}%
+ \fi\fi%
+ \ifmpi@checksum\global\mpi@filemodfalse\else\global\mpi@filemodtrue\fi%
+ \ifmpi@inclmod\global\mpi@filemodtrue\fi%
+% \end{macrocode}
+% Open file for writing, prepare and write header to file:
+% \begin{macrocode}
+ \global\mpi@infiletrue%
+ \global\mpi@showinfilefalse%
+ \gdef\mpi@filelist{}%
+ \ifmpi@write\immediate\openout\mpi@out\mpostfilename.mp\fi%
+ \mpi@clearbuf%
+ \mpi@beginfile%
+ \mpi@writebuf%
+% \end{macrocode}
+% For include files, write |input| statement to definition buffer
+% so that the file will be included by all main files:
+% \begin{macrocode}
+ \ifmpi@include%
+ \mpi@clearbuf%
+ \mpi@putlineno%
+ \mpi@addbuf{input \mpostfilename}%
+ \mpi@addtoexp\mpi@defbuf{\the\mpi@buf^^J}%
+% \end{macrocode}
+% If immediate mode is available fill immediate buffer with header:
+% \begin{macrocode}
+ \else%
+ \global\mpi@nowbuf={}%
+ \mpi@writenow%
+ \fi%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@startcontent}
+% Start content section of file;
+% make sure the file is open,
+% prepare start of content section and write to file,
+% if immediate mode is available also add to immediate buffer:
+% \begin{macrocode}
+\newcommand{\mpi@startcontent}{%
+ \mpi@startfile%
+ \ifmpi@inbody\else%
+ \global\mpi@inbodytrue%
+ \mpi@clearbuf%
+ \mpi@begindoc%
+ \mpi@writebuf%
+ \mpi@writenow%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@compile}
+% Compile the metapost file (if writing and compiling is enabled):
+% \begin{macrocode}
+\newcommand{\mpi@compile}[1]{%
+ \ifmpi@write\ifmpi@compile%
+ \ifx\mpi@mpostcompiler\mpi@empty%
+% \end{macrocode}
+% Compose command line for |mpost|;
+% pass on interactionmode setting to \MP{},
+% specify mem filem, specify tex compiler:
+% \begin{macrocode}
+ \def\mpi@imode{}%
+ \ifcase\the\interactionmode%
+ \def\mpi@imode{-interaction=batchmode}\or%
+ \def\mpi@imode{-interaction=nonstopmode}\or%
+ \def\mpi@imode{-interaction=scrollmode}\or%
+ \def\mpi@imode{-interaction=errorstopmode}\fi%
+ \let\mpi@texswitch\mpi@texcompiler%
+ \ifx\mpi@texswitch\@undefined%
+ \def\mpi@texswitch{\ifmpi@latex latex\else tex\fi}%
+ \fi%
+ \def\mpi@execute{mpost\space%
+ \mpi@imode\space%
+ \ifx\mpi@mpostmem\mpi@empty\else -mem=\mpi@mpostmem\space\fi%
+ \ifx\mpi@texswitch\mpi@empty\else -tex=\mpi@texswitch\space\fi%
+ #1}%
+ \else%
+% \end{macrocode}
+% Compose custom command:
+% \begin{macrocode}
+ \def\mpi@execute{\mpi@mpostcompiler\space#1}%
+ \fi%
+% \end{macrocode}
+% Execute \MP{} by |\write18| command; do it again if needed:
+% \begin{macrocode}
+ \immediate\write18{\mpi@execute}%
+ \ifmpi@twice%
+ \immediate\write18{\mpi@execute}%
+ \fi%
+ \fi\fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@cleanfile}
+% Write a mps file containing a plain cross:
+% \begin{macrocode}
+\newcommand{\mpi@cleanfile}[1]{%
+ \immediate\openout\mpi@outnow#1%
+ \immediate\write\mpi@outnow{%
+ \@percentchar!PS-Adobe-3.0 EPSF-3.0^^J%
+ \@percentchar\@percentchar Title: missing figure file^^J%
+ \@percentchar\@percentchar Creator: mpostinl.sty^^J%
+ \@percentchar\@percentchar BoundingBox: -36 -22 36 22^^J%
+ \@percentchar\@percentchar EndComments^^J%
+ \@percentchar\@percentchar Page: 1 1^^J%
+ 0 setgray 0 1.5 dtransform truncate idtransform setlinewidth pop^^J%
+ [] 0 setdash 1 setlinecap 1 setlinejoin 10 setmiterlimit^^J%
+ newpath -35 21 moveto 35 -21 lineto stroke^^J%
+ newpath -35 -21 moveto 35 21 lineto stroke^^J%
+ \@percentchar\@percentchar EOF}%
+ \immediate\closeout\mpi@outnow%
+}
+% \end{macrocode}
+
+% \macro{\mpi@cleanfiles}
+% Clean all figure files prior to compilation:
+% \begin{macrocode}
+\newcommand{\mpi@cleanfiles}[1]{%
+ \begingroup\def\mpi@tmp{#1}%
+ \ifx\mpi@tmp\mpi@empty\else\def\mpi@tmp{\mpi@cleanfiles}%
+ \mpi@cleanfile{#1}\fi%
+ \expandafter\endgroup\mpi@tmp%
+}
+% \end{macrocode}
+
+% \macro{\mpi@closefile}
+% Close the file, compile and reset:
+% \begin{macrocode}
+\newcommand{\mpi@closefile}{%
+ \ifmpi@infile%
+% \end{macrocode}
+% Write end of content section (if started):
+% \begin{macrocode}
+ \mpi@clearbuf%
+ \ifmpi@inbody%
+ \mpi@enddoc%
+ \mpi@addbuf{}%
+ \fi%
+% \end{macrocode}
+% Write end of file and close:
+% \begin{macrocode}
+ \mpi@endfile%
+ \mpi@writebuf%
+ \ifmpi@write\immediate\closeout\mpi@out\fi%
+% \end{macrocode}
+% Determine whether file has changed:
+% \begin{macrocode}
+ \ifmpi@filemod\else%
+ \mpi@getchecksum{}{\mpi@checksum@after}{\mpostfilename.mp}%
+ \ifx\mpi@checksum@before\mpi@checksum@after\else\mpi@filemodtrue\fi%
+ \fi%
+ \ifmpi@include\ifmpi@filemod\global\mpi@inclmodtrue\fi\fi%
+% \end{macrocode}
+% Compile if file has changed and if it contains figures.
+% Activate warning if file has changed and figures were displayed
+% during composition:
+% \begin{macrocode}
+ \ifmpi@filemod\ifmpi@inbody%
+ \ifmpi@clean\ifmpi@write\ifmpi@compile%
+ \expandafter\mpi@cleanfiles\mpi@filelist{}\fi\fi\fi%
+ \mpi@compile{\mpostfilename.mp}%
+ \fi\fi%
+ \ifmpi@filemod\ifmpi@showinfile\global\mpi@warnmodtrue\fi\fi%
+% \end{macrocode}
+% Reset variables:
+% \begin{macrocode}
+ \global\mpi@infilefalse%
+ \global\let\mpostfilename\mpi@empty%
+ \global\mpi@inbodyfalse%
+ \setcounter{mpi@count}{0}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpi@processnow}
+% Write present figure to an individual file and process immediately:
+% \begin{macrocode}
+\newcommand{\mpi@processnow}{%
+ \ifmpi@nowactive\ifmpi@write\ifmpi@compile%
+% \end{macrocode}
+% If immediate file is to be kept,
+% use \textit{filename}|.mp| as source
+% for \textit{filename}|.mps| output file.
+% \begin{macrocode}
+ \ifmpi@nowkeep%
+ \mpi@stripext{\mpi@figfile}%
+ \edef\mpi@nowname{\mpi@stripped}%
+ \fi%
+% \end{macrocode}
+% Open immediate file, write the immediate buffer,
+% the present figure and the end of file, close the file and compile:
+% \begin{macrocode}
+ \immediate\openout\mpi@outnow\mpi@nowname.mp%
+ \immediate\write\mpi@outnow{\the\mpi@nowbuf}%
+ \immediate\write\mpi@outnow{\the\mpi@buf}%
+ \mpi@clearbuf%
+ \mpi@enddoc%
+ \mpi@addbuf{}%
+ \mpi@endfile%
+ \immediate\write\mpi@outnow{\the\mpi@buf}%
+ \immediate\closeout\mpi@outnow%
+ \ifmpi@clean\mpi@cleanfile{\mpi@figfile}\fi%
+ \mpi@compile{\mpi@nowname.mp}%
+ \fi\fi\fi%
+}
+% \end{macrocode}
+
+% Make sure to close and process the file at the end.
+% Warn if figures may need another compiler pass:
+% \begin{macrocode}
+\AtEndDocument{\mpi@closefile}
+\AtEndDocument{\mpi@warnmod}
+% \end{macrocode}
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{External Commands.}
+%
+% The following commands are the interface of the package.
+%
+% \macro{\mpostsetup}
+% |\mpostsetup| processes package options
+% when the package has already been loaded:
+% \begin{macrocode}
+\newcommand{\mpostsetup}[1]{%
+ \setkeys\mpi@group{#1}%
+ \mpi@warncompile%
+ \ifdefined\pdfmdfivesum\else\mpi@checksumfalse\fi%
+}
+% \end{macrocode}
+
+% \macro{mpostdef}
+% Declare options for the |mpostdef| environment:
+% \begin{macrocode}
+\newif\ifmpi@deftex
+\define@key{mpi@def}{tex}[true]{\csname mpi@deftex#1\endcsname}
+\define@key{mpi@def}{global}[true]{\csname mpi@defglobal#1\endcsname}
+% \end{macrocode}
+
+% The environment |mpostdef| adds a block
+% of definitions to the metapost file.
+% Pass on to |\mpi@scanblock| mechanism:
+% \begin{macrocode}
+\def\mpostdef{\mpi@scanblock{\mpi@mpostdef}}
+\def\mpi@mpostdef#1#2{%
+% \end{macrocode}
+% Process optional arguments:
+% \begin{macrocode}
+ \mpi@deftexfalse%
+ \setkeys{mpi@def}{#1}%
+% \end{macrocode}
+% \TeX{} definitions cannot be in an include file:
+% \begin{macrocode}
+ \ifmpi@defglobal\else\ifmpi@deftex\ifmpi@include%
+ \PackageWarning{mpostinl}{tex definitions within an include file %
+ will be ignored by mpost; switching to global definition}{}%
+ \mpi@defglobaltrue%
+ \fi\fi\fi%
+% \end{macrocode}
+% Prepare for recording; start the file if not open and not global,
+% clear buffer, write current position,
+% and add `|verbatimtex|' if in \TeX{} mode:
+% \begin{macrocode}
+ \ifmpi@defglobal\else%
+ \mpi@startfile%
+ \fi%
+ \mpi@clearbuf%
+ \mpi@putlineno%
+ \ifmpi@deftex%
+ \mpi@addbuf{verbatimtex}%
+ \fi%
+ \mpi@verbatim#2%
+}
+% \end{macrocode}
+% Postprocessing; add `|etex|' if in \TeX{} mode,
+% add to appropriate buffer(s).
+% \begin{macrocode}
+\def\endmpostdef
+{%
+ \mpi@endverbatim%
+ \mpi@addbufbuf{\mpi@verbbuf}%
+ \ifmpi@deftex%
+ \mpi@addbuf{etex}%
+ \fi%
+ \ifmpi@defglobal%
+ \mpi@addtoexp\mpi@defbuf{\the\mpi@buf^^J}%
+ \ifmpi@include\else\ifmpi@infile%
+ \mpi@writebuf%
+ \mpi@writenow%
+ \fi\fi%
+ \else%
+ \mpi@writebuf%
+ \ifmpi@include\else\mpi@writenow\fi%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{mposttex}
+% Declare options for the |mposttex| environment:
+% \begin{macrocode}
+\newif\ifmpi@deftex
+\define@key{mpi@tex}{dual}[true]{\csname mpi@texdual#1\endcsname}
+\define@key{mpi@tex}{global}[true]{\csname mpi@defglobal#1\endcsname}
+% \end{macrocode}
+
+% The environment |mposttex| adds a block
+% of tex definitions to the metapost file.
+% Pass on to |\mpi@scanblock| mechanism:
+% \begin{macrocode}
+\def\mposttex{\mpi@scanblock{\mpi@mposttex}}
+\def\mpi@mposttex#1#2{%
+% \end{macrocode}
+% Process optional arguments:
+% \begin{macrocode}
+ \mpi@texdualfalse%
+ \setkeys{mpi@tex}{#1}%
+% \end{macrocode}
+% \TeX{} definitions cannot be in an include file:
+% \begin{macrocode}
+ \ifmpi@defglobal\else\ifmpi@include%
+ \PackageWarning{mpostinl}{tex definitions within an include file %
+ will be ignored by mpost; switching to global definition}{}%
+ \mpi@defglobaltrue%
+ \fi\fi%
+% \end{macrocode}
+% Prepare for recording; start the file if not open and not global,
+% clear buffer, write current position, and add `|verbatimtex|':
+% \begin{macrocode}
+ \ifmpi@defglobal\else%
+ \mpi@startfile%
+ \fi%
+ \mpi@clearbuf%
+ \mpi@putlineno%
+ \mpi@addbuf{verbatimtex}%
+ \mpi@verbatim#2%
+}
+% \end{macrocode}
+% Postprocessing; add `|etex|',
+% add to appropriate buffer(s).
+% \begin{macrocode}
+\def\endmposttex
+{%
+ \mpi@endverbatim%
+ \mpi@addbufbuf{\mpi@verbbuf}%
+ \mpi@addbuf{etex}%
+ \ifmpi@defglobal%
+ \mpi@addtoexp\mpi@defbuf{\the\mpi@buf^^J}%
+ \ifmpi@include\else\ifmpi@infile%
+ \mpi@writebuf%
+ \mpi@writenow%
+ \fi\fi%
+ \else%
+ \mpi@writebuf%
+ \ifmpi@include\else\mpi@writenow\fi%
+ \fi%
+% \end{macrocode}
+% Hack |\ignorespacesafterend| mechanism to
+% ship out block contents after environment group:
+% \begin{macrocode}
+ \ifmpi@texdual%
+ \ignorespacesafterend%
+ \global\let\mpi@ignorespaces\ignorespaces%
+ \gdef\ignorespaces{\expandafter\scantokens\expandafter{\the\mpi@verbbuf}%
+ \global\let\ignorespaces\mpi@ignorespaces}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{mpostfig}
+% Declare options for the |mpostfig| environment:
+% \begin{macrocode}
+\newif\ifmpi@figshow
+\define@key{mpi@fig}{show}[true]{\csname mpi@figshow#1\endcsname}
+\define@key{mpi@fig}{twice}[true]{\csname mpi@twice#1\endcsname}
+\define@key{mpi@fig}{file}{\def\mpi@figfile{#1}}
+\define@key{mpi@fig}{label}{\def\mpi@figlabel{#1}}
+\define@key{mpi@fig}{opt}{\def\mpi@figopt{[#1]}}
+\define@key{mpi@fig}{now}[true]{\csname mpi@now#1\endcsname}
+% \end{macrocode}
+
+% The environment |mpostfig| adds a figure to the metapost file.
+% Pass on to |\mpi@scanblock| mechanism:
+% \begin{macrocode}
+\def\mpostfig{\mpi@scanblock{\mpi@mpostfig}}
+\def\mpi@mpostfig#1#2{%
+% \end{macrocode}
+% Make sure that include files do not contain figures:
+% \begin{macrocode}
+ \ifmpi@include%
+ \PackageError{mpostinl}{cannot write figure to include file}{}%
+ \fi%
+% \end{macrocode}
+% Process optional arguments:
+% \begin{macrocode}
+ \def\mpi@figfile{}%
+ \def\mpi@figlabel{}%
+ \def\mpi@figopt{}%
+ \mpi@figshowfalse%
+ \setkeys{mpi@fig}{#1}%
+% \end{macrocode}
+% Display figure if no filename or label is provided:
+% \begin{macrocode}
+ \ifx\mpi@figlabel\mpi@empty\ifx\mpi@figfile\mpi@empty\mpi@figshowtrue\fi\fi%
+% \end{macrocode}
+% Compose filename from label (if desired and specified):
+% \begin{macrocode}
+ \ifmpi@labelnames\ifx\mpi@figfile\mpi@empty\ifx\mpi@figlabel\mpi@empty\else%
+ \edef\mpi@figfile{\mpi@template{\mpi@figlabel}}%
+ \fi\fi\fi%
+% \end{macrocode}
+% Compose filename from counter if no filename is provided:
+% \begin{macrocode}
+ \ifx\mpi@figfile\mpi@empty%
+ \addtocounter{mpi@count}{1}%
+ \edef\mpi@figfile{\mpi@template{\thempi@count}}%
+ \fi%
+% \end{macrocode}
+% Save filename to label, warn if label has already been defined,
+% remember all labels for checking whether unused:
+% \begin{macrocode}
+ \ifx\mpi@figlabel\mpi@empty\else%
+ \expandafter\ifx\csname mpi@l@\mpi@figlabel\endcsname\relax\else%
+ \PackageWarning{mpostinl}{label `\mpi@figlabel' already defined; %
+ overwriting}{}%
+ \fi%
+ \expandafter\xdef\csname mpi@l@\mpi@figlabel\endcsname{\mpi@figfile}%
+ \ifmpi@warnunused\ifmpi@figshow\else%
+ \xdef\mpi@unusedlist{\mpi@unusedlist{\mpi@figlabel}}%
+ \fi\fi%
+ \fi%
+% \end{macrocode}
+% Prepare for recording; start file and content section (if needed),
+% clear buffer, write current position, begin figure block:
+% \begin{macrocode}
+ \mpi@startcontent%
+ \mpi@clearbuf%
+ \mpi@putlineno%
+ \mpi@beginfig{\mpi@figfile}%
+ \mpi@verbatim#2%
+}
+% \end{macrocode}
+% Postprocessing; end figure block, add to buffer, add file to list,
+% process immediately if desired:
+% \begin{macrocode}
+\def\endmpostfig
+{%
+ \mpi@endverbatim%
+ \mpi@addbufbuf{\mpi@verbbuf}%
+ \mpi@endfig%
+ \mpi@writebuf%
+ \xdef\mpi@filelist{\mpi@filelist{\mpi@figfile}}%
+ \ifmpi@now%
+ \mpi@processnow%
+ \fi%
+% \end{macrocode}
+% Force compile if output file does not exist, is empty or equals dummy figure:
+% \begin{macrocode}
+ \ifmpi@filemod\else%
+ \mpi@getchecksum{}{\mpi@tmpa}{\mpi@figfile}%
+ \ifdefined\mpi@tmpa%
+ \edef\mpi@tmpa{\scantokens\expandafter{\mpi@tmpa\noexpand}}%
+ \def\mpi@tmpb{965DFFE32ABB43CC14C58E254B4D660E}%
+ \ifx\mpi@tmpa\mpi@tmpb\global\mpi@filemodtrue\fi%
+ \def\mpi@tmpb{D78A5F2EE4B244260ECD6A0E89ADC9CE}%
+ \ifx\mpi@tmpa\mpi@tmpb\global\mpi@filemodtrue\fi%
+ \def\mpi@tmpb{D41D8CD98F00B204E9800998ECF8427E}%
+ \ifx\mpi@tmpa\mpi@tmpb\global\mpi@filemodtrue\fi%
+ \else%
+ \global\mpi@filemodtrue%
+ \fi
+ \fi%
+% \end{macrocode}
+% Display figure.
+% Remember immediate display of figure unless processed immediately:
+% \begin{macrocode}
+ \ifmpi@figshow%
+ \expandafter\mpi@graphics\mpi@figopt{\mpi@figfile}%
+ \ifmpi@now\else\global\mpi@showinfiletrue\fi%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpostuse}
+% |\mpostuse| includes a metapost figure which was declared earlier
+% via its label. The optional argument is passed as the optional
+% argument for |\includegraphics|.
+% Remember that the label has been used,
+% remember if a file is currently open for writing:
+% \begin{macrocode}
+\newcommand{\mpostuse}[2][]{%
+ \expandafter\ifx\csname mpi@l@#2\endcsname\relax%
+ \PackageWarning{mpostinl}{unknown label `#2'}{}%
+ \mpostplaceholder[label]{#2}%
+ \else%
+ \ifmpi@warnunused\expandafter\gdef\csname mpi@lu@#2\endcsname{}\fi%
+ \mpi@graphics[#1]{\csname mpi@l@#2\endcsname}%
+ \ifmpi@infile\global\mpi@showinfiletrue\fi%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpostgetname}
+% |\mpostgetname| gets the filename of a figure declared earlier
+% via its label and returns it in the macro |\mpostfigurename|.
+% Remember that the label has been used:
+% \begin{macrocode}
+\newcommand{\mpostgetname}[1]{%
+ \expandafter\ifx\csname mpi@l@#1\endcsname\relax%
+ \PackageWarning{mpostinl}{unknown label `#1'}{}%
+ \let\mpostfigurename\relax%
+ \else%
+ \ifmpi@warnunused\expandafter\gdef\csname mpi@lu@#1\endcsname{}\fi%
+ \edef\mpostfigurename{\csname mpi@l@#1\endcsname}%
+ \fi%
+}
+% \end{macrocode}
+
+% \macro{\mpostfile}
+% Declare options for |\mpostfile|:
+% \begin{macrocode}
+\define@key{mpi@file}{include}[true]{\csname mpi@include#1\endcsname}
+% \end{macrocode}
+
+% |\mpostfile| sets up a new metapost file.
+% If the previous file is still open,
+% it will be closed and processed first:
+% \begin{macrocode}
+\newcommand{\mpostfile}[2][]{%
+ \mpi@closefile%
+ \mpi@includefalse%
+ \setkeys{mpi@file}{#1}%
+ \xdef\mpostfilename{#2}%
+}
+% \end{macrocode}
+
+% \macro{\mpostdone}
+% |\mpostdone| closes the present metapost file
+% and processes it if applicable:
+% \begin{macrocode}
+\newcommand{\mpostdone}{\mpi@closefile}
+% \end{macrocode}
+
+% \macro{\mpostuse<>}
+% This overwrites the definition of |\mpostfile|
+% to accept the overlay option |<|\ldots|>|
+% of the \textsf{beamer} package:
+% \begin{macrocode}
+\ifmpi@beamer\@ifclassloaded{beamer}{
+ \let\mpi@plain@mpostuse\mpostuse%
+ \newcommand<>{\mpostuse}[2][]{\begingroup%
+ \expandafter\def\expandafter\includegraphics\expandafter%
+ {\includegraphics#3}%
+ \mpi@plain@mpostuse[#1]{#2}\endgroup}%
+}{}\fi
+% \end{macrocode}
+
+%\iffalse
+%</package>
+%\fi
+%
+\endinput
diff --git a/macros/latex/contrib/mpostinl/mpostinl.ins b/macros/latex/contrib/mpostinl/mpostinl.ins
new file mode 100644
index 0000000000..bc2c8fa117
--- /dev/null
+++ b/macros/latex/contrib/mpostinl/mpostinl.ins
@@ -0,0 +1,39 @@
+\def\batchfile{mpostinl.ins}
+\input docstrip.tex
+
+\keepsilent
+% mpostinl.ins Copyright (C) 2010-2018 Niklas Beisert
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% 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.
+
+\preamble
+
+Copyright (C) 2010-2018 Niklas Beisert
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+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.
+
+\endpreamble
+
+% the style and sample files
+\generate{\askforoverwritefalse
+\file{mpostinl.sty}{\from{mpostinl.dtx}{package}}
+\file{mpinlsmp.tex}{\from{mpostinl.dtx}{sample}}
+}
+
+\Msg{***********************************************************************}
+\Msg{* Done. Please copy the file mpostinl.sty to an appropriate directory *}
+\Msg{* of your LaTeX distribution, e.g. texmf-root/tex/latex/mpostinl. *}
+\Msg{***********************************************************************}
+\endinput
diff --git a/macros/latex/contrib/mpostinl/mpostinl.pdf b/macros/latex/contrib/mpostinl/mpostinl.pdf
new file mode 100644
index 0000000000..39ba6f9a30
--- /dev/null
+++ b/macros/latex/contrib/mpostinl/mpostinl.pdf
Binary files differ