diff options
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base/source/mpman.tex')
-rw-r--r-- | Master/texmf-dist/doc/metapost/base/source/mpman.tex | 2150 |
1 files changed, 728 insertions, 1422 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpman.tex b/Master/texmf-dist/doc/metapost/base/source/mpman.tex index d72d133cc6d..0f689273db3 100644 --- a/Master/texmf-dist/doc/metapost/base/source/mpman.tex +++ b/Master/texmf-dist/doc/metapost/base/source/mpman.tex @@ -1,4 +1,4 @@ -% $Id: mpman.tex 524 2008-05-13 23:01:45Z stephanhennig $ +% $Id: mpman.tex 1051 2009-05-25 08:31:54Z taco $ % MetaPost manual, by John Hobby. License at end. \listfiles \RequirePackage{ifpdf} @@ -12,8 +12,8 @@ \fi \documentclass{article} % article is NOT the original style \usepackage[nofancy]{svninfo}% Access VCS information. -\svnInfo $Id: mpman.tex 524 2008-05-13 23:01:45Z stephanhennig $ -\newcommand*{\mpversion}{1.005} +\svnInfo $Id: mpman.tex 1051 2009-05-25 08:31:54Z taco $ +\newcommand*{\mpversion}{1.200} \usepackage[T1]{fontenc} \usepackage{lmodern} @@ -64,9 +64,10 @@ \usepackage{hyperxmp} \usepackage{hyperref} \hypersetup{ - pdftitle={A User's Manual for MetaPost}, + pdftitle={MetaPost: A User's Manual}, pdfauthor={John D. Hobby and the MetaPost development team}, - pdfkeywords={MetaPost, PostScript, vector graphics language, MetaFont, TeX} + pdfkeywords={MetaPost, PostScript, SVG, vector graphics language, + MetaFont, TeX} } \hypersetup{ pdfstartview={XYZ null null null},% Zoom factor is determined by viewer. @@ -94,7 +95,7 @@ \vfil \centerline{\resizebox{3.5in}{!}{\fontseries{b}\selectfont\MP}} \vskip10bp% actually 21bp (-11bp) - \centerline{\includegraphics{manfig-60.mps}} + \centerline{\includegraphics{mpman-60.mps}} \vskip15bp% actually 21bp (-6bp) \centerline{% \resizebox{3.5in}{!}{% @@ -130,7 +131,8 @@ MetaPost is a programming language much like Knuth's \MF\footnote{\MF\ is a trademark of Addison Wesley Publishing company.}\index{metafont?\MF}~\cite{kn:c} except that it outputs -PostScript programs instead of bitmaps. Borrowed from \MF\ are the +vector graphics, either PostScript programs or SVG\index{SVG} graphics, +instead of bitmaps. Borrowed from \MF\ are the basic tools for creating and manipulating pictures. These include numbers, coordinate pairs, cubic splines, affine transformations, text strings, and boolean quantities. Additional features facilitate @@ -151,62 +153,19 @@ is really a programming language for generating graphics, especially figures for \TeX\footnote{\TeX\ is a trademark of the American Mathematical Society.}\index{TeX?\TeX} and troff\index{troff} documents. -To use MetaPost, you prepare an input file containing MetaPost code and -then invoke MetaPost, usually by giving a command of the -form\index{mpost?\texttt{mpost}} -$$ {\tt mpost}\, \descr{filename} $$ -The syntax and program name itself are system-dependent; sometimes it is -named \texttt{mp}. MetaPost input -files\index{files!input} normally have names ending ``{\tt .mp}'' but -this part of the name can be omitted when invoking MetaPost. For an -input file {\tt foo.mp} -$$ \hbox{\tt mpost foo} $$ -invokes MetaPost and produces output files with names like {\tt foo.1} -and {\tt foo.2}. Any terminal I/O is summarized in a -transcript\index{files!transcript}\index{transcript file} file called -{\tt foo.log}. This includes error messages and any MetaPost commands -entered interactively.\footnote{A {\tt *}\index{*?\texttt{*}} prompt is -used for interactive input and a {\tt **}\index{**?\texttt{**}} prompt -indicates that an input file name is expected. This can be avoided by -invoking MetaPost on a file that ends with an {\tt -end}\index{end?\texttt{end}} command.} - -\label{Dmpversion}The transcript file starts with a banner line that -identifies the version of MetaPost you are using. You can also determine -the current version from within a MetaPost program via the -\texttt{mpversion} predefined constant string (this was introduced in -version 0.9). For instance: -$$\begin{verbatim} -if known mpversion: - message "mp = " & mpversion; - if scantokens(mpversion) < 1: message "CMYK color support not available!" fi -fi -\end{verbatim} -$$ -prints -$$\begin{verbatim}[commandchars=\\\{\}] -mp = \mpversion -\end{verbatim} -$$ -The {\tt scantokens} command is described on p.~\pageref{Dscantokens} -and can be utilized to convert strings to numbers. -\index{Creator comment in PostScript output}% -The version number is also included in the \texttt{Creator} comment in -the PostScript output. - This document introduces the MetaPost language, beginning with the features that are easiest to use and most important for simple -applications. Reading the manual does not require knowledge of \MF\ or -access to {\sl The \MF book}, but both are beneficial. -The first few sections describe the language as it +applications. The first few sections describe the language as it appears to the novice user with key parameters at their default values. Some features described in these sections are part of a predefined macro package called Plain. Later sections summarize the complete language and distinguish between primitives and preloaded macros from the Plain -macro package\index{Plain macros}. Since much of the language is -identical to Knuth's \MF, the appendix gives a detailed comparison so -that advanced users can learn more about MetaPost by reading {\sl The -\MF book\/} \cite{kn:c}. +macro package\index{Plain macros}. Reading the manual and creating +moderately complex graphics with MetaPost does not require knowledge of +\MF\ or access to {\sl The \MF book} \cite{kn:c}. However, to really +master MetaPost, both are beneficial, since the MetaPost language is +based on Knuth's \MF\ to a large extent. Appendix~\ref{MPvsMF} gives a +detailed comparison of MetaPost and \MF. MetaPost documentation is completed by ``Drawing Boxes with MetaPost'' and ``Drawing Graphs with MetaPost''---the manuals of the \texttt{boxes} @@ -236,7 +195,7 @@ $$ \hbox{\verb|draw (20,20)--(0,0)|} $$ draws\index{draw?\texttt{draw}} a diagonal line and $$ \hbox{\verb|draw (20,20)--(0,0)--(0,30)--(30,0)--(0,0)|} $$ draws a polygonal line like this: -$$ \includegraphics{manfig-1} $$ +$$ \includegraphics{mpman-1.mps} $$ \label{Ddrawdot}MetaPost also has a \ttt{drawdot} command to print a single point, as in \ttt{drawdot(30,0)}. @@ -309,62 +268,235 @@ for i=0 upto 2: endfor endfig; \end{verbatim} -\quad \mathcenter{\includegraphics{manfig-2}} +\quad \mathcenter{\includegraphics{mpman-2.mps}} $$ \caption{MetaPost commands and the resulting output} \label{fig1} \end{figure} -Note that the program in Figure~\ref{fig1} starts with -\verb|beginfig(2)|\index{beginfig?\texttt{beginfig}} and ends with -\verb|endfig|\index{endfig?\texttt{endfig}}. These are macros that -perform various administrative functions and ensure that the results of -all the \verb|draw| statements get packaged up and translated into -PostScript. A MetaPost input file normally contains a sequence of -\verb|beginfig|, \verb|endfig| pairs with an {\tt -end}\index{end?\texttt{end}} statement after the last one. If this file -is named {\tt fig.mp}, the output from \verb|draw| statements between -\verb|beginfig(1)| and the next \verb|endfig| is written in a file {\tt -fig.1}\index{files!output}. In other words, the numeric argument to the -\verb|beginfig| macro determines the name of the corresponding output -file. - -What does one do with all the PostScript files? They can be included as -figures in a \TeX\index{TeX?\TeX} or troff\index{troff} document if you -have an output driver that can handle encapsulated PostScript figures. -They can also be previewed before they are included in a thousand pages -document. The next sections give some more information. - - -\section{Handling MetaPost output} -\label{Dmpoutput} - -There can be a two-fold interaction between \TeX\ and MetaPost. On one -hand, MetaPost graphics can be imported into documents typeset by \TeX\ -and friends. On the other hand, MetaPost can delegate typesetting -textual elements to \TeX, \LaTeX\ or \emph{troff}, e.g., text labels or -mathematical formulas in a graphic. That way, MetaPost graphics can -easily adopt the style of a document (type, type size, etc.) and fit its -typesetting quality (use kerning, ligatures, etc.) This makes MetaPost -an ideal tool for preparing high-quality graphics for \TeX\ or -\emph{troff} documents. - -This section deals with the first aspect of \TeX--MetaPost interaction, -the import of MetaPost graphics into \TeX\ and friends. Typesetting -text in MetaPost is discussed in section~\ref{text}. +\section{The MetaPost workflow} +\label{workflow} + +Before describing the MetaPost language in detail, let's have a look at +how the MetaPost program is used for developing graphics: creating +MetaPost source files, compiling sources, previewing MetaPost graphics, +and finally including MetaPost graphics into third-party applications. +This section also contains some technical details about MetaPost that +are useful to know. If you're not interested in these basics right now +you can savely skip those parts and only refer to them later. + +\subsection{Processing source files} +\label{processing} + +To create graphics with MetaPost, you prepare a text file containing +code in the MetaPost language and then invoke the compiler, usually by +giving a command of the form\index{mpost?\texttt{mpost}} +$$ {\tt mpost}\, \descr{filename} $$ +on the command-line. The syntax and program name itself are +system-dependent; sometimes it is named \texttt{mp}. MetaPost input +files\index{files!input} normally have names ending +\texttt{.mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}} but +this part of the name can be omitted when invoking MetaPost. The +command-line options provided by MetaPost are summarized in +appendix~\ref{refman:commandline}. + +\paragraph{Input file} +\label{inputfile} + +A MetaPost input file normally contains a sequence of +\verb|beginfig()|\index{beginfig?\texttt{beginfig}}, +\verb|endfig|\index{endfig?\texttt{endfig}} pairs with an {\tt + end}\index{end?\texttt{end}} statement after the last one. These are +macros that perform various administrative functions and ensure that the +results of all drawing operations get packaged up and translated into +PostScript. The numeric argument to the \verb|beginfig| macro +determines the name of the corresponding output file, whose name, by +default, is of the form $\descr{jobname}{\tt.}\descr{n}$, where +$\descr{jobname}$ is the base name of the graphics source file and +$\descr{n}$ is the current argument to \verb|beginfig|. As an example, +if a file is named {\tt fig.mp}, the output from drawing statements +between \verb|beginfig(1)| and the next \verb|endfig| is written in a +file {\tt fig.1}\index{files!output}. + +Statements can also appear outside \verb|beginfig/endfig|. Such +statements are processed, but drawing operations generate no visible +output. Typically, global configurations are put outside +\verb|beginfig/endfig|, e.g., assignments to internal variables, such as +\verb|outputtemplate| or \verb|prologues|, or a \LaTeX\ preamble +declaration for enhanced text rendering. + +\paragraph{Log file and version number} +\label{logfile} + +Any terminal I/O is summarized in a +transcript\index{files!transcript}\index{transcript file} file called +$\descr{filename}{\tt.log}$\index{log file?{\tt log} + file}\index{files!log?{\tt log}}. This includes error messages and +any MetaPost commands entered interactively.\footnote{A {\tt + *}\index{*?\texttt{*}} prompt is used for interactive input and a + {\tt **}\index{**?\texttt{**}} prompt indicates that an input file + name is expected. This can be avoided by invoking MetaPost on a file + that ends with an {\tt end}\index{end?\texttt{end}} command.} The +transcript file starts with a banner line that identifies the +version\index{version number} of MetaPost you are using. The version +number is also written to the generated PostScript or SVG file as a +comment (for PostScript output the \texttt{Creator}\index{Creator + comment in PostScript output} line is used). You can also determine +the current version from within a MetaPost program via the predefined +constant string +\texttt{mpversion}\index{mpversion?\texttt{mpversion}}\label{Dmpversion} +(since version~0.9). For instance the following code + +$$\begin{verbatim} +message "mp = " & mpversion; +\end{verbatim} +$$ +writes +$$\begin{verbatim}[commandchars=\\\{\}] +mp = \mpversion +\end{verbatim} +$$ +to the console and the transcript file. + +\paragraph{Output format} +\label{outputformat} + +MetaPost can generate graphic in two output formats: Encapsulated +PostScript\index{PostScript!structured} (EPSF\index{EPSF}), hence the +name, and, since version~1.200, Scalable Vector Graphics +(SVG\index{SVG}) following version~1.1 of the SVG +specification~\cite{w3c:svg1.1}. By default, MetaPost outputs +PostScript files. The output format can be changed to SVG by assigning +the value \verb|"svg"| to the internal string variable\index{internal + variables}\index{variables!internal} +\ttindex{outputformat}\label{Doutputformat}: + +$$\begin{verbatim} +outputformat := "svg"; +\end{verbatim} +$$ + +Any other value makes MetaPost fall back to PostScript output. Variable +\verb|outputformat| is case-sensitive, so assigning it the string +\verb|"SVG"| enables PostScript output, too. Default value of variable +\verb|outputformat| is \verb|"eps"|. + +\paragraph{Output file names} +\label{outputfilenames} + +As discussed earlier, by default, every +\verb|beginfig/endfig| group in an input file corresponds to an output +file that follows the naming scheme $\descr{jobname}{\tt.}\descr{n}$. +That is, all files have varying numeric file extensions. MetaPost +provides a template mechanism that allows for more flexible output file +names. The template mechanism uses \ttt{printf}-style escape sequences +that are re-evaluated at ship-out time, i.e., before each figure is +written to disk. + +To configure the output file naming scheme a string containing the +corresponding escape sequences has to be assigned to the internal string +variable\index{internal variables}\index{variables!internal} +\ttt{outputtemplate}% +\index{outputtemplate?\texttt{outputtemplate}}\label{Doutputtemplate}. +The escape sequences provided are listed in table~\ref{tab:fntmpl}. If +this code is saved in a file \ttt{fig.mp}, + +$$\begin{verbatim} +outputtemplate := "%j-%3c.mps"; +beginfig(1); + draw origin--(100,100); +endfig; +\end{verbatim} +$$ +it will create the output file \ttt{fig-001.mps} instead of \ttt{fig.1}. +The file extension \texttt{.mps}\index{mps file?{\tt mps} + file}\index{files!mps?{\tt mps}} is conventionally chosen for +MetaPost's PostScript output (see section~\ref{teximport}). For SVG +output one would want to use \texttt{.svg}\index{svg file?{\tt svg} + file}\index{files!svg?{\tt svg}} instead. + +%\suppressfloats[t] +\begin{table} + \def\d{$\langle$0-9$\rangle$} + \centering + \begin{tabular}{|>{\ttfamily}l|>{\ttfamily}l|l|} + \hline + \multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Equivalent} + & \multicolumn1{c|}{Meaning}\\\hline + \%\%\index{\%\%?\texttt{\%\%}} & & percent sign\\ + \%\d\{$\descr{internal + variable}$\}\index{\%\{...\}?\texttt{\%\{\ldots\}}} & & evaluate + internal variable\\ + \%j\index{\%j?\texttt{\%j}} & \%\{jobname\} & current jobname\\ + \%\d c\index{\%c?\texttt{\%c}} & \%\d\{charcode\} & charcode value (\verb|beginfig| + argument)\\ + \%\d y\index{\%y?\texttt{\%y}} & \%\d\{year\} & current year\\ + \%\d m\index{\%m?\texttt{\%m}} & \%\d\{month\} & month (numeric)\\ + \%\d d\index{\%d?\texttt{\%d}} & \%\d\{day\} & day of the month\\ + \%\d H\index{\%H?\texttt{\%H}} & \%\d\{hour\} & hour\\ + \%\d M\index{\%M?\texttt{\%M}} & \%\d\{minute\} & minute\\ + \hline + \end{tabular} + \caption{Allowed escape sequences for \ttt{outputtemplate}} + \label{tab:fntmpl} +\end{table} + +The template mechanism can also be used for naming graphic files +individually, yet keeping all sources in one file. E.\,g., collecting +different diagram sources in a file \ttt{fig.mp} + +$$\begin{verbatim} +outputtemplate := "fig-quality.mps"; +beginfig(1); + ... +endfig; + +outputtemplate := "fig-cost-vs-productivity.mps"; +beginfig(2); + ... +endfig; +\end{verbatim} +$$ +it might be easier to recall the correct diagram names in a \TeX\ +document than with numbered file names. Note, the argument to +\verb|beginfig| is not relevant as long as there's no \ttt{\%c} pattern +in the file name template string. + +To ensure compatibility with older files, the default value of +\ttt{outputtemplate} is \verb|%j.%c|. +If you assign an empty string, it will revert to that default. MetaPost +versions~1.000 to~1.102 used a different template mechanism, see +section~\ref{Dfilenametemplate} for more information. + +What does one do with all the graphic files? PostScript files are +perfectly suitable for inclusion into documents created by +\TeX\index{TeX?\TeX} or \emph{troff}\index{troff}. The SVG format, as +an XML descendant (Extensible Meta Language), is more aiming at +automated data processing/interchanging and is widely used for web +applications. The next sections deal with the import of MetaPost +graphics into third-party applications. + +At this point, it seems advisable to point out, that it is good style to +create MetaPost graphics at nearly target size. While vector graphics +\emph{can} be scaled without quality degradation, the visual character +of a drawing might change unintentionally at large post-processing scale +factors, because certain properties of a drawing do not scale +proportionally, e.g., line width or arrow size. Additionally, while +outline fonts do scale proportionally, this is not always desired, e.g., +when a font is available in optical sizes, like the Computer Modern font +family. \subsection{Previewing MetaPost graphics} -\label{Dpreview} +\label{previewing} \index{previewing} +\index{PostScript!previewing} +\index{SVG!previewing} -The output of MetaPost is a variant of PostScript, called Encapsulated -PostScript\index{PostScript!structured} (EPSF\index{EPSF}). MetaPost -graphics can therefore be previewed with any decent PostScript viewer, -e.\,g., GSview\index{GSview}. - -The situation becomes only a little bit fussy when MetaPost output -contains text. By default, MetaPost doesn't produce self-contained EPS +The PostScript output of MetaPost can be previewed with any decent +PostScript viewer, e.\,g., GSview\index{GSview}. +The situation becomes only a little bit fussy when PostScript graphics +contain text. By default, MetaPost doesn't produce self-contained EPS files, e.\,g., font resources and encoding vectors are not stored in the output. For that reason MetaPost output containing text may be rendered with wrong fonts, wrong glyphs or with no text at all in a @@ -384,131 +516,100 @@ new behaviour can be triggered by setting MetaPost's internal variable \ttt{prologues}\index{prologues?\texttt{prologues}} to~3. See section~\ref{Dbtex} for more information on \ttt{prologues}. +Starting with version~1.200, MetaPost is also capable of producing +SVG output. SVG files can be previewed with certain web browsers, +for example Firefox~3\index{Firefox} or Konqueror~4.2\index{Konqueror}. -\subsection{Using MetaPost graphics in \TeX, \LaTeX, pdf\LaTeX, pdf\TeX, Con\TeX{}t and troff} -\label{Dteximport} +\subsection{Importing MetaPost graphics in \TeX\ documents} +\label{teximport} \index{TeX?\TeX!importing MetaPost files} \index{LaTeX?\LaTeX!importing MetaPost files} \index{pdfLaTeX?pdf\LaTeX!importing MetaPost files} \index{pdfTeX?pdf\TeX!importing MetaPost files} \index{ConTeXt?Con\TeX t!importing MetaPost files} -\index{troff!importing MetaPost files} -How MetaPost figures can be integrated into documents prepared with -\TeX\ and friends depends on the exact format and output driver. -Figure~\ref{fig0} shows the workflow for plain \TeX, \LaTeX\ and the -freely available program \ttindex{dvips}.\footnote{The C source for -\ttt{dvips} comes with the web2c \TeX\ distribution. Similar programs -are available from other sources.} A similar procedure works with -troff: the \ttt{grops} output processor includes PostScript figures when -they are requested via troff's \ttt{\string\X} command. For the PDF -flavour of \TeX\ and \LaTeX\ the situation is a little bit different. -The next paragraphs give brief information on some popular \TeX\ formats -and output drivers. +MetaPost graphics in the PostScript format can be easily integreated +into documents prepared with \TeX\ and friends. MetaPost's PostScript +output is a low-featured dialect of the Postscript language, called +\emph{purified EPS}, that can be converted into the Portable Document +Format (PDF\index{PDF}) language on-the-fly. For that reason, MetaPost +graphics can be handled by both engines, the traditional \TeX\ with an +external output driver and the newer pdf\TeX, that contains a built-in +PDF output driver. + +Figure~\ref{fig0} shows the process of including a MetaPost graphic into +a plain \TeX\ or \LaTeX\ document. In the \TeX\ document a ``magic +macro'' provided by the format or an external package is used for +including a graphic file. During the typesetting stage, the macro only +reads bounding box information off the PostScript file and reserves the +required space on the page via an empty box. The file reference is +passed-on to the output driver and only then, finally, the file is +embedded into the document. The freely available program +\ttindex{dvips} is used as an output driver in this +example.\footnote{The C source for \ttt{dvips} comes with the web2c + \TeX\ distribution. Similar programs are available from other + sources.} The next paragraphs give brief information on some popular +combinations of formats and engines. \begin{figure}[htp] -$$ \includegraphics{manfig-0} $$ +$$ \includegraphics{mpman-0.mps} $$ \caption[A diagram of the processing for a document with MetaPost figures] {A diagram of the processing for a \TeX\ document with figures in MetaPost} \label{fig0} \end{figure} -\paragraph{\TeX} -\TeX\ users can import EPS graphics by first loading package -\ttt{epsf}\index{epsf.tex?\texttt{epsf.tex}} via \verb+\input epsf+ and -then issuing the command -$$ \verb+\epsfbox{+\descr{filename}\verb+}+ $$% -\index{epsfbox?\texttt{\string\epsfbox}} -to load an EPS file, e.\,g., \verb+\epsfbox{fig.1}+. - -\paragraph{\LaTeX} -For \LaTeX\ documents the procedure is similar: first package -\ttindex{graphicx} has to be loaded by putting -\verb+\usepackage{graphicx}+ into the document preamble and then EPS -files can be loaded via -$$ \verb+\includegraphics{+\descr{filename}\verb+}+ $$% -\index{includegraphics?\texttt{\string\includegraphics}} -e.\,g., \verb+\includegraphics{fig.1}+. - -As can be seen in figure~\ref{fig0} graphic files are never included in a -\TeX\index{TeX?\TeX!importing MetaPost files} or -\LaTeX\index{LaTeX?\LaTeX!importing MetaPost files} run. Instead, -\TeX\ and \LaTeX\ only read bounding box information off PostScript -files, reserve as much space on a page as a graphic occupies and write -a reference to the corresponding file into \ttt{dvi} output. Graphic -files are only included in the subsequent run of an output driver, -that can handle PostScript files, e.\,g., \ttindex{dvips}. - -\paragraph{pdf\LaTeX} -The application pdf\LaTeX, when run in PDF mode, is both, a -\LaTeX\ interpreter and an output driver for the PDF document format. -For that reason graphic files are included in a single -pdf\LaTeX\ run. In contrast to \ttt{dvips}, pdf\LaTeX\ can't process -general PostScript files, but only so-called purified -EPS\index{PostScript!purified} files, which may only use a restricted -set of PostScript language features. Fortunately, MetaPost output -\emph{is} purified EPS, so we are in luck. Since -pdf\LaTeX's default extension for purified EPS files is -\ttt{mps}\index{files!mps?\texttt{mps}}, but MetaPost output by -default has a number as extensions, we either have to -\begin{itemize} -\item tell pdf\LaTeX\ to handle MetaPost's numbered files according to -\ttt{mps} file rules, or -\item change the file extension of MetaPost output to \ttt{mps}. -\end{itemize} - -For the conventional first approach we have to add the line -$$ \verb+\DeclareGraphicsRule{*}{mps}{*}{}+ $$% -\index{DeclareGraphicsRule?\texttt{\string\DeclareGraphicsRule}}% -to the document preamble after loading package \ttt{graphicx}. That -declaration tells pdf\LaTeX\ to load \emph{all} files with unknown file -extensions as \ttt{mps} files. Refer to the documentation of the -\ttt{graphicx} and \ttt{graphics} packages for more details. - -Since MetaPost version~1.000 the second approach is -recommended.\footnote{For handling MetaPost file extensions in MetaPost -source files seems to be the more natural place than \LaTeX\ sources. -Moreover, setting the MetaPost file extension to \ttt{mps} prevents from -file extension pollution and you only have to register one new extension -with your PostScript viewer, \ttt{.mps}, instead of \ttt{.0}, \ttt{.1}, -\ttt{.2}, etc.} The MetaPost primitive \verb+filenametemplate+ can be -used to set the file extension of MetaPost output to \ttt{mps} (see -section~\ref{Dfilenametemplate}). Hence, no \verb+\DeclareGraphicsRule+ -declaration is needed. Moreover, the file extension can then be omitted -in the \verb+\includegraphics+ command. - -\paragraph{\LaTeX\ and pdf\LaTeX} -If you want to keep flexible and be able to compile your documents with -both, \LaTeX\ and pdf\LaTeX, there are some things to take care of. If -you're using the conventional \verb+\DeclareGraphicsRule+ declaration, -that may only be activated if pdf\LaTeX\ runs in PDF mode. A -fully-featured declaration should therefore look like this: +\paragraph{Plain \TeX\ with \TeX} +For users of \TeX\ with traditional DVI output the +\ttt{epsf}\index{epsf.tex?\texttt{epsf.tex}} package provides the +``magic macro'' +$$ \verb|\epsfbox{|\descr{filename}\verb|}|% +\index{epsfbox?\texttt{\string\epsfbox}} $$ +for embedding graphics, e.g., \verb|\epsfbox{fig.1}|. + +\paragraph{Plain \TeX\ with pdf\TeX} +Users of Plain \TeX\ and pdf\TeX\ should refer to the standalone macros +of the \ttindex{mptopdf} bundle, that can be found at +\url{http://context.aanhet.net/mptopdf.htm}. -$$ -\begin{verbatim} -\usepackage{graphicx} -\usepackage{ifpdf} -\ifpdf - \DeclareGraphicsRule{*}{mps}{*}{} -\fi +\paragraph{\LaTeX\ format} +For \LaTeX\ documents the well-known \ttindex{graphics} (or +\ttindex{graphicx}) package aids in external graphics inclusion. The +package supports different engines and can handle several graphic +formats. The ``magic macro'' is +$$ \verb|\includegraphics{|\descr{filename}\verb|}|% +\index{includegraphics?\texttt{\string\includegraphics}} $$ + +When the \ttt{dvips} driver is chosen, the \ttt{graphics} package +assumes all files with an unknown file extension to be in the EPS +format. MetaPost files with a numeric default file extension are +therefore handled correctly -- even if only in a fall-back procedure +(see~\cite{reckdahl:epslatex} for more information). + +For the pdf\TeX\ driver, the situation is a bit different. Only files +with file extension \texttt{.mps}\index{mps file?{\tt mps} + file}\index{files!mps?{\tt mps}} are recognized as purified EPS and +can be converted to PDF\index{PDF} on-the-fly. The recommended +procedure for including MetaPost graphics into \LaTeX\ documents +compiled with the pdf\TeX\ engine should be obvious: change MetaPost's +output file naming scheme to write files ending \texttt{.mps} via +\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}} (see +p.~\pageref{Doutputtemplate}). In the \LaTeX\ document include the +graphic files with full name, e.g., +$$\begin{verbatim} +\includegraphics{fig-1.mps} \end{verbatim} $$ -If you're using the \ttt{filenametemplate} method the \ttt{mps} file -extension should not be omitted in \verb+\includegraphics+ commands, -since \ttt{mps} is not part of \LaTeX's file name completion scheme, by -default. If the \ttt{mps} extension is present, \LaTeX\ handles those -files as \ttt{eps} files, which is obviously correct. For more -information see the description of \verb+\DeclareGraphicsExtensions+% -\index{DeclareGraphicsExtensions?\texttt{\string\DeclareGraphicsExtensions}} -and \verb+\DeclareGraphicsRule+ in the documentation of packages -\ttt{graphicx} and \ttt{graphics}. - -\paragraph{pdf\TeX} -Users of plain pdf\TeX\ should refer to the standalone macros of the -\ttindex{mptopdf} bundle, that can be found at -\url{http://context.aanhet.net/mptopdf.htm}. +Note, the latter approach works with the \ttt{dvips} driver, too. Even +though, again, this time \ttt{.mps} is an unknown file extension and +triggers EPS file handling in the fall-back procedure. This property of +the \ttt{graphics} package, that comes in handy for MetaPost files, is +the reason many MetaPost source files start with the line +$$\begin{verbatim} +outputtemplate := "%j-%c.mps"; +\end{verbatim} +$$ \paragraph{Con\TeX t} In Con\TeX t\index{ConTeXt?Con\TeX t} support of MetaPost is integrated @@ -526,84 +627,41 @@ for MetaPost inclusion is present in the versions MkII as well as MkIV, but the used methods are slightly different. Future versions of MkIV will support an even more tight integration. -\paragraph{troff} +\subsection{Importing MetaPost graphics in \emph{troff} documents} +\label{troffimport} +\index{troff!importing MetaPost files} + It is also possible to include MetaPost output in a GNU \emph{troff} -document. The \ttt{-mpspic}\index{mpspic?\texttt{-mpspic}} macro -package defines a command \verb|.PSPIC|\index{PSPIC?\texttt{.PSPIC}} -that includes an encapsulated PostScript file. For instance, the -\emph{troff} command +document. The procedure is similar to Figure~\ref{fig0}: the +\ttt{grops} output processor includes PostScript files when they are +requested via \emph{troff}'s \ttt{\string\X} command. The +\ttt{-mpspic}\index{mpspic?\texttt{-mpspic}} macro package provides a +command \verb|.PSPIC|\index{PSPIC?\texttt{.PSPIC}}, that does just that +when including an encapsulated PostScript file in the source code. For +instance, the \emph{troff} command $$ \hbox{\verb|.PSPIC fig.1|} $$ includes \ttt{fig.1}, using the natural height and width of the image as given in the file's bounding box. +\subsection{Handling SVG files} +\label{svgimport} +\index{SVG!third-party applications} -\subsection{File name templates} -\suppressfloats[t] - -MetaPost has support for output file name templates. These templates -use \ttt{printf}-style escape sequences and are re-evaluated before -each figure is written to disk. - -The command to use is \ttt{filenametemplate}% -\index{filenametemplate?\texttt{filenametemplate}}\label{Dfilenametemplate}, -and it accepts a string as argument. The syntax is as simple as: - -\begin{center}\begin{tabular}{l} -\verb|filenametemplate "%j-%3c.mps";|\\ -\verb|beginfig(1);|\\ -\verb| draw p;|\\ -\verb|endfig;| -\end{tabular}\end{center} - -If the file is saved as \ttt{fig.mp}, then this will create the output -file \ttt{fig-001.mps} instead of \ttt{fig.1}. A small set of escape -sequences are possible, see table~\ref{tab:fntmpl} for details. - -\def\d{$\langle$0-9$\rangle$} +SVG graphics can be easily embedded into HTML\index{HTML} documents with +the following code snippet: -\begin{table} -\centering -\begin{tabular}{|>{\ttfamily}l|l|} -\hline -\multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Meaning}\\\hline -\%\% & A percent sign \\ -\%j & The current jobname\\ -\%\d c & The charcode value\\ -\%\d y & The current year\\ -\%\d m & The numeric month\\ -\%\d d & The day of the month\\ -\%\d H & The hour\\ -\%\d M & The minute\\ -\hline -\end{tabular} -\caption{Allowed escape sequences for \ttt{filenametemplate}} -\label{tab:fntmpl} -\end{table} - -The \ttt{filenametemplate} primitive can also be helpful for naming -graphic files individually, yet keeping all MetaPost sources in one file. -E.\,g., collecting different diagram sources in a file \ttt{fig.mp} -$$ -\begin{verbatim} -filenametemplate "fig-quality.mps"; -beginfig(1); - ... -endfig; - -filenametemplate "fig-cost-vs-productivity.mps"; -beginfig(2); - ... -endfig; +$$\begin{verbatim} +<p> + <object data="foo.svg" type="image/svg+xml" width="300" height="200"> + </object> +</p> \end{verbatim} $$ -it might be easier to recall the correct diagram names in a -\TeX\ document than with numbered file names. Note, the argument to -\ttt{beginfig} is not relevant as long as there's no \ttt{\%c} pattern -in the file name template string. -To ensure compatibility with older files, the default value of -\ttt{filenametemplate} is \verb|%j.%c|. -If you assign an empty string, it will revert to that default. +SVG files can also be imported by various interactive graphics editing +programs, for example GIMP\index{GIMP} or Inkscape\index{Inkscape}. See +section~\ref{Dprologues} for information on font handling in SVG +graphics. \section{Curves} @@ -625,7 +683,7 @@ Figure~\ref{fig2} shows the curve with points \verb|z0| through \verb|z4| labeled. \begin{figure}[htp] -$$ \includegraphics{manfig-3} +$$ \includegraphics{mpman-3.mps} $$ \caption[A curve through points 0, 1, 2, 3, and 4] {The result of {\tt draw z0..z1..z2..z3..z4}} @@ -650,8 +708,8 @@ as having two draw statements \end{eqnarray*} \begin{figure}[htp] -$$ {\includegraphics{manfig-104} \atop (a)} - \qquad {\includegraphics{manfig-204} \atop (b)} +$$ {\includegraphics{mpman-104.mps} \atop (a)} + \qquad {\includegraphics{mpman-204.mps} \atop (b)} $$ \caption[Closed curves through five points] {(a)~The result of {\tt draw z0..\linebreak[0]z1..\linebreak[0]% @@ -704,7 +762,7 @@ draw (0,0)..controls (26.8,-1.8) and (51.4,14.6) $$ \begin{figure}[htp] -$$ \includegraphics{manfig-5} +$$ \includegraphics{mpman-5.mps} $$ \caption[A curve and the control polygon] {The result of {\tt draw z0..z1..z2..z3..z4} with the @@ -732,7 +790,7 @@ would have chosen a direction designed to make the curvature above \verb|z1| almost the same as the curvature below that point. \begin{figure}[htp] -$$ \includegraphics{manfig-6} +$$ \includegraphics{mpman-6.mps} $$ \caption[A curve and the control polygon] {The result of {\tt draw z0..z1\char`\{up\char`\}..z2\char`\{left\char`\}% @@ -747,7 +805,7 @@ directions there. Figures \ref{fig6} and~\ref{fig7} give a good idea of what this family of curves is like. \begin{figure}[htp] -$$ \mathcenter{\includegraphics{manfig-7}} \quad +$$ \mathcenter{\includegraphics{mpman-7.mps}} \quad \begin{verbatim} beginfig(7) for a=0 upto 9: @@ -761,7 +819,7 @@ $$ \end{figure} \begin{figure}[htp] -$$ \mathcenter{\includegraphics{manfig-8}} \quad +$$ \mathcenter{\includegraphics{mpman-8.mps}} \quad \begin{verbatim} beginfig(8) for a=0 upto 7: @@ -807,10 +865,10 @@ endpoint directions make this impossible.'' (It would be possible to avoid inflections in Figure~\ref{fig6}, but not in Figure~\ref{fig7}). \begin{figure}[htp] -$$ {\mathcenter{\includegraphics{manfig-109}} \atop +$$ {\mathcenter{\includegraphics{mpman-109.mps}} \atop \hbox{\verb|draw z0{up}..z1{right}..z2{down}|}} \quad - {\mathcenter{\includegraphics{manfig-209}} \atop + {\mathcenter{\includegraphics{mpman-209.mps}} \atop \hbox{\verb|draw z0{up}...z1{right}...z2{down}|}} $$ \caption{Two {\tt draw} statements and the resulting curves.} @@ -831,11 +889,11 @@ $$ \hbox{\verb|draw z0..z1..tension 1.5 and 1..z2..z3|} $$ The tension parameter can be less than one, but it must be at least $3\over4$. \begin{figure}[htp] -$$ {\mathcenter{\includegraphics{manfig-110}} \atop (a)} +$$ {\mathcenter{\includegraphics{mpman-110.mps}} \atop (a)} \quad - {\mathcenter{\includegraphics{manfig-210}} \atop (b)} + {\mathcenter{\includegraphics{mpman-210.mps}} \atop (b)} \quad - {\mathcenter{\includegraphics{manfig-310}} \atop (c)} + {\mathcenter{\includegraphics{mpman-310.mps}} \atop (c)} $$ \caption[Effects of changing the tension parameter] {Results of {\tt draw z0..z1..tension} $\alpha$ {\tt and} $\beta$ @@ -859,13 +917,13 @@ shown in Figure~\ref{fig10}. In particular, a curl value of zero makes the curvature approach zero. \begin{figure}[htp] -$$ {\mathcenter{\includegraphics{manfig-111}} \atop c=0} +$$ {\mathcenter{\includegraphics{mpman-111.mps}} \atop c=0} \qquad - {\mathcenter{\includegraphics{manfig-211}} \atop c=1} + {\mathcenter{\includegraphics{mpman-211.mps}} \atop c=1} \qquad - {\mathcenter{\includegraphics{manfig-311}} \atop c=2} + {\mathcenter{\includegraphics{mpman-311.mps}} \atop c=2} \qquad - {\mathcenter{\includegraphics{manfig-411}} \atop c=\infty} + {\mathcenter{\includegraphics{mpman-411.mps}} \atop c=\infty} $$ \caption[Effects of changing the curl parameter] {Results of {\tt draw z0\char`\{curl c\char`\}..z1..% @@ -1036,7 +1094,7 @@ draw z1--z2; draw z3--z6; endfig; \end{verbatim} -\quad \mathcenter{\includegraphics{manfig-13}} +\quad \mathcenter{\includegraphics{mpman-13.mps}} $$ \caption[MetaPost code and figure using linear equations] {MetaPost commands and the resulting figure. Point labels have been @@ -1364,7 +1422,7 @@ is written on a piece of graph paper so that the first character occupies $x$~coordinates between zero and one and the next character covers the range $1\le x\le2$, etc. Thus the string \verb|"abcde"| should be thought of like this -$$ \includegraphics{manfig-14} $$ +$$ \includegraphics{mpman-14.mps} $$ and {\tt substring (2,4) of "abcde"} is {\tt "cd"}. This takes a little getting used to but it tends to avoid annoying ``off by one'' errors. @@ -1673,16 +1731,38 @@ the internal variables discussed in this manual are predefined and do not have to be declared at all, but there is a way to declare that a variable should behave like a newly-created internal variable. The declaration is {\tt -newinternal}\index{newinternal?\texttt{newinternal}}\label{Dnewint} -followed by a list of symbolic tokens. For example, -$$ \hbox{\tt newinternal a, b, c;} $$ -causes {\tt a}, {\tt b}, and {\tt c} to behave like internal variables. -Such variables always have known numeric values, and these values can -only be changed by using the assignment\index{assignment} operator -{\tt:=}\index{:=?\texttt{:=}}. Internal variables are initially zero -except that the Plain\index{Plain macros} macro package gives some of -them nonzero initial values. (The Plain macros are normally preloaded -automatically as explained in Section~\ref{intro}.) + newinternal}\index{newinternal?\texttt{newinternal}}\label{Dnewint} +followed by an optional type specifier \texttt{numeric}\index{internal + variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}} +or \texttt{string}\index{internal + variables!\texttt{string}}\index{variables!internal!\texttt{string}} +and a list of symbolic tokens. For example, +$$\begin{verbatim} +newinternal numeric n, m; +newinternal string s, t; +newinternal num; +\end{verbatim} +$$ +are valid declarations that declare three internal numeric variables +\texttt{n}, \texttt{m}, and~\texttt{num} and two internal string +variables \texttt{s} and~\texttt{t}. + +Internal variables always have known values, and these values can only +be changed by using the assignment\index{assignment} operator +{\tt:=}\index{:=?\texttt{:=}}. Internal numeric variables are initially +zero and internal string variables are initially the empty +string~\verb|""|, except that the Plain\index{Plain macros} macro +package gives some of the variables different initial values. (The +Plain macros are normally preloaded automatically as explained in +Section~\ref{intro}.) + +Internal string variables have been introduced in MetaPost +version~1.200. For backwards compatibility, if the type specifier is +missing, internal variables default to a \texttt{numeric}\index{internal + variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}} +type, as in the last example. The declarations \texttt{newinternal + numeric;} and \texttt{newinternal string;} are invalid and throw an +error. \section{Integrating Text and Graphics} @@ -1737,7 +1817,7 @@ label.lft("b", .5[z0,z2]); dotlabel.bot("(0,0)", z0); endfig; \end{verbatim} -\qquad \mathcenter{\includegraphics{manfig-17}} +\qquad \mathcenter{\includegraphics{mpman-17.mps}} $$ \caption{MetaPost code and the resulting output} \label{fig16} @@ -1856,7 +1936,7 @@ label.bot(btex $x$ etex, (2u,0)); label.lft(btex $y$ etex, (0,u)); endfig; \end{verbatim} -\qquad \mathcenter{\includegraphics{manfig-18}} +\qquad \mathcenter{\includegraphics{mpman-18.mps}} $$ \caption{Arbitrary \TeX\ as labels} \label{fig17} @@ -1892,7 +1972,7 @@ label.lft( (120ux, 4uy)); endfig; \end{verbatim} -\qquad \mathcenter{\includegraphics{manfig-19}} +\qquad \mathcenter{\includegraphics{mpman-19.mps}} $$ \caption{\TeX\ labels with display math, and rotated by MetaPost} \label{fig18} @@ -1909,23 +1989,49 @@ For a way to typeset \emph{variable} text as labels, see the \texttt{TEX} utility routine described on p.\ \pageref{dTEX}. Here is how \TeX\ material gets translated into a form MetaPost -understands: The MetaPost processor skips over {\tt -btex}\index{btex?\texttt{btex}} \ldots\ {\tt -etex}\index{etex?\texttt{etex}} blocks and depends on a preprocessor to -translate them into low level MetaPost commands. If the main file is -{\tt fig.mp}, the translated \TeX\ material is placed in a file named -{\tt fig.mpx}\index{files!mpx?{\tt mpx}}. This is normally done -silently without any user intervention but it could fail if one of the -{\tt btex} $\ldots$ {\tt etex} blocks contains an erroneous -\TeX\index{TeX?\TeX!errors} command. Then the erroneous \TeX\ input is -saved in the file {\tt mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} -and the error messages appear in {\tt -mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}. - -The preprocessor for \TeX\ labels {\it does\/} understand virtual +understands: MetaPost stores all {\tt btex}\index{btex?\texttt{btex}} +\ldots\ {\tt etex}\index{etex?\texttt{etex}} blocks in a temporary +file and then runs \TeX\ on that file. If the environment variable +\ttindex{MPTEXPRE} is set to the name of an existing file, its content +will be prepended to the output file for processing by \TeX. You can +use this to include \LaTeX\ preambles, for instance. The \ttt{TEX} +macro described on p.\ \pageref{dTEX} provides another way to handle +this. + +Once the \TeX\ run is finished, MetaPost translates the resulting +DVI\index{dvi file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} file into +low level MetaPost commands that are then read instead of the {\tt btex} +\ldots\ {\tt etex} blocks. If the main file is {\tt fig.mp}, the +translated \TeX\ material is placed in a file named {\tt + fig.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt mpx}}. + +The conversion normally runs silently without any user intervention but +it could fail, for instance if one of the {\tt btex} \ldots {\tt etex} +blocks contains an erroneous \TeX\index{TeX?\TeX!errors} command. In +that case, the \TeX\ input is saved in the file {\tt + mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} and the \TeX\ error +messages appear in {\tt + mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}\index{log file?{\tt + log} file}\index{files!log?{\tt log}}. + +The DVI to MetaPost conversion route {\it does\/} understand virtual fonts, so you can use your normal \TeX\ font switching commands inside the label. + +\label{Dmakempx} +In MetaPost versions before 1.100, the \TeX\ label preprocessing was +handled by an external program that was called upon automatically by +MetaPost. On Web2C-based systems, the preprocessor was normally named +\ttindex{makempx}, which called the utility \ttindex{mpto} for the +creation of the \TeX\ input file and the utility \ttindex{dvitomp} for +the conversion to low level MetaPost. In the current MetaPost version, +the work of this program is now done internally. However, if the +environment variable \ttindex{MPXCOMMAND} is set, the whole label +conversion mechanism will be delegated to the command given in that +variable. + + \label{Dverbatimtex} \TeX\ macro definitions or any other auxiliary \TeX\ commands can be enclosed in a {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} @@ -1958,30 +2064,50 @@ Setting \ttt{prologues} can be useful with \TeX, too, not just troff. Here is some explanation: \begin{itemize} -\item When \ttt{prologues} is 0, which is the default, the MetaPost +\item In PostScript output mode, when \ttt{prologues} is 0, which is the default, the MetaPost output files do not have embedded fonts. Fonts in the resulting -output will probably render as Courier\index{Courier} or Times-Roman\index{Times-Roman}. +output will probably render as Courier\index{Courier} or +Times-Roman\index{Times-Roman}. -\item When \ttt{prologues} is 1, the MetaPost output claims to be +In SVG mode, the text will probably render in a generic sans serif font. +There may very well be problems with the encoding of non-ASCII characters: +the font model of SVG is totally different from the model used by MetaPost. + +\item In PostScript output mode, when \ttt{prologues} is 1, the MetaPost output claims to be ``structured PostScript''\index{PostScript!structured} (EPSF\index{EPSF}), but it is not completely conformant. This variant is kept for backward compatibility with old (troff) documents, but its use is deprecated. -For historical reasons, MetaPost sets \ttt{prologues} to~1 when the {\tt --troff} option is given on the command line. +MetaPost sets \ttt{prologues} to~1 when the {\tt -troff} option is given +on the command line. + +A \ttt{prologues:=1} setting is currently ignored in SVG output +mode. The value is reserved for future use (possibly for mapping to +\ttt{font-family}, \ttt{font-weight}, etc. properties). -\item When \ttt{prologues} is 2, the MetaPost output is EPSF and assumes +\item In PostScript output mode, when \ttt{prologues} is 2, the +MetaPost output is EPSF and assumes that the text comes from PostScript\index{PostScript!fonts} fonts provided by the ``environment'', such as the document viewer or embedded application using the output. MetaPost will attempt to set up the font encodings correctly, based on \ttt{fontmapfile} and \ttt{fontmapline} commands. -\item When \ttt{prologues} is 3, the MetaPost output will be EPSF but +A \ttt{prologues:=2} setting is currently ignored in SVG output mode. +The value is reserved for future use (possibly for external +\ttt{font-face} definitions). + +\item In PostScript output mode, when \ttt{prologues} is 3, the MetaPost output will be EPSF but will contain the PostScript font(s) (or a subset) used based on the \ttt{fontmapfile} and \ttt{fontmapline} commands. This value is useful for generating stand-alone PostScript graphics. + +In SVG mode, the font glyphs are converted to path definitions that +are included at the top of the output file. This method is currently +the only reliable way to export text objects to SVG. + \end{itemize} + It is worth noting that the default value \ttt{prologues:=0} is sufficient for graphics included in \TeX-based documents. Also, the \ttt{prologues} variable is irrelevant when processing MetaPost files through the \ttindex{mptopdf} utility @@ -1994,25 +2120,15 @@ handle those. The details on how to include PostScript figures in a paper done in \TeX\ or troff are system-dependent. They can generally be found in manual pages and other on-line documentation, but have a look at -section~\ref{Dteximport} of this manual for some brief instructions that +section~\ref{teximport} of this manual for some brief instructions that in many cases should work. The manual for the widely-used Dvips processor is in a file \ttt{dvips.texi}, included in most distributions, and is available online at \url{http://tug.org/texinfohtml/dvips.html}, among many other places and formats. -\label{Dmakempx} -On Web2C-based systems, the preprocessor is named \ttindex{makempx}, -which calls another utility \ttindex{mpto}; the Web2C documentation -describes them in more detail. We'll mention one feature here, though: -if the environment variable \ttindex{MPTEXPRE} is set to the name of an -existing file, {\tt makempx} will prepend it to the output. You can use -this to include \LaTeX\ preambles, for instance. The \ttt{TEX} -macro described on p.\ \pageref{dTEX} provides another way to handle this. - - \subsection{Font map files} -\label{Sfontmapfile}\label{Sfontmapline} +\label{fontmap} If \ttt{prologues} is set to~2, any used fonts in the output file are automatically re-encoded, and the encoding vector file specified in @@ -2021,11 +2137,12 @@ the fontmap entry will be embedded in the output file. If (a subset of) the used PostScript\index{PostScript!fonts} fonts. For this to work, it needs to acquire font map information. -The code is based on the font library used by pdf\TeX. Following in -the footsteps of pdf\TeX, there are two new associated primitives: -\ttindex{fontmapfile} and \ttindex{fontmapline}. Here is a simple -example, specifying the map file for Latin Modern fonts in YandY -(\LaTeX\ LY1) encoding: +The code is based on the font library used by pdf\TeX. Following in the +footsteps of pdf\TeX, there are two new associated primitives: +\ttindex{fontmapfile}\label{Dfontmapfile} and +\ttindex{fontmapline}\label{Dfontmapline}. Here is a simple example, +specifying the map file for Latin Modern fonts in YandY (\LaTeX\ LY1) +encoding: \begin{center}\begin{tabular}{l} \verb|prologues:=2;|\\ \verb|fontmapfile "texnansi-lm.map";|\\ @@ -2142,7 +2259,7 @@ variables}\index{variables!internal} {\tt bboxmargin}\index{bboxmargin?\texttt{bboxmargin}}\label{Dbbmargin}. \begin{figure}[htp] -$$ \includegraphics{manfig-20} $$ +$$ \includegraphics{mpman-20.mps} $$ \caption{A bounding box and its corner points.} \label{bbox} \end{figure} @@ -2192,7 +2309,9 @@ example, the {\tt fill} statement in Figure~\ref{fig20} builds a closed path by extending the roughly semicircular path~{\tt p}. This path has a counter-clockwise orientation, but that does not matter because the {\tt fill} statement uses PostScript's\index{PostScript} non-zero -winding\index{winding number} number rule~\cite{ad:red2}. +winding\index{winding number} number rule\index{non-zero fill + rule}\index{fill rule!non-zero}\index{PostScript!fill + rule}~\cite{ad:red2}. \begin{figure}[htp] $$ \begin{verbatim} @@ -2203,7 +2322,7 @@ fill p{up}..(0,0){-1,-2}..{up}cycle; draw p..(0,1cm)..cycle; endfig; \end{verbatim} -\qquad \mathcenter{\includegraphics{manfig-21}} +\qquad \mathcenter{\includegraphics{mpman-21.mps}} $$ \caption{MetaPost code and the corresponding output.} \label{fig20} @@ -2252,8 +2371,8 @@ this model means that MetaPost will not write a color selection statement to the PostScript output file for this object. The `current default' color model can be set up using the internal -variable \ttindex{defaultcolormodel}. Table~\ref{dfltcmod} lists the -valid values. +variable \ttindex{defaultcolormodel}\label{Ddefaultcolormodel}. +Table~\ref{dfltcmod} lists the valid values. \begin{table} \centering \begin{tabular}{|c|l|} @@ -2305,7 +2424,7 @@ label.lft(btex $U$ etex, (-1cm,.5cm)); draw bbox currentpicture; endfig; \end{verbatim} -\qquad \mathcenter{\includegraphics{manfig-22}} +\qquad \mathcenter{\includegraphics{mpman-22.mps}} $$ \caption{MetaPost code and the corresponding output.} \index{fullcircle?\texttt{fullcircle}}\index{halfcircle?\texttt{halfcircle}}\index{buildcycle?\texttt{buildcycle}} @@ -2369,8 +2488,8 @@ little confusing. \begin{figure}[htp] -$$ {\includegraphics{manfig-123} \atop (a)} - \qquad {\includegraphics{manfig-223} \atop (b)} +$$ {\includegraphics{mpman-123.mps} \atop (a)} + \qquad {\includegraphics{mpman-223.mps} \atop (b)} $$ \caption[A demonstration of cycle building] {(a)~The semicircular path~{\tt aa} @@ -2417,7 +2536,7 @@ dotlabel.lft(btex $R$ etex, p4 intersectionpoint q1.5); dotlabel.bot(btex $S$ etex, p4 intersectionpoint q0.5); endfig; \end{verbatim} -\atop \mathcenter{\includegraphics{manfig-24}} +\atop \mathcenter{\includegraphics{mpman-24.mps}} $$ \caption{MetaPost code and the corresponding output.} \label{fig23} @@ -2490,7 +2609,7 @@ there are no integers between $t_a$ and $t'_a$\index{intersection}. (For more details, see {\sl The \MF book} \cite[Chapter 14]{kn:c}). \begin{figure}[htp] -$$ \includegraphics{manfig-25} $$ +$$ \includegraphics{mpman-25.mps} $$ \caption{Two intersecting paths with time values marked on each path.} \label{fig24} \end{figure} @@ -2591,7 +2710,7 @@ pickup pencircle scaled 1pt; draw fun; endfig; \end{verbatim} -\atop \includegraphics{manfig-26} +\atop \includegraphics{mpman-26.mps} $$ \caption{MetaPost code and the resulting figure} \label{fig25} @@ -2809,7 +2928,7 @@ endfor dotlabels.top(1,2,3); dotlabels.bot(4); endfig; \end{verbatim} -\quad \mathcenter{\includegraphics{manfig-28}} +\quad \mathcenter{\includegraphics{mpman-28.mps}} $$ \caption{MetaPost code and the resulting ``fractal'' figure} \label{fig27} @@ -2837,7 +2956,7 @@ can be scaled\index{scaled?\texttt{scaled}} as shown in Figure~\ref{fig28}. \begin{figure}[htp] -$$ \includegraphics{manfig-29} $$ +$$ \includegraphics{mpman-29.mps} $$ \caption[Dashed lines and the corresponding dash patters] {Dashed lines each labeled with the \tdescr{dash pattern} used to create it.} @@ -2854,7 +2973,7 @@ $y$~axis is laid out along the path to be dashed\index{dash pattern?\tdescr{dash pattern}}. \begin{figure}[htp] -$$ \includegraphics{manfig-30} $$ +$$ \includegraphics{mpman-30.mps} $$ \caption[Dashed lines and the corresponding dash patters] {Dashed lines and the MetaPost statements for drawing them where {\tt e4} refers to the dash pattern {\tt evenly scaled 4}.} @@ -2897,7 +3016,7 @@ $$ \hbox{\tt dashpattern(on 6bp off 12bp on 6bp)}, $$ then {\tt llcorner d} is $(0,24)$ and {\tt urcorner d} is $(24,24)$. Drawing {\tt d} directly without using it as a dash pattern produces two thin horizontal line segments like this: -$$ \includegraphics{manfig-31} $$ +$$ \includegraphics{mpman-31.mps} $$ The lines in this example are specified as having width zero, but this does not matter because the line width is ignored when a picture is used as a dash pattern. @@ -2939,7 +3058,7 @@ currentpicture:=nullpicture; draw fullcircle scaled 1cm xscaled 3 dashed p; endfig; \end{verbatim} -\quad \mathcenter{\includegraphics{manfig-32}} +\quad \mathcenter{\includegraphics{mpman-32.mps}} $$ \caption{MetaPost code for dashed patterns and the corresponding output} \label{fig32} @@ -3019,7 +3138,7 @@ dotlabels.top(0,1,2,3,4,5); endfig; linecap:=rounded; \end{verbatim} \qquad -\mathcenter{\includegraphics{manfig-33}} +\mathcenter{\includegraphics{mpman-33.mps}} $$ \caption{MetaPost code and the corresponding output} \label{fig33} @@ -3052,7 +3171,7 @@ dotlabels.bot(0,1,2,3,4,5,6,7,8); endfig; linejoin:=rounded; \end{verbatim} \qquad -\mathcenter{\includegraphics{manfig-34}} +\mathcenter{\includegraphics{mpman-34.mps}} $$ \caption{MetaPost code and the corresponding output} \label{fig34} @@ -3069,7 +3188,7 @@ default value of 10.0 and line joins revert to beveled when the ratio of miter length to line width reaches this value. \begin{figure}[htp] -$$ \includegraphics{manfig-35} $$ +$$ \includegraphics{mpman-35.mps} $$ \caption{The miter length and line width whose ratio is limited by {\tt miterlimit}.} \label{fig35} @@ -3084,7 +3203,7 @@ width and is quite subtle at the default line width of 0.5bp as shown in Figure~\ref{fig36}. \begin{figure}[htp] -$$\includegraphics{manfig-36}$$ +$$\includegraphics{mpman-36.mps}$$ \caption{Three ways of drawing arrows.} \label{fig36} \end{figure} @@ -3120,7 +3239,7 @@ parameter that controls the angle at the tip of the arrowhead. The default value of this angle is 45 degrees as shown in the figure. \begin{figure}[htp] -$$ \includegraphics{manfig-37} $$ +$$ \includegraphics{mpman-37.mps} $$ \caption[A large arrowhead with key parameters labeled.] {A large arrowhead with key parameters labeled and paths used to draw it marked with white lines.} @@ -3234,7 +3353,7 @@ draw z0--z1--z2--z3--z4--z5--z6 withcolor .7white; dotlabels.top(0,1,2,3,4,5,6); endfig; \end{verbatim} -\quad \mathcenter{\includegraphics{manfig-38}} +\quad \mathcenter{\includegraphics{mpman-38.mps}} $$ \caption{MetaPost code and the resulting ``calligraphic'' figure.} \label{fig38}\index{lft?\texttt{lft}}\index{bot?\texttt{bot}}\index{top?\texttt{top}} @@ -3412,7 +3531,7 @@ draw p3; endfig; \end{verbatim} \qquad -\mathcenter{\includegraphics{manfig-40}} +\mathcenter{\includegraphics{mpman-40.mps}} $$ \caption{MetaPost code and the resulting ``clipped'' figure.} \label{fig40} @@ -3424,8 +3543,8 @@ statement\index{shipout?\texttt{shipout}}\label{Dship} $$ {\tt shipout}\, \descr{picture expression} $$ writes out a picture as a PostScript\index{PostScript} file whose file name is determined by -{\tt filenametemplate}\index{filenametemplate?\texttt{filenametemplate}} -(see section~\ref{Dfilenametemplate}). By default, the file name ends +{\tt outputtemplate}\index{outputtemplate?\texttt{outputtemplate}} +(see section~\ref{outputfilenames}). By default, the file name ends {\tt.}{\it nnn}, where {\tt nnn} is the decimal representation of the value of the internal variable\index{internal variables}\index{variables!internal} {\tt @@ -3456,7 +3575,7 @@ corresponding output, without affecting {\tt currentpicture}. As an example, in the code of figure~\ref{fig55} an object \ttt{wheel} has been defined that saves the output of two \ttt{draw} operations as follows: \begin{figure}[b] -$$ \includegraphics{manfig-55} $$ +$$ \includegraphics{mpman-55.mps} $$ \caption{Copying objects with the \ttt{image} operator.} \label{fig55} \end{figure} @@ -3662,6 +3781,202 @@ To summarize the discussion of mismatching part operators: \index{greypart?\texttt{greypart}|)} +\subsection{Decomposing the glyphs of a font} +\label{glyphs} + +MetaPost provides a primitive to convert a glyph of a font in the Adobe +Type~1 Font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe + Type~1 Font}\index{font!Adobe Type~1} format into its constituent +filled paths---the strokes---and store them in a picture variable. A +glyph\index{font!glyph} is the visual representation of a character in a +font. A character\index{character}\index{font!character} is a certain +slot\index{slot} (index) in a font with an associated meaning, e.g., the +capital letter~``M'' or the exclamation mark. The meaning of a slot is +defined by the font encoding\index{encoding}\index{font!encoding}. In +general, the same character is represented by different glyphs in +different fonts. Figure~\ref{glyphsample} shows some glyphs for the +character at slot~103 in the T1 encoding, i.e., the lower-case +letter~``g''. All glyphs are at the same nominal size. Note, how +glyphs may extend beyond their bounding box. +\begin{figure}[htp] + \centering + \setlength{\fboxsep}{0pt} + \setlength{\fboxrule}{.125pt} + \fontsize{56pt}{56pt}\selectfont + \newcommand*{\showglyph}[4]{% a glyph with its bounding box + \fbox{\usefont{#1}{#2}{#3}{#4}g}% + } + \makebox[0pt][c]{% base line + \rule{.7\textwidth}{.125pt}% + }% + \makebox[0pt][c]{% glyphs + \showglyph{T1}{lmr}{m}{n}\hspace{.3em} + \showglyph{T1}{qag}{m}{n}\hspace{.3em} + \showglyph{T1}{qpl}{m}{it}\hspace{.3em} + \showglyph{T1}{qzc}{m}{it}% + } + \caption{Different glyphs representing the same character.} + \label{glyphsample} +\end{figure} + +The glyphs of an Adobe Type~1 font +\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1} are composed of two types of contours: +Clockwise oriented contours add to the shape of a glyph and are filled +with black ink. Counter-clockwise oriented contours +erase\index{erasing} parts of other contours, i.e., make them +transparent again. To save the contours of a glyph in a picture, the +\verb|glyph|\index{glyph?\texttt{glyph}}\label{Dglyph} operator can be +used. There are two ways to identify a glyph in a font: +\begin{eqnarray*} + & \verb|glyph|\, \descr{numeric expression}\, \verb|of|\, + \descr{string expression}\\ + \noalign{\hbox{and}} + & \verb|glyph|\, \descr{string expression}\, \verb|of|\, + \descr{string expression}\rlap{\quad\mbox{.}} +\end{eqnarray*} + +If the first argument is a numeric expression, it has to be a slot +number between 0 and~255. Fractional slot numbers are rounded to the +nearest integer value. Slot numbers outside the allowed range trigger +an error. If the first argument is string, it has to be a CharString +name\index{CharString name} in the PostScript font's source file. A +CharString name is a unique text label for a glyph in a PostScript font +(a font encoding actually maps CharStrings to slots). This second +syntax can be used to address glyphs without having to think about font +encodings. The second argument to the \verb|glyph| operator is a string +containing a font name (section~\ref{text} has more on font names). + +The \verb|glyph| operator looks-up the font name in the font map to +determine the encoding and to find the font's PostScript source file. +It returns a picture consisting of the glyph's contour lines, explicitly +filled black and white in the greyscale color model according to the +rules laid out above. Additionally, the contours are sorted, such that +all black contours are drawn before white contours. The filling and +sorting is necessary for the picture to resembles the corresponding +glyph visually\footnote{Plain contours already carry enough information + to completely reconstruct a glyph, the orientation of a contour can be + computed from its cardinal and control points. MetaPost has a + \texttt{turningnumber}\index{turningnumber?\texttt{turningnumber}}\label{Dturningnumber} + primitive to do that.}, since Adobe Type~1 +fonts\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1} use a generalized variant of the +non-zero winding number fill rule\index{non-zero fill rule}\index{fill + rule!non-zero}\index{PostScript!fill rule}, that MetaPost doesn't +implement (MetaPost cannot handle non-contiguous paths). As a side +effect, the interiors of the erasing\index{erasing} contours are an +opaque white in the returned picture, while they were transparent in the +original glyph. One can think of erasing contours to be unfilled (see +p.~\pageref{Dunfill}). For instance, the following code saves the +contours of the lower case letter~``g'', bound to slot~103 in the OT1 +encoding\index{OT1 encoding}\index{encoding!OT1}, in the Computer Modern +Roman\index{Computer Modern Roman} font in a picture variable: + +$$\begin{verbatim} +fontmapline "cmr10 CMR10 <cmr10.pfb"; +picture g; +g := glyph 103 of "cmr10"; +\end{verbatim} +$$ + +The \verb|glyph| operator returns an empty picture, if the +\texttt{.tfm}\index{tfm file?{\tt tfm} file}\index{files!tfm?{\tt tfm}} +or \texttt{.pfb}\index{pfb file?{\tt pfb} file}\index{files!pfb?{\tt + pfb}} file cannot be found, if the encoding given in the font map +cannot be found or the slot number is not covered by the encoding or if +the CharString name cannot be found. Note, while MetaPost delegates the +actual font handling to a rendering application for \verb|infont| and +\verb|btex| \ldots\ \verb|etex| blocks, the \verb|glyph| operator +directly operates on font ressources. For that reason, a font map entry +is mandatory for the font in question, given either by +\verb|fontmapline| or \verb|fontmapfile| (see +section~\ref{Dfontmapline}). + +In Figure~\ref{fig56}, the contours of the upper case letter~``\v{D}'' +in the Latin Modern Roman\index{Latin Modern Roman} font are saved in a +picture variable. The glyph is identified by its CharString name +``Dcaron''\index{Dcaron}. The code then iterates over all contours and +draws them together with their cardinal (black) and control points +(red). As it turns out, many of the control points coincide with +cardinal points in this glyph. + +\begin{figure}[htb] +$$\begin{verbatim} +fontmapfile "=lm-ec.map"; +beginfig(56); + picture q; + path p; + interim ahlength := 12bp; + interim ahangle := 25; + q := glyph "Dcaron" of "ec-lmr10" scaled .2; + for item within q: + p := pathpart item; + drawarrow p withcolor (.6,.9,.6) + withpen pencircle scaled 1.5; + for j=0 upto length p: + pickup pencircle scaled .7; + draw (point j of p -- precontrol j of p) + dashed evenly withcolor blue; + draw (point j of p -- postcontrol j of p) + dashed evenly withcolor blue; + pickup pencircle scaled 3; + draw precontrol j of p withcolor red; + draw postcontrol j of p withcolor red; + pickup pencircle scaled 2; + draw point j of p withcolor black; + endfor + endfor +endfig; +\end{verbatim} +\qquad +\mathcenter{\includegraphics{mpman-56.mps}} +$$ +\caption{Iterating over the contours of a glyph} +\label{fig56} +\end{figure} + +The contours in a picture returned by the \verb|glyph| operator are no +raw copies of the contours found in the font sources, but the +\verb|glyph| operator applies a number of transformations to them. +First, the direction of all contours is reversed, so that contours +filled black become counter-clockwise oriented (mathematically positive) +and contours filled white become clockwise oriented (mathematically +negative). Second, in an Adobe Type~1 +font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1}, contours are in general closed by +repeating the starting point before applying the \verb|closepath| +operator\index{PostScript!\texttt{closepath} operator}. The MetaPost +representation of such a path would be: +$$ +z_0\verb|..|\mbox{\itshape controls}\verb|..|z_1\verb|..| \cdots +\verb|..|z_n\verb|..|\mbox{\itshape controls}\verb|..|z_0\verb|--cycle| +$$ +A more natural MetaPost representation of this path would be: +$$ +z_0\verb|..|\mbox{\itshape controls}\verb|..|z_1\verb|..| \cdots +\verb|..|z_n\verb|..|\mbox{\itshape controls}\verb|..cycle| +$$ +The \verb|glyph| operator transforms all paths into the latter +representation, i.e., the last point is removed, whenever it matches the +starting point. Finally, the picture returned by the \verb|glyph| +operator is scaled such that one font design unit\index{font!design + unit} equals one PostScript +point\index{point!PostScript}\index{PostScript!point} (bp). A usual +font design unit is a thousandth part of the font design +size\index{font!design size}. The returned picture will therefore +typically have a height of around 1000\,bp. + +Converting a text into plain curves is part of a process oftentimes +called ``flattening\index{flattening} a document.'' When flattening +text, all hinting information in fonts are lost. Hinting information +aid a rendering application in aligning certain parts of a glyph on a +low-resolution output device. A flattened text may therefore look +distorted on screen. In SVG output, all text is automatically +flattened, when the internal variable +\verb|prologues|\index{prologues?\texttt{prologues}} is set to~3 (see +section~\ref{Dprologues}). + + \section{Macros} \label{macros} @@ -3810,7 +4125,7 @@ internal variable\index{internal variables}\index{variables!internal} gives it a new value without forgetting that {\tt linecap} is an internal variable. The general syntax is $$ {\tt interim}\, \descr{internal variable} \mathrel{\hbox{\tt:=}} - \descr{numeric expression} + \descr{numeric expression} \;|\; \descr{string expression} $$ @@ -3934,7 +4249,7 @@ mark_rt_angle(z.p, z0, a); mark_rt_angle(z.p, z1, b); endfig; \end{verbatim} -\quad \mathcenter{\includegraphics{manfig-42}} +\quad \mathcenter{\includegraphics{mpman-42.mps}} $$ \caption{MetaPost code and the corresponding figure} \label{fig42} @@ -4129,7 +4444,7 @@ for i=0 upto 3: endfor endfig; \end{verbatim} -\quad \mathcenter{\includegraphics{manfig-45}} +\quad \mathcenter{\includegraphics{mpman-45.mps}} $$ \caption{MetaPost code and the corresponding figure} \label{fig45} @@ -4720,7 +5035,8 @@ or just a one-off run. writes a proof sheet for MetaPost output. Call it like this: $$\hbox{\tt tex mproof {\sl MetaPost-output-filename}}$$ -Then process the resulting \texttt{dvi} file as usual. +Then process the resulting \texttt{.dvi}\index{dvi file?{\tt dvi} + file}\index{files!dvi?{\tt dvi}} file as usual. \section{Debugging} @@ -4785,12 +5101,35 @@ Among the possible responses to a {\tt ?} prompt are the following: {\tt ?} prompt. \end{description} +This interactive mode is not only entered when MetaPost finds an error +in the code. It can be explicitly entered by the \ttindex{errmessage} +command. The \ttindex{message}\label{Dmessage} command writes a string +argument to a new line on the terminal. The +\ttindex{errmessage}\label{Derrmessage} command is similar, but the +string argument is preceded by \verb|"! "| and followed by~\verb|"."|. +Additionally, some lines of context are appended as in MetaPost's normal +error messages. If the user now types ``h'', the most recent +\ttindex{errhelp}\label{Derrhelp} string will be shown (unless it was +empty). + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{message command} \rightarrow errhelp \descr{string expression}$\\ +$\tt \qquad \;|\; errmessage \descr{string expression}$\\ +$\tt \qquad \;|\; message \descr{string expression}$ +\end{ctabbing} +\caption{The syntax for message commands} +\label{symsg} +\end{figure} + Error messages and responses to {\tt show} commands are also written into the transcript\index{files!transcript} file whose name is obtained -from the name of the main input file by changing ``{\tt .mp}'' to ``{\tt -.log}''. When the internal variable\index{internal -variables}\index{variables!internal} {\tt -tracingonline}\index{tracingonline?\texttt{tracingonline}} is at its +from the name of the main input file by changing ``{\tt .mp}''\index{mp + file?{\tt mp} file}\index{files!mp?{\tt mp}} to ``{\tt + .log}''\index{log file?{\tt log} file}\index{files!log?{\tt + log}}. When the internal variable\index{internal + variables}\index{variables!internal} {\tt + tracingonline}\index{tracingonline?\texttt{tracingonline}} is at its default value of zero, some {\tt show} commands print their results in full detail only in the transcript file. @@ -4903,1047 +5242,8 @@ treatment of included \TeX\ material. \appendix -\section{Reference Manual} - -\let\svtopfrac=\topfraction % prepare to restore values at end of this appendix -\let\svtxtfrac=\textfraction % grouping would fail because \setcounter is global -\newcounter{svtopnum} -\newcounter{svtotnum} -\setcounter{svtopnum}{\value{topnumber}} -\setcounter{svtotnum}{\value{totalnumber}} - -\renewcommand\topfraction{1.0} % set values to allow *lots* of figures and tables -\renewcommand\textfraction{0.0} -\setcounter{topnumber}{10} -\setcounter{totalnumber}{10} - -Tables \ref{ivartab}--\ref{pseudotab} summarize the built-in features of -Plain MetaPost. Features from the Plain\index{Plain macros} macro -package are marked by \pl\ symbols. The distinction between primitives -and plain macros can be ignored by the casual user. - -The tables in this appendix give the name of each feature, the page -number where it is explained, and a short description. A few features -are not explained elsewhere and have no page number listed. These -features exist primarily for compatibility with \MF\index{metafont?\MF} -and are intended to be self-explanatory. Certain other features from -\MF\ are omitted entirely because they are of limited interest to the -MetaPost users and/or would require long explanations. All of these are -documented in {\sl The \MF book} \cite{kn:c} as explained in -Appendix~\ref{MPvsMF}. - -Table~\ref{ivartab} lists internal variables that take on numeric values. -Table~\ref{pvartab} lists predefined variables of other types. -Table~\ref{consttab} lists predefined constants. Some of these are implemented -as variables whose values are intended to be left unchanged. - -Table~\ref{optab} summarizes MetaPost operators and lists -the possible argument and result types for each one. A ``--'' entry for -the left argument indicates a unary operator; ``--'' entries for both -arguments indicate a nullary operator. Operators that take suffix -parameters are not listed in this table because they are treated as -``function-like macros''. - -The last two tables are Table~\ref{cmdtab} for commands and -Table~\ref{pseudotab} macros that behave like functions or procedures. -Such macros take parenthesized argument lists and/or suffix parameters, -returning either a value whose type is listed in the table, or nothing. -The latter case is for macros that behave like procedures. Their return -values are listed as ``--''. - -The figures in this appendix present the syntax of the MetaPost language -starting with expressions in Figures \ref{syexpr1}--\ref{sypseudo}. -Although the productions sometimes specify types for expressions, primaries, -secondaries, and tertiaries, no attempt is made to give separate syntaxes -for \tdescr{numeric expression}, \tdescr{pair expression}, etc. -The simplicity of the productions in Figure~\ref{sytypexpr} is due to this -lack of type information. Type information -can be found in Tables \ref{ivartab}--\ref{pseudotab}. - -Figures \ref{syprog} and \ref{sycmds} give the syntax for MetaPost programs, -including statements and commands. They do not mention loops\index{loops} -and {\tt if}\index{if?\texttt{if}} -tests because these constructions do not behave like statements. The syntax -given in Figures \ref{syexpr1}--\ref{sycondloop} applies to the result of -expanding all conditionals and loops. Conditionals and loops do have a -syntax, but they deal with almost arbitrary sequences of tokens. -Figure~\ref{sycondloop} specifies conditionals in terms of -\tdescr{balanced tokens} and loops in terms of \tdescr{loop text}, where -\tdescr{balanced tokens} is any sequence of tokens balanced with respect -to {\tt if} and {\tt fi}, and \tdescr{loop text} is a sequence of tokens -balanced with respect to {\tt for}, {\tt forsuffixes}, {\tt forever}, -and {\tt endfor}. - -\begin{table}[htp] -\caption{Internal variables with numeric values} -$$\begin{tabular}{|l|r|l|} -\hline -\multicolumn1{|c}{Name}& \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\ -\hline -\hline -\pl\tt ahangle& \pageref{Dahangle}& - angle for arrowheads in degrees (default: 45)\\\hline -\pl\tt ahlength& \pageref{Dahlength}& - size of arrowheads (default: 4{\tt bp})\\\hline -\pl\tt bboxmargin& \pageref{Dbbmargin}& - extra space allowed by {\tt bbox} (default 2{\tt bp})\\\hline -\tt charcode& \pageref{Dcharcode}& - the number of the current figure\\\hline -\tt day& --& - the current day of the month\\\hline -\tt defaultcolormodel& --& - the initial color model (default: 5, rgb)\\\hline -\pl\tt defaultpen& \pageref{Ddefaultpen}& - numeric index used by {\tt pickup} to select default pen\\\hline -\pl\tt defaultscale& \pageref{Ddfscale}& - font scale factor for label strings (default 1)\\\hline -\pl\tt labeloffset& \pageref{Dlaboff}& - offset distance for labels (default 3{\tt bp})\\\hline -\tt linecap& \pageref{Dlinecap}& - 0 for butt, 1 for round, 2 for square\\\hline -\tt linejoin& \pageref{Dlinejoin}& - 0 for mitered, 1 for round, 2 for beveled\\\hline -\tt miterlimit& \pageref{Dmiterlim}& - controls miter length as in PostScript\\\hline -\tt month& --& - the current month (e.g, 3 $\equiv$ March)\\\hline -\tt mpprocset& --& - \vtop{\hbox{set this to~1 if you want to include a PostScript -dictionary}\hbox{of abbreviations in the output}}\\\hline -\tt pausing& --& - ${}>0$ to display lines on the terminal before they are read\\\hline -\tt prologues& \pageref{Dprologues}& - ${}>0$ to output conforming PostScript using built-in fonts\\\hline -\tt restoreclipcolor& --& - restore the graphics state after clip operations (default: 1)\\\hline -\tt showstopping& --& - ${}>0$ to stop after each {\tt show} command\\\hline -\tt time& --& - the number of minutes past midnight when this job started\\\hline -\tt tracingcapsules& \pageref{Dtcapsules}& - ${}>0$ to show capsules too\\\hline -\tt tracingchoices& \pageref{Dtchoices}& - ${}>0$ to show the control points chosen for paths\\\hline -\tt tracingcommands& \pageref{Dtcommands}& - ${}>0$ to show commands and operations as they are performed\\\hline -\tt tracingequations& \pageref{Dtequations}& - ${}>0$ to show each variable when it becomes known\\\hline -\tt tracinglostchars& \pageref{Dtlostchars}& - ${}>0$ to show characters that aren't {\tt infont}\\\hline -\tt tracingmacros& \pageref{Dtmacros}& - ${}>0$ to show macros before they are expanded\\\hline -\tt tracingonline& \pageref{Dtonline}& - ${}>0$ to show long diagnostics on the terminal\\\hline -\tt tracingoutput& \pageref{Dtoutput}& - ${}>0$ to show digitized edges as they are output\\\hline -\tt tracingrestores& \pageref{Dtrestores}& - ${}>0$ to show when a variable or internal is restored\\\hline -\tt tracingspecs& \pageref{Dtspecs}& - ${}>0$ to show path subdivision when using a polygonal a pen\\\hline -\tt tracingstats& \pageref{Dtstats}& - ${}>0$ to show memory usage at end of job\\\hline -\tt tracingtitles& --& - ${}>0$ to show titles online when they appear\\\hline -\tt troffmode& \pageref{Dtroffmode}& - set to~1 if a {\tt -troff} or {\tt -T} option was given\\\hline -\tt truecorners& \pageref{Dtruecorn}& - ${}>0$ to make {\tt llcorner} etc. ignore {\tt setbounds}\\\hline -\tt warningcheck& \pageref{Dwarncheck}& - controls error message when variable value is large\\\hline -\tt year& --& - the current year (e.g., 1992)\\\hline -\end{tabular} -$$ -\label{ivartab}% -\index{day?\texttt{day}}\index{month?\texttt{month}}\index{pausing?\texttt{pausing}}\index{showstopping?\texttt{showstopping}}% -\index{time?\texttt{time}}\index{tracingtitles?\texttt{tracingtitles}}\index{year?\texttt{year}} -\end{table} - - -\begin{table}[htp] -\caption{Other Predefined Variables} -$$\begin{tabular}{|l|l|r|l|} -\hline -\multicolumn1{|c}{Name}& \multicolumn1{|c}{Type}& \multicolumn1{|c}{Page}& - \multicolumn1{|c|}{Explanation}\\ -\hline -\hline -\pl\tt background& color& \pageref{Dbground}& - Color for {\tt unfill} and {\tt undraw} (usually white)\\\hline -\pl\tt currentpen& pen& \pageref{Dcurpen}& - Last pen picked up (for use by the {\tt draw} command)\\\hline -\pl\tt currentpicture& picture& \pageref{Dcurpic}& - Accumulate results of {\tt draw} and {\tt fill} commands\\\hline -\pl\tt cuttings& path& \pageref{Dcuttings}& - subpath cut off by last {\tt cutbefore} or {\tt cutafter}\\\hline -\pl\tt defaultfont& string& \pageref{Ddffont}& - Font used by label commands for typesetting strings\\\hline -\pl\tt extra\_beginfig& string& \pageref{Dxbfig}& - Commands for {\tt beginfig} to scan\\\hline -\pl\tt extra\_endfig& string& \pageref{Dxefig}& - Commands for {\tt endfig} to scan\\\hline -\end{tabular} -$$ -\label{pvartab} -\end{table} - - -\begin{table}[htp] -\caption{Predefined Constants} -$$\begin{tabular}{|l|l|r|l|} -\hline -\multicolumn1{|c}{Name}& \multicolumn1{|c}{Type}& \multicolumn1{|c}{Page}& - \multicolumn1{|c|}{Explanation}\\ -\hline -\hline -\pl\tt beveled& numeric& \pageref{Dbvled}& - {\tt linejoin} value for beveled joins [2]\\\hline -\pl\tt black& color& \pageref{Dblack}& - Equivalent to {\tt (0,0,0)}\\\hline -\pl\tt blue& color& \pageref{Dblue}& - Equivalent to {\tt (0,0,1)}\\\hline -\pl\tt bp& numeric& \pageref{Dbp}& - One PostScript point in {\tt bp} units [1]\\\hline -\pl\tt butt& numeric& \pageref{Dbutt}& - {\tt linecap} value for butt end caps [0]\\\hline -\pl\tt cc& numeric& --& - One cicero in {\tt bp} units [12.79213]\\\hline -\pl\tt cm& numeric& \pageref{Dcm}& - One centimeter in {\tt bp} units [28.34645]\\\hline -\pl\tt dd& numeric& --& - One didot point in {\tt bp} units [1.06601]\\\hline -\pl\tt ditto& string& --& - The {\tt "} character as a string of length 1\\\hline -\pl\tt down& pair& \pageref{Ddown}& - Downward direction vector $(0,-1)$\\\hline -\pl\tt epsilon& numeric& --& - Smallest positive MetaPost number [$1\over65536$]\\\hline -\pl\tt evenly& picture& \pageref{Devenly}& - Dash pattern for equal length dashes\\\hline -\pl\tt EOF& string& \pageref{Deof}& - Single null character\\\hline -\tt false& boolean& \pageref{Dfalse}& - The boolean value {\it false\/}\\\hline -\pl\tt fullcircle& path& \pageref{Dfcirc}& - Circle of diameter 1 centered on $(0,0)$\\\hline -\pl\tt green& color& \pageref{Dgreen}& - Equivalent to {\tt (0,1,0)}\\\hline -\pl\tt halfcircle& path& \pageref{Dhcirc}& - Upper half of a circle of diameter 1\\\hline -\pl\tt identity& transform& \pageref{Dident}& - Identity transformation\\\hline -\pl\tt in& numeric& \pageref{Din}& - One inch in {\tt bp} units [72]\\\hline -\pl\tt infinity& numeric& \pageref{Dinf}& - Large positive value [4095.99998]\\\hline -\pl\tt left& pair& \pageref{Dleft}& - Leftward direction $(-1,0)$\\\hline -\pl\tt mitered& numeric& \pageref{Dmitred}& - {\tt linejoin} value for mitered joins [0]\\\hline -\pl\tt mm& numeric& \pageref{Dmm}& - One millimeter in {\tt bp} units [2.83464]\\\hline -\tt mpversion& string& \pageref{Dmpversion}& - MetaPost version number\\\hline -\tt nullpen& pen& \pageref{Dnlpen}& - Empty pen\\\hline -\tt nullpicture& picture& \pageref{Dnlpic}& - Empty picture\\\hline -\pl\tt origin& pair& --& - The pair $(0,0)$\\\hline -\pl\tt pc& numeric& --& - One pica in {\tt bp} units [11.95517]\\\hline -\tt pencircle& pen& \pageref{Dpncirc}& - Circular pen of diameter 1\\\hline -\pl\tt pensquare& pen& \pageref{Dpnsqr}& - square pen of height 1 and width 1\\\hline -\pl\tt pt& numeric& \pageref{Dpt}& - One printer's point in {\tt bp} units [0.99626]\\\hline -\pl\tt quartercircle& path& --& - First quadrant of a circle of diameter 1\\\hline -\pl\tt red& color& \pageref{Dred}& - Equivalent to {\tt (1,0,0)}\\\hline -\pl\tt right& pair& \pageref{Dright}& - Rightward direction $(1,0)$\\\hline -\pl\tt rounded& numeric& \pageref{Drnded}& - {\tt linecap} and {\tt linejoin} value for round joins\\ -\tt & & & - and end caps [1]\\\hline -\pl\tt squared& numeric& \pageref{Dsqred}& - {\tt linecap} value for square end caps [2]\\\hline -\tt true& boolean& \pageref{Dtrue}& - The boolean value {\tt true}\\\hline -\pl\tt unitsquare& path& --& - The path \verb|(0,0)--(1,0)--(1,1)--(0,1)--cycle|\\\hline -\pl\tt up& pair& \pageref{Dup}& - Upward direction $(0,1)$\\\hline -\pl\tt white& color& \pageref{Dwhite}& - Equivalent to {\tt (1,1,1)}\\\hline -\pl\tt withdots& picture& \pageref{Dwdots}& - Dash pattern that produces dotted lines\\\hline -\end{tabular} -$$ -\label{consttab}% -\index{cc?\texttt{cc}}\index{dd?\texttt{dd}}\index{ditto?\texttt{ditto}}\index{epsilon?\texttt{epsilon}}% -\index{origin?\texttt{origin}}\index{pc?\texttt{pc}}\index{quartercircle?\texttt{quartercircle}}% -\index{unitsquare?\texttt{unitsquare}} -\end{table} - - -\clearpage -\LTXtable{\textwidth}{mpman-optab} - -\begin{table}[htp] -\caption{Commands} -$$\begin{tabular}{|l|r|l|} -\hline -\multicolumn1{|c}{Name}& \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\ -\hline -\hline -\tt \verb|addto|& \pageref{sydraw}& - Low-level command for drawing and filling\\\hline -\tt \verb|clip|& \pageref{Dclip}& - Applies a clipping path to a picture\\\hline -\tt \verb|closefrom|& \pageref{Dclosefrom}& - Close a file opened by {\tt readfrom}\\\hline -\pl\tt \verb|cutdraw|& \pageref{Dctdraw}& - Draw with butt end caps\\\hline -\tt \verb|dashed|& \pageref{Ddashed}& - Apply dash pattern to drawing command\\\hline -\pl\tt \verb|draw|& \pageref{curves}& - Draw a line or a picture\\\hline -\pl\tt \verb|drawarrow|& \pageref{Ddrwarr}& - Draw a line with an arrowhead at the end\\\hline -\pl\tt \verb|drawdblarrow|& \pageref{Ddrwdar}& - Draw a line with arrowheads at both ends\\\hline -\tt \verb|filenametemplate|& \pageref{Dfilenametemplate}& - Set output file name pattern\\\hline -\pl\tt \verb|fill|& \pageref{Dfill}& - Fill inside a cyclic path\\\hline -\pl\tt \verb|filldraw|& \pageref{Dfildrw}& - Draw a cyclic path and fill inside it\\\hline -\tt \verb|interim|& \pageref{Dinterm}& - Make a local change to an internal variable\\\hline -\tt \verb|let|& --& - Assign one symbolic token the meaning of another\\\hline -\pl\tt \verb|loggingall|& \pageref{Dlogall}& - Turn on all tracing (log file only)\\\hline -\tt \verb|newinternal|& \pageref{Dnewint}& - Declare new internal variables\\\hline -\pl\tt \verb|pickup|& \pageref{Dpickup}& - Specify new pen for line drawing\\\hline -\tt \verb|save|& \pageref{Dsave}& - Make variables local\\\hline -\tt \verb|setbounds|& \pageref{Dsetbnd}& - Make a picture lie about its bounding box\\\hline -\tt \verb|shipout|& \pageref{Dship}& - Low-level command to output a figure\\\hline -\tt \verb|show|& \pageref{Dshow}& - print out expressions symbolically\\\hline -\tt \verb|showdependencies|& \pageref{Dshdep}& - print out all unsolved equations\\\hline -\tt \verb|showtoken|& \pageref{Dshtok}& - print an explanation of what a token is\\\hline -\tt \verb|showvariable|& \pageref{Dshvar}& - print variables symbolically\\\hline -\tt \verb|special|& \pageref{Dspecl}& - print a string directly in the PostScript output file\\\hline -\pl\tt \verb|tracingall|& \pageref{Dtall}& - Turn on all tracing\\\hline -\pl\tt \verb|tracingnone|& \pageref{Dtnone}& - Turn off all tracing\\\hline -\pl\tt \verb|undraw|& \pageref{Dundraw}& - Erase a line or a picture\\\hline -\pl\tt \verb|unfill|& \pageref{Dunfill}& - Erase inside a cyclic path\\\hline -\pl\tt \verb|unfilldraw|& \pageref{Dunfdrw}& - Erase a cyclic path and its inside\\\hline -\tt \verb|withcmykcolor|& \pageref{Dwithcmykcolor}& - Apply CMYK color to drawing command\\\hline -\tt \verb|withcolor|& \pageref{Dwithcolor}& - Apply generic color specification to drawing command\\\hline -\tt \verb|withgreyscale|& \pageref{Dwithgreyscale}& - Apply greyscale color to drawing command\\\hline -\tt \verb|withoutcolor|& \pageref{Dwithoutcolor}& - Don't apply any color specification to drawing command\\\hline -\tt \verb|withpen|& \pageref{sec.pens}& - Apply pen to drawing operation\\\hline -\tt \verb|withpostscript|& \pageref{Dwithpost}& - End raw PostScript code\\\hline -\tt \verb|withprescript|& \pageref{Dwithpre}& - Begin raw PostScript code\\\hline -\tt \verb|withrgbcolor|& \pageref{Dwithrgbcolor}& - Apply RGB color to drawing command\\\hline -\tt \verb|write to|& \pageref{Dwrite}& - Write string to file\\\hline -\end{tabular} -$$ -\index{let?\texttt{let}}% -\label{cmdtab} -\end{table} - - -\begin{table}[htp] -\caption{Function-Like Macros} -$$\begin{tabular}{|l|l|l|r|l|} -\hline -\multicolumn1{|c}{Name}& \multicolumn1{|c}{Arguments}& - \multicolumn1{|c}{Result}& \multicolumn1{|c}{Page}& - \multicolumn1{|c|}{Explanation}\\ -\hline -\hline -\pl\tt \verb|buildcycle|& list of paths& path& \pageref{buildcy}& - Build a cyclic path\\\hline -\pl\tt \verb|dashpattern|& on/off distances& picture& \pageref{Ddshpat}& - Create a pattern for dashed lines\\\hline -\pl\tt \verb|decr|& numeric variable& numeric& \pageref{Dincr}& - Decrement and return new value\\\hline -\pl\tt \verb|dotlabel|& suffix, picture, pair& --& \pageref{Ddotlab}& - Mark point and draw picture nearby\\\hline -\pl\tt \verb|dotlabel|& suffix, string, pair& --& \pageref{Ddotlab}& - Mark point and place text nearby\\\hline -\pl\tt \verb|dotlabels|& suffix, point numbers& --& \pageref{Ddotlbs}& - Mark {\tt z} points with their numbers\\\hline -\pl\tt \verb|drawdot|& pair& --& \pageref{Ddrawdot}& - Draw a dot at the given point\\\hline -\pl\tt \verb|drawoptions|& drawing options& --& \pageref{Ddropts}& - Set options for drawing commands\\\hline -\pl\tt \verb|image|& string& picture& \pageref{Dimage}& - Return picture from text\\\hline -\pl\tt \verb|incr|& numeric variable& numeric& \pageref{Dincr}& - Increment and return new value\\\hline -\pl\tt \verb|label|& suffix, picture, pair& --& \pageref{Dlabel}& - Draw picture near given point\\\hline -\pl\tt \verb|label|& suffix, string, pair& --& \pageref{Dlabel}& - Place text near given point\\\hline -\pl\tt \verb|labels|& suffix, point numbers& --& \pageref{Dlabels}& - Draw {\tt z} point numbers; no dots\\\hline -\pl\tt \verb|max|& list of numerics& numeric& --& - Find the maximum\\\hline -\pl\tt \verb|max|& list of strings& string& --& - Find the lexicographically last string\\\hline -\pl\tt \verb|min|& list of numerics& numeric& --& - Find the minimum\\\hline -\pl\tt \verb|min|& list of strings& string& --& - Find the lexicographically first string\\\hline -\pl\tt \verb|thelabel|& suffix, picture, pair& picture& \pageref{Dthelab}& - Picture shifted as if to label a point\\\hline -\pl\tt \verb|thelabel|& suffix, string, pair& picture& \pageref{Dthelab}& - Text positioned as if to label a point\\\hline -\pl\tt \verb|z|& suffix& pair& \pageref{Dzconv}& - The pair ${\tt x}\descr{suffix},{\tt y}\descr{suffix})$\\\hline -\end{tabular} -$$ -\index{min?\texttt{min}}\index{max?\texttt{max}}% -\label{pseudotab} -\end{table} - -\clearpage - -\begin{figure}[htp] -\begin{ctabbing} -$\tt \descr{atom} \rightarrow \descr{variable} \;|\; \descr{argument}$\\ -$\tt \qquad \;|\; \descr{number or fraction}$\\ -$\tt \qquad \;|\; \descr{internal variable}$\\ -$\tt \qquad \;|\; \hbox{\tt (}\descr{expression}\hbox{\tt )}$\\ -$\tt \qquad \;|\; begingroup \descr{statement list} \descr{expression} endgroup$\\ -$\tt \qquad \;|\; \descr{nullary op}$\\ -$\tt \qquad \;|\; btex \descr{typesetting commands} etex$\\ -$\tt \qquad \;|\; \descr{pseudo function}$\\ -$\tt \descr{primary} \rightarrow \descr{atom}$\\ -$\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt )}$\\ -$\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt )}$\\ -$\tt \qquad \;|\; \descr{of operator} \descr{expression} of \descr{primary}$\\ -$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\ -$\tt \qquad \;|\; str \descr{suffix}$\\ -$\tt \qquad \;|\; z \descr{suffix}$\\ -$\tt \qquad \;|\; \descr{numeric atom}\hbox{\tt [}\descr{expression}\hbox{\tt ,}\descr{expression}\hbox{\tt ]}$\\ -$\tt \qquad \;|\; \descr{scalar multiplication op} \descr{primary}$\\ -$\tt \descr{secondary} \rightarrow \descr{primary}$\\ -$\tt \qquad \;|\; \descr{secondary} \descr{primary binop} \descr{primary}$\\ -$\tt \qquad \;|\; \descr{secondary} \descr{transformer}$\\ -$\tt \descr{tertiary} \rightarrow \descr{secondary}$\\ -$\tt \qquad \;|\; \descr{tertiary} \descr{secondary binop} \descr{secondary}$\\ -$\tt \descr{subexpression} \rightarrow \descr{tertiary}$\\ -$\tt \qquad \;|\; \descr{path expression} \descr{path join} \descr{path knot}$\\ -$\tt \descr{expression} \rightarrow \descr{subexpression}$\\ -$\tt \qquad \;|\; \descr{expression} \descr{tertiary binop} \descr{tertiary}$\\ -$\tt \qquad \;|\; \descr{path subexpression} \descr{direction specifier}$\\ -$\tt \qquad \;|\; \descr{path subexpression} \descr{path join} cycle$\\ -$\tt $\\ -$\tt \descr{path knot} \rightarrow \descr{tertiary}$\\ -$\tt \descr{path join} \rightarrow \verb|--|$\\ -$\tt \qquad \;|\; \descr{direction specifier} \descr{basic path join} \descr{direction specifier}$\\ -$\tt \descr{direction specifier} \rightarrow \descr{empty}$\\ -$\tt \qquad \;|\; \verb|{|curl \descr{numeric expression}\verb|}|$\\ -$\tt \qquad \;|\; \verb|{|\descr{pair expression}\verb|}|$\\ -$\tt \qquad \;|\; \verb|{|\descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\verb|}|$\\ -$\tt \descr{basic path join} \rightarrow \hbox{\tt ..} \;|\; \hbox{\tt ...} \;|\; \hbox{\tt ..}\descr{tension}\hbox{\tt ..} \;|\; \hbox{\tt ..}\descr{controls}\hbox{\tt ..}$\\ -$\tt \descr{tension} \rightarrow tension \descr{numeric primary}$\\ -$\tt \qquad \;|\; tension \descr{numeric primary} and \descr{numeric primary}$\\ -$\tt \descr{controls} \rightarrow controls \descr{pair primary}$\\ -$\tt \qquad \;|\; controls \descr{pair primary} and \descr{pair primary}$\\ -$\tt $\\ -$\tt \descr{argument} \rightarrow \descr{symbolic token}$\\ -$\tt \descr{number or fraction} \rightarrow \descr{number}\hbox{\tt /}\descr{number}$\\ -$\tt \qquad \;|\; \descr{number not followed by `\hbox{\tt /}\tdescr{number}'}$\\ -$\tt \descr{scalar multiplication op} \rightarrow + \;|\; -$\\ -$\tt \qquad \;|\; \descr{`\tdescr{number or fraction}' not followed by `\tdescr{add op}\tdescr{number}'}$ -\end{ctabbing} -\caption{Part 1 of the syntax for expressions} -\index{expression?\tdescr{expression}}\index{nullary op?\tdescr{nullary op}}\index{of operator?\tdescr{of operator}}% -\index{path knot?\tdescr{path knot}}\index{primary?\tdescr{primary}}\index{primary binop?\tdescr{primary binop}}% -\index{secondary?\tdescr{secondary}}\index{secondary binop?\tdescr{secondary binop}}\index{suffix?\tdescr{suffix}}% -\index{tertiary?\tdescr{tertiary}}\index{tertiary binop?\tdescr{tertiary binop}}\index{unary op?\tdescr{unary op}}% -\label{syexpr1} -\end{figure} - -\begin{figure}[htp] -\begin{ctabbing} -$\tt \descr{transformer} \rightarrow rotated \descr{numeric primary}$\\ -$\tt \qquad \;|\; scaled \descr{numeric primary}$\\ -$\tt \qquad \;|\; shifted \descr{pair primary}$\\ -$\tt \qquad \;|\; slanted \descr{numeric primary}$\\ -$\tt \qquad \;|\; transformed \descr{transform primary}$\\ -$\tt \qquad \;|\; xscaled \descr{numeric primary}$\\ -$\tt \qquad \;|\; yscaled \descr{numeric primary}$\\ -$\tt \qquad \;|\; zscaled \descr{pair primary}$\\ -$\tt \qquad \;|\; reflectedabout\hbox{\tt (}\descr{pair expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\ -$\tt \qquad \;|\; rotatedaround\hbox{\tt (}\descr{pair expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt )}$\\ -$\tt $\\ -$\tt \descr{nullary op} \rightarrow false \;|\; normaldeviate \;|\; nullpen \;|\; nullpicture \;|\; pencircle$\\ -$\tt \qquad \;|\; true \;|\; whatever$\\ -$\tt \descr{unary op} \rightarrow \descr{type}$\\ -$\tt \qquad \;|\; abs \;|\; angle \;|\; arclength \;|\; ASCII \;|\; bbox \;|\; blackpart \;|\; bluepart \;|\; bot \;|\; bounded$\\ -$\tt \qquad \;|\; ceiling \;|\; center \;|\; char \;|\; clipped \;|\; colormodel \;|\; cosd \;|\; cyanpart \;|\; cycle$\\ -$\tt \qquad \;|\; dashpart \;|\; decimal \;|\; dir \;|\; floor \;|\; filled \;|\; fontpart \;|\; fontsize$\\ -$\tt \qquad \;|\; greenpart \;|\; greypart \;|\; hex \;|\; inverse \;|\; known \;|\; length \;|\; lft \;|\; llcorner$\\ -$\tt \qquad \;|\; lrcorner\;|\; magentapart \;|\; makepath \;|\; makepen \;|\; mexp \;|\; mlog \;|\; not \;|\; oct \;|\; odd$\\ -$\tt \qquad \;|\; pathpart \;|\; penpart \;|\; readfrom \;|\; redpart \;|\; reverse \;|\; round \;|\; rt \;|\; sind \;|\; sqrt$\\ -$\tt \qquad \;|\; stroked \;|\; textpart \;|\; textual \;|\; top \;|\; ulcorner$\\ -$\tt \qquad \;|\; uniformdeviate \;|\; unitvector \;|\; unknown \;|\; urcorner \;|\; xpart \;|\; xxpart$\\ -$\tt \qquad \;|\; xypart \;|\; yellowpart \;|\; ypart \;|\; yxpart \;|\; yypart$\\ -$\tt \descr{type} \rightarrow boolean \;|\; cmykcolor \;|\; color \;|\; numeric \;|\; pair$\\ -$\tt \qquad \;|\; path \;|\; pen \;|\; picture \;|\; rgbcolor \;|\; string \;|\; transform$\\ -$\tt \descr{primary binop} \rightarrow \hbox{\tt *} \;|\; \hbox{\tt /} \;|\; \hbox{\tt **} \;|\; and$\\ -$\tt \qquad \;|\; dotprod \;|\; div \;|\; infont \;|\; mod$\\ -$\tt \descr{secondary binop} \rightarrow + \;|\; - \;|\; ++ \;|\; +-+ \;|\; or$\\ -$\tt \qquad \;|\; intersectionpoint \;|\; intersectiontimes$\\ -$\tt \descr{tertiary binop} \rightarrow \hbox{\tt \&} \;|\; \hbox{\verb|<|} \;|\; \hbox{\verb|<=|} \;|\; \hbox{\verb|<>|} \;|\; \hbox{\tt =} \;|\; \hbox{\verb|>|} \;|\; \hbox{\verb|>=|}$\\ -$\tt \qquad \;|\; cutafter \;|\; cutbefore$\\ -$\tt \descr{of operator} \rightarrow arctime \;|\; direction \;|\; directiontime \;|\; directionpoint$\\ -$\tt \qquad \;|\; penoffset \;|\; point \;|\; postcontrol \;|\; precontrol \;|\; subpath$\\ -$\tt \qquad \;|\; substring$\\ -$\tt $\\ -$\tt \descr{variable} \rightarrow \descr{tag}\descr{suffix}$\\ -$\tt \descr{suffix} \rightarrow \descr{empty} \;|\; \descr{suffix}\descr{subscript} \;|\; \descr{suffix}\descr{tag}$\\ -$\tt \qquad \;|\; \descr{suffix parameter}$\\ -$\tt \descr{subscript} \rightarrow \descr{number} \;|\; \hbox{\tt [}\descr{numeric expression}\hbox{\tt ]}$\\ -$\tt $\\ -$\tt \descr{internal variable} \rightarrow ahangle \;|\; ahlength \;|\; bboxmargin$\\ -$\tt \qquad \;|\; charcode \;|\; day \;|\; defaultcolormodel \;|\; defaultpen \;|\; defaultscale$\\ -$\tt \qquad \;|\; labeloffset \;|\; linecap \;|\; linejoin \;|\; miterlimit \;|\; month$\\ -$\tt \qquad \;|\; pausing \;|\; prologues \;|\; showstopping \;|\; time \;|\; tracingoutput$\\ -$\tt \qquad \;|\; tracingcapsules \;|\; tracingchoices \;|\; tracingcommands$\\ -$\tt \qquad \;|\; tracingequations \;|\; tracinglostchars \;|\; tracingmacros$\\ -$\tt \qquad \;|\; tracingonline \;|\; tracingrestores \;|\; tracingspecs$\\ -$\tt \qquad \;|\; tracingstats \;|\; tracingtitles \;|\; truecorners$\\ -$\tt \qquad \;|\; warningcheck \;|\; year$\\ -$\tt \qquad \;|\; \descr{symbolic token defined by {\tt newinternal}}$ -\end{ctabbing} -\caption{Part 2 of the syntax for expressions} -\index{nullary op?\tdescr{nullary op}}\index{of operator?\tdescr{of operator}}\index{primary binop?\tdescr{primary binop}}% -\index{secondary binop?\tdescr{secondary binop}}\index{subscript?\tdescr{subscript}}\index{suffix?\tdescr{suffix}}% -\index{tertiary binop?\tdescr{tertiary binop}}\index{unary op?\tdescr{unary op}}% -\label{syexpr2} -\end{figure} - -\begin{figure}[htp] -\begin{ctabbing} -$\tt \descr{pseudo function} \rightarrow min\hbox{\tt (}\descr{expression list}\hbox{\tt )}$\\ -$\tt \qquad \;|\; max\hbox{\tt (}\descr{expression list}\hbox{\tt )}$\\ -$\tt \qquad \;|\; incr\hbox{\tt (}\descr{numeric variable}\hbox{\tt )}$\\ -$\tt \qquad \;|\; decr\hbox{\tt (}\descr{numeric variable}\hbox{\tt )}$\\ -$\tt \qquad \;|\; dashpattern\hbox{\tt (}\descr{on\hbox{\tt /}off list}\hbox{\tt )}$\\ -$\tt \qquad \;|\; interpath\hbox{\tt (}\descr{numeric expression}\hbox{\tt ,} \descr{path expression}\hbox{\tt ,} \descr{path expression}\hbox{\tt )}$\\ -$\tt \qquad \;|\; buildcycle\hbox{\tt (}\descr{path expression list}\hbox{\tt )}$\\ -$\tt \qquad \;|\; thelabel\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\ -$\tt \descr{path expression list} \rightarrow \descr{path expression}$\\ -$\tt \qquad \;|\; \descr{path expression list}\hbox{\tt ,} \descr{path expression}$\\ -$\tt \descr{on\hbox{\tt /}off list} \rightarrow \descr{on\hbox{\tt /}off list}\descr{on\hbox{\tt /}off clause} \;|\; \descr{on\hbox{\tt /}off clause}$\\ -$\tt \descr{on\hbox{\tt /}off clause} \rightarrow on \descr{numeric tertiary} \;|\; off \descr{numeric tertiary}$ -\end{ctabbing} -\caption{The syntax for function-like macros} -\index{label suffix?\tdescr{label suffix}}% -\label{sypseudo} -\end{figure} - -\begin{figure}[htp] -\begin{ctabbing} -$\tt \descr{boolean expression} \rightarrow \descr{expression}$\\ -$\tt \descr{cmykcolor expression} \rightarrow \descr{expression}$\\ -$\tt \descr{color expression} \rightarrow \descr{expression}$\\ -$\tt \descr{numeric atom} \rightarrow \descr{atom}$\\ -$\tt \descr{numeric expression} \rightarrow \descr{expression}$\\ -$\tt \descr{numeric primary} \rightarrow \descr{primary}$\\ -$\tt \descr{numeric tertiary} \rightarrow \descr{tertiary}$\\ -$\tt \descr{numeric variable} \rightarrow \descr{variable} \;|\; \descr{internal variable}$\\ -$\tt \descr{pair expression} \rightarrow \descr{expression}$\\ -$\tt \descr{pair primary} \rightarrow \descr{primary}$\\ -$\tt \descr{path expression} \rightarrow \descr{expression}$\\ -$\tt \descr{path subexpression} \rightarrow \descr{subexpression}$\\ -$\tt \descr{pen expression} \rightarrow \descr{expression}$\\ -$\tt \descr{picture expression} \rightarrow \descr{expression}$\\ -$\tt \descr{picture variable} \rightarrow \descr{variable}$\\ -$\tt \descr{rgbcolor expression} \rightarrow \descr{expression}$\\ -$\tt \descr{string expression} \rightarrow \descr{expression}$\\ -$\tt \descr{suffix parameter} \rightarrow \descr{parameter}$\\ -$\tt \descr{transform primary} \rightarrow \descr{primary}$ -\end{ctabbing} -\caption{Miscellaneous productions needed to complete the BNF} -\label{sytypexpr} -\end{figure} - -\begin{figure}[htp] -\begin{ctabbing} -$\tt \descr{program} \rightarrow \descr{statement list} end$\\ -$\tt \descr{statement list} \rightarrow \descr{empty} \;|\; \descr{statement list} \hbox{\tt ;} \descr{statement}$\\ -$\tt \descr{statement} \rightarrow \descr{empty}$\\ -$\tt \qquad \;|\; \descr{equation} \;|\; \descr{assignment}$\\ -$\tt \qquad \;|\; \descr{declaration} \;|\; \descr{macro definition}$\\ -$\tt \qquad \;|\; \descr{compound} \;|\; \descr{pseudo procedure}$\\ -$\tt \qquad \;|\; \descr{command}$\\ -$\tt \descr{compound} \rightarrow begingroup \descr{statement list} endgroup$\\ -$\tt \qquad \;|\; beginfig\hbox{\tt (}\descr{numeric expression}\hbox{\tt );} \descr{statement list}\hbox{\tt ;} endfig$\\ -$\tt $\\ -$\tt \descr{equation} \rightarrow \descr{expression} \hbox{\tt =} \descr{right-hand side}$\\ -$\tt \descr{assignment} \rightarrow \descr{variable} \hbox{\tt :=} \descr{right-hand side}$\\ -$\tt \qquad \;|\; \descr{internal variable} \hbox{\tt :=} \descr{right-hand side}$\\ -$\tt \descr{right-hand side} \rightarrow \descr{expression} \;|\; \descr{equation} \;|\; \descr{assignment}$\\ -$\tt $\\ -$\tt \descr{declaration} \rightarrow \descr{type} \descr{declaration list}$\\ -$\tt \descr{declaration list} \rightarrow \descr{generic variable}$\\ -$\tt \qquad \;|\; \descr{declaration list}\hbox{\tt ,} \descr{generic variable}$\\ -$\tt \descr{generic variable} \rightarrow \descr{symbolic token} \descr{generic suffix}$\\ -$\tt \descr{generic suffix} \rightarrow \descr{empty} \;|\; \descr{generic suffix} \descr{tag}$\\ -$\tt \qquad \;|\; \descr{generic suffix} \hbox{\tt []}$\\ -$\tt $\\ -$\tt \descr{macro definition} \rightarrow \descr{macro heading} \hbox{\tt =} \descr{replacement text} enddef$\\ -$\tt \descr{macro heading} \rightarrow def \descr{symbolic token} \descr{delimited part} \descr{undelimited part}$\\ -$\tt \qquad \;|\; vardef \descr{generic variable} \descr{delimited part} \descr{undelimited part}$\\ -$\tt \qquad \;|\; vardef \descr{generic variable} \hbox{\verb|@#|} \descr{delimited part} \descr{undelimited part}$\\ -$\tt \qquad \;|\; \descr{binary def} \descr{parameter} \descr{symbolic token} \descr{parameter}$\\ -$\tt \descr{delimited part} \rightarrow \descr{empty}$\\ -$\tt \qquad \;|\; \descr{delimited part}\hbox{\tt (}\descr{parameter type} \descr{parameter tokens}\hbox{\tt )}$\\ -$\tt \descr{parameter type} \rightarrow expr \;|\; suffix \;|\; text$\\ -$\tt \descr{parameter tokens} \rightarrow \descr{parameter} \;|\; \descr{parameter tokens}\hbox{\tt ,} \descr{parameter}$\\ -$\tt \descr{parameter} \rightarrow \descr{symbolic token}$\\ -$\tt \descr{undelimited part} \rightarrow \descr{empty}$\\ -$\tt \qquad \;|\; \descr{parameter type} \descr{parameter}$\\ -$\tt \qquad \;|\; \descr{precedence level} \descr{parameter}$\\ -$\tt \qquad \;|\; expr \descr{parameter} of \descr{parameter}$\\ -$\tt \descr{precedence level} \rightarrow primary \;|\; secondary \;|\; tertiary$\\ -$\tt \descr{binary def} \rightarrow primarydef \;|\; secondarydef \;|\; tertiarydef$\\ -$\tt $\\ -$\tt \descr{pseudo procedure} \rightarrow drawoptions\hbox{\tt (}\descr{option list}\hbox{\tt )}$\\ -$\tt \qquad \;|\; label\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\ -$\tt \qquad \;|\; dotlabel\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\ -$\tt \qquad \;|\; labels\descr{label suffix}\hbox{\tt (}\descr{point number list}\hbox{\tt )}$\\ -$\tt \qquad \;|\; dotlabels\descr{label suffix}\hbox{\tt (}\descr{point number list}\hbox{\tt )}$\\ -$\tt \descr{point number list} \rightarrow \descr{suffix} \;|\; \descr{point number list}\hbox{\tt ,} \descr{suffix}$\\ -$\tt \descr{label suffix} \rightarrow \descr{empty} \;|\; lft \;|\; rt \;|\; top \;|\; bot \;|\; ulft \;|\; urt \;|\; llft \;|\; lrt$ -\end{ctabbing} -\caption{Overall syntax for MetaPost programs} -\index{generic variable?\tdescr{generic variable}}\index{label suffix?\tdescr{label suffix}}\index{replacement text?\tdescr{replacement text}}% -\index{suffix?\tdescr{suffix}}% -\label{syprog} -\end{figure} - -\begin{figure}[htp] -\begin{ctabbing} -$\tt \descr{command} \rightarrow clip \descr{picture variable} to \descr{path expression}$\\ -$\tt \qquad \;|\; interim \descr{internal variable} \hbox{\tt :=} \descr{right-hand side}$\\ -$\tt \qquad \;|\; let \descr{symbolic token} \hbox{\tt =} \descr{symbolic token}$\\ -$\tt \qquad \;|\; newinternal \descr{symbolic token list}$\\ -$\tt \qquad \;|\; pickup \descr{expression}$\\ -$\tt \qquad \;|\; randomseed \hbox{\tt :=} \descr{numeric expression}$\\ -$\tt \qquad \;|\; save \descr{symbolic token list}$\\ -$\tt \qquad \;|\; setbounds \descr{picture variable} to \descr{path expression}$\\ -$\tt \qquad \;|\; shipout \descr{picture expression}$\\ -$\tt \qquad \;|\; special \descr{string expression}$\\ -$\tt \qquad \;|\; write \descr{string expression} to \descr{string expression}$\\ -$\tt \qquad \;|\; \descr{addto command}$\\ -$\tt \qquad \;|\; \descr{drawing command}$\\ -$\tt \qquad \;|\; \descr{font metric command}$\\ -$\tt \qquad \;|\; \descr{message command}$\\ -$\tt \qquad \;|\; \descr{show command}$\\ -$\tt \qquad \;|\; \descr{tracing command}$\\ -$\tt $\\ -$\tt \descr{show command} \rightarrow show \descr{expression list}$\\ -$\tt \qquad \;|\; showvariable \descr{symbolic token list}$\\ -$\tt \qquad \;|\; showtoken \descr{symbolic token list}$\\ -$\tt \qquad \;|\; showdependencies$\\ -$\tt $\\ -$\tt \descr{symbolic token list} \rightarrow \descr{symbolic token}$\\ -$\tt \qquad \;|\; \descr{symbolic token}\hbox{\tt ,} \descr{symbolic token list}$\\ -$\tt \descr{expression list} \rightarrow \descr{expression} \;|\; \descr{expression list}\hbox{\tt ,} \descr{expression}$\\ -$\tt $\\ -$\tt \descr{addto command} \rightarrow$\\ -$\tt \qquad addto \descr{picture variable} also \descr{picture expression} \descr{option list}$\\ -$\tt \qquad \;|\; addto \descr{picture variable} contour \descr{path expression} \descr{option list}$\\ -$\tt \qquad \;|\; addto \descr{picture variable} doublepath \descr{path expression} \descr{option list}$\\ -$\tt \descr{option list} \rightarrow \descr{empty} \;|\; \descr{drawing option} \descr{option list}$\\ -$\tt \descr{drawing option} \rightarrow withcolor \descr{color expression}$\\ -$\tt \qquad \;|\; withrgbcolor \descr{rgbcolor expression} \;|\; withcmykcolor \descr{cmykcolor expression}$\\ -$\tt \qquad \;|\; withgreyscale \descr{numeric expression} \;|\; withoutcolor$\\ -$\tt \qquad \;|\; withprescript \descr{string expression} \;|\; withpostscript \descr{string expression}$\\ -$\tt \qquad \;|\; withpen \descr{pen expression} \;|\; dashed \descr{picture expression}$\\ -$\tt $\\ -$\tt \descr{drawing command} \rightarrow draw \descr{picture expression} \descr{option list}$\\ -$\tt \qquad \;|\; \descr{fill type} \descr{path expression} \descr{option list}$\\ -$\tt \descr{fill type} \rightarrow fill \;|\; draw \;|\; filldraw \;|\; unfill \;|\; undraw \;|\; unfilldraw$\\ -$\tt \qquad \;|\; drawarrow \;|\; drawdblarrow \;|\; cutdraw$\\ -$\tt $\\ -$\tt \descr{message command} \rightarrow errhelp \descr{string expression}$\\ -$\tt \qquad \;|\; errmessage \descr{string expression}$\\ -$\tt \qquad \;|\; filenametemplate \descr{string expression}$\\ -$\tt \qquad \;|\; message \descr{string expression}$\\ -$\tt $\\ -$\tt \descr{tracing command} \rightarrow tracingall \;|\; loggingall \;|\; tracingnone$ -\end{ctabbing} -\caption{The syntax for commands} -\index{option list?\tdescr{option list}}\index{picture variable?\tdescr{picture variable}}% -\label{sycmds} - -% is this really true? in practice, in real implementations? -%\bigskip -%By the way, the default for \ttindex{randomseed} is, in effect, -%$\textsl{day} + \textsl{time}*\epsilon$. Unfortunately, \textsl{time} -%is in minutes. -\end{figure} - -\begin{figure}[htp] -\begin{ctabbing} -$\tt \descr{if test} \rightarrow if \descr{boolean expression} \hbox{\tt :} \descr{balanced tokens} \descr{alternatives} fi$\\ -$\tt \descr{alternatives} \rightarrow \descr{empty}$\\ -$\tt \qquad \;|\; else\hbox{\tt :} \descr{balanced tokens}$\\ -$\tt \qquad \;|\; elseif \descr{boolean expression} \hbox{\tt :} \descr{balanced tokens} \descr{alternatives}$\\ -$\tt $\\ -$\tt \descr{loop} \rightarrow \descr{loop header}\hbox{\tt :} \descr{loop text} endfor$\\ -$\tt \descr{loop header} \rightarrow for \descr{symbolic token} \hbox{\tt =} \descr{progression}$\\ -$\tt \qquad \;|\; for \descr{symbolic token} \hbox{\tt =} \descr{for list}$\\ -$\tt \qquad \;|\; for \descr{symbolic token} \hbox{\tt within} \descr{picture expression}$\\ -$\tt \qquad \;|\; forsuffixes \descr{symbolic token} \hbox{\tt =} \descr{suffix list}$\\ -$\tt \qquad \;|\; forever$\\ -$\tt \descr{progression} \rightarrow \descr{numeric expression} upto \descr{numeric expression}$\\ -$\tt \qquad \;|\; \descr{numeric expression} downto \descr{numeric expression}$\\ -$\tt \qquad \;|\; \descr{numeric expression} step \descr{numeric expression} until \descr{numeric expression} $\\ -$\tt \descr{for list} \rightarrow \descr{expression} \;|\; \descr{for list}\hbox{\tt ,} \descr{expression}$\\ -$\tt \descr{suffix list} \rightarrow \descr{suffix} \;|\; \descr{suffix list}\hbox{\tt ,} \descr{suffix}$ -\end{ctabbing} -\caption{The syntax for conditionals and loops} -\index{balanced tokens?\tdescr{balanced tokens}}\index{suffix?\tdescr{suffix}}% -\label{sycondloop} -\end{figure} - -\clearpage - -\let\topfraction=\svtopfrac % restore values from the start of this appendix -\let\textfraction=\svtxtfrac -\setcounter{topnumber}{\value{svtopnum}} -\setcounter{totalnumber}{\value{svtotnum}} - - -\section{MetaPost Versus \MF} -\label{MPvsMF} - -Since the \MF\index{metafont?\MF} and MetaPost languages have so much in -common, expert users of \MF\ will want to skip most of the explanations -in this document and concentrate on concepts that are unique to -MetaPost. The comparisons in this appendix are intended to help experts -that are familiar with {\sl The\ \MF book} as well as other users that -want to benefit from Knuth's more detailed explanations \cite{kn:c}. - -Since \MF\ is intended for making \TeX\ fonts, it has a number of -primitives for generating the {\tt tfm}\index{tfm file?{\tt tfm} -file}\index{files!tfm?{\tt tfm}} files that \TeX\ needs for character -dimensions, spacing information, ligatures\index{ligatures} and -kerning\index{kerning}. MetaPost can also be used for generating fonts, -and it also has \MF's primitives for making {\tt tfm} files. These are -listed in Table~\ref{tfmprim}. Explanations can be found in the \MF\ -documentation \cite{kn:c,kn:mf3}. - -\begin{table}[htp] -$$\begin{tabular}{|l|l|} \hline -commands& {\tt charlist}, {\tt extensible}, - {\tt fontdimen}, {\tt headerbyte} \\ - & {\tt kern}, {\tt ligtable} \\ \hline -ligtable operators& \verb!::!, \verb!=:!, \verb!=:|!, \verb!=:|>!, - \verb!|=:!, \verb!|=:>!, \\ - & \verb!|=:|!, \verb!|=:|>!, \verb!|=:|>>!, - \verb!||:! \\ \hline -internal variables\index{internal variables}\index{variables!internal}& - {\tt boundarychar}, {\tt chardp}, - {\tt charext}, {\tt charht}, \\ - & {\tt charic}, {\tt charwd}, - {\tt designsize}, {\tt fontmaking} \\ \hline -other operators& {\tt charexists} \\ \hline -\end{tabular} -$$ -\caption{MetaPost primitives for making {\tt tfm} files.} -\label{tfmprim} -\end{table} - -Even though MetaPost has the primitives for generating fonts, many of -the font-making primitives and internal variables that are part of Plain -\MF\index{metafont?\MF} are not defined in Plain MetaPost\index{Plain -macros}. Instead, there is a separate macro package called {\tt -mfplain}\index{mfplain?\texttt{mfplain}} that defines the macros -required to allow MetaPost to process Knuth's Computer Modern fonts as -shown in Table~\ref{mfponly} \cite{kn:e}. To load these macros, put -``\verb|&mfplain|'' before the name of the input file. This can be done -at the {\tt **} prompt after invoking the MetaPost interpreter with no -arguments, or on a command line that looks something like -this:\footnote{Command line syntax is system dependent. Quotes are -needed on most Unix systems to protect special characters like -{\tt\&}.} -$$ \hbox{\verb|mpost '&mfplain' cmr10|} $$ -The analog of a \MF\ command line like -$$ \hbox{\verb|mf '\mode=lowres; mag=1.2; input cmr10'|} $$ -is -$$ \hbox{\verb|mpost '&mfplain \mode=lowres; mag=1.2; input cmr10'|} $$ -The result is a set of PostScript\index{PostScript} files, one for each -character in the font. Some editing would be required in order to -merge them into a downloadable Type~3 PostScript font~\cite{ad:red2}. - -\begin{table}[htp] -$$ -\renewcommand{\FancyVerbFormatLine}[1]{\hbox{#1}\strut} -\begin{tabular}{|l|} \hline -\multicolumn 1{|c|} -{Defined in the {\tt mfplain} package} \\ \hline -\begin{verbatim} -beginchar font_identifier -blacker font_normal_shrink -capsule_def font_normal_space -change_width font_normal_stretch -define_blacker_pixels font_quad -define_corrected_pixels font_size -define_good_x_pixels font_slant -define_good_y_pixels font_x_height -define_horizontal_corrected_pixels italcorr -define_pixels labelfont -define_whole_blacker_pixels makebox -define_whole_pixels makegrid -define_whole_vertical_blacker_pixels maketicks -define_whole_vertical_pixels mode_def -endchar mode_setup -extra_beginchar o_correction -extra_endchar proofrule -extra_setup proofrulethickness -font_coding_scheme rulepen -font_extra_space smode -\end{verbatim} - \\ \hline -\multicolumn 1{|c|} -{Defined as no-ops in the {\tt mfplain} package}\\ \hline -\begin{verbatim} -cullit proofoffset -currenttransform screenchars -gfcorners screenrule -grayfont screenstrokes -hround showit -imagerules slantfont -lowres_fix titlefont -nodisplays unitpixel -notransforms vround -openit -\end{verbatim} - \\ \hline -\end{tabular} -\renewcommand{\FancyVerbFormatLine}[1]{#1} -$$ -\caption{Macros and internal variables defined only in the {\tt mfplain} -package.} -\label{mfponly} -\end{table} - -Another limitation of the {\tt mfplain} package is that certain internal -variables from Plain \MF\index{metafont?\MF} cannot be given reasonable -MetaPost definitions. These include {\tt displaying}, {\tt -currentwindow}, \verb|screen_rows|, and \verb|screen_cols| which depend -on \MF's ability to display images on the computer screen. In addition, -\verb|pixels_per_inch| is irrelevant since MetaPost uses fixed units of -PostScript\index{PostScript!point}\index{point!PostScript} points. - -The reason why some macros and internal variables\index{internal -variables}\index{variables!internal} are not meaningful in MetaPost is -that \MF\ primitive commands {\tt cull}, {\tt display}, {\tt -openwindow}, {\tt numspecial} and {\tt totalweight} are not implemented -in MetaPost. Also not implemented are a number of internal variables as -well as the \tdescr{drawing option} {\tt withweight}. Here is a -complete listing of the internal variables whose primitive meanings in -\MF\ do not make sense in MetaPost: -$$\begin{verbatim} -autorounding fillin proofing tracingpens xoffset -chardx granularity smoothing turningcheck yoffset -chardy hppp tracingedges vppp -\end{verbatim} -$$ - -There is also one \MF\ primitive that has a slightly different meaning in -MetaPost. Both languages allow statements of the -form\index{special?\texttt{special}}\label{Dspecl} -$$ {\tt special}\, \descr{string expression} \hbox{\tt;} $$ -but \MF\ copies the string into its ``generic font'' output file, while -MetaPost interprets the string as a sequence of PostScript\index{PostScript} -commands that are to be placed at the beginning of the next output file. - -In this regard, it is worth mentioning that rules in \TeX\ material -included via {\tt btex..etex} in MetaPost are rounded to the correct -number of pixels according to PostScript\index{PostScript!conversion rules} -conversion rules~\cite{ad:red2}. In \MF, rules are not generated -directly, but simply included in specials and interpreted later by -other programs, such as {\tt gftodvi}\index{gftodvi?\ttt{gftodvi}}, -so there is no special conversion. - -All the other differences between \MF\ and MetaPost are features found -only in MetaPost. These are listed in Table~\ref{mponly}. The only -commands listed in this table that the preceding sections do not discuss -are -\verb|extra_beginfig|\index{extra_beginfig?\texttt{extra\_beginfig}}\label{Dxbfig}, -\verb|extra_endfig|\index{extra_endfig?\texttt{extra\_endfig}}\label{Dxefig}, -and {\tt mpxbreak}. The first two are strings that contain extra -commands to be processed by {\tt -beginfig}\index{beginfig?\texttt{beginfig}} and {\tt -endfig}\index{endfig?\texttt{endfig}} just as \verb|extra_beginchar| and -\verb|extra_endchar| are processed by {\tt beginchar} and {\tt endchar}. -(The file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} uses these -features). - -The other new feature listed in Table~\ref{mponly} not listed in the -index is {\tt mpxbreak}\index{mpxbreak?\texttt{mpxbreak}}. This is used -to separate blocks of translated \TeX\index{TeX?\TeX} or -troff\index{troff} commands in {\tt mpx}\index{files!mpx?{\tt mpx}} -files. It should be of no concern to users since {\tt mpx} files are -generated automatically. - -\begin{table} -\centering -\begin{tabular}{|c|}\hline -MetaPost primitives not found in \MF\\\hline -\begin{minipage}[b]{.75\linewidth}\ttfamily -\begin{multicols}{3} -blackpart\\ -bluepart\\ -bounded\\ -btex\\ -clip\\ -clipped\\ -closefrom\\ -cmykcolor\\ -color\\ -colormodel\\ -cyanpart\\ -dashed\\ -dashpart\\ -defaultcolormodel\\ -etex\\ -filenametemplate\\ -filled\\ -fontmapfile\\ -fontmapline\\ -fontpart\\ -fontsize\\ -for within\\ -greenpart\\ -greypart\\ -infont\\ -linecap\\ -linejoin\\ -llcorner\\ -lrcorner\\ -magentapart\\ -miterlimit\\ -mpprocset\\ -mpxbreak\\ -pathpart\\ -penpart\\ -prologues\\ -readfrom\\ -redpart\\ -restoreclipcolor\\ -rgbcolor\\ -setbounds\\ -stroked\\ -textpart\\ -textual\\ -tracinglostchars\\ -troffmode\\ -truecorners\\ -ulcorner\\ -urcorner\\ -verbatimtex\\ -withcmykcolor\\ -withcolor\\ -withgreyscale\\ -withoutcolor\\ -withpostscript\\ -withprescript\\ -withrgbcolor\\ -write to\\ -yellowpart -\end{multicols} -\end{minipage}\\\hline - -Variables and Macros defined only in Plain MetaPost\\\hline -\begin{minipage}[b]{.75\linewidth}\ttfamily -\begin{multicols}{3} -ahangle\\ -ahlength\\ -background\\ -bbox\\ -bboxmargin\\ -beginfig\\ -beveled\\ -black\\ -blue\\ -buildcycle\\ -butt\\ -center\\ -colorpart\\ -cutafter\\ -cutbefore\\ -cuttings\\ -dashpattern\\ -defaultfont\\ -defaultpen\\ -defaultscale\\ -dotlabel\\ -dotlabels\\ -drawarrow\\ -drawdblarrow\\ -drawoptions\\ -endfig\\ -EOF\\ -evenly\\ -extra\_beginfig\\ -extra\_endfig\\ -green\\ -image\\ -label\\ -labeloffset\\ -mitered\\ -red\\ -rounded\\ -squared\\ -thelabel\\ -white -\end{multicols} -\end{minipage}\\\hline -\end{tabular} -\caption{Macros and internal variables defined in MetaPost but not \MF.} -\label{mponly} -\end{table} +\include{mpman-app-refman} +\include{mpman-app-legacy} \bibliographystyle{plain} @@ -5981,3 +5281,9 @@ white % - I request that it remain clear that I am the author of % "A User's Manual for MetaPost" and "Drawing Graphs with MetaPost". % - I request to be consulted before significant changes are made. + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: t +%%% End: |