summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/metapost
diff options
context:
space:
mode:
authorTaco Hoekwater <taco@elvenkind.com>2014-05-22 08:19:22 +0000
committerTaco Hoekwater <taco@elvenkind.com>2014-05-22 08:19:22 +0000
commitb064bcd0694381f3a2549fcb61b1d42247a67bab (patch)
treeeaf5a5eca8c2b55f59fc7939c92a10e992218386 /Master/texmf-dist/doc/metapost
parentae5103e2766275ccabb173b075a4abcf648f13ed (diff)
updated metapost manual
git-svn-id: svn://tug.org/texlive/trunk@34193 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/metapost')
-rw-r--r--Master/texmf-dist/doc/metapost/base/mpboxes.pdfbin371656 -> 375664 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/mpgraph.pdfbin467564 -> 471872 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/mplibapi.pdfbin277200 -> 279814 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/mpman.pdfbin899838 -> 913134 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/Makefile2
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/TODO18
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex12
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex25
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib30
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex273
10 files changed, 284 insertions, 76 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
index d1d0fcccc7d..e09572764cc 100644
--- a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
index 8be16292908..a8595c392bf 100644
--- a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/mplibapi.pdf b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf
index caabad494c1..6c9c005a868 100644
--- a/Master/texmf-dist/doc/metapost/base/mplibapi.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/mpman.pdf b/Master/texmf-dist/doc/metapost/base/mpman.pdf
index cafe45a9eee..89d21a3bcc6 100644
--- a/Master/texmf-dist/doc/metapost/base/mpman.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpman.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/Makefile b/Master/texmf-dist/doc/metapost/base/source-manual/Makefile
index de95dc82304..9ababb3330f 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/Makefile
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/Makefile
@@ -36,7 +36,7 @@ mpgraph.pdf: mpgraph.tex mpgraph.bib mpgraph.mp
$(pdflatex) mpgraph
$(pdflatex) mpgraph
-mpman.pdf: mpman.tex mpman-app-legacy.tex mpman-app-optab.tex mpman-app-refman.tex mpman.bib mpman.ist mpman.mp charts.mp mpman-charts.mp
+mpman.pdf: mpman.tex mpman-app-legacy.tex mpman-app-optab.tex mpman-app-refman.tex mpman-app-numbersystems.tex mpman.bib mpman.ist mpman.mp charts.mp mpman-charts.mp
$(mpost) mpman
$(mpost) mpman-charts
$(pdflatex) mpman
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/TODO b/Master/texmf-dist/doc/metapost/base/source-manual/TODO
index 0c99309afbc..56385d582b6 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/TODO
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/TODO
@@ -31,18 +31,14 @@ mp-implementors list or alternatively the metapost list.
*** Wanted For Release ***
*****************************
-* Discussion of floating point vs. fixed point numbers:
-
- + needs complete review of the manual ...
-
- + description of new command-line option
-
-* Describe PNG backend.
-
* Describe prescriptpart/postscriptpart.
* Describe envelope primitive/macro.
+* Describe penrazor, penspeck.
+
+* Describe drawdot withpen counter-intuitivity. Describe recent change
+ in drawdot definition.
@@ -53,10 +49,14 @@ mp-implementors list or alternatively the metapost list.
Integrating Text and Graphics:
* Fix bad description of prologues in table ivartab.
* Move discussion of prologues to sec. workflow2.
+* Discuss difference between
+ label(btex ... etex, ...)
+ draw btex ... etex
Advanced Graphics:
* Describe turningnumber (mention differences in sec. 'MetaPost
Versus METAFONT').
+* Make fig56 black and white.
Notes on the MetaPost Workflow:
* Describe variables jobname, charcode.
@@ -67,6 +67,8 @@ Reference Manual:
Legacy Information:
* Cite original Hobby papers.
+Debugging:
+* turningnumber and tracingchoices > 2
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex
index 3af2449244a..597ce8a5b1c 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex
@@ -1,4 +1,4 @@
-\svnInfo $Id: mpman-app-legacy.tex 1339 2010-08-15 13:17:48Z stephanhennig $
+\svnInfo $Id: mpman-app-legacy.tex 2023 2014-05-21 08:47:19Z stephanhennig $
\section{Legacy Information}
\label{legacy}
@@ -160,7 +160,11 @@ minute\\
miterlimit\\
mpprocset\\
mpxbreak\\
+numberprecision\\
+numbersystem\\
+outputfilename\\
outputformat\\
+outputformatoptions\\
outputtemplate\\
pathpart\\
penpart\\
@@ -258,9 +262,9 @@ 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
+autorounding fillin smoothing turningcheck
+chardx granularity tracingedges xoffset
+chardy proofing tracingpens yoffset
\end{verbatim}
$$
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex
index 863d93df13e..7d301c3ce09 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex
@@ -1,4 +1,4 @@
-\svnInfo $Id: mpman-app-refman.tex 1381 2010-10-08 16:13:03Z stephanhennig $
+\svnInfo $Id: mpman-app-refman.tex 2022 2014-05-20 21:50:47Z stephanhennig $
\section{Reference Manual}
\label{refman}
@@ -96,6 +96,8 @@ $$\begin{tabular}{|l|r|l|}
Diameter of the dot drawn by \verb|dotlabel| (default 3{\tt bp})\\\hline
\tt hour& \pageref{Dhour}&
The hour of the day this job started\\\hline
+\tt hppp& \pageref{Dhppp}&
+ The number of horizontal points per pixel for bitmap output\\\hline
\pl\tt labeloffset& \pageref{Dlaboff}&
Offset distance for labels (default 3{\tt bp})\\\hline
\tt linecap& \pageref{Dlinecap}&
@@ -110,6 +112,8 @@ $$\begin{tabular}{|l|r|l|}
The current month (e.g, 3 $\equiv$ March)\\\hline
\tt mpprocset& \pageref{Dmpprocset}&
Create a PostScript dictionary of command abbreviations\\\hline
+\tt numberprecision&\pageref{Dnumberprecision}&
+ Arithmetic precision in \texttt{binary} and \texttt{decimal} mode\\\hline
\tt pausing& --&
${}>0$ to display lines on the terminal before they are read\\\hline
\tt prologues& \pageref{Dprologues}&
@@ -148,6 +152,8 @@ $$\begin{tabular}{|l|r|l|}
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 vppp& \pageref{Dvppp}&
+ The number of vertical points per pixel for bitmap output\\\hline
\tt warningcheck& \pageref{Dwarncheck}&
Controls error message when variable value is large\\\hline
\tt year& \pageref{Dyear}&
@@ -169,8 +175,14 @@ $$\begin{tabular}{|l|r|l|}
\hline
\tt jobname& --&
The name of this job\\\hline
+\tt numbersystem& \pageref{Dnumbersystem}&
+ Arithmetic mode as given on the command-line\\\hline
+\tt outputfilename& \pageref{Doutputfilename}&
+ Name of the output file last written\\\hline
\tt outputformat& \pageref{Doutputformat}&
Output backend to be used (default: ``eps'')\\\hline
+\tt outputformatoptions& \pageref{Doutputformatoptions}&
+ Configure PNG output backend (default: ``'')\\\hline
\tt outputtemplate& \pageref{Doutputtemplate}&
Output filename template (default: ``\%j.\%c'')\\\hline
\end{tabular}
@@ -572,14 +584,16 @@ $\tt \descr{subscript} \rightarrow \descr{number} \;|\; \hbox{\tt [}\descr{numer
$\tt $\\
$\tt \descr{internal variable} \rightarrow ahangle \;|\; ahlength \;|\; bboxmargin$\\
$\tt \qquad \;|\; charcode \;|\; day \;|\; defaultcolormodel \;|\; defaultpen \;|\; defaultscale$\\
-$\tt \qquad \;|\; hour \;|\; jobname \;|\; labeloffset \;|\; linecap \;|\; linejoin
+$\tt \qquad \;|\; hour \;|\; hppp \;|\; jobname \;|\; labeloffset \;|\; linecap \;|\; linejoin
\;|\; minute \;|\; miterlimit \;|\; month$\\
-$\tt \qquad \;|\; outputformat \;|\; outputtemplate \;|\; pausing \;|\; prologues \;|\; showstopping$\\
+$\tt \qquad \;|\; numberprecision \;|\; numbersystem$\\
+$\tt \qquad \;|\; outputfilename \;|\; outputformat \;|\; outputformatoptions \;|\; outputtemplate$\\
+$\tt \qquad \;|\; pausing \;|\; prologues \;|\; showstopping$\\
$\tt \qquad \;|\; time \;|\; tracingoutput \;|\; tracingcapsules \;|\; tracingchoices \;|\; tracingcommands$\\
$\tt \qquad \;|\; tracingequations \;|\; tracinglostchars \;|\; tracingmacros$\\
$\tt \qquad \;|\; tracingonline \;|\; tracingrestores \;|\; tracingspecs$\\
$\tt \qquad \;|\; tracingstats \;|\; tracingtitles \;|\; truecorners$\\
-$\tt \qquad \;|\; warningcheck \;|\; year$\\
+$\tt \qquad \;|\; warningcheck \;|\; vppp \;|\; year$\\
$\tt \qquad \;|\; \descr{symbolic token defined by {\tt newinternal}}$
\end{ctabbing}
\caption{Part 2 of the syntax for expressions}
@@ -923,6 +937,9 @@ Here's a summary of the command-line switches provided by mpost:
\cmdindex{-no-kpathsea}
& Do not use the kpathsea program to find files. All files have to be
in the current directory or specified via a full path.\\
+ \cmdindex{-numbersystem}=\tdescr{string}
+ & Set arithmetic mode to one of \texttt{scaled}, \texttt{double},
+ \texttt{binary}, \texttt{decimal}\\
\cmdindex{-progname}=\tdescr{string}
& Pretend to be the \tdescr{string} executable.\\
\cmdindex{-recorder}
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib
index e54ed5603e4..7f089f8ba71 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib
@@ -103,3 +103,33 @@
title = "The luamplib package",
note = "\texttt{CTAN://macros/luatex/generic/luamplib/luamplib.pdf}"
}
+@misc{lib:cairo,
+ key = "Cairo",
+ title = "Cairo graphics library",
+ note = "\texttt{http://cairographics.org/}"
+}
+% taken from http://www.mpfr.org/faq.html#cite
+@Article{lib:mpfr,
+ author = "Laurent Fousse and Guillaume Hanrot and Vincent Lef\`evre and Patrick
+ P\'elissier and Paul Zimmermann",
+ title = "{MPFR}: A Multiple-Precision Binary Floating-Point Library with Correct Rounding",
+ journal = "{ACM} Transactions on Mathematical Software",
+ volume = "33",
+ number = "2",
+ month = jun,
+ year = "2007",
+ pages = "13:1--13:15",
+ URL = "http://doi.acm.org/10.1145/1236463.1236468",
+ abstract = "This paper presents a multiple-precision binary floating-point library,
+ written in the ISO C language, and based on the GNU MP library. Its
+ particularity is to extend to arbitrary-precision ideas from the IEEE 754
+ standard, by providing \emph{correct rounding} and \emph{exceptions}.
+ We demonstrate how these strong semantics are achieved --- with no
+ significant slowdown with respect to other arbitrary-precision tools
+ --- and discuss a few applications where such a library can be useful.",
+}
+@misc{lib:decnumber,
+ key = "decnumber",
+ title = "dec{N}umber {ANSI} {C} implementation of General Decimal Arithmetic",
+ note = "\texttt{http://speleotrove.com/decimal/decnumber.html}"
+}
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 a38cb529578..7d5a4f6dda5 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 1920 2013-06-13 14:21:25Z stephanhennig $
+% $Id: mpman.tex 2023 2014-05-21 08:47:19Z stephanhennig $
% MetaPost manual, by John Hobby. License at end.
\listfiles
\RequirePackage{ifpdf}
@@ -12,7 +12,7 @@
\fi
\documentclass{article} % article is NOT the original style
\usepackage[nofancy]{svninfo}% Access VCS information.
-\svnInfo $Id: mpman.tex 1920 2013-06-13 14:21:25Z stephanhennig $
+\svnInfo $Id: mpman.tex 2023 2014-05-21 08:47:19Z stephanhennig $
\newcommand*{\mpversion}{1.503}
\usepackage[T1]{fontenc}
@@ -67,7 +67,7 @@
\hypersetup{
pdftitle={MetaPost: A User's Manual},
pdfauthor={John D. Hobby and the MetaPost development team},
- pdfkeywords={MetaPost, PostScript, SVG, vector graphics language,
+ pdfkeywords={MetaPost, PostScript, SVG, PNG, vector graphics language,
MetaFont, TeX}
}
\hypersetup{
@@ -91,16 +91,6 @@
\begin{titlepage}
\vbox to \textheight {%
\vskip0pt
- \raisebox{0pt}[0pt][0pt]{%
- \begin{minipage}{\linewidth}
- \emph{The manual currently doesn't cover all recent features of
- MetaPost, such as the PNG backend or support for calculations
- in different number systems. We'll try to keep up. For more
- information, please refer to the
- \href{https://foundry.supelec.fr/scm/viewvc.php/trunk/CHANGES?view=markup&revision=1919&root=metapost}{change
- log}. Sorry for the inconvenience!}
- \end{minipage}%
- }
\vfil
\vfil
\vfil
@@ -142,12 +132,12 @@
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
-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
-integrating text and graphics and accessing special features of
+either vector graphics in the Postscript or SVG formats or bitmap
+graphics in the PNG format. 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 integrating text and
+graphics and accessing special features of
PostScript\footnote{PostScript is a trademark of Adobe Systems
Inc.}\index{PostScript} such as clipping, shading, and dashed lines.
Another feature borrowed from \MF\ is the ability to solve linear
@@ -372,18 +362,19 @@ PS\_View\index{PSView?PS\_View}. Section~\ref{preview} has some tips
and discusses several more elaborate ways for previewing PostScript
output. Particularly, if graphics contain text labels, some more work
might be required to get robust results in a PostScript viewer.
-Starting with version~1.200, MetaPost is also capable of generating
-graphics in the SVG\index{SVG} format. SVG files can be previewed with
+MetaPost is also capable of generating graphics in the SVG\index{SVG}
+and PNG\index{PNG} formats. These file types can be previewed with
certain web browsers, for example Firefox~3\index{Firefox} or
-Konqueror~4.2\index{Konqueror}.
+Konqueror~4.2\index{Konqueror}, or general purpose image viewers.
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 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.
-Section~\ref{mpimport} deals with the import of MetaPost graphics into
-external applications.
+processing/interchanging. The PNG format is a losslessly compressing
+bitmap format. Both, SVG and PNG graphics, are widely used for web
+applications. Section~\ref{mpimport} deals with the import of MetaPost
+graphics into external applications.
A MetaPost input file\index{files!input}\index{edit}\index{edit}
normally contains a sequence of
@@ -394,9 +385,9 @@ one.\footnote{Omitting the final \verb|end| statement causes MetaPost to
enter interactive mode\index{interactive mode} after processing the
input file.} These are macros that perform various administrative
functions and ensure that the results of all drawing operations get
-packaged up and translated into PostScript or SVG format. The numeric
-argument to the \verb|beginfig| macro determines the name of the
-corresponding output file, whose name, by default, is of the form
+packaged up and translated into PostScript (or the SVG or PNG format).
+The numeric argument to the \verb|beginfig| macro determines the name of
+the corresponding output file, whose name, by default, is of the form
\texttt{\tdescr{jobname}.\tdescr{n}}, where \tdescr{n} is the current
argument to \verb|beginfig| rounded to the nearest integer. As an
example, if a file is named \texttt{fig.mp} and contains the lines
@@ -1019,6 +1010,7 @@ variables} variable\index{variables!internal} {\tt
tracingonline}\index{tracingonline?\texttt{tracingonline}}\label{Dtonline}.
\subsection{Data Types}
+\label{datatypes}
MetaPost actually has ten basic data types\index{types}: numeric, pair,
path, transform, (rgb)color, cmykcolor, string, boolean, picture, and
@@ -1029,12 +1021,14 @@ 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{epsilon}\index{epsilon?\texttt{epsilon}}\label{Depsilon}.\footnote{MetaPost
+ can also do arithmetic with higher and (almost) arbitrary precision.
+ See Appendix~\ref{hparith} for more information.} 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.
@@ -1962,6 +1956,9 @@ popular use-cases:
by setting variable \texttt{prologues} to~3 is currently the only
reliable way to export text objects to SVG.
+\item[\normalfont\itshape PNG output:] Variable \texttt{prologues} has
+ no effect in PNG output mode.
+
\end{description}
It is worth noting that the value of \ttt{prologues} has no effect on
@@ -4971,9 +4968,11 @@ $$
it will create the output file \texttt{fig-1.mps} instead of
\texttt{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{mpimport}). For SVG
-output one would want to use \texttt{svg}\index{svg file?{\tt svg}
- file}\index{files!svg?{\tt svg}} instead.
+MetaPost's PostScript output (see Section~\ref{mpimport}). For SVG and
+PNG output one would want to use file extensions \texttt{svg}\index{svg
+ file?{\tt svg} file}\index{files!svg?{\tt svg}} and
+\texttt{png}\index{png file?{\tt png} file}\index{files!png?{\tt png}}
+instead.
\begin{table}
\centering
@@ -5046,15 +5045,28 @@ 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.
+During \texttt{shipout}\index{shipout?\texttt{shipout}}, the name of the
+output file to be written is stored in an internal string variable
+\texttt{outputfilename}\index{outputfilename?\texttt{outputfilename}}\label{Doutputfilename}.
+It remains available until the next \texttt{shipout} command. The
+variable is initially empty.
+
\paragraph{Output Format}
-MetaPost can generate graphics in two output formats: Encapsulated
-PostScript\index{PostScript!structured} (EPSF\index{EPSF}) 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---hence the name MetaPost. The output
-format can be changed to SVG by assigning the value \verb|"svg"| to the
-internal string variable\index{internal
+MetaPost can generate graphics in three output formats:
+
+\begin{itemize}
+\item Encapsulated PostScript\index{PostScript!structured}
+ (EPSF\index{EPSF}),
+\item Scalable Vector Graphics (SVG\index{SVG}) following version~1.1 of
+ the SVG specification~\cite{w3c:svg1.1} (since MetaPost version
+ 1.200),
+\item Portable Network Graphics (PNG), a losslessly compressing bitmap
+ format (since MetaPost version 1.800).
+\end{itemize}
+By default, MetaPost outputs PostScript files---hence the name MetaPost.
+The output format can be changed by assigning values \verb|"svg"| or
+\verb|"png"| to the internal string variable\index{internal
variables}\index{variables!internal}
\verb|outputformat|\index{outputformat?\texttt{outputformat}}\label{Doutputformat}:
$$
@@ -5062,12 +5074,134 @@ $$
outputformat := "svg";
\end{verbatim}
$$
-
-Any other value makes MetaPost fall back to PostScript output. Variable
+Other values make 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{Bitmap output} To create bitmap output in the PNG format,
+MetaPost utilizes the Cairo\index{Cairo} \cite{lib:cairo} graphics
+library.\footnote{The Cairo library version is printed when MetaPost is
+ run with the \texttt{-version} command-line switch.} Bitmap
+conversion can be controlled from within MetaPost using three internal
+variables: \texttt{outputformatoptions}, \texttt{hppp}, and
+\texttt{vppp}.
+
+\begin{table}
+ \centering
+ \begin{tabular}{|>{\ttfamily}l|>{\ttfamily}l|l|}
+ \hline
+ \multicolumn1{|c|}{Key} & \multicolumn1{c|}{Values} & \multicolumn1{c|}{Meaning}\\\hline
+ format &
+ rgba\index{rgba?\texttt{rgba}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & RGB color space\index{PNG!color space!RGBA}
+ with alpha channel\index{PNG!alpha channel}\\
+ & rgb\index{rgb?\texttt{rgb}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & RGB color space\index{PNG!color space!RGB}\\
+ & graya\index{graya?\texttt{graya}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & gray scale color space\index{PNG!color
+ space!gray scale with alpha} with alpha channel\index{PNG!alpha
+ channel}\\
+ & gray\index{gray?\texttt{gray}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & gray scale color space\index{PNG!color
+ space!gray scale}\\
+ \hline
+ antialias &
+ none\index{none?\texttt{none}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & no anti aliasing\index{PNG!anti
+ aliasing}\\
+ & fast\index{fast?\texttt{fast}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & fastest anti aliasing algorithm\\
+ & good\index{good?\texttt{good}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & better quality, but slower\\
+ & best\index{best?\texttt{best}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & best quality, slowest\\
+ \hline
+ \end{tabular}
+ \caption{Valid keys and values in variable \texttt{outputformatoptions}.}
+ \label{tab:outputformatoptions}
+\end{table}
+
+Variable
+\texttt{outputformatoptions}\index{outputformatoptions?\texttt{outputformatoptions}}\label{Doutputformatoptions}
+is a string containing a list of \tdescr{key}\verb|=|\tdescr{value}
+pairs separated by spaces (no other spaces are allowed). Key
+\texttt{format}\index{format?\texttt{format}|see{outputformatoptions,
+ \texttt{format}}}\index{outputformatoptions?\texttt{outputformatoptions}!format?\texttt{format}}
+determines color space of the written PNG file. Key
+\texttt{antialias}\index{antialias?\texttt{antialias}|see{outputformatoptions,
+ \texttt{antialias}}}\index{outputformatoptions?\texttt{outputformatoptions}!antialias?\texttt{antialias}}
+determines what level of anti aliasing\index{anti aliasing|see{PNG, anti
+ aliasing}}\index{PNG!anti aliasing} is applied during vector graphic
+to bitmap conversion. The set of accepted values and their meanings can
+be found in table~\ref{tab:outputformatoptions}. An assignment that
+would match the compiled-in default setup would look like
+
+$$
+\begin{verbatim}
+outputformatoptions := "format=rgba antialias=fast";
+\end{verbatim}
+$$
+Keys not given in an assignment to \texttt{outputformatoptions} are
+reset to their default value. By default, this variable is empty.
+
+PNG files have a transparent background\index{background in PNG output}
+if output color space provides an alpha channel\index{alpha
+ channel|see{PNG, alpha channel}}\index{PNG!alpha channel}
+(\texttt{format}\index{outputformatoptions?\texttt{outputformatoptions}!format?\texttt{format}}
+is \texttt{rgba} or \texttt{graya}). Otherwise background becomes
+white. Color channels have a bit-depth of~8 in output. Colors not
+supported by the output format, e.g., CMYK colors, are transformed to a
+color with a similar visual impression. Here's how colors are
+transformed during bitmap conversion. Let's recall that color
+components in a MetaPost picture are in the range $[0;1]$ (see the
+discussion of color types in Section~\ref{datatypes}). Whatever input
+and output color spaces are used, all colors found in a picture are
+initially converted to RGB color space. A gray scale color with
+intensity $i$ is converted to an RGB color with all components set
+to~$i$. RGB colors are left unchanged. A CMYK color with components
+$(c,m,y,k)$ is converted to an RGB color with components $(r,g,b)$ using
+equations
+\begin{eqnarray}
+ r &=& 1 - k - c\\
+ g &=& 1 - k - m\\
+ b &=& 1 - k - y
+\end{eqnarray}
+with results clipped to the range $[0;1]$. If requested by the output
+format (\texttt{gray} or \texttt{graya}), such a color is further
+converted to a gray color with intensity
+\begin{eqnarray}
+j = 0.2126 \cdot r + 0.7152 \cdot g + 0.0722 \cdot b
+\end{eqnarray}
+
+Note, colors are exact in PNG output if input and output color spaces
+are compatible, i.e., both are RGB or gray scale or output in RGB color
+space contains only gray scale colors. Users that care about color
+conversion can apply the necessary transformations explicitly in a
+\texttt{for within~\tdescr{\mbox{picture}}}\index{for within?\texttt{for
+ within}} loop inside
+\texttt{extra\_endfig}\index{extra_endfig?\texttt{extra\_endfig}} (see
+Section~\ref{Dforwithin} and Appendix~\ref{Dxefig}). MetaPost has no
+built-in color management support. The built-in conversions are
+provided just as a convenience.
+
+Resolution of PNG output is always 72~dpi\index{dpi}\index{units!dpi}
+(dots per inch). Two internal variables
+\texttt{hppp}\index{hppp?\texttt{hppp}}\label{Dhppp} and
+\texttt{vppp}\index{vppp?\texttt{vppp}}\label{Dvppp} are used by the PNG
+backend to decide on the scale of the generated bitmap. These two
+variables have already been present in \MF\ and have been revived when
+MetaPost acquired the bitmap backend in version 1.800. But there's a
+catch: In \MF, variables \texttt{hppp} and \texttt{vppp} refer to
+horizontal and vertical scale in \emph{pixels per
+ point}\index{units!pixels per point} and values larger than~1 result
+in output of larger dimensions. In MetaPost, the meaning of both
+variables is the other way around. They refer to horizontal and
+vertical scale in \emph{points per pixel}\index{units!points per pixel}
+and values larger than~1 result in output of smaller dimensions.
+Default value for both variables is $1.0$, i.e., one MetaPost point per
+pixel.
+
\paragraph{PostScript Dictionary}
For PostScript output, MetaPost can define a dictionary of abbreviations
@@ -5076,8 +5210,8 @@ reduce the size of output files. Setting the internal variable
\texttt{mpprocset}\index{mpprocset?\texttt{mpprocset}}\label{Dmpprocset}
to~1 makes MetaPost create an extended preamble setting-up the
dictionary. Default value of variable \texttt{mpprocset} is~0, that is,
-no dictionary is used. For SVG output, variable \texttt{mpprocset} is
-not relevant.
+no dictionary is used. For SVG and PNG output, variable
+\texttt{mpprocset} is not relevant.
\paragraph{Version Number}
@@ -5114,14 +5248,19 @@ versions gracefully that don't even know about variable
work.
The version number is also written to output files and the transcript
-file. For PostScript output the version number can be found in the
+file. For PostScript output, the version number can be found in the
\texttt{Creator}\index{Creator comment in PostScript
output?\texttt{Creator} comment in PostScript output|see{PostScript,
\texttt{Creator} comment}}\index{PostScript!Creator
comment?\texttt{Creator} comment} comment. SVG files contain a simple
-comment line near the beginning of the file. The
-transcript\index{files!transcript} file starts with a banner line that
-identifies the version\index{version number} of the MetaPost compiler.
+comment line near the beginning of the file. For PNG output, the
+version number can be found in a text chunk with keyword
+\texttt{Software}\index{Software keyword in PNG text
+ chunk?\texttt{Software} keyword in PNG text chunk|see{PNG, text
+ chunk}}\index{text chunk|see{PNG, text chunk}}\index{PNG!text
+ chunk}. The transcript\index{files!transcript} file starts with a
+banner line that identifies the version\index{version number} of the
+MetaPost compiler.
\subsection{Previewing PostScript Output}
\label{preview}
@@ -5734,23 +5873,38 @@ image as given in the file's bounding box.
\subsubsection{Web Applications}
\label{webimport}
-\index{SVG!files}
An SVG\index{svg file?{\tt svg} file}\index{files!svg?{\tt svg}} file
-\texttt{fig.svg} can be easily embedded into HTML\index{HTML} documents
-with the following code snippet:
+\texttt{fig.svg} can be easily embedded into
+HTML\index{HTML}\index{files!HTML} documents with the following code
+snippet:
$$\begin{verbatim}
<p>
<object data="fig.svg" type="image/svg+xml" width="300" height="200">
</object>
</p>
\end{verbatim}
+\index{object tag?\texttt{object} tag|see{HTML, tags, \texttt{object}}}
+\index{HTML!tags!object?\texttt{object}}
+$$
+The code is similar for PNG\index{png file?{\tt png}
+ file}\index{files!png?{\tt png}} files:
+$$\begin{verbatim}
+<p>
+ <img src="fig.png" alt="A picture.">
+</p>
+\end{verbatim}
+\index{img tag?\texttt{img} tag|see{HTML, tags, \texttt{img}}}
+\index{HTML!tags!img?\texttt{img}}
$$
+The \texttt{width} and \texttt{height} attributes used above allow for
+scaling a graphic to an arbitrary size. More information about HTML
+tags and attributes can be found in an HTML reference.
-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.
+SVG and PNG 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*{Acknowledgement}
@@ -5762,6 +5916,7 @@ treatment of included \TeX\ material.
\appendix
+\include{mpman-app-numbersystems}
\include{mpman-app-refman}
\include{mpman-app-legacy}