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 | 362 |
1 files changed, 247 insertions, 115 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpman.tex b/Master/texmf-dist/doc/metapost/base/source/mpman.tex index 8a1ce606dfd..c62e95f1a05 100644 --- a/Master/texmf-dist/doc/metapost/base/source/mpman.tex +++ b/Master/texmf-dist/doc/metapost/base/source/mpman.tex @@ -1,13 +1,23 @@ -% $Id: mpman.tex,v 1.26 2005/04/13 12:57:28 karl Exp $ +% $Id: mpman.tex 458 2008-04-03 21:56:20Z stephanhennig $ % MetaPost manual, by John Hobby. License at end. +\listfiles +\RequirePackage{ifpdf} +\ifpdf \ifnum\pdftexversion<140 \else \pdfminorversion=5 \pdfobjcompresslevel=1% Use compressed object streams. \fi -\RequirePackage[resetfonts]{cmap} +\RequirePackage{cmap} +\fi \documentclass{article} % article is NOT the original style -% +\usepackage[nofancy]{svninfo}% Access VCS information. +\svnInfo $Id: mpman.tex 458 2008-04-03 21:56:20Z stephanhennig $ + +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{textcomp} +\usepackage{mflogo} \usepackage{makeidx} \usepackage{fancyvrb} \usepackage{ctabbing} @@ -15,28 +25,16 @@ {verbatim}{BVerbatim}{baseline=c} \usepackage{graphicx} \usepackage[latin1]{inputenc} -\pdfmapfile{+lm-math.map} \usepackage[textwidth=6in,textheight=8.65in]{geometry} \usepackage{tocloft} \setlength\cftbeforesecskip{1.3ex plus 0.3ex minus 0.3ex} \usepackage{ltxtable} - \makeatletter - \def\logo{\global\font\logo=logo10 at1\@ptsize\p@ \logo} - \def\logosl{\global\font\logosl=logosl10 at1\@ptsize\p@ \logosl} - \def\MF{{\ifdim \fontdimen\@ne\font >\z@ \def\logo{\logosl}\fi - {\logo META}\-{\logo FONT}}} - \makeatother \def\ttindex#1{{\tt #1}\index{#1?\texttt{#1}}} \def\ttt{\texttt} % I get tired of typing this out \def\ConTeXt{Con\TeX t} -% \def\MF{{META\-FONT}} % Replacement for the above when using times.sty - - -\newfont\psyvii{psyr at 7pt} -\newcommand\reg{$^{\hbox{\psyvii\char'322}}$} % Registered trademark \newcommand\descr[1]{{\langle\hbox{#1}\rangle}} \newcommand\invisgap{\nobreak\hskip0pt\relax} @@ -78,28 +76,49 @@ citecolor=SpringGreen3 } \usepackage[all]{hypcap} +\ifpdf +\pdfmapfile{=cm2lm.map}% replace CM by LM in figures +\else +\DeclareGraphicsExtensions{.mps} +\DeclareGraphicsRule{mps}{eps}{*}{} +\usepackage{breakurl} +\fi \begin{document} \VerbatimFootnotes -\author{John D. Hobby\\\small and the MetaPost development team} -\title{A User's Manual for MetaPost} -\date{documented version: 1.000} -\maketitle - -\begin{abstract} -The MetaPost system implements a picture-drawing language very much like -Knuth's \MF\ except that it outputs PostScript commands instead of -run-length-encoded bitmaps. MetaPost is a powerful language for -producing figures for documents to be printed on PostScript printers. -It provides easy access to all the features of PostScript and it -includes facilities for integrating text and graphics. - -This document serves as an introductory user's manual. It does not require -knowledge of \MF\ or access to {\sl The \MF book}, but both are beneficial. -An appendix explains the differences between MetaPost and \MF. - -\end{abstract} -\thispagestyle{empty} -\newpage +%%% Title page layout documentation is missing. +\begin{titlepage} + \vbox to \textheight {% + \vskip0pt + \vfil + \vfil + \vfil + \centerline{\resizebox{3.5in}{!}{\fontseries{b}\selectfont\MP}} + \vskip10bp% actually 21bp (-11bp) + \centerline{\includegraphics{manfig-60.mps}} + \vskip15bp% actually 21bp (-6bp) + \centerline{% + \resizebox{3.5in}{!}{% + \scshape% + \fontsize{28bp}{28bp}\selectfont + \strut\lowercase{A USER\kern-2bp\lower3bp\hbox{'}S MANUAL}% + }% + } + \vskip-11bp + \vfil + \vfil + \centerline{\large John D. Hobby} + \vskip3bp + \centerline{and the MetaPost development team} + \vskip20.8bp% actually 31.8bp (-11bp) + \centerline{\large documented version: 1.003} + \vskip3bp + \centerline{\svnToday} + \vfil + \vfil + \vfil + } +\end{titlepage} + \setlength{\columnsep}{2.5em} \begin{multicols}{2} \tableofcontents @@ -166,7 +185,7 @@ fi $$ prints $$\begin{verbatim} -mp = 1.000 +mp = 1.003 \end{verbatim} $$ The {\tt scantokens} command is described on p.~\pageref{Dscantokens} @@ -177,7 +196,9 @@ the PostScript output. This document introduces the MetaPost language, beginning with the features that are easiest to use and most important for simple -applications. The first few sections describe the language as it +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 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 @@ -206,7 +227,7 @@ Please report bugs and request enhancements either on the \label{basic} The simplest drawing statements are the ones that generate straight lines. -Thus\index{draw?\texttt{draw}}\index{--?\texttt{--}} +Thus\index{draw?\texttt{draw}}\index{-{}-?\texttt{-{}-}} $$ \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)|} $$ @@ -314,6 +335,21 @@ 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}. + + \subsection{Previewing MetaPost graphics} \label{Dpreview} \index{previewing} @@ -394,12 +430,11 @@ 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 the PostScript -file, reserve as much space on a page as the graphic -occupies and write a reference to the corresponding file into the -\ttt{dvi} output. The graphic file is only included in the subsequent -run of an output driver, that can handle PostScript files, e.\,g., -\ttindex{dvips}. +\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 @@ -410,8 +445,9 @@ 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 -\ttt{mps}\index{files!mps?\texttt{mps}} is pdf\LaTeX's default -extension for purified EPS files, we can +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 @@ -462,7 +498,7 @@ 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 documentaion of packages +and \verb+\DeclareGraphicsRule+ in the documentation of packages \ttt{graphicx} and \ttt{graphics}. \paragraph{pdf\TeX} @@ -552,7 +588,7 @@ beginfig(2); endfig; \end{verbatim} $$ -it might be easier to recall the correct diagram names in the +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. @@ -783,7 +819,7 @@ between {\tt z1} and {\tt z2}: $$ \hbox{\verb|draw z0..z1..tension 1.3..z2..z3|} $$ This produces Figure~\ref{fig9}b. For an asymmetrical effect like Figure~\ref{fig9}c, the \verb|draw| statement becomes -$$ \hbox{\verb|draw z0..z1..tension 1.6 and 1..z2..z3|} $$ +$$ \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] @@ -958,7 +994,7 @@ via the following equations: Exactly the same points could be obtained by setting their values directly: $$ \begin{verbatim} z1=(.2in,0); z2=(-.2in,0); -z3=(.3in,.6in); z6=(-.3in,1.2in); +z3=(.3in,.8in); z6=(-.3in,1.4in); \end{verbatim} $$ @@ -1076,7 +1112,7 @@ $$ \hbox{\verb|! Inconsistent equation (off by 71.99979).|} $$ This error message illustrates roundoff\index{roundoff error} error in MetaPost's linear equation solving mechanism. Roundoff error -is normally not a serious problem. but it is likely to cause trouble if you are +is normally not a serious problem, but it is likely to cause trouble if you are trying to do something like find the intersection of two lines that are almost parallel. @@ -1120,8 +1156,8 @@ less than 4096 but intermediate results can be eight times larger. This should not be a problem for distances or coordinate values since 4096 PostScript points is more than 1.4~meters. If you need to work with numbers of magnitude 4096 or more, setting the internal variable -{\tt warningcheck}\index{warningcheck}\label{Dwarncheck} to zero -suppresses the warning messages about large numeric quantities. +{\tt warningcheck}\index{warningcheck?\texttt{warningcheck}}\label{Dwarncheck} +to zero suppresses the warning messages about large numeric quantities. The pair\index{pair type} type is represented as a pair of numeric quantities. We have seen that pairs are used to give coordinates in @@ -1164,12 +1200,16 @@ MetaPost solves linear equations involving colors the same way it does for pairs. The type `rgbcolor' is an alias of type `color'. -The cmykcolor\index{cmykcolor type} type is similar to the color -type except that it has four components instead of three. This type is used to -specify colors by their cyan, magenta, yellow, and black components explicitly. -Because cmykcolors deal with pigments instead of light rays, the color -black would be expressed as {\tt (1,1,1,1)} and white as {\tt (0,0,0,0)}. - +The cmykcolor\index{cmykcolor type} type is similar +to the color type except that it has four components instead of +three. This type is used to specify colors by their cyan, magenta, +yellow, and black components explicitly. Because CMYK colors deal with +pigments instead of light rays, the color white would be expressed as +{\tt (0,0,0,0)} and black as {\tt (0,0,0,1)}. In theory, the colors +{\tt ($c$,$m$,$y$,1)} and {\tt (1,1,1,$k$)} should result in black for +any values of $c$, $m$, $y$ and~$k$, too. But in practice, this is +avoided since it is a waste of colored ink and can lead to +unsatisfactory results. A string\index{string type} represents a sequence of characters. String constants\index{string constants} are given @@ -1179,7 +1219,7 @@ any sequence of eight-bit characters. \label{Dscantokens} Conversion from strings to other types, notably numeric, can be accomplished by -the \ttindex{scantokens} primitive: +the {\tt scantokens}\index{scantokens?\texttt{scantokens}} primitive: \begin{center}\texttt{n := scantokens(}\textit{str}\texttt{);}\end{center} More generally, \texttt{scantokens} parses a string into a token sequence, as if MetaPost had read it as input. @@ -1279,7 +1319,7 @@ $(a-b)^2$. Another \tdescr{primary binop} is the {\tt dotprod}\index{dotprod?\texttt{dotprod}}\label{Ddprod} operator that computes the vector dot product of two pairs. For example, {\tt z1 -dotprod z2} is equivalent to {\tt x1*y1 + x2*y2}. +dotprod z2} is equivalent to {\tt x1*x2 + y1*y2}. The additive operators {\tt +} and {\tt -}\label{Dadd} are \tdescr{secondary binops} that operate on numerics, pairs, or colors and @@ -1382,7 +1422,7 @@ the {\tt /}\index{fractions} operator binds most tightly when its operands are numbers. Thus {\tt 2/3} is a \tdescr{numeric atom}\index{numeric atom?\tdescr{numeric atom}}\index{parsing irregularities} while {\tt (1+1)/3} is only a \tdescr{numeric -secondary}. Applying a \tdescr{primary binop} such as {\tt +secondary}. Applying a \tdescr{unary op} such as {\tt sqrt}\index{sqrt?\texttt{sqrt}}\label{Dsqrt} makes the difference clear: $$ \hbox{\tt sqrt 2/3} $$ means $\sqrt{2\over3}$ while @@ -1390,7 +1430,7 @@ $$ \hbox{\tt sqrt(1+1)/3} $$ means $\sqrt 2/3$. Operators such as {\tt sqrt} can be written in standard functional notation, but it is often unnecessary to parenthesize the argument. This applies to any function that is parsed -as a \tdescr{primary binop}. For instance {\tt +as a \tdescr{unary op}. For instance {\tt abs(x)}\index{abs?\texttt{abs}}\label{Dabs} and {\tt abs x} both compute the absolute value of {\tt x}. The same holds for the {\tt round}\index{round?\texttt{round}}\label{Dround}, {\tt @@ -1456,20 +1496,25 @@ Similarly, a color {\tt c} is equivalent to\index{redpart?\texttt{redpart}}% \index{greenpart?\texttt{greenpart}}% \index{bluepart?\texttt{bluepart}}\label{Drgbprt} -$$ \hbox{\tt (redpart c, greenpart c, bluepart c)} $$. -For a cmykcolor {\tt c}, the parts are:\index{cyanpart?\texttt{cyanpart}}% +$$ \hbox{\tt (redpart c, greenpart c, bluepart c)}. $$ +For a cmykcolor {\tt c}, the components are% +\index{cyanpart?\texttt{cyanpart}}% \index{magentapart?\texttt{magentapart}}% \index{yellowpart?\texttt{yellowpart}}% \index{blackpart?\texttt{blackpart}}\label{Dcmykprt} $$ \hbox{\tt (cyanpart c, magentapart c, yellowpart c, blackpart c)} $$ -The part -specifiers for transforms will be discussed later. +and for a greyscale color {\tt c}, there is only one component% +\index{greypart?\texttt{greypart}}\label{Dgreyprt}% +$$ \hbox{\tt greypart c}. $$ +All color component operators are discussed in more detail in +section~\ref{piccomp}. Part specifiers for transforms are discussed +in section~\ref{transsec}. \section{Variables} \label{vars} -MetaPost allows compound variable names such as {x.a}, {\tt x2r}, {\tt y2r}, +MetaPost allows compound variable names such as {z.a}, {\tt x2r}, {\tt y2r}, and {\tt z2r}, where {\tt z2r} means {\tt (x2r,y2r)} and {\tt z.a} means {\tt (x.a,y.a)}. In fact there is a broad class of suffixes such that {\tt z}\tdescr{suffix}\index{suffix?\tdescr{suffix}} means @@ -1600,8 +1645,8 @@ restored to their previous values at the end of the current figure. Of course, they are restored to unknown pairs if the declaration is repeated. -Declarations work the same way for any of the other eight types: -numeric, path, transform, color, string, boolean, picture, and pen. The +Declarations work the same way for any of the other nine types: numeric, +path, transform, color, cmykcolor, string, boolean, picture, and pen. The only restriction is that you cannot give explicit numeric subscripts in a variable declaration. Do not give the illegal declaration $$ \hbox{\tt numeric q1, q2, q3;} $$ @@ -1893,7 +1938,7 @@ something like this: \label{Dtroffmode} On Unix\footnote{Unix is a registered trademark of Unix Systems -Laboratories.}\index{Unix\reg} and other Web2C-based systems, the +Laboratories.}\index{Unix} and other Web2C-based systems, the option {\tt -troff} to MetaPost tells the preprocessor that {\tt btex} $\ldots$ {\tt etex} and {\tt verbatimtex} $\ldots$ {\tt etex} blocks are in troff\index{troff} instead of \TeX. When using this option, @@ -2065,7 +2110,7 @@ llcorner}\index{llcorner?\texttt{llcorner}}\label{Dcornop}, {\tt lrcorner}\index{lrcorner?\texttt{lrcorner}}, {\tt urcorner}\index{urcorner?\texttt{urcorner}}, {\tt ulcorner}\index{ulcorner?\texttt{ulcorner}}, and {\tt -center}\index{center}\label{Dcenter} that take a \tdescr{picture +center}\index{center?\texttt{center}}\label{Dcenter} that take a \tdescr{picture primary} and return the corners of its ``bounding box'' as illustrated in Figure~\ref{bbox}. The {\tt center} operator also accepts \tdescr{path primary} and \tdescr{pen primary} operands. In MetaPost @@ -2078,8 +2123,11 @@ dotlabel} statements to center their text properly. The predefined macro\index{bbox?\texttt{bbox}}\label{Dbbox} $$ {\tt bbox}\, \descr{picture primary} $$ finds a rectangular path that represents the bounding box of a given picture. -If {\tt p} is a picture, {\tt bbox p} equivalent to -$$ \hbox{\tt (llcorner p--lrcorner p--urcorner p--ulcorner p--cycle)} $$ +If {\tt p} is a picture, {\tt bbox p} is equivalent to +$$\begin{verbatim} +(llcorner p--lrcorner p--urcorner p--ulcorner p--cycle) +\end{verbatim} +$$ except that it allows for a small amount of extra space around {\tt p} as specified by the internal variable\index{internal variables}\index{variables!internal} {\tt @@ -2107,7 +2155,8 @@ does the lying:\index{picture variable?\tdescr{picture variable}} $$ {\tt setbounds}\, \descr{picture variable}\, {\tt to}\, \descr{path expression} $$ makes the \tdescr{picture variable} behave as if its bounding box were -the same as the given path. To get the true bounding box of such a +the same as the given path. The path has to be a cycle, i.e., it must +be a closed path. To get the true bounding box of such a picture, assign a positive value to the internal variable\index{internal variables}\index{variables!internal} {\tt truecorners}\index{truecorners?\texttt{truecorners}}\label{Dtruecorn}:\footnote{The @@ -2130,7 +2179,7 @@ form, the {\tt fill} statement requires a \tdescr{path expression} that gives the boundary of the region to be filled. In the syntax $$ {\tt fill}\, \descr{path expression} $$ the argument should be a cyclic path, i.e., a path that describes a -closed curve via the {\tt ..cycle} or {\tt --cycle} notation. For +closed curve via the \verb|..cycle| or \verb|--cycle| notation. For 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 @@ -2152,7 +2201,7 @@ $$ \label{fig20} \end{figure} -The general {\tt fill} statement\index{withcolor?\texttt{withcolor}} +The general {\tt fill} statement\index{withcolor?\texttt{withcolor}}\label{Dwithcolor} $$ {\tt fill}\, \descr{path expression}\, {\tt withcolor}\, \descr{color expression} $$ @@ -2163,10 +2212,10 @@ values, mapping to four possible color models: $$ \begin{tabular}{|l|l|} Actual input & Remapped meaning\\ -{\tt withcolor} $\descr{rgbcolor} c$ & withrgbcolor\index{withrgbcolor?\texttt{withrgbcolor}} $c$\\ -{\tt withcolor} $\descr{cmykcolor} c$ & withcmykcolor\index{withrgbcolor?\texttt{withcmykcolor}} $c$\\ -{\tt withcolor} $\descr{numeric} c$ & withgreyscale\index{withrgbcolor?\texttt{withgreyscale}} $c$\\ -{\tt withcolor} $\descr{false}$ & withoutcolor\index{withrgbcolor?\texttt{withoutcolor}} \\ +{\tt withcolor} $\descr{rgbcolor} c$ & withrgbcolor\index{withrgbcolor?\texttt{withrgbcolor}}\label{Dwithrgbcolor} $c$\\ +{\tt withcolor} $\descr{cmykcolor} c$ & withcmykcolor\index{withcmykcolor?\texttt{withcmykcolor}}\label{Dwithcmykcolor} $c$\\ +{\tt withcolor} $\descr{numeric} c$ & withgreyscale\index{withgreyscale?\texttt{withgreyscale}}\label{Dwithgreyscale} $c$\\ +{\tt withcolor} $\descr{false}$ & withoutcolor\index{withoutcolor?\texttt{withoutcolor}}\label{Dwithoutcolor} \\ {\tt withcolor} $\descr{true}$ & $\descr{current default color model}$\\ \end{tabular} $$ @@ -2626,7 +2675,7 @@ identity}\index{identity?\texttt{identity}}\label{Dident} is a useful starting point for this process. This can be illustrated by paraphrasing the above equation for {\tt T} into English: ``{\tt T} should be the transform obtained by doing whatever {\tt identity} -does. Then scaling $x$~coordinates by $-1$, rotating $45^\circ$, and +does. Then scaling $x$~coordinates by $-1$, rotating $90^\circ$, and shifting by $(1,1)$.'' This works because {\tt identity} is the identity transformation which does nothing; i.e., {\tt transformed identity} is a no-op. @@ -2757,7 +2806,7 @@ $$ The MetaPost language provides many ways of changing the appearance of a line besides just changing its width. One way is to use dashed lines as was done in Figures \ref{fig4} and~\ref{fig22}. The syntax for this -is\index{dashed?\texttt{dashed}} +is\index{dashed?\texttt{dashed}}\label{Ddashed} $$ {\tt draw}\, \descr{path expression}\, {\tt dashed}\, \descr{dash pattern} $$ where a \tdescr{dash pattern}\index{dash pattern?\tdescr{dash pattern}} is really a special type of \tdescr{picture expression}. There is a @@ -2895,17 +2944,25 @@ paths created by polygonal pens. See Section~\ref{sec.pens}, p.\ If you want to attach a special bit of PostScript code, you can use $$ -{\tt withprescript} \descr{string expression} -$$\index{withprescript?\texttt{withprescript}}\label{Dwithpre}% +{\tt withprescript} \descr{string expression}% +\index{withprescript?\texttt{withprescript}}\label{Dwithpre} +$$ and $$ -{\tt withpostcript} \descr{string expression} -$$\index{withpostscript?\texttt{withpostscript}}\label{Dwithpost}% +{\tt withpostscript} \descr{string expression}% +\index{withpostscript?\texttt{withpostscript}}\label{Dwithpost} +$$ The strings will be written to the output file before and after the current object, each beginning on their own line. You can specify multiple {\tt withprescript} or {\tt withpostscript} options if you like. +When you specify more than one {\tt withprescript} or more than one {\tt + withpostscript} option, be wary of the fact that the scripts use a +form of nesting: the {\tt withprescript} items are written to the +PostScript file in last in, first out order; whereas the {\tt + withpostscript} items are written in first in, first out order. + \subsection{Other Options} \label{oopt} @@ -3203,7 +3260,7 @@ convex-polygon-shaped path and makes a pen that shape and size. If the path is not exactly convex or polygonal, the {\tt makepen} operator will straighten the edges and/or drop some of the vertices. In particular, {\tt pensquare} is equivalent to -$$ \hbox{\tt makepen((-.5,-.5)--(.5,-.5)--(.5,.5)--(-.5,.5)--cycle)} $$ +$$ \hbox{\verb|makepen((-.5,-.5)--(.5,-.5)--(.5,.5)--(-.5,.5)--cycle)|} $$ {\tt pensquare} and {\tt makepen} should not be used with dash patterns. See the end of Section~\ref{sec.pens}, p.\ @@ -3401,7 +3458,9 @@ Figure~\ref{fig55} shows three \ttt{car} objects drawn with two different slant values. -\subsection{Extracting Information from Pictures} +\subsection{Inspecting the Components of a Picture} +\label{piccomp} + MetaPost pictures are composed of stroked lines, filled outlines, pieces of typeset text, clipping paths\index{clip?\texttt{clip}}, and {\tt setbounds}\index{setbounds?\texttt{setbounds}} paths. (A {\tt setbounds} @@ -3442,22 +3501,62 @@ of a picture. If {\tt p} is a picture and {\tt stroked p} is true, path describing the line that got stroked, {\tt penpart p}\index{penpart?\texttt{penpart}}\label{Dpenpart} is the pen that was used, {\tt dashpart p}\index{dashpart?\texttt{dashpart}}\label{Ddashpart} -is the dash pattern, and the color is -$$ \hbox{\tt (redpart p, greenpart p, bluepart p)} $$% -\index{redpart?\texttt{redpart}}\index{greenpart?\texttt{greenpart}}\index{bluepart?\texttt{bluepart}} -If the line is not dashed, {\tt dashpart p} returns an empty picture. +is the dash pattern. If the line is not dashed, {\tt dashpart p} +returns an empty picture. The same part extraction operators work when {\tt filled p} is true, except -that {\tt dashpart p} is not meaningful in that case. For text components, -{\tt textual p} is true, +that {\tt dashpart p} is not meaningful in that case. + +For text components, {\tt textual p} is true, {\tt textpart p}\index{textpart?\texttt{textpart}}\label{Dtextpart} gives the text that got typeset, {\tt fontpart p}\index{fontpart?\texttt{fontpart}}\label{Dfontpart} gives the font that was used, and {\tt xpart~p}\index{xpart?\texttt{xpart}}\index{ypart?\texttt{ypart}}\index{xxpart?\texttt{xxpart}}% \index{xypart?\texttt{xypart}}\index{yxpart?\texttt{yxpart}}\index{yypart?\texttt{yypart}}, {\tt ypart~p}, {\tt xxpart~p}, {\tt xypart~p}, {\tt yxpart~p}, {\tt yypart~p} -tell how the text has been shifted, rotated, and scaled. The {\tt redpart}, -{\tt greenpart}, and {\tt bluepart} operators also work for text components. +tell how the text has been shifted, rotated, and scaled. + +Additionally, for \ttt{stroked}, \ttt{filled} and \ttt{textual} +components the color can be inspected. The color model of a picture +component can be requested by the +\ttt{colormodel}\index{colormodel?\texttt{colormodel}}\label{Dcolormodel} +operator (see section~\ref{adv.gr}). Depending on the color model of +a picture component \ttt{p} the color is +$$ \hbox{\tt (redpart p, greenpart p, bluepart p)} $$% +\index{redpart?\texttt{redpart}}\index{greenpart?\texttt{greenpart}}\index{bluepart?\texttt{bluepart}} +for RGB colors or +$$ \hbox{\tt (cyanpart p, magentapart p, yellowpart p, blackpart p)} $$% +\index{cyanpart?\texttt{cyanpart}}\index{magentapart?\texttt{magentapart}}\index{yellowpart?\texttt{yellowpart}}\index{blackpart?\texttt{blackpart}} +for CMYK colors or +$$ \hbox{\tt (greypart p)} $$% +\index{greypart?\texttt{greypart}} for grey scale colors. + +Applying a non-matching color part +operator to a picture component triggers an error and returns a color +part for the color \ttindex{black} in the requested color model. +That is, for the code +$$\begin{verbatim} +picture pic; +pic := image(fill unitsquare scaled 1cm withcolor (0.3, 0.6, 0.9);); +for item within pic: + show greypart item; + show cyanpart item; + show blackpart item; + show redpart item; +endfor +\end{verbatim} +$$ +the output is (omitting the error messages) +$$\begin{verbatim} +>> 0 +>> 0 +>> 1 +>> 0.3 +\end{verbatim} +$$ +since in grey scale color model black is {\tt 0} and in CMYK color model +black is {\tt (0, 0, 0, 1)}. For the matching RGB color model the true +color component is returned. When {\tt clipped p} or {\tt bounded p} is true, {\tt pathpart p} gives the clipping or {\tt setbounds} path and the other part extraction operators are @@ -3672,7 +3771,7 @@ $$ where the \tdescr{balanced tokens}\index{balanced tokens?\tdescr{balanced tokens}} can be anything that is balanced with respect to {\tt if} and {\tt fi}, the complete {\tt -middlepoint}\index{midpoint?\texttt{midpoint}} macro with type test +middlepoint}\index{middlepoint?\texttt{middlepoint}} macro with type test looks like this: $$\begin{verbatim} def middlepoint(expr a) = if path a: (point .5*length a of a) @@ -3690,9 +3789,9 @@ Note that {\tt if} tests are not statements and the \tdescr{balanced tokens} in the syntax rules can be any sequence of balanced tokens even if they do not form a complete expression or statement. Thus we could have saved two tokens at the expense of clarity by defining {\tt -midpoint} like this: +middlepoint} like this: $$\begin{verbatim} -def midpoint(expr a) = if path a: (point .5*length a of +def middlepoint(expr a) = if path a: (point .5*length a of else: .5(llcorner a + urcorner fi a) enddef; \end{verbatim} $$ @@ -4259,7 +4358,8 @@ $$ \hbox{\tt for i=a step b until c} $$ scans a sequence of {\tt i} values {\tt a}, ${\tt a}+{\tt b}$, ${\tt a}+2{\tt b}$, \ldots, stopping before {\tt i} passes {\tt c}; i.e., the loop scans {\tt i} values where ${\tt i}\le {\tt c}$ if ${\tt b}>0$ and -${\tt i}\ge {\tt c}$ if ${\tt i}<0$. +${\tt i}\ge {\tt c}$ if ${\tt b}<0$. For ${\tt b}=0$ the loop never +terminates, even if ${\tt a}={\tt c}$. It is best to use this feature only when the step size is an integer or some number that can be represented exactly in fixed point @@ -4286,9 +4386,9 @@ semicolon. It is common for the body of a loop to be one or more statements, but this need not be the case. A loop is like a macro definition followed by calls to the macro. The loop body can be virtually any sequence of tokens as long as they make sense together. Thus, the (ridiculous) statement -$$ \hbox{\tt draw for p=(3,1),(6,2),(7,5),(4,6),(1,3): p-- endfor cycle;} $$ +$$ \hbox{\verb|draw for p=(3,1),(6,2),(7,5),(4,6),(1,3): p-- endfor cycle;|} $$ is equivalent to -$$ \hbox{\tt draw (3,1)--(6,2)--(7,5)--(4,6)--(1,3)--cycle;} $$ +$$ \hbox{\verb|draw (3,1)--(6,2)--(7,5)--(4,6)--(1,3)--cycle;|} $$ (See Figure~\ref{fig17} for a more realistic example of this.) If a loop is like a macro definition, the loop index is like an expr @@ -4584,8 +4684,8 @@ $$ where \tdescr{box name} is a suffix and \tdescr{box contents} is either a picture expression, a string expression, or \tdescr{empty}. -The {\tt circleit} macro defines pair variable just as {\tt boxit} does, except -that there are no corner points \tdescr{box name}{\tt.ne}, +The {\tt circleit} macro defines pair variables just as {\tt boxit} +does, except that there are no corner points \tdescr{box name}{\tt.ne}, \tdescr{box name}{\tt.sw}, etc. A call to $$ \hbox{\tt circleit.a(}\ldots \hbox{\tt )} $$ gives relationships among points {\tt a.c}, {\tt a.s}, {\tt a.e}, {\tt @@ -4711,6 +4811,16 @@ result is a string consisting of a single null character. The preloaded {\tt readfrom} has returned {\tt EOF}, additional reads from the same file cause the file to be reread from the start. +All files opened by \ttt{readfrom} that have not completely been read +yet are closed\index{files!closing} automatically when the program +terminates, but there exists a command +$${\tt closefrom}\ \descr{file name}$$% +\index{closefrom?\texttt{closefrom}}\label{Dclosefrom}% +to close files opened by {\tt readfrom} explicitly. It is wise to +manually close files you do not need to read completely (i.e. until {\tt + EOF} is returned) because otherwise such files will continue to use +internal resources and perhaps cause a \ttt{capacity exceeded!} error. + The opposite of {\tt readfrom} is the command $$ {\tt write}\ \descr{string expression}\ {\tt to}\ \descr{file name} $$% \index{write to?\texttt{write to}}\label{Dwrite}% @@ -4770,7 +4880,8 @@ MetaPost text variable~$s$. values are remembered, and included before and after (respectively) each call to \texttt{TEX}. Otherwise, each \texttt{TEX} call is effectively typeset independently. \texttt{TEX} calls also do not interfere with -uses of \ttindex{verbatimtex} (p.\ \pageref{Dverbatimtex}). +uses of {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} (p.\ +\pageref{Dverbatimtex}). Here's the same example as above, using the \LaTeX\ commands \verb|\(| and \verb|\)|: @@ -4856,7 +4967,7 @@ Further information on error messages, debugging, and generating tracing information can be found in {\sl The\ \MF book} \cite{kn:c}. Suppose your input file says -$$ \hbox{\tt draw z1--z2;} $$ +$$ \hbox{\verb|draw z1--z2;|} $$ on line 17 without first giving known values to {\tt z1} and {\tt z2}. Figure~\ref{errmsg} shows what the MetaPost interpreter prints on your terminal when it finds the error. The actual error message is the line @@ -4898,7 +5009,7 @@ line number like ``{\tt l.17}'' for line 17 of the current file; or it can be a macro name followed by ``{\tt ->}''; or it is a descriptive phrase in angle brackets. Thus, the meaning of the context listing in Figure~\ref{errmsg} is that the interpreter has just read line 17 of the -input file up to ``{\tt --},'' the expansion of the {\tt --} macro has +input file up to ``\verb|--|,'' the expansion of the \verb|--| macro has just started, and the initial ``\verb|{|'' has been reinserted to allow for user input before scanning this token. @@ -5316,7 +5427,7 @@ $$\begin{tabular}{|l|l|r|l|} \tt true& boolean& \pageref{Dtrue}& The boolean value {\tt true}\\\hline \pl\tt unitsquare& path& --& - The path {\tt (0,0)--(1,0)--(1,1)--(0,1)--cycle}\\\hline + 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}& @@ -5346,8 +5457,12 @@ $$\begin{tabular}{|l|r|l|} 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}& @@ -5396,6 +5511,22 @@ $$\begin{tabular}{|l|r|l|} 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} @@ -5483,7 +5614,7 @@ $$\begin{tabular}{|l|l|l|r|l|} \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 + 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} @@ -5526,12 +5657,12 @@ $\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 --$\\ +$\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 \;|\; \char`\{curl \descr{numeric expression}\char`\}$\\ -$\tt \qquad \;|\; \char`\{\descr{pair expression}\char`\}$\\ -$\tt \qquad \;|\; \char`\{\descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\char`\}$\\ +$\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}$\\ @@ -5748,7 +5879,7 @@ $\tt \qquad \;|\; addto \descr{picture variable} contour \descr{path expression} $\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 \;|\; withrgcolor \descr{rgbcolor expression} \;|\; withcmykcolor \descr{cmykcolor 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}$\\ @@ -5994,6 +6125,7 @@ bounded\\ btex\\ clip\\ clipped\\ +closefrom\\ cmykcolor\\ color\\ colormodel\\ |