Debian Codegraph @

texmf-dist/source/latex/mpostinl/mpostinl.dtx

raw
1 %
2 % \iffalse meta-comment
3 %
4 % mpostinl.dtx Copyright (C) 2010-2025 Niklas Beisert
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 % https://www.latex-project.org/lppl.txt
11 % and version 1.3c or later is part of all distributions of LaTeX
12 % version 2008 or later.
13 %
14 % This work has the LPPL maintenance status `maintained'.
15 %
16 % The Current Maintainer of this work is Niklas Beisert.
17 %
18 % This work consists of the files mpostinl.dtx and mpostinl.ins
19 % and the derived files mpostinl.sty and mpinlsmp.tex.
20 %
21 %<package|sample>\NeedsTeXFormat{LaTeX2e}[1996/12/01]
22 %<package>\ProvidesPackage{mpostinl}[2025/12/27 v1.5.3 metapost inline figures]
23 %<sample>\ProvidesFile{mpinlsmp.tex}[2025/12/27 v1.5.3 sample for mpostinl]
24 %<source>\ProvidesFile{mpostinl-src.tex}[2025/12/27 v1.5.3 mpostinl source code documentation]
25 %<manual>\ProvidesFile{mpostinl.tex}[2025/12/27 v1.5.3 mpostinl reference manual]
26 %<*main|manual|source>
27 \def\thedate/{2025/12/27}\def\theversion/{v1.5.3}
28 \def\thecopyright/{2010\texorpdfstring{--}{-}2025 Niklas Beisert}
29 %<*main>
30 \ProvidesFile{mpostinl.dtx}[\thedate/ \theversion/ mpostinl reference manual file]
31 %</main>
32 \PassOptionsToClass{10pt,a4paper}{article}
33 \documentclass{ltxdoc}
34
35 \usepackage[margin=35mm]{geometry}
36 \usepackage[hyperindex=false]{hyperref}
37 \usepackage{hyperxmp}
38 \usepackage[usenames]{color}
39 \usepackage{mflogo}
40 \usepackage[utf8]{inputenc}
41
42 %<*main>
43 \title{The \markpkg{mpostinl} Package}
44 \hypersetup{pdftitle={The mpostinl Package}}
45 \hypersetup{pdfsubject={Main file for the LaTeX2e Package mpostinl}}
46 %</main>
47 %<manual>\title{The \markpkg{mpostinl} Package\\Reference Manual}
48 %<manual>\hypersetup{pdftitle={The mpostinl Package -- Reference Manual}}
49 %<manual>\hypersetup{pdfsubject={Reference Manual for the LaTeX2e Package mpostinl}}
50 %<source>\title{The \markpkg{mpostinl} Package\\Source Code Documentation}
51 %<source>\hypersetup{pdftitle={The mpostinl Package -- Source Code Documentation}}
52 %<source>\hypersetup{pdfsubject={Documented Source for the LaTeX2e Package mpostinl}}
53 \author{Niklas Beisert\\[2ex]
54 Institut f\"ur Theoretische Physik\\
55 Eidgen\"ossische Technische Hochschule Z\"urich\\
56 Wolfgang-Pauli-Strasse 27, 8093 Z\"urich, Switzerland\\[1ex]
57 \href{mailto:[email protected]}
58 {\texttt{[email protected]}}}
59 \hypersetup{pdfauthor={Niklas Beisert}}
60 \date{\thedate/, \theversion/\\[1ex]
61 \url{https://ctan.org/pkg/mpostinl}\\[0.5ex]
62 \url{https://github.com/nbeisert/latex-pkg-nb}}
63
64 \hypersetup{pdflang={en-UK}}
65 \hypersetup{pdfurl={https://ctan.org/pkg/mpostinl}}
66 \hypersetup{pdfcopyright={Copyright \thecopyright/.
67 This work may be distributed and/or modified under the
68 conditions of the LaTeX Project Public License, either version 1.3
69 of this license or (at your option) any later version.}}
70 \hypersetup{pdflicenseurl={https://www.latex-project.org/lppl.txt}}
71 \hypersetup{pdfcontactaddress={ETH Zurich, ITP, HIT K,
72 Wolfgang-Pauli-Strasse 27}}
73 \hypersetup{pdfcontactpostcode={8093}}
74 \hypersetup{pdfcontactcity={Zurich}}
75 \hypersetup{pdfcontactcountry={Switzerland}}
76 \hypersetup{pdfcontactemail={[email protected]}}
77 \hypersetup{pdfcontacturl={https://people.phys.ethz.ch/\xmptilde nbeisert/}}
78
79 \hypersetup{keeppdfinfo=true}
80 \hypersetup{pdfsource={}}
81 \AddToHook{begindocument/before}{\hypersetup{colorlinks=false}}
82 \hypersetup{urlbordercolor={.5 1 1}}
83 \hypersetup{linkbordercolor={1 .7 .7}}
84 \AddToHook{begindocument/before}{\hypersetup{pdfstartview=FitH}}
85
86 \parskip1ex
87 \parindent0pt
88 \edef\itemize{\unexpanded\expandafter{\itemize}\parskip0pt}
89
90 \newcommand{\markpkg}[1]{\textsf{#1}}
91 \newcommand{\secref}[1]{\hyperref[#1]{section \ref*{#1}}}
92 \newcommand{\ctanref}[2]{\href{https://ctan.org/#1}{#2}}
93 \newcommand{\ctanpkg}[1]{\ctanref{pkg/#1}{\markpkg{#1}}}
94
95 \def\textvert{\texttt{\char"7C}}
96
97 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
98 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
99 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
100 \begin{document}
101
102 \maketitle
103
104 \begin{abstract}\noindent
105 \markpkg{mpostinl} is a \LaTeXe{} package
106 which enables the embedding of \MP{} figures
107 within a \LaTeX{} document.
108 The package automatically collects the embedded
109 definitions and figures in a |.mp| file,
110 adds an appropriate \LaTeX{} document structure,
111 and compiles it to |.mps| files.
112 It also allows for various configuration options
113 to manage the generation of files and compilation.
114 \end{abstract}
115
116 \begingroup
117 \parskip0ex
118 \tableofcontents
119 \endgroup
120
121
122 %<*main|manual>
123 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
124 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
125 \section{Introduction}
126
127 \MP{} is a versatile tool
128 to generate vector graphics files
129 from a plain text source for inclusion
130 in \LaTeX{} documents which allows to typeset labels
131 in native \LaTeX{} code and fonts.
132 The \MP{} compiler |mpost| typically compiles a
133 metapost source file (extension |.mp|) to
134 a set of metapost figure files (extension |.mps|)
135 which are encapsulated postscript files (|.eps|)
136 with a somewhat reduced scope.
137 The figure files can be included in a \LaTeX{}
138 document by |\includegraphics|,
139 and modern \TeX{} distributions are typically able to handle
140 the required conversions on the fly.
141
142 While many steps in the compilation process are automated,
143 some management is left to the user:
144 \begin{itemize}
145 \item
146 Link the figures in the metapost source
147 with the \LaTeX{} source by choosing an
148 appropriate figure filename (or numeric identifier).
149 \item
150 When a figure is changed,
151 the metapost source file must be compiled
152 to update the figure files,
153 and afterwards the \LaTeX{} source must be compiled
154 to introduce the changes into the output document.
155 \item
156 Keep any changes aligned between \LaTeX{}
157 and metapost source files.
158 \item
159 Set up a proper \LaTeX{} document structure
160 to compile labels via \LaTeX{}.
161 \item
162 Distribute source and figures as separate files.
163 \end{itemize}
164 %
165 The present \LaTeX{} package \ctanpkg{mpostinl}
166 helps in the management of metapost figures
167 by embedding them into the \LaTeX{} source:
168 %
169 \begin{itemize}
170 \item
171 Figures are displayed at the location of their definition
172 within the \LaTeX{} source
173 to facilitate alignment between text and figures.
174 \item
175 A metapost source file with \LaTeX{} structure
176 for the labels is generated.
177 \item
178 Figure files are compiled automatically
179 from within the \LaTeX{} compiler.
180 \end{itemize}
181 %
182 For example, a simple figure consisting
183 of a circle might be represented as:
184 %
185 \begin{verbatim}
186 \begin{mpostfig}
187 draw fullcircle scaled 1cm;
188 \end{mpostfig}
189 \end{verbatim}
190 %
191 The package also offers several options and customisations
192 to streamline its use in several situations:
193 %
194 \begin{itemize}
195 \item
196 Figures can be assigned labels or filenames for later usage.
197 \item
198 There are several options and mechanisms to
199 minimise the need for multiple compiler passes
200 to generate the desired output.
201 \item
202 The package can handle several metapost files in a row
203 with common definitions or include files.
204 \item
205 The font generation, \LaTeX{} structure
206 and generated filenames can be customised.
207 \end{itemize}
208
209
210 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
211 \subsection{Related CTAN Packages}
212
213 There are at least four other \LaTeX{} packages
214 which offer a similar functionality:
215 %
216 \begin{itemize}
217 \item
218 The package \ctanpkg{emp}
219 provides similar basic functionality to compose a metapost file,
220 but it does not automatically compile it.
221 Analogously to the |picture| environment
222 the size for every figure must be specified explicitly.
223 \item
224 The package \href{http://ci.uofl.edu/tom/software/LaTeX/}{\markpkg{mpfig}}
225 by Tomasz Cholewo (not available on CTAN)
226 provides very basic functionality to compose a metapost file.
227 \item
228 The package \ctanpkg{mpgraphics}
229 provides similar functionality to compose and compile a metapost file.
230 It processes all figures immediately and does not offer labels
231 for recycling figures.
232 \item
233 The package \ctanpkg{gmp}
234 provides similar functionality to compose and compile a metapost file.
235 It processes all figures immediately and allows to inject \LaTeX{}
236 definitions into the metapost code at the price of
237 modifying the metapost syntax slightly.
238 \end{itemize}
239 %
240 The philosophy of the present package is to generate a
241 single metapost file containing all figures
242 as in a traditional metapost setup
243 which can be compiled in one pass.
244 The aim is to provide a metapost setup which works
245 with as little configuration as possible,
246 but which offers several configuration options to
247 customise the management in the desired way.
248 The package offers most of the functionality of the above packages,
249 but (presently) misses out on some more advanced features,
250 see \secref{sec:suggestions}.
251
252
253 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
254 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
255 \section{Usage}
256
257 This manual assumes familiarity
258 with the \MP{} figure description language.
259 The \MP{} manual is a recommended introduction
260 and an excellent reference.
261
262 To use the package \ctanpkg{mpostinl} add the command
263 \begin{center}
264 |\usepackage{mpostinl}|
265 \end{center}
266 to the preamble of your \LaTeX{} document.
267 If not yet present,
268 the package \ctanpkg{graphicx} will be loaded automatically.
269 Metapost figures and definitions are to be specified using
270 the environments |mpostfig| and |mpostdef|, respectively,
271 as described in \secref{sec:figuresdefinitions}.
272
273 The package collects the figure files
274 contained in the \LaTeX{} source,
275 writes them to a metapost file,
276 and compiles them at the end of the \LaTeX{} document.
277 This means that the figures (or their updates)
278 will normally \emph{not} be available
279 in the first \LaTeX{} run and a secondary run is required
280 for the correct output,
281 see \secref{sec:immediate} for strategies
282 to avoid a second pass.
283
284 You should make sure that \LaTeX{} allows
285 calling of external programs.
286 If this feature is not enabled by default,
287 it is achieved by calling |latex|
288 with the command line option |-shell-escape|
289 (or |-shell-restricted| if |mpost|
290 is in the list of permissible commands):
291 \begin{center}
292 |latex -shell-escape |\textit{source}
293 \end{center}
294 In the MiK\TeX{} distribution the appropriate
295 command line option is |-enable-write18|.
296 In a \LaTeX{} front end this option may
297 be configurable in the preferences.
298 If the shell escape is not available,
299 the generated metapost file(s) \textit{filename}
300 (typically the same as the \LaTeX{} source \textit{source})
301 must be compiled manually:
302 \begin{center}
303 |mpost -tex=latex |\textit{filename}
304 \end{center}
305
306 Some extended configuration options and situations are described in
307 the following sections:
308 package options are listed in \secref{sec:packageoptions};
309 some options for writing and compiling are discussed
310 in \secref{sec:compiling};
311 the generation of multiple metapost files
312 is described in \secref{sec:multiplefiles};
313 finally, some issues regarding other \LaTeX{} packages
314 are discussed in \secref{sec:interactions}.
315
316
317 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
318 \subsection{Figures and Definitions}
319 \label{sec:figuresdefinitions}
320
321 \DescribeEnv{mpostfig}
322 The main functionality provided
323 by the package is the |mpostfig| environment:
324 \begin{center}
325 \begin{tabular}{l}
326 |\||begin{mpostfig}[|\textit{opts}|]|\\
327 | |\textit{metapost code}\\
328 |\||end{mpostfig}|
329 \end{tabular}
330 \end{center}
331 %
332 The above block is translated
333 to the following code in the metapost file:
334 %
335 \begin{center}
336 \begin{tabular}{l}
337 |filenametemplate:="|\textit{filename}|";|\\
338 |beginfig(|\textit{number}|)|\\
339 | |\textit{metapost code}\\
340 |endfig;|
341 \end{tabular}
342 \end{center}
343 %
344 The optional argument \textit{opts} of the |mpostfig| environment
345 is a comma-separated list of options:
346 %
347 \begin{itemize}
348 \item |show|[|=true|\textbar|false|]
349 (no value implies |true|, initially set to |false|) --
350 Show the figure in place.
351 If neither |file| nor |label| are specified,
352 this option is forced to |true|.
353
354 \item |file=|\textit{filename} --
355 Filename for the figure.
356
357 \item |label=|\textit{label} --
358 Label for later use by the command |\mpostuse{|\textit{label}|}|.
359
360 \item |opt=|\textit{opt} --
361 Options to be passed on to |\includegraphics[|\textit{opt}|]|.
362
363 \item |now|[|=true|\textbar|false|]
364 (no value implies |true|, overrides global setting |nowall|) --
365 Compile figure immediately. Requires global option |now| to work.
366
367 \item |twice|[|=true|\textbar|false|]
368 (no value implies |true|, overrides global setting |twice|) --
369 Compile this figure twice.
370
371 \end{itemize}
372 %
373 Please note the following restrictions
374 due to the implementation via the package \ctanpkg{verbatim}:
375 %
376 \begin{itemize}
377 \item
378 The closing statement |\||end{mpostfig}| must be on a line on its own.
379 Any amount of leading whitespace is allowed,
380 and trailing characters are ignored.
381
382 \item
383 The opening statement |\||begin{mpostfig}| has to find out
384 whether an optional argument is provided
385 by scanning into the block of metapost content.
386 If none is given, all the code already scanned needs to be
387 (re)interpreted as metapost content.
388 In special circumstances this may cause problems.
389 It should then help to use an empty optional argument:
390 |\||begin{mpostfig}[]|.
391
392 \item
393 Lines starting with a single `|%|'
394 are ignored and do not appear in the metapost file.
395 Double `|%%|'
396 or leading spaces preserve comments in the metapost file.
397
398 \item
399 The environment |mpostfig|
400 cannot be used within macro arguments or particular other environments
401 such as |align|, |gather|, |multline|, |equations| and |\<...\>|
402 of \ctanpkg{amsmath} and \ctanpkg{eqnlines}
403 (in certain situations |equation| and |\[...\]|
404 may be problematic as well).
405 If you want to display a figure in these situations,
406 you should declare the figure with a label and
407 display it via the command |\mpostuse| (see below).
408
409 \end{itemize}
410
411
412 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
413 \DescribeMacro{\mpostuse}
414 Figures which have been previously declared
415 with a label \textit{label}
416 can be recycled any number of times with the command:
417 \begin{center}
418 |\mpostuse[|\textit{opts}|]{|\textit{label}|}|
419 \end{center}
420 The options are passed on to
421 |\includegraphics[|\textit{opt}|]{|\textit{filename}|}|.
422 Note that |\mpostuse| accepts the overlay specification
423 from the \ctanpkg{beamer} package
424 \begin{center}
425 |\mpostuse<|\textit{overlay}|>[|\textit{opts}|]{|\textit{label}|}|
426 \end{center}
427 and passes it on to |\includegraphics|.
428
429 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
430 \DescribeMacro{\mpostgetname}
431 Furthermore, the filename of a figure can be obtained by
432 calling |\mpostgetname{|\textit{label}|}|.
433 The filename is returned in the macro |\mpostfigurename|.
434
435 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
436 \DescribeEnv{mpostdef}
437 Plain metapost code which is not part of a figure
438 (definitions, assignments)
439 can be specified by the |mpostdef| environment:
440 %
441 \begin{center}
442 \begin{tabular}{l}
443 |\||begin{mpostdef}[|\textit{opts}|]|\\
444 | |\textit{code}\\
445 |\||end{mpostdef}|
446 \end{tabular}
447 \end{center}
448 %
449 Note that the same restrictions as for |mpostfig| (see above)
450 apply to |mpostdef|.
451 The optional argument \textit{opts}
452 is a comma-separated list of options:
453 %
454 \begin{itemize}
455 \item |global|[|=true|\textbar|false|]
456 (no value implies |true|, overrides global setting |globaldef|) --
457 In a setup with multiple metapost files, the block \textit{code}
458 is applied to all files, not just the current file.
459
460 \item |tex|[|=true|\textbar|false|]
461 (no value implies |true|, initially set to |false|) --
462 The block \textit{code} represents \TeX{} or \LaTeX{} definitions
463 rather than \MP{} code,
464 which will be enclosed in the metapost file by |verbatimtex| and |etex|.
465 This feature is superseded by the environment |mposttex| described below.
466 The |tex| option is deprecated, and provided for backward compatibility only.
467
468 \end{itemize}
469
470 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
471 \DescribeEnv{mposttex}
472 \TeX{} or \LaTeX{} definitions for use in metapost labels
473 can be specified by the |mposttex| environment:
474 %
475 \begin{center}
476 \begin{tabular}{l}
477 |\||begin{mposttex}[|\textit{opts}|]|\\
478 | |\textit{code}\\
479 |\||end{mposttex}|
480 \end{tabular}
481 \end{center}
482 %
483 The code will be enclosed in the metapost file by |verbatimtex| and |etex|.
484 Note that the same restrictions as for |mpostfig| (see above)
485 apply to |mposttex|.
486 The optional argument \textit{opts}
487 is a comma-separated list of options:
488 %
489 \begin{itemize}
490 \item |global|[|=true|\textbar|false|]
491 (no value implies |true|, overrides global setting |globaldef|) --
492 In a setup with multiple metapost files, the block \textit{code}
493 is applied to all files, not just the current file.
494
495 \item |dual|[|=true|\textbar|false|]
496 (no value implies |true|, initially set to |false|) --
497 The definitions within the block \textit{code}
498 will be available to both metapost figures and subsequent \LaTeX{} code.
499
500 \end{itemize}
501
502
503 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
504 \subsection{Package Options}
505 \label{sec:packageoptions}
506
507 \DescribeMacro{\mpostsetup}
508 Options can be passed to the package by:
509 \begin{center}
510 \begin{tabular}{rl}
511 &|\usepackage[|\textit{opts}|]{mpostinl}|
512 \\
513 or&|\PassOptionsToPackage{|\textit{opts}|}{mpostinl}|
514 \\
515 or&|\mpostsetup{|\textit{opts}|}|
516 \end{tabular}
517 \end{center}
518 %
519 |\PassOptionsToPackage| must be used before |\usepackage|;
520 |\mpostsetup| must be used afterwards (for selected options).
521 \textit{opts} is a comma-separated list of options.
522 Below we provide a complete list of available options
523 while some of the more relevant options are discussed
524 in detail in the following sections:
525 %
526 \begin{itemize}
527 \item |draft|[|=true|\textbar|false|]
528 (no value implies |true|, initially set to |false|) --
529 Enable/disable |draft| mode by declaring |draft:=1|
530 at the top of the metapost file.
531
532 \item |final| --
533 Same as |draft=false|.
534
535 \item |write|[|=true|\textbar|false|]
536 (no value implies |true|, initially set to |true|) --
537 Enable/disable writing to metapost file.
538
539 \item |compile|[|=true|\textbar|false|]
540 (no value implies |true|, initially set to |true|) --
541 Enable/disable automatic compilation of metapost file.
542 Requires shell escapes to work properly.
543
544 \item |twice|[|=true|\textbar|false|]
545 (no value implies |true|, initially set to |false|) --
546 Enable/disable secondary metapost compilation.
547 Some metapost files may require this to produce the intended output.
548
549 \item |clean|[|=true|\textbar|false|]
550 (no value implies |true|, initially set to |true|) --
551 Enable/disable cleaning of figure files prior to compilation.
552 A dummy figure will be shown in case metapost cannot generate a figure.
553
554 \item |checksum|[|=true|\textbar|false|]
555 (no value implies |true|, initially set to |false|) --
556 Enable/disable update detection.
557 Compiles figures only if the metapost code has changed.
558
559 \item |fonts|[|=true|\textbar|false|]
560 (no value implies |true|, initially set to |false|) --
561 Enable/disable embedding of fonts in metapost figures
562 by setting |prologues:=3| thus making them proper
563 encapsulated postscript files.
564 This option may be required if figure files are
565 used outside a \TeX{} environment,
566 e.g.\ if the files are to be viewed or processed by |.eps| tools.
567 Has no effect if |prologues| option is specified.
568
569 \item |prologues=|\textit{value} --
570 Declares |prologues:=|\textit{value} at the top of the metapost file.
571 Set \textit{value} to empty to disable the |prologues| statement.
572
573 \item |lineno|[|=true|\textbar|false|]
574 (no value implies |true|, initially set to |false|) --
575 Enable/disable line number indicators in the metapost file.
576 All blocks in the metapost file will start with the line number
577 where this block can be found in the \LaTeX{} source file.
578 To view the source file name
579 you should load the package \ctanpkg{currfile}.
580
581 \item |labelnames|[|=true|\textbar|false|]
582 (no value implies |true|, initially set to |false|) --
583 Use the figure label instead of a consecutive number
584 to construct the name for figure files.
585 The benefit of this mode is that the label will usually stay fixed
586 while the number may change when adding or removing figures.
587 The drawback is that the \LaTeX{} internal labels will appear as
588 part of the filenames cluttering the directory slightly more.
589 Moreover, one has to make sure that the figure labels
590 are valid filenames in your operating system,
591 i.e.\ use special characters with care,
592 better only use alphanumeric characters,
593 and bear in mind that some operating systems do
594 not distinguish upper- and lowercase letters.
595
596 \item |latex|[|=true|\textbar|false|]
597 (no value implies |true|, initially set to |true|) --
598 Switch between \TeX{} (|false|) and \LaTeX{} (|true|)
599 processing of labels.
600 In \LaTeX{} mode a basic \LaTeX{} document structure is
601 provided by the metapost file.
602
603 \item |compiler=|\textit{compiler} --
604 Set the compiler program for labels to \textit{compiler}
605 (command line option |-tex=|\textit{compiler} for \MP).
606 The default is |tex| (in \TeX{} mode)
607 or |latex| (in \LaTeX{} mode).
608 Set \textit{compiler} to empty to specify no compiler.
609
610 \item |format=|\textit{tag} --
611 Write format tag |%&|%
612 \textit{tag} to specify the compiler program for labels.
613 The default is |tex| (in \TeX{} mode)
614 or |latex| (in \LaTeX{} mode).
615 Set \textit{tag} to empty to write no format tag.
616
617 \item |class=|\textit{class}
618 (initially set to |article|) --
619 Set the document class to be used in \LaTeX{} mode.
620
621 \item |classopt=|\textit{options} --
622 Set the options for the |\documentclass| statement in \LaTeX{} mode,
623 e.g.\ |12pt| or |11pt|.
624 No options are specified initially resulting in the |10pt| font set.
625
626 \item |mem=|\textit{mem} --
627 Set the metapost format file to \textit{mem}.
628
629 \item |command=|\textit{command} --
630 Use \textit{command} to process the generated file(s).
631 By default the \MP{} program |mpost| is invoked
632 to compile the generated metapost files
633 (with appropriate command line options).
634
635 \item |now|[|=true|\textbar|false|]
636 (no value implies |true|, initially set to |false|) --
637 Activate/deactivate immediate mode.
638 In immediate mode, figures can be processed immediately
639 so that a secondary \LaTeX{} pass is not required to
640 display the figure correctly.
641 Note that this option merely enables recording
642 of all the required definitions
643 so that immediate processing will be possible,
644 but it does not activate immediate processing per se.
645
646 \item |nowall|[|=true|\textbar|false|]
647 (no value implies |true|, initially set to |false|) --
648 Enable/disable immediate processing for all figures by default.
649 This option will call the \MP{} compiler for every figure.
650 While convenient, it requires heavier processing.
651
652 \item |nowkeep|[|=true|\textbar|false|]
653 (no value implies |true|, initially set to |false|) --
654 Enable/disable immediate generation
655 of figures by individual metapost files.
656 If this mode is enabled,
657 the filename for immediate processing
658 of the figure \textit{filename}|.mps|
659 will be \textit{filename}|.mp|.
660 Otherwise the metapost code is stored in a temporary file and
661 is overwritten by any subsequent immediate processing.
662
663 \item |globaldef|[|=true|\textbar|false|]
664 (no value implies |true|, initially set to |false|) --
665 Enable/disable the |global| option
666 for the |mpostdef| and |mposttex| environments by default.
667 This option can be used to specify a global block of definitions
668 by enclosing it with appropriate |\mpostsetup| statements.
669
670 \item |template=|\textit{template}
671 (initially set to |\mpostfilename-#1.mps|) --
672 Set the template for figure filenames
673 for which it is not given explicitly.
674 The parameter |#1| carries the number (or label) to be used.
675 Moreover, the macro |\mpostfilename|
676 carries the current metapost file.
677
678 \item |figurepath=|\textit{path}
679 (initially blank) --
680 Set the path for figure files.
681
682 \item |figureprefix=|\textit{prefix}
683 (initially blank) --
684 Set a prefix for figure files.
685
686 \item |extension=|\textit{ext}
687 (initially set to |mps|) --
688 Set the default extension for figure filenames.
689
690 \item |numberwithin=|\textit{counter} --
691 Declares the figure counter
692 to be a child of \textit{counter}.
693 In other words, the figure counter
694 is reset when \textit{counter} is increased,
695 and the figure number will be composed
696 as \textit{counter}|-|\textit{figure}.
697 Using this option with a top-level counter
698 such as |section| or |chapter|
699 stabilises the figure numbering
700 by making changes to the sequence have
701 effects only within the present section or chapter.
702
703 \item |beamer|[|=true|\textbar|false|]
704 (no value implies |true|, initially set to |true|) --
705 Enable/disable processing of overlay parameters |<|\ldots|>|
706 by |\mpostuse| defined by the \ctanpkg{beamer} package.
707
708 \item |warnunused|[|=true|\textbar|false|]
709 (no value implies |true|, initially set to |true|) --
710 Enable/disable warnings for unused figure labels.
711
712 \end{itemize}
713 %
714 Admittedly, some of these options are hardly necessary
715 as they will have little impact on output
716 or performance in ordinary situations.
717 They are provided for completeness,
718 to make the package work in more exotic situations,
719 and/or to satisfy some personal taste regarding
720 how things should be managed.
721
722 \DescribeMacro{\mpostplaceholder}
723 \DescribeMacro{\mpostdisplaylabel}
724 Finally, the package allows to customise the placeholder
725 which is displayed when a figure file is not (yet) present
726 after the first \LaTeX{} pass (or in case of some compile error)
727 or a figure label does not exist.
728 In these situations the following macro is called:
729 \begin{center}
730 |\mpostplaceholder[|\textit{type}|]{|\textit{name}|}|
731 \end{center}
732 \textit{type} is either `|file|' or `|label|'
733 and \textit{name} is the missing filename or label.
734 By default this command displays a 1''$\times$0.6'' box
735 containing the missing filename or label.
736 This behaviour can be customised by overwriting the macro.
737 It makes sense to display the filename or label through
738 |\mpostdisplaylabel| which can handle some special characters
739 such as an underscore.
740
741 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
742 \subsection{Writing and Compiling Options}
743 \label{sec:compiling}
744
745 The following discusses some package options regarding the writing
746 and compiling of metapost files in more detail.
747
748 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
749 \paragraph{Label Typesetting Options.}
750
751 Metapost figure files may or may not include the \MF{} fonts
752 which are used by the figure labels.
753 When the generated metapost figures
754 are only used within a \LaTeX{} document
755 in a standard \TeX{} distribution, it is not necessary to
756 include the required fonts as they are automatically
757 supplied by the \LaTeX{} compiler.
758 This omission reduces the size of the figure files
759 (but apparently it has no impact
760 on the size of the compiled \LaTeX{} document
761 in modern \TeX{} distributions).
762 However, the postscript structure
763 of such figure files is incomplete,
764 and therefore the labels typically appear distorted
765 in external viewing or processing tools.
766 If the figure files are to be viewed,
767 processed or passed on to
768 a publisher, it makes sense to include the required fonts.
769 The latter is achieved by enabling the package option |fonts|.
770 In this context, one can also set the default figure file
771 extension to |eps| by means of the package option |extension|.
772
773 By default, the package provides a \LaTeX{} document structure
774 for processing labels by \LaTeX{}.
775 The default document class is |article| without options.
776 An alternative class and options can be specified
777 by the package options |class| and |classopt|.
778 Further packages or macros should be declared as usual
779 by specifying them in a |mposttex| enviroment.
780 If no \LaTeX{} structure is desired,
781 set the package option |latex| to |false|.
782 If the typesetting requires an advanced compiler
783 beyond |latex| or |tex|, it should be
784 specified by the package option |compiler|.
785
786 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
787 \paragraph{Compiling Options.}
788
789 When the figure files are in a final form
790 it may make sense to disable the cleaning, compiling
791 or even the writing of the metapost file(s)
792 by setting the package options |compile|, |clean|
793 or |write| to |false|.
794 In particular, this may be desirable
795 if the \LaTeX{} source is uploaded to a repository
796 or passed on to a publisher.
797
798 The package can check whether the generated files
799 change with respect to the previous \LaTeX{} pass,
800 and only modified files are compiled thereupon.
801 This check can be enabled by setting the option
802 |checksum| to |true|.
803 Note that under some conditions
804 (in particular, if the previous \LaTeX{} pass
805 produced compile errors),
806 figures may not get compiled even though the source changed.
807 In that case you can trigger compilation
808 by deleting the generated metapost source or figures
809 or by introducing further changes to the metapost code.
810 By default all files are compiled.
811
812 When the metapost file compiles with errors,
813 one can inspect the generated metapost file.
814 To this end it may be helpful to know which
815 part of the \LaTeX{} source file is responsible
816 for which part of the metapost file.
817 The package option |lineno| activates
818 prepending every block in the metapost file
819 by the corresponding location in the \LaTeX{} source.
820 If the \LaTeX{} source is distributed over several files,
821 the source filename can also be provided
822 if the package \ctanpkg{currfile} is loaded.
823
824 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
825 \paragraph{Filename Options.}
826
827 By default the names of figure files take the form
828 %
829 \begin{center}
830 [\textit{path}|/|][\textit{prefix}]%
831 \textit{filename}|-|\textit{specifier}|.|\textit{ext}
832 \end{center}
833 %
834 where \textit{filename} is the name of the metapost file,
835 \textit{specifier} is an integer number which enumerates the figures
836 and \textit{ext} is `|mps|'.
837 There are several options to customise the scheme:
838 %
839 \begin{itemize}
840 \item
841 The figure option |file| allows to explicitly specify
842 the desired filename.
843
844 \item
845 The package option |numberwithin=|\textit{section} can be used to
846 associate the counting with a top-level section counter
847 (such as `|section|' or `|chapter|').
848 Then \textit{specifier} takes the form
849 \textit{section}|-|\textit{number},
850 where \textit{number} is an integer that enumerates the figures
851 within the present \textit{section}.
852
853 \item
854 The package option |labelnames| lets \textit{specifier}
855 be the figure label. This option should be used with care,
856 as the operating system does not necessarily allow
857 or distinguish all characters which are available for \TeX{} macros.
858
859 \item
860 A (subdirectory) path \textit{path} for storing the output figures
861 can be set by the package option |figurepath|.
862
863 \item
864 A prefix \textit{prefix} for output figures
865 can be set by the package option |figureprefix|.
866
867 \item
868 The extension \textit{ext} can be customised
869 by the package option |extension|.
870
871 \item
872 The package option |template|
873 allows to customise the above template.
874 In composing the template,
875 the argument |#1| carries the \textit{specifier}
876 and |\mpostfilename| carries the name
877 of the present metapost file.
878 \end{itemize}
879
880
881 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
882 \subsection{Multiple Files}
883 \label{sec:multiplefiles}
884
885 By default the package \ctanpkg{mpostinl} writes out a single file
886 \textit{source}|.mp| if the \LaTeX{} source is called \textit{source}|.tex|.
887 However, the package can also be configured
888 to write out several metapost files.
889 This feature can be used to declare one metapost file
890 for each top-level section of a large \LaTeX{} document
891 (e.g.\ section or chapter).
892 Alternatively, one could define
893 different metapost files for figures of different kinds
894 (e.g.\ technical drawings, diagrams, graphs, charts).
895 Note that these could well use different
896 sets of metapost macros and variables.
897
898 This feature can make sense
899 if the metapost source or generated figures
900 are to be passed on to someone else (e.g.\ publisher)
901 in order to help clarify the placement of figures.
902 It may also be useful if selected sections
903 of the document are generated
904 individually by means of |\includeonly|,
905 in which case only the relevant metapost file
906 is generated and compiled.
907
908 The contents of each metapost file should be enclosed
909 by |\mpostfile| and |\mpostdone|.
910
911 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
912 \DescribeMacro{\mpostfile}
913 A new metapost file is started by the command:
914 \begin{center}
915 |\mpostfile[|\textit{opts}|]{|\textit{filename}|}|
916 \end{center}
917 %
918 \textit{filename} is the filename without |.mp| extension.
919 \textit{opt} is a comma-separated list of options:
920 the only available option is |include|[|=true|\textbar|false|]
921 (no value implies |true|, initially set to |false|)
922 which declares whether the file is an include file.
923
924 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
925 \DescribeMacro{\mpostdone}
926 The present metapost file is completed by the command
927 |\mpostdone| which also compiles the contained figures.
928 Note that this command is called automatically
929 at the end of the \LaTeX{} document.
930
931 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
932 \paragraph{Global Definitions.}
933
934 Definitions in |mpostdef| and |mposttex| environments apply to the
935 present metapost file only. However, definitions can also be
936 specified for all metapost files
937 by means of the option |global|:
938 \begin{center}
939 |\||begin{mpostdef}[global]|
940 \end{center}
941 These definitions are stored internally and will be written
942 to all subsequent metapost files.
943
944 To declare several consecutive (or all)
945 blocks of definitions as global,
946 one can use the package option |globaldef|.
947 To that end, enclose the blocks by
948 |\mpostsetup{globaldef=true}| and |\mpostsetup{globaldef=false}|.
949
950 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
951 \paragraph{Include Files.}
952
953 Alternatively, global definitions can be saved to an include file.
954 This may make sense if there is a large amount of definitions
955 which should not be written to each and every metapost file.
956 An include file is declared by
957 |\mpostfile[include]{|\textit{filename}|}|
958 and will be used by all subsequent main metapost files.
959 Include files are equivalent to global definitions,
960 but they cannot contain \TeX{} definitions.
961 Moreover they must not contain figures.
962
963 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
964 \subsection{Immediate Processing}
965 \label{sec:immediate}
966
967 By default, the metapost file is compiled
968 at the end of the \LaTeX{} document.
969 Therefore all new figures and any changes to existing figures
970 are not reflected in the compiled \LaTeX{} document
971 after the first pass.
972 A second \LaTeX{} pass is needed to generate the desired output.
973 Moreover, any change to the sequence of figures
974 (figures inserted, deleted or moved)
975 can only be seen after the second pass;
976 the first pass shows the old sequence.
977
978 In the following we present some strategies to minimise or avoid
979 this issue.
980
981 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
982 \paragraph{Collecting Figures at the Top.}
983
984 One option is to declare all figures
985 with labels near the top of the document,
986 and close the metapost file by the command |\mpostdone|.
987 The compiled figures are immediately available afterwards.
988 A side effect is that metapost
989 and \LaTeX{} source is necessarily separated
990 (which may be considered a benefit
991 or a drawback depending on philosophy).
992 Note that in a setup with multiple metapost files,
993 the figures can be defined at the top of each section
994 thereby allowing some association between figures and manuscript.
995
996 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
997 \paragraph{Stable Filenames.}
998
999 A change of figure sequence can have irritating effects
1000 because some figures are displayed
1001 in the wrong place in the first pass.
1002 Even though a second pass resolves this issue,
1003 the first pass may have upset the page composition
1004 so that some labels containing page numbers can be messed up
1005 in the second pass thus requiring a third pass.
1006 There are some methods to reduce this effect:
1007 \begin{itemize}
1008 \item
1009 Provide a filename for each figure by the option |file|.
1010
1011 \item
1012 Automatically align the figure filenames with the labels by
1013 the package option |labelnames|.
1014
1015 \item
1016 Use the package option |numberwithin| with the counter
1017 of the top-level section.
1018 Changes of the figure order will then
1019 be contained within each section.
1020
1021 \item
1022 Use one metapost file for each top-level section.
1023 Changes of the figure order will then
1024 be contained within each metapost file.
1025 \end{itemize}
1026
1027
1028 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1029 \paragraph{Immediate Processing.}
1030
1031 The above strategies are workarounds, but the package also provides
1032 a mechanism to compile individual figures or all figures at once.
1033 The drawback is that one metapost file with all relevant definitions
1034 needs to be generated and compiled for each figure.
1035 This may have some negative impact on performance
1036 for very large documents with excessively many figures,
1037 if many such documents are to be generated in a row,
1038 if the computer is slow or busy otherwise,
1039 or if the laptop battery is low on a long journey
1040 (or eventually if the user is old-fashioned or paranoid).
1041
1042 The mechanism is enabled by the package option |now|.
1043 While composing or editing individual figures,
1044 one can specify the figure option |now|,
1045 and remove it when the figure is final.
1046 Alternatively one can activate immediate processing for all figures
1047 with the package option |nowall| (together with |now|).
1048 Ordinarily, a temporary file is used for the metapost source
1049 for immediate processing.
1050 If the metapost sources for individual figures are needed,
1051 the package option |nowkeep| stores the metapost source
1052 for every generated figure \textit{filename}|.mps|
1053 in the file \textit{filename}|.mp|.
1054 When the figures are in a final state,
1055 all immediate processing can be disabled by turning off the package
1056 option |now|.
1057
1058 Note that changing some variables within the figure blocks
1059 can have undesired effects for immediate processing:
1060 In immediate processing only the present figure is included
1061 in the metapost file,
1062 otherwise the metapost file contains the sequence of all figures.
1063 Therefore, a change or (re)definition of a variable within
1064 a figure block will not be visible to all subsequent figures
1065 in immediate mode!
1066 To avoid such situations:
1067 %
1068 \begin{itemize}
1069 \item
1070 Do not (re)define variables within a figure block.
1071 Use a definition block before the figure instead.
1072 \item
1073 Provide an initial value for all used variables
1074 which could change within other figures.
1075 \item
1076 For internal variables (such as the size |ahlength| of an arrow head)
1077 you can |save| the initial value before
1078 the first redefinition within a figure block.
1079 Alternatively you can prepend the first change to the variable
1080 by |interim|.
1081 Note that you can declare variables as internal
1082 by means of |newinternal|.
1083 \end{itemize}
1084
1085 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1086 \subsection{Interaction with Other Packages}
1087 \label{sec:interactions}
1088
1089 The following lists some potential issues in
1090 the interaction with other \LaTeX{} packages:
1091
1092 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1093 \paragraph{Package \markpkg{inputenc}.}
1094
1095 This package should not interfere with the input encoding
1096 selected via the package \ctanpkg{inputenc}, e.g.\ |utf8| encoding.
1097 Extended characters are passed on
1098 unchanged by the |mpostfig| environment.
1099 If you declare an input encoding for your \LaTeX{} source by:
1100 \begin{center}
1101 |\usepackage[|\textit{enc}|]{inputenc}|
1102 \end{center}
1103 you should select the \emph{same} input encoding for the labels
1104 in the metapost figures by means of:
1105 \begin{center}
1106 \begin{tabular}{l}
1107 |\||begin{mposttex}|\\
1108 |\usepackage[|\textit{enc}|]{inputenc}|\\
1109 |\||end{mposttex}|
1110 \end{tabular}
1111 \end{center}
1112
1113 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1114 \paragraph{Package \markpkg{beamer}.}
1115
1116 The package \ctanpkg{beamer} is a popular package for
1117 preparing slideshow presentations.
1118 In particular, slides can be presented in several steps
1119 by means on an overlay mechanism.
1120 To that end the |frame| environment
1121 saves the enclosed block and processes it in several passes.
1122 Therefore, the environments |mpostfig|, |mpostdef| and |mposttex|
1123 must not be used within the |frame| environment.
1124 Instead, figures should be declared outside the |frame| environment
1125 and can be displayed by |\mpostuse| within the |frame| environment.
1126 Note that |\mpostuse| accepts the overlay parameter |<|\ldots|>|.
1127
1128 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1129 \paragraph{Package \markpkg{graphbox}.}
1130
1131 Figures are eventually displayed by the |\includegraphics| command
1132 which aligns the graphics with the bottom of the current line.
1133 To achieve different alignments or placements takes some efforts.
1134 The package \ctanpkg{graphbox} extends the optional
1135 arguments of |\includegraphics| to customise the alignment conveniently.
1136 Since graphics arguments are passed on directly to |\includegraphics|
1137 the \ctanpkg{graphbox} package can be used without restrictions.
1138 For instance, to align a figure vertically with the centre of the line,
1139 you may use |\||begin{mpostfig}[opt={align}]|
1140 or |\mpostuse[align]{|\textit{label}|}|.
1141
1142 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1143 \paragraph{Package \markpkg{latexmp}.}
1144
1145 The \MP{} package \ctanpkg{latexmp} writes its own \LaTeX{} structure
1146 to the metapost file.
1147 Therefore \ctanpkg{mpostinl} must not write the \LaTeX{} structure,
1148 but still use the |latex| compiler.
1149 Furthermore \ctanpkg{latexmp} needs two \MP{} passes.
1150 The required options are:
1151 \begin{center}
1152 |\mpostsetup{latex=false,format,compiler=latex,twice}|
1153 \end{center}
1154
1155 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1156 \paragraph{Script \markpkg{mplatex}.}
1157
1158 The \MP{} processing script \ctanpkg{mplatex} expects the default metapost
1159 file naming convention (\textit{filename}|.|\textit{nn})
1160 and no |prologues| statement.
1161 Moreover, it provides the \LaTeX{} structure.
1162 The required options are:
1163 %
1164 \begin{center}
1165 \begin{tabular}{l}
1166 |\mpostsetup{latex=false,format,prologues}|\\
1167 |\mpostsetup{template={\mpostfilename.#1}}|\\
1168 |\mpostsetup{command={mplatex |\textit{opt}|}}|
1169 \end{tabular}
1170 \end{center}
1171 %
1172 In \textit{opt} you can specify command line options for |mplatex|,
1173 e.g.\ to include \LaTeX{} packages.
1174 Make sure to enable full access to external programs,
1175 and that |mplatex| is in the path (or specify its location explicitly).
1176 Note that the file naming convention (\textit{filename}|.|\textit{nn})
1177 does not seem to work with pdf\LaTeX{}.
1178
1179 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1180 \paragraph{Packages \markpkg{amsmath}, \markpkg{eqnlines}.}
1181
1182 The packages \ctanpkg{amsmath} and \ctanpkg{eqnlines}
1183 declare several math display environments
1184 (|align|, |gather|, |multline|, |equations|, |\<...\>|;
1185 potentially also |equation| and |\[...\]|)
1186 which scan the contents before typesetting them as mathematical expressions.
1187 The scanning process eliminates line breaks in the source code
1188 and thus breaks the scanning for the end of the metapost code block
1189 which has to be on a separate line.
1190 Furthermore, other aspects of the metapost code may get distorted,
1191 so no attempts are made to recover.
1192 Please declare the metapost figures outside of math display environments
1193 and print then via |\mpostuse|.
1194
1195
1196 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1197 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1198 \section{Information}
1199
1200 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1201 \subsection{Copyright}
1202
1203 Copyright \copyright{} \thecopyright/
1204
1205 This work may be distributed and/or modified under the
1206 conditions of the \LaTeX{} Project Public License, either version 1.3
1207 of this license or (at your option) any later version.
1208 The latest version of this license is in
1209 \url{https://www.latex-project.org/lppl.txt}
1210 and version 1.3c or later is part of all distributions of \LaTeX{}
1211 version 2008 or later.
1212
1213 This work has the LPPL maintenance status `maintained'.
1214
1215 The Current Maintainer of this work is Niklas Beisert.
1216
1217 This work consists of the files |README.txt|, |mpostinl.ins| and |mpostinl.dtx|
1218 as well as the derived files |mpostinl.sty|, |mpinlsmp.tex| and |mpostinl.pdf|.
1219
1220 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1221 \subsection{Files and Installation}
1222
1223 The package consists of the files:
1224 %
1225 \begin{center}
1226 \begin{tabular}{ll}
1227 |README.txt| & readme file \\
1228 |mpostinl.ins| & installation file \\
1229 |mpostinl.dtx| & source file \\
1230 |mpostinl.sty| & package file \\
1231 |mpinlsmp.tex| & sample file \\
1232 |mpostinl.pdf| & manual
1233 \end{tabular}
1234 \end{center}
1235 %
1236 The distribution consists of the files
1237 |README.txt|, |mpostinl.ins| and |mpostinl.dtx|.
1238 %
1239 \begin{itemize}
1240 \item
1241 Run (pdf)\LaTeX{} on |mpostinl.dtx|
1242 to compile the manual |mpostinl.pdf| (this file).
1243 \item
1244 Run \LaTeX{} on |mpostinl.ins| to create the package |mpostinl.sty|
1245 and the sample |mpinlsmp.tex|.
1246 Copy the file |mpostinl.sty| to an appropriate directory of your \LaTeX{}
1247 distribution, e.g.\ \textit{texmf-root}|/tex/latex/mpostinl|.
1248 \end{itemize}
1249
1250 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1251 \subsection{Required Packages and Software}
1252
1253 The package relies on other packages and software:
1254 \begin{itemize}
1255 \item
1256 This package relies on some functionality of the package \ctanpkg{verbatim}
1257 to read verbatim code from the \LaTeX{} source without expansion of macros.
1258 Compatibility with the \ctanpkg{verbatim} package
1259 has been tested with v1.5q (2014/10/28).
1260 \item
1261 This package uses the package \ctanpkg{graphicx}
1262 from the \ctanpkg{graphics} bundle to include graphics files.
1263 Compatibility with the \ctanpkg{graphicx} package
1264 has been tested with v1.0g (2014/10/28).
1265 \item
1266 This package uses the package \ctanpkg{keyval}
1267 from the \ctanpkg{graphics} bundle
1268 to process the options for the package, environments and macros.
1269 Compatibility with the \ctanpkg{keyval} package
1270 has been tested with v1.15 (2014/10/28).
1271 \item
1272 This package uses the package \ctanpkg{shellesc}
1273 to invoke |mpost|.
1274 Compatibility with the \ctanpkg{shellesc} package
1275 has been tested with v1.0d (2023/07/08).
1276 \item
1277 This package uses the command |\currfilename|
1278 provided by the package \ctanpkg{currfile} (if available and loaded)
1279 to indicate the \LaTeX{} source file in the generated metapost file.
1280 Compatibility with the \ctanpkg{currfile} package
1281 has been tested with v0.7c (2015/04/23).
1282 \item
1283 The package assumes a \TeX{} installation with \MP{}
1284 configured appropriately.
1285 Recent \textsf{texlive} and MiK\TeX{} distributions should work well.
1286 Compatibility with the \textsf{texlive} distribution
1287 has been tested with the 2016 issue containing
1288 pdf\TeX{} version 3.14159265-2.6-1.40.17
1289 and \MP{} version 1.9991.
1290 \end{itemize}
1291
1292 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1293 \subsection{Feature Suggestions}
1294 \label{sec:suggestions}
1295
1296 The following is a list of features which may be useful for future
1297 versions of this package:
1298 %
1299 \begin{itemize}
1300 \item
1301 A method to expand \LaTeX{} macros to the metapost code
1302 to match the corresponding feature of package \ctanpkg{gmp}:
1303 One difficulty is that direct insertion of \LaTeX{} macros
1304 requires a substantially different implementation of the
1305 block scanning method
1306 because the method supplied by \ctanpkg{verbatim} does not work.
1307 Furthermore, some escape mechanism is required
1308 either to expand selected \LaTeX{} macros
1309 or to prevent their expansion (within |btex| \ldots\ |etex| blocks).
1310 % encapsulate via | |
1311 % extra env
1312 \item
1313 A simpler approach to the above feature would be to implement a
1314 command or option to prepend some metapost statements
1315 to a given metapost block where \LaTeX{} macros are expanded.
1316 This may work well for passing very few macros to metapost variables.
1317 However, one would have to decide how aggressively
1318 macros are to be expanded.
1319 \item
1320 Option to write all generated files to a subdirectory.
1321 \item
1322 Remove files not needed after processing.
1323 However, this appears to be somewhat in contrast
1324 to the usual \TeX{} philosophy.
1325 %\item
1326 %improve detection of changed figure files?
1327 %allow to declare extra include files for update detection
1328 %clean default to false?
1329 \end{itemize}
1330
1331 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1332 \subsection{Revision History}
1333
1334 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1335 \iffalse
1336 \paragraph{vN.N.N+:} 20YY/MM/NN
1337
1338 \begin{itemize}
1339 \item
1340 \ldots
1341 \end{itemize}
1342 \fi
1343
1344 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1345 \paragraph{v1.5.3:} 2025/12/27
1346
1347 \begin{itemize}
1348 \item
1349 new options |figurepath| and |figureprefix|
1350 to specify output path and prefix for figure files
1351 (thanks to Van Abel for suggestion)
1352 \end{itemize}
1353
1354 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1355 \paragraph{v1.5.2:} 2025/04/26
1356
1357 \begin{itemize}
1358 \item
1359 use package \ctanpkg{shellesc} to invoke |mpost|
1360 for compatibility with Lua\TeX{}
1361 \end{itemize}
1362
1363 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1364 \paragraph{v1.5.1:} 2025/03/25
1365
1366 \begin{itemize}
1367 \item
1368 maintenance and manual update
1369 \end{itemize}
1370
1371 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1372 \paragraph{v1.5:} 2018/12/30
1373
1374 \begin{itemize}
1375 \item
1376 new environment |mposttex| for \TeX{} or \LaTeX{} definitions
1377 to replace option |tex| of |mpostdef|;
1378 can be used in |dual| mode
1379 \item
1380 allow underscore, caret and ampersand in figure labels and filenames
1381 \item
1382 improve handling of optional arguments and special situations
1383 when scanning metapost blocks
1384 \end{itemize}
1385
1386 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1387 \paragraph{v1.4:} 2018/03/01
1388
1389 \begin{itemize}
1390 \item
1391 |\mpostuse| now accepts overlay options |<|\ldots|>|
1392 of the \ctanpkg{beamer} package;
1393 new option |beamer| to control the feature
1394 \item
1395 issue warnings for unused labels;
1396 new option |warnunused| to control the feature
1397 \end{itemize}
1398
1399 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1400 \paragraph{v1.3:} 2018/02/09
1401
1402 \begin{itemize}
1403 \item
1404 new |clean| option to initialise figure files
1405 with dummy figures to show \MP{} compiler errors
1406 \item
1407 |checksum| behaviour improved
1408 \end{itemize}
1409
1410 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1411 \paragraph{v1.21:} 2018/01/17
1412
1413 \begin{itemize}
1414 \item
1415 remark on leading empty lines added
1416 \item
1417 manual rearranged
1418 \end{itemize}
1419
1420 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1421 \paragraph{v1.2:} 2018/01/05
1422
1423 \begin{itemize}
1424 \item
1425 new option |checksum| to compile only modified files
1426 (requires the pdf\TeX{} engine, otherwise disabled)
1427 \item
1428 warn if some figures may not be up to date
1429 \item
1430 bugfix for example if \ctanpkg{graphbox} is not available
1431 \end{itemize}
1432
1433 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1434 \paragraph{v1.12:} 2017/06/24
1435
1436 \begin{itemize}
1437 \item
1438 bugfix for blank |mpostfig| display
1439 due to changes in the basic
1440 \LaTeX{} or \ctanpkg{graphicx} system
1441 \end{itemize}
1442
1443 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1444 \paragraph{v1.11:} 2017/04/01
1445
1446 \begin{itemize}
1447 \item
1448 implementation of |fonts| option repaired
1449 \end{itemize}
1450
1451 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1452 \paragraph{v1.1:} 2017/02/27
1453
1454 \begin{itemize}
1455 \item
1456 improved compatibility with package \ctanpkg{latexmp}
1457 and script \ctanpkg{mplatex}
1458 (thanks to Walter Entenmann for encouragement and testing)
1459 \item
1460 options improved to fine-tune structures written to metapost files
1461 and to specify compiler programs
1462 \end{itemize}
1463
1464 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1465 \paragraph{v1.0:} 2017/01/04
1466
1467 \begin{itemize}
1468 \item
1469 manual and install package
1470 \item
1471 first version published on CTAN
1472 \end{itemize}
1473
1474 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1475 \paragraph{v0.7--0.9:} 2016/11/15 -- 2017/01/04
1476
1477 \begin{itemize}
1478 \item
1479 package options
1480 \item
1481 metapost environments simplified and renamed
1482 \item
1483 immediate and multiple file processing
1484 \item
1485 customisation options
1486 \item
1487 internal buffer processing
1488 \end{itemize}
1489
1490 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1491 \paragraph{v0.6--0.63:} 2015/07/11 -- 2016/10/03
1492
1493 \begin{itemize}
1494 \item
1495 minor improvements
1496 \end{itemize}
1497
1498 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1499 \paragraph{v0.5:} 2010/11/01
1500
1501 \begin{itemize}
1502 \item
1503 basic functionality
1504 \end{itemize}
1505
1506 %</main|manual>
1507 %<*main>
1508 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1509 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1510 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1511
1512 \appendix
1513 %</main>
1514 %<*main|source>
1515 \raggedright
1516 \settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
1517
1518 \DocInput{mpostinl.dtx}
1519 %</main|source>
1520
1521 \end{document}
1522 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1523 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1524 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1525 %</main|manual|source>
1526 % \fi
1527 %
1528 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1529 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1530 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1531 %
1532 %
1533 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1534 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1535 % \section{Sample File}
1536 % \iffalse
1537 %<*sample>
1538 % \fi
1539 %
1540 % In this section we provide a \LaTeX{} example how to use
1541 % some of the \ctanpkg{mpostinl} features.
1542 %
1543 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1544 % \subsection{Preamble}
1545 %
1546 % Standard document class:
1547 % \begin{macrocode}
1548 \documentclass[12pt,a4paper]{article}
1549 % \end{macrocode}
1550
1551 % Adjust the paragraph shape:
1552 % \begin{macrocode}
1553 \parindent0pt
1554 \parskip6pt
1555 % \end{macrocode}
1556
1557 % Include the \ctanpkg{mpostinl} package,
1558 % include \MF{} fonts in the metapost figures:
1559 % \begin{macrocode}
1560 \usepackage[fonts=true]{mpostinl}
1561 % \end{macrocode}
1562
1563 % We will test labels in UTF-8, so include package \ctanpkg{inputenc}:
1564 % \begin{macrocode}
1565 \usepackage[utf8]{inputenc}
1566 % \end{macrocode}
1567
1568 % Include packages \ctanpkg{currfile} and \ctanpkg{graphbox} if available,
1569 % declare dummy option |align| for |\includegraphics|
1570 % if \ctanpkg{graphbox} is not available:
1571 % \begin{macrocode}
1572 %% optional: add filename to position labels in metapost code
1573 \IfFileExists{currfile.sty}{\usepackage{currfile}}{}
1574 %% optional: tools to align graphics
1575 \makeatletter\define@key{Gin}{align}[]{}\makeatother
1576 \IfFileExists{graphbox.sty}{\usepackage{graphbox}}{}
1577 % \end{macrocode}
1578
1579 % Enable immediate mode and line number indicators,
1580 % prepare some \ctanpkg{mpostinl} options for testing:
1581 % \begin{macrocode}
1582 %% some sample package options:
1583 %% \mpostsetup{write=false}
1584 %% \mpostsetup{compile=false}
1585 \mpostsetup{checksum}
1586 \mpostsetup{now}
1587 %% \mpostsetup{nowall}
1588 \mpostsetup{lineno}
1589 %% \mpostsetup{latex=false}
1590 %% \mpostsetup{classopt={12pt}}
1591 % \end{macrocode}
1592
1593 % Include the package \ctanpkg{inputenc}
1594 % for preparing \LaTeX{} labels within the metapost figures;
1595 % as we will be generating several metapost files later on,
1596 % make sure this statement in included in all of them:
1597 % \begin{macrocode}
1598 %% declare packages to be used for processing labels:
1599 \begin{mposttex}[global]
1600 \usepackage[utf8]{inputenc}
1601 \end{mposttex}
1602 % \end{macrocode}
1603
1604 % Define an internal variable |unit| and initialise to 1cm;
1605 % as we will be generating several metapost files later on,
1606 % make sure this statement in included in all of them:
1607 % \begin{macrocode}
1608 %% specify global definitions:
1609 \begin{mpostdef}[global]
1610 newinternal unit;
1611 unit:=1cm;
1612 \end{mpostdef}
1613 % \end{macrocode}
1614
1615 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1616 % Begin document body:
1617 % \begin{macrocode}
1618 \begin{document}
1619 % \end{macrocode}
1620
1621 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1622 % \subsection{Basic Functionality}
1623 %
1624 % We start by demonstrating the basic functionality of the package:
1625 %
1626 % \begin{macrocode}
1627 \section{Basic Functionality}
1628 % \end{macrocode}
1629
1630 % First, draw a circle of diameter 1cm and write a `1' in the centre:
1631 % \begin{macrocode}
1632 a plain circle:\\
1633 \begin{mpostfig}
1634 draw fullcircle scaled unit;
1635 label(btex 1 etex, (0,0));
1636 \end{mpostfig}
1637 % \end{macrocode}
1638
1639 % Use the options for |\includegraphics|.
1640 % Draw another circle containing a `2' and scale it by factor $1.5$.
1641 % Also vertically align to the centre (if \ctanpkg{graphbox} is available):
1642 % \begin{macrocode}
1643 scaled (and aligned to centre if available):\\
1644 X
1645 \begin{mpostfig}[opt={scale=1.5,align}]
1646 draw fullcircle scaled unit;
1647 label(btex 2 etex, (0,0));
1648 \end{mpostfig}
1649 X
1650 % \end{macrocode}
1651
1652 % Declare a figure with label |fig|, do not show:
1653 % \begin{macrocode}
1654 declare figure with label (no display).
1655 \begin{mpostfig}[label={fig}]
1656 draw fullcircle scaled unit;
1657 label(btex 3 etex, (0,0));
1658 \end{mpostfig}
1659 % \end{macrocode}
1660
1661 % Display the figure:
1662 % \begin{macrocode}
1663 display:\\
1664 \mpostuse{fig}
1665 % \end{macrocode}
1666
1667 % Display the figure with options for |\includegraphics|:
1668 % \begin{macrocode}
1669 display with options:\\
1670 \mpostuse[scale=1.5,align]{fig}
1671 % \end{macrocode}
1672
1673 % Display the figure within a box:
1674 % \begin{macrocode}
1675 display in a box:\\
1676 \fbox{\mpostuse{fig}}
1677 % \end{macrocode}
1678
1679 % Display the figure at the centre of a line:
1680 % \begin{macrocode}
1681 centred display:
1682 \begin{center}
1683 \mpostuse[scale=1.5]{fig}
1684 \end{center}
1685 % \end{macrocode}
1686
1687 % Display the figure within an equation:
1688 % \begin{macrocode}
1689 display in equation (align if possible):
1690 \begin{equation}
1691 \mpostuse[scale=1.5,align]{fig}
1692 \end{equation}
1693 % \end{macrocode}
1694
1695 % Show the filename of the figure:
1696 % \begin{macrocode}
1697 filename: \mpostgetname{fig}
1698 \texttt{\mpostfigurename}
1699 % \end{macrocode}
1700
1701 % Declare a figure with filename, label and show it,
1702 % then display filename:
1703 % \begin{macrocode}
1704 figure with filename:\\
1705 \begin{mpostfig}[file={\jobname-name.mps},label={name},show]
1706 draw fullcircle scaled unit;
1707 label(btex 4 etex, (0,0));
1708 \end{mpostfig}
1709 \\
1710 filename: \mpostgetname{name}
1711 \texttt{\mpostfigurename}
1712 % \end{macrocode}
1713
1714 % Display the file via |\includegraphics|.
1715 % As the figure may not exist (in the first pass)
1716 % check for existence first to avoid a compile error:
1717 % \begin{macrocode}
1718 display by \verb+\includegraphics+ (if file exists):\\
1719 \IfFileExists{\jobname-name.mps}{\includegraphics{\jobname-name.mps}}{}
1720 % \end{macrocode}
1721
1722 % Show a figure which does not exist,
1723 % triggers a warning and displays a box:
1724 % \begin{macrocode}
1725 label does not exist:\\
1726 \mpostuse{not_exist}
1727 % \end{macrocode}
1728
1729 % Display a figure with a label containing special characters in UTF-8.
1730 % Note that the internal variable |unit| is changed locally (|interim|)
1731 % so that subsequent figures will see the old value:
1732 % \begin{macrocode}
1733 utf-8 test:\\
1734 \begin{mpostfig}
1735 interim unit:=1.5cm;
1736 draw fullcircle scaled unit;
1737 label(btex àáâãäåæ etex, (0,0));
1738 \end{mpostfig}
1739 % \end{macrocode}
1740
1741 % Write a totally empty figure
1742 % \begin{macrocode}
1743 empty figure:\\
1744 \begin{mpostfig}
1745 \end{mpostfig}
1746 % \end{macrocode}
1747
1748 % Write a figure with an empty line
1749 % \begin{macrocode}
1750 empty figure:\\
1751 \begin{mpostfig}
1752
1753 \end{mpostfig}
1754 % \end{macrocode}
1755
1756 % Make a dual definition
1757 % \begin{macrocode}
1758 \begin{mposttex}[dual]
1759 \def\mymacro{hello!}
1760 \end{mposttex}
1761 % \end{macrocode}
1762 % and test it
1763 % \begin{macrocode}
1764 dual definition `\mymacro':\\
1765 \begin{mpostfig}
1766 draw unitsquare shifted (-0.5,-0.5) xscaled 3 scaled unit;
1767 label(btex \mymacro etex, (0,0));
1768 \end{mpostfig}
1769 % \end{macrocode}
1770
1771 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1772 % \subsection{Immediate Processing}
1773 %
1774 % Next, we demonstrate immediate processing
1775 % (make sure to enable the package option |now|):
1776 %
1777 % \begin{macrocode}
1778 \section{Immediate Processing}
1779 % \end{macrocode}
1780
1781 % Declare a figure for immediate processing.
1782 % You may change the size |unit| and the figure will be
1783 % adjusted after the first \LaTeX{} pass:
1784 % \begin{macrocode}
1785 immediate processing per figure:\\
1786 \begin{mpostfig}[now]
1787 interim unit:=1.5cm;
1788 draw fullcircle scaled unit;
1789 label(btex 5 etex, (0,0));
1790 \end{mpostfig}
1791 % \end{macrocode}
1792
1793 % One can also enable immediate processing for all subsequent figures.
1794 % Furthermore, store the metapost source in individual files:
1795 % \begin{macrocode}
1796 turn on immediate processing for all figures and keep sources.
1797 \mpostsetup{nowall,nowkeep}
1798 % \end{macrocode}
1799
1800 % Now declare a figure with individual metapost source,
1801 % display via |\includegraphics|,
1802 % and confirm that source exists:
1803 % \begin{macrocode}
1804 generate file \texttt{\jobname-now.mps}:
1805 \begin{mpostfig}[file={\jobname-now.mps}]
1806 draw fullcircle scaled unit;
1807 label(btex 6 etex, (0,0));
1808 \end{mpostfig}
1809 \\
1810 display by \verb+\includegraphics+:\\
1811 \includegraphics{\jobname-now.mps}
1812 \\
1813 source \texttt{\jobname-now.mp}
1814 \IfFileExists{\jobname-now.mp}{exists}{does not exist}.
1815 % \end{macrocode}
1816
1817 % Reset immediate processing options for further examples
1818 % (normally not necessary):
1819 % \begin{macrocode}
1820 turn off immediate processing and discard sources.
1821 \mpostsetup{nowall=false,nowkeep=false}
1822 % \end{macrocode}
1823
1824 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1825 % \subsection{Filename Composition}
1826 %
1827 % Now, we demonstrate how to adjust the composition of figure filenames:
1828 %
1829 % \begin{macrocode}
1830 \section{Filename Composition}
1831 % \end{macrocode}
1832
1833 % Use the figure label instead of a figure counter:
1834 % \begin{macrocode}
1835 by label:\\
1836 \mpostsetup{labelnames=true}
1837 \begin{mpostfig}[label={circle},show]
1838 draw fullcircle scaled unit;
1839 label(btex 7 etex, (0,0));
1840 \end{mpostfig}
1841 \mpostsetup{labelnames=false}
1842 \\
1843 filename: \mpostgetname{circle}
1844 \texttt{\mpostfigurename}
1845 % \end{macrocode}
1846
1847 % Change extension to |.eps|:
1848 % \begin{macrocode}
1849 change extension:
1850 \mpostsetup{extension=eps}
1851 \begin{mpostfig}[label={ext}]
1852 draw fullcircle scaled unit;
1853 label(btex 8 etex, (0,0));
1854 \end{mpostfig}
1855 \mpostsetup{extension=mps}
1856 \\
1857 filename: \mpostgetname{ext}
1858 \texttt{\mpostfigurename}
1859 % \end{macrocode}
1860
1861 % Change template altogether:
1862 % \begin{macrocode}
1863 change template:\\
1864 \mpostsetup{template=\mpostfilename-figure-#1.mps}
1865 \begin{mpostfig}[label={template},show]
1866 draw fullcircle scaled unit;
1867 label(btex 9 etex, (0,0));
1868 \end{mpostfig}
1869 \mpostsetup{template=\mpostfilename-#1.mps}
1870 \\
1871 filename: \mpostgetname{template}
1872 \texttt{\mpostfigurename}
1873 % \end{macrocode}
1874
1875 % Demonstrate numbering within a section (here: |subsection|)
1876 % \begin{macrocode}
1877 \mpostsetup{numberwithin=subsection}
1878 % \end{macrocode}
1879
1880 % One figure in the first section:
1881 % \begin{macrocode}
1882 \subsection{Section 1}
1883
1884 \begin{mpostfig}[show,label={sec1}]
1885 draw fullcircle scaled unit;
1886 label(btex 10 etex, (0,0));
1887 \end{mpostfig}
1888 \\
1889 filename: \mpostgetname{sec1}
1890 \texttt{\mpostfigurename}
1891 % \end{macrocode}
1892
1893 % Two figures in the second section:
1894 % \begin{macrocode}
1895 \subsection{Section 2}
1896
1897 \begin{mpostfig}[show,label={sec2}]
1898 draw fullcircle scaled unit;
1899 label(btex 11 etex, (0,0));
1900 \end{mpostfig}
1901 \\
1902 filename: \mpostgetname{sec2}
1903 \texttt{\mpostfigurename}
1904
1905 \begin{mpostfig}[show,label={sec3}]
1906 draw fullcircle scaled unit;
1907 label(btex 12 etex, (0,0));
1908 \end{mpostfig}
1909 \\
1910 filename: \mpostgetname{sec3}
1911 \texttt{\mpostfigurename}
1912 % \end{macrocode}
1913
1914 % One figure in the third section:
1915 % \begin{macrocode}
1916 \subsection{Section 3}
1917
1918 \begin{mpostfig}[show,label={sec4}]
1919 draw fullcircle scaled unit;
1920 label(btex 13 etex, (0,0));
1921 \end{mpostfig}
1922 \\
1923 filename: \mpostgetname{sec4}
1924 \texttt{\mpostfigurename}
1925 % \end{macrocode}
1926
1927 % Reset numbering for further examples
1928 % (normally not necessary, setting cannot be undone completely):
1929 % \begin{macrocode}
1930 \makeatletter
1931 \def\thempi@count{\arabic{mpi@count}}
1932 \makeatother
1933 % \end{macrocode}
1934
1935 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1936 % \subsection{Multiple Files}
1937 %
1938 % Finally, demonstrate the generation and usage of several metapost files:
1939 %
1940 % \begin{macrocode}
1941 \section{Multiple Files}
1942 % \end{macrocode}
1943
1944 % First, close the old metapost file to get to a clean state:
1945 % \begin{macrocode}
1946 \mpostdone
1947 % \end{macrocode}
1948
1949 % Make a definition which will apply to all metapost files.
1950 % |global| option can be activated
1951 % for a block of definitions (here only one):
1952 % \begin{macrocode}
1953 \mpostsetup{globaldef=true}
1954
1955 \begin{mpostdef}
1956 unit:=0.8cm;
1957 \end{mpostdef}
1958
1959 \mpostsetup{globaldef=false}
1960 % \end{macrocode}
1961
1962 % Alternatively, we can define an include file
1963 % to be included by all main metapost files.
1964 % This has the same effect as a global definition,
1965 % but is intended for long definitions:
1966 % \begin{macrocode}
1967 \mpostfile[include]{\jobname-inc}
1968
1969 \begin{mpostdef}
1970 def drawcircle =
1971 draw fullcircle scaled unit
1972 enddef;
1973 \end{mpostdef}
1974
1975 \mpostdone
1976 % \end{macrocode}
1977
1978 % The first file contains one figure:
1979 % \begin{macrocode}
1980 \subsection*{Section 1}
1981 \mpostfile{\jobname-sec1}
1982
1983 \begin{mpostfig}[show,label={sec5}]
1984 drawcircle;
1985 label(btex 14 etex, (0,0));
1986 \end{mpostfig}
1987 \\
1988 filename: \mpostgetname{sec5}
1989 \texttt{\mpostfigurename}
1990
1991 \mpostdone
1992 % \end{macrocode}
1993
1994 % The second file contains a local redefinition of |unit|
1995 % and two figures:
1996 % \begin{macrocode}
1997 \subsection*{Section 2}
1998 \mpostfile{\jobname-sec2}
1999
2000 \begin{mpostfig}[show,label={sec6}]
2001 drawcircle;
2002 label(btex 15 etex, (0,0));
2003 \end{mpostfig}
2004 \\
2005 filename: \mpostgetname{sec6}
2006 \texttt{\mpostfigurename}
2007
2008 \begin{mpostdef}
2009 unit:=1.5cm;
2010 \end{mpostdef}
2011
2012 \begin{mpostfig}[show,label={sec7}]
2013 drawcircle;
2014 label(btex 16 etex, (0,0));
2015 \end{mpostfig}
2016 \\
2017 filename: \mpostgetname{sec7}
2018 \texttt{\mpostfigurename}
2019
2020 \mpostdone
2021 % \end{macrocode}
2022
2023 % The third file contains one figure. Note that the redefinition
2024 % of the second file does not apply here:
2025 % \begin{macrocode}
2026 \subsection*{Section 3}
2027 \mpostfile{\jobname-sec3}
2028
2029 \begin{mpostfig}[show,label={sec8}]
2030 drawcircle;
2031 label(btex 17 etex, (0,0));
2032 \end{mpostfig}
2033 \\
2034 filename: \mpostgetname{sec8}
2035 \texttt{\mpostfigurename}
2036
2037 \mpostdone
2038 % \end{macrocode}
2039
2040 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2041 % End of document body:
2042 % \begin{macrocode}
2043 \end{document}
2044 % \end{macrocode}
2045 % \iffalse
2046 %</sample>
2047 % \fi
2048 %
2049 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2050 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2051 % \section{Implementation}
2052 % \iffalse
2053 %<*package>
2054 % \fi
2055 %
2056 % In this section we describe the package |mpostinl.sty|.
2057
2058 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2059 % \paragraph{Required Packages.}
2060 %
2061 % The package loads the packages
2062 % \ctanpkg{verbatim}, \ctanpkg{graphicx} and \ctanpkg{keyval}
2063 % if not yet present.
2064 % \ctanpkg{verbatim} is used for reading verbatim metapost code.
2065 % \ctanpkg{graphicx} is used for including graphics files.
2066 % \ctanpkg{keyval} is used for extended options processing.
2067 % \begin{macrocode}
2068 \RequirePackage{verbatim}
2069 \RequirePackage{graphicx}
2070 \RequirePackage{keyval}
2071 \RequirePackage{shellesc}
2072 % \end{macrocode}
2073
2074 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2075 % \paragraph{Package Options.}
2076 %
2077 % \macro{\mpostfilename}
2078 % \macro{\mpi@nowname}
2079 % \macro{\mpi@figurepath}
2080 % \macro{\mpi@figureprefix}
2081 % \macro{\mpi@extension}
2082 % \macro{\mpi@template}
2083 % |\mpostfilename| stores the metapost filename,
2084 % |\mpi@nowname| stores the filename for immediate processing,
2085 % and |\mpi@template| is the template to generate the figure filenames:
2086 % \begin{macrocode}
2087 \def\mpostfilename{\jobname}
2088 \def\mpi@nowname{\jobname-tmp}
2089 \def\mpi@dirsep{/}
2090 \def\mpi@figurepath{}
2091 \def\mpi@figureprefix{}
2092 \def\mpi@extension{.mps}
2093 \def\mpi@template#1{\mpi@figurepath\mpi@figureprefix\mpostfilename-#1%
2094 \mpi@extension}
2095 % \end{macrocode}
2096
2097 % \macro{mpi@count}
2098 % Declare a counter for figure filenames:
2099 % \begin{macrocode}
2100 \newcounter{mpi@count}
2101 \def\thempi@count{\arabic{mpi@count}}
2102 % \end{macrocode}
2103
2104 % The package has some boolean \ctanpkg{keyval} options
2105 % which can be set to |true| or |false|.
2106 % \begin{macrocode}
2107 \newif\ifmpi@draft\mpi@draftfalse
2108 \newif\ifmpi@latex\mpi@latextrue
2109 \newif\ifmpi@fonts\mpi@fontsfalse
2110 \newif\ifmpi@write\mpi@writetrue
2111 \newif\ifmpi@compile\mpi@compiletrue
2112 \newif\ifmpi@twice\mpi@twicefalse
2113 \newif\ifmpi@clean\mpi@cleantrue
2114 \newif\ifmpi@checksum\mpi@checksumfalse
2115 \newif\ifmpi@lineno\mpi@linenofalse
2116 \newif\ifmpi@labelnames\mpi@labelnamesfalse
2117 \newif\ifmpi@nowactive\mpi@nowactivefalse
2118 \newif\ifmpi@now\mpi@nowfalse
2119 \newif\ifmpi@nowkeep\mpi@nowkeepfalse
2120 \newif\ifmpi@include\mpi@includefalse
2121 \newif\ifmpi@defglobal\mpi@defglobalfalse
2122 \newif\ifmpi@texdual\mpi@texdualfalse
2123 \newif\ifmpi@warnunused\mpi@warnunusedtrue
2124 \newif\ifmpi@beamer\mpi@beamertrue
2125 % \end{macrocode}
2126
2127 % \macro{\mpi@mpostmem}
2128 % \macro{\mpi@mpostcompiler}
2129 % \macro{\mpi@latexclass}
2130 % \macro{\mpi@latexoptions}
2131 % \macro{\mpi@documentclass}
2132 % These definitions store the options for processing labels via
2133 % \TeX{} or \LaTeX{}:
2134 % \begin{macrocode}
2135 \def\mpi@mpostmem{}
2136 \def\mpi@mpostcompiler{}
2137 \def\mpi@latexclass{article}
2138 \def\mpi@latexoptions{}
2139 \def\mpi@documentclass{\@backslashchar documentclass%
2140 \mpi@latexoptions{\mpi@latexclass}}
2141 % \end{macrocode}
2142
2143 % \macro{\mpi@warncompile}
2144 % Warn and disable compiling if shell escape is unavailable:
2145 % \begin{macrocode}
2146 \def\mpi@warncompile{\ifmpi@compile\ifnum\ShellEscapeStatus=0\relax%
2147 \PackageWarningNoLine{mpostinl}{shell escape (write18) disabled, %
2148 manual metapost compiling required}{}%
2149 \global\mpi@compilefalse\fi\fi}
2150 % \end{macrocode}
2151
2152 % Process package options:
2153 % \begin{macrocode}
2154 \def\mpi@group{mpi@}
2155 \DeclareOption{final}{\mpi@draftfalse}
2156 \define@key{\mpi@group}{draft}[true]{\csname mpi@draft#1\endcsname}
2157 \define@key{\mpi@group}{write}[true]{\csname mpi@write#1\endcsname}
2158 \define@key{\mpi@group}{latex}[true]{\csname mpi@latex#1\endcsname}
2159 \define@key{\mpi@group}{compile}[true]{\csname mpi@compile#1\endcsname}
2160 \define@key{\mpi@group}{twice}[true]{\csname mpi@twice#1\endcsname}
2161 \define@key{\mpi@group}{clean}[true]{\csname mpi@clean#1\endcsname}
2162 \define@key{\mpi@group}{checksum}[true]{\csname mpi@checksum#1\endcsname}
2163 \define@key{\mpi@group}{fonts}[true]{\csname mpi@fonts#1\endcsname}
2164 \define@key{\mpi@group}{prologues}[]{\def\mpi@prologues{#1}}
2165 \define@key{\mpi@group}{lineno}[true]{\csname mpi@lineno#1\endcsname}
2166 \define@key{\mpi@group}{labelnames}[true]{\csname mpi@labelnames#1\endcsname}
2167 \define@key{\mpi@group}{compiler}[]{\def\mpi@texcompiler{#1}}
2168 \define@key{\mpi@group}{format}[]{\def\mpi@texformat{#1}}
2169 \define@key{\mpi@group}{mem}[]{\def\mpi@mpostmem{#1}}
2170 \define@key{\mpi@group}{command}[]{\def\mpi@mpostcompiler{#1}}
2171 \define@key{\mpi@group}{class}{\def\mpi@latexclass{#1}}
2172 \define@key{\mpi@group}{classopt}[]{\def\mpi@latexoptions{[#1]}}
2173 \define@key{\mpi@group}{beamer}[true]{\csname mpi@beamer#1\endcsname}
2174 \define@key{\mpi@group}{warnunused}[true]{\csname mpi@warnunused#1\endcsname}
2175 \define@key{\mpi@group}{now}[true]{\csname mpi@nowactive#1\endcsname}
2176 \define@key{\mpi@group}{nowall}[true]{\csname mpi@now#1\endcsname}
2177 \define@key{\mpi@group}{nowkeep}[true]{\csname mpi@nowkeep#1\endcsname}
2178 \define@key{\mpi@group}{globaldef}[true]{\csname mpi@defglobal#1\endcsname}
2179 \define@key{\mpi@group}{figurepath}[]{\def\mpi@figurepath{#1}%
2180 \ifx\mpi@figurepath\mpi@empty\else\def\mpi@figurepath{#1\mpi@dirsep}\fi}
2181 \define@key{\mpi@group}{figureprefix}[]{\def\mpi@figureprefix{#1}}
2182 \define@key{\mpi@group}{extension}[]{\def\mpi@extension{#1}%
2183 \ifx\mpi@extension\mpi@empty\else\def\mpi@extension{.#1}\fi}
2184 \define@key{\mpi@group}{template}{\def\mpi@template##1{#1}}
2185 \define@key{\mpi@group}{numberwithin}{%
2186 \@addtoreset{mpi@count}{#1}%
2187 \def\thempi@count{\arabic{#1}-\arabic{mpi@count}}%
2188 }
2189 % \end{macrocode}
2190
2191 % Pass undeclared options on to \ctanpkg{keyval} processing:
2192 % \begin{macrocode}
2193 \DeclareOption*{\expandafter\setkeys\expandafter\mpi@group%
2194 \expandafter{\CurrentOption}}
2195 % \end{macrocode}
2196
2197 % Process package options,
2198 % warn if shell escape mechanism is not available,
2199 % and disable checksum if |\pdfmdfivesum| is not available:
2200 % \begin{macrocode}
2201 \ProcessOptions
2202 \mpi@warncompile
2203 \ifdefined\pdfmdfivesum\else\mpi@checksumfalse\fi
2204 % \end{macrocode}
2205
2206 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2207 % \paragraph{Internal Commands and Definitions.}
2208 %
2209 % \macro{\mpi@empty}
2210 % Define an empty macro for comparison via |\ifx|:
2211 % \begin{macrocode}
2212 \def\mpi@empty{}
2213 % \end{macrocode}
2214
2215 % \macro{\mpi@unusedlist}
2216 % Initialise a list of unused figure labels:
2217 % \begin{macrocode}
2218 \def\mpi@unusedlist{}
2219 % \end{macrocode}
2220
2221
2222 % \macro{\mpi@dblquotchar}
2223 % Define a bare double quotation character for writing to the file:
2224 % \begin{macrocode}
2225 \begingroup\catcode`\"=12\relax\gdef\mpi@dblquotchar{"}\endgroup
2226 % \end{macrocode}
2227
2228 % \macro{\ifmpi@infile}
2229 % \macro{\ifmpi@inbody}
2230 % |\ifmpi@infile| indicates whether a file is open,
2231 % |\ifmpi@inbody| indicates whether the content section has started:
2232 % \begin{macrocode}
2233 \newif\ifmpi@infile\mpi@infilefalse
2234 \newif\ifmpi@inbody\mpi@inbodyfalse
2235 % \end{macrocode}
2236
2237 % \macro{\ifmpi@inclmod}
2238 % \macro{\ifmpi@filemod}
2239 % |\ifmpi@inclmod| indicates whether an include file has been modified,
2240 % |\ifmpi@filemod| indicates whether the current file is modified:
2241 % \begin{macrocode}
2242 \newif\ifmpi@inclmod\mpi@inclmodfalse
2243 \newif\ifmpi@filemod
2244 % \end{macrocode}
2245
2246 % \macro{\ifmpi@warnmod}
2247 % \macro{\ifmpi@showinfile}
2248 % |\ifmpi@warnmod| indicates whether a rerun warning is to be issued,
2249 % |\ifmpi@showinfile| indicates whether a figure has been displayed
2250 % while a file is being composed:
2251 % \begin{macrocode}
2252 \newif\ifmpi@warnmod\mpi@warnmodfalse
2253 \newif\ifmpi@showinfile
2254 % \end{macrocode}
2255
2256 % \macro{\mpi@out}
2257 % \macro{\mpi@outnow}
2258 % File handles for the metapost file (|\mpi@out|)
2259 % and for immediate output (|\mpi@outnow|):
2260 % \begin{macrocode}
2261 \newwrite\mpi@out
2262 \newwrite\mpi@outnow
2263 % \end{macrocode}
2264
2265 % \macro{\mpi@writebuf}
2266 % Write to the file:
2267 % \begin{macrocode}
2268 \def\mpi@writebuf{\ifmpi@write\immediate\write\mpi@out{\the\mpi@buf}\fi}
2269 % \end{macrocode}
2270
2271 % \macro{\mpi@writenow}
2272 % Write to the immediate buffer:
2273 % \begin{macrocode}
2274 \def\mpi@writenow{\ifmpi@nowactive\mpi@addtoexp\mpi@nowbuf{\the\mpi@buf^^J}\fi}
2275 % \end{macrocode}
2276
2277 % \macro{\mpi@buf}
2278 % \macro{\mpi@defbuf}
2279 % \macro{\mpi@nowbuf}
2280 % Declare three token buffers to store the current block (|\mpi@buf|),
2281 % global definitions (|\mpi@defbuf|)
2282 % and the definitions for immediate processing (|\mpi@nowbuf|):
2283 % \begin{macrocode}
2284 \newtoks\mpi@buf
2285 \newtoks\mpi@defbuf
2286 \newtoks\mpi@nowbuf
2287 \newtoks\mpi@verbbuf
2288 \mpi@defbuf={}
2289 % \end{macrocode}
2290
2291 % \macro{\mpi@addto}
2292 % \macro{\mpi@addtoexp}
2293 % |\mpi@addto| adds the second argument to a global token buffer
2294 % without expansion.
2295 % |\mpi@addtoexp| first expands the second argument (once)
2296 % and adds it to the token buffer:
2297 % \begin{macrocode}
2298 \def\mpi@addto#1#2{\global#1=\expandafter{\the#1#2}}
2299 \def\mpi@addtoexp#1#2{\expandafter\mpi@addto\expandafter#1\expandafter{#2}}
2300 % \end{macrocode}
2301
2302 % \macro{\mpi@clearbuf}
2303 % \macro{\mpi@addbufexp}
2304 % \macro{\mpi@addbufbuf}
2305 % \macro{\mpi@addbuf}
2306 % |\mpi@clearbuf| clears the current block buffer.
2307 % |\mpi@addbufexp| expands the first token
2308 % and adds to the current block buffer.
2309 % |\mpi@addbufbuf| adds a buffer to the current block buffer.
2310 % |\mpi@addbuf| adds to the current block buffer via |\protected@edef|:
2311 % \begin{macrocode}
2312 \def\mpi@clearbuf{\global\mpi@buf={}}
2313 \def\mpi@addbufexp#1{\mpi@addtoexp\mpi@buf{#1^^J}}
2314 \def\mpi@addbufbuf#1{\mpi@addtoexp\mpi@buf{\the#1}}
2315 \def\mpi@addbuf#1{{\protected@edef\mpi@tmp{#1}\mpi@addbufexp\mpi@tmp}}
2316 % \end{macrocode}
2317
2318 % \macro{\mpi@stripext}
2319 % Strip |.mps| or |.eps| ending of a figure filename,
2320 % return result in |\mpi@stripped|:
2321 % \begin{macrocode}
2322 \def\mpi@stripext#1{\edef\mpi@tmp{#1}\expandafter%
2323 \mpi@stripstart\expandafter{\mpi@tmp}}
2324 \def\mpi@ifeq#1#2#3#4{\def\mpi@tmpa{#1}\def\mpi@tmpb{#2}%
2325 \ifx\mpi@tmpa\mpi@tmpb#3\else#4\fi}
2326 \def\mpi@stripstart#1{\mpi@stripfor{\@gobble}#1.\@@.}
2327 \def\mpi@stripfor#1#2.#3.{%
2328 \begingroup%
2329 \mpi@ifeq{#3}{\@@}{%
2330 \def\mpi@tmp{\def\mpi@stripped{#1.#2}}%
2331 \mpi@ifeq{#1}{\@gobble}{}{%
2332 \mpi@ifeq{#2}{eps}{\def\mpi@tmp{\def\mpi@stripped{#1}}}{}%
2333 \mpi@ifeq{#2}{mps}{\def\mpi@tmp{\def\mpi@stripped{#1}}}{}%
2334 \ifx\mpi@extension\mpi@empty\else%
2335 \expandafter\mpi@ifeq\expandafter{\mpi@extension}{#2}%
2336 {\def\mpi@tmp{\def\mpi@stripped{#1}}}{}%
2337 \fi%
2338 }%
2339 }{\def\mpi@tmp{\mpi@stripfor{#1.#2}#3.}}%
2340 \expandafter\endgroup\mpi@tmp%
2341 }
2342 % \end{macrocode}
2343
2344 % \macro{\mpi@warnmod}
2345 % Warn if some figure has been displayed while a file has been written
2346 % (potentially the displayed figure is old):
2347 % \begin{macrocode}
2348 \newcommand{\mpi@warnmod}{%
2349 \ifmpi@checksum\ifmpi@warnmod%
2350 \PackageWarningNoLine{mpostinl}{figure(s) may have changed. %
2351 Rerun to update figures}{}%
2352 \fi\fi%
2353 }
2354 % \end{macrocode}
2355
2356 % \macro{\mpi@warnunused}
2357 % This macro processes the list of all figure labels
2358 % and issues a warning for every unused ones:
2359 % \begin{macrocode}
2360 \def\mpi@warnunused#1{%
2361 \begingroup\def\mpi@tmp{#1}\ifx\mpi@tmp\mpi@empty\else%
2362 \ifcsname mpi@lu@#1\endcsname\else
2363 \PackageWarningNoLine{mpostinl}{figure label `#1' not used}{}%
2364 \fi%
2365 \def\mpi@tmp{\mpi@warnunused}%
2366 \fi\expandafter\endgroup\mpi@tmp%
2367 }
2368 % \end{macrocode}
2369 % Run |\mpi@warnunused| at the end of the document:
2370 % \begin{macrocode}
2371 \AtEndDocument{\expandafter\mpi@warnunused\mpi@unusedlist{}}
2372 % \end{macrocode}
2373
2374 % \macro{\mpostdisplaylabel}
2375 % Rescan a string potentially containing the special characters
2376 % underscore (`|_|'), caret (`|^|') and ampersand (`|&|'):
2377 % \begin{macrocode}
2378 \newcommand{\mpostdisplaylabel}[1]{{%
2379 \catcode`\_=11\catcode`\^=11\catcode`\&=11%
2380 \edef\mpi@tmp{#1}\expandafter\scantokens\expandafter{\mpi@tmp}}}
2381 % \end{macrocode}
2382
2383 % \macro{\mpostplaceholder}
2384 % Display a placeholder for non-existing files or labels;
2385 % this function may be overwritten by the user for customisation purposes
2386 % (optional argument contains either `|file|' or `|label|'):
2387 % \begin{macrocode}
2388 \newcommand{\mpostplaceholder}[2][]{\parbox[c]{1in}{%
2389 \hrule\vrule\hfill%
2390 \parbox[c]{0pt}{\rule{0cm}{0.6in}}%
2391 \makebox[0pt][c]{\scriptsize\tt\mpostdisplaylabel{#2}}%
2392 \hfill\vrule\hrule}}
2393 % \end{macrocode}
2394
2395 % \macro{\mpi@graphics}
2396 % Display a figure;
2397 % if the file does not exist (yet) issue a warning and display a placeholder,
2398 % otherwise expand filename properly and pass on to |\includegraphics|:
2399 % \begin{macrocode}
2400 \newcommand{\mpi@graphics}[2][]{%
2401 \IfFileExists{#2}%
2402 {\edef\mpi@tmp{#2}\includegraphics[#1]{\mpi@tmp}}%
2403 {\typeout{graphics file `#2' missing}\mpostplaceholder[file]{#2}}%
2404 }
2405 % \end{macrocode}
2406
2407 % \macro{\mpi@verbatim}
2408 % Start reading the block from the source file
2409 % using the \ctanpkg{verbatim} package;
2410 % add each line to the buffer:
2411 % \begin{macrocode}
2412 \newcommand{\mpi@verbatim}{%
2413 \begingroup%
2414 \@bsphack%
2415 \let\do\@makeother\dospecials%
2416 \catcode`\^^M\active%
2417 \global\mpi@verbbuf={}%
2418 \def\verbatim@processline{\mpi@addtoexp\mpi@verbbuf{\the\verbatim@line^^J}}%
2419 \verbatim@start%
2420 }
2421 % \end{macrocode}
2422
2423 % \macro{\mpi@endverbatim}
2424 % End reading the block from the source file:
2425 % \begin{macrocode}
2426 \newcommand{\mpi@endverbatim}{%
2427 \@esphack%
2428 \endgroup%
2429 }
2430 % \end{macrocode}
2431
2432 % \macro{\mpi@scanblock}
2433 % Read one optional argument and pass on
2434 % to an environment which reads a block from the source file.
2435 % Handle special cases of an initial empty line
2436 % or a completely empty block.
2437 % Pass prefetched tokens as second argument:
2438 % \begin{macrocode}
2439 \def\mpi@scanblock#1{%
2440 \@ifnextchar\par{\mpi@scanblock@par{#1}}{\mpi@scanblock@sel{#1}}}
2441 \long\def\mpi@scanblock@par#1\par{\mpi@scanblock@sel{#1}[]}
2442 \def\mpi@scanblock@sel#1{\@ifnextchar[{\mpi@scanblock@opt{#1}}%
2443 {\@ifnextchar\end{\mpi@scanblock@end{#1}}{\mpi@scanblock@noopt{#1}}}}
2444 \def\mpi@scanblock@end#1\end#2{%
2445 \def\mpi@tmp{#2}\ifx\mpi@tmp\@currenvir%
2446 \def\mpi@verbatim{\global\mpi@verbbuf={}}\def\mpi@endverbatim{}%
2447 \fi%
2448 #1{}{\scantokens{\end{#2}}}}
2449 \def\mpi@scanblock@noopt#1#2{#1{}{\scantokens#2}}
2450 \def\mpi@scanblock@opt#1[#2]{#1{#2}{}}
2451 % \end{macrocode}
2452
2453 % \macro{\mpi@putlineno}
2454 % Write current position in source file to buffer;
2455 % write line number and source file name
2456 % (if available via package \ctanpkg{currfile}):
2457 % \begin{macrocode}
2458 \newcommand{\mpi@putlineno}{%
2459 \ifmpi@lineno%
2460 \mpi@addbuf{\@percentchar---------------------------------------}%
2461 \mpi@addbuf{\@percentchar%
2462 \ifx\currfilename\@undefined\else\currfilename\space\fi%
2463 l.\the\inputlineno}%
2464 \fi%
2465 }
2466 % \end{macrocode}
2467
2468 % \macro{\mpi@beginfig}
2469 % Write beginning of figure block to buffer;
2470 % write filename and |beginfig| statement:
2471 % \begin{macrocode}
2472 \newcommand{\mpi@beginfig}[1]{%
2473 \mpi@addbuf{filenametemplate \mpi@dblquotchar#1\mpi@dblquotchar;}%
2474 \mpi@addbuf{beginfig(\arabic{mpi@count})}%
2475 }
2476 % \end{macrocode}
2477
2478 % \macro{\mpi@endfig}
2479 % Write end of figure block to buffer;
2480 % write |endfig| statement:
2481 % \begin{macrocode}
2482 \newcommand{\mpi@endfig}{%
2483 \mpi@addbuf{endfig;}%
2484 }
2485 % \end{macrocode}
2486
2487 % \macro{\mpi@declaredoc}
2488 % Write |\documentclass| statement in \LaTeX{} mode to buffer:
2489 % \begin{macrocode}
2490 \newcommand{\mpi@declaredoc}{%
2491 \ifmpi@latex%
2492 \mpi@addbuf{verbatimtex}%
2493 \mpi@addbuf{\mpi@documentclass}%
2494 \mpi@addbuf{etex}%
2495 \mpi@addbuf{}%
2496 \fi%
2497 }
2498 % \end{macrocode}
2499
2500 % \macro{\mpi@begindoc}
2501 % Write beginning of content section to buffer;
2502 % write |\||begin{document}| statement in \LaTeX{} mode:
2503 % \begin{macrocode}
2504 \newcommand{\mpi@begindoc}{%
2505 \ifmpi@latex%
2506 \mpi@putlineno%
2507 \mpi@addbuf{verbatimtex}%
2508 \mpi@addbuf{\@backslashchar begin{document}}%
2509 \mpi@addbuf{etex}%
2510 \fi%
2511 }
2512 % \end{macrocode}
2513
2514 % \macro{\mpi@enddoc}
2515 % Write end of content section to buffer;
2516 % write |\||end{document}| statement in \LaTeX{} mode:
2517 % \begin{macrocode}
2518 \newcommand{\mpi@enddoc}{%
2519 \ifmpi@latex%
2520 \mpi@putlineno%
2521 \mpi@addbuf{verbatimtex}%
2522 \mpi@addbuf{\@backslashchar end{document}}%
2523 \mpi@addbuf{etex}%
2524 \fi%
2525 }
2526 % \end{macrocode}
2527
2528 % \macro{\mpi@declareformat}
2529 % Write \TeX{} format specifier to buffer:
2530 % \begin{macrocode}
2531 \newcommand{\mpi@declareformat}{%
2532 \let\mpi@tmp\mpi@texformat%
2533 \ifx\mpi@tmp\@undefined\def\mpi@tmp{\ifmpi@latex latex\else tex\fi}\fi%
2534 \ifx\mpi@tmp\mpi@empty\else%
2535 \mpi@addbuf{verbatimtex}%
2536 \mpi@addbuf{\@percentchar &\mpi@tmp}%
2537 \mpi@addbuf{etex}%
2538 \mpi@addbuf{}%
2539 \fi%
2540 }
2541 % \end{macrocode}
2542
2543 % \macro{\mpi@composehead}
2544 % Write file header to buffer;
2545 % declare font inclusion and draft mode,
2546 % write \TeX{} format specifier and \LaTeX{} header:
2547 % \begin{macrocode}
2548 \newcommand{\mpi@composehead}{%
2549 \mpi@putlineno%
2550 \let\mpi@tmp\mpi@prologues%
2551 \ifx\mpi@tmp\@undefined\def\mpi@tmp{\ifmpi@fonts 3\else 2\fi}\fi%
2552 \ifx\mpi@tmp\mpi@empty\else%
2553 \mpi@addbuf{prologues:=\mpi@tmp;}%
2554 \fi%
2555 \ifmpi@draft\mpi@addbuf{draft:=1;}\fi%
2556 \mpi@addbuf{}%
2557 \mpi@declareformat%
2558 \mpi@declaredoc%
2559 }
2560 % \end{macrocode}
2561
2562 % \macro{\mpi@beginfile}
2563 % Write beginning of file to buffer;
2564 % write generated file comment and header:
2565 % \begin{macrocode}
2566 \newcommand{\mpi@beginfile}{%
2567 \ifx\mpi@mpostmem\mpi@empty\else%
2568 \mpi@addbuf{\@percentchar &\mpi@mpostmem}%
2569 \fi%
2570 \mpi@addbuf{\@percentchar generated from file `\jobname' by mpostinl.sty}%
2571 \ifmpi@include\else%
2572 \mpi@composehead%
2573 \mpi@addbufbuf{\mpi@defbuf}%
2574 \fi%
2575 }
2576 % \end{macrocode}
2577
2578 % \macro{\mpi@endfile}
2579 % Write end of file to buffer;
2580 % write |end| statement:
2581 % \begin{macrocode}
2582 \newcommand{\mpi@endfile}{%
2583 \mpi@putlineno%
2584 \ifmpi@include\else%
2585 \mpi@addbuf{end}%
2586 \fi%
2587 }
2588 % \end{macrocode}
2589
2590 % \macro{\mpi@getchecksum}
2591 % Compute the MD5 checksum for a metapost file and store in macro:
2592 % \begin{macrocode}
2593 \newcommand{\mpi@getchecksum}[3]{%
2594 \IfFileExists{#3}{#1\edef#2{\pdfmdfivesum file{#3}}}{#1\let#2=\@undefined}%
2595 }
2596 % \end{macrocode}
2597
2598 % \macro{\mpi@startfile}
2599 % Start a new file if not already open:
2600 % \begin{macrocode}
2601 \newcommand{\mpi@startfile}{%
2602 \ifmpi@infile\else%
2603 % \end{macrocode}
2604 % Prevent reopening and overwriting the previous file:
2605 % \begin{macrocode}
2606 \ifx\mpostfilename\mpi@empty%
2607 \PackageError{mpostinl}{no filename provided to write to}{}%
2608 \fi%
2609 % \end{macrocode}
2610 % Compute checksum of old file:
2611 % \begin{macrocode}
2612 \ifmpi@checksum\ifmpi@inclmod\else%
2613 \mpi@getchecksum{\global}{\mpi@checksum@before}{\mpostfilename.mp}%
2614 \fi\fi%
2615 \ifmpi@checksum\global\mpi@filemodfalse\else\global\mpi@filemodtrue\fi%
2616 \ifmpi@inclmod\global\mpi@filemodtrue\fi%
2617 % \end{macrocode}
2618 % Open file for writing, prepare and write header to file:
2619 % \begin{macrocode}
2620 \global\mpi@infiletrue%
2621 \global\mpi@showinfilefalse%
2622 \gdef\mpi@filelist{}%
2623 \ifmpi@write\immediate\openout\mpi@out\mpostfilename.mp\fi%
2624 \mpi@clearbuf%
2625 \mpi@beginfile%
2626 \mpi@writebuf%
2627 % \end{macrocode}
2628 % For include files, write |input| statement to definition buffer
2629 % so that the file will be included by all main files:
2630 % \begin{macrocode}
2631 \ifmpi@include%
2632 \mpi@clearbuf%
2633 \mpi@putlineno%
2634 \mpi@addbuf{input \mpostfilename}%
2635 \mpi@addtoexp\mpi@defbuf{\the\mpi@buf^^J}%
2636 % \end{macrocode}
2637 % If immediate mode is available fill immediate buffer with header:
2638 % \begin{macrocode}
2639 \else%
2640 \global\mpi@nowbuf={}%
2641 \mpi@writenow%
2642 \fi%
2643 \fi%
2644 }
2645 % \end{macrocode}
2646
2647 % \macro{\mpi@startcontent}
2648 % Start content section of file;
2649 % make sure the file is open,
2650 % prepare start of content section and write to file,
2651 % if immediate mode is available also add to immediate buffer:
2652 % \begin{macrocode}
2653 \newcommand{\mpi@startcontent}{%
2654 \mpi@startfile%
2655 \ifmpi@inbody\else%
2656 \global\mpi@inbodytrue%
2657 \mpi@clearbuf%
2658 \mpi@begindoc%
2659 \mpi@writebuf%
2660 \mpi@writenow%
2661 \fi%
2662 }
2663 % \end{macrocode}
2664
2665 % \macro{\mpi@compile}
2666 % Compile the metapost file (if writing and compiling is enabled):
2667 % \begin{macrocode}
2668 \newcommand{\mpi@compile}[1]{%
2669 \ifmpi@write\ifmpi@compile%
2670 \ifx\mpi@mpostcompiler\mpi@empty%
2671 % \end{macrocode}
2672 % Compose command line for |mpost|;
2673 % pass on interactionmode setting to \MP{},
2674 % specify mem filem, specify tex compiler:
2675 % \begin{macrocode}
2676 \def\mpi@imode{}%
2677 \ifcase\the\interactionmode%
2678 \def\mpi@imode{-interaction=batchmode}\or%
2679 \def\mpi@imode{-interaction=nonstopmode}\or%
2680 \def\mpi@imode{-interaction=scrollmode}\or%
2681 \def\mpi@imode{-interaction=errorstopmode}\fi%
2682 \let\mpi@texswitch\mpi@texcompiler%
2683 \ifx\mpi@texswitch\@undefined%
2684 \def\mpi@texswitch{\ifmpi@latex latex\else tex\fi}%
2685 \fi%
2686 \def\mpi@execute{mpost\space%
2687 \mpi@imode\space%
2688 \ifx\mpi@mpostmem\mpi@empty\else -mem=\mpi@mpostmem\space\fi%
2689 \ifx\mpi@texswitch\mpi@empty\else -tex=\mpi@texswitch\space\fi%
2690 #1}%
2691 \else%
2692 % \end{macrocode}
2693 % Compose custom command:
2694 % \begin{macrocode}
2695 \def\mpi@execute{\mpi@mpostcompiler\space#1}%
2696 \fi%
2697 % \end{macrocode}
2698 % Execute \MP{} by |\ShellEscape|; do it again if needed:
2699 % \begin{macrocode}
2700 \ShellEscape{\mpi@execute}%
2701 \ifmpi@twice%
2702 \ShellEscape{\mpi@execute}%
2703 \fi%
2704 \fi\fi%
2705 }
2706 % \end{macrocode}
2707
2708 % \macro{\mpi@cleanfile}
2709 % Write a mps file containing a plain cross:
2710 % \begin{macrocode}
2711 \newcommand{\mpi@cleanfile}[1]{%
2712 \immediate\openout\mpi@outnow#1%
2713 \immediate\write\mpi@outnow{%
2714 \@percentchar!PS-Adobe-3.0 EPSF-3.0^^J%
2715 \@percentchar\@percentchar Title: missing figure file^^J%
2716 \@percentchar\@percentchar Creator: mpostinl.sty^^J%
2717 \@percentchar\@percentchar BoundingBox: -36 -22 36 22^^J%
2718 \@percentchar\@percentchar EndComments^^J%
2719 \@percentchar\@percentchar Page: 1 1^^J%
2720 0 setgray 0 1.5 dtransform truncate idtransform setlinewidth pop^^J%
2721 [] 0 setdash 1 setlinecap 1 setlinejoin 10 setmiterlimit^^J%
2722 newpath -35 21 moveto 35 -21 lineto stroke^^J%
2723 newpath -35 -21 moveto 35 21 lineto stroke^^J%
2724 \@percentchar\@percentchar EOF}%
2725 \immediate\closeout\mpi@outnow%
2726 }
2727 % \end{macrocode}
2728
2729 % \macro{\mpi@cleanfiles}
2730 % Clean all figure files prior to compilation:
2731 % \begin{macrocode}
2732 \newcommand{\mpi@cleanfiles}[1]{%
2733 \begingroup\def\mpi@tmp{#1}%
2734 \ifx\mpi@tmp\mpi@empty\else\def\mpi@tmp{\mpi@cleanfiles}%
2735 \mpi@cleanfile{#1}\fi%
2736 \expandafter\endgroup\mpi@tmp%
2737 }
2738 % \end{macrocode}
2739
2740 % \macro{\mpi@closefile}
2741 % Close the file, compile and reset:
2742 % \begin{macrocode}
2743 \newcommand{\mpi@closefile}{%
2744 \ifmpi@infile%
2745 % \end{macrocode}
2746 % Write end of content section (if started):
2747 % \begin{macrocode}
2748 \mpi@clearbuf%
2749 \ifmpi@inbody%
2750 \mpi@enddoc%
2751 \mpi@addbuf{}%
2752 \fi%
2753 % \end{macrocode}
2754 % Write end of file and close:
2755 % \begin{macrocode}
2756 \mpi@endfile%
2757 \mpi@writebuf%
2758 \ifmpi@write\immediate\closeout\mpi@out\fi%
2759 % \end{macrocode}
2760 % Determine whether file has changed:
2761 % \begin{macrocode}
2762 \ifmpi@filemod\else%
2763 \mpi@getchecksum{}{\mpi@checksum@after}{\mpostfilename.mp}%
2764 \ifx\mpi@checksum@before\mpi@checksum@after\else\mpi@filemodtrue\fi%
2765 \fi%
2766 \ifmpi@include\ifmpi@filemod\global\mpi@inclmodtrue\fi\fi%
2767 % \end{macrocode}
2768 % Compile if file has changed and if it contains figures.
2769 % Activate warning if file has changed and figures were displayed
2770 % during composition:
2771 % \begin{macrocode}
2772 \ifmpi@filemod\ifmpi@inbody%
2773 \ifmpi@clean\ifmpi@write\ifmpi@compile%
2774 \expandafter\mpi@cleanfiles\mpi@filelist{}\fi\fi\fi%
2775 \mpi@compile{\mpostfilename.mp}%
2776 \fi\fi%
2777 \ifmpi@filemod\ifmpi@showinfile\global\mpi@warnmodtrue\fi\fi%
2778 % \end{macrocode}
2779 % Reset variables:
2780 % \begin{macrocode}
2781 \global\mpi@infilefalse%
2782 \global\let\mpostfilename\mpi@empty%
2783 \global\mpi@inbodyfalse%
2784 \setcounter{mpi@count}{0}%
2785 \fi%
2786 }
2787 % \end{macrocode}
2788
2789 % \macro{\mpi@processnow}
2790 % Write present figure to an individual file and process immediately:
2791 % \begin{macrocode}
2792 \newcommand{\mpi@processnow}{%
2793 \ifmpi@nowactive\ifmpi@write\ifmpi@compile%
2794 % \end{macrocode}
2795 % If immediate file is to be kept,
2796 % use \textit{filename}|.mp| as source
2797 % for \textit{filename}|.mps| output file.
2798 % \begin{macrocode}
2799 \ifmpi@nowkeep%
2800 \mpi@stripext{\mpi@figfile}%
2801 \edef\mpi@nowname{\mpi@stripped}%
2802 \fi%
2803 % \end{macrocode}
2804 % Open immediate file, write the immediate buffer,
2805 % the present figure and the end of file, close the file and compile:
2806 % \begin{macrocode}
2807 \immediate\openout\mpi@outnow\[email protected]%
2808 \immediate\write\mpi@outnow{\the\mpi@nowbuf}%
2809 \immediate\write\mpi@outnow{\the\mpi@buf}%
2810 \mpi@clearbuf%
2811 \mpi@enddoc%
2812 \mpi@addbuf{}%
2813 \mpi@endfile%
2814 \immediate\write\mpi@outnow{\the\mpi@buf}%
2815 \immediate\closeout\mpi@outnow%
2816 \ifmpi@clean\mpi@cleanfile{\mpi@figfile}\fi%
2817 \mpi@compile{\[email protected]}%
2818 \fi\fi\fi%
2819 }
2820 % \end{macrocode}
2821
2822 % Make sure to close and process the file at the end.
2823 % Warn if figures may need another compiler pass:
2824 % \begin{macrocode}
2825 \AtEndDocument{\mpi@closefile}
2826 \AtEndDocument{\mpi@warnmod}
2827 % \end{macrocode}
2828
2829 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2830 % \paragraph{External Commands.}
2831 %
2832 % The following commands are the interface of the package.
2833 %
2834 % \macro{\mpostsetup}
2835 % |\mpostsetup| processes package options
2836 % when the package has already been loaded:
2837 % \begin{macrocode}
2838 \newcommand{\mpostsetup}[1]{%
2839 \setkeys\mpi@group{#1}%
2840 \mpi@warncompile%
2841 \ifdefined\pdfmdfivesum\else\mpi@checksumfalse\fi%
2842 }
2843 % \end{macrocode}
2844
2845 % \macro{mpostdef}
2846 % Declare options for the |mpostdef| environment:
2847 % \begin{macrocode}
2848 \newif\ifmpi@deftex
2849 \define@key{mpi@def}{tex}[true]{\csname mpi@deftex#1\endcsname}
2850 \define@key{mpi@def}{global}[true]{\csname mpi@defglobal#1\endcsname}
2851 % \end{macrocode}
2852
2853 % The environment |mpostdef| adds a block
2854 % of definitions to the metapost file.
2855 % Pass on to |\mpi@scanblock| mechanism:
2856 % \begin{macrocode}
2857 \def\mpostdef{\mpi@scanblock{\mpi@mpostdef}}
2858 \def\mpi@mpostdef#1#2{%
2859 % \end{macrocode}
2860 % Process optional arguments:
2861 % \begin{macrocode}
2862 \mpi@deftexfalse%
2863 \setkeys{mpi@def}{#1}%
2864 % \end{macrocode}
2865 % \TeX{} definitions cannot be in an include file:
2866 % \begin{macrocode}
2867 \ifmpi@defglobal\else\ifmpi@deftex\ifmpi@include%
2868 \PackageWarning{mpostinl}{tex definitions within an include file %
2869 will be ignored by mpost; switching to global definition}{}%
2870 \mpi@defglobaltrue%
2871 \fi\fi\fi%
2872 % \end{macrocode}
2873 % Prepare for recording; start the file if not open and not global,
2874 % clear buffer, write current position,
2875 % and add `|verbatimtex|' if in \TeX{} mode:
2876 % \begin{macrocode}
2877 \ifmpi@defglobal\else%
2878 \mpi@startfile%
2879 \fi%
2880 \mpi@clearbuf%
2881 \mpi@putlineno%
2882 \ifmpi@deftex%
2883 \mpi@addbuf{verbatimtex}%
2884 \fi%
2885 \mpi@verbatim#2%
2886 }
2887 % \end{macrocode}
2888 % Postprocessing; add `|etex|' if in \TeX{} mode,
2889 % add to appropriate buffer(s).
2890 % \begin{macrocode}
2891 \def\endmpostdef
2892 {%
2893 \mpi@endverbatim%
2894 \mpi@addbufbuf{\mpi@verbbuf}%
2895 \ifmpi@deftex%
2896 \mpi@addbuf{etex}%
2897 \fi%
2898 \ifmpi@defglobal%
2899 \mpi@addtoexp\mpi@defbuf{\the\mpi@buf^^J}%
2900 \ifmpi@include\else\ifmpi@infile%
2901 \mpi@writebuf%
2902 \mpi@writenow%
2903 \fi\fi%
2904 \else%
2905 \mpi@writebuf%
2906 \ifmpi@include\else\mpi@writenow\fi%
2907 \fi%
2908 }
2909 % \end{macrocode}
2910
2911 % \macro{mposttex}
2912 % Declare options for the |mposttex| environment:
2913 % \begin{macrocode}
2914 \newif\ifmpi@deftex
2915 \define@key{mpi@tex}{dual}[true]{\csname mpi@texdual#1\endcsname}
2916 \define@key{mpi@tex}{global}[true]{\csname mpi@defglobal#1\endcsname}
2917 % \end{macrocode}
2918
2919 % The environment |mposttex| adds a block
2920 % of tex definitions to the metapost file.
2921 % Pass on to |\mpi@scanblock| mechanism:
2922 % \begin{macrocode}
2923 \def\mposttex{\mpi@scanblock{\mpi@mposttex}}
2924 \def\mpi@mposttex#1#2{%
2925 % \end{macrocode}
2926 % Process optional arguments:
2927 % \begin{macrocode}
2928 \mpi@texdualfalse%
2929 \setkeys{mpi@tex}{#1}%
2930 % \end{macrocode}
2931 % \TeX{} definitions cannot be in an include file:
2932 % \begin{macrocode}
2933 \ifmpi@defglobal\else\ifmpi@include%
2934 \PackageWarning{mpostinl}{tex definitions within an include file %
2935 will be ignored by mpost; switching to global definition}{}%
2936 \mpi@defglobaltrue%
2937 \fi\fi%
2938 % \end{macrocode}
2939 % Prepare for recording; start the file if not open and not global,
2940 % clear buffer, write current position, and add `|verbatimtex|':
2941 % \begin{macrocode}
2942 \ifmpi@defglobal\else%
2943 \mpi@startfile%
2944 \fi%
2945 \mpi@clearbuf%
2946 \mpi@putlineno%
2947 \mpi@addbuf{verbatimtex}%
2948 \mpi@verbatim#2%
2949 }
2950 % \end{macrocode}
2951 % Postprocessing; add `|etex|',
2952 % add to appropriate buffer(s).
2953 % \begin{macrocode}
2954 \def\endmposttex
2955 {%
2956 \mpi@endverbatim%
2957 \mpi@addbufbuf{\mpi@verbbuf}%
2958 \mpi@addbuf{etex}%
2959 \ifmpi@defglobal%
2960 \mpi@addtoexp\mpi@defbuf{\the\mpi@buf^^J}%
2961 \ifmpi@include\else\ifmpi@infile%
2962 \mpi@writebuf%
2963 \mpi@writenow%
2964 \fi\fi%
2965 \else%
2966 \mpi@writebuf%
2967 \ifmpi@include\else\mpi@writenow\fi%
2968 \fi%
2969 % \end{macrocode}
2970 % Hack |\ignorespacesafterend| mechanism to
2971 % ship out block contents after environment group:
2972 % \begin{macrocode}
2973 \ifmpi@texdual%
2974 \ignorespacesafterend%
2975 \global\let\mpi@ignorespaces\ignorespaces%
2976 \gdef\ignorespaces{\expandafter\scantokens\expandafter{\the\mpi@verbbuf}%
2977 \global\let\ignorespaces\mpi@ignorespaces}%
2978 \fi%
2979 }
2980 % \end{macrocode}
2981
2982 % \macro{mpostfig}
2983 % Declare options for the |mpostfig| environment:
2984 % \begin{macrocode}
2985 \newif\ifmpi@figshow
2986 \define@key{mpi@fig}{show}[true]{\csname mpi@figshow#1\endcsname}
2987 \define@key{mpi@fig}{twice}[true]{\csname mpi@twice#1\endcsname}
2988 \define@key{mpi@fig}{file}{\def\mpi@figfile{#1}}
2989 \define@key{mpi@fig}{label}{\def\mpi@figlabel{#1}}
2990 \define@key{mpi@fig}{opt}{\def\mpi@figopt{[#1]}}
2991 \define@key{mpi@fig}{now}[true]{\csname mpi@now#1\endcsname}
2992 % \end{macrocode}
2993
2994 % The environment |mpostfig| adds a figure to the metapost file.
2995 % Pass on to |\mpi@scanblock| mechanism:
2996 % \begin{macrocode}
2997 \def\mpostfig{\mpi@scanblock{\mpi@mpostfig}}
2998 \def\mpi@mpostfig#1#2{%
2999 % \end{macrocode}
3000 % Make sure that include files do not contain figures:
3001 % \begin{macrocode}
3002 \ifmpi@include%
3003 \PackageError{mpostinl}{cannot write figure to include file}{}%
3004 \fi%
3005 % \end{macrocode}
3006 % Process optional arguments:
3007 % \begin{macrocode}
3008 \def\mpi@figfile{}%
3009 \def\mpi@figlabel{}%
3010 \def\mpi@figopt{}%
3011 \mpi@figshowfalse%
3012 \setkeys{mpi@fig}{#1}%
3013 % \end{macrocode}
3014 % Display figure if no filename or label is provided:
3015 % \begin{macrocode}
3016 \ifx\mpi@figlabel\mpi@empty\ifx\mpi@figfile\mpi@empty\mpi@figshowtrue\fi\fi%
3017 % \end{macrocode}
3018 % Compose filename from label (if desired and specified):
3019 % \begin{macrocode}
3020 \ifmpi@labelnames\ifx\mpi@figfile\mpi@empty\ifx\mpi@figlabel\mpi@empty\else%
3021 \edef\mpi@figfile{\mpi@template{\mpi@figlabel}}%
3022 \fi\fi\fi%
3023 % \end{macrocode}
3024 % Compose filename from counter if no filename is provided:
3025 % \begin{macrocode}
3026 \ifx\mpi@figfile\mpi@empty%
3027 \addtocounter{mpi@count}{1}%
3028 \edef\mpi@figfile{\mpi@template{\thempi@count}}%
3029 \fi%
3030 % \end{macrocode}
3031 % Save filename to label, warn if label has already been defined,
3032 % remember all labels for checking whether unused:
3033 % \begin{macrocode}
3034 \ifx\mpi@figlabel\mpi@empty\else%
3035 \expandafter\ifx\csname mpi@l@\mpi@figlabel\endcsname\relax\else%
3036 \PackageWarning{mpostinl}{label `\mpi@figlabel' already defined; %
3037 overwriting}{}%
3038 \fi%
3039 \expandafter\xdef\csname mpi@l@\mpi@figlabel\endcsname{\mpi@figfile}%
3040 \ifmpi@warnunused\ifmpi@figshow\else%
3041 \xdef\mpi@unusedlist{\mpi@unusedlist{\mpi@figlabel}}%
3042 \fi\fi%
3043 \fi%
3044 % \end{macrocode}
3045 % Prepare for recording; start file and content section (if needed),
3046 % clear buffer, write current position, begin figure block:
3047 % \begin{macrocode}
3048 \mpi@startcontent%
3049 \mpi@clearbuf%
3050 \mpi@putlineno%
3051 \mpi@beginfig{\mpi@figfile}%
3052 \mpi@verbatim#2%
3053 }
3054 % \end{macrocode}
3055 % Postprocessing; end figure block, add to buffer, add file to list,
3056 % process immediately if desired:
3057 % \begin{macrocode}
3058 \def\endmpostfig
3059 {%
3060 \mpi@endverbatim%
3061 \mpi@addbufbuf{\mpi@verbbuf}%
3062 \mpi@endfig%
3063 \mpi@writebuf%
3064 \xdef\mpi@filelist{\mpi@filelist{\mpi@figfile}}%
3065 \ifmpi@now%
3066 \mpi@processnow%
3067 \fi%
3068 % \end{macrocode}
3069 % Force compile if output file does not exist, is empty or equals dummy figure:
3070 % \begin{macrocode}
3071 \ifmpi@filemod\else%
3072 \mpi@getchecksum{}{\mpi@tmpa}{\mpi@figfile}%
3073 \ifdefined\mpi@tmpa%
3074 \edef\mpi@tmpa{\scantokens\expandafter{\mpi@tmpa\noexpand}}%
3075 \def\mpi@tmpb{965DFFE32ABB43CC14C58E254B4D660E}%
3076 \ifx\mpi@tmpa\mpi@tmpb\global\mpi@filemodtrue\fi%
3077 \def\mpi@tmpb{D78A5F2EE4B244260ECD6A0E89ADC9CE}%
3078 \ifx\mpi@tmpa\mpi@tmpb\global\mpi@filemodtrue\fi%
3079 \def\mpi@tmpb{D41D8CD98F00B204E9800998ECF8427E}%
3080 \ifx\mpi@tmpa\mpi@tmpb\global\mpi@filemodtrue\fi%
3081 \else%
3082 \global\mpi@filemodtrue%
3083 \fi
3084 \fi%
3085 % \end{macrocode}
3086 % Display figure.
3087 % Remember immediate display of figure unless processed immediately:
3088 % \begin{macrocode}
3089 \ifmpi@figshow%
3090 \expandafter\mpi@graphics\mpi@figopt{\mpi@figfile}%
3091 \ifmpi@now\else\global\mpi@showinfiletrue\fi%
3092 \fi%
3093 }
3094 % \end{macrocode}
3095
3096 % \macro{\mpostuse}
3097 % |\mpostuse| includes a metapost figure which was declared earlier
3098 % via its label. The optional argument is passed as the optional
3099 % argument for |\includegraphics|.
3100 % Remember that the label has been used,
3101 % remember if a file is currently open for writing:
3102 % \begin{macrocode}
3103 \newcommand{\mpostuse}[2][]{%
3104 \expandafter\ifx\csname mpi@l@#2\endcsname\relax%
3105 \PackageWarning{mpostinl}{unknown label `#2'}{}%
3106 \mpostplaceholder[label]{#2}%
3107 \else%
3108 \ifmpi@warnunused\expandafter\gdef\csname mpi@lu@#2\endcsname{}\fi%
3109 \mpi@graphics[#1]{\csname mpi@l@#2\endcsname}%
3110 \ifmpi@infile\global\mpi@showinfiletrue\fi%
3111 \fi%
3112 }
3113 % \end{macrocode}
3114
3115 % \macro{\mpostgetname}
3116 % |\mpostgetname| gets the filename of a figure declared earlier
3117 % via its label and returns it in the macro |\mpostfigurename|.
3118 % Remember that the label has been used:
3119 % \begin{macrocode}
3120 \newcommand{\mpostgetname}[1]{%
3121 \expandafter\ifx\csname mpi@l@#1\endcsname\relax%
3122 \PackageWarning{mpostinl}{unknown label `#1'}{}%
3123 \let\mpostfigurename\relax%
3124 \else%
3125 \ifmpi@warnunused\expandafter\gdef\csname mpi@lu@#1\endcsname{}\fi%
3126 \edef\mpostfigurename{\csname mpi@l@#1\endcsname}%
3127 \fi%
3128 }
3129 % \end{macrocode}
3130
3131 % \macro{\mpostfile}
3132 % Declare options for |\mpostfile|:
3133 % \begin{macrocode}
3134 \define@key{mpi@file}{include}[true]{\csname mpi@include#1\endcsname}
3135 % \end{macrocode}
3136
3137 % |\mpostfile| sets up a new metapost file.
3138 % If the previous file is still open,
3139 % it will be closed and processed first:
3140 % \begin{macrocode}
3141 \newcommand{\mpostfile}[2][]{%
3142 \mpi@closefile%
3143 \mpi@includefalse%
3144 \setkeys{mpi@file}{#1}%
3145 \xdef\mpostfilename{#2}%
3146 }
3147 % \end{macrocode}
3148
3149 % \macro{\mpostdone}
3150 % |\mpostdone| closes the present metapost file
3151 % and processes it if applicable:
3152 % \begin{macrocode}
3153 \newcommand{\mpostdone}{\mpi@closefile}
3154 % \end{macrocode}
3155
3156 % \macro{\mpostuse<>}
3157 % This overwrites the definition of |\mpostfile|
3158 % to accept the overlay option |<|\ldots|>|
3159 % of the \ctanpkg{beamer} package:
3160 % \begin{macrocode}
3161 \ifmpi@beamer\@ifclassloaded{beamer}{
3162 \let\mpi@plain@mpostuse\mpostuse%
3163 \newcommand<>{\mpostuse}[2][]{\begingroup%
3164 \expandafter\def\expandafter\includegraphics\expandafter%
3165 {\includegraphics#3}%
3166 \mpi@plain@mpostuse[#1]{#2}\endgroup}%
3167 }{}\fi
3168 % \end{macrocode}
3169
3170 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3171 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3172 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3173 % \iffalse
3174 %</package>
3175 % \fi
3176 %
3177 \endinput