summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/metapost/base/source/mpman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base/source/mpman.tex')
-rw-r--r--Master/texmf-dist/doc/metapost/base/source/mpman.tex362
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\\