diff options
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex')
-rw-r--r-- | Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex | 183 |
1 files changed, 113 insertions, 70 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex index 6889d586176..274c2982ead 100644 --- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex @@ -1,4 +1,4 @@ -% $Id: mpman.tex 1432 2010-10-22 12:02:13Z stephanhennig $ +% $Id: mpman.tex 1599 2011-04-05 14:15:45Z 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 1432 2010-10-22 12:02:13Z stephanhennig $ -\newcommand*{\mpversion}{1.503} +\svnInfo $Id: mpman.tex 1599 2011-04-05 14:15:45Z taco $ +\newcommand*{\mpversion}{1.504} \usepackage[T1]{fontenc} \usepackage{lmodern} @@ -190,7 +190,17 @@ Please report bugs and request enhancements either on the \section{Basic Drawing Statements} \label{basic} -The simplest drawing statements are the ones that generate straight lines. +The simplest drawing statement is the one that draws a single dot with +the current pen at a given coordinate: +$$ +\begin{verbatim} +drawdot (30,0) +\end{verbatim} +\index{drawdot?\texttt{drawdot}} +\label{Ddrawdot} +$$ + +MetaPost can also draw straight lines. Thus\index{draw?\texttt{draw}}\index{-{}-?\texttt{-{}-}} $$ \hbox{\verb|draw (20,20)--(0,0)|} $$ draws\index{draw?\texttt{draw}} a diagonal line and @@ -198,11 +208,6 @@ $$ \hbox{\verb|draw (20,20)--(0,0)--(0,30)--(30,0)--(0,0)|} $$ draws a polygonal line like this: $$ \includegraphics{mpman-1.mps} $$ -MetaPost also has a -\verb|drawdot|\index{drawdot?\texttt{drawdot}}\label{Ddrawdot} command -to draw a single point with the current pen, as in -\verb|drawdot (30,0)|. - What is meant by coordinates like \verb|(30,0)|? MetaPost uses the same default coordinate system that PostScript\index{PostScript!coordinate system} does. This @@ -213,20 +218,32 @@ to distinguish it from the standard printer's point\index{point!printer's} which is $1\over72.27$ inches. MetaPost uses the same names for units of measure that \TeX\ and \MF\ -do. Thus \verb|bp|\index{bp?\texttt{bp}}\label{Dbp} refers to -PostScript points (``big points'') and -\verb|pt|\index{pt?\texttt{pt}}\label{Dpt} refers to printer's points. -Other units of measure include -\verb|in|\index{in?\texttt{in}}\label{Din} for inches, -\verb|cm|\index{cm?\texttt{cm}}\label{Dcm} for centimeters, and -\verb|mm|\index{mm?\texttt{mm}}\label{Dmm} for millimeters. For -example, +do. Thus +\verb|bp|\index{bp?\texttt{bp}}\index{units!bp?\texttt{bp}}\label{Dbp} +refers to PostScript points (``big points'') and +\verb|pt|\index{pt?\texttt{pt}}\index{units!pt?\texttt{pt}}\label{Dpt} +refers to printer's points. Other units of measure include +\verb|in|\index{in?\texttt{in}}\index{units!in?\texttt{in}}\label{Din} +for inches, +\verb|pc|\index{pc?\texttt{pc}}\index{units!pc?\texttt{pc}}\label{Dpc} +for picas, +\verb|cm|\index{cm?\texttt{cm}}\index{units!cm?\texttt{cm}}\label{Dcm} +for centimeters, +\verb|mm|\index{mm?\texttt{mm}}\index{units!mm?\texttt{mm}}\label{Dmm} +for millimeters, +\verb|cc|\index{cc?\texttt{cc}}\index{units!cc?\texttt{cc}}\label{Dcc} +for ciceros, and +\verb|dd|\index{dd?\texttt{dd}}\index{units!dd?\texttt{dd}}\label{Ddd} +for Didot points. For example, $$ \hbox{\verb|(2cm,2cm)--(0,0)--(0,3cm)--(3cm,0)--(0,0)|} $$ generates a larger version of the above diagram. It is OK to say \verb|0| instead \verb|0cm| because {\tt cm} is really just a conversion factor and {\tt 0cm} just multiplies the conversion factor by zero. -(MetaPost understands constructions like {\tt -2cm}\index{multiplication, implicit} as shorthand for \verb|2*cm|). +(MetaPost understands constructions like {\tt 2cm}\index{multiplication, + implicit} as shorthand for \verb|2*cm|). The coordinate \verb|(0,0)| +can also be referred to as +\texttt{origin}\index{origin?\texttt{origin}}\label{Dorigin}, as in +$$ \hbox{\verb|drawdot origin|} $$ It is convenient to introduce your own scale factor, say $u$. Then you can define coordinates in terms of $u$ and decide later whether you want @@ -391,8 +408,8 @@ outside \verb|beginfig| \ldots\ \verb|endfig|, e.g., assignments to internal variables, such as \texttt{outputtemplate}, or a \LaTeX\ preamble declaration for enhanced text rendering. Comments\index{comments} in MetaPost code are introduced by the percent -sign~\verb|%|\index{\%?\texttt{\%}}, which causes the remainder of the -current line to be ignored. +sign~\verb|%|\index{\%?\texttt{\%}!comment}, which causes the remainder +of the current line to be ignored. The remainder of this section briefly introduces three assignments to internal variables, each one useful by itself, that can often be found @@ -473,6 +490,32 @@ $$ \label{fig3} \end{figure} +MetaPost already provides a small selection of basic path shapes that +can be used to derive custom paths from. The predefined variable +\texttt{fullcircle}\index{fullcircle?\texttt{fullcircle}}\label{Dfcirc} +refers to a closed path describing a circle of unit diameter centered on +the origin. There are also +\texttt{halfcircle}\index{halfcircle?\texttt{halfcircle}}\label{Dhcirc} +and +\texttt{quartercircle}\index{quartercircle?\texttt{quartercircle}}\label{Dqcirc}, +the former being the part of a full circle covering the first and second +quadrant and the latter covering just the first quadrant. Because of +the mathematical model that is used to describe paths in MetaPost, all +these are not exactly circular paths, but very good approximations (see +Figure~\ref{fig3a}). + +\begin{figure} +$$ \includegraphics{mpman-61.mps} $$ +\caption{A circle and a square with cardinal points. Arrows are + pointing to the start and end points of the closed paths.} +\label{fig3a} +\end{figure} + +Rectangularly shaped paths can be derived from +\texttt{unitsquare}\index{unitsquare?\texttt{unitsquare}}\label{Dunitsqr}, +a closed path describing a square of unit side length whose lower left +corner is located at the origin. + \subsection{B\'ezier Cubic Curves} When MetaPost is asked to draw a smooth curve through a sequence of @@ -967,19 +1010,22 @@ tracingonline}\index{tracingonline?\texttt{tracingonline}}\label{Dtonline}. \subsection{Data Types} -MetaPost actually has ten basic data types\index{types}: numeric, -pair, path, transform, (rgb)color, cmykcolor, string, boolean, picture, and +MetaPost actually has ten basic data types\index{types}: numeric, pair, +path, transform, (rgb)color, cmykcolor, string, boolean, picture, and pen. Let us consider these one at a time beginning with the numeric type. -Numeric\index{numeric type} quantities in MetaPost are represented in fixed -point arithmetic\index{arithmetic} as -integer multiples of $1\over65536$. They must normally have absolute values -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?\texttt{warningcheck}}\label{Dwarncheck} +Numeric\index{numeric type} quantities in MetaPost are represented in +fixed point arithmetic\index{arithmetic} as integer multiples of +$1\over65536$, the smallest positive value, which is also available as +the predefined constant +\texttt{epsilon}\index{epsilon?\texttt{epsilon}}\label{Depsilon}. +Numeric quantities must normally have absolute values 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 +\texttt{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 @@ -1397,11 +1443,11 @@ themselves, the only symbolic tokens involving them are {\tt [}, {\tt Some characters are not listed in Table~\ref{classes} because they need special treatment. The four characters {\tt ,;()} are ``loners'': each -comma, semicolon, or parenthesis is a separate token -even when they occur consecutively. Thus {\tt (())} is four tokens, not -one or two. The percent sign is very special because it introduces -comments\index{comments}. The percent sign and everything after it up -to the end of the line are ignored. +comma, semicolon, or parenthesis is a separate token even when they +occur consecutively. Thus {\tt (())} is four tokens, not one or two. +The percent sign is very special because it introduces +comments\index{\%?\texttt{\%}!comment}\index{comments}. The percent +sign and everything after it up to the end of the line are ignored. Another special character is the period. Two or more periods together form a symbolic token, but a single period is ignored, and a period @@ -2188,15 +2234,9 @@ Value & Color model\\\hline Figure~\ref{fig21} illustrates several applications of the fill command to fill areas with shades of gray. The paths involved are intersecting circles {\tt a} and {\tt b} and a path {\tt ab} that bounds the region -inside both circles. Circles {\tt a} and {\tt b} are derived from a -predefined path {\tt -fullcircle}\index{fullcircle?\texttt{fullcircle}}\label{Dfcirc} that -approximates a circle of unit diameter centered on the origin. There is -also a predefined path {\tt -halfcircle}\index{halfcircle?\texttt{halfcircle}}\label{Dhcirc} that is -the part of {\tt fullcircle} above the $x$ axis. Path~{\tt ab} is then -initialized using a predefined macro {\tt buildcycle} that will be -discussed shortly. +inside both circles. Circles {\tt a} and {\tt b} are derived from {\tt + fullcircle}. Path~{\tt ab} is then initialized using a predefined +macro {\tt buildcycle} that will be discussed shortly. \begin{figure}[htp] $$ \begin{verbatim} @@ -4807,7 +4847,7 @@ Explanation: \begin{itemize} \item -The \texttt{\%\&latex}\index{\%\&?\texttt{\%\&}} causes \LaTeX\ to be invoked instead of \TeX. +The \texttt{\%\&latex}\index{\%?\texttt{\%}!magic comment!\%\&?\texttt{\%\&}} causes \LaTeX\ to be invoked instead of \TeX. (See below, also.) Web2C- and MiKTeX-based \TeX\ implementations, at least, understand this \texttt{\%\&} specification; see, e.g., the Web2C documentation for details, \url{http://tug.org/web2c}. (Information on @@ -4926,20 +4966,20 @@ output one would want to use \texttt{svg}\index{svg file?{\tt svg} file}\index{files!svg?{\tt svg}} instead. \begin{table} - \newcommand*{\otesc}[3]{\%#1\index{\%#1?\texttt{\%#1}} & #2 & \%\{#3\}} \centering \begin{tabular}{|>{\ttfamily}l|l|>{\ttfamily}l|} \hline \multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Meaning} & \multicolumn1{c|}{Alternative}\\\hline - \%\%\index{\%\%?\texttt{\%\%}} & percent sign &\\ - \%\{\tdescr{internal variable}\}\index{\%\{...\}?\texttt{\%\{\tdescr{internal variable}\}}} & evaluate internal variable &\\ - \%j\index{\%j?\texttt{\%j}} & current jobname & \%\{jobname\} \\ - \otesc{c}{charcode value (\texttt{beginfig} argument)}{charcode}\\ - \otesc{y}{current year}{year}\\ - \otesc{m}{month (numeric)}{month}\\ - \otesc{d}{day of the month}{day}\\ - \otesc{H}{hour}{hour}\\ - \otesc{M}{minute}{minute}\\ + \%\%\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%\%?\texttt{\%\%}} & percent sign &\\ + \%\{\tdescr{internal variable}\}\index{\%?\texttt{\%}!outputtemplate + escape sequence?\texttt{outputtemplate} escape sequence!\%\{...\}?\texttt{\%\{\tdescr{internal variable}\}}} & evaluate internal variable &\\ + \%j\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%j?\texttt{\%j}} & current jobname & \%\{jobname\}\\ + \%c\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%c?\texttt{\%c}} & charcode value (\texttt{beginfig} argument) & \%\{charcode\}\\ + \%y\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%y?\texttt{\%y}} & current year & \%\{year\}\\ + \%m\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%m?\texttt{\%m}} & month (numeric) & \%\{month\}\\ + \%d\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%d?\texttt{\%d}} & day of the month & \%\{day\}\\ + \%H\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%H?\texttt{\%H}} & hour & \%\{hour\}\\ + \%M\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%M?\texttt{\%M}} & minute & \%\{minute\}\\ \hline \end{tabular} \caption{Allowed escape sequences for \ttt{outputtemplate}} @@ -4948,23 +4988,26 @@ output one would want to use \texttt{svg}\index{svg file?{\tt svg} In single-letter escape sequences referring to internal numerics, the corresponding value is rounded to the nearest integer before it is -converted to a string expression. In such escape sequences, there can -be an optional number (0--99) following \verb|%| that determines the -minimum number of digits in the resulting string expression, like -\verb|%2m|. If the decimal representation of the internal variable -requires more digits, actual string length exceeds the requested length. -If less digits are required, the string is padded to the requested -length with zeros from left. - -In the \verb|%{...}| escape sequence no rounding takes place. -Additionally, neither this nor single-letter escape sequences referring -to internal string variables can be zero-padded. - -For backwards compatibility, the \verb|%c|\index{\%c?\texttt{\%c}} +converted to a string expression. In such escape sequences, a number +from the range 0 to~99 can optionally be placed directly after \verb|%| +that determines the minimum number of digits in the resulting string +expression, like \verb|%2m|. If the decimal representation of the +internal variable requires more digits, actual string length will exceed +the requested length. If less digits are required, the string is padded +to the requested length with zeros from left. + +In single-letter escape sequences referring to internal string +variables, like \verb|%j|, and in the \verb|%{...}| escape sequence, +neither rounding nor zero-padding take place. + +For backwards compatibility, the +\verb|%c|\index{\%?\texttt{\%}!outputtemplate escape + sequence?\texttt{outputtemplate} escape sequence!\%c?\texttt{\%c}} escape sequence is handled special. If the result of rounding the charcode value is negative, \verb|%c| evaluates to the string \verb|ps|. This transformation can be bypassed by using \verb|%{charcode}| instead -of \verb|%c| (bypassing the rounding, too). +of \verb|%c|. But note, that this bypasses rounding and zero-padding as +well. The template mechanism can also be used for naming graphic files individually, yet keeping all sources in one file. Collecting, e.g., |