From b064bcd0694381f3a2549fcb61b1d42247a67bab Mon Sep 17 00:00:00 2001 From: Taco Hoekwater Date: Thu, 22 May 2014 08:19:22 +0000 Subject: updated metapost manual git-svn-id: svn://tug.org/texlive/trunk@34193 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/metapost/base/mpboxes.pdf | Bin 371656 -> 375664 bytes Master/texmf-dist/doc/metapost/base/mpgraph.pdf | Bin 467564 -> 471872 bytes Master/texmf-dist/doc/metapost/base/mplibapi.pdf | Bin 277200 -> 279814 bytes Master/texmf-dist/doc/metapost/base/mpman.pdf | Bin 899838 -> 913134 bytes .../doc/metapost/base/source-manual/Makefile | 2 +- .../doc/metapost/base/source-manual/TODO | 18 +- .../base/source-manual/mpman-app-legacy.tex | 12 +- .../base/source-manual/mpman-app-refman.tex | 25 +- .../doc/metapost/base/source-manual/mpman.bib | 30 +++ .../doc/metapost/base/source-manual/mpman.tex | 273 ++++++++++++++++----- 10 files changed, 284 insertions(+), 76 deletions(-) (limited to 'Master') diff --git a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf index d1d0fcccc7d..e09572764cc 100644 Binary files a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf and b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf 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 Binary files a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf and b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf 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 Binary files a/Master/texmf-dist/doc/metapost/base/mplibapi.pdf and b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf 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 Binary files a/Master/texmf-dist/doc/metapost/base/mpman.pdf and b/Master/texmf-dist/doc/metapost/base/mpman.pdf 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}

\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} +

+ A picture. +

+\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} -- cgit v1.2.3