diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/mpostinl |
Initial commit
Diffstat (limited to 'macros/latex/contrib/mpostinl')
-rw-r--r-- | macros/latex/contrib/mpostinl/README.txt | 39 | ||||
-rw-r--r-- | macros/latex/contrib/mpostinl/mpostinl.dtx | 3037 | ||||
-rw-r--r-- | macros/latex/contrib/mpostinl/mpostinl.ins | 39 | ||||
-rw-r--r-- | macros/latex/contrib/mpostinl/mpostinl.pdf | bin | 0 -> 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 Binary files differnew file mode 100644 index 0000000000..39ba6f9a30 --- /dev/null +++ b/macros/latex/contrib/mpostinl/mpostinl.pdf |